t1k:playablelabs:base:change-proof
| Field | Value |
|---|---|
| Module | base |
| Version | 2.29.2 |
| Effort | high |
| Tools | — |
Keywords: cocos zero behaviour change, engine-matrix, jenkins-pair, packer back-compat proof, verify-both-engines
How to invoke
Section titled “How to invoke”/t1k:playablelabs:base:change-proof--pr <n> --base-sha <40-hex> [--repo The1Studio/PlaybleEngine]PlayableLabs Change Proof (zero Cocos change)
Section titled “PlayableLabs Change Proof (zero Cocos change)”Scope: how an agent PROVES a PlaybleEngine (packer) change on BOTH engines. Authoring Cocos game
code is theonekit-cocos (t1k-cocos-playable-*); Jenkins job config is core t1k-jenkins-job.
This skill never restates packer internals: it points at them. Recorded evidence recipes live in
references/evidence.md.
The HARD constraint
Section titled “The HARD constraint”Existing Cocos customers see ZERO behaviour change. Only the web engine host may change, and
every change is proven on BOTH engines before it merges. A green unit suite does not prove it: the
real-build proofs below do.
Rules (PlaybleEngine .claude/skills/playable-engine/SKILL.md “Working Rules” + .claude/skills/playable-engine/references/cocos-build.md in the packer)
Section titled “Rules (PlaybleEngine .claude/skills/playable-engine/SKILL.md “Working Rules” + .claude/skills/playable-engine/references/cocos-build.md in the packer)”masterhas NO branch protection and Jenkins packs from it: a merge is a production deploy.- Never force-push or rebase PlaybleEngine, PlayableLabs or ParamTool. Sync with
git merge origin/master; commit by pathspec; nevergit stash; never--amendafter a push. - Engine seam:
cc/window.cc/legacyCC/ Cocos chunk names / Cocos build paths may appear only in the seam files thattests/engine-seam-gate.test.jsallows:src/engine/cocos38/**,src/runtime/engine-host-cocos38.ts,scripts/lib/engine-probes-cocos38.cjs(+ one named tool,scripts/reconstruct-build.cjs).src/runtime/engine-host.tsis NOT allowed. Never widen the allow-list to silence a hit: move the code behind the seam. - Engine fork patch is last resort: (1) per-project module switch / Creator build config, (2)
packer code in
src/runtime/orsrc/adapters/, (3) a minimal patch on thestudio/3.8.7fork recorded inPATCHES.md. If you think you need (3), stop and report. - Parameter publish: only
webever sendsengineType(Jenkinsfile/PlayablePackerpublishParameters);cocos-3.8/nonemust never overwrite the dashboard value. - Back-compat proofs compare against a LITERAL base SHA (
git show <sha>:<path>), neverorigin/master: a RED proof read fromorigin/masterflips green the moment the PR merges.
The two proofs
Section titled “The two proofs”| Proof | What it shows | Where it runs |
|---|---|---|
engine-matrix | for each of 9 fixtures: pack with the PR’s dist/cli.js, smoke every network, pack-hashes.json byte-identical to ci/engine-matrix/baselines/<name>.pack-hashes.json | CI job engine-matrix-shard (<fixture>) + aggregate engine-matrix (.github/workflows/ci.yml) |
jenkins-pair | real PlayablePacker-Canary Jenkins builds: Cocos on master, Cocos on the PR branch (must hash-equal), web green | job pair (.github/workflows/jenkins-pair.yml), ONLY when the PR touches Jenkinsfile/**, ci/jenkins-pair/**, scripts/jenkins-canary-pair.cjs or that workflow |
Fixtures (ci/engine-matrix/fixtures.json, 9): Cocos (engineHost: cocos-3.8) goodsortpla,
arrow3dpla, helpmepla1, lifechoicepla, solitairejigsortpla; non-Cocos arrow3d-three
(none), slingnshot (none), arrow3d-three-web (web), slingnshot-web (web).
An intentional output change runs bun scripts/engine-matrix.cjs --update-baselines in the SAME
PR so the diff shows what moved; a moved Cocos baseline is a Cocos behaviour change: state why in the PR or drop the change.
# 1. read the proof for a PR (thin wrapper, no hashing; needs gh auth)bun scripts/verify-both-engines.cjs --pr <n> --base-sha <40-hex> [--require-jenkins-pair] [--json]# 2. run one fixture locally (downloads the fixture; scratch dir, never the shared clone)bun scripts/engine-matrix.cjs --only lifechoicepla --work-dir <scratch> # in a PlaybleEngine worktree after bun install --frozen-lockfile && bun run build; needs cwebp 1.5.0 (see references/evidence.md)Exit: 0 every check proven; 1 any check failed OR evidence missing (unknown is never a pass:
an unfinished check counts as missing); 2 usage/auth error (--base-sha not 40-hex, gh failed).
JSON: {ok, headSha, baseSha, checks:[{name,status,evidence}], missing:[...]}; status is
pass|fail|missing|not-applicable. On 1, fix the named check; never re-run hoping it flips. On 2
with base-sha, pin git rev-parse <merge-base>; do not pass a branch name.
Local runs: workers <= 4, check free -g first, one suite at a time.
Trust: a check run counts only if produced by the github-actions app (check_runs[].app.slug) on
the PR head SHA; any other producer reads as missing. This is an ACCIDENT guard, not tamper-proof:
a PR author who edits ci.yml can still emit the real job names. The real gate is PlaybleEngine
required checks on master (none today; recommendation only, this kit never writes there). See
references/evidence.md “Threat model”.
Verified against
Section titled “Verified against”PlaybleEngine@4ee4272 (2026-10-04): ci/engine-matrix/fixtures.json, scripts/engine-matrix.cjs
(header), .github/workflows/{ci,jenkins-pair}.yml, ci/jenkins-pair/{cocos,web}.json,
scripts/jenkins-canary-pair.cjs (header), tests/engine-seam-gate.test.js,
Jenkinsfile/PlayablePacker (engineTypeForHost, publishParameters),
.claude/skills/playable-engine/SKILL.md, .claude/skills/playable-engine/references/cocos-build.md. Check-run names and the
compare status values were read back from live PRs #158/#160 via gh api.
Hard rules
Section titled “Hard rules”- The workflow
jenkins-pair.ymlis path-filtered on purpose (not a required check): for a PR that touches none of those paths the wrapper reportsnot-applicable, not a pass of the pair. pairis ONE check run covering Cocos-unchanged and web, sojenkins-pair:cocosand:webshare the same evidence.- Branch-canary (
PlayablePacker-Canary) refuses publish params (validateParamsinscripts/jenkins-canary-pair.cjs): it never publishes. Unrelated:PARAM_CANARYinJenkinsfile/PlayablePackeris the runtime-canary audit toggle. - The shard matrix in
ci.ymlis a static list;tests/ci-workflow-matrix.test.jspins it to the manifest. The wrapper reads fixtures from the manifest at the head SHA and fails ifci.ymlstops declaringengine-matrix-shard/engine-matrix. - Verified-SHA drift:
git -C <packer clone> diff 4ee4272..HEAD -- ci/engine-matrix/fixtures.json .github/workflows Jenkinsfile/PlayablePacker.
Executed by
Section titled “Executed by”Reading the proof (verify-both-engines.cjs, gh api check runs) is mechanical; deciding whether a
moved baseline is an intentional web change or a Cocos regression is not. Routing SSOT:
rules/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run verify-both-engines.cjs, tabulate check status and evidence | t1k-data-verifier |
Read engine-matrix / jenkins-pair results and report pass/fail per fixture | t1k-tester |
| Judge a moved baseline, an allow-list change or a fork patch | t1k-playablelabs-base-packer-engineer (sonnet, native) |