Skip to content
T1KTheOneKit

wired-not-just-present

Wired, Not Just Present — A File That Exists May Still Never Run

Section titled “Wired, Not Just Present — A File That Exists May Still Never Run”

Rule

Section titled “Rule”

Shipping a hook, script, or config file is half the change. Until something loads it, it does nothing — and nothing says so. Whenever you add or verify one, check BOTH facts separately:

  1. Present — the file exists at the path the runtime actually reads.
  2. Wired — a registration, manifest entry, or caller invokes it.

A check that only proves (1) reports green on an install where (2) is missing. Verify the wired half by naming its consumer: which settings.json entry, which module.json list, which caller.

Why this matters: three same-day 2026-08-14 incidents all reported healthy because the check asserted presence, never wiring. Full incident table: docs/wired-not-just-present.md.

How to apply

Section titled “How to apply”
  • Adding a hook → also add its settings.json registration, and assert the matcher covers the event you need (Task|Agent, Bash, …).
  • Adding a script → also add it to the owning module.json. An unclaimed script does not ship (validate-all-shippable-claimed catches this).
  • Writing a doctor/health check → assert the path the RUNTIME loads, not the copy that happens to be in the repo. If those differ, check both and say which is which.
  • A broken wiring is FAIL, not WARN. A warning in a thirty-line green report is scrolled past; that is how the interceptor case survived nine machines.
  • Config the kit owns must propagate on update, not only on first install. “Copy if absent” freezes kit-owned facts at install time.
  • A registered matcher can still be structurally blind (#1383) — PostToolUse/Edit|Write|MultiEdit never fires for a Bash-based write (sed, heredoc, python3), which bypass-permissions mode actively steers a session toward. A matcher naming a closed tool set cannot be extended to cover every future write path; prefer a tool-agnostic end-of-turn/session sweep (e.g. sync-back-rollup.cjs’s git status sweep) as the net underneath it. Full incident: docs/wired-not-just-present.md.
Section titled “Related”
  • kit-wide-fix-discipline.md — fix at the kit source so the wiring reaches everyone
  • prefer-local-over-global-edits.md — which copy is canonical
  • green-that-proves-nothing.md — the broader failure this is one instance of
  • docs/wired-not-just-present.md — the full incident table and the interceptor case in detail