Skip to content

t1k:cocos:playable:characterization

FieldValue
Moduleplayable
Version4.33.13
Effortmedium
Tools—

Keywords: behaviour unchanged, characterization, characterization test, golden master, record baseline, relocation gate, verify golden

/t1k:cocos:playable:characterization
record --project <root> --module <Name> [--out <path>] [--files <manifest.json>] | verify --project <root> --golden <path> [--json <out>] [--files <manifest.json>]

Records what a module’s use cases DO, before a single line of relocation, and replays the exact same recording after — so “behaviour unchanged” is a diff a machine ran, not a claim a reviewer has to take on faith.

This is the equivalence gate for stage R of plans/260921-pla-retrofit-program/README.md (§3, §4.1): relocation is the one stage of R→E→V→T→M that moves executable logic, and it is the stage most likely to silently change gameplay. t1k-cocos-playable-stdlib-harvest’s diff-test-generate.cjs/diff-test-run.cjs already do equivalence testing in this kit, but they are scoped to a single pure symbol being harvested into stdlib and explicitly refuse a multi-file closure or anything cc-coupled (S6a). This skill works at module scope, across files — the R stage’s actual unit of change — which is precisely the case that pipeline refuses.

Terminal window
# BEFORE relocation — record the golden.
bun scripts/record-baseline.cjs --project <root> --module <Name> [--out <path>] [--vectors <n>] [--seed <n>] [--files <manifest.json>]
# AFTER relocation — replay it against the current source.
bun scripts/verify-golden.cjs --project <root> --golden <path> [--json <out>] [--files <manifest.json>]

--files <manifest.json> names a module’s entry-point files EXPLICITLY, bypassing the modules/<Name>/ scaffold requirement entirely — see “How discovery works” below. Omit it and discovery falls back to the scaffold convention exactly as before; this flag is additive.

Both scripts print exactly one JSON object on stdout — facts, never judgement (theonekit-core/.claude/modules/t1k-engineering/rules/ai-driven-design.md). record-baseline.cjs exits 0 when a golden was written (even if some classes/methods were refused — a refusal is reported, not fatal), 1 when NOTHING could be recorded or the two runs disagreed, 2 on a usage/environment error. verify-golden.cjs exits 0 when every recorded row replayed identically, 1 on any divergence/missing row, 2 on usage/ environment error.

CheckWhy
<project>/assets/ existsThe target must be a Cocos project; the wrong root is a usage error, not an empty result
Pinned parser installed: bun install --frozen-lockfile --ignore-scripts --cwd .claude/modules/playable/skills/t1k-cocos-playable-characterization/scripts (or bun install — this skill ships no lockfile)ts-morph’s Type API (call signatures, union members, array/tuple elements) drives synthesis. No regex fallback: a missing pin is exit 2 with the install command
The target project’s own node_modules/.bin/vitest (or bunx-reachable vitest) is installedBoth scripts drive the project’s OWN Vitest config to run the generated harness — see “Why a real spec” below
The project’s Vitest include covers root tests/**The harness writes its spec to <projectRoot>/tests/__characterization_tmp__/ (harness.cjs, TMP_DIRNAME). vitest run <spec> still intersects the positional path with the config’s include, so an assets/-only include reports No test files found for a spec that exists on disk — which reads as a recorder bug and is a config gap. stdlib-autocontribute’s Stage 0 probe states the same requirement for the same reason (#1010, fixed for that skill in #1011)
Either the module resolves to exactly one directory named <Module> whose parent is literally modules/, OR --files names a manifest of real filesAmbiguous or missing resolves to a usage error, never a guess (findModuleDir, resolveExplicitFiles)

Two modes, tried in this order — resolveModuleFiles (scripts/lib/discover.cjs) is the shared front door both record-baseline.cjs and verify-golden.cjs call:

  1. --files <manifest.json> given → explicit mode. The manifest is a plain JSON array of file path strings (relative to --project, or absolute) — e.g. hand-derived from a docs/system-design.md § Module Architecture table that maps a module name to its real files. Every listed path is resolved and must exist; ANY missing path is a typed, non-silent refusal (explicit-files-missing, listing which ones) — a partial/degraded file set is never used. This is the path for a module with no modules/<Name>/ scaffold at all — see “Why explicit mode exists” below. Tier reported: explicit.
  2. --files absent → scaffold mode (unchanged from V1).
    1. Find the module directory — a directory named <Module> (case-insensitive) whose parent is literally modules/. Zero or more-than-one match is an error, never a silent pick (findModuleDir).
    2. Find candidate entry-point files, first non-empty tier wins: application/**/*UseCase.ts → application/**/*{Service,Handler,Command,Query,Controller,Router}.ts → presentation/**/*.ts (last resort — this tier is where a file importing cc is expected). No files in any tier is a hard error (no-entry-points-found), never an empty golden.

Either mode then parses each resolved file with ts-morph and describes every EXPORTED class: its constructor parameters and its candidate operations (the method named execute when present, otherwise every public non-underscore-prefixed method) — identical downstream of discovery, parseEntry/plan.cjs/harness.cjs never branch on which mode produced the file list.

A module that resolves (either mode) but whose every class exposes no public operation is no-operations-refused per class exactly as before, and record-baseline.cjs refuses to write ANY golden when nothing was recordable at all (countAttempted(...).recorded === 0 → nothing-recordable, exit 1) — a vacuous golden (zero rows) that would pass verify-golden.cjs forever while proving nothing is never written.

This skill gates the R (Relocate) stage of the PLA retrofit (plans/260921-pla-retrofit-program/README.md §3, §4.1), whose targets are legacy repos never scaffolded into modules/<Name>/. Scaffolding them first would itself be relocation work, so --files is how a caller reaches a repo the scaffold mode cannot. Measured case: references/why-explicit-mode.md.

The refusal contract — this IS the product

Section titled “The refusal contract — this IS the product”

A cc.Component-only behaviour is never recorded by mocking the engine; the tool refuses, and the refusal is the signal that the logic must be relocated first before it can be characterized at all. Four refusal reasons, checked in this order:

ReasonFires whenWhat it means
cc-coupledThe candidate file imports from 'cc'/'cc/*'/'db://...' at all (file-level gate), or a constructor/method type resolves to a name bound by such an importThis behaviour is only reachable through the engine — relocate it out of Presentation/Infrastructure before it can be characterized. File-level and therefore over-broad: one cc import refuses every class in the file, including an engine-free one. When relocation is not yet available (Stage 5), that class has a sanctioned manual path — see “A cc-bound file with an engine-free class” below
concrete-classA constructor parameter’s type is a real class (not an interface/type-literal/function type)Out of scope for V1 — instantiating a real collaborator (rather than a port) needs a hand-written fixture this tool does not attempt
unresolvable-typeAn overloaded call signature, a type with no synthesizable shape, a depth-6+ recursive type, or an object with a property this tool cannot classify as data or a methodThe type is real but this synthesizer has no case for it
no-operationsA class was found and its constructor resolved, but it exposes no candidate methodNothing to call — not an error in discovery, just nothing to characterize on this class

A refusal is scoped to the narrowest node that failed — a cc-coupled FILE refuses every class in it; a concrete-class constructor param refuses only that CLASS (its siblings in the same file are unaffected); an unresolvable-type method parameter refuses only that METHOD. See references/refusal-and-synthesis.md for the full synthesis rules (what counts as “plain data” vs. a “port”, how unions/arrays/Promise<T> are handled) and worked examples.

A hand-authored spec is not a substitute — it is the failure this refusal prevents

Section titled “A hand-authored spec is not a substitute — it is the failure this refusal prevents”

On RushTankPLA, 100 hand-written characterization tests were authored for one system by copying its logic INTO the spec rather than importing the subject (the subject sat inside a cc.Component, so a bare require/import could not load it in Node). 49 of the 100 never imported anything from the file they claimed to pin — including the two highest-risk behaviours, which landed in the two weakest of the 49. A spec built that way passes forever: it asserts the transcription against itself, and it stays green while the real source drifts arbitrarily far from what the spec still describes. A spec claiming to characterize file X must contain an import that resolves to X. If it cannot — because the subject is cc-coupled — that is exactly the cc-coupled refusal above, and the fix is relocation (t1k-cocos-base-architecture-patterns’ pattern triggers, rules/code-quality-cocos.md), never a spec that reimplements the logic to work around the refusal. Reviewing a characterization/golden-master spec that does not import its subject is the same finding as a missing test, not a lesser one.

A cc-bound file with an engine-free class — the mocked-engine mode

Section titled “A cc-bound file with an engine-free class — the mocked-engine mode”

The section above refuses the counterfeit spec: one that reimplements the subject’s logic and imports nothing. There is a second, sanctioned shape that the refusal contract’s file-level gate cannot express, and it is the one Stage 5 needs when relocation is not yet permitted.

The case. A file imports cc (or db://) but holds at least one class whose signatures never name an engine type — a decision/state class that collaborates with engine-bound neighbours rather than subclassing cc.Component. The file-level gate refuses the whole file (classes: []), so the engine-free class is recorded nowhere even though nothing about it needs the engine.

The mode. Run the real class under a mocked engine, with its engine-bound collaborators replaced by port objects at the source’s own declared seam — the pattern is vi.mock('cc', …) + stubs, and it is only the sanctioned path when all of the following hold:

  1. The spec imports the subject (import { X } from '<real path>'). This is the line that separates the mode from the failure the section above describes — a mocked-engine spec that still imports its subject is a characterization test; one that does not is a transcription.
  2. The mocked surface is the engine and presentation collaborators only — never the subject’s own decision logic, which must execute for real.
  3. The golden records a decision-level outcome — gate outcome, occupancy, which signals fired — not tween/animation-level detail. This is what lets the presentation layer be relocated later without making the golden diverge: the golden pins decisions, and relocation moves tweening.
  4. It lands in the module’s .tests/ directory beside the source (.tests/x.golden.test.ts), not in the recorder’s tests/__characterization_tmp__/, because it is hand-maintained.

Mutation-verify it before trusting it — flip one decision in the subject and confirm the spec goes red. A mocked-engine golden that cannot be made to fail is asserting the mock against itself, which is the same defect wearing a better disguise.

Cost, stated plainly. The recorder cannot generate this mode: it is a hand-written spec, so it does not carry the recorder’s determinism guarantee (the seeded Math.random swap, the two-run reproducibility check) and it is not replayed by verify-golden.cjs. It is strictly weaker than a recorded golden and strictly stronger than nothing — which is exactly the trade Stage 5 makes when the alternative is no golden at all. Prefer relocation the moment the stage allows it; the plan’s §4.1 ordering is not negotiable, and this mode does not license editing source to make a class recordable.

The plan’s own file-scoped gate makes this the only refusal that is broader than the node that failed: a concrete-class or unresolvable-type refusal is already per-class/per-method (§ above), and a per-class cc gate would narrow this one too. It is not implemented in V1.

Every derived value is hash(seed, seedPath), where seedPath is built from discovered names, never from position alone. record-baseline.cjs runs the harness twice and refuses to write a golden unless both runs agree byte-for-byte (error: "non-deterministic", exit 1). Full rationale: references/determinism.md.

Why a real Vitest spec, not a bare require

Section titled “Why a real Vitest spec, not a bare require”

Both scripts render a disposable spec into <project>/tests/__characterization_tmp__/, run it through the project’s own Vitest config, and delete that directory in a finally, so a crash never leaves a stray spec. Full rationale: references/why-vitest-spec.md.

references/golden-schema.md documents the golden JSON shape (schemaVersion, module, seed, vectorCount, and the entries → classes → operations → vectors tree, each level carrying either refused: false plus its children or refused: true plus reason/detail).

verify-golden.cjs’s report gives each golden row a status:

statusmeaning
identicalThe row replayed byte-for-byte
divergentThe row replayed to a DIFFERENT output/threw — a real behaviour change
missingThe golden’s key is no longer reachable by discovery (class renamed/moved, or a dependency no longer resolves) — reported, never silently skipped

A missing row is treated exactly like divergent for the exit code: a characterization gate that quietly drops what it cannot re-find would pass on a relocation that changed the public surface enough to make the old behaviour unobservable — which is a real regression signal, not a housekeeping detail.

Recording and verifying a golden are scripted; interpreting a diff is not. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.

StepAgent
Run record-baseline.cjs and verify-golden.cjs and relay the verdict and diff counts verbatimt1k-cocos-base-tester
Decide whether a golden diff is a regression or an intended changet1k-cocos-base-debugger — reasoning tier
  • No concrete-class constructor dependencies. A use case that takes a real collaborator class (not a port interface) is refused (concrete-class); wiring one in needs a hand-written fixture, which is future work, not silent skipping.
  • Method arguments must be plain data (primitives, literal unions, arrays/tuples, or a plain object of those) — a method whose OWN argument is itself a function/port is refused (unresolvable-type), because a per-vector varying port stub is out of scope for V1.
  • Overloaded call signatures refuse. A port method or a function-typed dependency with more than one call signature is unresolvable-type — there is no single return type to synthesize against.

None of these degrade silently — every one is a named refusal in the golden’s refusals list.

Script and reference map (entry points, the pinned parser, the synthesis library, the golden schema, the test suite): references/files-map.md. Entry points: scripts/record-baseline.cjs (record) and scripts/verify-golden.cjs (replay).

  • plans/260921-pla-retrofit-program/README.md — the program this gates (§3 R→E→V→T→M, §4.1)
  • t1k-cocos-playable-stdlib-harvest (diff-test-generate.cjs/diff-test-run.cjs) — the single-symbol equivalence gate this skill does NOT replace; both may run on the same module at different stages (harvest’s S6b runs on the now-pure code AFTER extraction into stdlib)
  • t1k-cocos-base-clean-architecture — the Domain/Application/Presentation layering this skill’s discovery assumes
  • theonekit-core/.claude/modules/t1k-engineering/rules/ai-driven-design.md — why both scripts emit facts only, never a verdict