@tech-leads-club/harness-toolkit 0.2.1

package/docs/decisions/ad-014.md

@@ -0,0 +1,56 @@
+---
+type: Decision
+title: "AD-014 — Claude Code hook payload field paths, pinned"
+description: "The design specified Claude's event names and capability booleans but never its JSON field paths; this decision pins them so a wrong field path cannot silently pass a green test suite."
+tags: [decision, claude, contracts, inbound]
+timestamp: "2026-07-29"
+---
+
+# AD-014 — Claude Code hook payload field paths, pinned
+
+- **status**: active
+- **date**: 2026-07-29
+
+## Why this exists
+
+The design specified Claude's event *names* and capability *booleans* but never the JSON field paths.
+Cursor's adapter could be checked against captured goldens from the predecessor handlers; Claude has no
+such upstream, so a wrong field path produces a passing test suite and a silently broken adapter. This
+pins the field paths before later phases build on top.
+
+## Field paths
+
+| Field | Where | Source |
+| --- | --- | --- |
+| `session_id` | top level, all events | documented |
+| `hook_event_name` | top level, PascalCase | documented |
+| `cwd` | top level | documented |
+| `transcript_path` | top level | documented |
+| `permission_mode` | top level (`default\|plan\|acceptEdits\|auto\|dontAsk\|bypassPermissions`) | documented |
+| `effort.level` | top level object, `low\|medium\|high\|xhigh\|max` | documented |
+| `prompt_id` | top level, absent until first input | documented |
+| `agent_id`, `agent_type` | top level, subagent events only | documented |
+| `tool_name`, `tool_input`, `tool_use_id` | top level, tool events | documented |
+| `tool_input.command` | Bash | documented (official example) |
+| `tool_input.file_path` | Edit / Write / Read | **inferred** from the tool schema, not quoted in the hooks reference — verify against a real payload when one is available |
+| loop counter | **does not exist** on `Stop` | documented by absence; this is why Claude has no native loop counter (see [/providers/claude-code.md](/providers/claude-code.md)) |
+
+## Consequence
+
+`claude.inbound.ts` reads exactly these paths. Any future divergence is a payload change, not a design
+choice, and must be caught by re-reading the reference rather than by guessing.
+
+## Applies to
+
+- `src/providers/claude/claude.inbound.ts`
+- its fixtures
+- Claude entrypoints
+
+## See also
+
+- [/providers/claude-code.md](/providers/claude-code.md)
+
+# Citations
+
+1. Claude Code hooks reference (Anthropic documentation) — field paths pinned above were cross-checked
+   against the documented hook payload shape at the time this decision was recorded.

package/docs/decisions/ad-015.md

@@ -0,0 +1,33 @@
+---
+type: Decision
+title: "AD-015 — Wiring handler names are the entrypoint filenames"
+description: "The handler name a provider's wiring registers is the src/entrypoints/<name>.ts filename, so both providers' wiring descriptors reference exactly the same eleven handler names."
+tags: [decision, entrypoints, providers, wiring]
+timestamp: "2026-07-29"
+---
+
+# AD-015 — Wiring handler names are the entrypoint filenames
+
+- **status**: active
+- **date**: 2026-07-29
+
+## Decision
+
+The handler name a provider's wiring registers is the `src/entrypoints/<name>.ts` filename —
+`session-start`, `session-end`, `prompt-submit`, `tool-before`, `tool-after`, `tool-failure`,
+`subagent-start`, `subagent-stop`, `stop`, `compact-before`, `response-after`. Both providers' wiring
+descriptors already use these names.
+
+## Why
+
+Building the second provider adapter required picking a naming scheme with no spec anchor. Making the
+entrypoint filename the single source of truth removes the guess for every wiring descriptor that follows.
+
+## Applies to
+
+- `cursor.wiring.ts`, `claude.wiring.ts`
+- all `src/entrypoints/*.ts` files
+
+## See also
+
+- [/providers/cursor.md](/providers/cursor.md), [/providers/claude-code.md](/providers/claude-code.md) — the wiring tables built on this naming

package/docs/decisions/ad-016.md

@@ -0,0 +1,98 @@
+---
+type: Decision
+title: "AD-016 — Field semantics, state writers, and the core export surface"
+description: "Spawn fields are named apart from the running agent's, parent-model state has a writer, core exports what entrypoints need, ObsKind covers the adapter boundary, blockMode is honoured, and shell audit records are signal-level."
+tags: [decision, entrypoints, contracts, observability, correctness]
+timestamp: "2026-07-29"
+---
+
+# AD-016 — Field semantics, state writers, and the core export surface
+
+- **status**: active
+- **date**: 2026-07-29
+
+## Why this exists
+
+Seven decisions about contracts that only settle where the layers meet: what a field name promises, who
+writes a piece of state, what core exports, and which records are durable.
+
+## 1. `spawn*` names the child of a spawn; unprefixed fields name the running agent
+
+Cursor's inbound adapter reads `raw.subagent_type` (the *calling* agent's identity). Claude's inbound
+adapter reads `tool_input.subagent_type` (the *target of a Task spawn*). Same field, inverted semantics.
+`model` had the same clash: on `subagent.start`/`subagent.stop` it means the child being spawned, everywhere
+else the parent's current model. This reproduced as AD-001's `blockParentFast` state being clobbered by
+every subsequent event.
+
+Fix — split the fields in `contracts/harness-event.ts`:
+
+| Field | Meaning | Cursor | Claude |
+| --- | --- | --- | --- |
+| `subagentType` | the **calling** agent's own identity | `raw.subagent_type` | top-level `agent_type` |
+| `spawnSubagentType` | the **target** of a Task spawn | `tool_input.subagent_type` | `tool_input.subagent_type` |
+| `model` | the current / parent model | `raw.model` | `raw.model` |
+| `spawnModel` | the child model being spawned | `raw.subagent_model` | `tool_input.model` |
+
+**Needs verification against a real payload:** AD-014 records `agent_type` as "subagent events only",
+quoting the reference's "present only in subagent hooks". The useful reading is "present whenever a hook
+fires *inside* a subagent's context", which would make it the caller identity on an ordinary `PreToolUse`.
+If that reading is wrong, Claude has no caller-identity signal at tool time and the read-only-subagent rail
+is Cursor-only — a genuine parity gap to be documented rather than hidden.
+
+## 2. Parent-model state is written wherever an event carries the running agent's model
+
+`upsertParentModelState` was built early and consumed by `evaluateSubagentSpawn`, but no task ever called
+it — `blockParentFast` was dead on the write side for several phases. It is now wired in `run.ts`.
+
+## 3. Core must export what entrypoints legitimately need
+
+Several constants and helpers (a stagnation follow-up string, default observability config, lessons
+rendering helpers, a gate-lock timeout error) were being duplicated by entrypoints because the core facade
+curated them out. Duplication guarantees drift. They are now exported from core and the copies deleted.
+
+## 4. `ObsKind` needs adapter-boundary members
+
+`adapter.unrecognized`, `adapter.error` and `adapter.ambiguous` fire before a provider or session is
+resolved. An earlier version bypassed the observability recorder and appended JSONL directly rather than
+widen a core type from outside core — right instinct, wrong resting place. The union is widened inside core
+instead.
+
+## 5. `subagents.blockMode` is honoured by the spawn decision
+
+A documented option must change behaviour: `deny` refuses the spawn, `ask` escalates it. An option the
+service ignores is removed rather than documented.
+
+## 6. `impeccableHook` is out of scope
+
+Relaying a third-party script's verdict is the script author's concern, not the harness's. No port,
+timeout or contract for it exists.
+
+## 7. Shell audit records must be signal-level, not debug-level
+
+`SIGNAL_KINDS` excluded `shell.end` outright, so "shell commands are audited" silently persisted nothing
+unless `debugEnabled` was on. An audit trail that requires opting in is not an audit trail — `shell.end` is
+now signal-level whenever the shell permission was not a plain allow (see
+[/measure.md](/measure.md#observability-planes)).
+
+## Also
+
+`HarnessEvent` had no generic usage field, so Cursor's `usageInPayload: true` went unread — only Claude's
+transcript path fed cost. `usage?: { inputTokens?, outputTokens?, … }` was added, populated by whichever
+provider reports it.
+
+`sandbox` is documented for Cursor only; an earlier version read `raw.sandbox` defensively for Claude with
+no confirmation it exists — verify or drop from the Claude path.
+
+## Applies to
+
+- `contracts/harness-event.ts`
+- both `*.inbound.ts` adapters
+- `core/observability`, `core/subagent-policy`, `core/gate`, `core/lesson`, `core/stagnation`
+- `core/index.ts` (the facade)
+- entrypoints (`run`, `support`, `tool-before`, `tool-after`)
+
+## See also
+
+- [/decisions/ad-001.md](/decisions/ad-001.md) — the rail item 2 restores the writer for
+- [/decisions/ad-009.md](/decisions/ad-009.md) — the earlier round of amendments this one follows
+- [/providers/index.md](/providers/index.md) — `subagentType` vs `spawnSubagentType` in the event mapping tables

package/docs/decisions/ad-017.md

@@ -0,0 +1,65 @@
+---
+type: Decision
+title: "AD-017 — The docs gate delegates to the project's tool, and the catalog is the only source of capability metadata"
+description: "Path mapping was measured reporting on 82-100% of commits and removed; the docs gate runs the repository's own staleness tool through the grind path; the capability catalog generates the wizard menu and the architecture rails table."
+tags: [decision, docs, capabilities, gates]
+timestamp: "2026-07-30"
+---
+
+# AD-017 — The docs gate delegates to the project's tool, and the catalog is the only source of capability metadata
+
+- **status**: active
+- **date**: 2026-07-30
+
+## Decision
+
+`docs.command` runs the repository's own documentation staleness tool on stop, through the same lock, artifact
+writer and failure path as the lint and test gates. `docs.severity` is `warn` or `deny`, defaulting to `warn`.
+A repository without such a tool gets no gate.
+
+`capabilities/catalog.json` is the only place a capability is described. `tools/render-capabilities.ts`
+generates the wizard's menu and the architecture rails table into marked regions, and `--check` is part of the
+gate.
+
+## Why
+
+Code changes pass lint, tests and the ship gate; the documents describing them pass nothing.
+
+The first implementation inferred staleness from a source-glob to docs-glob map. It was replayed over real
+history with its own evaluator and reported on 100% of applicable commits in one repository and 82–91% in
+another, at every granularity tried — any markdown, co-located markdown, excluding test paths, a specific
+artifact. The denominator is wrong: nearly every commit touches an area and few change documented behaviour.
+A gate that reports almost always detects nothing, so it was removed rather than kept as a fallback.
+
+The tools that do discriminate declare rather than infer. `drift` anchors a document to a file or symbol and
+hashes a normalized AST through tree-sitter. `oasdiff` compares generated specs and classifies changes by
+severity. `ast-grep` matches structure.
+
+Building an equivalent inside the harness was rejected on availability, not taste. Regex over source is the
+failure mode this project has already removed twice. The TypeScript compiler API is not guaranteed at runtime,
+since the installer runs no package install and a clean runtime has no `node_modules`. `Bun.Transpiler.scan()`
+is precise and free but Bun-only, which would make a gate's verdict depend on which runtime launched the hook.
+
+That leaves delegation, which is what `grind` already does: the harness runs the project's lint and test rather
+than implementing either. The docs gate is the same shape, so it inherits stagnation fingerprinting, gap
+feedback and progressive follow-up for free, and adds no second gate mechanism.
+
+## Consequences
+
+- Prose a catalog entry cannot express stays outside the markers: the floor table, the always-ask section, the
+  lessons subsection, and operator mode, which is posture rather than a capability.
+- Adding a capability is one edit to the catalog plus running the generator.
+- No skip token of our own: the tool owns its escape hatch, and `drift` already hardened that path by
+  requiring explicit confirmation that the document was read before re-stamping.
+- A repository with no such tool is told so and the capability stays off.
+
+## Applies to
+
+- `src/entrypoints/stop.ts`, `src/core/policy/`
+- `capabilities/catalog.json`, `tools/render-capabilities.ts`
+- `skills/harness-init/`
+
+## See also
+
+- [/decisions/ad-013.md](/decisions/ad-013.md) — the documentation bundle this gate protects
+- [/decisions/index.md](/decisions/index.md)

package/docs/decisions/ad-018.md

@@ -0,0 +1,77 @@
+---
+type: Decision
+title: "AD-018 — Three rails adopted from an external review, each off by default and declared rather than inferred"
+description: "The plan gate, the untrusted-content framing and the global observability spool were adopted after validating each candidate against this codebase; two candidates were refuted and one turned out to be an active defect. All three are opt-in, and both detectors match declared inputs instead of inferring from content."
+tags: [decision, gates, capabilities, security, observability]
+timestamp: "2026-07-30"
+---
+
+# AD-018 — Three rails adopted from an external review, each off by default and declared rather than inferred
+
+- **status**: active
+- **date**: 2026-07-30
+
+## Decision
+
+Three capabilities were added, all off by default: `planGate.enabled` (declared scope versus the diff),
+`untrustedContent.enabled` (framing for content read from outside the repository) and `obs.globalSpool`
+(cross-repository record spool).
+
+Both new detectors match **declared inputs**, never inferred ones. The plan gate reads a `HARNESS_PLAN:`
+protocol line and ignores prose about plans. The untrusted-content rail matches a fixed list of tool names,
+every MCP result, and command patterns anchored at the start of a command segment.
+
+## Why
+
+The candidates came from reading another agent-facing product. Each was validated against this codebase
+before being accepted, and the record matters more than the list:
+
+| Candidate | Outcome |
+| --- | --- |
+| Reclaim a stale grind lock | **Defect found here** — `describeHolder` ignored mtime and the stop short-circuited on it, so the steal path was unreachable |
+| Typed handoff phase machine | Refuted — the routing machine already exists in `last_gate_result`, `fingerprint_hits`, `last_failure_category` and `next_action` |
+| Persist state as it happens | Refuted — `stop.ts` already patches the handoff in every branch |
+| Plan versus diff conformance | Adopted |
+| Untrusted-content framing | Adopted |
+| Cross-repo observability | Adopted |
+| Ship evidence tied to a reproduction | Cut — depends on a `HARNESS_REPRO:` discipline nobody practises, and re-executing agent-authored argv is the riskiest surface proposed even behind the floor |
+
+Adopting on reputation would have shipped two mechanisms this product already had and missed the defect.
+
+**Off by default** is not timidity. `obs.globalSpool` writes outside the repository, which is the one thing
+an operator cannot undo by editing project policy. The plan gate changes what "done" means for a turn. A
+capability that changes either belongs in the wizard, presented with its trade-off, rather than arriving
+with an update.
+
+**Declared over inferred** is the lesson AD-017 already paid for with the docs gate: a check that fires on
+almost everything detects nothing. The untrusted rail proved it again on its first production run — the
+patterns were matched as substrings, so writing the documentation that names them tripped the rail on its
+own prose. Anchoring at the start of a command segment fixed it, and the false positive is now a test.
+
+**The plan gate's limit is stated, not hidden.** A turn that declares no plan is not gated. That is the same
+weakness that disqualified the reproduction gate; the difference is that the plan gate executes nothing, so
+the cost of the weakness is friction rather than a privilege-escalation path.
+
+## Consequences
+
+- `Policy` gained `planGate`, `untrustedContent` and `obs`; the loader merges each like every other section.
+- `ProviderPolicyDefaults` gained `untrustedTools`, so a new adapter cannot forget to declare which of its
+  own tools carry outside content — the provider contract test fails if it does.
+- The handoff carries `plan_paths`, `plan_at`, `plan_snippet` and `plan_deviations`.
+- The plan gate runs before the ship gate: a turn whose scope is invalid produced evidence for the wrong
+  change.
+- A deviation without a stated reason is refused, otherwise the gate is a formality satisfied by restating
+  the file just touched.
+- Catalog version 8, twenty-one capabilities, generated regions rewritten from the catalog per AD-017.
+
+## Applies to
+
+- `src/core/plan/`, `src/core/untrusted/`, `src/core/observability/`
+- `src/entrypoints/stop.ts`, `src/entrypoints/response-after.ts`, `src/entrypoints/tool-after.ts`
+- `capabilities/catalog.json`, `docs/concepts.md`, `docs/measure.md`
+
+## See also
+
+- [/decisions/ad-017.md](/decisions/ad-017.md) — declared over inferred, and the catalog as the only source
+- [/decisions/ad-019.md](/decisions/ad-019.md) — the identity bugs found while verifying these rails
+- [/concepts.md](/concepts.md)

package/docs/decisions/ad-019.md

@@ -0,0 +1,75 @@
+---
+type: Decision
+title: "AD-019 — A resource is identified by what it resolves to, and a declared capability must be read where it matters"
+description: "Three defects of the same shape: a lock body that parses is not a holder, a launcher path string is not the launcher file, and a capability every adapter declares was consulted by nothing. Each let a gate report a state that was not true."
+tags: [decision, gates, capabilities, providers]
+timestamp: "2026-07-30"
+---
+
+# AD-019 — A resource is identified by what it resolves to, and a declared capability must be read where it matters
+
+- **status**: active
+- **date**: 2026-07-30
+
+## Decision
+
+Three comparisons were corrected, all of the same shape — the check used a proxy for the thing instead of the
+thing:
+
+1. **A lock is a holder only if its body names one.** `readLockBody` returning non-null is not enough:
+   `JSON.parse` succeeds on `"a string"`, `42`, `{}` and `{"provider":"p"}`. `isUsableLockBody` checks for
+   `provider`, `session` and `pid`. A lock that names no holder is reclaimed after a five-second grace
+   window, alongside the existing age-based steal.
+2. **A launcher is the file, not the path string.** Wiring comparison canonicalises any argument naming the
+   launcher before deciding whether it changed.
+3. **`contextAtToolBefore` / `contextAtToolAfter` are now read.** `degrade` abstains when a `context`
+   decision lands on an event the provider cannot carry.
+
+## Why
+
+Each of the three let a gate report something untrue, which is worse than a gate that is absent.
+
+The lock case cost **120 seconds per stop, indefinitely**. `describeHolder` returned null for an unreadable
+body, so the stop fell through to `withGateLock`, which reclaimed only by mtime — a recent corrupt file was
+never stale, so the loop ran to the deadline and abstained with an `adapter.error`. The escape was deleting
+the file by hand. It was first written off as safe degradation; that was wrong. An unreadable file blocking
+every stop for two minutes is a defect, and the grace window has to outlast `tryAcquire`'s create-then-write
+gap by orders of magnitude without approaching the stale threshold — five seconds is roughly four orders
+above the gap and twenty-four times below the wait it replaces.
+
+The launcher case made `doctor` report "detected but not wired" for a provider whose eleven hooks were wired
+and firing, on every from-a-clone install, because `settings.json` holds the symlinked install path while the
+runtime resolves the checkout behind it. `bin/tlc-exec.mjs` already documents this hazard and reads `argv[1]`
+to preserve the caller's path — but `bin/tlc` walks `readlink` before invoking it, so the protection never
+applied to a CLI reached through `~/.local/bin/tlc`. Rather than unpick that resolution, the comparison was
+made canonical, which also stops `update` from rewriting a `settings.json` that was already correct.
+
+The capability case was found by verifying an acceptance criterion that assumed a degrade path existed. Both
+adapters declared the field and nothing consulted it, so a `context` returned on an unsupported event was
+rendered into a field the provider ignores and lost silently, while the caller believed it was delivered.
+Abstaining is the honest degradation: `context` is informative, so unlike `ask` there is nothing to escalate
+to.
+
+## Consequences
+
+- `describeHolder` returns null for a stale lock and for one whose body names no holder, so a caller that
+  short-circuits on it falls through to the reclaim path instead of reporting a dead owner.
+- `withGateLock` accepts `unreadableGraceMs`; `GATE_LOCK_UNREADABLE_GRACE_MS` is 5 000 ms.
+- Wiring equality is canonical, so a symlinked install is recognised and not rewritten. Only strings naming
+  the launcher are resolved: a foreign hook's own script path is untouched.
+- The untrusted-content rail keeps its own capability check in addition to `degrade`, because reaching
+  `degrade` would already have consumed the once-per-turn marker and cost the whole turn its framing.
+- A test that passed for the wrong reason was found the same way: it hardcoded `WebFetch` while
+  `providers[0]` is Cursor, whose untrusted list does not contain it. The tool name now comes from the
+  provider's own list.
+
+## Applies to
+
+- `src/core/gate/gate.lock.ts`
+- `src/providers/claude/claude.wiring.ts`, `src/providers/provider.degrade.ts`
+- `src/entrypoints/tool-after.ts`, `tools/doctor.ts`
+
+## See also
+
+- [/decisions/ad-018.md](/decisions/ad-018.md) — the rails whose verification surfaced these
+- [/diagnose.md](/diagnose.md) — operator-facing symptoms of all three

package/docs/decisions/ad-020.md

@@ -0,0 +1,88 @@
+---
+type: Decision
+title: "AD-020 — One resolution for the install path, one source for posture, and a config that only advertises what it reads"
+description: "The wrappers collapsed the install symlink, so generated shims named the checkout; status derived posture separately from the loader and disagreed with it; the observability config section was read by nothing. Each is fixed at the root, and a gate refuses any operator home path in a tracked file."
+tags: [decision, runtime, cli, observability, security]
+timestamp: "2026-07-30"
+---
+
+# AD-020 — One resolution for the install path, one source for posture, and a config that only advertises what it reads
+
+- **status**: active
+- **date**: 2026-07-30
+
+## Decision
+
+1. **`resolveHarnessHome` returns the conventional install path when `realpath` proves it names the same
+   runtime as the invoked launcher.** An explicit `TLC_HOME` still wins; a relocated install is untouched.
+2. **`status` reads `loadPolicy`.** It reports the posture a hook resolves and, under `--json` and in the text
+   form, where the mode came from (`config`, `file` or `flag`).
+3. **`Policy.obs` carries `globalSpool`, `includePayloads`, `maxAttrChars`, `sessionCostAlertUsd` and
+   `retentionDays`.** The `observability` section is removed, not honoured. `debugEnabled` is deliberately
+   absent.
+4. **A tracked file may not contain an operator's home path**, enforced by a test over `git ls-files` with a
+   per-line `leak-gate-allow` marker for fixtures.
+5. **Project shim hooks stay untracked**, and that is a decision rather than a deferral — see below.
+
+## Why
+
+**One resolution.** Both bash wrappers walk `readlink` before invoking the launcher, so `argv[1]` and `binDir`
+name the checkout. `resolveHarnessHome` documented that exact hazard and still returned the collapsed path.
+Everything derived from it is written to disk or compared: `init` wrote shim hooks pointing at a checkout that
+exists only on the machine that ran it, and `doctor` compared a checkout-shaped path against the install-shaped
+one recorded in the provider's config, reporting healthy wiring as broken. Preferring the conventional path
+only when `realpath` agrees fixes the source instead of each symptom, and refuses to guess: a deliberately
+relocated install still wins.
+
+**One source for posture.** `status` recomputed mode and grind from flag files and defaulted to `solo`. This
+repository, whose policy sets `heads-down`, therefore reported `mode: solo, grind: OFF` while every hook
+resolved focus with grind forced on. A second derivation of the same fact is the whole reason they could
+disagree. Reporting the origin matters as much as the value: the question after a surprising posture is always
+*why*, and a leftover flag is the usual answer.
+
+An earlier reading of this — that `tlc harness grind on` and `mode` were inert — was **wrong**, and is recorded
+as refuted: `policy.loader.ts` has always read those flags. Only the reporting was broken.
+
+**A config that only advertises what it reads.** The `observability` block sat in the example config and in
+this repository's policy, was documented in `concepts.md` with an instruction to set `debugEnabled: true`, and
+was read by nothing — the planes came from a module constant. Values happened to match the defaults, so it
+never diverged visibly; it simply promised configuration that did not exist. Honouring the key would have been
+back-compat this project refuses ([/decisions/ad-003.md](/decisions/ad-003.md)), so the fields that have a real effect moved to `obs` and the key was
+deleted.
+
+`debugEnabled` was implemented, then removed before shipping: every event that resolves to debug level is
+emitted with the audit configuration, which forces debug on for the audit trail (AD-016 item 7). Exposing a
+field with nothing to switch would have repeated the mistake being corrected. A mutation test confirmed the
+same danger elsewhere — `retentionDays` initially reached the runtime with no test covering it, and the
+mutation that ignored it survived until one was added.
+
+**The leak gate.** This product installs with a shell one-liner and tracks its own bundles, so a generated file
+is exactly where an account name slips in unnoticed. A denylist of one name would pass on every other machine,
+so the rule is the shape of the path. An audit before adding it found the tree clean.
+
+## Consequences
+
+- `bin/tlc-exec.d.mts` declares the four-argument resolver; the `.mjs` and its declarations are separate files
+  and both must move together.
+- `StatusReport` gained `modeOrigin`. Any consumer of `status --json` sees one more field.
+- `tlc harness obs prune` reads retention from policy, so two projects on one machine can differ.
+- The example config and this repository's policy no longer carry `observability`; a project that copied it
+  loses nothing, because nothing read it.
+- Fixtures that need a realistic account name carry `leak-gate-allow` on that line.
+
+**Project shims are not version-controllable, by decision.** A portable form needs shell expansion, and `args`
+arrays carry none — so every hook of every provider would need `sh -c` (or `cmd /c` on Windows), paying
+permanent per-hook latency for a file `tlc harness init` regenerates in under a second. They are ignored and
+documented instead.
+
+## Applies to
+
+- `bin/tlc-exec.mjs`, `bin/tlc-exec.d.mts`, `bin/tlc-cli.ts`
+- `src/core/policy/`, `src/entrypoints/support.ts`, `tools/obs-cli.ts`
+- `config.example.json`, `.gitignore`
+
+## See also
+
+- [/decisions/ad-019.md](/decisions/ad-019.md) — the same identity-versus-proxy mistake in three other places
+- [/decisions/ad-003.md](/decisions/ad-003.md) — no backward compatibility
+- [/diagnose.md](/diagnose.md), [/concepts.md](/concepts.md)

package/docs/decisions/ad-021.md

@@ -0,0 +1,57 @@
+---
+type: Decision
+title: "AD-021 — A gate command that never resolved is a config fault, and a recipe runner does not receive file arguments"
+description: "The grind gate appended changed files to every lint/test argv. Against a recipe runner that reads the first path as a second target, the gate failed on code it never executed, and the failure was classified as verification — a follow-up that instructs the agent to fix findings without deleting tests, aimed at healthy code."
+tags: [decision, grind, gate, config]
+timestamp: "2026-07-30"
+---
+
+# AD-021 — A gate command that never resolved is a config fault, and a recipe runner does not receive file arguments
+
+- **status**: active
+- **date**: 2026-07-30
+
+## Decision
+
+1. **`grind.appendFiles` decides whether changed files reach the lint/test argv**, with modes `auto`
+   (default), `always` and `never`. `auto` appends, except to a recipe runner.
+2. **A recipe runner never receives file arguments.** The set is `just`, `make`, `task`, `mise` and `rake`,
+   matched on the executable name after stripping the directory and a Windows `.exe`/`.cmd`/`.bat` suffix.
+3. **A gate whose command never resolved is classified `config`, not `verification`.** The signal is exit
+   127, or a runner message that names an unresolved target: `does not contain recipe`, `No rule to make
+   target`, `unknown recipe`, `Missing script:`, `task "…" does not exist`, `Don't know how to build task`.
+
+## Why
+
+A project configured `testCommand` as a recipe runner invocation. The gate ran
+`just <recipe> <path>.test.ts`; `just` read the path as a second recipe and exited 1 in 53ms with
+`justfile does not contain recipe`. Nothing about the code caused it, and no edit to the code could clear it.
+
+The second half is the damaging one. `classifyGateFailure` maps the `test` gate to `verification`, whose
+follow-up reads *"Fix the test findings without suppressions or deleted tests"*, reinforced by a lesson that
+forbids deleting or skipping tests. Pointed at a malformed command, that text is an instruction to go edit a
+test file that passes — in the observed case a file being edited concurrently by another session, on another
+branch. The harness was steering an agent into damaging healthy work, and the loop counter plus stagnation
+detection kept it there.
+
+`config` already existed as a category, with the suggestion *"Check .tlc/harness/config.json commands/paths;
+run harness doctor."* The fix routes to it rather than inventing a concept.
+
+## Trade-offs
+
+Detection is a closed set of runner names and messages, not inference. A runner outside the set that also
+rejects file arguments still needs `appendFiles: "never"`; that is deliberate, because guessing at argv
+semantics is how the original bug reached a user. The message patterns are specific strings rather than a
+generic `command not found`, so a test whose own output mentions a missing command is not misfiled — exit 127
+covers the real missing-binary case.
+
+`auto` changes behaviour for an existing config that pairs a recipe runner with a file-scoped expectation:
+the gate now runs the recipe as written, over the whole suite, instead of failing. That is the intended
+correction.
+
+## Not decided here
+
+The gate scopes files from `listChangedRepoFiles`, which reads the whole dirty worktree. When two sessions
+share a checkout, one session's gate sees the other's edits. The observed incident surfaced that, and it is
+not addressed: there is no per-session record of edited paths to intersect against, and adding one is a
+separate change to the tool-after path.