@tech-leads-club/harness-toolkit 0.2.1

package/docs/diagnose.md

@@ -0,0 +1,248 @@
+---
+type: Runbook
+title: "Diagnose"
+description: "Checklist for hooks not firing, Node vs Bun runtime confusion, stale runtime, subagent denials, cost showing null, and double hooks — for both Cursor and Claude Code."
+tags: [runbook, diagnose, troubleshooting]
+timestamp: "2026-07-29"
+---
+
+# Diagnose
+
+Run `tlc harness doctor` first. Then walk this checklist.
+
+## Hooks not firing
+
+**Cursor**
+
+1. Confirm the Cursor config directory's `hooks.json` invokes `node …/tlc-exec.mjs <handler>` (installers
+   write this). `tlc harness doctor` prints the resolved path; `CURSOR_CONFIG_DIR` overrides the default.
+2. `dist/*.mjs` must exist (`tlc harness build`).
+3. Reload Cursor after editing hooks.
+4. Open **View → Output → Hooks** for exit errors.
+5. Project shim should call `tlc-exec shim <handler>`; with the global `sessionStart` hook set,
+   `TLC_ACTIVE=1` makes the shim no-op (expected).
+
+**Claude Code**
+
+1. Confirm the Claude config directory's `settings.json` (resolved, `CLAUDE_CONFIG_DIR` overrides the
+   default) has a `hooks` block with entries whose `command` is `node` and whose
+   `args` start with the launcher path (see [/providers/claude-code.md](/providers/claude-code.md)).
+2. `dist/*.mjs` must exist (`tlc harness build`).
+3. Restart the Claude Code session after editing `settings.json`.
+4. Project shim should call `tlc-exec shim <handler>`.
+
+On Windows, Cursor hooks use `cmd /c node "…\tlc-exec.mjs" …`; Claude Code hooks stay exec-form
+(`node …`) on every platform.
+
+## Node vs Bun
+
+- Preferred: **Bun** on PATH — every hook runs the TypeScript source directly, ~1 ms per invocation.
+- Guaranteed fallback: **Node 24+** + `tlc harness build` (`dist/*.mjs`), ~27 ms per invocation.
+- `tlc harness doctor` reports the resolved runtime as `OK` (Bun found) or `WARN` (Node fallback, with the
+  measured cost of the gap and the one-line fix). See [/decisions/ad-012.md](/decisions/ad-012.md).
+- Missing dist with Node present: run `tlc harness build` (needs Bun or esbuild once to compile).
+
+## `update` aborts on `dist/` and keeps aborting
+
+The one manual step, once, on every platform:
+
+```bash
+npm i -g @tech-leads-club/harness-toolkit@latest
+tlc harness install
+```
+
+**Why it has to be that and not `update`.** `update` runs from the installed runtime, and the fix for `update` is in
+the revision `update` has to fetch — so a stuck install cannot deliver its own fix. The registry serves the package
+independently of what is installed, which makes it the only route that does not depend on the thing that is stuck
+([/decisions/ad-048.md](/decisions/ad-048.md)).
+
+Installing over a managed checkout moves it to `origin/main` with a hard reset. `config.json` and `state/` are gitignored,
+so your policy, global lessons and obs history survive it. A **linked** runtime — a symlink to your own clone — is
+left completely alone.
+
+There is no `--force`: a managed runtime is already reset, and a linked clone is never written to.
+
+## Stale runtime / need latest main
+
+```bash
+tlc harness update
+```
+
+Then reload/restart the provider session.
+
+**What update may write depends on what the runtime path is.** `tlc harness doctor` prints it as
+`runtime ownership` ([/decisions/ad-046.md](/decisions/ad-046.md)):
+
+| Kind | What update does |
+| --- | --- |
+| `managed checkout` | fetches and moves it to upstream with a hard reset — the harness owns its contents, so a local change there is never yours |
+| `link to a working clone` | **nothing** in the clone. Refreshes only the CLI link, the skill link and provider hooks. Pull that clone yourself |
+| `installed from npm` | bumps the package to `@latest` and re-materialises the runtime. No git command runs against it |
+| `not a git checkout` | nothing to pull — install the package and run `tlc harness install` |
+
+Update never rebuilds `dist/` when every bundle is present. It used to, and because Bun and esbuild emit different
+bytes for the same source, the rebuild left the checkout permanently dirty and every later update failed. If you see
+`update: dist/ complete — no rebuild`, that is the fix working.
+
+After update, `tlc harness doctor` reports non-blocking `WARN:` lines for off/missing opt-ins (and for
+default-on features you explicitly set to `false`). They do not fail doctor by themselves. A missing
+`.tlc/harness/config.json` still fails the project-policy check until you init.
+
+## `tlc: command not found`
+
+Re-run the platform installer, or ensure the CLI shim is on PATH:
+
+- Unix: `~/.local/bin/tlc` → `~/.tlc/harness/bin/tlc`
+- Windows: `%USERPROFILE%\.local\bin\tlc.cmd`
+
+## Obs empty / no signal
+
+1. `observability.enabled` must not be `false` in config.
+2. Happy-path tool/shell events are **debug** — enable `debugEnabled` or look for signal kinds only.
+3. Confirm `.tlc/harness/state/` is writable in the project.
+4. `tlc harness obs live` after a prompt submit / stop / denial.
+
+## The floor blocked a command that only reads harness state
+
+Reading is ordinary work and the bootstrap asks for it, so a refusal there means the *verb* could not be proven to
+only read — not that reading is forbidden. The refusal now says so and names the way through
+([/decisions/ad-047.md](/decisions/ad-047.md)):
+
+```bash
+tlc harness handoff          # handoff state, no shell needed
+tlc harness policy           # the resolved policy
+tlc harness handoff --json   # same, for a script
+```
+
+Proven readers on the policy surface: `cat`, `head`, `tail`, `less`, `more`, `grep`, `rg`, `jq`, `ls`, `stat`,
+`file`, `wc`, `cmp`, `diff`, `od`, `xxd`, `strings`, `md5sum`, `sha256sum`, `echo`, `printf`, `test`, `[`, and
+`git show|diff|log|status|ls-files|cat-file|blame`.
+
+`awk` and `sort` are **not** readers, on purpose — `awk '{print > f}'` and `sort -o f` write a file the head verb
+never reveals. A redirect onto the surface is denied whatever the verb, so `test -f x > config.json` still fails.
+
+## The gate runs on a turn that changed nothing
+
+It does not any more, and this is how to confirm it. A verdict is keyed on a content hash of the gate command and
+the files it ran against; a match reuses the verdict without executing the command
+([/decisions/ad-045.md](/decisions/ad-045.md)).
+
+```bash
+tlc harness obs report      # the Gate time table has a Reused column
+```
+
+| Reading | Meaning |
+| --- | --- |
+| `Runs` climbing on every turn | the inputs really are changing, or the hash is incomplete |
+| `Reused` climbing | the verdict stood and the command did not run |
+| both zero | the gate never ran; check `grind.enabled` and `codePaths` |
+
+The hash is **incomplete** — so the gate always runs — when an input cannot be read, which includes a tracked file
+that was deleted, or when the changed set exceeds 400 files or 12 MB. A gate that depends on something outside the
+changed files (a database, a service, an environment variable) can also reuse a verdict that no longer holds.
+
+## A lesson is not reaching the turn
+
+`tlc harness lessons list` answers it directly — a lesson that is being withheld is marked `WITHHELD` and the
+notes on its line say why.
+
+| Note | Meaning | What to do |
+| --- | --- | --- |
+| `stale=path-missing` / `symbol-missing` | a `--ref` no longer resolves | restore or rename the ref, then `tlc harness lessons garden` |
+| `validity=expired` | past its `--until` | the next garden prunes it; write a new one |
+| `validity=pending` | its window has not opened | wait, or rewrite without `--from` |
+| `validity=invalid` | an unparseable bound, so it fails closed | rewrite with an ISO date |
+| `WITHHELD` with no note | a **global** lesson whose refs do not resolve in this repository | expected — it applies where it came from |
+
+Nothing withheld and still absent? Then it lost on rank or budget, not on health:
+
+1. `enabled=true` on the last line of `lessons list`.
+2. `status` must be `active` for session injection; a `candidate` only shows on a matching retry.
+3. **The budget usually binds.** `maxCharsSession` defaults to 900 and fits about two blocks while
+   `maxInjectSession` says five. The injected block names what it dropped; raising `maxCharsSession` is the fix.
+4. **A rule you consider non-negotiable should be pinned, not ranked** — `lessons add … --pin` puts it ahead of
+   every scored lesson ([/decisions/ad-043.md](/decisions/ad-043.md)).
+
+`tlc harness doctor` carries the same facts as one row (`lesson health`), and warns separately about stale,
+out-of-window and unproven lessons. See [/lessons.md](/lessons.md).
+
+## Two agents in one checkout, and the grind
+
+A turn no longer blocks because a neighbour session is mid-gate. It resolves in this order
+([/decisions/ad-073.md](/decisions/ad-073.md)):
+
+1. **A recorded verdict whose inputs hash matches is reused**, and the lock is never taken. Two sessions editing
+   one tree usually land here, because the hash covers the command and the files rather than the session.
+2. **Otherwise the turn waits**, up to ten seconds — bounded so the wait plus the gate still fit inside the
+   `Stop` hook's 120-second timeout.
+3. **If the wait expires the gate defers.** The turn ends, the handoff records `last_gate_result: skipped` naming
+   the holder, and a `gate.outcome` carrying `deferred_to` reaches the record, so `tlc harness why` shows it.
+
+Deferring is safe because both sessions share the tree: the neighbour's commands cover this turn's edits too. If
+they pass, this turn was legitimate. If they fail, the neighbour is blocked holding the failure and the tree is
+still broken, so the next stop in either session blocks on it. What is given up is only *which* turn is told.
+
+A dead or stale holder never causes even the wait: the runtime reclaims past `GATE_LOCK_STALE_MS` (30 minutes) by
+age, immediately when the pid is gone, and after a five-second grace window when the body cannot be read or names
+no holder — a truncated write, a zero-length file, or JSON without `provider` / `session` / `pid`. Deleting the
+file by hand is never necessary.
+
+**An agent cannot switch the grind off from inside a session**, and that is correct: those subcommands are policy
+surface ([/decisions/ad-022.md](/decisions/ad-022.md)). Run them from your own terminal.
+
+## `status` disagrees with what a hook does
+
+It no longer can: `status` reads `loadPolicy`, the same resolution a hook performs, and prints where the mode
+came from — `[from config]`, `[from file]` or `[from flag]`. If the origin is `flag` or `file` and you expected
+`config`, a leftover `tlc harness mode` or `grind on` is winning; clear it with `tlc harness mode solo` or
+`tlc harness grind off`.
+
+## A shim hook points at a path that does not exist
+
+`tlc harness init` writes the install path (`~/.tlc/harness/bin/tlc-exec.mjs`), not the checkout behind its
+symlink. A shim naming a checkout directory was written by an older runtime — re-run `tlc harness init` to
+regenerate it. These files stay untracked on purpose: they carry an absolute path that is only valid on the
+machine that generated them.
+
+## Doctor says a provider is "detected but not wired" while hooks fire
+
+The launcher path is compared by the file it resolves to, not by the string. If this warning appears while
+hooks demonstrably run, check that the path recorded in the provider's config still exists — a moved or
+deleted checkout is a real break, whereas reaching the same file through a symlink is not and no longer
+warns.
+
+## Grind not looping
+
+1. `tlc harness status` — grind must be ON.
+2. Gates must not be PAUSED.
+3. Project `.tlc/harness/config.json` needs `grind.lintCommand` / `grind.testCommand` if you expect those
+   gates.
+4. On failure, inspect `.tlc/harness/state/last-gate.json` (`findings`, `exitCode`, `outputTail`) before
+   trusting chat follow-up text.
+5. Concurrent agents: wait for `.tlc/harness/state/grind.lock` or stop the other grind.
+6. Stop status must be `completed` (aborted/error skips).
+
+## Subagent model denied
+
+Allowlist + blocked `*-fast`-shaped patterns (provider-specific — see
+[/providers/index.md](/providers/index.md)). Check `subagents.allowedModels` in user config and project
+`.tlc/harness/config.json`. Dual gate: `subagentStart` + `preToolUse` on a spawn tool. Optional
+`subagents.blockParentFast` denies spawns while sticky parent state is Fast
+(`.tlc/harness/state/parent-model.json`, see [/decisions/ad-001.md](/decisions/ad-001.md)).
+
+## Cost always null
+
+1. `tlc harness help prices`.
+2. `tlc harness prices refresh` (or `refresh cursor` if you only need the primary catalog).
+3. `tlc harness prices lookup <model> [provider]` — if null, the id is missing from that provider's
+   catalog + LiteLLM.
+4. Add an alias in `~/.tlc/harness/model-aliases.json` if the provider's model slug ≠ catalog key.
+5. Optional override in `model-prices.json` (local).
+6. Events need input/output token counts; duration-only events yield null USD even when the catalog has the
+   model.
+
+## Double hooks / slow turns
+
+If both user and project hooks run the same heavy logic without shim no-op, fix shim / `TLC_ACTIVE`. Global
+observability hooks should stay in the user-level hook file only (the resolved provider config
+directory's `hooks.json` or `settings.json`), not duplicated into the project shim.

package/docs/index.md

@@ -0,0 +1,52 @@
+---
+okf_version: "0.1"
+title: "agent-harness documentation bundle"
+description: "OKF v0.1 documentation bundle for the tlc harness — architecture, concepts, runbooks, provider adapters, and the full architectural decision log."
+tags: [index, okf]
+timestamp: "2026-07-29"
+---
+
+# agent-harness docs
+
+This is an [Open Knowledge Format v0.1](/decisions/ad-013.md) bundle: every non-reserved document below
+carries YAML frontmatter with a `type` from the closed vocabulary `Concept | Runbook | Provider | Decision
+| Capability | Aggregate`, plus `title`, `description`, `tags`, and `timestamp`. Cross-links are absolute
+and bundle-relative (e.g. `/decisions/ad-010.md`), never relative.
+
+See [/log.md](/log.md) for every decision in date order, and [/decisions/index.md](/decisions/index.md) for
+the same records by number. Both are rendered from `docs/decisions/`, so neither can drift from it.
+
+## Concepts
+
+| Doc | Description |
+| --- | --- |
+| [/architecture.md](/architecture.md) | Ports-and-adapters shape of the harness: contracts, core, providers, entrypoints, and how the tlc CLI and runtime home fit together. |
+| [/concepts.md](/concepts.md) | The operator-facing concepts behind the harness: grind, pause/resume, shipGate, subagent allowlist, comment policy, duplication, catastrophic shell, shell stall, the intelligence rails, observability planes, and cost estimates. |
+| [/coverage.md](/coverage.md) | A self-assessment against a published agentic-risk taxonomy: which of the harness's own rules answer each risk, and what each one still leaves open. Control names are generated from the catalogs and checked by the gate. |
+| [/lessons.md](/lessons.md) | 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. |
+
+## Runbooks
+
+| Doc | Description |
+| --- | --- |
+| [/init.md](/init.md) | What tlc harness init creates, what it deliberately does not do, and the mandatory harness-init wizard's capability menu — including the Bun-vs-Node hook runtime question. |
+| [/troubleshooting.md](/troubleshooting.md) | How to tell a harness decision from model behaviour, in the moment and after the fact: the one command that answers it, what each rule name means, and the four symptoms that are not the harness at all. |
+| [/diagnose.md](/diagnose.md) | Checklist for hooks not firing, Node vs Bun runtime confusion, stale runtime, subagent denials, cost showing null, and double hooks — for both Cursor and Claude Code. |
+| [/measure.md](/measure.md) | 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. |
+
+## Providers
+
+| Doc | Description |
+| --- | --- |
+| [/providers/index.md](/providers/index.md) | Index of the provider adapters — Cursor and Claude Code — and the port they both implement. |
+| [/providers/cursor.md](/providers/cursor.md) | The Cursor adapter — capability descriptor, event mapping, and wiring target for Cursor's hooks.json. |
+| [/providers/claude-code.md](/providers/claude-code.md) | The Claude Code adapter — capability descriptor, event mapping, and wiring target for the settings.json hooks block in Claude Code's resolved config directory. |
+
+## Decisions
+
+| Doc | Description |
+| --- | --- |
+| [/decisions/index.md](/decisions/index.md) | Index of every architectural decision (AD-001…AD-016) made while building the multi-provider harness. |
+
+Each individual decision (`/decisions/ad-001.md` … `/decisions/ad-016.md`) is listed with its own
+description in [/decisions/index.md](/decisions/index.md).

package/docs/init.md

@@ -0,0 +1,101 @@
+---
+type: Runbook
+title: "Init (project bootstrap)"
+description: "What tlc harness init creates, what it deliberately does not do, and the mandatory harness-init wizard's capability menu — including the Bun-vs-Node hook runtime question."
+tags: [runbook, init, wizard]
+timestamp: "2026-07-29"
+---
+
+# Init (project bootstrap)
+
+## What init creates (project-agnostic)
+
+| File | Purpose |
+|------|---------|
+| `.tlc/harness/config.json` | Policy for this repo only |
+| `.cursor/hooks.json` | Cursor shim to the global runtime — only written when `~/.cursor` is detected |
+| `.claude/settings.json` (`hooks` block, merged) | Claude Code shim — only written when `~/.claude` is detected |
+| `.gitignore` entries | `.tlc/harness/state/` |
+
+`tlc harness init` detects which providers are installed (presence of `~/.cursor`, `~/.claude`) and wires
+only those — it never assumes Cursor. See `tools/init-project.ts` and
+[/providers/index.md](/providers/index.md).
+
+## What init does NOT do
+
+- Does not install the global runtime (assumes `~/.tlc/harness` already present)
+- Does not assume Biome, Vitest, npm, or any stack
+- Does not enable grind/shipGate/etc. unless the user opts in during discovery
+
+## Wizard rule
+
+The **harness-init skill is mandatory** for project setup. **Each capability is optional** — the wizard
+must present benefit / trade-off / default and ask before enabling.
+
+## Step 1b: hook runtime (ask once, never block)
+
+Before the capability menu, the wizard checks whether **Bun** is on `PATH` and presents the measured
+trade-off from [/decisions/ad-012.md](/decisions/ad-012.md):
+
+```
+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), never ask twice (the answer is recorded in project state so
+later runs skip this step; `doctor` keeps reporting it as a non-failing `WARN`), always give the exact
+numbers, and re-probe if the user installs Bun mid-wizard rather than trusting the earlier check.
+
+## Capability menu (for the skill wizard)
+
+| Capability | Keys | Default | Benefit | Trade-off |
+|------------|------|---------|---------|-----------|
+| format | `format.*` | off | Consistent style on Write | Needs a correct format command |
+| grind | `grind.*` | off | Lint/test follow-ups on stop | Turn cost; flaky commands thrash |
+| shipGate | `shipGate.*` + `HARNESS_SHIP_CLAIM` | off | Honest ship after protocol claim | Needs evidence workflow; free English ignored |
+| emptyDiffAntiShip | `shipGate.emptyDiffAntiShip` | off | No claim on empty tree | Annoys when zero-diff is correct |
+| comments | `comments.*` | off | Junk-comment follow-ups | Noise on dirty trees |
+| subagents | `subagents.*` | off | Model allowlist / require model | Maintain the list |
+| blockParentFast | `subagents.blockParentFast` | off | Deny Task/subagent while parent is Fast | Needs sticky parent hooks; blocks intentional Fast parent |
+| catastrophic shell | `shell.catastrophicAsk` | on | Ask before destructive shell | Extra prompts |
+| shell stall | `shell.stallDetection` | off | Block repeated identical commands | False positives on retries |
+| gap feedback | `intelligence.gapFeedback` | on | Structured PREVIOUS_GAPS | Longer follow-ups |
+| failure classification | `intelligence.failureClassification` | on | Failure categories in handoff | Extra fields |
+| progressive handoff | `intelligence.progressiveHandoff` | on | Gaps injected on next session | Slightly longer bootstrap |
+| progressive context | `intelligence.progressiveContext` | on | Escalates context on each stop retry | Longer follow-ups on thrash |
+| autopilot | `intelligence.autopilot` | on | Runtime decides ordered next steps | Agent must follow AUTOPILOT block |
+| lessons | `intelligence.lessons.*` | off | Durable ranked lessons + decay | Uses context; enable when you want cross-session memory of gate fails |
+| budget continue | `intelligence.budgetContinue` | off | Keep working under pressure if unfinished | Can delay clean stops |
+| observability | usually global | signal on | Measure/diagnose | Disk under `.tlc/harness/state/` |
+| mcpPrime / bootstrapExtra | arrays | empty | Project rails at sessionStart | Context cost |
+
+Stagnation fingerprinting is built into grind gate fails (no separate toggle).
+
+## CLI flags
+
+```bash
+tlc harness init --dry-run
+tlc harness init --write [--stdin-json] [--force]
+tlc harness init --minimal
+```
+
+`--minimal` writes a safe, provider-agnostic stub (grind/ship off) plus whichever provider shims are
+detected. Prefer the harness-init skill for full discovery.
+
+## After write
+
+```bash
+tlc harness status
+tlc harness doctor
+```
+
+Next agent turn should set `TLC_ACTIVE` via the global `sessionStart` hook. Use `tlc harness help` for
+concepts.
+
+## Slash / global commands
+
+Keep provider-native slash commands (e.g. Cursor's `~/.cursor/commands/`) global. Init must not create
+`<repo>/.cursor/commands/` or an equivalent project-local commands directory for harness toggles or help.