@tech-leads-club/harness-toolkit 0.2.1

package/docs/decisions/ad-035.md

@@ -0,0 +1,86 @@
+---
+type: Decision
+title: "AD-035 — A lesson learned by reasoning can be written down, and the harness never learns where lessons come from"
+description: "The lesson store had one producer — gate stagnation — so a pattern noticed across several changes, an operator's correction or an incident had no way in, while the mechanism that would carry it already ran every session. `tlc harness lessons add` is that route. It reads no documentation, knows no decision-record convention, and assumes no directory, because the harness runs in many products and one project's filing habits are not a feature."
+tags: [decision, lessons, cli, coupling]
+timestamp: "2026-08-04"
+---
+
+# AD-035 — A lesson learned by reasoning can be written down
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **`tlc harness lessons add "<instruction>"` writes a lesson**, with optional `--gate`, `--avoid`, `--prefer` and
+   `--tokens`.
+2. **It is `source: "manual"`** — a value already present in `LessonSource` and produced by nothing.
+3. **It is `active` immediately**, not `candidate`. A candidate exists because the automatic producer guesses from
+   output; an author is not guessing.
+4. **With no `--gate` it takes a neutral gate**, so a retry for a specific gate is not falsely boosted. Session-mode
+   injection carries it regardless.
+5. **The id is a hash of the normalised instruction**, so rewriting the same lesson updates it in place.
+6. **A lesson authored inside an agent session records that in its category.** Recorded, not refused.
+7. **The harness reads no documentation to find lessons.** No decision-record convention, no directory, no file
+   format. It ships the mechanism; a project decides what feeds it.
+
+## Why
+
+The harness injects lessons at session start and on retry, ranked, with recurrence decay and gardening ([/decisions/ad-023.md](/decisions/ad-023.md)). That
+machinery is the right shape for exactly one purpose: carrying what was learned back to the next turn. And it had a
+single producer — `recordLessonFromFailure`, triggered by the same gate fingerprint appearing twice.
+
+So everything learned any other way stayed out. A pattern noticed across several changes, a code review, a production
+incident, an operator's correction: none of it could enter the one channel built to deliver it. The measured cost is
+this repository's own week — the same defect family shipped **five times** (a consumer written before its producer),
+each instance recorded in its own decision record, and the pattern never written anywhere that loads before work
+starts. Thirty-four decision records, none of them injected.
+
+`LessonSource` already contained `"manual"`, produced by nothing — the union anticipated this route and it was never
+built. Sixth instance of the family, found while fixing the family.
+
+## The coupling this deliberately refuses
+
+The obvious next step was to let a decision record feed the store: put a `lesson:` field in the frontmatter next to
+the `migration:` field, and have the harness read `docs/decisions/`. It was proposed and rejected by the operator, and
+the rejection is right.
+
+`docs/decisions/ad-NNN.md` with OKF frontmatter is **this repository's filing habit**, decided in AD-013 for its own
+documentation bundle. Another product using this harness may keep ADRs in `doc/adr/0001-*.md`, or in a wiki, or
+nowhere. A harness that reads one layout to harvest lessons would make every install carry one project's conventions —
+the same mistake as the earlier coupling to an external methodology's vocabulary, which AD-025 had to undo.
+
+The line is: **the harness ships the mechanism, the project decides what feeds it.** If this repository wants its
+decision records to produce lessons, that is a script in this repository calling `lessons add` — not behaviour in the
+tool that every other product installs.
+
+## Trade-offs
+
+**An agent can write its own injected context.** That is a self-modification surface, and refusing it was considered.
+It loses to the alternative: the reason five patterns went unrecorded is that recording required the operator to
+transcribe what the agent had learned, and that never happens. The mitigations are that the source and the
+in-session marker are recorded, `lessons list` shows them, and `garden` decays and quarantines them like anything
+else. The store already carried harness-authored content from gate output, so the boundary being crossed is narrower
+than it looks.
+
+**`active` from the start skips the promotion threshold**, which exists to stop a one-off gate failure from becoming
+advice. An authored lesson has no recurrence to accumulate, so waiting for `promoteHitCount` would mean it never
+activates. The cost is that a badly-written authored lesson is injected immediately; `garden` and `lessons list` are
+the recourse.
+
+**The neutral gate is a string that reads in the rendered line**, so an operator sees `[any/active]`. A separate
+"applies to everything" flag would be cleaner and would touch the ranking code, which is not worth it for the
+difference.
+
+## Not decided here
+
+- **`scope` is read by nothing.** It is a single-value union on every lesson and no ranking or selection consults it.
+  Found while building this, left alone — removing a persisted field is its own change, and an authored lesson carries
+  the same value rather than inventing an unread second one.
+- **A repository-local bridge from decision records to lessons.** Legitimate for this repository, and it belongs here
+  rather than in the shipped tool. Not built.
+- **Whether the floor should refuse `lessons add` in-session.** It does not today, by the reasoning above. If a
+  self-written lesson ever causes harm, the marker is what makes that case findable.
+- **De-duplicating an authored lesson against an automatic one** saying the same thing in different words. The ids
+  cannot collide, so both would be injected.

package/docs/decisions/ad-036.md

@@ -0,0 +1,68 @@
+---
+type: Decision
+title: "AD-036 — A lesson names what makes it true, and stops being injected when that is gone"
+description: "A lesson is a claim about a repository, and the repository outlives the claim. `tools/check-dist-fresh.ts` gets renamed and the lesson naming it turns from useful into misleading, with the authority of a lesson. A lesson may now carry refs — repository-relative `path` or `path:symbol` — and `garden` withholds it when one stops resolving. An unreadable file is deferred, never stale."
+tags: [decision, lessons, staleness]
+timestamp: "2026-08-04"
+---
+
+# AD-036 — A lesson names what makes it true
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **A lesson carries zero or more `refs`**, each a repository-relative `{ path, symbol? }`, written with
+   `tlc harness lessons add --ref path[:symbol]`. The flag may repeat.
+2. **Four statuses**: `present`, `path-missing`, `symbol-missing`, `unreadable`.
+3. **`unreadable` is deferred, never stale.** A file this process cannot open is not evidence that the lesson
+   stopped being true — it is evidence that the check could not run.
+4. **`garden` sets `staleReason` and clears it** when every ref resolves again. A rename can be reverted.
+5. **A stale lesson is withheld from injection** in both session and retry mode, and is not deleted.
+6. **A lesson with no refs is never stale.** Most lessons are about conduct, and demanding a ref would make
+   authors invent one.
+7. **A symbol is checked by substring, not by parsing.** The question is whether the name still appears in the
+   file.
+8. **Staleness is persisted only for the project tier.** The global tier is decided per repository at selection
+   time — see AD-040.
+
+## Why
+
+The harness could expire a lesson by attention and never by truth: quarantine after ninety idle days, prune after
+a hundred and eighty. Neither asks whether the lesson is still *correct*.
+
+The concrete case is in this repository's own memory. A recorded lesson says to run `tools/check-dist-fresh.ts`
+before committing. On the day that file is renamed the lesson keeps being injected, and it is now worse than
+absent: it sends the next turn looking for something that does not exist, ranked above lessons that are true.
+Nothing in the harness could notice, because nothing in the harness knew the lesson was about a file.
+
+The mechanism is taken from a prior implementation that stores linked symbols on a memory and marks the
+row stale when a linked symbol disappears. Two things were kept and one was dropped. Kept: the `path_renamed` /
+`symbol_deleted` distinction, and the treatment of an unreadable file as deferred rather than stale — the
+conservative direction. Dropped: the LSP-backed symbol checker. That implementation's own fallback is
+`text.includes(symbol)`, which is the whole mechanism at zero dependency and one file read.
+
+## The hazard an absolute path would create
+
+A ref is repository-relative and an absolute one never resolves. Otherwise a global lesson naming
+`/home/me/repos/a/tools/gate.ts` would report `present` in every product on that machine, because the path
+resolves regardless of which repository is open. Refs describe a repository, not a disk.
+
+## Trade-offs
+
+**Substring matching accepts a false `present`.** A symbol mentioned in a comment, or a name that is a substring
+of another, keeps a lesson alive that a rename should have retired. The cost is one stale lesson; the alternative
+is a parser per language per turn, which the hook's latency budget forbids.
+
+**Refs are author-supplied and never inferred.** Deriving them from gate output was considered and refused:
+guessed links would mark true lessons stale, which is a worse failure than no links at all.
+
+**Staleness is reported, not auto-deleted.** A broken ref is a filesystem observation, and a revert or a branch
+switch undoes it. Only an expired validity window — which the author declared — is pruned ([/decisions/ad-037.md](/decisions/ad-037.md)).
+
+## Not decided here
+
+- **Whether a stale lesson should eventually be pruned.** Today it is withheld and reported forever. The existing
+  decay path does not reach it, because decay measures recurrence.
+- **Refs on core lessons.** They ship with none; the six are about conduct, not about files.

package/docs/decisions/ad-037.md

@@ -0,0 +1,47 @@
+---
+type: Decision
+title: "AD-037 — A lesson can be true for a period, and an unparseable bound withholds it"
+description: "Some knowledge has a known end: pin the formatter until the toolchain moves. A lesson may now carry `validFrom` / `validTo`, and is injected only inside that window. An unparseable bound fails the window rather than being ignored, because the conservative side is the one where a claim nobody can evaluate does not reach the turn."
+tags: [decision, lessons, validity]
+timestamp: "2026-08-04"
+---
+
+# AD-037 — A lesson can be true for a period
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **Optional `validFrom` and `validTo`**, ISO strings, written with `tlc harness lessons add --until <iso>`.
+2. **Active when** `(validFrom absent or <= now) and (validTo absent or > now)`. The lower bound is inclusive, the
+   upper is exclusive.
+3. **An unparseable bound fails the window.** The lesson is withheld.
+4. **An empty string is absent, not invalid.**
+5. **`garden` prunes an expired lesson.** Unlike a broken ref, the end was declared by the author.
+6. **`validityReason` names the state** — `active`, `pending`, `expired`, `invalid` — so a report can distinguish
+   "not yet" from "no longer".
+
+## Why
+
+The store had two exits, both driven by idle time. Neither can express "this was true and now is not", which is
+the normal fate of a lesson about a version, a migration in progress, or a workaround for a bug that will be
+fixed. Without it, the author's choice is to inject something they know will expire, or not record it.
+
+Taken from a prior validity filter, including its conservative rule: an invalid ISO string fails the window.
+Ignoring an unparseable bound would inject the lesson — treating a broken declaration as no declaration — and the
+author who wrote `--until "next tuesday"` intended a limit. Failing closed surfaces the typo through
+`lessons list` and `doctor` instead of silently disregarding it.
+
+## Trade-offs
+
+**Pruning on expiry deletes knowledge.** A lesson that expires is gone, not quarantined. That is the difference
+from staleness: a filesystem observation can be wrong or reverted, and a date the author wrote cannot.
+
+**`validFrom` has no CLI flag.** Only `--until` is exposed, because the case for a lesson that starts later has
+not appeared. The field is read wherever validity is evaluated, so a future flag needs no new logic.
+
+## Not decided here
+
+- **Reminding the operator before a window closes.** `doctor` reports it after the fact.
+- **A relative form** such as `--until 30d`. Absolute ISO only, so a stored record means one thing.

package/docs/decisions/ad-038.md

@@ -0,0 +1,52 @@
+---
+type: Decision
+title: "AD-038 — Promotion counts distinct sessions, because one stuck session is one observation"
+description: "A candidate lesson was promoted on `hitCount >= promoteHitCount`, and `hitCount` counted fingerprint recurrences with no session identity. One session hammering the same failure five times promoted a lesson that had occurred once in the world. Promotion now counts the distinct sessions that produced it; `hitCount` keeps counting recurrence and no longer decides."
+tags: [decision, lessons, promotion]
+timestamp: "2026-08-04"
+---
+
+# AD-038 — Promotion counts distinct sessions
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **A lesson records the distinct session keys that produced it**, capped at twelve.
+2. **`garden` promotes a candidate when the distinct session count reaches `promoteHitCount`.**
+3. **`hitCount` keeps counting raw recurrence** and is still displayed. It no longer decides promotion.
+4. **A record with no session keys falls back to `hitCount`.** Every store already on disk predates the field, and
+   freezing those lessons as candidates forever would be a silent regression.
+5. **Quarantine uses the same count**, so the promotion threshold means one thing in both directions.
+6. **An authored lesson carries no session keys** and never consults them — it is already `active` ([/decisions/ad-035.md](/decisions/ad-035.md)).
+
+## Why
+
+`promoteHitCount` defaults to 2 and reads as "seen twice". It was not: `recordLessonFromFailure` incremented
+`hitCount` on every recurrence of the same gate fingerprint, and a single stuck session produces that recurrence by
+definition — the stagnation rail exists because sessions repeat themselves. So the threshold measured persistence
+within one session, and promoted advice from a single observation to active guidance injected at every session
+start.
+
+A prior pattern miner makes the distinction explicitly: it aggregates escalation events into
+`uniqueSessionCount` and requires that to cross `patternMiningThreshold` before writing a gotcha, deriving
+importance from the same number. The rule is the transferable part — the recurrence that justifies a durable claim
+is recurrence *across* sessions.
+
+## Trade-offs
+
+**The cap can lose a promotion signal.** Twelve keys is a bounded record; a lesson recurring across more sessions
+counts twelve. The threshold is a small number, so the cap cannot prevent a promotion that should happen.
+
+**Distinct sessions is still not distinct causes.** Two sessions on the same branch hitting the same wall are two
+observations of one situation. Counting causes would need a notion of cause the harness does not have.
+
+**Legacy fallback lets an old record promote on within-session recurrence.** Accepted deliberately: the alternative
+punishes existing stores for a field that did not exist when they were written.
+
+## Not decided here
+
+- **Weighting a session by how much work it contained.** A one-turn session and a fifty-turn session count the
+  same.
+- **Whether `hitCount` should stay.** It is displayed and it is honest about what it measures, so it stays.

package/docs/decisions/ad-039.md

@@ -0,0 +1,69 @@
+---
+type: Decision
+title: "AD-039 — A lesson is graded by the gate it was injected for, and unproven is not a passing reading"
+description: "Nothing in the harness measured whether a lesson ever helped. Injection was recorded; what happened next was not. The lessons injected for a failing gate are now credited by that gate's next run — passed is `helped`, failed is `neutral` — and a lesson nothing has graded reads `unproven`, which `doctor` reports as a warning rather than folding into a zero rate."
+tags: [decision, lessons, measurement, observability]
+timestamp: "2026-08-04"
+---
+
+# AD-039 — A lesson is graded by the gate it was injected for
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **Three counters on a lesson**: `injectedCount`, `helpedCount`, `neutralCount`.
+2. **When lessons are injected on a retry for gate G**, their ids and G are written to the handoff as a pending
+   credit.
+3. **On the next run of gate G**: passed → `helpedCount`, failed → `neutralCount`.
+4. **The gate name is compared.** Without it, lessons injected for `lint` would be graded by whichever gate ran
+   next, which is `test`, and read as help the lesson never gave.
+5. **Consumed exactly once.** The pending credit is cleared whether or not any lesson matched.
+6. **`helpRate` is `null` over zero graded injections, never zero.** Zero reads as "measured and it never helped".
+7. **`unproven` is a `doctor` warning, not an `ok` row** — and only for a lesson that has actually been injected.
+8. **Core lessons are never credited.** They ship inside the runtime, identical in every install, and there is no
+   file to write a counter to.
+
+## Why
+
+The harness ranks lessons by recurrence, decay, gate match and trigger tokens. Every one of those is a proxy for
+usefulness. None of them is usefulness. So a lesson could be injected at every session start for months, spend its
+share of the budget, and no number anywhere would say whether it ever changed an outcome.
+
+The signal was already within reach. `gate.outcome` began being emitted in AD-027, and the retry path already knows
+which lessons it selected and which gate is failing. Joining the two is the difference between "this lesson matches
+the failing gate" and "this lesson was present when that gate started passing".
+
+The `null`-over-zero rule is taken from a prior rate KPI helper, which returns `value: null` when the denominator
+is zero, and from the `met: boolean | null` of its KPI targets. That third state is the point. A capability with
+`attempted > 0` and `effective == 0` is wired and broken; one with `attempted == 0` is **unproven**, and reading the
+second as healthy is how this repository shipped a report that printed a truthful-looking `0 / 0` for every gate it
+had ever run.
+
+## What this is not
+
+**It is not causal.** A gate passing after a lesson was injected does not establish that the lesson caused it — the
+turn also read the gate output, changed files, and may have ignored the lesson entirely. `neutral` likewise does not
+mean the lesson was wrong; it means the gate failed again.
+
+The claim is narrower and still worth having: a lesson with many `neutral` gradings and no `helped` ones has been
+present at many failures and no recoveries, and an operator can act on that. A properly causal answer needs the same
+task run with and without the lesson, which requires task repetition, and real work does not repeat — the reason
+AD-027 built observation mode instead of an A/B probe.
+
+## Trade-offs
+
+**A credit can land on the wrong turn.** If the gate is not reached on the next stop — no changed files, a cap hit,
+a skip flag — the credit waits, and a later run grades it. The gate name bounds the error; time does not.
+
+**The handoff carries session state that outlives a session.** A pending credit written at the end of one session is
+graded in the next. That is intended: the retry loop it belongs to often spans a compaction.
+
+## Not decided here
+
+- **Ranking by effectiveness.** The counters are recorded and reported and do not yet feed `rankScore`. Boosting on
+  a non-causal signal would make the ranking self-confirming, which is the hazard already documented for
+  `lastAccessedAt`.
+- **Auto-quarantining a lesson with many neutral gradings.** Reported; the operator decides.
+- **Grading session-start injections.** Only the retry path has a gate to compare against.

package/docs/decisions/ad-040.md

@@ -0,0 +1,89 @@
+---
+type: Decision
+title: "AD-040 — Three lesson tiers, and nothing crosses between products by itself"
+description: "Four of the five patterns recorded on 2026-08-04 are general engineering discipline and were locked in one repository's store, so they would not reach the same operator working in another product. A global tier — this machine, every product — sits between the shipped core and the project store. Promotion into it is an operator command and never automatic, and `projectScoped` is replaced by the tier it duplicated."
+tags: [decision, lessons, tiers, coupling]
+timestamp: "2026-08-04"
+---
+
+# AD-040 — Three lesson tiers
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **Three tiers.** `core` ships inside the runtime, identical everywhere, immutable. `global` is
+   `<runtime home>/state/lessons.json` — this machine, every product. `project` is
+   `<repo>/.tlc/harness/state/lessons.json`.
+2. **`allLessons` returns core + global + project**, deduplicated by id with the nearer tier winning.
+3. **`tlc harness lessons add --global`** writes to the global tier.
+4. **`tlc harness lessons promote <id>`** copies a project lesson into the global tier. Operator-invoked only.
+5. **No automatic promotion.** A lesson learned in product A never reaches product B unattended.
+6. **`projectBoost` favours the project tier**, so local knowledge outranks knowledge carried in.
+7. **`tier` is derived on read** from the store the lesson came out of, never trusted from the file.
+8. **`projectScoped` is removed.** It was a persisted boolean meaning "gets the boost" that read as "lives in the
+   project store"; with three tiers the two stop coinciding.
+9. **Staleness for a global lesson is decided per repository at selection time**, not persisted.
+10. **`garden` sweeps both writable tiers.** Decay, promotion and expiry apply identically; only staleness differs.
+
+## Why
+
+The measured gap is this repository's own week. Five patterns were recorded on 2026-08-04. One is local — this
+repository's CI sets `TLC_HOME`. The other four are not about this repository at all:
+
+- run the gate itself, never an approximation of its steps
+- read the operator's output before anyone else tests
+- a surviving mutant is usually one that never landed
+- a consumer written before its producer reads as working
+
+Those are true in `platform`, in `fitness-portal`, in any repository. They were in a store that only this
+repository reads, so the same mistakes were queued to repeat everywhere else — and the harness is installed into
+many products by design.
+
+A prior system has the same three-layer shape, and its personal layer explicitly holds cross-project — "knowledge I
+apply across any project" — with promotion drawn as `Personal → Team → Project`, one direction, operator-invoked.
+The shape transferred; the middle layer did not. That system's Layer 2 is a synced team database. This harness has no
+server and no sync, so its middle tier is *this machine* — the operator, across products. The precedent for the
+location already existed: `obs.globalSpool` writes to the same runtime home for exactly the same reason.
+
+## Why promotion is never automatic
+
+It auto-promotes personal → team on decay and access thresholds, and that is defensible inside one project
+where both layers describe the same codebase. Across products it is not. A lesson mined from a gate failure in
+product A names product A's test runner, its file layout, its stack. Injected into product B it is confident,
+specific and wrong.
+
+Thresholds cannot separate the two cases, because the signal they measure — recurrence in A — says nothing about
+applicability in B. Only the operator knows. So the tier is opt-in per lesson, twice: `--global` when writing, or
+`promote` afterwards.
+
+The residual risk is a global lesson that is genuinely irrelevant in some product. Two things bound it: the ranking
+boost keeps project lessons above it, and a global lesson carrying refs withholds itself where those refs do not
+resolve ([/decisions/ad-036.md](/decisions/ad-036.md)). That withholding is why the tier is safe rather than merely convenient — a lesson can state the
+conditions under which it applies, and the absence of those conditions silences it.
+
+## Why the rendered line names the tier
+
+An injected lesson renders as `[gate/status/tier]`. A turn reading `[test/active/global]` can tell the advice was
+written about a different repository and weigh it accordingly. The alternative — hiding the provenance — asks the
+model to treat carried-in advice with the same authority as local knowledge.
+
+## Trade-offs
+
+**`projectScoped` removal touches every stored record.** No migration is needed, because the tier is derived from
+the file the record was read from, and the removed field is simply ignored.
+
+**The global store is per machine, not per operator account.** Two accounts on one machine with the same
+`TLC_HOME` share it. `TLC_HOME` already defines the runtime, and every other runtime-home artefact has the same
+property.
+
+**A promoted lesson exists in two stores.** `promote` copies rather than moves, so the project keeps its own copy
+and the dedup rule resolves to it. Moving would remove local knowledge as a side effect of sharing it.
+
+## Not decided here
+
+- **A team tier.** It needs sync, a server and a trust model. Out of scope.
+- **`lessons demote`**, and deleting a global lesson from within a project. Editing the global store is the
+  operator's own act, at its printed path.
+- **Whether the global tier should decay faster.** It uses the same `decayLambda`.

package/docs/decisions/ad-041.md

@@ -0,0 +1,98 @@
+---
+type: Decision
+title: "AD-041 — A member something reads and nothing writes fails the gate"
+description: "This repository has shipped the same defect eight times: a consumer written before its producer, which reads as working because the consumer's default is plausible. `tools/check-wiring.ts` refuses it mechanically — every member of every exported string-literal union that is read anywhere must be written somewhere. Inventories are discovered, never registered, so the check cannot itself be forgotten."
+tags: [decision, gate, tooling, dead-code]
+timestamp: "2026-08-04"
+---
+
+# AD-041 — A member something reads and nothing writes fails the gate
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **`tools/check-wiring.ts` is a step of `tlc harness test`** and exits non-zero on any finding.
+2. **Inventories are discovered, never registered.** Every exported string-literal union in the tracked non-test
+   source is scanned. A registry would need an entry per union, and the missing entry is the same class of omission
+   this exists to catch.
+3. **The rule is one-directional: consumed and never produced.** Written-and-never-read is dead data, a lesser
+   smell, and often legitimate — a field emitted for a human to read in JSON.
+4. **Occurrences are classified by preceding context**, and consumer context wins. A producer is a value position
+   (`: "x"`, `return "x"`, `=> "x"`, `("x"`, `, "x"`, `["x"`); a consumer is an unambiguous read (`=== "x"`,
+   `!== "x"`, `case "x"`, `includes("x")`, `has("x")`).
+5. **Collection membership is a producer, not a read.** The same syntax declares an inventory.
+6. **The file set is git's index**, so an untracked scratch file cannot change the verdict.
+7. **`CONFIG_FACING` is the only escape hatch**, per union rather than per member, for types whose values arrive in
+   the operator's `config.json`. Each entry carries a reason and is printed in the clean report.
+8. **The finding names the type, the member, the declaring file and every reader**, and states the two ways out:
+   write it, or delete it and the branches that read it.
+
+## Why
+
+The measured record, each instance its own decision or fix: `attrs.permission` ([/decisions/ad-026.md](/decisions/ad-026.md)), `gate.outcome` and
+`policy.deny` ([/decisions/ad-027.md](/decisions/ad-027.md)), `observe.rails` values ([/decisions/ad-029.md](/decisions/ad-029.md)), `format.enabled` ([/decisions/ad-033.md](/decisions/ad-033.md)), `LessonSource "manual"`
+([/decisions/ad-035.md](/decisions/ad-035.md)), and — found by this check on its first run — `FailureCategory "infra"` and the whole `GenAiOutcome`
+union.
+
+Every instance has the same shape. The consumer exists, the producer does not, and the consumer's default is a
+plausible value: a counter reads zero, a flag reads false, a `case` is never entered. Tests pass, because each half
+is tested separately and no test asserts that the two are connected. The session report printed `Gates pass/fail:
+0 / 0` for every gate this harness had ever run, and it looked correct.
+
+Prose does not fix this. Six decision records say some version of "wire the producer in the same change", and the
+seventh instance shipped anyway. The August 2026 practitioner consensus on the same failure mode says the same
+thing structurally: prompt-level instructions to double-check do not work reliably because the checker is the
+maker, and what works is an out-of-band audit that cross-references declarations against registrations. That is
+exactly a hook-audit, generalised — and the same writing warns that adding one rule per new defect produces rule
+inflation. Hence one discovered, data-driven check rather than eight.
+
+## What the first run found
+
+Two real defects, on a repository whose gate was green:
+
+- **`FailureCategory "infra"`** — two `case "infra":` branches, in the retry suggestion and in autopilot, that
+  nothing could ever enter. `classifyGateFailure` never returns it. Its text told the operator to check that lint
+  and test CLIs are on `PATH`, which is the case AD-021 already decided classifies as `config` — a duplicate
+  without a producer. Deleted.
+- **`GenAiOutcome`** — a five-member union on `ObsEvent.gen_ai.outcome`, populated by nothing. `usageGenAi` is the
+  only producer of that object and never sets it. Sweeping the same field revealed four more never-written
+  siblings: `operation_name`, `provider_name`, `request_model`, `reasoning_tokens`. All five removed from the
+  shipped event schema.
+
+## The two calibration errors, both mine, both measured
+
+The first draft excluded the declaring file and required both directions. It reported **85 findings across 129
+members** — 66% noise, because producers legitimately live beside their type and many members are written without
+ever being compared. A check that cries wolf gets disabled, which is the defect family AD-034 named.
+
+The second draft included the declaring file and required only "consumed, not produced": **2 findings**, one real,
+one false. The false one was `SpoolStream "audit"`, where `appendSpoolRecord(root, "audit", record)` is a producer
+that the comma-adjacent consumer pattern read as a comparison.
+
+Fixing that exposed a worse error in the opposite direction. Adding `=` and `(` to the producer alternatives made
+`=== "x"` and `includes("x")` match as *producers* — so any member compared anywhere counted as written, and the
+check would have passed on nearly every dead rail it exists to catch. The sensor was weaker than its own
+measurement claimed. Classifying each occurrence by its preceding context, with consumer context tested first, is
+what makes the two unambiguous; both holes have a test.
+
+## Trade-offs
+
+**It matches strings, not types.** Two unions sharing a member string are conflated, and a member appearing in a
+comment or a test fixture name counts. Accepted: the alternative is the TypeScript compiler API, and the
+string-based version found two real defects on its first run with one false positive.
+
+**`CONFIG_FACING` can be widened to silence a finding.** It is per union, so it cannot hide one dead member of an
+internal union — only state that a whole type is operator-supplied. Both entries are printed on every clean run,
+because a silent exemption reads as a passing check.
+
+**Config-facing unions are therefore unchecked.** Nothing validates that `appendFiles` in a config file is one of
+the three legal values. That is a real gap and it is not this check's subject.
+
+## Not decided here
+
+- **Validating config-supplied union values at load.** The gap above.
+- **Non-union inventories** — `OBSERVABLE_RAILS` and similar constant arrays. Their invariant is documented and
+  tested at the call site; extending discovery to array constants would need a producer notion per constant.
+- **Never-written optional scalar fields** that are not union members. The `gen_ai` sweep was done by hand.

package/docs/decisions/ad-042.md

@@ -0,0 +1,82 @@
+---
+type: Decision
+title: "AD-042 — The suite gets an empty runtime home, and one renderer renders a lesson"
+description: "Two defects the previous change shipped, both found by running it rather than by any check. `TLC_HOME` was deliberately left alone in the hermetic setup, which was safe only while nothing machine-wide lived under it — the global lesson tier does, so a test reading `allLessons` read whichever lessons the developer had promoted. And `support.ts` carried a copy of the lesson renderer, so the tier added to the core block never reached the text a model receives."
+tags: [decision, testing, lessons, hermetic]
+timestamp: "2026-08-04"
+---
+
+# AD-042 — The suite gets an empty runtime home, and one renderer renders a lesson
+
+- **status**: active
+- **date**: 2026-08-04
+
+## Decision
+
+1. **`tools/test-env.mjs` points `TLC_HOME` at a fresh empty temp directory.** Redirected, not deleted — deleting
+   it would send every test at the developer's real `~/.tlc/harness`, which is the opposite of hermetic.
+2. **A test that needs the real runtime says so.** `e2e-consistency.test.ts` drives the actual launcher and CLI, so
+   it passes `TLC_HOME: repoRoot` explicitly.
+3. **`renderLessonLine` in `src/entrypoints/support.ts` delegates to the core renderer**, exposed on the facade as
+   `coreFacade.lesson.renderLessonBlock`. The copy is deleted.
+4. **An end-to-end test asserts the tier appears in the text the hook returns**, not only in the core block.
+
+## Why the runtime home had to change
+
+`TLC_HOME` was excluded from the hermetic setup on an explicit rationale, written in
+`tools/test-env.names.mjs`: it names *which runtime*, not which project, CI sets it deliberately, and the suite
+exercises it.
+
+That was true, and it stopped being sufficient the moment something machine-wide lived under it. AD-040 put the
+global lesson tier at `<runtime home>/state/lessons.json`. From then on, any test calling `allLessons` without
+pinning a home read whichever lessons the operator of that machine happened to have promoted.
+
+The failure profile is what makes this worth a decision record: **green on a fresh machine, green in CI, green on
+mine at commit time** — because my global store was empty — and red minutes later, when I promoted five lessons
+into it. The gate ran three times and passed three times before the store had contents. Nothing about the change
+was wrong; the test's assumption was, and the assumption only became visible once the feature was used.
+
+`obs.globalSpool` ([/decisions/ad-018.md](/decisions/ad-018.md)) had already put a file under the runtime home and did not expose this, because no test
+asserts a count over the spool. The lesson store is read by `allLessons`, which almost every lesson test calls.
+
+## Why one renderer
+
+`support.ts` carried `renderLessonLine`, a duplicate of `renderLessonBlock`, with a comment explaining the choice:
+the core's version is presentation-only and was not on the facade, so reaching into core internals was avoided by
+copying it.
+
+The copy is the one the model actually receives. So `[gate/status/tier]` — added in AD-040 precisely so a turn can
+tell that a lesson was written about a different repository — rendered in `lessons list` and in nothing an agent
+ever saw. Two derivations of one string is the same defect as a consumer without a producer, pointed sideways: both
+halves work, and the one that matters is the one nobody checked.
+
+Exposing it on the facade is the sanctioned route ([/decisions/ad-004.md](/decisions/ad-004.md)). "Presentation does not belong in core" was the right
+instinct applied to the wrong thing — the block's shape *is* a core contract, because ranking, budgeting and the
+synced markdown all depend on its length.
+
+## How both were found
+
+By running the thing and reading the output — the practice AD-034 records, not a mechanism. `check-wiring` ([/decisions/ad-041.md](/decisions/ad-041.md))
+catches a declared member nothing writes; neither of these is that shape. Stated plainly: after this change the
+harness mechanically refuses one defect family, and the other two found here still depend on someone exercising the
+feature and reading what comes out.
+
+## Trade-offs
+
+**Every test now pays a `mkdtemp` at startup.** One syscall per test process, twice per gate run.
+
+**A test that silently depended on the ambient runtime home now fails.** Three did, all in the E2E file, and all
+three were better off stating the dependency. A future test that needs the real runtime will fail loudly rather
+than pass for an ambient reason.
+
+**The temp home is not cleaned up.** The OS reclaims `TMPDIR`; a directory per test process with nothing in it is
+cheaper to leak than to track.
+
+## Not decided here
+
+- **Whether CI should keep setting `TLC_HOME` to the workspace.** It still does, and the setup module now overrides
+  it for the suite while `check-dist-fresh` and the CLI steps still read it.
+- **A mechanical check that a test does not read machine state.** It would need to know which paths are
+  machine-wide; the hermetic setup covers the two that exist.
+- **Auditing every other machine-wide read for the same assumption.** The runtime home is now empty for the suite,
+  which covers the class rather than the instances.