@tech-leads-club/harness-toolkit 0.2.1

package/docs/decisions/ad-022.md

@@ -0,0 +1,120 @@
+---
+type: Decision
+title: "AD-022 — The policy surface is a floor rule, detection sits behind interception, and the operator/agent line is structural"
+description: "The guard denied agent writes to the policy file with the words 'a gate an agent can switch off is not a gate' and enforced that for five tool names only, so one shell line went around it. The invariant moves to the floor, a per-session hash covers what shell parsing cannot see, and the missing CLI route that produced the bypass is opened."
+tags: [decision, floor, policy, gate, cli]
+timestamp: "2026-07-31"
+---
+
+# AD-022 — The policy surface is a floor rule, detection sits behind interception, and the operator/agent line is structural
+
+- **status**: active
+- **date**: 2026-07-31
+
+## Decision
+
+1. **The policy surface is a floor rule, `policy-surface-write`.** It covers shell routes to
+   `.tlc/harness/config.json`, `flags/` and `state/`, and the mutating `tlc harness` subcommands
+   (`pause`, `resume`, `grind`, `mode`, `init`, `gate`). The tool guard stays for tool writes, where it
+   produces a better-targeted message, but it is no longer the only thing standing there.
+2. **The surface includes the runtime config and runtime state**, `~/.tlc/harness/config.json` and
+   `~/.tlc/harness/state/`, not only the project's. `loadPolicy` merges the runtime config *under* the
+   project one, so every field the project leaves unset is decided there — for every repository on the
+   machine.
+3. **Detection is an allowlist of proven readers, never an enumeration of writers.** A verb not in the set
+   cannot be shown to only read, so it is denied. `awk` and `sort` are excluded despite looking like readers.
+   `git` is a reader only for `show`, `diff`, `log`, `status`, `ls-files`, `cat-file` and `blame`.
+4. **The operator/agent distinction is structural.** The floor runs only inside a hook, and a hook exists
+   only inside an agent session, so the operator's own terminal never reaches the check and needs no
+   exemption. No TTY sniffing and no environment marker decide who is asking.
+5. **A per-session baseline hash detects what parsing cannot intercept.** Every source `loadPolicy` reads is
+   hashed at session start; an intra-session change with no `tlc harness` command behind it blocks the next
+   tool call and reports the path. The check is unconditional.
+6. **`tlc harness gate test-command | lint-command` is the legitimate route** to `grind.testCommand` and
+   `grind.lintCommand`, refusing an empty argv, an unresolvable binary and a non-interactive invocation.
+
+## Why
+
+The guard's message asserted an invariant the guard did not hold. `guardPolicySurface` was reached only from
+`case "tool.before"` and keyed off `WRITE_TOOLS`, a set of five tool names, so anything that was not one of
+those five bypassed it by construction. An agent replaced `grind.testCommand` with `python3 -c` in the shell,
+unopposed, and was refused minutes later when it attempted the same write through `Edit`. The gate that fires
+second is not a gate.
+
+The floor is where the invariant belonged all along: it is evaluated before any policy is loaded, it already
+receives `command`, and its own comment forbids giving it a config parameter. Moving the rule there made the
+message true instead of aspirational.
+
+The sanctioned route was the wider hole. `evaluateShellCommand` handles only catastrophic commands and stall
+detection, so `tlc harness pause` — one word, fully supported, writing `flags/skip-verify` — turned every stop
+check off from the agent's shell. `isPolicySurface` already protected `flags/` from tool writes, which shows
+the intent; the CLI wrote them for whoever asked. Closing the file route while leaving that open would have
+moved the bypass rather than fixed it.
+
+The third defect was the incentive behind the first. `grind.testCommand` had no CLI subcommand, so the guard
+forbade the edit and offered nothing instead. An agent that needs a field it is not allowed to set will find
+the shell. The route and the refusal had to ship together.
+
+## Trade-offs
+
+Prove-safe misfires toward denial, and four of those misfires were real — each one caught by the gate
+refusing its own author, and each fixed rather than worked around.
+
+1. The heredoc check first asked whether the segment's verb was a proven reader, which denied
+   `git commit -F -` for a message that merely named the policy path. Writing about this rule tripped it, and
+   every commit in this change would have had to route around the gate being added. The question is not
+   whether the verb reads but whether it *executes* what it reads, so the check is an interpreter set.
+2. It then attributed a body to the whole command, which denied `cat >> f <<'T' … T; node --test` because a
+   different segment ran node. Bodies are now paired with the text before their marker, so the owning verb is
+   the one that actually receives them. Found when the gate refused to let its own test file be written.
+3. `printf '{…config.json…}' | node dist/tool-before.mjs` was denied, which blocked the rule's own end-to-end
+   verification. `echo` and `printf` cannot modify a file on their own — only a redirect can, and redirects
+   are judged separately — so both joined the reader set.
+4. The redirect scanner read a `>` inside a quoted argument as a redirect, so a JSON payload carrying
+   `"command":"echo x > cfg"` was refused. No shell performs that redirect: quoting makes the operator
+   literal. The tokenizer now reports whether a word *opened* with a quote, and only such words are skipped —
+   `>"$f"` begins unquoted and remains a real redirect.
+
+Each is a regression test now, with the opposite direction pinned beside it: the interpreter heredoc, the
+cross-segment attribution, `echo '{}' > cfg` and `echo x > "cfg"` all still deny.
+
+Reading stays ordinary work. The bootstrap instructs the agent to read `handoff.json`, and inspecting the
+config is normal investigation, so a proven reader on those paths passes. The cost is an allowlist that will
+need a new entry occasionally — three entries already arrived this way — and the alternative was a rule that
+punished the reading it asks for.
+
+The project root is excluded from the containment check by name. It contains the surface, so counting it
+would deny `find .` and `grep -r x .` — the most common commands there are. Destruction of the whole project
+remains the concern of `outside-project-destruction` and its siblings.
+
+Integrity detection is intra-session only. Flagging every out-of-band change would fire on the operator
+editing a tracked file between sessions, which is their prerogative and the misfire this repository forbids.
+Re-recording is the entire receipt: every mutator refreshes all live baselines, so "a harness command did
+this" and "the baseline matches" are one fact rather than two that can drift, and the CLI refreshes every
+session because it cannot know which are live.
+
+The TTY requirement on `gate` is a second layer, not the distinction. Existing mutators keep working
+non-interactively — nothing in CI or the installers calls them, which was verified before the choice.
+
+## Not decided here
+
+- **Fully dynamic path construction.** `P=$(…); echo x > "$P"` is unreachable by the floor, as are
+  `bash script.sh` and compiled binaries. The floor already documents that class as a coverage limit rather
+  than evasion; the baseline hash catches the effect after the fact. Detection after the write is inherent,
+  and it is why interception exists in front of it.
+- **`rm -rf .` still reaches the state directory.** It is allowed by the existing destruction rules as
+  destruction inside the project, and narrowing that is a change to those rules, not to this one. Note this
+  is a pre-existing property of `outside-project-destruction`, not something this decision introduced: a
+  command that erases the whole repository is a larger problem than the policy files inside it.
+
+## Corrected after first writing
+
+This decision first left the runtime config as "not decided here", on the reasoning that `isPolicySurface`
+is per-project by design. That was wrong, and adding `echo` and `printf` to the reader set is what exposed it:
+`echo '{}' > ~/.tlc/harness/config.json` resolved outside the project, so the redirect check did not match,
+and the head verb was a proven reader, so nothing else did either. It was allowed, verified against the built
+bundle. The substring fallback caught the *interpreter* spelling of the same write, which is why it read as
+covered.
+
+Deferring it would have left the machine-wide half of the surface open while the project half was closed —
+the same defect one directory up, reachable by the reader set this decision had just widened.

package/docs/decisions/ad-023.md

@@ -0,0 +1,87 @@
+---
+type: Decision
+title: "AD-023 — One finding per failure, and lesson relevance is recurrence rather than exposure"
+description: "A single failing test reached an operator as three gaps — the assertion header, the test name and the tally '1 fail' — while a lesson whose cause had been fixed four days earlier outranked everything. Findings are now grouped per failure, and lesson decay reads the field the world writes instead of the field the harness writes by reading."
+tags: [decision, gate, lessons, signal]
+timestamp: "2026-08-03"
+---
+
+# AD-023 — One finding per failure, and lesson relevance is recurrence rather than exposure
+
+- **status**: active
+- **date**: 2026-08-03
+
+## Decision
+
+1. **A finding corresponds to a failure, not to a matched line.** `extractFindingsFromOutput` classifies each
+   line by role — `count`, `test`, `assertion`, `other` — groups an assertion onto the test it explains, and
+   deduplicates. A tally is never a finding on its own.
+2. **A tally is a line composed only of tally clauses.** `1 fail — runCascade …` is not a tally, because the
+   name is the failure's only identity.
+3. **A bare `error:` is not an assertion.** Assertion vocabulary (`expect(`, `toEqual`, `AssertionError`,
+   `Expected`, `received`) decides detail; `error: cannot find module` stays a failure of its own.
+4. **An unrecognised runner degrades to one finding per line** — today's behaviour minus the tally. Unknown
+   formats become noisier, never silent.
+5. **The cap discloses what it omitted.** The disclosure occupies one slot, so the omitted count is always two
+   or more.
+6. **Lesson decay and pruning measure `lastSeenAt`, never `lastAccessedAt`.** `lastSeenAt` moves only when the
+   failure signature recurs; `lastAccessedAt` moves when a lesson is injected and is telemetry only.
+7. **A lesson does not restate the gate's own suggestion.** `recordLessonFromFailure` no longer takes
+   `suggestion`; the lesson carries the signature and the retry guidance.
+8. **The garden retires a `verification` lesson whose signal is an unresolved gate command**, because AD-021
+   made that class classify as `config` and it can no longer legitimately recur.
+
+## Why
+
+Both halves were observed together on one real gate run: `28 pass, 1 fail` in a project's `bun test`, reported
+to the agent as three gaps plus a lesson from a dead cause.
+
+**The findings.** `extractFindingsFromOutput` returned one `GateFinding` per line matching `FAIL_HINT`. For
+that run it returned three: `error: expect(received).toEqual(expected)`, `(fail) runCascade — métricas …`, and
+`1 fail`. Those are the assertion, the test's identity, and a counter — three views of one failure. This is
+not a display nicety: `gapsFromArtifact` maps findings 1:1 to gaps, the autopilot prints *"Read the
+PREVIOUS_GAPS list and fix each item explicitly"*, and `mergeGaps` carries the list into the handoff. One
+assertion failure became three tracked problems that persisted across turns, with a counter among them as
+something to go fix.
+
+**The lesson.** `decayedConfidence` read `lastAccessedAt || lastSeenAt`, and `touchAccessed` writes
+`lastAccessedAt` for every lesson *selected for injection*. Showing a lesson therefore reset the clock that
+decided whether to keep showing it: injected → touched → decay back to zero → still ranked high → injected
+again. The garden's prune expression read the same field, so it never pruned either. Relevance was being
+measured by "was recently injected", and injecting is what writes that field.
+
+That loop is why a lesson from a config fault AD-021 had already fixed was still ranked top four days later,
+with `lastAccessedAt` renewed daily by its own injection. Its `instruction` was also, by construction, the
+gate's own `next_action`: the text was built as `` `${suggestion} Recurrent failure signature…` `` while
+`stop.ts` handed the same `suggestionFor(category, gate)` value to both the plan and the lesson. The
+highest-ranked entry in a budgeted list restated the sentence printed directly above it.
+
+## Trade-offs
+
+Role classification is a heuristic over text, not a parser. The alternative — requiring each project to emit
+JUnit XML or a JSON reporter — would change every project's configured command, and `reportPath` already
+serves projects that want structured findings. The heuristic is therefore built to fail toward noise: an
+unknown format keeps every matched line, and an assertion with no test line ever seen becomes its own finding
+rather than being dropped with the buffer. Losing a real failure is the only unacceptable outcome on this
+channel.
+
+`lastAccessedAt` is kept and still written. Removing it would break existing stores for no reader benefit, and
+"was this lesson ever used" is worth knowing — it just is not evidence that the lesson is still relevant. The
+defect was reading it, not writing it.
+
+Stored lessons keep their old prefixed instructions. A migration that rewrites them buys no reader anything
+once the decay clock is honest; they fade on their own.
+
+The AD-021 retirement is narrow on purpose. Only that class is provable from what the store retains — the
+store keeps a signal snippet, not raw output and exit codes — so a general "would this classify differently
+today" engine would be guesswork. `exitCode: 0` is passed to `isCommandResolutionFailure` so that only its
+message patterns can decide; the real function returns true for 127, and stored text can contain any number.
+
+## Not decided here
+
+- **Grouping across the cap.** When more than `FINDINGS_MAX` distinct failures exist, the omitted ones are
+  counted, not summarised. Clustering them by file or suite would need more structure than the text gives.
+- **Retiring lessons whose cause was fixed in general.** Beyond the AD-021 signature there is no stored
+  evidence to decide it, and inventing one would put guesswork into the channel this decision exists to clean.
+- **`lastSeenAt` on the six built-in core lessons** is the epoch. It never reaches the maths because
+  `decayedConfidence` returns early for `source === "core"`, so it was left alone rather than backfilled.

package/docs/decisions/ad-024.md

@@ -0,0 +1,85 @@
+---
+type: Decision
+title: "AD-024 — The gate tells the truth about its own environment, its own lock, and the cause of a failure"
+description: "One stop hook produced three wrong statements at once: 22 tests failed for environmental reasons, the gate could not run because a lock named a dead process, and the plan blamed the only file that had changed. The suite is now hermetic, pid liveness is host-scoped, and the named files come from the failure rather than from the diff."
+tags: [decision, gate, testing, lock, signal]
+timestamp: "2026-08-04"
+---
+
+# AD-024 — The gate tells the truth about its own environment, its own lock, and the cause of a failure
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **The test suite is hermetic with respect to project-identifying environment.** A setup module loaded via
+   `node --import` deletes `CLAUDE_PROJECT_DIR` and `TLC_PROJECT_DIR` before any test file runs, for both
+   suites. `TLC_HOME` is deliberately kept: it names which runtime, CI sets it on purpose, and the suite
+   exercises it.
+2. **A leak fails one test that names itself**, and the wiring is asserted separately, so dropping the
+   `--import` fails rather than silently restoring 22 misleading failures.
+3. **A test that asserts what happens when a variable is absent makes it absent itself**, rather than
+   inheriting that from the shell.
+4. **Lock reclaim consults process liveness, scoped to the host that wrote the lock.** `LockBody` gains
+   `host`; `process.kill(pid, 0)` decides; `ESRCH` is gone, `EPERM` is alive, and a foreign host, a missing
+   host or an unusable pid all fall back to the age rule.
+5. **`describeHolder` applies the same rule as reclaim.** The two must agree or the reclaim path is
+   unreachable.
+6. **The files a plan names come from the failure output when it names any.** Only that list may read as an
+   instruction; the changed files are labelled as coming from the diff, and neither list is called "focus".
+
+## Why
+
+A single stop hook made three false statements, and each traced to a different defect.
+
+**The suite answered the shell, not its fixtures.** `projectDirFor` prefers `CLAUDE_PROJECT_DIR` over the
+payload's `cwd`, which is correct in production — the variable is the project root, `cwd` can be a
+subdirectory. Inside a Claude Code hook it is always set, so every test that built a fixture in a temp
+directory and passed `cwd` resolved against the real repository. Measured: 947 pass from a shell, 925 pass and
+22 fail with the variable set, reproduced on a clean HEAD. The 22 spanned presence collisions, minEffort
+denial, untrusted-content framing, policy integrity and cost estimation, so the gate read as five product bugs
+rather than one leak. The resolver is untouched; the tests were the defect.
+
+**The lock honoured a dead owner.** The gate refused to run because the lock named a session whose pid `ps`
+reported gone. The body carried the pid and nothing consulted the operating system: `isLockStale` decides by
+file age alone, against a thirty-minute window. The half of this that actually unblocked the gate was
+`describeHolder`, which already carried a comment saying *"an abandoned lock must not read as held … callers
+short-circuit on this answer before withGateLock can reach stealIfStale"* — and implemented that for staleness
+only. A fresh lock with a dead owner was reported as held, the caller short-circuited, and no change to
+reclaimability could have been reached.
+
+**The plan blamed proximity.** `Focus files` was rendered from the changed files, under a category whose steps
+say to fix each item explicitly. It named a new file no test imports while the output named the three real
+ones. The evidence was in the same text and was passed over in favour of the diff. AD-021 recorded this harm
+once already, arriving through a malformed command; this is the same harm arriving through the diff.
+
+## Trade-offs
+
+Cleaning environment in a setup module is a blunt instrument, and the blunt part is the point: enumerating
+which tests need which variable absent is what produced a suite that passed in one place and failed in
+another. The cleaned set stays minimal — only variables that name *which project* — and `TLC_HOME` is excluded
+by name and by test, because deleting it would hide a different class of bug than the one this module exists
+for.
+
+Splitting the module in two (`test-env.mjs` performs the deletion, `test-env.names.mjs` holds the list) looks
+redundant and is not. The first draft had the guard import the list from the module that deletes, so importing
+it ran the cleanup and the assertion could never fail — verified: it passed with the variable set and the
+`--import` absent.
+
+Host-scoped liveness is narrower than checking every pid, deliberately. A pid means nothing on another
+machine, and reclaiming a lock whose owner is alive elsewhere would let two gates run at once, which is the
+thing the lock exists to prevent. `GATE_LOCK_STALE_MS` is unchanged for the same reason: age remains the answer
+whenever liveness cannot be established.
+
+File extraction is a heuristic over text and is scoped to paths the runner itself printed. It does not attempt
+to infer a culprit from a stack, a symbol or a diff — inferring is what this decision exists to stop.
+
+## Not decided here
+
+- **Cursor's project-identifying variables**, if any exist, are not in the cleaned set. None were found; the
+  set grows when one is.
+- **Orphan lock sweeping** on a schedule. Reclaim is checked when the lock is contended, not proactively;
+  presence has `sweepStale` and the lock does not, which is a difference this decision leaves standing.
+- **Whether the changed-file list belongs in the plan at all.** It is kept, relabelled. Removing it would lose
+  context that is occasionally the right lead.

package/docs/decisions/ad-025.md

@@ -0,0 +1,92 @@
+---
+type: Decision
+title: "AD-025 — Posture governs surfacing only, and each posture has exactly one name"
+description: "Three postures existed by name and two by behaviour: the deepest one was reachable under a second spelling, forced grind on, narrowed the test gate, and stated a threshold that the invariant block contradicted. Posture now varies one thing — what earns an interruption — and one word names each level everywhere."
+tags: [decision, policy, posture, cli, vocabulary]
+timestamp: "2026-08-04"
+---
+
+# AD-025 — Posture governs surfacing only, and each posture has exactly one name
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **One word per posture: `paired`, `solo`, `focus`.** It is the word the operator types, the word the config
+   field holds, the name of the flag file, and the word `status` prints. No alias, no translation.
+2. **`resolvePosture` is the only thing that answers which posture is in effect**, and it answers *where from* in
+   the same call. The loader, `status` and `doctor` read that one result.
+3. **A value that is not a posture is refused, not absorbed.** The CLI rejects it with the three accepted words;
+   a config value falls back to `solo` with origin `fallback` and the rejected word carried alongside, which
+   `status` prints and `doctor` reports as a `warn`.
+4. **Posture changes what the agent surfaces and nothing else.** The evidence bar, the gates and the
+   done-criteria are identical at all three, and the harness says so in its own bootstrap.
+5. **The interruption threshold is stated per posture, not once for all three.** `paired` adds a pre-check
+   before any sizable move; `solo` names three stops; `focus` names two and hands ambiguity to the agent under a
+   stated assumption.
+6. **`paired` is enforced, not only described.** A shell command classified `write` or `network` is asked about
+   before it runs. `solo` and `focus` share enforcement, because what separates them is whether *ambiguity*
+   reaches the operator — the agent's judgement, not a hook event.
+7. **No posture raises grind and no posture narrows the test gate.** Grind has its own switch, its own flag and
+   its own documented trade-off; the test gate runs whenever test files or `codePaths` files changed.
+
+## Why
+
+The harness advertised three postures and implemented two. Measured on the config this repository ships:
+`"mode": "focus"` — the word the README documents and the CLI accepts — matched no branch in the operator
+bootstrap, because the field stored a second spelling. The result was a policy with **no posture line at all**
+and grind left off, reported by nothing. A vocabulary split between the command and the file it writes is not a
+cosmetic defect; it is a value the operator can express and the system cannot hold.
+
+The deepest posture also carried three things that were not surfacing. It forced grind on, so a preference about
+interruptions silently switched on a capability with its own switch — the AD-020 defect class, arriving from the
+policy loader instead of from `status`. It narrowed the test gate to *test files changed*, which skips exactly
+the change that most needs testing: a code change with no test in the diff. And its own line told the agent not
+to ask about reversible work while the invariant block, which applies to every posture, demanded escalating
+ambiguity. A rule that varies cannot sit in the block that does not vary, so the threshold moved out of `BASE`
+and is now stated once per posture.
+
+`paired` was the posture that promised the most and enforced the least: it said it would check in before a
+sizable move and then relied entirely on the agent reading its own instructions. `classifyShell` already answers
+"is this a write or a network call" and is already tested, so the promise became a decision at the hook. The
+first draft of this feature recorded that enforcement was impossible here; that reading was wrong and is
+recorded as refuted.
+
+## Trade-offs
+
+`focus` won as the canonical name over the alternative spelling because it is the operator-facing word and it
+matches the shape of its siblings — three single words for three levels. The earlier draft chose the other way
+on the grounds that the word came from an external methodology the harness was modelled on. That rationale was
+withdrawn: the harness must not know that anything outside it exists, so the only remaining criterion is
+internal coherence.
+
+Refusing the second spelling breaks existing configs that carry it, by choice. AD-003 forbids back-compat
+shims, and an alias is precisely the translation layer this decision exists to remove. The cost is one word in
+one file per project, and `doctor` names the file and the fix. Absorbing it silently is what produced the
+original bug.
+
+`solo` and `focus` being identical in enforcement is deliberate and will read as a gap. What separates them is
+whether the agent raises ambiguity, and no hook observes ambiguity — text is the honest mechanism there. Giving
+them different enforcement would mean inventing a signal that does not exist.
+
+Removing grind forcing means an operator who relied on the deepest posture implying grind now sets grind
+explicitly. Both known installs already enable it, so the measured impact is zero, and the alternative is a
+posture that quietly changes what "verified" means.
+
+Two things about verifying this are worth keeping. **A second derivation of the same fact can pass an entire
+suite.** The precedence between the project and the user config was written twice — once where the policy is
+loaded, once where it is reported — and reversing one of them passed all 982 tests in that suite. The test that
+now pins it makes the two configs *disagree*, because with both saying the same thing a reversed precedence
+passes. **And a module can ship with no test file at all.** `policy.operator.ts` was rewritten with the
+threshold moved out of its invariant block, and the green suite said nothing, because there was never a test
+file to fail. A passing gate is evidence about the tests that exist and about nothing else.
+
+## Not decided here
+
+- **Whether `init` should validate `mode` before writing it.** It validates no other field, and a bad value now
+  surfaces through the fallback and the `doctor` row rather than disappearing.
+- **A fourth posture**, or per-project thresholds inside a posture. Three levels of one dimension is the whole
+  model; a second dimension would be a different decision.
+- **Whether `paired` should also pre-check non-shell actions** such as an Edit to a large file. Only the shell
+  is classified today.

package/docs/decisions/ad-026.md

@@ -0,0 +1,131 @@
+---
+type: Decision
+title: "AD-026 — An interruption is worth what it costs: narrower asks, a deadline on questions, and a rate the operator can see"
+description: "Published 2026 work confirmed that verification must not weaken with autonomy and contradicted three details of the posture model: the paired ask was broad enough to become reflex, no posture stated when a question stops being worth asking, and the interruption rate was unmeasurable while the report printed a number for it. Approval fatigue is treated as a security defect, ambiguity gets a deadline stated in words, and a rail that was pointed at the wrong phase is connected."
+tags: [decision, policy, posture, security, observability]
+timestamp: "2026-08-04"
+---
+
+# AD-026 — An interruption is worth what it costs
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **The `paired` ask marks a command that can lose something or widen access, not one that merely changes
+   something.** The shell classifier gains two classes: `write-preserving` (an append — content survives, so it
+   leaves the asking tier) and `privilege` (`chmod`, `chown` — no byte is lost and access moves, so it stays).
+   `cp`, `mv` and `tee` stay in `write`, because each can overwrite a destination and the harness cannot know
+   whether that destination exists. `privilege` outranks `write`: an overwrite inside a repository is recoverable
+   and visible in a diff, a widened permission is neither.
+2. **`>` and `>>` are different classes.** They collapsed into one branch, so an append was indistinguishable
+   from an overwrite — the exact line the new class draws.
+3. **`PAIRED_ASK` is unchanged.** The narrowing happens in the classifier, because what a command can do is
+   decided in one place.
+4. **Every posture states a deadline for ambiguity, not only a threshold.** An unclear goal belongs in the first
+   actions; once the work is under way, the agent takes the most reasonable reading and states the assumption
+   instead of asking. `focus` admits exactly one early question — the goal it cannot read before starting.
+5. **No posture line contains a digit.** The harness cannot measure where in a trajectory it is, so the deadline
+   is stated in words. A position it cannot compute would be a claim it cannot honour.
+6. **The autopilot's posture step states the settle-and-state form at every posture and invites no question.** It
+   renders only after a gate has already failed, so it is late by construction — the one place where the deadline
+   is a fact rather than a guess.
+7. **A `deny` or `ask` decision may name the rule that produced it.** `Decision.rule` is optional; a consumer
+   that wants attribution and finds none reports it as unattributed rather than guessing.
+8. **Every shell decision is recorded with its permission, the active posture and its rule.** An `allow` grades
+   as debug and `debugEnabled` is false by default, so the common path computes and drops it.
+9. **The session report attributes interruptions by rule**, ordered by weight, rendered only when non-empty.
+10. **The harness does not claim Ask-F1, or any precision or recall.** It records its own decisions. It never sees
+    the operator's answer, and it cannot see whether a question it did not ask would have helped.
+
+## Why
+
+Three findings from published 2026 work, and one confirmation.
+
+**Confirmed: verification must not weaken as autonomy rises.** Graduated oversight for agentic code generation
+(arXiv 2606.22484) names that coupling — more autonomy, less verification rigour — as the common pitfall, and
+recommends gates stay constant or strengthen. That is AD-025, and nothing here touches it.
+
+**Approval fatigue is a security defect, not an ergonomics complaint.** A survey reframing agent security as an
+agent-human interaction problem (arXiv 2605.24309) finds the cost asymmetry decides the outcome: rejecting an
+action means understanding it well enough to say why, while approving is one keystroke. After enough
+interruptions the human approves by reflex — and an attacker who can influence agent output hides the
+consequential action inside the stream of routine ones, where a habituated reviewer waves it through. The
+convergent mitigation across every source is the same: reduce the number of approvals so the remaining ones get
+real attention. `PAIRED_ASK` covered the whole `write` class, which meant asking before `chmod +x` and before
+appending a line to a file. Those are the routine ones.
+
+Measured against the shipped classifier rather than assumed. The research note that opened this work claimed
+`mkdir` asked; it never did — `mkdir` and `touch` classify as `read`. What actually asked was `cp`, `mv`,
+`chmod`, `chown`, `rm`, `rmdir`, `tee`, `truncate`, `sed -i`, and both redirects. Three of those cannot lose a
+byte that existed.
+
+**A late question is worse than no question.** Clarification timing across 6,000+ runs, four models and four
+information dimensions (arXiv 2605.07937) measures the decay: a goal question loses nearly all its value once
+work is under way, an input question holds longer, and deferring any clarification past the middle of the work is
+worse than never asking at all. Cross-model agreement (Kendall τ 0.78–0.87) says this is the structure of the
+task, not a quirk of one model. Every posture line stated a threshold with no deadline, which licensed precisely
+the worst case: asking at the twentieth action about a goal misread at the first. `focus` already had the correct
+late behaviour and never said that a goal unclear *before starting* is the one question worth the interruption.
+`focus` means ask early or not at all — not never ask.
+
+**The interruption rate was unmeasurable, and the report said otherwise.** HiL-Bench (arXiv 2604.09408) defines
+Ask-F1 — the harmonic mean of question precision and blocker recall — because a benchmark rewarding only
+execution scores a lucky guess the same as a correct escalation. This harness measured nothing about asking, and
+the shape of that gap was worse than absence. `attrs.permission` was read in two places and written in none, so
+`shell.ask` and `shell.deny` were structurally zero while the report printed `Shell allow/ask/deny` — a
+truthful-looking `0` for every ask that ever happened. And the rail was not merely unconnected: the level branch
+keyed on `shell.end` alone, and a command that was denied or asked about never reaches an "after" event. The only
+permission that phase could ever carry was `allow`, so the counter could not have moved even once something wrote
+the attribute. The decision exists at `shell.start`, and that is where it is now recorded.
+
+## Trade-offs
+
+The narrowing is small, and worth stating plainly rather than dressing up: **one shape left the asking tier** —
+the append. `cp` and `mv` stayed because the destination may exist, which is unknowable without touching the
+filesystem, and `tee` stayed with or without `-a` because the flagless form truncates and a rule whose failure
+mode is silent data loss does not get a special case. So the fatigue reduction this delivers is close to nothing;
+what it delivers is the structure and the correct question. Whether `paired` actually interrupts too often is
+unanswered, and decision 8 is the instrument that will answer it, with no data in it yet.
+
+**The first version of this decision had the wrong axis, and it shipped for one revision.** `chmod` and `chown`
+were classified as preserving on the reasoning that they lose no bytes. That is true and beside the point:
+`chmod -R 777 .` went through `paired` unremarked. Losing content and widening access are separate questions, and
+the second is the one whose answer never appears in a diff — which makes it worse to miss, not better. The
+correction is recorded here rather than quietly folded in, because the failure was in the criterion, not in the
+code, and a criterion is the kind of thing that gets reused.
+
+**Sticky approval was rejected, using the same source that motivated the narrowing.** The obvious next step —
+remember that this command was approved and stop asking — is the pattern the survey names as having the *worst
+long-term security profile*, because each click monotonically widens the trusted surface. Worse, this harness
+cannot tell a human approval from a host auto-approval: `shell.after` fires either way, so a trust cache built on
+it would record consent that was never given. Every sticky approval needs scope and expiry, and the honest
+sequence is to measure the rate first — which is what decision 8 makes possible, with data rather than taste.
+
+**Sandbox auto-approval was rejected for a simpler reason.** It is the pattern with the strongest reported
+reduction, and it delegates the decision to a boundary this harness does not have. Claiming it without the
+mechanism would advertise a protection that does not exist.
+
+`focus` gaining a stop reads as a regression against "fewest interruptions" and is not: the stop is bounded to
+before the first action, and one question there is cheaper than everything built on a misreading. A test asserts
+the late form is still settle-and-state, so the bound holds.
+
+Widening `ShellEffectClass` touched five references in one file, and `tsc` proves the exhaustiveness. Adding an
+optional field to two `Decision` members is source-compatible; no existing consumer reads it.
+
+## Not decided here
+
+- **`policy.deny` has the same shape of defect.** `rollup.denials` and the report's "Policy denials" are fed by
+  an obs kind nothing emits. Fixing it means deciding which layer owns the emission and accepting that emitting
+  `tool.start` creates empty per-tool slots in the report. Recorded, not fixed.
+- **Floor denials are not recorded.** `rm -rf /` never reaches a policy layer, so the rate covers policy
+  decisions only. The catastrophic-attribution test states this in the command it chooses.
+- **Whether `paired` should pre-check non-shell actions.** Unchanged from AD-025: only the shell is classified,
+  and asking before every one-line `Edit` turns a posture into a permission prompt.
+- **Plan-level approval as the middle posture.** `planGate` already checks declared scope against the diff, which
+  covers the harm; swapping `solo` for a plan-approval model would redesign a feature that just stabilised.
+- **Autonomy that accrues with trust.** Posture is the operator's declared preference, not a score the harness
+  assigns itself.
+- **A second agent detecting underspecification** (arXiv 2603.26233). Demonstrated, and out of scale for a hook:
+  it needs a monitor running alongside every turn.

package/docs/decisions/ad-027.md

@@ -0,0 +1,90 @@
+---
+type: Decision
+title: "AD-027 — Evidence is ordered against the code, every rail's firing is recorded, and a checker can run with its rule off"
+description: "The ship gate compared evidence to the clock instead of to the work it certified. Three declared observability rails had no producer while the report printed numbers for two of them. And nothing could tell a rail that works from a rail that was never needed — so a checker can now run while its rule is switched off, which is the reading that makes deleting a rail a decision rather than a feeling."
+migration: "Re-run your verification after the last code change before citing the verdict — the ship gate now refuses evidence written before the code it certifies, so a claim that used to pass can block. Nothing in doctor can see this one; it shows up as a blocked stop."
+tags: [decision, ship, observability, rails, measurement]
+timestamp: "2026-08-04"
+---
+
+# AD-027 — Measure the rails, and measure them honestly
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **Evidence must be newer than the code it certifies.** `hasRecentEvidence` takes the newest mtime among the
+   turn's changed files; a verdict older than that does not count. Age remains the second criterion, and a missing
+   timestamp falls back to age rather than failing closed.
+2. **`gate.outcome` is emitted**, from inside `runLockedGate` so a gate added later cannot be forgotten, and
+   outside the lock so a measurement never widens the window in which one gate blocks another.
+3. **`policy.deny` is emitted** from the one place every entrypoint's decision passes through, after `degrade`, so
+   what is recorded is what the provider actually rendered.
+4. **A floor denial carries its rule structurally.** The floor already wrote `rule=<name>` into its reason prose;
+   attributing a refusal no longer requires parsing English.
+5. **One rail owns every shell decision, including the ones the floor makes.** The shared refusal path skips
+   `shell.before` to avoid double counting, so the shell rail records the floor's shell denials itself.
+6. **Refusals are counted by rule in one place**, whichever rail produced them, and gates are counted by name.
+7. **The session report answers three questions that need no inference**: which enabled rail never fired, which
+   fires constantly, and what the injected prose cost in characters. The active-rail list is a parameter, because
+   core cannot see which rails a project enabled and a report that guessed would accuse a rail nobody switched on.
+8. **Observation mode runs a rail's checker while that rail is not enforcing**, records the reading, and never
+   returns a decision. Opt-in, default empty. An enforcing rail is not observed, and observations carry their own
+   obs kind so the refusal counters stay honest.
+
+## Why
+
+**Freshness is not what makes evidence evidence.** The ship gate asked `now - mtime > maxAgeHours`. A verdict
+written ten minutes ago passed while the code it certified changed five minutes ago — evidence that predates the
+change proves nothing about it, and the gate accepted it in silence. Ordering is the question that matters, and the
+comparison timestamp was already in hand: the stop path lists the turn's changed files on every run.
+
+**Three rails were declared and unfed, and two of them printed numbers.** `gate.outcome` is consumed by the rollup
+counter and by the report's "Gates pass/fail" line, and was emitted by nothing — so the report has printed a
+truthful-looking `0 / 0` for every gate this harness has ever run. `policy.deny` fed `rollup.denials` and "Policy
+denials" with no producer, so a harness whose whole purpose is refusing things reported zero refusals. This is the
+third instance of the family recorded in AD-020 and AD-024: a field advertised and never written. The pattern is
+consistent enough to name — a consumer written before its producer reads as working, because zero is a plausible
+number.
+
+**And a firing rate cannot tell you whether a rule was needed.** A rail that never fires while its prose is
+injected is either working perfectly or unnecessary, and the count is identical in both cases. That matters because
+prose is not free: the harness injects at every session start, paid in input tokens on every turn, and it had never
+told the operator the size of that bill.
+
+Running the checker with the prose *absent* separates the two. If the property holds anyway, the model was already
+honouring it and the rule is paying for context and returning nothing. This is possible here and almost nowhere
+else, because in this harness the checker and the instruction are different things; in a system where the rule *is*
+the mechanism there is nothing to hold apart.
+
+## Trade-offs
+
+Observation costs a diff scan per turn per observed rail, and it is opt-in for exactly that reason: it answers a
+question only an operator who is asking it needs answered. It never blocks and never changes a decision, and a test
+asserts the turn's outcome is identical with it on — a measurement that can change what it measures is not a
+measurement.
+
+The `held-with-prose` reading is ambiguous by construction and stays that way. Resolving it would mean withholding
+the prose on a fraction of real turns to compare, which pays for the measurement in the operator's own outcomes.
+The harness's job is to make this turn better.
+
+Recording the injected character count is a proxy for tokens, not a token count. It is honest about being a
+character count, and it moves in the same direction as the thing that is billed.
+
+The ordering check compares mtimes, which a filesystem with coarse timestamps or a checkout that rewrites them can
+confuse. Age remains as the second criterion for that reason, and an absent timestamp falls back to it rather than
+blocking a stop on missing input.
+
+## Not decided here
+
+- **A probe that runs a task N times with and without a rule.** It is the clean way to measure a rule's effect and
+  it needs task repetition. Real work does not repeat: a bug is fixed once. That design belongs to a benchmark.
+- **A placebo arm** — injecting filler of equal token count to separate "the content helped" from "more context
+  helped". Methodologically the sharpest instrument available and it degrades real work to obtain a reading.
+- **Inference over the recorded data.** Mixed models, Bayes factors and equivalence tests are sized for a
+  benchmark, and the load-bearing element is a paired design that task repetition would provide and real work does
+  not — while task identity is the largest confound there is. Inference earns its keep at fleet scale, where a
+  random intercept per repository is meaningful. Two installations are not a fleet.
+- **Per-rail token attribution.** The report gives one number for all injected prose. Splitting it by rail means
+  threading provenance through the assembly, and the single number already answers "is this bill large or small".