@tech-leads-club/harness-toolkit 0.2.1

package/docs/decisions/ad-028.md

@@ -0,0 +1,90 @@
+---
+type: Decision
+title: "AD-028 — A resolved failure is kept, a session attests to itself, and provider neutrality becomes a proof"
+description: "The harness deleted the pairing of a failure with what resolved it at the exact moment the gate went green. A reviewer asked to trust agent-written code had nothing to read, while the harness held every input. And the central promise of provider neutrality was asserted by goldens covering one decision kind out of seven."
+tags: [decision, stagnation, attestation, providers, recovery]
+timestamp: "2026-08-04"
+---
+
+# AD-028 — Keep what resolved it, attest to what ran, prove the neutrality
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **When a gate passes after failing, the files changed between those states are recorded against the failure's
+   fingerprint.** Captured immediately before the fingerprint record is cleared — the one moment both halves exist.
+2. **On recurrence the follow-up cites that history in one line, in the past tense, saying it is not a list to
+   edit.** A test asserts no imperative survives in the wording.
+3. **The store is bounded** at 200 resolutions and 8 files each, pruning the oldest, because it is read on the
+   failure path while an operator waits.
+4. **Scope is the repository.** A resolution from elsewhere is not offered.
+5. **A session appends a hash-chained attestation**: policy fingerprint, whether policy diverged mid-session, the
+   rails that were active, refusals by rule, and gate outcomes. `tlc harness attest [--json]` reads and verifies
+   it, exiting non-zero on a broken chain.
+6. **Verification reports the index at which the chain broke**, and an absent file is an empty valid chain rather
+   than a broken one.
+7. **The attestation states only what the harness observed.** No claim of correctness, of review, or of human
+   approval.
+8. **Provider neutrality is asserted across the full matrix** — every event kind × every decision kind × every
+   registered provider — driven from the registry so a new provider is covered without editing the test.
+
+## Why
+
+**The harness destroyed its most valuable output at the moment it became true.** It computes an identity for a
+failure and counts repeats to detect stagnation; on success it called `clearFingerprint`, which wiped the record.
+The pairing of *that failure* with *what resolved it* is the one thing nothing else can assemble, because nothing
+else holds a failure fingerprint and the diff in the same process. Products that "learn" from failures store prose;
+this stores evidence.
+
+It also addresses the failure mode that matters most in long work: an agent that commits a wrong intermediate state
+deep in a trajectory, where the error propagates because nothing detects or reverts it. A repeated fingerprint is
+precisely that situation announcing itself, and the harness now has something to say about it beyond "you are
+stuck".
+
+**The wording is the whole safeguard.** AD-021 recorded the harm of sending an agent to edit healthy code because a
+gate command was malformed; AD-024 recorded the same harm arriving through the diff, and established that a plan
+names files from evidence and never from proximity. A previous resolution is evidence — but the same list phrased
+as an instruction would be that harm arriving through a third door. Hence past tense, hence the explicit "not a
+list to edit", hence a test that fails on an imperative.
+
+**A reviewer had nothing to read.** Everything needed to trust an agent-produced change was already in the
+harness — which policy was in force, whether it moved mid-session, every refusal with its rule, every gate
+outcome — and none of it left the machine in a form anyone could check. Governance treated as prompting produces
+no artifact; governance treated as record-keeping does.
+
+**And the neutrality claim was thinner than it looked.** `provider.contract.test.ts` asserted the port shape and
+that render survived `abstain`. Six of the seven decision kinds and eighteen of the nineteen event kinds went
+unexercised per provider. A provider that throws on one of those combinations breaks a real turn in production, and
+the test suite would have said nothing.
+
+## Trade-offs
+
+Hash chaining is not signing, and the record says so by omission: it detects a rewritten or removed middle record,
+which is what an on-disk ledger is exposed to, and it does not prove authorship. A key would prove more and would
+mean key management, a different problem with its own failure modes. If authorship becomes the requirement, that is
+a separate decision.
+
+Repository-scoped resolution history is narrower than it could be. The global spool could carry these across
+repositories, and a fix that worked in another codebase is exactly the kind of advice that reads plausible and is
+wrong. Narrow first.
+
+The resolution cache pairs a fingerprint with *everything that changed*, which on a wide turn includes files that
+had nothing to do with the fix. The file cap bounds the noise and the wording refuses to assert causation — it says
+what changed, not what fixed it. That is the honest limit of what the data supports.
+
+The conformance matrix runs 266 combinations and will grow with every event kind and provider. It is cheap because
+render is pure, and the test asserts the number of combinations it ran: a loop over an empty registry passes
+silently, which is the way this kind of test rots.
+
+## Not decided here
+
+- **Signed attestation** and any notion of identity. Hash chaining is the tamper evidence; authorship is not
+  claimed.
+- **Cross-repository resolution history.** The mechanism exists in the global spool; the advice is dangerous enough
+  to want data first.
+- **Whether the attestation should be emitted on stop rather than session end.** Session end has the complete
+  rollup; a crash before it leaves no record, which is a gap this accepts.
+- **Asserting that two providers produce byte-identical output.** They cannot — each speaks its own dialect. The
+  matrix asserts the decision survives and its meaning is preserved, which is the property that matters.

package/docs/decisions/ad-029.md

@@ -0,0 +1,73 @@
+---
+type: Decision
+title: "AD-029 — A capability the init skill cannot correctly initialise is not shipped"
+description: "Observation mode shipped with one observable rail, a catalog prompt that named none of them, and silent inertness for any other name — so the init skill would present it, collect a value that does nothing, and report success. The observable set now has one source, the prompt names it, and doctor refuses to be silent about a name with no checker."
+tags: [decision, capability, init, observability, doctor]
+timestamp: "2026-08-04"
+---
+
+# AD-029 — A capability the init skill cannot correctly initialise is not shipped
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **`OBSERVABLE_RAILS` is the single source of what can be observed**, read by the classifier, by `doctor`, and by
+   the capability catalog's own prompt.
+2. **A name enters that list in the same change that adds its `shouldObserve` call site.** A name listed without a
+   call site would advertise an observation that never happens.
+3. **`shouldObserve` refuses a rail it cannot observe**, even when the operator listed it, so the function's
+   contract matches what the harness can actually do.
+4. **`doctor` reports an unobservable rail by name**, alongside the set that is observable. Observation enabled with
+   an empty list is also a warning, because that is the shape a "yes" with no follow-up produces.
+5. **The catalog's `asks` names the valid values and states the consequence of a wrong one**, so the init skill
+   collects something real rather than inventing a plausible name.
+6. **Both are warnings, not failures.** A misconfigured measurement rail is a config fault to fix, not a broken
+   install, and failing here would block the command an operator runs to find out what is wrong.
+
+## Why
+
+Observation mode shipped one revision ago with three properties that only make sense separately. Exactly one rail
+has a checker wired to it (`comments`). The catalog asked the operator for "rails (rail names to observe)" without
+naming any. And a name with no checker was **silently inert** — inertness was deliberate, for forward compatibility,
+and the silence was not thought about at all.
+
+Put together, the failure is specific and bad: the init skill presents the capability, the operator says yes, a
+plausible name like `plan-gate` gets written, and nothing is ever recorded. The operator then reads that silence as
+*the property always holds*, which is the worst available misreading of a rail whose entire purpose is to tell them
+whether a rule is needed. A measurement that reads as a clean result when it never ran is worse than no measurement.
+
+This is the AD-020 family again — a config value nothing reads — and it arrived through a route the previous
+instances did not: not a field with no producer, but a field whose *values* have no producer. The check that caught
+it was the question "can the init skill actually initialise this?", which is worth asking of every capability rather
+than of this one.
+
+The general rule this establishes: **a capability is not finished when its code works. It is finished when the
+surface that offers it can offer it correctly.** The init skill, `doctor` and the catalog prompt are part of the
+capability, not documentation of it.
+
+## Trade-offs
+
+Forward-compatible inertness is kept — an unknown name does not throw, so a config written for a future version of
+the harness still loads. What changed is that inertness is now reported. Refusing to load would be the other
+defensible choice and it would break the forward compatibility this project has elsewhere; reporting keeps both.
+
+`OBSERVABLE_RAILS` is a hand-maintained list, which is a small duplication against the call sites. Deriving it
+mechanically would mean either a registry the call sites enrol in — more machinery than one entry justifies — or
+scanning source at runtime, which the latency budget forbids. The invariant is stated in a comment and asserted by a
+test that pins the list, so adding a rail without its call site fails.
+
+One rail is a thin start, and naming it explicitly makes that thinness visible in the catalog rather than implied.
+That is the point: an operator reading "observable today: comments" knows the shape of what they are buying, and an
+operator reading "rail names to observe" does not.
+
+## Not decided here
+
+- **Observing the plan gate or the ship gate.** Both have deterministic checkers and would be genuine additions.
+  Each needs its own call site and its own entry in the list, in a change that adds both together.
+- **Deriving the observable set from the call sites mechanically.** Worth revisiting if the list reaches a size
+  where hand-maintenance is a real risk.
+- **Whether the init skill should refuse to write an unobservable name.** Today it can write one and `doctor` will
+  say so. Validating at write time is stricter and would need `init` to validate fields generally, which it does not
+  do for any other value.

package/docs/decisions/ad-030.md

@@ -0,0 +1,97 @@
+---
+type: Decision
+title: "AD-030 — Clearing a policy divergence is one operator command behind four independent locks, and a refusal never points an agent at a door the floor holds shut"
+description: "The integrity check locked two live sessions out because its recovery path named no command, pointed the agent at commands the floor refuses, and did not exist as a side-effect-free operation. `tlc harness policy accept` is that operation, kept out of an agent's reach by four locks that fail independently, recorded rather than erased — and a sweep now fails the build when an agent-facing refusal instructs a command the agent cannot run."
+tags: [decision, policy, integrity, security, cli]
+timestamp: "2026-08-04"
+---
+
+# AD-030 — One operator command, four locks, and a refusal that knows its audience
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **`tlc harness policy` lists every source that changed out of band during a live session and changes nothing.**
+2. **`tlc harness policy accept <path>...` updates the baseline entry for exactly the named paths**, in every live
+   session's baseline.
+3. **Four independent locks sit between that command and an agent**, no one of them load-bearing alone:
+   - the floor refuses `tlc harness policy` from inside any agent session, with no config switch;
+   - the command refuses without an interactive terminal, so a script cannot reach it;
+   - the operator names each path, so accepting is an act rather than a keystroke and its blast radius is exactly
+     what was typed;
+   - acceptance is per source, so every other divergence keeps blocking.
+4. **No blanket permission is expressible.** The accepted hash is the hash at that moment; a later change to the
+   same file diverges again. There is deliberately no way to stop watching a source.
+5. **A path the loader never reads is refused**, naming the sources that exist.
+6. **`reason` is the agent's half of a refusal and `userNote` is the operator's.** An agent-facing refusal states
+   what happened and says to report it; the command that clears it lives in the operator's half.
+7. **A sweep over every refusal producer fails the build** when a `reason` instructs a mutating harness subcommand.
+8. **`doctor` reports a divergence, naming the paths and the command**, and is silent when there is none.
+
+## Why
+
+The integrity check has now blocked two live sessions: its own author, and a colleague's agent after an operator
+edited `config.json` from their terminal. The check behaved correctly both times — a mid-session policy change with
+no harness command behind it is precisely what it exists to catch. The recovery path is what failed, in four
+measurable ways.
+
+**It named no command.** The refusal said "the harness commands re-record the baseline when they write". Only
+`grind`, `pause|resume`, `mode` and `gate` do. `status` and `doctor` do not — and `status` is exactly what a
+reasonable reader tries first, because it sounds like the command that reports state. The blocked agent tried it,
+learned nothing, and stopped.
+
+**It pointed the agent at a door the floor holds shut.** Every command that would have worked is in
+`MUTATING_SUBCOMMANDS`, refused from inside a session by design. So the instruction was not merely unhelpful; it was
+addressed to the one party that cannot act on it. This is the third instance of that defect: the policy-surface
+guard had it and was fixed under AD-026, the integrity check had it here, and the sweep built for this decision
+found a third in the `paired` shell ask on its first run. Three instances is not carelessness about wording — it is
+a missing invariant, which is why the sweep exists.
+
+**No side-effect-free operation existed.** Every route that repairs a baseline also writes something: `mode` writes
+a state file that then outranks config, `grind` writes a flag that outranks it too. An operator fixing a lockout
+would silently acquire a latent surprise for the next time they edited config.
+
+**And `doctor` was silent.** The one command an operator runs to find out what is wrong said nothing about the thing
+blocking every acting tool call.
+
+The design question that matters is not "add an accept command" but **"what keeps an accept command out of reach of
+the thing it defends against?"** A command that clears a tampering signal is the first thing an attacker wants, and
+one lock is one bug away from nothing. Hence four, at different layers, testable separately: a floor rule that no
+config can weaken, a TTY requirement that stops scripts, an explicit naming that cannot happen by accident, and
+per-source scope that limits what a single accept can bless.
+
+## Trade-offs
+
+**Accept is recorded, not silent.** Without that it would be a memory hole: the rail's own history could be erased
+by the command meant to resolve it. Recorded, it is an operator decision a later reviewer can see, which is the
+difference between a sanctioned override and a bypass.
+
+**Naming the path instead of prompting.** A y/N prompt is the obvious alternative and it is worse twice over: a
+prompt is a keystroke, and keystrokes become reflex — the finding AD-026 acted on — and a prompt cannot be tested
+without a pty, on a rail whose failure mode is silence. Typing the path is slower on purpose.
+
+**Per-source acceptance required new machinery.** `refreshPolicyBaselines` rewrites the whole fingerprint, which is
+right for a sanctioned mutation that changed one thing and wrong here: it would bless every other pending change
+alongside the one named. `acceptPolicySources` writes one entry at a time and leaves the rest untouched.
+
+**The sweep is a line-scoped scan, not an AST walk.** It reads the `reason:` property and the continuation lines of
+its array literal, which is the shape every refusal in this codebase uses, and skips comments. It asserts how many
+reason strings it scanned, because a scan that parses nothing passes forever. A refusal built in some other shape
+would escape it — the test says so rather than implying completeness.
+
+**Social engineering is not solved.** An agent cannot run accept, and nothing stops it from writing a message that
+persuades an operator to. The mitigation is that accept prints the path, so the operator sees what they are being
+asked to bless. Stated here rather than pretended away.
+
+## Not decided here
+
+- **Whether a read should ever refresh a baseline.** It should not, and this decision does not revisit it: a
+  tampering signal cleared as a side effect of looking is not a signal.
+- **Recording the acceptance in a dedicated ledger.** The attestation carries `policyDiverged` for the session; a
+  per-acceptance audit row would be finer and needs its own decision about retention.
+- **Refusing to load a config whose divergence was never accepted.** The current design blocks acting tool calls and
+  allows reads ([/decisions/ad-025.md](/decisions/ad-025.md)), which is what lets a blocked agent explain the situation. Failing closed would remove that.
+- **Extending the sweep to `userNote`, `text` and `detail` strings.** Only `reason` is agent-facing today. The others
+  reach the operator, where naming a command is correct.

package/docs/decisions/ad-031.md

@@ -0,0 +1,94 @@
+---
+type: Decision
+title: "AD-031 — The decisions are the changelog, a breaking change carries its own instruction, and looking never changes anything"
+description: "Update did the mechanical work well and could not say what changed: no version identity, no mapping from a revision to the decisions that landed, and no channel for a breaking change at the moment of impact — three shipped in one week and only doctor mentioned them afterwards. The revision is the version, a migration note lives in the decision that caused it, and `update --check` fetches without merging."
+tags: [decision, release, update, changelog, cli]
+timestamp: "2026-08-04"
+---
+
+# AD-031 — The decisions are the changelog
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **The runtime's git revision and commit date are the version.** `tlc harness version` reports them, plus the
+   revision this project last saw.
+2. **A breaking change carries a `migration` note in the frontmatter of the decision that caused it.** Optional;
+   validated as non-empty when present.
+3. **`migration` marks a decision as needing operator action.** Amended by
+   [/decisions/ad-034.md](/decisions/ad-034.md): a note belongs only where `doctor` cannot detect the condition for
+   the operator. Five of the first six notes repeated a doctor row and were removed.
+4. **`tlc harness update --check` fetches and never merges**, reporting the pending commit count and the decisions
+   that would land, with the ones needing action first and their notes shown.
+5. **After an update, decisions added between the seen revision and the new one are announced once.** A project with
+   no marker records where it stands and announces nothing.
+6. **A fast-forward failure names both routes out** — reset to upstream, or re-run the installer — gives the command
+   for the first, and runs neither.
+7. **There is no hand-written changelog and no semantic version.**
+
+## Why
+
+`update` already did the mechanical work well: fetch, fast-forward, relink the CLI and skill, rewrite hooks, rebuild
+`dist/`, announce newly available capabilities, run `doctor`. One command ending in a health check. What it could not
+do was tell the operator what changed, for reasons that compound.
+
+**There was no version identity.** `package.json` has said `0.1.0` since the first commit — which is exactly what a
+hand-maintained number does — with no tags and no releases, and `tlc harness version` answered `unknown: version`.
+Without an identity, "what changed since mine?" is not a hard question, it is an unanswerable one.
+
+**The substance of a changelog already existed and was unreachable.** Thirty decision records carry why, the
+trade-offs and what was refused, which is more than most changelogs contain. What was missing was the mapping from
+*I updated* to *these landed*. Writing a `CHANGELOG.md` would have restated them and then drifted from them; reading
+them needs no second source to maintain.
+
+**A breaking change had no channel at the moment of impact, and three shipped in one week.** AD-025 removed a
+posture's second spelling, so a config carrying it falls back silently at load. AD-029 made an unobservable rail name
+reportable, which means a config naming one had been recording nothing. AD-027 is the sharpest: ordering evidence
+against the code can newly **block a stop that previously passed**. `doctor` reports all three afterwards — that is
+the safety net working — but the operator was standing in front of `update` when the change happened, and it said
+nothing.
+
+The mechanism was already in the codebase and pointed at the wrong subject. `announceNewCapabilities` reads a
+per-project seen marker, lists only what is new *to that project*, prints benefit and trade-off, and never repeats.
+That is a changelog delivered at the moment of impact. Applying the same shape to decisions is the whole feature.
+
+## Trade-offs
+
+**No semantic version.** A version number is a promise about compatibility, and AD-003 refuses back-compat shims —
+so the promise cannot be kept and stating it would be a lie with a dot in it. The revision is honest, moves with the
+thing it names, and is what `update` already manipulates. Tags become worth adding when the compatibility promise
+becomes real.
+
+**`migration` is optional, which means it can be forgotten.** Requiring it on every decision would produce "no
+migration needed" on the large majority and train a reader to skip the field. The bundle check catches the halfway
+state — present and empty — because a decision announced as needing action that then shows nothing is worse than one
+that never claimed it. Forgetting it entirely is still possible, and `doctor` remains the net.
+
+**A first update announces nothing.** A project with no seen marker could be shown every decision ever written, and
+thirty entries is indistinguishable from no message. It records where it stands instead. The cost is that an operator
+installing today learns nothing about the past from this rail — which is what `docs/decisions/index.md` is for.
+
+**The digest reads decisions added in a range**, so a decision *amended* after landing is not re-announced. That is
+deliberate: an amendment is usually a wording fix, and re-announcing on every edit is how the capability digest would
+have become noise too.
+
+**The three retroactive notes were written after the fact**, by the author of the changes they describe. That is the
+weakest part of this: they are as good as the memory of the week they cover. Notes written at the time of the change
+are the standard from here.
+
+**Amended the day after by AD-034.** Five of the six notes then in the tree said, in substance, "run
+`tlc harness doctor`" — which `update` runs automatically three lines later, and which reports whether the condition
+applies at all. The mechanism was right and the content was noise, so `migration` now means specifically "something
+doctor cannot detect for you".
+
+## Not decided here
+
+- **Tags and releases.** Worth adding when there is a compatibility promise to attach to them.
+- **Announcing on session start rather than on update.** The information belongs where the change happens, and a
+  hook that reports it every session is a cost on every session.
+- **Checking for updates in the background.** A scheduled phone-home is a permanent cost for information the operator
+  can ask for in one command.
+- **Migration notes that the harness applies.** `config.json` is a protected surface and policy is the operator's
+  ([/decisions/ad-022.md](/decisions/ad-022.md)). A note says what to run; running it is not the harness's call.

package/docs/decisions/ad-032.md

@@ -0,0 +1,83 @@
+---
+type: Decision
+title: "AD-032 — A hook is healthy when it can run, not when a marker string is present"
+description: "A colleague's session was blocked by a preToolUse hook whose command was a bare executable, so Node read the hook payload as a program. The harness could not have written that command — but its health check could not have caught it either, because it decided wiring health by looking for one string. Health is now per event: our launcher named, the script present, a handler after it."
+tags: [decision, providers, wiring, doctor, diagnosis]
+timestamp: "2026-08-04"
+---
+
+# AD-032 — A hook is healthy when it can run
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **Wiring health is checked per declared event**: an entry must name the expected launcher, that file must exist,
+   and a handler token must follow it.
+2. **Only the events this provider declares are inspected**, and within them only entries whose command names our
+   launcher. A hook belonging to another tool is never reported.
+3. **A declared event with no harness entry is a problem**, which is the case marker presence cannot see.
+4. **Marker presence keeps its job unchanged** — deciding whether the file is ours, and therefore whether `update`
+   may overwrite it. Two questions, two checks.
+5. **`doctor` names the failing event and the reason**, bounded to three with a count of the rest.
+6. **Command tokens are parsed respecting quotes**, because the writer quotes a path containing spaces and a checker
+   that mis-tokenises reports a healthy wiring as broken.
+
+## Why
+
+A colleague's Cursor session stopped working. The `preToolUse` hook crashed with a raw Node stack trace and the hook
+payload echoed back — conversation id, workspace path, email, and the command they were about to run. The entry was
+`failClosed: true`, so the crash did not merely log: it blocked the tool.
+
+The signature was `node:internal/main/eval_stdin`, which occurs only when `node` is invoked with **no script** and
+stdin is a pipe: Node reads the payload as a program, and the first `:` in the JSON is a syntax error.
+
+Two things were worth separating. **The harness could not have written that command.** `cursorWiring` builds `args`
+as `[launcherPath, handler]`, so every rendered command carries three tokens; even an empty launcher path renders
+`node  tool-before`, which fails as a missing module and not as an eval. `tlc-exec.mjs` is ruled out too — every run
+branch carries non-empty args, and a missing entry exits 2 with usage. Verified by rendering, not by reading.
+
+**But the harness could not have caught it either, and that part is ours.** `isCursorWired` decides health by
+checking whether the file *contains* the string `tlc-exec.mjs`. That is a good proxy for "is this file ours", which
+is the right question when deciding whether `update` may overwrite it. It is the wrong question for "do these hooks
+work": a file with the marker in one entry and a broken command in another reported `wired`, and `doctor` said the
+provider was healthy. Nothing checked that the executable resolves, that the script exists, or that every event the
+harness needs has an entry at all. A hook whose script moved in a reinstall reported healthy until it fired.
+
+And when `doctor` did notice, it said `detected but not wired — run: tlc harness update` and nothing else. An
+operator learned that something was wrong, which is one step above silence.
+
+## Trade-offs
+
+**The check resolves paths; it does not run hooks.** Running a hook to prove it runs would run it, with whatever side
+effects that implies on a `preToolUse`. Naming the launcher, checking the file exists and requiring a handler is what
+can be established without acting — and it is exactly the set of things that produced this incident.
+
+**Foreign hooks are ignored, which means a foreign hook can still break a session.** That is deliberate: reporting
+another tool's entry would train an operator to skip the check, and the check would then miss ours. The harness
+reports on what it wrote.
+
+**A fresh install with no wiring produces one problem per declared event**, nineteen of them, which is why the
+formatted detail is bounded to three plus a count. A doctor line that is a wall is a line nobody reads.
+
+**Quote-aware tokenising was found by a test, not by review.** Splitting on whitespace broke a launcher path
+containing spaces — a macOS path under "Application Support" is an ordinary shape — and a checker that
+reports a healthy wiring as broken is the failure mode that gets a check switched off. The writer already quoted for
+this reason; the reader now matches it.
+
+**One pre-existing test asserted the weak rule** — marker present, one entry out of nineteen, expect `wired` — and it
+had to be inverted rather than deleted. It now asserts the incident's shape.
+
+## Not decided here
+
+- **Where the broken hook came from.** The file is not the harness's output, so either it was hand-edited, written by
+  a much older revision, or written by another tool. Answering it needs the operator's `hooks.json`, and the fix does
+  not depend on the answer.
+- **Whether `update` should overwrite a file that is ours but broken.** Today it refuses when the marker is absent and
+  rewrites when present, which already covers the broken-but-ours case. A file with the marker and a foreign entry
+  alongside is the one shape where overwriting loses something, and it stays refused.
+- **Checking the Claude settings shape more deeply.** Its status already comes from a merge comparison against the
+  desired entries, so a changed command is caught. Only the replace-strategy path used the weak check.
+- **Rewriting a hook's crash output.** The stack trace and echoed payload come from Node running someone else's
+  malformed command. The harness cannot format an error it did not produce.

package/docs/decisions/ad-033.md

@@ -0,0 +1,89 @@
+---
+type: Decision
+title: "AD-033 — The gate says what it costs, appendFiles stops promising what it cannot deliver, and a dead capability leaves"
+description: "An operator reported thirty minutes on a small feature. The cause was not his machine: appendFiles auto advertised narrowing the gate to changed files and could deliver it for neither of his commands, so a full lint and a full suite ran on every one of three attempts. Doctor now names that, measures the interpreter start instead of asserting it, the report shows time per gate, and the format capability nothing ever read is gone."
+tags: [decision, grind, cost, doctor, observability]
+timestamp: "2026-08-04"
+---
+
+# AD-033 — The gate says what it costs
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **A package-manager script does not receive appended files.** `npm`, `yarn`, `pnpm` and `bun run` invoke somebody
+   else's script, and what that script does with a path is not something this process can know.
+2. **A command that already carries a glob does not receive appended files.** It walks the glob regardless, so
+   appending narrows nothing.
+3. **A transparent prefix resolves through to the real tool.** `npx`, `bunx` and `dlx` run the tool named next, and
+   that tool decides whether a path narrows — so `npx jest <file>` still narrows.
+4. **`appendFilesVerdict` returns a reason**, and `doctor` reports a `gate scope` warning naming the command, the
+   reason, and `maxLoops`.
+5. **`doctor` measures the interpreter's cold start** — three samples, median — and reports no number when the
+   measurement fails. The hardcoded millisecond claim is gone.
+6. **The session report shows runs, total and worst run per gate**, and states that the cost is paid once per attempt.
+7. **`format.enabled` and `format.command` are removed** from the policy type, the defaults, the loader, the catalog
+   and the docs.
+
+## Why
+
+An operator reported the harness as "extremely slow" — thirty minutes on a three-model feature, "still running jest,
+format and whatever". Three findings, none of them his machine.
+
+**The harness was not running format.** `format` was capability number one in the catalog, presented to every operator
+by the init skill, declared in `Policy`, merged by the loader, and read by no entrypoint. Fifth instance in one week
+of a field advertised and never consumed, and the worst placed of them. AD-003 removes what nothing reads rather than
+honouring it late, and implementing it now — a command after every Write — would ship exactly the failure mode being
+reported.
+
+**The cost was a promise `appendFiles` could not keep.** His configuration, verbatim: `appendFiles: "auto"`,
+`lintCommand: ["npx","eslint","src/**/*.ts","test/**/*.ts","--no-fix"]`, `testCommand: ["npm","test"]`,
+`maxLoops: 3`. The lint command carries its own globs, so appending changed files narrows nothing and the whole tree
+is linted on every stop. The test command is a package-manager script, so whether appended paths reach the runner
+depends on the manager and its version — and `shouldAppendFiles(["npm","test"], "auto")` returned **true**, verified
+by running it.
+
+The codebase already knew this. `RESOLUTION_FAILURE_PATTERNS` contains `missing script:`, which is npm's message —
+so npm was recognised as a script runner for the purpose of classifying a failure, and not for the purpose of
+deciding whether to append arguments to it. The recipe-runner exception exists for precisely this reason and had the
+wrong membership.
+
+**And the one number `doctor` offered about speed was prose.** `BUN_COST_NOTE` asserted "hook cost ~1 ms with Bun vs
+~27 ms with Node" on every machine and had measured it on none. An operator with a slow install had nothing to
+measure and nothing to point at, which is how "the harness is slow" becomes unfalsifiable. It measures now: 2 ms on
+the machine this decision was written on.
+
+The data to answer his question was already recorded — `gate.outcome` carries `duration_ms` — and surfaced nowhere.
+
+## Trade-offs
+
+**Not appending is the conservative direction.** The command runs as the operator wrote it, which is what they can
+reason about. Appending is what produced the surprise. `always` remains for an operator who knows their runner
+forwards, and `never` remains for one who wants the full run.
+
+**`bun test` narrows and `bun run test` does not**, which is a distinction inside one executable. It is real — the
+first is bun's own runner, the second is a script — and encoding it means a special case. The alternative was to
+refuse narrowing for all of `bun`, which would penalise the shape that works.
+
+**The glob rule is a character match**, so a literal `[` in a filename would read as a glob and stop narrowing. The
+failure direction is the safe one: the command runs as written.
+
+**The measured figure is the interpreter's start, not the whole hook.** Every entrypoint has side effects — an
+unrecognised payload writes an obs record into the operator's repository — so a full round trip cannot be measured
+without acting. The label says which it is, because reporting a part as the whole is the overclaim this replaces.
+
+**Removing `format` breaks nothing and deletes an option some operator may have enabled**, believing it worked. It
+never did. A stale block in a config still loads and is ignored, so there is nothing to do about it and — per
+[/decisions/ad-034.md](/decisions/ad-034.md) — nothing worth telling an operator to do.
+
+## Not decided here
+
+- **Implementing format-on-edit.** It would be a new capability with a measured per-Write cost, decided on its own
+  evidence rather than inherited from a field that never ran.
+- **Warning about `maxLoops` itself.** Three or five is a considered choice; multiplying a cheap gate is fine and
+  multiplying an expensive one is what the `gate scope` row is for.
+- **Detecting a slow gate command and suggesting a faster one.** The harness would be guessing at somebody's test
+  setup. It reports the time and the multiplication; the choice is theirs.
+- **Measuring a full hook round trip.** Needs an entrypoint with no side effects, which none of them is today.

package/docs/decisions/ad-034.md

@@ -0,0 +1,86 @@
+---
+type: Decision
+title: "AD-034 — A warning that fires on a healthy install is not a warning, and the author reads the operator's output before anyone else does"
+description: "A real update run put NEEDS YOUR ACTION on two changes that did not apply, both saying run doctor — which update ran automatically three lines later — with an escaped quote leaking into the terminal, above nine warnings for capabilities nobody had enabled, under a line claiming all checks passed. Every piece had a passing test. A migration note now means something doctor cannot detect, unenabled capabilities are inventory, and the author runs the operator-facing commands and reads them before shipping."
+tags: [decision, process, doctor, release, noise]
+timestamp: "2026-08-04"
+---
+
+# AD-034 — A warning that fires on a healthy install is not a warning
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **A `migration` note exists only where `doctor` cannot detect the condition for the operator.** Five of the six
+   notes then in the tree said, in substance, "run `tlc harness doctor`" — which `update` runs automatically. They are
+   removed. AD-027 keeps its note because a stop blocked by evidence ordering is invisible to every check.
+2. **The digest leads with the note and trails the decision id.** A decision's title states the author's reasoning;
+   the operator's situation is what belongs on the first line.
+3. **The heading appears only when a note exists**, and says what a note now means. With nothing to do, the digest
+   states what landed and points at the doctor run below rather than asking for it.
+4. **A frontmatter value is unescaped before display.** An escaped quote reached a terminal as a literal backslash.
+5. **A capability that is merely not enabled is one `ok` inventory row**, not one warning each.
+6. **The doctor summary counts failures and warnings separately** and never says everything passed while printing a
+   warning.
+7. **Before asking anyone else to test, the author runs every operator-facing command and reads the output.** Unit
+   tests assert pieces; the defects here were all in the composition and in the reading.
+
+## Why
+
+An operator ran `tlc harness update` and the output contained four defects, each of which had a passing test.
+
+`NEEDS YOUR ACTION (2)` — and neither applied to him. Three lines below, `doctor` reported his Cursor wiring as
+`wired` and his config carried no `format` block. Both notes said "run `tlc harness doctor`", which the update then
+did automatically. One of them rendered `\"detected but not wired\"` with the backslashes visible, because the value
+was written with escaped quotes inside a quoted string and only the outer pair was stripped.
+
+Below that, nine warnings for capabilities he had never enabled — and buried among them the three rows that mattered:
+a policy baseline changed out of band, and two gate commands running in full on every attempt. Then, under all of it,
+`doctor: all checks passed`.
+
+Every one of those pieces was individually correct and individually tested. The escaping test did not exist because
+the value looked fine in the source. The digest test asserted the heading appeared, which it did. The capability
+warning test asserted a warning was produced, which it was. What no test covered, and no test naturally would, is
+**what the whole thing reads like to the person it is for**.
+
+The through-line is one idea, arriving for the fourth time this week. AD-026 removed an approval prompt that fired
+often enough to become a keystroke. AD-029 removed a silence an operator would misread as a clean result. AD-032
+removed a health check that passed on a broken install. This removes an alarm that fires on a healthy one. In every
+case the mechanism worked and the signal was worthless, because **a signal that appears when nothing is wrong cannot
+carry the case where something is.**
+
+And the process failure is mine and worth writing down plainly: the harness was handed to two colleagues today and
+broke in front of both. The first was a hook that could not run; the second was thirty minutes of gate time nobody
+could see. Both were found by them, not by me, and both were visible in output I had never once read end to end. The
+tests were not the problem. Not looking was.
+
+## Trade-offs
+
+**Removing five notes loses real information for an operator who never runs `doctor`.** That is accepted: `update`
+runs `doctor` at the end, so the only way to miss it is to ignore the output — and a reader who ignores the output is
+exactly the reader an extra alarm does not reach.
+
+**One inventory row is less discoverable than nine warnings.** Deliberately. `update` still prints each capability
+with its benefit and trade-off in full, which is the moment an operator is choosing; `doctor` is the moment they are
+diagnosing, and a list of things they decided not to enable is not a diagnosis.
+
+**`migration` now depends on a judgement — can doctor see this?** — which cannot be checked mechanically. The bundle
+check still catches a present-but-empty note. The judgement is stated here so the next note is written against it
+rather than against a habit.
+
+**Reading the output by hand does not scale and is not a test.** It found four defects that four suites did not, so
+it earns its place as a step rather than as a substitute. The narrower part is testable and now tested: the digest's
+shape, the unescaping, the inventory row, the summary wording.
+
+## Not decided here
+
+- **A golden test over the whole `update` output.** It would have caught all four, and it would also fail on every
+  wording change, which is how a golden becomes a rubber stamp. The composition is checked by reading; the pieces by
+  assertions.
+- **Whether `doctor` should have a quiet mode.** With the wall gone the output is short enough that it has not earned
+  a flag.
+- **Re-announcing a decision whose note is added later.** The digest reads decisions added in a range, so a note
+  written after the fact is not delivered. Notes belong in the change that causes them, which is the standard this
+  decision is a correction toward.