t1k:cocos:playable:characterization
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | medium |
| Tools | — |
Keywords: behaviour unchanged, characterization, characterization test, golden master, record baseline, relocation gate, verify golden
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:characterizationrecord --project <root> --module <Name> [--out <path>] [--files <manifest.json>] | verify --project <root> --golden <path> [--json <out>] [--files <manifest.json>]characterization
Section titled “characterization”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.
The two commands
Section titled “The two commands”# 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.
Preconditions
Section titled “Preconditions”| Check | Why |
|---|---|
<project>/assets/ exists | The 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 installed | Both 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 files | Ambiguous or missing resolves to a usage error, never a guess (findModuleDir, resolveExplicitFiles) |
How discovery works
Section titled “How discovery works”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:
--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 nomodules/<Name>/scaffold at all — see “Why explicit mode exists” below. Tier reported:explicit.--filesabsent → scaffold mode (unchanged from V1).- Find the module directory — a directory named
<Module>(case-insensitive) whose parent is literallymodules/. Zero or more-than-one match is an error, never a silent pick (findModuleDir). - 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 importingccis expected). No files in any tier is a hard error (no-entry-points-found), never an empty golden.
- Find the module directory — a directory named
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.
Why explicit mode exists
Section titled “Why explicit mode exists”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:
| Reason | Fires when | What it means |
|---|---|---|
cc-coupled | The 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 import | This 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-class | A 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-type | An 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 method | The type is real but this synthesizer has no case for it |
no-operations | A class was found and its constructor resolved, but it exposes no candidate method | Nothing 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:
- 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. - The mocked surface is the engine and presentation collaborators only — never the subject’s own decision logic, which must execute for real.
- 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.
- It lands in the module’s
.tests/directory beside the source (.tests/x.golden.test.ts), not in the recorder’stests/__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.
Determinism — the whole product
Section titled “Determinism — the whole product”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.
Reading a golden / a verify report
Section titled “Reading a golden / a verify report”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:
| status | meaning |
|---|---|
identical | The row replayed byte-for-byte |
divergent | The row replayed to a DIFFERENT output/threw — a real behaviour change |
missing | The 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.
Executed by
Section titled “Executed by”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”.
| Step | Agent |
|---|---|
Run record-baseline.cjs and verify-golden.cjs and relay the verdict and diff counts verbatim | t1k-cocos-base-tester |
| Decide whether a golden diff is a regression or an intended change | t1k-cocos-base-debugger — reasoning tier |
Scope — what V1 does not attempt
Section titled “Scope — what V1 does not attempt”- 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).
Related
Section titled “Related”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 assumestheonekit-core/.claude/modules/t1k-engineering/rules/ai-driven-design.md— why both scripts emit facts only, never a verdict