@tech-leads-club/harness-toolkit 0.2.1

package/docs/lessons.md

@@ -0,0 +1,294 @@
+---
+type: Concept
+title: "Lessons"
+description: "Durable, ranked lessons that keep the agent from repeating gate failures — three tiers, staleness against a named reference, a validity window, effectiveness measured after injection, lifecycle, config, ranking, and the per-provider rendered view."
+tags: [concept, lessons, intelligence]
+timestamp: "2026-08-04"
+---
+
+# Lessons
+
+Durable, compact lessons that keep the agent from repeating **gate failures**. Ranked inject under a char
+budget — not conversational memory.
+
+Four things decide whether a lesson reaches a turn: which **tier** it lives in, whether it is still **true**
+(its refs resolve, its window is open), how it **ranks**, and whether the budget has room.
+
+## The three tiers
+
+| Tier | Where | Who reads it | Written by |
+|------|-------|--------------|------------|
+| `core` | inside the runtime | every install, identically | shipped — immutable |
+| `global` | `<runtime home>/state/lessons.json` | every product on this machine | `lessons add --global`, `lessons promote` |
+| `project` | `<repo>/.tlc/harness/state/lessons.json` | this repository only | gate stagnation, `lessons add` |
+
+`<runtime home>` is `$TLC_HOME`, or `~/.tlc/harness` when it is unset.
+
+**Choosing a tier.** Ask whether the lesson would still be true in a different product:
+
+- "this repository's CI sets `TLC_HOME`" → **project**
+- "run the gate itself, never an approximation of its steps" → **global**
+
+Ranking reads all three; `projectBoost` keeps the project tier above the global tier, so local knowledge
+outranks knowledge carried in. On a duplicate id the nearer tier wins, so a project that took a global lesson
+and rewrote it reads its own version.
+
+**Nothing crosses between products by itself.** There is no automatic promotion, by design: a lesson mined from
+a gate failure in one product names that product's test runner and file layout, and no threshold can tell
+whether it applies elsewhere. Only the operator can ([/decisions/ad-040.md](/decisions/ad-040.md)).
+
+An injected lesson renders as `[gate/status/tier]`, so a turn reading `[test/active/global]` can tell the advice
+was written about a different repository.
+
+`source` is a different fact from `tier`: it records *how* the lesson was learned — `core`, `project` (mined
+from a gate failure) or `manual` (authored) — not where it lives.
+
+## Staleness — a lesson names what makes it true
+
+A lesson may carry **refs**, each a repository-relative `path` or `path:symbol`. When a ref stops resolving the
+lesson is withheld: a lesson naming a renamed file is worse than absent, because it sends the next turn looking
+for something that no longer exists, with the authority of a lesson.
+
+| Status | Meaning | Stale? |
+|--------|---------|--------|
+| `present` | the path exists, and the symbol appears in it | no |
+| `path-missing` | the path is gone, or was absolute | **yes** |
+| `symbol-missing` | the file survived, the name did not | **yes** |
+| `unreadable` | the file could not be read | no — deferred |
+
+`unreadable` is deliberately not stale. A file this process cannot open is not evidence the lesson stopped being
+true. A lesson with **no refs is never stale** — most lessons are about conduct.
+
+Refs are repository-relative; an absolute path never resolves, or a global lesson would report `present` in every
+product on the machine that happens to contain the file.
+
+`garden` sets and clears staleness for **project** lessons. A **global** lesson is judged per repository at
+selection time instead — its refs may legitimately be missing here and present in the product it came from, so
+one stored flag cannot be right for all of them ([/decisions/ad-036.md](/decisions/ad-036.md)).
+
+## Validity window
+
+`validFrom` / `validTo` (ISO) express knowledge with a known end — "pin the formatter until the toolchain moves".
+Active when `(validFrom absent or ≤ now) and (validTo absent or > now)`.
+
+An **unparseable bound withholds the lesson**. `--until "next tuesday"` is a typo, and treating a broken
+declaration as no declaration would inject exactly what the author meant to limit. `garden` prunes an expired
+lesson, because unlike a broken ref the end was declared by the author
+([/decisions/ad-037.md](/decisions/ad-037.md)).
+
+## Effectiveness — did the lesson help?
+
+Ranking is built from proxies for usefulness. This is the measurement.
+
+When lessons are injected on a retry for gate G, their ids and G go on the handoff. The **next run of gate G**
+grades them: passed → `helped`, failed → `neutral`. The gate name is compared, so lessons injected for `lint` are
+not graded by `test`.
+
+| Reading | Meaning |
+|---------|---------|
+| `helped n/m` | present when that gate recovered, at least once |
+| `neutral 0/m` | present at m failures and no recoveries |
+| `unproven` | injected **for a gate** and never graded — no evidence, not "fine" |
+| `session-only` | injected at session start and never for a gate, so this mechanism cannot measure it |
+| `not-injected` | never shown yet |
+
+Only `unproven` is a `doctor` warning. **A session-start injection is never graded** — only the retry path has a
+gate whose next run can decide — so a lesson with gate `any` is unprovable by this mechanism rather than
+unjustified, and saying otherwise would warn about a healthy store on every run
+([/decisions/ad-044.md](/decisions/ad-044.md)).
+
+The rate is `null` over zero graded injections, never `0` — zero would read as "measured and it never helped",
+which is a claim the harness has not earned.
+
+**This is not causal.** A gate passing after a lesson was injected does not prove the lesson caused it, and
+`neutral` does not mean the lesson was wrong. A causal answer needs the same task run twice, and real work does
+not repeat. The counters do not feed ranking, because boosting on a non-causal signal would make the ranking
+self-confirming ([/decisions/ad-039.md](/decisions/ad-039.md)).
+
+## Lifecycle
+
+```text
+gate stagnation (fingerprint ≥ 2)
+  → upsert candidate lesson (project store), recording the session key
+garden (sessionEnd / tlc harness lessons garden) — both writable tiers
+  → promote candidates (distinct sessions ≥ promoteHitCount)
+  → mark / clear staleness (project tier)
+  → prune expired
+  → decay / quarantine / prune
+inject
+  → sessionStart: active only, top N / maxChars
+  → stop retry: active + matching candidates, gate-scoped; records a pending credit
+grade
+  → next run of the same gate: helped / neutral
+optional
+  → sync provider-native durable view (see Provider views below)
+```
+
+## Config (`intelligence.lessons`)
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `enabled` | false | Master switch |
+| `maxInjectSession` | 5 | Cap at sessionStart |
+| `maxInjectRetry` | 8 | Cap on stop follow-up |
+| `maxCharsSession` | 900 | Char budget session |
+| `maxCharsRetry` | 1400 | Char budget retry |
+| `promoteHitCount` | 2 | Candidate → active, counted in **distinct sessions** |
+| `decayLambda` | 0.02 | Exponential decay per hour since the failure last **recurred** (`lastSeenAt`) |
+| `projectBoost` | 1.5 | Score multiplier for the **project** tier |
+| `syncRulesFile` | `auto` | Write the provider-native durable view: `auto` where the provider does not deliver hook context, `always`, or `never` |
+| `gardenOnSessionEnd` | true | Garden on sessionEnd |
+
+## Ranking
+
+`score = relevance(gate, tokens) × confidence × exp(-λ · hours since lastSeenAt) × projectBoost?`
+
+**Hours are counted from recurrence, never from exposure.** `lastSeenAt` moves only when the failure
+signature happens again; `lastAccessedAt` moves when a lesson is *shown* and is telemetry only. Decay and
+pruning both read `lastSeenAt` — reading the exposure field made relevance self-fulfilling, so a lesson that
+merely matched a gate name kept resetting its own clock and never faded
+([/decisions/ad-023.md](/decisions/ad-023.md)).
+
+**Promotion counts distinct sessions, not `hitCount`.** `hitCount` counts recurrences of the same gate
+fingerprint, and one stuck session produces those by definition — the stagnation rail exists because sessions
+repeat themselves. A record written before session keys existed falls back to `hitCount` so it can still promote
+([/decisions/ad-038.md](/decisions/ad-038.md)).
+
+A lesson also retires when its cause is gone: the garden prunes a `verification` lesson whose stored signal is
+an unresolved gate command, because AD-021 made that class classify as `config` and it can no longer recur.
+
+Pack **whole lesson blocks** under the char budget. Never mid-string `slice` a lesson. When the budget is
+full, omit lower-ranked lessons entirely and append `_(N more active lessons omitted under char budget)_`.
+
+Session inject stops at the first lesson that does not fit (no filler with lower-ranked leftovers).
+Quarantine never injects. Stale and out-of-window lessons are excluded **before** ranking, not scored low.
+
+**The budget usually binds, and says so.** `maxCharsSession` defaults to 900 and a rendered block is four lines,
+so about two fit while `maxInjectSession` says five. The injected block names what it dropped:
+
+```text
+  (3 more eligible lessons omitted under the char budget — raise maxCharsSession to see them)
+```
+
+## Pinning a standing rule
+
+Ranking weighs recurrence, decay and gate match — all estimates about a lesson the harness *inferred*. An
+instruction the operator wrote deliberately has no recurrence to accumulate, so making it compete on score is a
+category error: it loses to a shipped seed and never arrives.
+
+```bash
+tlc harness lessons add "Never declare done without an end-to-end run pasted into the reply." --global --pin
+```
+
+A pinned lesson is placed **before every scored lesson**, in store order. Everything else still binds — staleness,
+the validity window, mode filtering and the char budget — so pinning changes order, not eligibility, and a pinned
+rule naming a renamed file is withheld like any other. Nothing caps how many can be pinned; the budget bounds
+delivery and `lessons list` marks each one `PINNED` ([/decisions/ad-043.md](/decisions/ad-043.md)).
+
+## Provider views
+
+`.tlc/harness/lessons.md` is the source of truth, and the store, the ranking, the budget and the rendered text are
+shared by every provider. What differs is **transport** — how the text reaches the model — and that is a declared
+capability rather than a preference ([/decisions/ad-050.md](/decisions/ad-050.md)):
+
+| Provider | `sessionStartContextReliable` | Rendered view |
+| --- | --- | --- |
+| Cursor | `false` — `additional_context` returned from `sessionStart` is accepted, logged as merged, and dropped; acknowledged by Cursor as a race between the hook and the composer handle (forum 158452, 2026-04-20; reported again against 3.14.7 on 2026-08-02) | `.cursor/rules/harness-lessons.mdc` (`alwaysApply: true`) — the durable route, and on this host the only reliable one |
+| Claude Code | `true` — `SessionStart` delivers `hookSpecificOutput.additionalContext` | a single `@.tlc/harness/lessons.md` import line appended to `CLAUDE.md`, under `always` |
+
+Under the default `auto`, the view is written where the provider does not deliver hook context and withheld where it
+does. `always` writes it everywhere; `never` writes it nowhere, which is how an operator declines a file in their
+repo. A config carrying the field's old boolean still works — `true` reads as `always`, `false` as `never` — and
+`tlc harness lessons list` names the coercion.
+
+The view carries all three tiers and only what would actually be injected, so a withheld lesson never appears there
+and a core or global lesson is not missing from it. It is written at session start as well as session end, because a
+transport that is one session behind carries the previous session's guidance.
+
+`tlc harness obs report` says which of the two is paid: the emission where the host delivers it, the rules file where
+it does not.
+
+## Design notes
+
+| Insight | Applied here |
+|---------|--------------|
+| Lessons are atoms | Whole-block pack in `packLessonsUnderBudget` / the provider-view renderers |
+| Rank before cut | Inject by `rankScore`; sync by priority → hitCount → confidence |
+| Promote on repeat across sessions | distinct `sessionKeys` ≥ `promoteHitCount` |
+| A claim outlives its subject | Refs + staleness, withheld not deleted |
+| Some knowledge expires | Validity window, pruned on expiry |
+| Usefulness is measured, not assumed | helped / neutral / unproven after the next gate run |
+| Knowledge travels, context does not | Three tiers, operator-invoked promotion, tier in the rendered line |
+| Grounded only | Gate stagnation / failures / an author — not chat memory |
+| Noise control | Cap N + maxChars; omit note instead of half-sentences; garden decay/quarantine |
+
+## CLI
+
+```bash
+tlc harness lessons add "<instruction>" [--gate <name>] [--avoid "..."] [--prefer "..."] \
+                        [--tokens a,b] [--ref path[:symbol]] [--until <iso>] [--global] [--pin]
+tlc harness lessons promote <id>          # copy a project lesson into the global tier
+tlc harness lessons list [--all] [--json]
+tlc harness lessons show <id>
+tlc harness lessons garden
+tlc harness lessons sync-rules
+tlc harness lessons path
+```
+
+`--ref` may repeat. `list` marks a withheld lesson `WITHHELD` and reports `effect=`, `validity=`, `stale=` and
+`refs=` per lesson.
+
+**Two different counts at the end, on purpose.** The tier line counts what would be *injected*, after the nearer
+tier wins a duplicate id. The store lines count what is *on disk*. A promoted lesson lives in both stores and
+resolves to the project copy, so without the second pair an operator reads `core=6 project=5` and concludes
+`promote` did nothing:
+
+```text
+11 lessons — core=6 project=5
+stale=0 out-of-window=0 unproven=0 not-injected=11
+project store: <repo>/.tlc/harness/state/lessons.json  (5 lessons)
+global store:  ~/.tlc/harness/state/lessons.json  (5 lessons, 5 also in this project)
+```
+
+`doctor` reports stale, out-of-window and unproven lessons as separate warnings, and stays silent when the
+capability is off or the writable tiers are empty. When everything is healthy it prints one row:
+
+```text
+OK    lesson health — 10 lessons across the writable tiers, none stale, none out of window
+```
+
+## When the synced file looks empty
+
+The synced markdown is a rendering of the store, so an empty one has a reason and now names it
+([/decisions/ad-049.md](/decisions/ad-049.md)):
+
+| What the file says | What is happening |
+| --- | --- |
+| `switched off … intelligence.lessons.enabled is false` | the capability is off, so no gate failure is ever recorded — and off is the default |
+| `No lesson recorded yet` | on, but no failure has repeated inside a session yet |
+| `N candidate lessons recorded, none promoted` | recorded, waiting for the same failure in `promoteHitCount` distinct sessions |
+| `N active lesson is withheld` | promoted, but a ref stopped resolving or a window closed |
+
+Three hurdles stand between a gate failing and that file showing anything: the capability has to be on, the *same*
+failure has to repeat inside a session, and the candidate has to be promoted across distinct sessions. One sentence
+covered all of them, which reads as broken.
+
+**`.specs/LESSONS.md` is not this file.** It belongs to the `/sdd` skill, which keeps its own lessons layer. The
+harness writes one file and nothing else.
+
+## Reading the store from a test
+
+The suite runs with `TLC_HOME` pointed at an empty temporary directory, so no test can read the lessons an
+operator happened to promote on that machine. A test that needs the real runtime home sets it explicitly
+([/decisions/ad-042.md](/decisions/ad-042.md)).
+
+## Trade-offs
+
+| Benefit | Cost |
+|---------|------|
+| Stops repeating the same gate mistake across sessions | Uses context tokens |
+| Gate-scoped + decay stays relevant | Needs enable + occasional garden |
+| A lesson retires when its subject is renamed | Refs are author-supplied; substring matching accepts a false `present` |
+| Knowledge follows the operator across products | A global lesson can be irrelevant in some product; refs and the boost bound it |
+| The store can be defended with numbers | The grading is correlational, not causal |
+| Provider-view sync survives hook races | Can dirty the provider's own rules/memory file if enabled |

package/docs/log.md

@@ -0,0 +1,139 @@
+---
+type: Aggregate
+title: "Documentation log"
+description: "Chronological, ISO 8601 record of every architectural decision, grouped by the date it was taken. Generated from docs/decisions/."
+tags: [log, history, okf]
+timestamp: "2026-08-12"
+---
+
+# Log
+
+Generated from `docs/decisions/` — do not edit by hand. Run `node tools/render-log.ts`.
+
+A reserved file of the [OKF v0.1](/decisions/ad-013.md) bundle: entries grouped under ISO 8601 headings,
+newest first. For what landed in which npm release, see `CHANGELOG.md` at the repository root.
+
+## 2026-08-19
+
+- **AD-081** — The manifest npm publishes is checked here, because the release runner was the only thing reading it ([/decisions/ad-081.md](/decisions/ad-081.md))
+- **AD-082** — npm is the documented install, and the first version cannot come from CI ([/decisions/ad-082.md](/decisions/ad-082.md))
+- **AD-083** — Going public switched the branch ruleset on, and an unattended release needs the App to bypass it ([/decisions/ad-083.md](/decisions/ad-083.md))
+
+## 2026-08-17
+
+- **AD-073** — A neighbour mid-gate is not a reason to block a turn ([/decisions/ad-073.md](/decisions/ad-073.md))
+- **AD-074** — Code the gate cannot read is refused, and a credential is not always a file ([/decisions/ad-074.md](/decisions/ad-074.md))
+- **AD-075** — A dependency a turn adds outlives the turn, so two mechanical failures are worth a stop ([/decisions/ad-075.md](/decisions/ad-075.md))
+- **AD-076** — Goal-hijack enforcement needs the tool's output, and the host does not deliver it ([/decisions/ad-076.md](/decisions/ad-076.md))
+- **AD-077** — A command that appears verbatim in fetched content is put to the operator ([/decisions/ad-077.md](/decisions/ad-077.md))
+- **AD-078** — The two files the harness reads aloud are sealed on write and verified on injection ([/decisions/ad-078.md](/decisions/ad-078.md))
+- **AD-079** — The coverage claim is a generated page with its gaps in it, not a badge in the README ([/decisions/ad-079.md](/decisions/ad-079.md))
+- **AD-080** — Every hand-written list of our own rules is now checked, including the one that drifted while writing this ([/decisions/ad-080.md](/decisions/ad-080.md))
+
+## 2026-08-13
+
+- **AD-068** — A directory decides what ships, and dist is derived from disk in both directions ([/decisions/ad-068.md](/decisions/ad-068.md))
+- **AD-069** — A decision record declares its shape, and cites by link so a move cannot break it ([/decisions/ad-069.md](/decisions/ad-069.md))
+- **AD-070** — A comment has to read for somebody who was not in the session ([/decisions/ad-070.md](/decisions/ad-070.md))
+- **AD-071** — The turn's added lines are checked against the code the project already has ([/decisions/ad-071.md](/decisions/ad-071.md))
+- **AD-072** — A record can leave the corpus, and removing is a change worth recording ([/decisions/ad-072.md](/decisions/ad-072.md))
+
+## 2026-08-12
+
+- **AD-060** — The gate records the environment it ran under, and names it only once the cheap explanations are spent ([/decisions/ad-060.md](/decisions/ad-060.md))
+- **AD-061** — A decision that refuses names its rule, and degrading preserves it ([/decisions/ad-061.md](/decisions/ad-061.md))
+- **AD-062** — One command answers whether the harness did that, and says so plainly when it did not ([/decisions/ad-062.md](/decisions/ad-062.md))
+- **AD-063** — One palette for human output, and a checker keeping it out of everything else ([/decisions/ad-063.md](/decisions/ad-063.md))
+- **AD-064** — A snapshot is assigned, never accumulated, and a table does not list what it cannot count ([/decisions/ad-064.md](/decisions/ad-064.md))
+- **AD-065** — The obs bus has a contract, and the gate checks both sides of it ([/decisions/ad-065.md](/decisions/ad-065.md))
+- **AD-066** — Uninstall reads the artefact, and the plan is the confirmation ([/decisions/ad-066.md](/decisions/ad-066.md))
+- **AD-067** — A reserved file that cannot be retired is rendered, and the gate holds it there ([/decisions/ad-067.md](/decisions/ad-067.md))
+
+## 2026-08-10
+
+- **AD-058** — Gates diff against the turn's base, and language knowledge is one table ([/decisions/ad-058.md](/decisions/ad-058.md))
+- **AD-059** — A rail never writes a field it reads, and a counter reads the plane its events land on ([/decisions/ad-059.md](/decisions/ad-059.md))
+
+## 2026-08-07
+
+- **AD-054** — npm is the distribution, and a merged release PR is the only thing that publishes ([/decisions/ad-054.md](/decisions/ad-054.md))
+- **AD-055** — The changelog is rendered from the decision records, and git says which release each landed in ([/decisions/ad-055.md](/decisions/ad-055.md))
+- **AD-056** — The package delivers the runtime, and the runtime path stays where hooks already point ([/decisions/ad-056.md](/decisions/ad-056.md))
+- **AD-057** — The release PR is a mechanism, not a gate, and the bot merges it ([/decisions/ad-057.md](/decisions/ad-057.md))
+
+## 2026-08-06
+
+- **AD-053** — The harness ships no model allowlist, and a list that names nothing enforces nothing ([/decisions/ad-053.md](/decisions/ad-053.md))
+
+## 2026-08-05
+
+- **AD-045** — A gate verdict is reused when the content hash of its inputs did not change ([/decisions/ad-045.md](/decisions/ad-045.md))
+- **AD-046** — The runtime path is an artifact, and update never touches what it does not own ([/decisions/ad-046.md](/decisions/ad-046.md))
+- **AD-047** — An instruction is not an affordance, and a refusal names the route that works ([/decisions/ad-047.md](/decisions/ad-047.md))
+- **AD-048** — A broken updater cannot deliver its own fix, so the installer is the recovery route ([/decisions/ad-048.md](/decisions/ad-048.md))
+- **AD-049** — An empty synced file says which of four reasons made it empty ([/decisions/ad-049.md](/decisions/ad-049.md))
+- **AD-050** — Lesson transport is a provider capability, not an operator preference ([/decisions/ad-050.md](/decisions/ad-050.md))
+- **AD-051** — A warning fails the gate, and a suppression states what breaks without it ([/decisions/ad-051.md](/decisions/ad-051.md))
+- **AD-052** — The repository moves to the org and the runtime paths do not ([/decisions/ad-052.md](/decisions/ad-052.md))
+
+## 2026-08-04
+
+- **AD-024** — The gate tells the truth about its own environment, its own lock, and the cause of a failure ([/decisions/ad-024.md](/decisions/ad-024.md))
+- **AD-025** — Posture governs surfacing only, and each posture has exactly one name ([/decisions/ad-025.md](/decisions/ad-025.md))
+- **AD-026** — An interruption is worth what it costs: narrower asks, a deadline on questions, and a rate the operator can see ([/decisions/ad-026.md](/decisions/ad-026.md))
+- **AD-027** — Evidence is ordered against the code, every rail's firing is recorded, and a checker can run with its rule off ([/decisions/ad-027.md](/decisions/ad-027.md))
+- **AD-028** — A resolved failure is kept, a session attests to itself, and provider neutrality becomes a proof ([/decisions/ad-028.md](/decisions/ad-028.md))
+- **AD-029** — A capability the init skill cannot correctly initialise is not shipped ([/decisions/ad-029.md](/decisions/ad-029.md))
+- **AD-030** — Clearing a policy divergence is one operator command behind four independent locks, and a refusal never points an agent at a door the floor holds shut ([/decisions/ad-030.md](/decisions/ad-030.md))
+- **AD-031** — The decisions are the changelog, a breaking change carries its own instruction, and looking never changes anything ([/decisions/ad-031.md](/decisions/ad-031.md))
+- **AD-032** — A hook is healthy when it can run, not when a marker string is present ([/decisions/ad-032.md](/decisions/ad-032.md))
+- **AD-033** — The gate says what it costs, appendFiles stops promising what it cannot deliver, and a dead capability leaves ([/decisions/ad-033.md](/decisions/ad-033.md))
+- **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 ([/decisions/ad-034.md](/decisions/ad-034.md))
+- **AD-035** — A lesson learned by reasoning can be written down, and the harness never learns where lessons come from ([/decisions/ad-035.md](/decisions/ad-035.md))
+- **AD-036** — A lesson names what makes it true, and stops being injected when that is gone ([/decisions/ad-036.md](/decisions/ad-036.md))
+- **AD-037** — A lesson can be true for a period, and an unparseable bound withholds it ([/decisions/ad-037.md](/decisions/ad-037.md))
+- **AD-038** — Promotion counts distinct sessions, because one stuck session is one observation ([/decisions/ad-038.md](/decisions/ad-038.md))
+- **AD-039** — A lesson is graded by the gate it was injected for, and unproven is not a passing reading ([/decisions/ad-039.md](/decisions/ad-039.md))
+- **AD-040** — Three lesson tiers, and nothing crosses between products by itself ([/decisions/ad-040.md](/decisions/ad-040.md))
+- **AD-041** — A member something reads and nothing writes fails the gate ([/decisions/ad-041.md](/decisions/ad-041.md))
+- **AD-042** — The suite gets an empty runtime home, and one renderer renders a lesson ([/decisions/ad-042.md](/decisions/ad-042.md))
+- **AD-043** — A standing rule is pinned, not ranked, and the budget says what it dropped ([/decisions/ad-043.md](/decisions/ad-043.md))
+- **AD-044** — Only an injection a gate could grade can be unproven ([/decisions/ad-044.md](/decisions/ad-044.md))
+
+## 2026-08-03
+
+- **AD-023** — One finding per failure, and lesson relevance is recurrence rather than exposure ([/decisions/ad-023.md](/decisions/ad-023.md))
+
+## 2026-07-31
+
+- **AD-022** — The policy surface is a floor rule, detection sits behind interception, and the operator/agent line is structural ([/decisions/ad-022.md](/decisions/ad-022.md))
+
+## 2026-07-30
+
+- **AD-017** — The docs gate delegates to the project's tool, and the catalog is the only source of capability metadata ([/decisions/ad-017.md](/decisions/ad-017.md))
+- **AD-018** — Three rails adopted from an external review, each off by default and declared rather than inferred ([/decisions/ad-018.md](/decisions/ad-018.md))
+- **AD-019** — A resource is identified by what it resolves to, and a declared capability must be read where it matters ([/decisions/ad-019.md](/decisions/ad-019.md))
+- **AD-020** — One resolution for the install path, one source for posture, and a config that only advertises what it reads ([/decisions/ad-020.md](/decisions/ad-020.md))
+- **AD-021** — A gate command that never resolved is a config fault, and a recipe runner does not receive file arguments ([/decisions/ad-021.md](/decisions/ad-021.md))
+
+## 2026-07-29
+
+- **AD-002** — Provider-neutral naming and layout ([/decisions/ad-002.md](/decisions/ad-002.md))
+- **AD-003** — No backward compatibility ([/decisions/ad-003.md](/decisions/ad-003.md))
+- **AD-004** — Ports and adapters with an anti-corruption layer per provider ([/decisions/ad-004.md](/decisions/ad-004.md))
+- **AD-005** — Local test runner is the gate; CI matrix runs on every push ([/decisions/ad-005.md](/decisions/ad-005.md))
+- **AD-006** — Windows ships in scope, with CI covering the suite and the build ([/decisions/ad-006.md](/decisions/ad-006.md))
+- **AD-007** — Vendor check applies to core tests; absence checks do not ([/decisions/ad-007.md](/decisions/ad-007.md))
+- **AD-008** — Biome + TypeScript in the gate; @types/node pinned to the declared floor ([/decisions/ad-008.md](/decisions/ad-008.md))
+- **AD-009** — Event kinds are provider-agnostic; capabilities are data, not flags ([/decisions/ad-009.md](/decisions/ad-009.md))
+- **AD-010** — Shared vocabulary moves to src/contracts/ ([/decisions/ad-010.md](/decisions/ad-010.md))
+- **AD-011** — Vendor-specific data belongs to the provider, not to core ([/decisions/ad-011.md](/decisions/ad-011.md))
+- **AD-012** — Prefer Bun at runtime, keep dist/ for the Node fallback, ship no binary ([/decisions/ad-012.md](/decisions/ad-012.md))
+- **AD-013** — Documentation follows the Open Knowledge Format (OKF v0.1) ([/decisions/ad-013.md](/decisions/ad-013.md))
+- **AD-014** — Claude Code hook payload field paths, pinned ([/decisions/ad-014.md](/decisions/ad-014.md))
+- **AD-015** — Wiring handler names are the entrypoint filenames ([/decisions/ad-015.md](/decisions/ad-015.md))
+- **AD-016** — Field semantics, state writers, and the core export surface ([/decisions/ad-016.md](/decisions/ad-016.md))
+
+## 2026-07-27
+
+- **AD-001** — Optional parent-Fast sticky deny for Task spawns ([/decisions/ad-001.md](/decisions/ad-001.md))

package/docs/measure.md

@@ -0,0 +1,178 @@
+---
+type: Runbook
+title: "Measure"
+description: "How to read harness observability: status, live signal, raw signal, session reports, audit trail, price catalogs, and the on-disk project state files, all provider-tagged."
+tags: [runbook, measure, observability, pricing]
+timestamp: "2026-07-29"
+---
+
+# Measure
+
+Run from the project root, or set `TLC_PROJECT_DIR`.
+
+## Status
+
+```bash
+tlc harness status
+```
+
+Shows mode, grind on/off, and whether stop gates are paused.
+
+## Live signal
+
+```bash
+tlc harness obs live
+```
+
+Allowlisted tail of signal events (session, prompt, fails, denials, gates, compact, subagents, cost alerts).
+
+## Raw signal
+
+```bash
+tlc harness obs events [n]
+```
+
+Last N JSON lines from `obs.jsonl`.
+
+## Session report
+
+```bash
+tlc harness obs report [conversation_id]
+```
+
+Markdown rollup: tokens, estimated USD, tools, subagents, gates. Writes under
+`.tlc/harness/state/reports/`.
+
+```bash
+tlc harness obs rollup <conversation_id>
+tlc harness obs prune
+```
+
+`rollup` prints the raw JSON rollup for one session; `prune` deletes rollups older than
+`retentionDays` (default 14).
+
+## Machine-readable output
+
+Every read command accepts `--json` and then writes exactly one JSON value to stdout and no prose, so a CI
+step or an agent can parse it instead of scraping text:
+
+```bash
+tlc harness status --json
+tlc harness doctor --json          # { ok, failed, warned, checks: [{ id, name, status, detail }] }
+tlc harness obs live --json        # { count, events: [...] }
+tlc harness obs report --json      # { session, path, rollup }
+tlc harness lessons list --json
+tlc harness prices lookup <model> --json
+```
+
+Without the flag, output is byte-identical to what it has always been. Exit codes do not change either: a
+failing `doctor --json` still exits 1 and still emits a parseable value, with `ok: false`, so a caller can
+branch on the code or on the payload.
+
+## Global spool
+
+`obs.globalSpool` (off by default) mirrors every obs and audit record into a single file under the runtime
+home — `~/.tlc/harness/state/obs-spool.jsonl` — wrapping each one with the repository path and project name:
+
+```json
+{"repo":"/work/my-repo","project":"my-repo","stream":"obs","record":{...}}
+```
+
+That is what makes cost and gate history readable across every repository at once; per-repo files stay
+authoritative and untouched. Writes are best-effort — an unwritable runtime home degrades to project-only
+recording rather than failing a hook. `tlc harness obs prune` prunes the spool on the same retention window
+as session rollups and reports how many records it dropped.
+
+When the runtime home is itself a checkout reached through a symlink, the spool lands in that checkout's
+`state/` directory, which `.gitignore` already covers for exactly this case.
+
+## Retention
+
+`tlc harness obs prune` reads `obs.retentionDays` from project policy (default 14) and applies it to session
+rollups and to the spool, reporting how many spool records it dropped. The other tunables — `includePayloads`,
+`maxAttrChars`, `sessionCostAlertUsd` — are described in [/concepts.md](/concepts.md).
+
+## Observability planes
+
+Every record carries a `provider` field (`"cursor" | "claude"`) so signal, debug, and audit records from a
+multi-provider project stay attributable per-event, not just per-project (see
+[/decisions/ad-011.md](/decisions/ad-011.md)).
+
+| Plane | File | Default | Contents |
+|-------|------|---------|----------|
+| Signal | `.tlc/harness/state/obs.jsonl` | ON | lifecycle, fails, denials, gates, cost alerts, ship claims |
+| Debug | `.tlc/harness/state/debug.jsonl` | OFF | happy-path tool/shell/mcp noise |
+| Audit | `.tlc/harness/state/audit.jsonl` | ON | one record per hook invocation (`{ ts, event, payload }`), restored per [/decisions/ad-016.md](/decisions/ad-016.md) item 7 so a denied/asked shell command is never silently unaudited |
+
+Set `"observability": { "debugEnabled": true }` in user or project config to also capture debug-level
+events. `shell.end` is promoted from debug to signal automatically whenever the permission was not a plain
+allow — an audited denial should never require opting into debug mode to see.
+
+18 `HarnessEventKind` values map onto a smaller set of `ObsKind` values (`session.start`, `tool.start`,
+`shell.end`, `gate.outcome`, `cost.turn`, …) — see `src/core/observability/observability.types.ts` for the
+full mapping table.
+
+## Prices
+
+Cost estimates use on-disk catalogs under `~/.tlc/harness/`, resolved provider-first:
+
+```bash
+tlc harness prices refresh
+tlc harness prices refresh all
+tlc harness prices refresh cursor
+tlc harness prices refresh litellm
+tlc harness prices lookup <model-id> [provider]
+```
+
+| Command | Effect |
+|---------|--------|
+| `refresh` / `refresh all` | Update the Cursor catalog and the LiteLLM fallback |
+| `refresh cursor` | Write `model-prices.cursor.json` (commit when rates change) |
+| `refresh litellm` | Write `model-prices.litellm.json` (gitignored; regenerate locally) |
+| `lookup <model-id> [provider]` | Resolve catalog key, pool, and USD for 1M input + 1M output |
+
+### Catalogs
+
+| File | Role | In git |
+|------|------|--------|
+| `model-prices.<provider>.json` (e.g. `model-prices.cursor.json`) | Primary, per provider | Yes |
+| `model-prices.litellm.json` | Fallback (LiteLLM public JSON) | No |
+| `model-prices.json` | Local overrides | Empty `{}` template only |
+| `model-aliases.json` | Model id → catalog key | Yes |
+
+### Resolution order
+
+1. `model-prices.json` (local overrides)
+2. `model-prices.<provider>.json` (this provider's own catalog)
+3. `model-prices.litellm.json`
+4. otherwise `cost_usd: null`
+
+Pools (neutral names in observability records; see [/decisions/ad-011.md](/decisions/ad-011.md) item 2):
+`provider_native` | `other` | `auto` | `unknown`. The on-disk catalog files still use vendor-named pool
+keys internally (`cursor_models`, `anthropic_models`, …) since pricing must name real vendors — those are
+mapped to the neutral names before they reach `core/`.
+
+### When to refresh
+
+| Situation | Command |
+|-----------|---------|
+| A provider published new rates or models | `tlc harness prices refresh cursor` (then commit) |
+| Missing LiteLLM file or obscure model | `tlc harness prices refresh litellm` |
+| Update both catalogs | `tlc harness prices refresh` |
+| Inspect one model | `tlc harness prices lookup <model-id> [provider]` |
+
+`tlc harness doctor` requires at least one provider catalog to be present. LiteLLM is optional until needed
+as fallback.
+
+## Project state files
+
+| Path | Contents |
+|------|----------|
+| `.tlc/harness/state/obs.jsonl` | Signal |
+| `.tlc/harness/state/debug.jsonl` | Debug (if enabled) |
+| `.tlc/harness/state/audit.jsonl` | Verbose per-hook audit trail |
+| `.tlc/harness/state/sessions/*.json` | Per-conversation rollups |
+| `.tlc/harness/state/handoff.json` | Cross-turn handoff |
+| `.tlc/harness/state/ship-ledger.jsonl` | Ship claim / challenge / pass rows |
+| `.tlc/harness/state/lessons.json` | Project lessons store |
+| `.tlc/harness/state/parent-model.json` | Sticky parent-model snapshot (see [/decisions/ad-001.md](/decisions/ad-001.md)) |