Skip to content

t1k:cocos:playable:modularize-refactor

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: embedded-to-cpm, import-repoint, modularize refactor, playablesync

/t1k:cocos:playable:modularize-refactor
<cocos-project-root> --audit <path> --reuse <path> [--arch <path>] [--apply]

Turn the audit + reuse classifications into an ordered project refactor plan and (with --apply) execute it incrementally. Migrates the embedded framework (PLAGameFoundation, PlayableParamterTool) to CPM-package consumption. No package splitting — that is contribute. Part of the t1k-cocos-playable-modularize set — obeys the shared CLI contract (../t1k-cocos-playable-modularize/references/shared-cli-contract.md).

Graph grounding — t1k-cocos-base-code-graph

Section titled “Graph grounding — t1k-cocos-base-code-graph”

The studio code graph (code-graph-cocos) answers the one question the corpus and grep both cannot: what is structurally connected to this symbol. Recipes, the Cocos-only gaps and the provenance line: t1k-cocos-base-code-graph; usage SSOT: core’s t1k-code-graph.

Every tier below that repoints or retires an import edge — Tier 0 upgrades, Tier 2 swaps, Tier 2.75, Tier 3’s submodule removal — deletes or moves a source the graph sees as an edge source. Before any such unit, get_neighbors on the symbols it touches bounds who depends on them, so a non-empty incoming set is the argument against retiring.

It is corroboration, not a gate. The graph is nightly and default branch only: a call site added since the last build is invisible, and a call site the unit itself just deleted is still listed. So verify-imports.cjs / verify-reachability.cjs on disk stay the pass condition for every unit, and the graph answer is recorded beside them — a divergence is a finding to report, not a tie to break silently. Nothing in the unattended-walk block below may be released on a graph result alone.

Read it as blast radius for scoping a unit, never as a licence to delete: no dead-code verdicts on Cocos (@ccclass attaches via prefab __uuid__, not an import).

  • After structure-audit + reuse-scan: produce the ordered migration plan.
  • To execute a migration incrementally (--apply, one package per gate).

Requires BOTH input reports: a structure-audit JSON (--audit) and a reuse-scan JSON (--reuse). plan-refactor.cjs sets preconditionsOk: false if either is missing/empty — the skill then hard-blocks --apply (report the missing input; do not guess a plan).

An architecture-audit JSON (--arch, from t1k-cocos-base-architecture-patterns audit mode) is optional but strongly recommended. Without it Tiers 2.5/2.75 are skipped and the plan reports archAudit: absent — a legacy project then migrates its structural debt into packages untouched.

The design-doc probe BLOCKS Tiers 2.5/2.6/2.75 — always pass --design-probe

Section titled “The design-doc probe BLOCKS Tiers 2.5/2.6/2.75 — always pass --design-probe”
Terminal window
bun <system-design>/scripts/probe-design-doc.cjs docs/system-design.md <repo-root> > design-probe.json
bun scripts/plan-refactor.cjs --audit <a> --reuse <r> --arch <arch> --design-probe design-probe.json

plan-refactor.cjs records designDoc: ok | foreign | template-verbatim | template-unfilled | non-canonical | absent | indeterminate | unchecked, and emits a machine-readable blockers[] + blockedTiers whenever that verdict is anything but ok. Every step in a blocked tier repeats the block inline as blockedBy, so an --apply walker refuses those units mechanically rather than relying on the operator having read a warning two hundred lines up.

unchecked (flag omitted) blocks too. Not asking is not a pass — it is precisely the state an inherited doc sits in while looking healthy to every other check here (theonekit-core/.claude/modules/t1k-verification/rules/negative-result-scope.md).

Three reasons this is a block and not a warning: (1) a doc describing another project satisfies every other check identically — structure-audit R9 only asks whether the file exists, and generate-manifest’s failure surfaces as the generic designState: null; measured 2026-08-20 (HexaBugFlowPLA), a 16-step plan with six Tier 2.5 module-boundary steps graded against PlayableAdsTemplate’s doc. (2) designState: null and “the doc belongs to someone else” need different repairs — regenerating a manifest fixes the first and is useless against the second, so the plan names them separately (design-manifest-missing vs design-doc-foreign). (3) Tier 2.5 is the only tier that rewrites source logic, and its splits break scene references tsc cannot see; boundaries nobody decided are the most expensive thing this pipeline can produce.

The block is scoped on purpose, and the scoping is what keeps it enabled. Tiers 0/1/2/3/4 are version, folder and import-path work no design doc grades — fully plannable and appliable on a legacy repo with no doc, with plan-refactor.cjs still exiting 0 and still printing the blocked findings. A gate that refuses the whole report is one operators route around, and then it protects nothing.

This is the pillar that genuinely requires docs/system-design.md (pillars A and B do not — see the dependency table in t1k-cocos-playable-modularize). Its § “Code Structure Rules (Mandatory)” is the SSOT Tier 2.5 is graded against, so planning without it means measuring against nothing.

Resolving, authoring and drift-auditing the doc is owned end-to-end by t1k-cocos-base-system-design (authoring + template resolution) and t1k-cocos-base-architecture-patterns (audit), including the missing-template and legacy “no architecture to document” cases. Do not re-derive that procedure here; it is report-or-author only and never mutates code.

Generate the manifest from the doc, then pass it so the plan records what it was graded against:

Terminal window
bun <system-design>/scripts/generate-manifest.cjs docs/system-design.md --out docs/design-manifest.json
bun scripts/plan-refactor.cjs --audit <a> --reuse <r> --arch <arch> --manifest docs/design-manifest.json

The plan reports manifest: present | absent | unchecked. unchecked (flag omitted) is not absent — the first makes no claim about the project, the second is a checked negative. Omitting the flag on a project that has no doc is the case that reads as fine and is not.

It also records designState — the doc’s tense. A plan built from a to-be manifest moves TOWARD a documented target; from as-is, AWAY from documented current reality. Identical step lists, opposite meaning; say which one you are executing. designParse: "partial" means the module map was only partly readable, so the plan is not fully informed.

designState: null is a third case, and the common one. No manifest was read at all, so the plan moves neither toward a target nor away from a baseline — a bottom-up list of violation fixes whose module boundaries land wherever the split test happened to cut. The script says so on stderr and mirrors it into the artifact as designStateWarning (null in every other case), because a plan built against nothing reads exactly like one built against a target: ordered tiers, real evidence, plausible steps. The fix is upstream: run t1k-cocos-playable-modularize Phase 2.5 (t1k-cocos-playable-preproduction in refactor mode) to author the to-be doc from the as-is doc

  • architecture-audit.json + reuse-scan.json, regenerate the manifest, re-plan with --manifest. Exit stays 0, but the design-probe gate above also raises a design-manifest-missing blocker withholding Tiers 2.5/2.6/2.75 — the report still prints in full, which is what keeps pillars 1 and 2 usable on a repo with no doc. Exiting non-zero is what would get the pipeline abandoned on exactly the legacy projects it exists for; withholding tiers does not.

Before mutating anything, the manifest must still describe the code:

Terminal window
bun <system-design>/scripts/verify-manifest.cjs docs/design-manifest.json <project-root>

Non-zero exit blocks --apply. Planning against a manifest that no longer matches the tree means every Tier 2.5 step is aimed at a file layout that has already moved. Verification is state-dependent, so read pathsChecked in the report: under to-be it is false and a pass proves only internal consistency — it is not evidence the code matches. Unclaimed files are reported and never block; a legacy project is mostly unclaimed and that is the finding, not an error.

The whole-refactor plan is built once, in step 2 below, from all three audits, before any mutation. Architecture findings are an input to planning, not a mid-flight discovery: audit early, mutate in tier order. Do not replan between units — if a finding emerges during --apply, record it and re-plan in a fresh pass.

Ordering (safe → risky) — never reorder

Section titled “Ordering (safe → risky) — never reorder”
  1. Tier 0 — upgrade installed-but-outdated packages: one row per @playablelabs/* package whose installed version is behind the registry latest, from the reuse-scan report’s installedVersions block. Lowest risk, highest value — and the ONLY tier that fires on a project that already finished CPM migration, where Tier 3 is empty by construction. Gated per-unit: an upgrade is a small diff but can still change behaviour.

    The action is a command, never a panel instruction — every row renders as bun <refactor-skill>/scripts/upgrade-package.cjs <cocos-project-root> <pkg> --to <latest> --expect-installed <installed>, which self-verifies by re-reading the vendored package.json and exits non-zero unless the version on disk is the one asked for. update-package via package-manager names an editor-panel handler no MCP tool exposes, so --implement reached the row with nothing to run and the upgrade silently never happened (pinned by plan-refactor-tier0-executable-action.test.cjs).

    Two axes decide routine vs BLOCKED, both read from the reuse-scan: vendoredDivergence / locallyModified (#274 — the upgrade overwrites the vendored tree and deletes a local patch while tsc stays clean) and importPathCheck / removedImportPaths (#294 — semver is no proxy: the measured case was a patch bump removing 3 of 14 imported paths). A recorded finding blocks at risk: high with a requires: prerequisite; an absent check blocks at risk: medium (divergence-never-checked / import-paths-never-checked), because unchecked is “nobody compared”, not “nothing is patched”. One row per package carrying every blockReasons entry it trips and one requires: per reason. A Tier 0 row reaches unattended.walkOrder only when both axes ran and neither recorded anything — full matrix in decision-policy rule 5, full rationale in references/migration-playbook.md § Tier 0.

    A VERIFIED @playablelabs/parameter-tool sync is not a wired one (#1719). Read the result’s hostWiring: the host must call PlayableConfigProvider.initialize(PlayableConfig, meta, CURRENT_SDK) and register the ParameterToolRuntime seams itself, and the sync only warns. Steps: § Tier 0 “Host wiring” in the same playbook.

  2. Tier 1 — folder normalizations (create canonical dirs, gitignore artifacts, quarantine orphan metas to report, review unexpected top-level dirs, relocate stray game-assets/ entries). Rules that grade more than one sub-condition (R2, R3) emit one row per sub-condition that actually fired, each carrying only its own evidence — never a fixed action per rule ID (#249). R11 (a script directory that has become the codebase) emits a report-only row, not a move: the audit knows which directory is crowded, only the design doc knows which module each file belongs to. With --manifest the row names the real target modules and points at the Tier 2.6 rows that actually order the moves; without one it says plainly that no targets are known and routes to Phase 2.5, because a split into invented folders is worse than the pile it replaces.

  3. Tier 1.5 — INSTALL a package a live REUSE swap needs and the project does not have, via install-package.cjs. One unit per package ROOT, editorState: closed, and the Tier 2 swap that needs it declares dependsOn this unit. Only a live swap earns an install — a keep-retract, an extend or a manual-queue is a decision NOT to import that package, and installing anyway vendors code the plan already declined. Before this tier the install was a parenthetical (install package first — Tier 3) pointing at a tier that emits nothing for a package which is merely absent: ordered by prose, owned by no tier, executable by nobody (theonekit-core/.claude/modules/t1k-verification/rules/wired-not-just-present.md).

  4. Tier 2 — REUSE swaps for packages installed already or by Tier 1.5 (pure import-path changes). Runs before architecture work: never refactor code a swap is about to delete.

  5. Tier 2.5 — architecture refactor (SOLID + mandatory pattern triggers per rules/code-quality-cocos.md), driven by the --arch findings. Includes enabling extractions — SRP splits whose purpose is to expose a seam that a package can then fill.

  6. Tier 2.6 — MECHANIC SLICE: move each design-doc module into its own vertical folder, one unit per module, editorState: closed. Delegated in full to t1k-cocos-playable-mechanic-split — that skill is the SSOT for the procedure (cid snapshot/diff around every move, .ts + .ts.meta co-move, barrel + README contract, portability-blocker scans). This skill owns only the wrapper: which modules, in what order, gated per unit. Boundaries come from the manifest, never from a coupling audit re-run here — every row invokes it as --mechanics-from docs/design-manifest.json, because a second module map decided by a different method is the one failure this delegation exists to avoid. Rows carry dependsOn the Tier 2.5 extraction that rewrites their files, and a module already living in its own folder emits no row at all. This is the tier that turns R11’s report into work: it stayed report-only for want of the module table, and the manifest is that table.

  7. Tier 2.75 — second REUSE pass over the seams Tier 2.5 exposed (exposesSeamFor in the arch findings). Skipping this makes Tier 2.5 a net loss: more files, same duplicated logic.

  8. Tier 3 — embedded-submodule → CPM migration, per package. Highest blast-radius. Delegated in full to t1k-cocos-playable-submodule-to-package, the SSOT for the procedure (submodule removal, vendoring, playableSync, import repoint + API-signature changes, ParameterToolRuntime seams, scene/prefab uuid remap, its own defect scanner); this skill owns only the wrapper: gate → invoke → both verifiers green → editor confirm → remove embedded dir → pathspec commit. Tier 1.5 supersedes it for a package that is merely ABSENT — Tier 3 ends in “remove the embedded dir”, and there is none when the source was never vendored; before 1.5 this loop doubled as the install path and named the dead panel handler to do it.

  9. Tier 4 — tag CONTRIBUTE (no mutation; hand-off to contribute).

editorState and the unattended walk block — see references/editorstate-walk-block.md

Section titled “editorState and the unattended walk block — see references/editorstate-walk-block.md”

Plan generation, status and delta reporting are scripts; executing the refactor is not. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.

StepAgent
Run plan-refactor.cjs --audit, refactor-status.cjs and symbol-delta.cjs and relay their tablest1k-list-classifier
Run install-package.cjs / retire-consumed.cjs for one planned stept1k-cocos-base-tester
Execute a refactor step or resolve an editorState blockt1k-cocos-base-developer — reasoning tier