t1k:cocos:playable:modularize-reuse-scan
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: reuse, reuse-scan, subsystem
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:modularize-reuse-scan<cocos-project-root> [--apply|--json]reuse-scan (Pillar B)
Section titled “reuse-scan (Pillar B)”Classify every local framework-ish subsystem into one of four verdicts. Part of the
t1k-cocos-playable-modularize set — obeys the
shared CLI contract (../t1k-cocos-playable-modularize/references/shared-cli-contract.md).
| Verdict | Meaning | Consumed by |
|---|---|---|
| REUSE | Duplicates an upstream package; local is equivalent or worse → swap for a package import. | refactor Tier 2 |
| EXTEND | An upstream package covers it, but local has a genuine fix or extension → swap and contribute the improvement back as a package update. | refactor Tier 2 + contribute (UPDATE mode) |
| KEEP | Game-specific glue; stays in the project. | — |
| CONTRIBUTE | Novel, self-contained, general; no upstream package → new package. | contribute (ADD mode) |
EXTEND is the verdict that prevents silent data loss. Without it, a subsystem where local diverged ahead of the package gets tagged REUSE, and the Tier 2 swap deletes the local improvement along with the local code — irreversibly, and invisibly, because the swap compiles clean. Whenever a package match is found, compare versions of the behaviour, not just presence.
Executed by
Section titled “Executed by”Unlike structure-audit’s closed-form R1–R11 grading, this pillar’s
REUSE/EXTEND/KEEP/CONTRIBUTE verdict is NOT rubric application over known
facts — it turns on judging semantic-similarity doc_search hits, filtering
Unity/.NET noise from genuine Cocos-foundation matches, and weighing whether a
divergence is loadBearing. Only the surrounding fact-gathering is mechanical
(routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”):
| Step | Agent |
|---|---|
Run enumerate-subsystems.cjs and tabulate the cpmAdoption / installedVersions rollups it already computes offline | t1k-metrics-reporter |
Pull ONE named CPM listing (bun info @playablelabs/<name> --registry <host>) to resolve a package’s latest version | t1k-fact-fetcher |
Reconcile a vendored package’s tree against its published tarball for vendoredDivergence (byte/line diff, CRLF-normalized) | t1k-data-verifier — a stated comparison method, not a judgment |
Judge REUSE vs EXTEND vs KEEP vs CONTRIBUTE per subsystem (doc_search similarity, loadBearing divergence, .NET-noise filtering) | stays on a reasoning tier — the rubric in classification-rubric.md still requires interpreting an unstructured similarity hit and a behavioral diff, not just applying labels to known values |
--apply: perform the AskUserQuestion-gated package install | stays on a write-capable, reasoning tier |
A block claiming the whole pillar is cheap would be wrong: t1k-list-classifier
labels items against an already-decided rule, and here the hard part — was
this doc_search hit actually the same subsystem, does this diff matter enough
to block a swap — is the decision the rubric depends on, not a lookup into it.
Only the deterministic scaffolding around that decision (running the
enumerator, tabulating what it already computed, fetching one named version,
diffing two known trees) is cheap-tier work.
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.
Extraction-candidate recipe (per-repo god_nodes dedupe trap; get_node before ranking): references/graph-grounding.md.
Candidate volume is not a verdict. The REUSE/EXTEND/KEEP/CONTRIBUTE rubric below still decides, and
the graph only narrows which subsystems are worth running doc_search against.
No dead-code verdicts. A zero-caller result on a Cocos @ccclass is not an unused signal — the
component is attached by prefab __uuid__, not an import. verify-reachability.cjs on disk stays
the reachability authority; the graph corroborates or contradicts it, and a divergence is recorded,
never silently resolved.
The graph is nightly, default branch only. It cannot see a file added since the last build, so it never grounds a REUSE/CONTRIBUTE verdict on its own — Step 2’s grep still does.
When to invoke
Section titled “When to invoke”- After
structure-auditflags embedded framework (R1 DRIFT): decide which subsystems to reuse. - “Which of our local systems already exist as
@playablelabspackages?” - Before
refactor: produce the REUSE/EXTEND/KEEP/CONTRIBUTE input its migration plan consumes.
Manifest input — where subsystem boundaries come from
Section titled “Manifest input — where subsystem boundaries come from”A “subsystem” is either a declared module or a top-level folder, and which one you got
changes what the report means. Pass --manifest docs/design-manifest.json (generated by
t1k-cocos-base-system-design) and modules come from the design doc’s explicit file lists;
omit it and they are readdir(assets/scripts).
discovery | Subsystem = | Read it as |
|---|---|---|
manifest | a module from the design doc, with an explicit file list | real boundaries; a module spanning three directories enumerates as one subsystem |
readdir-fallback | a top-level directory | a guess at boundaries |
The fallback is labelled, never silent — every studio project has no manifest on day one, so a degraded scan must stay distinguishable from a real one. It is also a fully valid report: this pillar grades local subsystems against upstream packages, which is independent of the project’s own architecture target. A project with no design doc still gets a complete reuse-scan.
Why it is worth passing. On a legacy god-class project folder shape is exactly what is wrong. On
the one real canonical studio project, readdir returns a single scripts/SniperDuel blob where the
design doc declares 12 modules — one doc_search instead of twelve, against a boundary nobody drew.
parse: "partial" propagates. A partially-read module map covers only what was read; the report
says so, and you must not present it as complete. parse: "unparseable" falls back to readdir
and names the migration helper — modules: [] there means the doc could not be read, not that the
project has no modules.
Skipping doc_search. When a module carries upstreamPackage, the subsystem is flagged
skipDocSearch: true only if the manifest’s priorArt is "searched" — that is Phase 0’s sweep
having actually run. When priorArt is "unavailable" the recorded answer is unverified rather than
disproven, so query it yourself; trusting it would launder “never looked” into “already checked”
(theonekit-core/.claude/modules/t1k-verification/rules/negative-result-scope.md).
What genuinely gates this scan is discovery (MCP and/or CPM), below — not the design doc.
Library discovery — two sources, MCP is not required
Section titled “Library discovery — two sources, MCP is not required”Full contract: shared-cpm-facts § Library discovery (../t1k-cocos-playable-modularize/references/shared-cpm-facts.md).
- Knowledge MCP (
mcp__knowledge-retrieval__doc_search) — hybrid lexical+vector discovery. Best at “does something already do X?” but proves capability, never the package name. - Cocos Package Manager — https://cpm.playablelabs.ai/ web UI, the CLI, the editor extension’s
list-packageshandler, orbun info @playablelabs/<name> --registry <host>. Authoritative on names, versions, and current contents; only matches what you thought to look up.
Prefer both: MCP to discover, CPM to confirm the concrete package and version. Record which source produced each verdict.
- MCP absent → degraded, NOT blocked. Drive discovery from the CPM listing instead, and mark the
report
discovery: cpm-onlyso a reader knows synonym matches may have been missed. Never report a false “0 packages found” because one source was unavailable — that would falsely mark every subsystem CONTRIBUTE (errors over silent fallbacks). - Both sources unavailable → exit 3. With no discovery at all there is no REUSE signal, and every verdict would be a guess.
- Corpus reality (verified): doc_search indexes the TheOne .NET/Unity API corpus PLUS the Cocos
template’s own subsystems (
objectPool,signalBus,async,gameControl, …). It is NOT a@playablelabsnpm registry — that is exactly why CPM is the naming authority.GameFoundation.*is on the Unity/.NET side despite the name — never a Cocos REUSE signal. Full contract + how to filter .NET noise:references/doc-search-contract.md.
Module contract (do not re-derive)
Section titled “Module contract (do not re-derive)”Composition is plain import; there is no register(ctx). A REUSE swap replaces
embedded-source imports with the owning package’s import and records the package in playableSync +
assets/packages/@playablelabs/. Install SSOT + the package↔subsystem folder map:
references/playablesync-ssot.md.
Workflow
Section titled “Workflow”-
Pre-flight — Knowledge MCP registration.
<HARD-GATE-CORPUS-PREFLIGHT>Before enumerating anything, check whethermcp__knowledge-retrieval__doc_searchis loaded this session. Loaded → step 1. Not loaded → register it in the background and HALT, telling the user a restart is required now, before enumeration spends anything on a run whose discovery half cannot work. Only an explicit “proceed on fallback” override continues — and the report must then recorddiscovery: cpm-onlyand mark everyCONTRIBUTEunverified.</HARD-GATE-CORPUS-PREFLIGHT>Why this gate exists when § “Library discovery” says the MCP is optional (CPM can verify a package you named; it cannot discover one you did not, so it may never conclude absence):references/corpus-preflight-and-receipt.md. -
Validate
<project-root>; resolve discovery sources — MCP live? CPM reachable? Record which. Neither available → exit 3. MCP-only or CPM-only → proceed, marking the report’sdiscoveryfield. -
Enumerate:
bun scripts/enumerate-subsystems.cjs <project-root> [--manifest docs/design-manifest.json]→ per-subsystem JSON. Pass--manifestwhenever one exists (see § Manifest input); check the report’sdiscoveryfield to know which definition of “subsystem” you actually got. Also carries a self-containment /reuseLikelihoodheuristic (game-coupled = low, self-contained = high), an offlinedivergence/verdictHintsignal against any already-installed package counterpart (see below), plus a top-levelcpmAdoption: { onCpm, totalCpmImports, subsystemsImportingCpm }rollup, plus aninstalledVersionsblock (one entry per vendored@playablelabs/*package, withinstalledread offline andlatestleft null for step 5 to fill). ReadcpmAdoption.onCpmFIRST — it answers “is this project already on CPM?”. When true, subsystems withimports["external-cpm"] > 0are already consuming upstream packages, so their doc_search result confirms an existing install rather than proposing a new one. -
Query per subsystem: one behaviour-keyword
doc_searcheach (see the contract). Read the top hits’assembly; a high-similarity hit on a known foundation subsystem = “exists upstream”. -
Classify via
references/classification-rubric.md(exists-upstream × game-coupled × divergence → REUSE / EXTEND / KEEP / CONTRIBUTE). Map REUSE and EXTEND subsystems to their owning package via the folder map. On every upstream match, run the divergence check before settling on REUSE:verdictHintfrom step 2 is the first signal —'EXTEND'means the offline export-name diff already found local exporting something the installed package doesn’t (divergence.extraExports). WhenverdictHintisnull(nothing installed locally yet), fall back to comparing against the CPM listing / published contents directly. Local has a fix, an extra case, or a behaviour the package lacks → EXTEND, and record what diverged socontributecan carry it upstream. Equivalent or worse → REUSE. -
Resolve
installedVersions(REQUIRED when anything is installed).enumerate-subsystems.cjsemits one entry per vendoredassets/packages/@playablelabs/*withinstalledread offline andlatest: null. Fill in eachlatestfrom CPM —https://cpm.playablelabs.ai/-/verdaccio/data/packages, authenticated with the~/.npmrctoken, or the package-manager extension’slist-packages. Carry the block through to the persisted report unchanged in shape (see § “installedVersions” below). Leavelatestnull where you could not resolve it — never guess, never copyinstalledacross;refactordistinguishes the two and reports which it got.
5b. Compare each vendored package against its own published tarball, and record the result in
vendoredDivergence (see § below). This is the question “was this package patched in place?”,
which nothing else in the pipeline asks: the per-subsystem divergence from step 2 diffs export
NAMES between local game code and an installed package, and never looks inside the vendored tree.
Without this block refactor plans every upgrade as routine, and running one silently deletes the
patch (#274). Where the comparison genuinely could not run (no registry access), emit
{ "checked": false } rather than omitting the block or writing an empty realDivergences — those
two say different things and refactor reports them differently. Normalize \r\n -> \n on both
sides before diffing, or on a Windows checkout every text file reports as diverged and the one
real patch is lost in the noise (#294).
5c. Resolve every imported subpath against the latest tarball, and record the result in
importPathCheck + per-entry removedImportPaths (see § below). This is the question “does the
version we are about to move to still export what this project imports?”, which neither of the
two blocks above asks — and which semver cannot answer, because this registry ships removals under
patch bumps. Without it refactor plans a breaking migration as a routine risk: low bump and
offers it first (#294). Where the resolution genuinely could not run (no registry access), emit
{ "checked": false } rather than omitting the block — an absent removedImportPaths under an
unchecked report means nobody looked, not that nothing was removed.
Placement: importPathCheck is a TOP-LEVEL key of the reuse-scan JSON (a sibling of
subsystems / installedVersions), never nested under another block — plan-refactor reads
reuse.importPathCheck only, and a nested one reads as “nobody checked” (#682).
-
Report + name the install →
reports/; persist JSON. For each REUSE subsystem the report names the owning@playablelabs/*package — and, wherever the CPM listing gave you one, the version, on the subsystem row (targetVersion). Carry it:refactorTier 1.5 pins that version onto the install command, and a row without one installs registry latest and has to say in its own evidence that nobody resolved a version (theonekit-core/.claude/modules/t1k-verification/rules/negative-result-scope.md). The REUSE/KEEP/CONTRIBUTE lists are the direct input torefactor(andcontributereads CONTRIBUTE). -
Who performs the install. The install itself is
refactorTier 1.5, runninginstall-package.cjs— a headless, self-verifying script, gated per unit, ordered before the Tier 2 swap thatdependsOnit. Prefer that path: it is the one an unattended--implementwalk can execute, and it only installs for a swap the plan has actually decided to make. (--applyonly) reuse-scan may still install a package itself after an AskUserQuestion gate, per package, for the standalone case where no refactor plan exists yet — use the same script, not the package-manager panel handler, which no unattended walk can reach. Either way reuse-scan NEVER rewrites game source imports; that isrefactor. -
Emit the reuse receipt (REQUIRED). Before declaring the scan complete:
Terminal window bun <knowledge-sweep-skill>/scripts/verify-sweep-ran.cjs \--receipt reports/reuse-receipt-<YYYY-MM-DD>.jsonThe machine-readable counterpart to step 6’s human report, and the only artifact that later answers “was the corpus actually consulted in that session?”. Read the verdict, not the issued count —
NON-CONFORMANT-UNANSWEREDmeans the searches went out and the corpus said nothing back, so everyCONTRIBUTEin that report is unverified. Commit the receipt beside the report; the discovery half is the half that historically goes untracked. Outcome semantics and the false green this closed:references/corpus-preflight-and-receipt.md.