t1k:cocos:playable:modularize-structure-audit

Field	Value
Module	`playable`
Version	`0.15.0`
Effort	`medium`
Tools	—

Keywords: blueprint, drift, folder-conformance, layout-grading, modularize, playable-structure, structure-audit

How to invoke

/t1k:cocos:playable:modularize-structure-audit
<project-root> [--apply|--json]

structure-audit (Pillar A)

Grade a project’s folder layout (not its code) against the vendored references/blueprint.md snapshot of PlayableAdsTemplate@develop. Emit a per-rule verdict + a normalization plan. Part of the t1k-cocos-playable-modularize set — obeys the shared CLI contract (report-only default, --apply behind an AskUserQuestion gate).

When to invoke

“Does this playable-ad project follow the canonical structure?”
First pass of a modularization — establish where the folders drift before reuse/refactor.
Regression-check a project’s layout after a refactor.

Scope boundary (read this)

Folder-only. Grades layout: asset placement, game-assets/resources split, scripts/ layout, framework-consumption shape, repo scaffold.
Does NOT verify imports/consumption. Whether a declared @playablelabs package is actually imported is reuse-scan/refactor’s job (a project can list a package in playableSync yet never import it — out of scope here). Do not conflate “package folder present” with “package used”.
Does NOT migrate. R1 framework migration (embedded → CPM) is reported, never applied here — it is high-blast-radius and belongs to refactor.

Workflow

Validate <project-root> (must contain assets/ + package.json) — else usage error, exit 2.
Scan: node scripts/scan-structure.cjs <project-root> → per-rule JSON (R1–R10 + registry note).
Grade via references/rule-grading.md: weights, score, and the safe/deferred/report-only bucketing of each DRIFT/MISSING.
Report per references/report-format.md → reports/; persist the JSON alongside.
(--apply only) Decide via AskUserQuestion, then apply SAFE normalizations only (create missing canonical dirs; gitignore build artifacts; emit font-move list). Never move/delete .meta; never migrate the framework.

Blueprint facts (do not re-derive)

Snapshot is pinned to a specific PlayableAdsTemplate@develop commit (exact SHA, date, and refresh procedure in references/blueprint.md — bump SHA + re-check rules + re-run self-consistency together).
Self-consistency: running this on the template snapshot itself MUST score ~all CONFORMANT. The 3 top-level metas Config.meta/Scene.meta/res.meta are baseline-canonical (whitelisted) — they are NOT drift.
Expected AnimalHunter drift: R1 (embedded PLAGameFoundation/PlayableParamterTool; only warning/ under @playablelabs/), R3 (game-assets/font/), R10 (.optimize-data/). Registry host .studio vs .ai is a config note, not an R-rule verdict.

Scripts

node scripts/scan-structure.cjs <project-root>              # per-rule JSON to stdout (report-only)
node scripts/scan-structure.cjs <project-root> --repo-root <dir>   # override repo-root for R9

References

references/blueprint.md — the pinned R1–R10 folder rules + provenance + refresh procedure.
references/rule-grading.md — verdict vocabulary, weights, safe-vs-deferred normalization buckets.
references/report-format.md — markdown report template + rendering rules.

Gotchas

Never move or delete a .meta. UUIDs live there; a silent move re-points every scene/prefab ref. Orphan metas are quarantine-to-report only.
The 3 baseline metas are not drift — the scanner whitelists them. If a blueprint refresh changes the template’s meta set, update the whitelist in scan-structure.cjs + blueprint.md together.
Folder present ≠ package used. Don’t claim a package is consumed just because its folder exists.
R1 is not auto-fixable here. Report it; migration is refactor with a per-unit gate.