t1k:verify-wiring
| Field | Value |
|---|---|
| Module | t1k-base |
| Version | 5.15.36 |
| Effort | low |
| Tools | — |
Keywords: claimed, consumer scope, green, hook, installed, module claim, no effect, not running, packaging, registered, shared, silent, unregistered, verify, wiring
How to invoke
Section titled “How to invoke”/t1k:verify-wiring[hook-name | script-name | check-name]Verify Wiring — Prove It Runs, Not That It Exists
Section titled “Verify Wiring — Prove It Runs, Not That It Exists”A hook that is present but unregistered does nothing, reports nothing, and fails
nothing. So does a script no manifest claims, and a check that asserts a path the
runtime never loads. And a lib claimed by an opt-in module is a live wire into a
dead socket for every required: true consumer that require()s it — it ships
to the wrong audience, silently. Each looks installed. Each is silent.
This skill turns “it should be working” into evidence either way.
When to use
Section titled “When to use”- After adding a hook, script, or gate — before calling it done
- After re-homing or re-claiming a hook/script across modules — the audience changed
- A feature “is installed” but has no observable effect
- A health check reports green and you cannot name what it would catch
- A cross-tree
require()smells wrong (skill script → hooks lib) — check the claim - Before concluding a fix reached other machines (it usually has not)
Step 1 — Present: at the path the RUNTIME reads
Section titled “Step 1 — Present: at the path the RUNTIME reads”The repo copy and the loaded copy are different files. Check the loaded one.
NAME="${1:?hook or script name}"for p in "$HOME/.claude/hooks/$NAME.cjs" "$HOME/.claude/scripts/$NAME"* \ "$PWD/.claude/hooks/$NAME.cjs" "$PWD/.claude/scripts/$NAME"*; do [ -e "$p" ] && echo "present: $p"doneGlobal vs project matters. Registrations built with os.userInfo().homedir
load the GLOBAL copy — a repo-local file satisfies no such registration. If only
the repo copy exists, routing/telemetry/whatever it drives is off.
Step 2 — Wired: something invokes it
Section titled “Step 2 — Wired: something invokes it”# Hooks — registered, and on the right event?jq -r '.hooks | to_entries[] | .key as $ev | .value[] | select((.hooks[]?.command? // "") | test(env.NAME)) | "\($ev) matcher=\(.matcher)"' ~/.claude/settings.json
# Scripts — claimed by a module, or it never shipsgrep -rn "$NAME" .claude/modules/*/module.jsonEmpty output = the file is inert. That is a FAIL, not a warning: a silent component in an otherwise-green report is scrolled past, which is how one such hook survived across nine machines.
Step 3 — Claimed correctly: it reaches exactly the consumers who need it
Section titled “Step 3 — Claimed correctly: it reaches exactly the consumers who need it”Present + wired still does not prove the right audience. Hooks ship by default
in the shared ZIP (build-shared-zip.cjs copyHooksTree); a files.hooks[]
claim in modules/<name>/module.json moves a file OUT of the shared ZIP into
that module’s ZIP; sharedAlso[] claims AND keeps it shared. So
| Resolution | Meaning |
|---|---|
grep -n "<file>" .claude/modules/*/module.json → NO hit | SHARED — every consumer |
files.hooks[] (or files.scripts[]) claim | that module’s consumers ONLY |
sharedAlso[] claim | claimed AND still shared |
Consumer-scope rule — the lesson: find consumers by grepping the WHOLE
.claude/ tree, NEVER hooks/ alone. A lib claimed by a hooks module can be
consumed by a SKILL script (t1k-preview/scripts/refresh-orchestrator.cjs
require()ing lib/process-lock.cjs is the incident: consumed by a
required: true module, claimed by an opt-in module, every fresh install
MODULE_NOT_FOUND on /t1k:preview).
grep -rn "NAME" .claude/skills .claude/agents .claude/hooks .claude/modules # the whole treeThe invariant: if a file is required by a module with required: true, it
MUST be SHARED or in a sharedAlso[]. A required module may never hard-depend on
an opt-in module’s claimed file.
Guarded vs unguarded: a try/existsSync-wrapped require degrades at load;
a top-level destructuring require(path.resolve(...)) crashes the consumer at
load. Only the second is critical.
Step 4 — Runs: produce evidence
Section titled “Step 4 — Runs: produce evidence”Presence + registration still is not proof. Force the path and look:
# A hook: trigger its event, then check for its tracels -la ~/.model-router/*.jsonl ~/.claude/telemetry/*.jsonl 2>/dev/null | tail -3
# A check: break it deliberately and confirm it goes REDcp <target> /tmp/t1k-wiring-backup && rm <target>bash <the-check> # must FAIL herecp /tmp/t1k-wiring-backup <target>A check never observed failing is unproven. Prefer pinning the FAILURE states.
Step 5 — Fleet: your machine is not the population
Section titled “Step 5 — Fleet: your machine is not the population”The most expensive version of this bug is per-machine. A component wired on your box says nothing about anyone else’s, and config that ships “copy if absent” freezes at install time.
- Is there a fleet-visible signal (telemetry table, dashboard) confirming it runs elsewhere? Local JSONL cannot answer this.
- If the fix is config the kit owns, does it propagate on update, or only on first install?
Report
Section titled “Report”present: <path the runtime loads> | MISSINGregistered: <event> matcher=<m> | NOT REGISTEREDclaim: SHARED | module.<name> | sharedAlso | UNCLAIMEDconsumer: <whole-tree grep result> | <paths searched>evidence: <trace/log/row observed> | nonefleet: <how other machines are known> | unknown — local onlyState unknown plainly. An unverified wiring reported as working is the failure
this skill exists to prevent.
Related
Section titled “Related”rules/wired-not-just-present.md— the rule this operationalisesrules/green-that-proves-nothing.md— why the check itself needs checkingrules/negative-result-scope.md— state the paths you actually searched for consumerst1k:doctor— registry-wide validationagents/t1k-hooks-manager.md— the agent that owns hook authoring + claim placement