@tech-leads-club/harness-toolkit 0.2.1 → 0.2.4

package/docs/decisions/ad-034.md

@@ -1,86 +0,0 @@
----
-type: Decision
-title: "AD-034 — A warning that fires on a healthy install is not a warning, and the author reads the operator's output before anyone else does"
-description: "A real update run put NEEDS YOUR ACTION on two changes that did not apply, both saying run doctor — which update ran automatically three lines later — with an escaped quote leaking into the terminal, above nine warnings for capabilities nobody had enabled, under a line claiming all checks passed. Every piece had a passing test. A migration note now means something doctor cannot detect, unenabled capabilities are inventory, and the author runs the operator-facing commands and reads them before shipping."
-tags: [decision, process, doctor, release, noise]
-timestamp: "2026-08-04"
----
-
-# AD-034 — A warning that fires on a healthy install is not a warning
-
-- **status**: active
-- **date**: 2026-08-04
-
-## Decision
-
-1. **A `migration` note exists only where `doctor` cannot detect the condition for the operator.** Five of the six
-   notes then in the tree said, in substance, "run `tlc harness doctor`" — which `update` runs automatically. They are
-   removed. AD-027 keeps its note because a stop blocked by evidence ordering is invisible to every check.
-2. **The digest leads with the note and trails the decision id.** A decision's title states the author's reasoning;
-   the operator's situation is what belongs on the first line.
-3. **The heading appears only when a note exists**, and says what a note now means. With nothing to do, the digest
-   states what landed and points at the doctor run below rather than asking for it.
-4. **A frontmatter value is unescaped before display.** An escaped quote reached a terminal as a literal backslash.
-5. **A capability that is merely not enabled is one `ok` inventory row**, not one warning each.
-6. **The doctor summary counts failures and warnings separately** and never says everything passed while printing a
-   warning.
-7. **Before asking anyone else to test, the author runs every operator-facing command and reads the output.** Unit
-   tests assert pieces; the defects here were all in the composition and in the reading.
-
-## Why
-
-An operator ran `tlc harness update` and the output contained four defects, each of which had a passing test.
-
-`NEEDS YOUR ACTION (2)` — and neither applied to him. Three lines below, `doctor` reported his Cursor wiring as
-`wired` and his config carried no `format` block. Both notes said "run `tlc harness doctor`", which the update then
-did automatically. One of them rendered `\"detected but not wired\"` with the backslashes visible, because the value
-was written with escaped quotes inside a quoted string and only the outer pair was stripped.
-
-Below that, nine warnings for capabilities he had never enabled — and buried among them the three rows that mattered:
-a policy baseline changed out of band, and two gate commands running in full on every attempt. Then, under all of it,
-`doctor: all checks passed`.
-
-Every one of those pieces was individually correct and individually tested. The escaping test did not exist because
-the value looked fine in the source. The digest test asserted the heading appeared, which it did. The capability
-warning test asserted a warning was produced, which it was. What no test covered, and no test naturally would, is
-**what the whole thing reads like to the person it is for**.
-
-The through-line is one idea, arriving for the fourth time this week. AD-026 removed an approval prompt that fired
-often enough to become a keystroke. AD-029 removed a silence an operator would misread as a clean result. AD-032
-removed a health check that passed on a broken install. This removes an alarm that fires on a healthy one. In every
-case the mechanism worked and the signal was worthless, because **a signal that appears when nothing is wrong cannot
-carry the case where something is.**
-
-And the process failure is mine and worth writing down plainly: the harness was handed to two colleagues today and
-broke in front of both. The first was a hook that could not run; the second was thirty minutes of gate time nobody
-could see. Both were found by them, not by me, and both were visible in output I had never once read end to end. The
-tests were not the problem. Not looking was.
-
-## Trade-offs
-
-**Removing five notes loses real information for an operator who never runs `doctor`.** That is accepted: `update`
-runs `doctor` at the end, so the only way to miss it is to ignore the output — and a reader who ignores the output is
-exactly the reader an extra alarm does not reach.
-
-**One inventory row is less discoverable than nine warnings.** Deliberately. `update` still prints each capability
-with its benefit and trade-off in full, which is the moment an operator is choosing; `doctor` is the moment they are
-diagnosing, and a list of things they decided not to enable is not a diagnosis.
-
-**`migration` now depends on a judgement — can doctor see this?** — which cannot be checked mechanically. The bundle
-check still catches a present-but-empty note. The judgement is stated here so the next note is written against it
-rather than against a habit.
-
-**Reading the output by hand does not scale and is not a test.** It found four defects that four suites did not, so
-it earns its place as a step rather than as a substitute. The narrower part is testable and now tested: the digest's
-shape, the unescaping, the inventory row, the summary wording.
-
-## Not decided here
-
-- **A golden test over the whole `update` output.** It would have caught all four, and it would also fail on every
-  wording change, which is how a golden becomes a rubber stamp. The composition is checked by reading; the pieces by
-  assertions.
-- **Whether `doctor` should have a quiet mode.** With the wall gone the output is short enough that it has not earned
-  a flag.
-- **Re-announcing a decision whose note is added later.** The digest reads decisions added in a range, so a note
-  written after the fact is not delivered. Notes belong in the change that causes them, which is the standard this
-  decision is a correction toward.

package/docs/decisions/ad-035.md

@@ -1,86 +0,0 @@
----
-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

@@ -1,68 +0,0 @@
----
-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

@@ -1,47 +0,0 @@
----
-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

@@ -1,52 +0,0 @@
----
-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

@@ -1,69 +0,0 @@
----
-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

@@ -1,89 +0,0 @@
----
-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

@@ -1,98 +0,0 @@
----
-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.