t1k:playablelabs:base:params-audit
| Field | Value |
|---|---|
| Module | base |
| Version | 2.29.2 |
| Effort | medium |
| Tools | — |
Keywords: dead param, dirty set, LOGIC-DEAD, param audit, param cache, parameter audit web, params audit incremental, playthrough, UNWIRED, visual gate
How to invoke
Section titled “How to invoke”/t1k:playablelabs:base:params-audit[--root <dir>] [--adapter <path>] [--full] [--no-runtime] [--runtime-results <file>] [--json] [--no-write] [--check] [--explain <key>]Incremental Param Audit (engine-neutral core, contract v1.3)
Section titled “Incremental Param Audit (engine-neutral core, contract v1.3)”Finds parameters declared but never reaching the game (UNWIRED, NO-OP, LOGIC-DEAD, NULL-REF), then plays every visually
testable one and checks the target’s region really changes, re-doing only what a change could have affected. An adapter holds the
engine specifics; this skill owns scan, cache, dirty set, status, report, receipt, exit code. Spec (binding):
references/cache-contract.md; change the contract first, never this file alone.
What a run does
Section titled “What a run does”- Scans every source file once (token counts, declaration index), classifies each LIVE key from
.param-audit/probe.json. - Computes the dirty set, calls
adapter.auditParamsfor dirty keys only, carries the rest fromcache.json. - Playthrough (default-on): each visual key’s
closureHashcarries a valid result fromstatus.json; the rest go toruntime.needed, the adapter’s probe plays them and writesprobe-results.json. - Committed:
status.json, plusprobe.json(hand-authored or scaffolded by the probe’s--init). Local, ignored:cache.json,report.json,probe-results.json,local/shots/(the core writes.param-audit/.gitignoreonce, never rewrites it).
bun <skill>/scripts/param-audit.cjs --root <game> [--adapter <adapter.cjs>] (no --adapter: the one installed adapter that detects the root, else an error).
| flag | meaning |
|---|---|
--full | ignore the cache (reason forced), carry no runtime result |
--no-runtime | opt out of the playthrough: receipt not-run, verdict UNKNOWN, never PASS; stored results kept |
--runtime / --runtime-results <file> | deprecated no-op (default-on; note on stderr) / stamp a probe’s rows with each key’s current closureHash, conflicts with --no-runtime |
--check | exit 1 if the cache or the committed status.json is stale; never writes; CI runs this |
--json / --no-write | machine output (dirty keys carry explain) / write nothing |
--explain <key> | print why the key is dirty: reasons, the shortest declaration chain to each changed declaration, hub counts that moved |
Exit 0 ran, no DEAD param, no runtime FAIL; 1 DEAD, runtime FAIL, or --check stale; 2 could not run (adapter threw,
unreadable probe.json, conflicting flags), nothing written.
Classification and verdict
Section titled “Classification and verdict”Every LIVE key in probe.json is visual ({key, values >= 2 distinct, stateExpr, region}), not-visual ({key, visual:false, reason}, reason audio | sdk | store-link | logic-only | other:<text>) or unclassified (unprobed). A run
never applies suggestVisual. The visual gate (scripts/lib/visual-gate.cjs) diffs only the target’s own region against
two control shots: VISIBLE | NOT-VISIBLE | UNVERIFIABLE-visual; noisy controls are UNVERIFIABLE-visual, never NOT-VISIBLE.
A VISIBLE change must also clear the perceptibility floor minMeanDelta (default 4 of 255, a margin override).
| input | counts as |
|---|---|
| visual key, gate PASS | probed, pass |
APPLIED-OK-NOT-VISIBLE, NO-EFFECT, WRONG-TARGET | probed, failed |
UNVERIFIABLE, UNVERIFIABLE-visual, no result, unclassified | unprobed, never carried |
| not-visual | exempt (counted, listed) |
Receipt fail if any failed; unknown if anything is unprobed or the probe ran --no-visual; clean otherwise; not-run under
--no-runtime. Verdict FAIL on a DEAD param or runtime fail; PASS only with no DEAD, no UNKNOWN param and a clean receipt.
Dirty means related
Section titled “Dirty means related”A key is re-audited when its definition, read spans, a tracked token count, OR any declaration it flows through changed: editing
hpHandler in applyHp -> setHp -> hpHandler dirties exactly Hp (reason reach), static and playthrough together. Reach
follows names from the read spans (3 hops) plus the readers of the field the key writes; comments, whitespace and JSON/CSS never
dirty. Real 81-param game: a SfxVolume default or apply edit audits 1, the setSfxVolume sink body 4, a config comment 0.
Honest limits
Section titled “Honest limits”String-keyed dispatch and reflection are invisible to the graph (--full forces). Name collisions over-dirty, never under-dirty.
A hub identifier (declared by more than 8 or mentioned by more than 60 declarations) is never expanded, so flow through a generic
hub name is invisible. A require/import is followed only through names the code mentions; code without semicolons merges
statements. Identical frames read NOT-VISIBLE (no capture-degenerate verdict). A tracked token in a comment dirties its keys.
Adding an adapter
Section titled “Adding an adapter”Export { id, version, detect, listParams, readSpans, auditParams } (optional scan, runtimeSpans, suggestVisual; contract
section 3). readSpans returns text found verbatim; auditParams lists in reads.tokens every identifier whose occurrence
count the verdict used. Prove it: copy tests/fixtures/toy-adapter.cjs, run the differential suite, make the
toy-adapter-broken-*.cjs stubs go red against yours. Probe, region resolution and probe.json scaffold stay in the adapter’s skill.
Executed by
Section titled “Executed by”The mechanical steps (running scripts/param-audit.cjs and its selftests, and reading the audit status it writes) are run by the cheap-tier t1k-tester agent. The verdict and any dirty-set decision stay with the calling agent.
Related
Section titled “Related”t1k-playablelabs-base-params is the runtime and WEB publish side; t1k-cocos-playable-parameter-audit the heavy Cocos-only audit.
Tests: bun test <skill>/tests/*.test.cjs; a new check is not done until it has gone red on a broken core.