@tech-leads-club/harness-toolkit 0.2.1

package/skills/harness-init/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: harness-init
+description: Mandatory interactive wizard to connect a repo to the global harness (writes .tlc/harness/config.json + shim hooks via tlc-exec, for whichever of Cursor / Claude Code are installed). Use when the user says setup harness, init harness, enable harness, ligar o harness, bootstrap harness, configure harness for this repo, or wants lessons/grind/shipGate policy chosen with trade-offs. Do NOT use for status (tlc harness status), expert Q&A (tlc harness help), grind/mode toggles alone, or explaining metrics (send those to tlc harness help).
+license: CC-BY-4.0
+metadata:
+  author: Felipe Rodrigues
+  version: 1.0.0
+---
+
+# Harness init (mandatory project wizard)
+
+Connect the **global** harness runtime to **this** repo, for whichever providers are actually installed
+(Cursor, Claude Code, or both). The skill is required for setup; **each capability is optional** and must
+be chosen with benefit / trade-off / default.
+
+Help SoT is CLI docs (`tlc harness help <topic>`), not this skill. For Q&A only, stop and send the user to
+`tlc harness help`.
+
+## Instructions
+
+### Step 1: Preconditions
+
+1. Run `tlc harness doctor` and `tlc harness help init`.
+2. If global runtime checks FAIL (Node 24+, `dist/`, `tlc-exec`), stop and fix the global install
+   (`tlc harness build`, PATH link) before project policy.
+3. Detect which providers are installed. **Resolve the directories, do not assume them**: Claude Code
+   honours `CLAUDE_CONFIG_DIR` and Cursor honours `CURSOR_CONFIG_DIR`, so a relocated config is common
+   and wiring the default path would write a file the agent never reads. `tlc harness doctor` prints the
+   resolved target for each provider — read it from there rather than guessing. Tell the user which
+   provider(s) will be wired. Never assume Cursor: a Claude-only machine has no Cursor directory at all.
+4. If `.tlc/harness/config.json` already exists, show it and ask: **overwrite**, **merge**, or **abort**.
+
+### Step 1b: Hook runtime (ask once, never block)
+
+Hooks fire on every tool call, shell command, file read and stop — dozens per agent turn — so the runtime
+that launches them dominates their cost, regardless of which provider is in use.
+
+Check whether **Bun** is on `PATH`.
+
+**Bun present** → say so in one line and move on.
+
+**Bun absent** → present it as a trade-off, not a warning, with the measured numbers:
+
+```
+Hook runtime: Node (Bun not found)
+  Bun runs each hook in ~1ms; Node needs ~27ms.
+  At ~30 hooks per turn that is ~30ms vs ~810ms of startup.
+  Install: curl -fsSL https://bun.sh/install | bash
+  Node works fine — just slower. Continue on Node?
+```
+
+Rules:
+
+- **Never block.** Node is fully supported. The question is "continue?", not "install first".
+- **Never ask twice.** Record the answer in the project's harness state; on later runs skip this step.
+  `doctor` keeps reporting it as a non-failing `WARN`.
+- **Always give the number.** "~1ms vs ~27ms" lets the user decide; "faster" gets ignored.
+- If the user installs Bun mid-wizard, re-check before continuing rather than trusting the earlier probe.
+
+### Step 1c: State the floor once (no question attached)
+
+Before offering any choice, tell the user what holds regardless of configuration. Read the
+**Not configurable** table in `references/capabilities.md` and state it in two or three lines. This is not
+a question and nothing here is optional; skipping it means their first denial looks like a defect.
+
+### Step 2: Discovery (never skip)
+
+Read `references/capabilities.md` **now** (full menu + lessons automation table).
+
+Work **one capability at a time** from that catalog. For each: name → benefit → trade-off → default → ask
+yes/no → if yes, collect values. Stay stack-agnostic.
+
+When presenting **Subagent allowlist** (capability 6), also present **Block parent Fast** (capability 6b /
+`subagents.blockParentFast`, default **off**) from `references/capabilities.md` in the same pass: benefit →
+trade-off → default → ask yes/no. Write `blockParentFast: true` only if the user accepts.
+
+If the user accepts the allowlist, **collect the model slugs from them**. The harness ships no catalogue, and
+`enforceAllowlist: true` with an empty `allowedModels` enforces nothing — `doctor` reports it as a fault. Do not
+propose slugs: a suggested list is a shipped default one conversation later, and the one that used to be shipped is
+exactly what went stale ([/decisions/ad-053.md](/decisions/ad-053.md)). Tell them the values their provider accepts
+are in its own model picker, that a variant suffix such as `-thinking-high` needs its own entry, and that `inherit`
+is a value the list may contain. If they accept the capability but have no list ready, write
+`enforceAllowlist: false` and say why.
+
+Do **not** enable anything the user did not accept. Do **not** invent stack commands.
+
+### Step 2b: Comment gate — four choices, ask explicitly
+
+Agents narrate. Prose in an instruction file does not stop it, so this is the deterministic gate.
+It compares added lines against the commit the turn started from, so comments already committed are
+never flagged — and a turn that commits its own work cannot move the base past its own lines.
+
+Present all four and let the user pick:
+
+```
+off         — no comment gate. Anything the agent writes lands.
+declared    — an added comment must declare a reason: why: / hazard: / invariant:
+              Narration is blocked; a real hazard can be recorded without interrupting you.
+              Cost: a marker prefix no other codebase uses.
+resolvable  — declared, plus the question a marker cannot answer: can a reader who was not
+              in this session check the comment? Blocks change narration ("this used to"),
+              citations only the session saw ("(decision 3)", "per the plan"), PR vantage
+              ("this PR"), and comments arguing their own correctness.
+              Cost: a phrase-level rule, so it refuses some sentences that were fine.
+strict      — no agent-added comments at all. If one is warranted the agent says so in
+              its reply and you write it. Cost: interrupts more; zero invented convention.
+```
+
+Write `comments.enabled: false` for **off**, or `comments.enabled: true` with
+`comments.mode: "declared" | "resolvable" | "strict"`. Default is off, like every other capability.
+
+In every mode a `/** */` comment attached to a declaration is judged differently: it does not need a
+marker, but it must say something its identifier does not already say. A floating `/** */` inside a
+function body is not attached to anything, so it counts as an ordinary comment.
+
+Tool directives (`biome-ignore`, `@ts-`, `noqa`, `shellcheck`, shebang) are exempt in every mode.
+
+### Step 2c: Idle-turn gate (capability 17 — offer it, default off)
+
+The mode lines tell the agent not to interrupt for reversible work, but that is prose and prose is
+probabilistic. This is the deterministic half.
+
+It blocks the stop when a turn ends with open handoff work, **zero recorded tool calls and zero file
+changes**. It counts events the harness already recorded — it never reads or judges the agent's reply,
+so there is no wording that satisfies it. Works on both providers, since both fire tool hooks.
+
+Ask yes/no. Default off. Turn it off for conversational repos where answering without touching files
+is a normal turn.
+
+### Step 2d: Docs staleness gate (capability 18 — offer it, default off)
+
+Code changes pass lint, tests and the ship gate; the documents describing them pass nothing. This gate runs
+**the repository's own** staleness tool on stop, the same way grind runs its lint and test. The harness does
+not infer staleness from paths: mapping directories to documentation was measured reporting on 82–100% of
+commits, which detects nothing.
+
+So the question is which tool the repository has, not which globs to write. Look for evidence before asking:
+
+```
+drift.lock, .drift/           → drift (AST anchors; command is usually: drift check)
+openapi.yaml + oasdiff in CI  → oasdiff (usually: oasdiff changelog <base> <head> --fail-on-diff)
+sgconfig.yml, ast-grep rules  → ast-grep (usually: ast-grep scan)
+a docs script in package.json → that script
+```
+
+Ask, in this order:
+
+1. Is there such a tool? If the repository has none, **say so and leave the capability off.** A gate with
+   nothing to run is not worth configuring, and inventing a command is worse than no gate.
+2. If there is one, ask for the exact argv array. Never guess flags.
+3. `warn` or `deny`. Default `warn`; reserve `deny` for a surface where a stale document is actively harmful.
+
+The tool owns its own escape hatch — `drift` requires an explicit confirmation that the document was read
+before re-stamping — so the harness adds no skip token of its own.
+
+### Step 3: Confirm
+
+Show the **full proposed** `.tlc/harness/config.json` in a fenced block (English keys/strings only). Ask
+explicit confirmation before writing.
+
+### Step 4: Write
+
+Only after confirmation:
+
+1. Prefer: `echo '<policy-json>' | tlc harness init --write --stdin-json`
+2. If that fails: write `.tlc/harness/config.json` yourself; `tlc harness init --minimal` only as last
+   resort for hooks/gitignore, then re-apply the agreed policy.
+3. Shim hooks must call `$HOME/.tlc/harness/bin/tlc-exec shim <handler>` (never `bun run …/src/*.ts`
+   directly, and never a bare `harness-exec` from the predecessor layout).
+4. `tlc harness init` writes project shim hooks only for providers detected present, using the config
+   directory each provider actually resolves to — the defaults are `~/.cursor` and `~/.claude`, but
+   `CURSOR_CONFIG_DIR` and `CLAUDE_CONFIG_DIR` override them and a relocated config is common. Take the
+   resolved paths from `tlc harness doctor` rather than assuming either default.
+5. Ensure `.gitignore` covers `.tlc/harness/state/`.
+6. If `intelligence.lessons.enabled` is true and `syncRulesFile` is not `never`, run `tlc harness lessons
+   sync-rules` once after write. Under the default `auto` the durable view is written where the provider does not
+   deliver hook context, so do not ask the user to choose a transport — ask only whether they want the file at all.
+7. Run `tlc harness status` and `tlc harness doctor`.
+8. Tell the user: reload/restart the provider session if hooks were new; next agent turn should set
+   `TLC_ACTIVE`; day-to-day help is `tlc harness help`.
+
+**Never** create `<repo>/.cursor/commands/` or an equivalent project-local commands directory for harness
+slash commands — keep provider-native commands global.
+
+### Step 5: Explain automation (if lessons or grind enabled)
+
+State clearly what runs **without further prompts**:
+
+- Grind/ship/comments/intelligence rails fire on **stop** / **sessionStart** via hooks, on every wired
+  provider.
+- Ship gate (when enabled) reacts **only** to an explicit `HARNESS_SHIP_CLAIM: …` line — free-English
+  "done/shipped" is ignored. Prefer `runtimePathExcludes` (defaults include `.tlc/`, `.cursor/`, `.claude/`)
+  over pausing gates forever.
+- Lessons (when enabled): auto-record on **stagnation**, auto-inject on start/retry, auto-garden on
+  sessionEnd; the provider-native durable view (Cursor's `.cursor/rules/harness-lessons.mdc` or Claude's
+  `CLAUDE.md` import line) syncs only if configured.
+- Enabling capabilities is never automatic — only what the user opted into during discovery.
+
+## Examples
+
+### Example 1: New repo, Cursor only
+
+User: "setup harness here"
+Actions: doctor → detect Cursor installed, Claude Code not → read capabilities.md → one-by-one opt-in →
+confirm JSON → `tlc harness init --write --stdin-json` → status/doctor
+Result: policy + Cursor shim; features only where user said yes
+
+### Example 2: Repo already used with Claude Code, enabling lessons
+
+User: "ligar lessons no harness deste repo"
+Actions: show current `.tlc/harness/config.json` → explain auto record/inject/garden + `syncRulesFile`
+trade-off → merge `intelligence.lessons` → confirm → write → `tlc harness lessons sync-rules` if sync on →
+doctor
+Result: lessons enabled; no unrelated feature flips; only Claude's `CLAUDE.md` import line is touched,
+since Cursor is not installed on this machine
+
+### Example 3: Wrong skill
+
+User: "how do I see harness metrics?"
+Actions: do **not** run init; tell them `tlc harness help measure`
+Result: no files written
+
+## Troubleshooting
+
+### Error: tlc not found
+
+Cause: CLI not on PATH.
+Solution: `ln -sfn ~/.tlc/harness/bin/tlc ~/.local/bin/tlc`
+
+### Error: doctor fails Node / dist
+
+Cause: neither Bun nor Node 24+ is available, or the bundles are missing.
+Solution: either is enough — `curl -fsSL https://bun.sh/install | bash`, or Node 24 LTS / 26 Current from
+nodejs.org. Bun needs no build step; on Node run `tlc harness build`. Reload the editor session afterwards.
+Doctor reports an old Node as `OK` when Bun covers it, so check the `hook runtime` line too.
+
+### Error: doctor fails global runtime
+
+Cause: incomplete `~/.tlc/harness` or hooks still pointing at a predecessor path (`~/.cursor/agent-harness`,
+`harness-exec`).
+Solution: fix global hooks to `tlc-exec` under `~/.tlc/harness`; rebuild dist.

package/skills/harness-init/evals/trigger_evals.json

@@ -0,0 +1,86 @@
+[
+  {
+    "query": "setup harness",
+    "should_trigger": true,
+    "phrase": "setup harness",
+    "note": "the canonical opening phrase named in the description"
+  },
+  {
+    "query": "setup harness aqui neste repo, quero escolher as regras",
+    "should_trigger": true,
+    "phrase": "setup harness",
+    "note": "same intent in Portuguese, with the policy choice made explicit"
+  },
+  {
+    "query": "init harness for this project",
+    "should_trigger": true,
+    "phrase": "init harness",
+    "note": "init is the CLI verb; the wizard owns the interactive path"
+  },
+  {
+    "query": "enable harness on this repository",
+    "should_trigger": true,
+    "phrase": "enable harness",
+    "note": "enable reads as first-time connection, not as a single toggle"
+  },
+  {
+    "query": "ligar o harness neste repositório",
+    "should_trigger": true,
+    "phrase": "ligar o harness",
+    "note": "Portuguese trigger; the skill is bilingual by description"
+  },
+  {
+    "query": "bootstrap harness",
+    "should_trigger": true,
+    "phrase": "bootstrap harness",
+    "note": "bootstrap implies writing project policy plus shim hooks"
+  },
+  {
+    "query": "configure harness for this repo",
+    "should_trigger": true,
+    "phrase": "configure harness for this repo",
+    "note": "configure plus repo scope is the wizard, not the help topic"
+  },
+  {
+    "query": "quero definir a política de lessons e grind com os trade-offs explicados",
+    "should_trigger": true,
+    "phrase": "policy",
+    "note": "policy chosen with trade-offs is a listed trigger even without the word harness"
+  },
+  {
+    "query": "I want the shipGate policy for this project, walk me through the trade-offs",
+    "should_trigger": true,
+    "phrase": "policy",
+    "note": "shipGate policy with trade-offs routes to discovery, capability by capability"
+  },
+  {
+    "query": "qual o status do harness agora?",
+    "should_trigger": false,
+    "note": "status is a non-goal — answer with tlc harness status, never run the wizard"
+  },
+  {
+    "query": "how do I see harness metrics?",
+    "should_trigger": false,
+    "note": "explaining metrics is a non-goal — send this to tlc harness help measure"
+  },
+  {
+    "query": "what does the ship gate actually do?",
+    "should_trigger": false,
+    "note": "expert Q&A is a non-goal — the help topics are the source of truth, not the wizard"
+  },
+  {
+    "query": "turn grind off",
+    "should_trigger": false,
+    "note": "a grind toggle alone is a non-goal — tlc harness grind off, no discovery pass"
+  },
+  {
+    "query": "mude o mode para paired",
+    "should_trigger": false,
+    "note": "a mode toggle alone is a non-goal — tlc harness mode paired"
+  },
+  {
+    "query": "run the tests and fix whatever fails",
+    "should_trigger": false,
+    "note": "ordinary engineering work; nothing about connecting a repo to the harness"
+  }
+]

package/skills/harness-init/references/capabilities.md

@@ -0,0 +1,113 @@
+# Capability catalog (load when running discovery)
+
+Read this file during the Discovery step of harness-init. Present **one capability at a time**: name →
+benefit → trade-off → default → ask yes/no → if yes, collect values.
+
+Stay **stack-agnostic** (never assume Biome, Vitest, npm, Bun, pytest) and **provider-agnostic** (never
+assume Cursor — check what Step 1 detected).
+
+## Always ask once (before capabilities)
+
+- `projectName` (optional string)
+- `codePaths` (dirs that count as code for grind)
+- starting `mode`: `paired` | `solo` | `focus` (default `solo`) — how much the agent surfaces; verification is
+  identical at all three. No other value is accepted
+
+## Capabilities (all optional)
+
+<!-- generated:capabilities -->
+
+| # | Capability | Key | Default | Benefit | Trade-off | Extra asks if yes |
+|---|------------|-----|---------|---------|-----------|-------------------|
+| 1 | Grind (lint/test on stop) | `grind.enabled` | off | Re-checks lint/test after each completed turn and follow-ups until gates pass. | Uses turns; flaky commands thrash the agent. The gate's cost is paid once per attempt, up to maxLoops — a four-minute suite with maxLoops 5 can spend twenty minutes on tests alone. tlc harness obs report shows the runs and the total. | `lintCommand`, `testCommand`, `maxLoops` |
+| 2 | Ship gate | `shipGate.enabled` | off | Blocks false done after an explicit HARNESS_SHIP_CLAIM when evidence is missing. | Needs a real evidenceDir workflow; free-English done is ignored. | `evidenceDir`, `runtimePathPrefixes`, `runtimePathExcludes`, `evidenceMaxAgeHours`, `claimWindowMinutes` |
+| 3 | Empty-diff anti-ship | `shipGate.emptyDiffAntiShip` | off | Blocks a ship claim when the working tree has zero changes. | Annoys when a zero-diff claim is intentionally correct. | `requires shipGate enabled` |
+| 4 | Comment gate (agent-added comments) | `comments.enabled` | off | Blocks the stop when this turn added comment lines, so narration never lands. Diff-scoped: comments you already committed are never flagged. | Three modes. declared lets the agent keep a comment by writing why:/hazard:/invariant:; resolvable adds the question the marker cannot answer — can a reader who was not in the session check this? — and catches change narration, dead plan or decision citations, and comments arguing with a reviewer; strict accepts none and asks you to write it instead. Each is stricter and interrupts more. | `mode: declared \| resolvable \| strict` |
+| 5 | Duplication gate (agent-added copies) | `duplication.enabled` | off | Blocks the stop when the turn wrote six or more lines the project already has, naming both sites. Diff-scoped: what was already duplicated is not counted. | Reads every tracked file on stop, bounded at 2000 files and 8 MB, and says when a bound was reached. Comments, dependency declarations and pure data — object literals, type bodies, export lists — are excluded, so it reports duplicated logic and misses duplicated shape. | `minRun: lines a run must reach before two copies count (default 6)` |
+| 6 | Supply-chain gate (dependencies this turn added) | `supplyChain.enabled` | off | Blocks the stop when a dependency added this turn is not recorded in a lockfile, or is specified as latest/*/no version. A dependency added in a turn runs on every later turn, in CI, and on every machine that installs the project. | Recognises a manifest by filename from one table, so an ecosystem the table does not carry is not covered. For a JSON manifest the declared dependency sections decide, so it reads the manifest as it stands — without that, a rename or a scripts entry reads as a dependency. It does not check advisories, licences or typosquats: those need the network on every stop. | — |
+| 7 | Subagent allowlist | `subagents.enforceAllowlist` | off | Restricts Task/subagent models to a list you write, and blocks *-fast shapes by default. | The harness ships no model list, so switching this on without filling allowedModels enforces nothing and doctor reports it as a fault. You maintain the list as providers add models — including a value for `inherit` if you want subagents to take the parent's model. | `allowedModels`, `requireModel`, `blockMode` |
+| 8 | Block parent Fast mode for Task spawns | `subagents.blockParentFast` | off | Denies Task/subagentStart while the parent chat is in Fast mode (sticky from hooks), closing the gap where Task slugs omit *-fast. | Needs parent model hooks (sessionStart/obs/stop); false denials if you intentionally run Fast parent with workers. | recommend **on** |
+| 9 | Shell stall detection | `shell.stallDetection` | off | Blocks repeating the exact same shell command too many times. | Can false-positive on intentional retries. | `stallRepeatThreshold (default 3)` |
+| 10 | Catastrophic shell ask | `shell.catastrophicAsk` | **on** | Asks before destructive shell commands (rm -rf, drop db, force push, …). | Extra prompts on risky commands. | recommend **on** |
+| 11 | Lessons | `intelligence.lessons.enabled` | off | Records compact lessons on gate stagnation and reinjects them ranked under a char budget. A lesson can name the path or symbol that makes it true and is withheld once that stops resolving, can carry an end date, and is graded helped or neutral by the next run of the gate it was injected for. Three tiers: shipped core, a global tier read by every product on this machine, and this project's own. How the lessons reach the model is decided by the provider rather than configured: where a host does not deliver context returned from its session-start hook, a durable rules file is written instead. | Uses context tokens; not a second brain / chat memory. The grading is correlational, not causal — a gate passing after a lesson was injected does not prove the lesson caused it. Nothing is promoted between products automatically, so carrying a lesson to another product is an operator command. On a host that needs the durable view, a file is written into the repo (`.cursor/rules/harness-lessons.mdc`) and asked to be included on every request; `syncRulesFile: never` declines it. | `maxInjectSession`, `maxCharsSession`, `maxInjectRetry`, `maxCharsRetry`, `promoteHitCount`, `decayLambda`, `projectBoost`, `syncRulesFile`, `gardenOnSessionEnd`; recommend **on** |
+| 12 | Budget continue | `intelligence.budgetContinue` | off | Pushes the agent to keep working under context pressure instead of wrapping up early. | Can delay clean stops. | `budgetContinueAfterLoops` |
+| 13 | Gap feedback | `intelligence.gapFeedback` | **on** | Injects PREVIOUS_GAPS on gate failure so retries fix listed items. | Longer follow-ups. | — |
+| 14 | Failure classification | `intelligence.failureClassification` | **on** | Stores failure categories on the handoff for clearer next actions. | Extra handoff fields. | — |
+| 15 | Progressive handoff | `intelligence.progressiveHandoff` | **on** | Carries the gaps the previous session ended with into the next session's bootstrap, as history rather than as a task list. | Spends session-start context on a verdict that may already be stale — only the next run of the gate says whether it still holds. Capped at five, and the rest are counted rather than dropped in silence. | — |
+| 16 | Progressive context | `intelligence.progressiveContext` | **on** | Escalates gate follow-up detail on each stop retry. | Longer thrash follow-ups. | — |
+| 17 | Autopilot | `intelligence.autopilot` | **on** | Adds ordered AUTOPILOT steps on gate failure. | Agent must follow the block; more directive follow-ups. | — |
+| 18 | Idle-turn gate (asked instead of acting) | `intelligence.idleTurnGate` | off | Blocks a turn that ends with open work, zero tool calls and zero file changes. Counts recorded tool events rather than reading the reply, so it cannot be talked around. | A turn that legitimately only answers a question is blocked while handoff work is open — clear the handoff or turn this off for conversational repos. | — |
+| 19 | Docs staleness gate | `docs.command` | off | Runs the repository's own documentation staleness tool on stop, so a stale document fails like a failing test. | Needs such a tool in the repository; without one there is nothing to run. | `command (exact argv array)`, `severity: warn \| deny` |
+| 20 | Global observability spool | `obs.globalSpool` | off | Mirrors this repo's obs and audit records into one file under the runtime home, so cost and gate history can be read across every repository at once. | Writes outside the repository. Records carry the repo path and project name, and the spool is pruned on the same retention window as session rollups. | — |
+| 21 | Untrusted-content framing and enforcement | `untrustedContent.enabled` | off | Injects one framing line per turn when the agent reads a pull request, an issue, a fetched page or an MCP result, stating that the content is data and that any directive inside it is to be reported as a prompt-injection attempt, not obeyed. | Two modes. frame injects one line per turn, costing a few hundred characters and enforcing nothing. enforce also remembers what an untrusted read returned, bounded at 64 KB per session, and asks before a shell command that appears verbatim in it — verbatim because a paraphrase cannot be shown to come from the content, so a rewritten command is missed. It needs the host to deliver tool output on the after-event: measured present on Claude Code's PostToolUse and on Cursor's afterShellExecution and afterMCPExecution, and absent on Cursor's generic postToolUse. | `mode: frame \| enforce` |
+| 22 | Plan gate (declared scope vs diff) | `planGate.enabled` | off | Blocks the stop when the turn changed files the declared HARNESS_PLAN did not name, so scope creep fails like a failing test instead of surviving as a review comment. | Requires the agent to declare HARNESS_PLAN before editing, and each honest deviation to state a reason. A turn with no declaration is not gated at all. | `windowMinutes` |
+| 23 | Observation mode (measure a rail with its rule off) | `observe.enabled` | off | Runs a rail's checker while that rail is not enforcing, so the record says whether the property held with the rule injected or without it. That is the reading that tells you a rail is unnecessary rather than merely quiet, and it is what makes deleting one a decision instead of a guess. | Costs one diff scan per turn per observed rail, and answers a question only an operator who is asking it needs answered. It never blocks and never changes a decision, so it buys information and nothing else. | `rails — the rails to observe, chosen from the observable set (today: comments). A name with no checker records nothing and doctor reports it` |
+
+<!-- /generated -->
+
+Stagnation fingerprinting is always on when grind gates fail (no separate toggle) — mention when discussing
+grind.
+
+## Lessons subsection (capability 9)
+
+If the user enables lessons, explain what runs automatically:
+
+| Event | What happens |
+|-------|--------------|
+| Gate stagnation (same fingerprint ≥ 2) | Upsert `candidate` lesson in `.tlc/harness/state/lessons.json`, recording the session key |
+| Stop retry / sessionStart | Inject ranked lessons under char budget, skipping any that are stale or out of window |
+| Next run of the same gate | Grade the lessons injected for it: passed → `helped`, failed → `neutral` |
+| sessionEnd | Promote / decay / quarantine when `gardenOnSessionEnd`, mark or clear staleness, prune expired |
+| `syncRulesFile` | Rewrite the provider-native durable view — Cursor's `.cursor/rules/harness-lessons.mdc`, Claude's `CLAUDE.md` import line. `auto` writes it where the provider does not deliver context returned from its session-start hook, which today is Cursor |
+
+Ask for lessons knobs (offer defaults):
+
+- `maxInjectSession` (5), `maxCharsSession` (900)
+- `maxInjectRetry` (8), `maxCharsRetry` (1400)
+- `promoteHitCount` (2) — counted in **distinct sessions**, not raw recurrences
+- `decayLambda` (0.02), `projectBoost` (1.5) — the boost favours this project over the global tier
+- `syncRulesFile` (recommend **auto**, the default — the provider decides. Cursor drops `additional_context`
+  returned from `sessionStart`, acknowledged by Cursor as a race with the composer handle, so `auto` writes the
+  rules file there and not on Claude Code. Use `never` if the user does not want a file in `.cursor/rules/`, and
+  `always` on Claude Code to keep a `CLAUDE.md` pointer that survives a restart)
+- `gardenOnSessionEnd` (recommend true)
+
+**Nothing to configure for the tiers.** The global tier lives at `<runtime home>/state/lessons.json` and is read
+automatically; it is written only when the operator passes `--global` or runs `lessons promote`. There is no
+setting that makes promotion automatic, and that is deliberate — a lesson mined from one product's gate names that
+product's tooling ([/decisions/ad-040.md](/decisions/ad-040.md)).
+
+If the user asks how to record something they just learned, the commands are:
+
+```bash
+tlc harness lessons add "<what to do differently>" [--gate <name>] [--ref path[:symbol]] [--until <iso>] [--global]
+tlc harness lessons promote <id>
+tlc harness lessons list
+```
+
+Mention `--ref` when the lesson is about a file or a symbol: it is what makes the lesson retire itself instead of
+outliving what it was about. Mention `--global` when the lesson would be true in a different repository.
+
+Point deep docs to: `tlc harness help lessons` (load only if the user asks how decay/ranking works).
+
+## Not configurable — state this once, before discovery
+
+A floor tier runs ahead of every setting and reads no configuration, so nothing below can switch it off.
+Tell the user plainly, because the first denial otherwise looks like a bug:
+
+| Rule | Denies |
+|------|--------|
+| `outside-project-destruction` | A destructive command whose target resolves outside the project and outside the OS temp directory |
+| `unprovable-destruction` | A destructive verb whose target cannot be resolved — a variable, a substitution, or a command built at runtime |
+| `secret-access` | Reading a credential path into the transcript: `.env`, `~/.ssh`, `~/.aws`, `*.pem`, and similar. `.env.example` and friends are not secrets |
+| `history-rewrite` | `git push --force`. `--force-with-lease` is allowed, since it refuses when the remote moved |
+| `machine-control` | `shutdown`, `reboot`, `halt`, `poweroff` |
+
+Harness policy and state are not agent-writable either: a gate an agent can edit is not a gate.
+
+## Runtime note (tell user once)
+
+Hooks call `~/.tlc/harness/bin/tlc-exec` — Bun-first when Bun is on PATH (~1 ms/hook), Node 24+ + `dist/`
+otherwise (~27 ms/hook; see Step 1b). After global code changes: `tlc harness build`. Day-to-day use does
+**not** require Bun. Install path is only `~/.tlc/harness` — never `~/.cursor/harness` or
+`~/.cursor/agent-harness`.

package/src/contracts/capabilities.ts

@@ -0,0 +1,30 @@
+import type { HarnessEventKind } from "./harness-event.ts";
+
+export type ProviderCapabilities = {
+  enforcesHooks: boolean;
+  askSupportedOn: HarnessEventKind[];
+  sessionEnv: boolean;
+  nativeLoopCounter: boolean;
+  dedicatedShellEvent: boolean;
+  toolInputRewrite: boolean;
+  toolOutputRewrite: boolean;
+  contextAtToolBefore: boolean;
+  contextAtToolAfter: boolean;
+  contextAtStop: boolean;
+  /**
+   * Whether context returned from the session-start hook reaches the model. A host can accept the field, log it as
+   * merged, and still drop it, so this is not the same question as whether the field exists. A host declaring false
+   * needs the durable provider view to carry lessons; the adapter that declares it cites the evidence
+   * ([/decisions/ad-050.md](/decisions/ad-050.md)).
+   */
+  sessionStartContextReliable: boolean;
+  /**
+   * Whether an after-event delivers what the tool returned. Measured as per-event rather than per-host: one host
+   * supplies it on its shell and MCP after-events and not on its generic tool after-event, so a rail that needs
+   * it asks the capability and then still checks the field ([/decisions/ad-077.md](/decisions/ad-077.md)).
+   */
+  toolOutputAtAfter: boolean;
+  usageInPayload: boolean;
+  effortSignal: boolean;
+  thoughtEvent: boolean;
+};

package/src/contracts/decision.ts

@@ -0,0 +1,21 @@
+/**
+ * why: `rule` is the machine-readable form of a thing the codebase already wanted — the floor hand-writes
+ * `rule=policy-surface-write` into its reason prose, and anything wanting to attribute a decision had to parse
+ * English. Optional, because a decision is valid without one; a consumer that wants attribution and finds none
+ * reports it as unattributed rather than guessing.
+ */
+export type Decision =
+  | { kind: "abstain" }
+  | { kind: "allow" }
+  | { kind: "deny"; reason: string; userNote?: string; rule: string }
+  | { kind: "ask"; reason: string; userNote?: string; rule: string }
+  | { kind: "context"; text: string; env?: Record<string, string> }
+  | { kind: "continue"; text: string }
+  | { kind: "rewriteInput"; input: Record<string, unknown>; reason: string };
+
+export type Rendered = {
+  // invariant: null means write nothing; a provider whose abstain is a literal "{}" sets it explicitly.
+  stdout: string | null;
+  // invariant: always 0 — exit code is never used as a policy channel.
+  exitCode: number;
+};

package/src/contracts/effort.ts

@@ -0,0 +1,15 @@
+// why: never an enum — erasableSyntaxOnly forbids it.
+export const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"] as const;
+export type EffortLevel = (typeof EFFORT_LEVELS)[number];
+
+export function effortOrdinal(level: EffortLevel): number {
+  return EFFORT_LEVELS.indexOf(level);
+}
+
+export function compareEffort(a: EffortLevel, b: EffortLevel): number {
+  return effortOrdinal(a) - effortOrdinal(b);
+}
+
+export function isEffortLevel(value: unknown): value is EffortLevel {
+  return typeof value === "string" && (EFFORT_LEVELS as readonly string[]).includes(value);
+}

package/src/contracts/harness-event.ts

@@ -0,0 +1,87 @@
+import type { EffortLevel } from "./effort.ts";
+
+export type HarnessEventKind =
+  | "session.start"
+  | "session.end"
+  | "prompt.submit"
+  | "tool.before"
+  | "tool.after"
+  | "tool.failure"
+  | "shell.before"
+  | "shell.after"
+  | "mcp.before"
+  | "mcp.after"
+  | "read.before"
+  | "edit.after"
+  | "subagent.start"
+  | "subagent.stop"
+  | "stop"
+  | "compact.before"
+  | "response.after"
+  | "thought.after";
+
+export const HARNESS_EVENT_KINDS: readonly HarnessEventKind[] = [
+  "session.start",
+  "session.end",
+  "prompt.submit",
+  "tool.before",
+  "tool.after",
+  "tool.failure",
+  "shell.before",
+  "shell.after",
+  "mcp.before",
+  "mcp.after",
+  "read.before",
+  "edit.after",
+  "subagent.start",
+  "subagent.stop",
+  "stop",
+  "compact.before",
+  "response.after",
+  "thought.after",
+];
+
+export type HarnessUsage = {
+  inputTokens?: number;
+  outputTokens?: number;
+  cachedInputTokens?: number;
+};
+
+export type HarnessEvent = {
+  provider: string;
+  event: HarnessEventKind;
+  sessionKey: string;
+  projectDir: string;
+  // hazard: the `spawn*` pair describes the child of a spawn; the unprefixed fields describe the
+  // running agent. Conflating them clobbers sticky parent state.
+  model?: string;
+  spawnModel?: string;
+  effort?: EffortLevel;
+  text?: string;
+  toolName?: string;
+  toolInput?: Record<string, unknown>;
+  command?: string;
+  filePath?: string;
+  subagentType?: string;
+  spawnSubagentType?: string;
+  status?: "completed" | "aborted" | "error";
+  loopCount?: number;
+  /** Provider's own permission posture, when it exposes one. Absent means unknown, not permissive. */
+  permissionMode?: string;
+  contextUsagePercent?: number;
+  transcriptPath?: string;
+  usage?: HarnessUsage;
+  /**
+   * What the tool returned, when the host delivers it.
+   *
+   * why: measured across 69,034 real records before this existed. Every host that delivers it uses its own field
+   * name and its own type — three names and two types across the two adapters — so the translation belongs to
+   * each adapter and this is the one shape core reads ([/decisions/ad-077.md](/decisions/ad-077.md)).
+   *
+   * invariant: absent is absent. Two of the after-events measured carry nothing on 21,167 records, so a reader
+   * that assumed presence would be blind on the majority of one host's traffic.
+   */
+  toolOutput?: string;
+  /** Adapter-only escape hatch — core must not read this. */
+  raw: Record<string, unknown>;
+};

package/src/contracts/index.ts

@@ -0,0 +1,6 @@
+export * from "./capabilities.ts";
+export * from "./decision.ts";
+export * from "./effort.ts";
+export * from "./harness-event.ts";
+export * from "./policy-defaults.ts";
+export * from "./wiring.ts";

package/src/contracts/policy-defaults.ts

@@ -0,0 +1,14 @@
+import type { EffortLevel } from "./effort.ts";
+
+/**
+ * hazard: this carried `allowedModels`, and an empty project list fell back to it — so a spawn could be refused by
+ * a list the operator never wrote, which had already gone stale. `blockedPatterns` stays because it is the opposite
+ * mechanism: it is concatenated with the project's rather than replacing it, and what it carries is the `-fast`
+ * denial the rail exists for ([/decisions/ad-053.md](/decisions/ad-053.md)).
+ */
+export type ProviderPolicyDefaults = {
+  blockedPatterns: string[];
+  minEffort: EffortLevel | null;
+  /** Tool names whose results carry content from outside the repository. */
+  untrustedTools: string[];
+};

package/src/contracts/wiring.ts

@@ -0,0 +1,20 @@
+export type RuntimePaths = {
+  launcherPath: string;
+};
+
+export type WiringEntry = {
+  hookEvent: string;
+  handler: string;
+  command: string;
+  args: string[];
+  timeoutSeconds: number;
+  failClosed?: boolean;
+  matcher?: string;
+  loopLimit?: number;
+};
+
+export type ProviderWiring = {
+  target: string;
+  strategy: "replace" | "merge";
+  entries: WiringEntry[];
+};