Skip to content
T1KTheOneKit

t1k:cocos:playable:modularize-structure-audit

FieldValue
Moduleplayable
Version2.14.4
Effortmedium
Tools—

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

How to invoke

Section titled “How to invoke”
/t1k:cocos:playable:modularize-structure-audit
<project-root> [--apply|--json]

structure-audit (Pillar A)

Section titled “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).

Executed by

Section titled “Executed by”

Grading a fixed R1–R11 rubric against a pinned blueprint is mechanical; deciding what a DRIFT means for THIS project, and any actual normalization, are not (routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”):

StepAgent
Run scan-structure.cjs and classify each of R1–R11 CONFORMANT / DRIFT / MISSING per the pinned blueprintt1k-list-classifier
Bucket each DRIFT/MISSING safe / deferred / report-only per the stated rule-grading.md weightst1k-list-classifier
Decide whether an R1 framework-migration DRIFT should actually be migrated (high blast radius, belongs to refactor)stays with the orchestrating skill/user — never this skill, never cheap tier
--apply: perform the AskUserQuestion-gated SAFE normalizations (create dirs, gitignore artifacts)stays on a write-capable, reasoning tier — t1k-list-classifier has no Edit/Write tool

The rubric and the bucketing are both closed-form and pinned to a specific blueprint commit, so applying them needs no judgment. --apply is destructive and AskUserQuestion-gated by design, which is exactly why it stays off the read-only cheap tier regardless of how mechanical the grading itself is.

When to invoke

Section titled “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)

Section titled “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.

Design doc and manifest

Section titled “Design doc and manifest”

This pillar grades folders against the pinned blueprint and reads neither docs/system-design.md nor docs/design-manifest.json. Rule R9 checks only that the doc file exists as part of the repo scaffold, never its content.

Workflow

Section titled “Workflow”
  1. Validate <project-root> (must contain assets/ + package.json) — else usage error, exit 2.
  2. Scan: node scripts/scan-structure.cjs <project-root> → per-rule JSON (R1–R11 + registry note).
  3. Grade via references/rule-grading.md: weights, score, and the safe/deferred/report-only bucketing of each DRIFT/MISSING.
  4. Report per references/report-format.md → reports/; persist the JSON alongside.
  5. (--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)

Section titled “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

Section titled “Scripts”
Terminal window
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

Section titled “References”

Gotchas

Section titled “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.