t1k:cocos:playable:pla-retrofit
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: cocos-stdlib retrofit, đưa code lên stdlib, lordmobile retrofit, pla retrofit, retrofit pipeline, stdlib retrofit
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:pla-retrofit[<project-root>] [--stage b0..b9] [--integration-branch <name>]t1k-cocos-playable-pla-retrofit
Section titled “t1k-cocos-playable-pla-retrofit”Main goal: take a shipped playable project and make its reusable code live in the studio library
(The1Studio/cocos-stdlib, @playablelabs/* packages) — measured, gated, and provably done.
This skill orchestrates; it implements nothing. Every stage below is an existing skill or an existing script. What this file owns is the order, the gate between stages, and the six decisions that are the same on every project — the ones a fresh session gets wrong because they are not written down anywhere else.
Documentation-only orchestration — there is no runtime skill-spawning here. Each stage runs standalone; this file tells you which one, in what order, and what must be true before the next.
When to invoke
Section titled “When to invoke”- Running the whole retrofit on one project end to end (
<project-root>). - Resuming at a stage (
--stage b4) after a stop. - Answering “is this retrofit done?” → walk § “Definition of Done” and then run stage B9.
Not for: a greenfield playable (→ t1k-cocos-playable-gen), a one-off refactor
(→ t1k-cocos-playable-modularize), or a single component split
(→ t1k-cocos-playable-primitive-decompose).
The six decisions this file fixes (read before stage B0)
Section titled “The six decisions this file fixes (read before stage B0)”These are not preferences. Each one has a failure attached.
- Pure-TS packages only.
core-/feature-/mechanic-— nocc-*package. Thecclayer shrinks by refactor/relocate, never by packaging it. Moving acc.Componentinto a package changes its script UUID and re-wires nothing; acc-*package also cannot be reused by a non-Cocos consumer, which defeats the library’s purpose. - Goldens gate every logic move. No logic is moved before the characterization golden covering it is written and committed. A move without a golden is unverifiable — you cannot tell a faithful relocation from a silent behaviour change, and the suite that would have caught it is the one you did not write.
- Measurement writes nothing into the repo. Every
--jsonreport goes to a scratch path outside the project. A measurement that mutates the tree it is measuring has invalidated itself, and the diff noise buries the real change. - ONE integration branch. All lanes merge into
refactor/stdlib-packages(or the name given by--integration-branch), cut from the project’s real base branch. At the end it merges back and is deleted — the repo is left with its normal branch count, not a branch per stage. - Lane worktrees live under the scratchpad and are reaped immediately. One worktree per parallel
lane, created under scratch (never inside the project), removed and its lane branch deleted the
moment that lane merges. A retrofit leaves zero worktrees behind.
git worktree listis part of the final report — the count is an output, not an implementation detail. - Package granularity is by functional group, not by file. A ~330-line mechanic becomes one
package; a ~50-line helper does not become its own package — it goes into an existing one
(
core-utilsfor math/hysteresis/vector helpers). Micro-packages trade a real reuse win for publishing overhead and version churn.
Stage table — the gates are the contract
Section titled “Stage table — the gates are the contract”| Stage | Work | Executor | Gate OUT (do not advance until this holds) |
|---|---|---|---|
| B0 | Test harness: vitest at environment: 'node', a narrow db:// alias (@playablelabs/core-*|mechanic-*|feature-* only), colocated tests dot-prefixed (.tests/) | t1k-cocos-playable-characterization (harness mode) + t1k-game-arch | the test script RUNS (a vacuous pass is not a pass — at least one real import resolves through the alias) |
| B1 | Characterization goldens for every reachable piece of logic, seeded inputs | t1k-cocos-playable-characterization | goldens committed; replay green against the unmodified tree |
| B2 | Dead code: delete what the sweep proves unreachable | verify-reachability.cjs --all (A1) | every deletion is ORPHAN; every UNKNOWN kept, with its keep-reason recorded |
| B3 | Hardcode → named constants / config | hardcode-scan.cjs (A4) | 0 findings in files this work touched. Pre-existing findings elsewhere are a backlog line, not a gate |
| B4 | Relocate logic out of cc.Component into pure-TS modules — each module’s unit test written immediately before that module moves | t1k-cocos-playable-primitive-decompose, t1k-cocos-base-clean-architecture | --cc-thickness gluePct down AND goldens replay green AND a typecheck:game pass over assets/scripts/** (see below). All three, not any two |
| B5 | Contribute to cocos-stdlib — scope gate, corpus sweep, decouple, scaffold, PR | t1k-cocos-base-stdlib-contribute / t1k-cocos-playable-stdlib-autocontribute | PR merged, CI green, gatekeeper APPROVE. Merging publishes |
| B6 | Adopt: vendor → repoint db:// imports → retire the originals, one commit per unit | t1k-cocos-playable-stdlib-adopt | reachability re-run before each deletion; each commit prints its git revert <sha> |
| B7 | Re-measure: coverage + adoption + cc-thickness | reuse-coverage.cjs (A2) + adoption.cjs | all three numbers reported, --index explicit, reports outside the repo |
| B8 | Four-layer gate: vitest → equivalence → headless preview-verify → human playtest | preview-verify + a human | console clean, CTA fired, diffPercent reported, and the human’s confirmation on the record. STOP here — do not self-certify this layer |
| B9 | Whole-repo review | t1k-tester (runs G1-G8) → t1k-cocos-playable-pla-retrofit-reviewer (A5, reads the gate JSON, judges) | verdict PASS — zero gates errored/not-run, zero blocking findings |
Full per-stage detail, the commands, and the lane-management recipe: references/stage-gates.md.
Cross-cutting gates
Section titled “Cross-cutting gates”Portability (A3) — enforced by another repo, referenced by name.
bun <cocos-stdlib>/scripts/portability-check.mjs --strict runs against every core-/feature-/
mechanic- package before its PR. The script lives in cocos-stdlib, which owns the rule — locate
it, never vendor it into this kit. It forbids decorators, Proxy/Reflect, eval/new Function,
dynamic import(), prototype mutation, explicit any, arguments, loose ==, unqualified
DOM/Node/window, undeclared-side-effect getters, and magic Symbol beyond iteration. cc-* is
exempt — and since decision 1 rules those out, every package this pipeline produces is subject to it.
The core hook (A7) — the net has a hole, and CI is under it.
cocos-stdlib-portability-guard.cjs is a theonekit-core PreToolUse hook (this kit ships zero hooks
by design — gate #22). It runs the same A3 check on the content about to be written, inside a
cocos-stdlib checkout, and blocks a violation. It fires on Edit/Write only — a sed, a
heredoc, or any Bash-based write goes straight past it. That hole is precisely why stage B5’s CI check
is not optional and why B9 re-runs A3 by hand: the hook and CI are two layers of one gate, and neither
covers what the other misses.
Measurement discipline — applies to every --json in the table.
Write reports to a scratch dir; pass --index <clone-index-dir> explicitly on every coverage and
adoption run. Omitting it lets the resolver’s <cwd> candidate win, and two runs of the same command
from different shell directories read two different clone-index dirs while both report
templateBaseline: available. A bare “available” proves an index was read, not which one.
Lane discipline.
Parallel lanes each get a worktree under scratch, cut from the integration branch; they merge back
with --no-ff, and the worktree plus its branch are removed immediately on merge — not at the
end. A lane left standing holds a branch, a checkout, and a merge conflict waiting to happen. The
final report states the worktree count, and the number after the last merge is zero.
Definition of Done
Section titled “Definition of Done”references/stage-gates.md § “Definition of Done” is the SSOT — eight goals, each with the gate
that proves it, and the prohibition against reporting done on a green suite alone. Walk it before
reporting anything. A green vitest run is evidence for one clause of one row, and a report
that leads with it and omits the rest is the exact failure that section’s prohibition exists to stop.
Reading the result
Section titled “Reading the result”- Coverage moving DOWN mid-relocation is expected, not regression. Moving pure logic out of a
component without a package vendored yet raises the
projectdenominator —stdlib + projectgrows whilestdlibstays 0. The payoff lands at B6. A report must say this, or a reader sees the number fall and concludes the strategy failed while it is doing what the metric predicts. cc-thicknessis the before/after pair for B4, and it must be taken at the same--scope. Two numbers describing different file sets are not a comparison.gluePctdown does not mean the relocated code still runs — B4 also needs atypecheck:game. A projecttypecheckcovering only.tests/compiles none ofassets/scripts/**, i.e. exactly thecc.Components this stage rewrites. A finished retrofit’s review found two runtime crashes that the unit suite and that typecheck both passed clean, because the suite imports the logic unit directly and never loads the component. Runtsc-baseline.cjs(fromt1k-cocos-playable-modularize-refactor) over the game against the editor’stemp/declarationscctypes, with the pre-existing vendored errors held in an identity-keyed known-gap list asserted in both directions — new fails, vanished reports STALE (theonekit-core/.claude/modules/t1k-verification/rules/pinned-baseline-test-companion.md). Never a raw exit code: a legacy tree is red before B4 starts, and an always-red gate is ignored as surely as an always-green one.adoptionandcoveragemeasure different things — what is used vs what is installed. B7 reports both; a package installed and never called raises coverage and leaves adoption flat.
Related
Section titled “Related”references/stage-gates.md— per-stage commands, the Definition of Done (including the DoD prohibition), the lane recipe, and the failure modest1k-cocos-playable-pla-retrofit-reviewer— the stage-B9 agentt1k-cocos-playable-modularize— the sibling CPM pipeline (this one is the retrofit-specific order)t1k-cocos-playable-reuse-coverage— the B7 metrics, including--cc-thicknessrules/knowledge-sweep-cocos.md— the reuse loop every B5 package starts from