@tech-leads-club/harness-toolkit 0.2.1

package/docs/decisions/ad-058.md

@@ -0,0 +1,97 @@
+---
+type: Decision
+title: "AD-058 — Gates diff against the turn's base, and language knowledge is one table"
+description: "A turn that commits used to erase its own violations, because every stop-time gate diffed against HEAD. The comparison point is now the revision the turn started at. Comment syntax moves from three hand-written regexes to one catalog module, after measuring that a grammar-based parser would not remove per-language knowledge."
+tags: [decision, comments, gates, git, languages]
+timestamp: "2026-08-10"
+migration: "If a project has the comment gate on, expect it to start firing on turns that commit and on languages it never covered. Nothing changes in your config."
+---
+
+# AD-058 — Gates diff against the turn's base, and language knowledge is one table
+
+- **status**: active
+- **date**: 2026-08-10
+
+## Decision
+
+1. **`listChangedRepoFiles` and `listAddedLines` take a base revision**, and `stop` passes the sha recorded at
+   `prompt.submit`. Absent, the base is `HEAD` — the previous behaviour exactly.
+2. **Comment syntax is one catalog module**, `comment-syntax.catalog.ts`: line prefixes, block pairs and
+   continuation prefixes per extension. Adding a language is an entry, never code.
+3. **No parser, and no runtime dependency.** Measured against the alternatives below.
+4. **An unknown extension yields no findings and is named** in the observation record, rather than reading as
+   "the property held".
+5. **`tlc harness policy accept` says which project it applied to**, gains `--all`, and says so plainly when the
+   project it ran in has no recorded baseline.
+
+## Why
+
+**A commit inside the turn erased the violation.** `listAddedLines` ran `git diff --unified=0 HEAD`, so once a
+turn committed, its own added lines were "pre-existing" and the file list was empty — which made
+`codeTargets.length > 0` skip the comment gate outright. Reported from a project with
+`comments: { enabled: true, mode: "strict" }` where a turn added a docstring and a JSDoc block and nothing
+fired; the task was named "schema v2 + tests + commit". This was never comment-specific: the plan gate and the
+ship gate read the same list.
+
+The turn boundary is `prompt.submit`, which already resets the untrusted-content marker for the same reason, so
+the base has an obvious producer and one writer.
+
+**A grammar would not have removed the per-language knowledge.** The research finding that decided this: tree-sitter
+grammars name comment nodes inconsistently — `comment`, `line_comment`, `block_comment`, and `string` for a Python
+docstring — so a per-language kind allowlist is required whichever tool is used. What a parser adds is cost, not
+coverage:
+
+| Option | What it costs | Verdict |
+| --- | --- | --- |
+| `@ast-grep/napi` | platform-specific native binaries across eight targets; only JS-ecosystem languages built in, the rest via `registerDynamicLanguage` | Refused: [/decisions/ad-012.md](/decisions/ad-012.md) ships no binary |
+| tree-sitter WASM | one grammar `.wasm` per language, megabytes into a 1.2 MB package, **plus** the kind allowlist | Refused: cost without the benefit |
+| Catalog module | one table, zero dependencies, zero I/O | Chosen |
+
+So the shape that answers the objection is not a parser. It is **one scanner and one table**: the per-language
+knowledge exists in exactly one place, as data, and the code that reads it never grows.
+
+**A module rather than a data file.** The first version read `comment-syntax.json` from the runtime home and
+promptly broke its own suite, because the suite runs with a deliberately empty runtime home
+([/decisions/ad-042.md](/decisions/ad-042.md)). A hook is a process, so a data file is one more read per
+invocation and one more path that resolves differently under Bun, under `dist/` and under a test. Bundled, it
+costs nothing and behaves identically everywhere. The trade-off is real and stated below.
+
+**Following the modular rules the repository already applies**: the catalog is the external vocabulary, and
+`comment-syntax.store.ts` is the anti-corruption layer over it. The scanner asks "how does this file write a
+comment" and is answered in the domain's own type; it knows nothing about extensions, languages or file formats.
+The aggregate stays flat — catalog, store, types, service, all in `comment-policy/`.
+
+## Trade-offs
+
+**A delimiter scanner cannot see a comment inside a string literal, and cannot track a block across
+non-contiguous diff hunks.** Neither could the regexes it replaces. What it can do is stop guessing: `#` is a
+comment in Python and a private field in TypeScript, and the catalog is what knows the difference.
+
+**Adding a language now requires a release.** With a JSON file an operator could have added one locally. That
+route also made the scanner depend on a file that may not exist, and the language a project needs is a change
+worth shipping to everyone rather than carrying privately.
+
+**Coverage is finite and now visible.** Forty-one languages, a hundred-odd extensions. A file outside that set
+produces no findings, and the observation record names its extension — which is the honest reading, but it is
+still a gap rather than a guarantee.
+
+**The gate will start firing where it was silent.** A project with the gate on and turns that commit will now be
+blocked by comments it had been landing. That is the fix working, and it is the reason this decision carries a
+migration note.
+
+**`--all` reduces typing, not authority.** It expands to what diverged at that moment, so it is still per source
+and still refuses without a terminal. The four locks of
+[/decisions/ad-030.md](/decisions/ad-030.md) are untouched — they govern who clears a divergence and from where,
+never how much they type.
+
+## Not decided here
+
+- **Making acceptance machine-wide.** The runtime config is a machine-scoped file, so a divergence in it blocks
+  every project at once and has to be accepted in each. Fixing that needs a registry of projects the harness
+  does not have.
+- **Regenerating the catalog from upstream language-configuration files.** The shape allows it; a tool that
+  fetches and rewrites the module is a separate change.
+- **Tracking block state across hunks.** It would need the whole file rather than the diff, and the gate is
+  about what the turn added.
+- **Whether `doctor` should report a runtime older than its package.** Noted in
+  [/decisions/ad-056.md](/decisions/ad-056.md) and still open.

package/docs/decisions/ad-059.md

@@ -0,0 +1,82 @@
+---
+type: Decision
+title: "AD-059 — A rail never writes a field it reads, and a counter reads the plane its events land on"
+description: "The idle-turn gate blocked the same turn four times in a row. Two defects compounded: its activity counter read the signal plane, where a successful tool call never lands, and the rail wrote the `blockers` that its own precondition reads. Neither is specific to that rail, so both are stated as rules."
+tags: [decision, observability, gates, idle-turn]
+timestamp: "2026-08-10"
+---
+
+# AD-059 — A rail never writes a field it reads, and a counter reads the plane its events land on
+
+- **status**: active
+- **date**: 2026-08-10
+
+## Decision
+
+1. **`readTurnActivity` reads both planes.** `obs.jsonl` carries the turn boundary; `debug.jsonl` carries the
+   work. The window boundary is therefore a timestamp rather than a position in one file.
+2. **The counted kinds are the ones a turn actually produces**: `tool.end`, `shell.end`, `file.edit`,
+   `file.read`, `mcp.end`, alongside the `.start` and `.fail` kinds already listed.
+3. **The idle-turn rail no longer writes `blockers`.** It writes `next_action` and the failure category. No rail
+   may write a field that its own trigger reads.
+4. Both are asserted by tests that a mutant kills, because both failures were invisible to a green suite.
+
+## Why
+
+**The counter read the one plane its events cannot reach.** `resolveObsLevel` sends a successful tool call to
+`debug`, and `SIGNAL_KINDS` does not contain `tool.end`, `shell.end` or `file.edit`. `readTurnActivity` read
+`obs.jsonl` — the signal plane — so `toolCalls` was structurally zero for every turn whose work went well.
+Measured on this repository's own state:
+
+| Plane | `tool.end` | `shell.end` | `file.edit` |
+| --- | --- | --- | --- |
+| `obs.jsonl` — what the counter read | 0 | 0 | 0 |
+| `debug.jsonl` | 322 | 1909 | 981 |
+
+Three thousand records of work in the file next to the one being read. The rail's stated property — that it
+counts events the harness recorded and so no wording can satisfy it
+([/decisions/ad-027.md](/decisions/ad-027.md)) — was exactly inverted: **nothing** could satisfy it.
+
+**The rail manufactured its own precondition.** `endedWithoutActing` fires only with open work, and open work is
+`blockers || previous_gaps || pending || in_progress`. The rail then wrote
+`blockers: "Turn ended with open work and nothing attempted."`. So one firing guaranteed the next, and it
+returned `continue` before reaching the clean-stop path that clears `blockers` — the operator saw the same
+BLOCKED four times in a row, with the agent running tools and reporting a clean tree between each one.
+
+Either defect alone would have been survivable: a wrong counter with no self-feeding write stops when the
+blocker clears, and a self-feeding write with a working counter stops as soon as the agent does anything. Together
+they made a rail with no exit.
+
+**Both generalise, which is why they are decisions and not fixes.** A counter that reads one plane is a bug any
+rail can repeat, since which plane an event lands on is decided by `resolveObsLevel` and not by the rail. A rail
+writing a field its trigger reads is a loop any rail can build. The two rules are cheap to check in review and
+neither had been stated.
+
+## Trade-offs
+
+**Reading two planes doubles the tail read.** Two files, 500 records each, once per stop. The stop hook already
+runs lint and test, so this is not where the time goes — but it is not free, and a third plane would be worth
+questioning.
+
+**`debug.jsonl` is written because one code path forces it on.** `debugEnabled` is `false` in the default config
+and the tool entrypoints record with `OBS_CONFIG_AUDIT`, which sets it true so the audit trail persists
+([/decisions/ad-016.md](/decisions/ad-016.md) item 7). The counter now depends on that arrangement. It is
+deliberate and tested, but it is a dependency on a decision made for another reason.
+
+**The rail is now weaker against one shape.** A turn that opens a file and answers without changing anything
+counts as activity, because `file.read` counts. That is intended — reading is attempting — but it means "asked
+instead of acting" no longer catches an agent that reads and then asks.
+
+**Nothing retroactively clears a stuck handoff.** A project already carrying
+`blockers: "Turn ended with open work and nothing attempted."` keeps it until a clean stop clears it, which now
+happens as soon as a turn does anything. No migration note, because the next successful turn fixes it.
+
+## Not decided here
+
+- **Whether `resolveObsLevel` should promote tool events to signal.** It should not: the signal plane exists to
+  be readable, and 1909 shell calls would drown it. The consumer moving to the right plane is the correct fix.
+- **A dedicated per-turn activity counter** instead of mining the obs planes. Cheaper to read and one more thing
+  to keep in step with what actually happened; the planes are already the record of record.
+- **Whether the idle-turn rail should be on by default.** Unchanged: off, and offered with its trade-off.
+- **Clearing `blockers` on a turn that only answers.** That is the rail's whole subject, and deciding it here
+  would be deciding it twice.

package/docs/decisions/ad-060.md

@@ -0,0 +1,75 @@
+---
+type: Decision
+title: "AD-060 — The gate records the environment it ran under, and names it only once the cheap explanations are spent"
+description: "A gate that fails because the hook's environment points its fixtures at the real project is indistinguishable, from the follow-up, from a gate that fails because the code is wrong. It cost four stop loops. The artifact now records which project-scoping variables were set, and the follow-up names them from the second attempt — never the first, because they are set on every hook invocation."
+tags: [decision, gates, observability, environment]
+timestamp: "2026-08-12"
+---
+
+# AD-060 — The gate records the environment it ran under, and names it only once the cheap explanations are spent
+
+- **status**: active
+- **date**: 2026-08-12
+
+## Decision
+
+1. **Every gate artifact records which project-scoping variables were set** when it ran, by name, as an empty
+   list when none were. Always, as a fact.
+2. **`gate.outcome` carries the same reading**, so `obs report` and `attest` can answer it after the fact.
+3. **The follow-up names them from the second attempt onward**, never the first.
+4. **The names live in `src/platform/env-scope.ts`**, once. `core/` asks which are set and never spells one,
+   because `tools/check-boundaries.ts` forbids a vendor identifier there.
+5. **A test asserts `tools/test-env.names.mjs` lists the same names.** It is a `.mjs` module loaded by
+   `node --import` and cannot import the TypeScript one, so agreement is asserted rather than shared.
+
+## Why
+
+**Measured, on this repository, against its own author.** The suite passed 1298/1298 from a shell and failed
+nine assertions from inside the hook, four stop loops in a row. The cause was that the project's
+`grind.testCommand` omitted the import that neutralises the provider's project-directory variable — the exact
+hazard `tools/test-env.mjs` documents in prose:
+
+> Inside a hook that variable is always set, so 22 tests that build a fixture in a temp directory silently read
+> policy and state from the real repository instead. The suite passed from a shell and failed from inside a hook.
+
+The harness held both halves of that fact — the gate's command and output, and the variables in its own
+environment — and joined neither. The follow-up said "fix the test findings", the autopilot said "do not invent
+a different plan", and the lesson store said "do not delete tests". Every one of those was right and none of
+them was the answer.
+
+**The second attempt, not the first, and that is the whole design.** A project-scoping variable is set on every
+hook invocation under some providers, so an unconditional note would appear on every gate failure this product
+ever reports. That is the alarm [/decisions/ad-034.md](/decisions/ad-034.md) removed from the update digest —
+one that fires on a healthy run is one the reader learns to scroll past, and it takes the next real one with it.
+By the second attempt the cheap explanations are spent, and the escalation machinery for exactly that already
+exists.
+
+**A fact in the record, a hypothesis in the follow-up.** The note says the variables were set and names the
+command that settles it. It does not say they caused the failure, because nothing in the harness can know that:
+whether a variable changes an outcome depends on what the command does with it. Recording is free and always
+correct; diagnosing would be a guess that either accuses a healthy run or excuses a real failure.
+
+## Trade-offs
+
+**The note can be wrong-footed.** A genuine code failure on the second attempt now carries a paragraph about the
+environment. It costs a few hundred characters and one command to rule out; the alternative cost four loops.
+
+**Two declarations of one list.** The hermetic loader cannot import the TypeScript module, so the names exist
+twice with a test holding them together. One of them was already missing an entry once, which is the evidence
+that the test is the load-bearing part.
+
+**It does not fix the underlying divergence.** A project can still configure a gate command that differs from
+the one its own suite needs, and the harness must not read or rewrite it — that is the operator's, on the policy
+surface. This makes the divergence visible on the second failure instead of the fourth.
+
+**`scopedEnv` is absent on an artifact written before this shipped**, so the first failure after an upgrade
+reports no environment. The reader treats absent as unknown rather than as none.
+
+## Not decided here
+
+- **Running the gate a second time with the variables cleared.** It would answer the question outright and
+  double the cost of every failure to do it. If the note proves insufficient, this is the next step.
+- **`doctor` comparing the project's gate command against anything.** There is nothing correct to compare it
+  to — the harness does not know what a given repository's suite needs.
+- **Recording the full environment.** Only variables that name *which project* are recorded. Anything wider is
+  a secrets surface.

package/docs/decisions/ad-061.md

@@ -0,0 +1,68 @@
+---
+type: Decision
+title: "AD-061 — A decision that refuses names its rule, and degrading preserves it"
+description: "`rule` becomes required on deny and ask. Of sixteen producers, four carried one, so the report that attributes refusals by rule had holes exactly where operators were confused. Degrade preserved none at all — the one place a decision changes shape."
+tags: [decision, contracts, observability, rules]
+timestamp: "2026-08-12"
+---
+
+# AD-061 — A decision that refuses names its rule, and degrading preserves it
+
+- **status**: active
+- **date**: 2026-08-12
+
+## Decision
+
+1. **`rule` is required on `deny` and `ask`.** The type is the enforcement.
+2. **`degrade` preserves the rule it was given** and never replaces it. The one rule it may name is its own,
+   `rewrite-unavailable`, for the conversion where the incoming decision refused nothing.
+3. **Each aggregate owns its rule names as a constant**, following `SHELL_RULES`, which already did.
+4. **One rule per reason, not one per aggregate.** A spawn refused by the allowlist and a spawn refused because
+   the parent is in Fast mode are different facts.
+5. `allow`, `context`, `continue`, `abstain` and `rewriteInput` are untouched — they refuse nothing.
+
+## Why
+
+**A teammate could not tell harness behaviour from model behaviour**, and the command that answers that —
+`tlc harness obs report` — attributes refusals by rule. With `rule` optional and four producers of sixteen
+carrying one, the table was blank precisely where he had been confused: the subagent allowlist refused his
+spawn and the report could not say so.
+
+**The type is the enforcement, and that is a measured claim.** Making the field optional again produces zero
+compiler errors across the whole repository — nothing else would catch a producer that forgot. Flipping it to
+required produced 32 errors in seven files in one command, which is the complete list, obtained without writing
+a checker that would then need keeping in step.
+
+**Degrade was the worst case and had no attribution at all.** `ask` becomes `deny` where the provider cannot
+ask; `rewriteInput` becomes `ask` where it cannot rewrite. Both dropped the rule. That is the one place a
+decision changes shape between the rail that made it and the operator who reads it, so it is exactly where the
+attribution matters most — and inventing a rule there would have blamed the transport for a rail's decision.
+
+**One rule per reason.** Five distinct refusals shared one `block()` helper in the subagent aggregate. Naming
+them `subagent-allowlist`, `subagent-parent-fast`, `subagent-blocked-pattern`, `subagent-model-required` and
+`subagent-min-effort` is what lets a report say which one fired, which was the original complaint.
+
+## Trade-offs
+
+**Every future producer must name a rule.** That is the point, and it is a real constraint on anyone adding a
+rail: the name appears in `rule=…` in messages operators read, so it is a small piece of public interface
+rather than an internal label.
+
+**Test fixtures now carry a rule too** — twenty-six of them. They say `test-deny` and `test-ask`, which is
+noise in the fixtures and the price of the type being unconditional. An optional field with a checker would
+have spared them and would not have been enforced anywhere the checker did not look.
+
+**Nothing prevents an empty or duplicated name.** The type accepts any string. A test asserts the declared
+constants are non-empty, kebab-case and unique; a producer that inlines a literal is outside it.
+
+**The rule set is not enumerable from one place.** A closed union in `contracts/` would give that, and would
+make adding a rail a two-file change for no gain the required field does not already provide. `tlc harness why`
+will group by whatever it finds rather than by a list it has to be told.
+
+## Not decided here
+
+- **A closed union of rule names.** Rejected above; revisit if `why` needs to render a rule the operator has
+  never seen with an explanation rather than a name.
+- **Recording every refusal in obs.** `rule` being present makes attribution possible; whether every rail also
+  writes an obs record is a separate gap, and the next thing to check.
+- **Renaming existing rules.** `secret-access` and its siblings already appear in messages people have read.

package/docs/decisions/ad-062.md

@@ -0,0 +1,72 @@
+---
+type: Decision
+title: "AD-062 — One command answers whether the harness did that, and says so plainly when it did not"
+description: "Hooks are invisible by construction: the harness answers the host and the host decides whether to show it. `tlc harness why` prints the last decisions with the rule behind each, derived from the two obs planes, and states in words when there were none — which is the reading no other command gives."
+tags: [decision, observability, cli, legibility]
+timestamp: "2026-08-12"
+---
+
+# AD-062 — One command answers whether the harness did that, and says so plainly when it did not
+
+- **status**: active
+- **date**: 2026-08-12
+
+## Decision
+
+1. **`tlc harness why [n]`** prints the last n harness decisions, newest first: the event answered, the verdict,
+   the rule, and one line of detail. Default 10.
+2. **It is a first-class verb**, not `obs why`. It routes to the obs entry, and the alias is the interface.
+3. **A window with no decision says so in words**, and that sentence is the feature.
+4. **It derives from the two obs planes and nothing else.** No new producer, no second index.
+5. **Read-only, `--json` like every read command.**
+
+## Why
+
+**The complaint is structural, not a bug.** A hook answers the host; the host decides whether to render it. So
+a rail can fire and the operator sees only that the agent behaved differently — "só muda o comportamento e não
+fala". Reverse-engineering which behaviour was a rail is the state two people on this team were in.
+
+**The two commands that exist answer other questions.** `obs report` is a session rollup — right for "what did
+this session cost and what fired", wrong for "what just happened". `obs live` is a firehose of every recorded
+event. Neither is what someone reaches for in the moment.
+
+**The empty case is the whole point.** Every other command shows what happened; none of them can say *nothing
+here was mine*. An empty table would leave the reader exactly as unsure as before, so the absence of decisions
+is rendered as a sentence:
+
+> No harness decision in this window. Whatever you just saw was the model, not a rail — the harness allowed
+> everything it was asked about.
+
+**It reads both planes for the same reason the idle-turn counter now does.** The signal plane holds the
+refusals, the debug plane holds the allows, and an allow is a decision: "it let it through" is exactly the
+reading someone is looking for ([/decisions/ad-059.md](/decisions/ad-059.md)).
+
+**It required [/decisions/ad-061.md](/decisions/ad-061.md) first.** With `rule` optional, this command would
+have rendered "deny, unattributed" precisely on the rail that started the complaint.
+
+## Trade-offs
+
+**It shows decisions, never reasoning.** The rule name is a pointer; the reasoning is in the decision record it
+cites. Rendering an explanation inline would put a second copy of every rationale in the CLI, to drift from the
+one in `docs/decisions/`.
+
+**Activity is excluded, and that is a judgement.** A turn reading forty files is not the harness doing
+something, so it is not listed — but if the interesting question ever becomes "what did the agent do", this is
+the wrong command and `obs live` is the right one.
+
+**Historical records read as `unattributed`.** Anything written before rules were required carries none. It
+resolves itself as those records age out of the window; until then it is a name for "the record does not say"
+rather than a blank, because a blank reads as "no rule applied".
+
+**A record that no producer writes cannot be shown.** The command is only as complete as the obs planes. Every
+refusal is recorded today — `recordRefusal` covers the non-shell path and the shell rail owns its own — but a
+rail added later that decides without recording would be invisible here, and nothing in the build would catch
+that.
+
+## Not decided here
+
+- **Failing the gate on a rail that decides without recording.** It is the same shape as the required `rule`
+  and would close the last gap above; it needs a way to enumerate rails that is not a hand-written list.
+- **Showing the follow-up text.** A blocked stop appears as a gate outcome, not as the paragraph the agent
+  received. The paragraph is in the transcript; duplicating it here would be a second copy that can disagree.
+- **A `--since` window by time.** `n` was enough for the question people are actually asking.

package/docs/decisions/ad-063.md

@@ -0,0 +1,84 @@
+---
+type: Decision
+title: "AD-063 — One palette for human output, and a checker keeping it out of everything else"
+description: "The CLI's human surfaces share one truecolor palette and symbol set, written without a dependency. Colour is off unless stdout is a terminal, and `check-boundaries` refuses the style module in `providers/` and `entrypoints/` — an escape reaching parsed output already sent an agent to fix a file that does not exist."
+tags: [decision, cli, output, boundaries]
+timestamp: "2026-08-12"
+---
+
+# AD-063 — One palette for human output, and a checker keeping it out of everything else
+
+- **status**: active
+- **date**: 2026-08-12
+
+## Decision
+
+1. **`src/platform/style.ts` owns the palette and the symbols.** One place, so a surface cannot invent its own.
+2. **No dependency.** Truecolor escapes written directly, because this package has none and ships no binary
+   ([/decisions/ad-012.md](/decisions/ad-012.md)).
+3. **Colour is off unless stdout is a TTY**, and off under `NO_COLOR` or `--no-color`.
+4. **`providers/` and `entrypoints/` may not import it**, enforced by `tools/check-boundaries.ts` with the rule
+   `styles-machine-readable-output`.
+5. **`why` gained substance with the paint**: a verdict summary, a date on any record not from today, and the
+   `rule=` prefix kept because that is what people grep for.
+
+## Why
+
+**The output was asked about and the answer was no.** `tlc harness why` shipped as ten lines of
+undifferentiated monospace, six of them `rule=unattributed`, every timestamp reading `19:23:05` with no date —
+so a window spanning three days looked like one burst. Colour was the smaller half of the fix.
+
+**The TTY check is load-bearing, not politeness.** This CLI's output is redirected into files, quoted into gate
+follow-ups, and read by the repository's own checkers. An escape in any of those is a defect, and it is not
+hypothetical: a colour escape ends `[39m`, `39m` matched the path pattern in gate output, and the autopilot told
+an agent by name to fix `39msrc/entrypoints/__test__/tool-after.test.ts` — a file that does not exist. That was
+output the harness *read*; this decision adds output the harness *writes*, so the rule gets a checker rather
+than a convention.
+
+**The boundary is where it is because of what those directories do.** `entrypoints/` renders text that goes to
+a host and to `--json`; `providers/` serialises the decision the host parses. Neither has a human reader. The
+check costs one import scan and removes a whole class of defect from review.
+
+## Trade-offs
+
+**Two ways to print now.** A human surface takes a `Style`; everything else does not. A renderer shared between
+the two has to take the style as a parameter and default to plain, which is one more thing to get right — and
+the checker only catches the import, not a styled string threaded through by hand.
+
+**Truecolor assumes a modern terminal.** No 256-colour or 16-colour fallback: a terminal that cannot do
+truecolor shows the escape's effect wrong rather than degrading. `NO_COLOR` is the escape hatch, and adding
+fallback tiers would be palette code for a case nobody on this team has.
+
+**The palette is not configurable.** One set of hex values, consistent with the team's other tooling. A theme
+option would be a config surface for a preference nobody has asked for.
+
+**`why`'s summary counts verdicts, not importance.** Three floor denials of the same command read as "3 denied",
+which is accurate and not the same as "one thing went wrong three times". Grouping would be a judgement about
+which repeats matter.
+
+## The standard is structural
+
+A screen describes its content as a `Screen` — a title, a summary, sections of label/value rows — and one
+renderer in `src/platform/screen.ts` decides spacing, alignment and colour. A screen cannot be off-standard
+because it cannot express layout.
+
+`tools/check-screens.ts` is a gate step at budget **zero**: every exported `*Text` renderer either goes through
+`render` or takes a `Style`. A new one that does neither fails the gate. It was shipped at a budget of fourteen
+and lowered in two passes, because a checker that merely allowed a list would have hidden the remainder.
+
+**The plain form is the contract.** Colour wraps; it never reshapes. `obs live` stays tab-separated with a full
+ISO timestamp because that output is piped — `cut -f2` gives the kind — and three tests caught a restyle that
+had quietly dropped wording the reader needed: `DIVERGED mid-session`, `N pass / N fail`, and the phrase that
+says what a garden verdict means. Layout moved; text did not.
+
+`obs report` produces two things from one rollup: `sessionReportMarkdown` for the file people paste into a pull
+request, and `sessionReportScreen` for the terminal. One string for both would have put escapes in the artifact.
+
+## Not decided here
+
+- **A test that the two `obs report` renderings agree.** They read the same rollup and can drift in what they
+  choose to show; nothing currently asserts they agree on the numbers.
+- **`usageText` staying plain.** It is thrown as a `UsageError` and printed on the error path, which may be
+  redirected. Colouring an error message is the same hazard as colouring an artifact.
+- **Boxes, spinners, progress.** Hook output is not interactive and the CLI is not a TUI.
+- **A 256-colour fallback.** Named above as a real limit rather than an oversight.

package/docs/decisions/ad-064.md

@@ -0,0 +1,79 @@
+---
+type: Decision
+title: "AD-064 — A snapshot is assigned, never accumulated, and a table does not list what it cannot count"
+description: "The session report claimed 102.7M output tokens against 559k input. The transcript reader sums the tail of the transcript and that total is attached to every tool event, so the rollup was summing 3,488 snapshots of a sliding window. It also listed Bash as 0 ok / 23 fail, a row that can only ever show failures."
+tags: [decision, observability, cost, reporting]
+timestamp: "2026-08-12"
+---
+
+# AD-064 — A snapshot is assigned, never accumulated, and a table does not list what it cannot count
+
+- **status**: active
+- **date**: 2026-08-12
+
+## Decision
+
+1. **A token reading is assigned to the rollup, not added.** Same for the cost estimate.
+2. **The row says what the number is**: the latest reading over the recent transcript, not a session total.
+3. **A shell tool is not listed in the tools table.** Its successes are recorded as shell events, and the
+   `shell` row already answers for it.
+4. Both are asserted by tests that a mutant kills.
+
+## Why
+
+**The number was wrong by two orders of magnitude and looked authoritative.** 102,780,796 output tokens against
+559,896 input, with the cost shown as `$0.0000`. Three layers stacked:
+
+```
+claude.transcript.ts   readTail(transcriptPath, tailLines)   reads the tail
+claude.transcript.ts   inputTokens += …                      sums every record in it
+tool-after.ts          attaches that total to every event
+observability.service  rollup.output_tokens += outTok        sums it again, 3,488 times
+```
+
+The reader's result is a **snapshot of a sliding window**, not a delta. Measured: consecutive values oscillate —
+27515, 24764, 29082, 24819 — and repeat within one turn, which is a snapshot re-read, not a counter. Summing
+snapshots multiplies each turn's figure by the number of tool calls in it.
+
+**Last-per-turn was measured and rejected.** Taking the final reading of each turn and summing those gives 4.66M
+output tokens and 2.76 **billion** cache reads. Also snapshots, also summed. The only correct operation on a
+gauge is to take it, so the rollup takes the latest.
+
+**And the label had to change with it.** "Input tokens / Output tokens" reads as a session total, which is the
+reading that made the sum look reasonable to write. It now says what it is. A number whose meaning is stated is
+usable; one that implies a meaning it does not have is worse than none
+([/decisions/ad-034.md](/decisions/ad-034.md)).
+
+**`Bash: 0 ok, 23 fail` was structurally impossible to get right.** `rollup.tools` is fed by `tool.start`,
+`tool.end` and `tool.fail`. A successful shell call is `shell.end`; a failed one is `tool.fail`. So the row
+counted every failure and no success — after roughly 1,900 successful shell calls in the same session. The
+`shell` row two lines above reports `1874 allow / 0 ask / 60 deny`, correctly. Two sources for one fact is how
+this broke, so one of them goes.
+
+## Trade-offs
+
+**The token figure is now honest and small.** It reports the recent transcript window rather than the session,
+which is less than an operator wants. It is the number the harness can actually justify, and the label says so.
+
+**A true session total needs per-record accounting.** Counting each usage record exactly once means tracking a
+cursor into the transcript per session, or reading the whole file. The tail read exists because hook latency is
+a product property ([/decisions/ad-012.md](/decisions/ad-012.md)), and reading a long transcript on every tool
+call would spend it.
+
+**The cost estimate inherits the same limitation.** It is the estimate for the latest reading, not the session's
+bill. It was previously the sum of estimates over snapshots, which was wrong in the same way and by the same
+factor.
+
+**Dropping the shell row loses its duration.** `tools[name].ms` accumulated for a shell tool would have been a
+per-call timing the shell row does not carry. It was always zero here, because only `tool.end` writes it and a
+shell call never produces one.
+
+## Not decided here
+
+- **Per-record token accounting for a true session total.** The right fix and a bigger one: a cursor per
+  session, or a single whole-transcript read at session end where latency does not matter.
+- **Whether `SHELL_TOOLS` should come from the provider adapter.** It is a three-name set in core today, which
+  `check-boundaries` allows because none of the names is a vendor identifier. A fourth host with a differently
+  named shell tool would need it moved.
+- **Reporting cache-read tokens at all.** They dominate the real cost and are not shown; showing a number that
+  is also a snapshot would repeat the mistake in a new column.

package/docs/decisions/ad-065.md

@@ -0,0 +1,81 @@
+---
+type: Decision
+title: "AD-065 — The obs bus has a contract, and the gate checks both sides of it"
+description: "Seven defects in one week shared one shape: a consumer reading where the producer does not write. Each became a decision record and the pattern never became an object, so it was rediscovered by hand seven times. A kind consumed and never emitted now fails the gate, and so does a consumer reading a plane its kinds never land on."
+tags: [decision, observability, contracts, gates]
+timestamp: "2026-08-12"
+---
+
+# AD-065 — The obs bus has a contract, and the gate checks both sides of it
+
+- **status**: active
+- **date**: 2026-08-12
+
+## Decision
+
+1. **A kind a consumer counts and no producer emits fails the gate.**
+2. **A consumer declares its kinds and its planes**, and a kind landing on a plane the consumer does not read
+   fails. The plane comes from `resolveObsLevel` — the real function — so a change to the plane rules cannot
+   leave the check stale.
+3. **A kind emitted and read by nothing is reported, not failed.** It costs a write per event and may be a rail
+   half-built; that is the operator's judgement.
+4. **No registry file.** Emit sites are read from the source and consumers declare their own sets, so there is
+   nothing to keep in step.
+
+## Why
+
+**One pattern, seven instances, never materialised.** A consumer reading where the producer does not write:
+`gate.outcome` and `policy.deny` consumed by the report and emitted by nothing
+([/decisions/ad-027.md](/decisions/ad-027.md)); `format.enabled` in the catalog and read by no entrypoint
+([/decisions/ad-033.md](/decisions/ad-033.md)); `progressiveHandoff` written and never read; the idle-turn
+counter reading the signal plane while its kinds land on debug ([/decisions/ad-059.md](/decisions/ad-059.md));
+`latestSessionId` ordering UUIDs by name; the comment gate diffing against `HEAD` after the turn had committed
+([/decisions/ad-058.md](/decisions/ad-058.md)); the rollup summing a snapshot
+([/decisions/ad-064.md](/decisions/ad-064.md)).
+
+Every one was recorded. None of it stopped the next. Recording a fact is not the same as materialising the
+pattern, and this repository already has two proofs that materialising works —
+[/decisions/ad-041.md](/decisions/ad-041.md) made a union member read and never written a build failure, and
+`check-screens.ts` did the same for a screen outside the standard.
+
+**The practice transfers; the implementation does not exist.** Event-driven work treats a contract as a build
+gate rather than as documentation — validate the producer's record, verify the consumer against it, fail the
+pipeline on a mismatch. Orphan detection is the mirror: enumerate what is declared, check for references, attach
+a cost to what nothing uses. Searching found no tooling that does either statically for an in-process bus, so
+the pattern is borrowed and the code is ours.
+
+**`ObsKind` was a schema, not a contract.** A closed union says which kinds exist. It does not say who emits
+one, who reads it, or **which plane it lands on** — and the plane is exactly what the idle-turn rail got wrong.
+`resolveObsLevel` decides it deterministically from the kind, which is what makes the check possible without a
+runtime.
+
+## Trade-offs
+
+**It catches three of the seven.** The dead-kind class and the plane mismatch. It does nothing for the two
+diff-base defects or the two aggregation defects, and saying otherwise would be the false coverage this exists
+to remove. Those need a relation this cannot enumerate mechanically yet.
+
+**The consumer list is hand-maintained.** One entry today. A consumer that never registers is invisible to the
+check — the same shape as the defect it guards against, one level up. It is small enough to see in review and
+large enough to be worth saying out loud.
+
+**Emit sites are found by matching `kind:` literals.** A kind assembled at runtime would read as unemitted and
+fail a consumer that reads it. Nothing does that today, and the failure is loud rather than silent.
+
+**The orphan list found a defect on its first honest run.** Registering the session rollup and `why` took it
+from thirteen to five, and two of the five were real: `policy.observe` and `cost.session_alert` were emitted and
+read by nothing. Observation mode exists to produce a reading an operator acts on
+([/decisions/ad-027.md](/decisions/ad-027.md)) and no command showed one — the rail recorded into a plane
+nobody read. Both are now decisions in `why`, and three lifecycle kinds remain unread, which is fine and stated.
+
+**An inline consumer cannot have a plane mismatch**, and the contract says so rather than passing it silently.
+The rollup is fed at `recordObs` time, before plane routing; `why` and the activity counter read plane files.
+Marking the difference is what separates "checked and fine" from "not checked".
+
+## Not decided here
+
+- **`generation.end`, `session.end` and `subagent.end`.** Emitted, read by nothing. They are lifecycle markers
+  and may stay that way; the report names them so it is a decision rather than an oversight.
+- **Validating attributes per kind.** The payload half of a contract, and a much larger change. The rollup reads
+  `attrs.permission`, `attrs.rule` and others with no declaration that a producer sets them.
+- **A runtime check.** This is a build gate; a hook has no budget for it.