Skip to content

t1k:verify-wiring

FieldValue
Modulet1k-base
Version5.15.36
Effortlow
Tools—

Keywords: claimed, consumer scope, green, hook, installed, module claim, no effect, not running, packaging, registered, shared, silent, unregistered, verify, wiring

/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.

  • 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.

Terminal window
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"
done

Global 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.

Terminal window
# 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 ships
grep -rn "$NAME" .claude/modules/*/module.json

Empty 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

ResolutionMeaning
grep -n "<file>" .claude/modules/*/module.json → NO hitSHARED — every consumer
files.hooks[] (or files.scripts[]) claimthat module’s consumers ONLY
sharedAlso[] claimclaimed 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).

Terminal window
grep -rn "NAME" .claude/skills .claude/agents .claude/hooks .claude/modules # the whole tree

The 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.

Presence + registration still is not proof. Force the path and look:

Terminal window
# A hook: trigger its event, then check for its trace
ls -la ~/.model-router/*.jsonl ~/.claude/telemetry/*.jsonl 2>/dev/null | tail -3
# A check: break it deliberately and confirm it goes RED
cp <target> /tmp/t1k-wiring-backup && rm <target>
bash <the-check> # must FAIL here
cp /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?
present: <path the runtime loads> | MISSING
registered: <event> matcher=<m> | NOT REGISTERED
claim: SHARED | module.<name> | sharedAlso | UNCLAIMED
consumer: <whole-tree grep result> | <paths searched>
evidence: <trace/log/row observed> | none
fleet: <how other machines are known> | unknown — local only

State unknown plainly. An unverified wiring reported as working is the failure this skill exists to prevent.

  • rules/wired-not-just-present.md — the rule this operationalises
  • rules/green-that-proves-nothing.md — why the check itself needs checking
  • rules/negative-result-scope.md — state the paths you actually searched for consumers
  • t1k:doctor — registry-wide validation
  • agents/t1k-hooks-manager.md — the agent that owns hook authoring + claim placement