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

package/docs/decisions/ad-012.md

@@ -1,71 +0,0 @@
----
-type: Decision
-title: "AD-012 — Prefer Bun at runtime, keep dist/ for the Node fallback, ship no binary"
-description: "tlc-exec tries Bun first, falling back to Node + dist/*.mjs; dist/ stays tracked since the installer is a git clone with no build step, and no compiled single-file binary ships."
-tags: [decision, runtime, bun, performance]
-timestamp: "2026-07-29"
----
-
-# AD-012 — Prefer Bun at runtime, keep `dist/` for the Node fallback, ship no binary
-
-- **status**: active
-- **date**: 2026-07-29
-
-## Decision
-
-`tlc-exec` tries **Bun first** when it is on PATH, falling back to Node + `dist/*.mjs`. `dist/` stays
-tracked (the installer is `git clone` with no build step). No compiled single-file binary.
-
-## Measured
-
-Same handler, 30 warm invocations each, on the development machine:
-
-| Path | Per invocation |
-| --- | --- |
-| `bun run src/*.ts` | ~1 ms |
-| `bun run dist/*.mjs` | ~1 ms |
-| `node dist/*.mjs` | 27 ms |
-| `node src/*.ts` | 63 ms |
-
-## Why
-
-Hooks are inner-loop — they fire on every tool call, shell command, read, and stop. At ~30 fires per agent
-turn that is ~810 ms of pure process startup on Node versus ~30 ms on Bun. Output is byte-identical across
-runtimes — verified on `guard-shell` (`{"permission":"allow"}`).
-
-`dist/` still earns its keep only for the Node path, where it is 2.3× faster than stripping types at
-runtime (27 ms vs 63 ms). Under Bun it buys nothing, which is why it is a fallback artifact rather than the
-primary one.
-
-No compiled binary because a Bun-compiled executable is 50–100 MB per platform and this repo both installs
-by `git clone` and tracks its build output — four platform binaries in git history is untenable. The gain
-over `bun run` is also ~zero at this scale; the published latency case for binaries is against a *cold Node*
-baseline, which the Bun-first path already removes.
-
-Using the harness never requires Bun — Bun is the fast path, Node stays the guaranteed path.
-
-**Surface the fallback, never fall back silently.** A user on the 27× slower path must know they are on it
-and how to leave it. `tlc harness doctor` and `tlc harness status` both report the resolved runtime with the
-measured cost of the gap and the one-line fix (install Bun). Absent Bun is a `WARN`, not a `FAIL` — Node is
-supported, just slower.
-
-**Detection must not cost a spawn per hook.** `spawnSync(bun, ["--version"])` on every invocation would burn
-more than the 26 ms it saves. Resolve by testing for the executable on `PATH` without executing it, and
-cache the result in `state/` keyed by the resolved path; refresh on `doctor` / `status` / `update`.
-
-## Context
-
-Claude Code itself is TypeScript on Bun, shipped as a Bun-compiled binary; other CLI agent tools are
-TS/Node or have migrated to a compiled systems language. TS-on-Bun is the incumbent pattern for this exact
-problem domain.
-
-## Applies to
-
-- `bin/tlc-exec.mjs`
-- `bin/tlc-build`
-- [/architecture.md](/architecture.md)
-
-## See also
-
-- [/measure.md](/measure.md) — how `doctor`/`status` surface the resolved runtime
-- [/init.md](/init.md) — Step 1b of the init skill, which presents this trade-off to the user

package/docs/decisions/ad-013.md

@@ -1,87 +0,0 @@
----
-type: Decision
-title: "AD-013 — Documentation follows the Open Knowledge Format (OKF v0.1)"
-description: "docs/ becomes an OKF v0.1 bundle — markdown with YAML frontmatter, index.md and log.md as reserved files, absolute bundle-relative cross-links, and a closed type vocabulary."
-tags: [decision, docs, okf]
-timestamp: "2026-07-29"
----
-
-# AD-013 — Documentation follows the Open Knowledge Format (OKF v0.1)
-
-- **status**: active
-- **date**: 2026-07-29
-
-## Decision
-
-`docs/` becomes an OKF v0.1 bundle — markdown with YAML frontmatter, `index.md` and `log.md` as reserved
-files, absolute bundle-relative cross-links.
-
-## Layout
-
-```
-docs/
-├── index.md              okf_version: "0.1", entries from concept descriptions
-├── log.md                chronological, ISO 8601
-├── architecture.md       type: Concept
-├── concepts.md           type: Concept
-├── diagnose.md           type: Runbook
-├── init.md               type: Runbook
-├── lessons.md            type: Concept
-├── measure.md            type: Runbook
-├── providers/{index,cursor,claude-code}.md      type: Aggregate / Provider
-└── decisions/{index,ad-001…ad-016}.md           type: Aggregate / Decision
-```
-
-## `type` vocabulary
-
-Closed, small: `Concept`, `Runbook`, `Provider`, `Decision`, `Capability`, `Aggregate`. OKF has no central
-registry, so the constraint is ours to keep.
-
-## Frontmatter
-
-`type` is the only field the spec requires. This bundle also always sets `title`, `description`, `tags`,
-`timestamp`. Unknown keys must be preserved on round-trip; broken links are valid and mean unrealized
-knowledge.
-
-## Links
-
-Absolute (`/decisions/ad-010.md`), not relative — they survive a document moving between subdirectories.
-
-## Citations
-
-Any doc asserting something from an external source carries a numbered `# Citations` section, per the spec.
-
-## Why
-
-This repo is a harness *for coding agents*; its own documentation should be machine-consumable by the
-agents it steers. OKF is markdown with structured metadata, needs no SDK, no registry and no service, and
-the spec explicitly targets keeping knowledge beside the code so an agent reads both from one clone.
-
-## Why this also splits `STATE.md`
-
-`AD-001`…`AD-016` were sixteen-plus sections in one growing file. As OKF concepts — one decision per file,
-`type: Decision`, cross-linked — they become addressable: an agent asking "why does `contracts/` exist"
-resolves `/decisions/ad-010.md` directly instead of scanning one long document.
-
-## Note on the sibling repo
-
-Some projects use OKF for **runtime knowledge** (an agent's own `knowledge/` namespace), not for repo
-docs — its `docs/*.md` carry no frontmatter. Applying it to docs here is a different and additional use, not
-a copy of that setup.
-
-## Applies to
-
-- `docs/**`
-- `.specs/STATE.md` (split)
-- `tools/check-docs-bundle.ts`
-
-## See also
-
-- [/index.md](/index.md), [/log.md](/log.md)
-- [/decisions/index.md](/decisions/index.md)
-
-# Citations
-
-1. Open Knowledge Format annotated specification — https://okf.md/spec/
-2. GitBook, *What is OKF? Understanding Google's Open Knowledge Format* — https://www.gitbook.com/blog/what-is-okf-open-knowledge-format
-3. Reference implementation, `GoogleCloudPlatform/knowledge-catalog` (Apache 2.0)

package/docs/decisions/ad-014.md

@@ -1,56 +0,0 @@
----
-type: Decision
-title: "AD-014 — Claude Code hook payload field paths, pinned"
-description: "The design specified Claude's event names and capability booleans but never its JSON field paths; this decision pins them so a wrong field path cannot silently pass a green test suite."
-tags: [decision, claude, contracts, inbound]
-timestamp: "2026-07-29"
----
-
-# AD-014 — Claude Code hook payload field paths, pinned
-
-- **status**: active
-- **date**: 2026-07-29
-
-## Why this exists
-
-The design specified Claude's event *names* and capability *booleans* but never the JSON field paths.
-Cursor's adapter could be checked against captured goldens from the predecessor handlers; Claude has no
-such upstream, so a wrong field path produces a passing test suite and a silently broken adapter. This
-pins the field paths before later phases build on top.
-
-## Field paths
-
-| Field | Where | Source |
-| --- | --- | --- |
-| `session_id` | top level, all events | documented |
-| `hook_event_name` | top level, PascalCase | documented |
-| `cwd` | top level | documented |
-| `transcript_path` | top level | documented |
-| `permission_mode` | top level (`default\|plan\|acceptEdits\|auto\|dontAsk\|bypassPermissions`) | documented |
-| `effort.level` | top level object, `low\|medium\|high\|xhigh\|max` | documented |
-| `prompt_id` | top level, absent until first input | documented |
-| `agent_id`, `agent_type` | top level, subagent events only | documented |
-| `tool_name`, `tool_input`, `tool_use_id` | top level, tool events | documented |
-| `tool_input.command` | Bash | documented (official example) |
-| `tool_input.file_path` | Edit / Write / Read | **inferred** from the tool schema, not quoted in the hooks reference — verify against a real payload when one is available |
-| loop counter | **does not exist** on `Stop` | documented by absence; this is why Claude has no native loop counter (see [/providers/claude-code.md](/providers/claude-code.md)) |
-
-## Consequence
-
-`claude.inbound.ts` reads exactly these paths. Any future divergence is a payload change, not a design
-choice, and must be caught by re-reading the reference rather than by guessing.
-
-## Applies to
-
-- `src/providers/claude/claude.inbound.ts`
-- its fixtures
-- Claude entrypoints
-
-## See also
-
-- [/providers/claude-code.md](/providers/claude-code.md)
-
-# Citations
-
-1. Claude Code hooks reference (Anthropic documentation) — field paths pinned above were cross-checked
-   against the documented hook payload shape at the time this decision was recorded.

package/docs/decisions/ad-015.md

@@ -1,33 +0,0 @@
----
-type: Decision
-title: "AD-015 — Wiring handler names are the entrypoint filenames"
-description: "The handler name a provider's wiring registers is the src/entrypoints/<name>.ts filename, so both providers' wiring descriptors reference exactly the same eleven handler names."
-tags: [decision, entrypoints, providers, wiring]
-timestamp: "2026-07-29"
----
-
-# AD-015 — Wiring handler names are the entrypoint filenames
-
-- **status**: active
-- **date**: 2026-07-29
-
-## Decision
-
-The handler name a provider's wiring registers is the `src/entrypoints/<name>.ts` filename —
-`session-start`, `session-end`, `prompt-submit`, `tool-before`, `tool-after`, `tool-failure`,
-`subagent-start`, `subagent-stop`, `stop`, `compact-before`, `response-after`. Both providers' wiring
-descriptors already use these names.
-
-## Why
-
-Building the second provider adapter required picking a naming scheme with no spec anchor. Making the
-entrypoint filename the single source of truth removes the guess for every wiring descriptor that follows.
-
-## Applies to
-
-- `cursor.wiring.ts`, `claude.wiring.ts`
-- all `src/entrypoints/*.ts` files
-
-## See also
-
-- [/providers/cursor.md](/providers/cursor.md), [/providers/claude-code.md](/providers/claude-code.md) — the wiring tables built on this naming

package/docs/decisions/ad-016.md

@@ -1,98 +0,0 @@
----
-type: Decision
-title: "AD-016 — Field semantics, state writers, and the core export surface"
-description: "Spawn fields are named apart from the running agent's, parent-model state has a writer, core exports what entrypoints need, ObsKind covers the adapter boundary, blockMode is honoured, and shell audit records are signal-level."
-tags: [decision, entrypoints, contracts, observability, correctness]
-timestamp: "2026-07-29"
----
-
-# AD-016 — Field semantics, state writers, and the core export surface
-
-- **status**: active
-- **date**: 2026-07-29
-
-## Why this exists
-
-Seven decisions about contracts that only settle where the layers meet: what a field name promises, who
-writes a piece of state, what core exports, and which records are durable.
-
-## 1. `spawn*` names the child of a spawn; unprefixed fields name the running agent
-
-Cursor's inbound adapter reads `raw.subagent_type` (the *calling* agent's identity). Claude's inbound
-adapter reads `tool_input.subagent_type` (the *target of a Task spawn*). Same field, inverted semantics.
-`model` had the same clash: on `subagent.start`/`subagent.stop` it means the child being spawned, everywhere
-else the parent's current model. This reproduced as AD-001's `blockParentFast` state being clobbered by
-every subsequent event.
-
-Fix — split the fields in `contracts/harness-event.ts`:
-
-| Field | Meaning | Cursor | Claude |
-| --- | --- | --- | --- |
-| `subagentType` | the **calling** agent's own identity | `raw.subagent_type` | top-level `agent_type` |
-| `spawnSubagentType` | the **target** of a Task spawn | `tool_input.subagent_type` | `tool_input.subagent_type` |
-| `model` | the current / parent model | `raw.model` | `raw.model` |
-| `spawnModel` | the child model being spawned | `raw.subagent_model` | `tool_input.model` |
-
-**Needs verification against a real payload:** AD-014 records `agent_type` as "subagent events only",
-quoting the reference's "present only in subagent hooks". The useful reading is "present whenever a hook
-fires *inside* a subagent's context", which would make it the caller identity on an ordinary `PreToolUse`.
-If that reading is wrong, Claude has no caller-identity signal at tool time and the read-only-subagent rail
-is Cursor-only — a genuine parity gap to be documented rather than hidden.
-
-## 2. Parent-model state is written wherever an event carries the running agent's model
-
-`upsertParentModelState` was built early and consumed by `evaluateSubagentSpawn`, but no task ever called
-it — `blockParentFast` was dead on the write side for several phases. It is now wired in `run.ts`.
-
-## 3. Core must export what entrypoints legitimately need
-
-Several constants and helpers (a stagnation follow-up string, default observability config, lessons
-rendering helpers, a gate-lock timeout error) were being duplicated by entrypoints because the core facade
-curated them out. Duplication guarantees drift. They are now exported from core and the copies deleted.
-
-## 4. `ObsKind` needs adapter-boundary members
-
-`adapter.unrecognized`, `adapter.error` and `adapter.ambiguous` fire before a provider or session is
-resolved. An earlier version bypassed the observability recorder and appended JSONL directly rather than
-widen a core type from outside core — right instinct, wrong resting place. The union is widened inside core
-instead.
-
-## 5. `subagents.blockMode` is honoured by the spawn decision
-
-A documented option must change behaviour: `deny` refuses the spawn, `ask` escalates it. An option the
-service ignores is removed rather than documented.
-
-## 6. `impeccableHook` is out of scope
-
-Relaying a third-party script's verdict is the script author's concern, not the harness's. No port,
-timeout or contract for it exists.
-
-## 7. Shell audit records must be signal-level, not debug-level
-
-`SIGNAL_KINDS` excluded `shell.end` outright, so "shell commands are audited" silently persisted nothing
-unless `debugEnabled` was on. An audit trail that requires opting in is not an audit trail — `shell.end` is
-now signal-level whenever the shell permission was not a plain allow (see
-[/measure.md](/measure.md#observability-planes)).
-
-## Also
-
-`HarnessEvent` had no generic usage field, so Cursor's `usageInPayload: true` went unread — only Claude's
-transcript path fed cost. `usage?: { inputTokens?, outputTokens?, … }` was added, populated by whichever
-provider reports it.
-
-`sandbox` is documented for Cursor only; an earlier version read `raw.sandbox` defensively for Claude with
-no confirmation it exists — verify or drop from the Claude path.
-
-## Applies to
-
-- `contracts/harness-event.ts`
-- both `*.inbound.ts` adapters
-- `core/observability`, `core/subagent-policy`, `core/gate`, `core/lesson`, `core/stagnation`
-- `core/index.ts` (the facade)
-- entrypoints (`run`, `support`, `tool-before`, `tool-after`)
-
-## See also
-
-- [/decisions/ad-001.md](/decisions/ad-001.md) — the rail item 2 restores the writer for
-- [/decisions/ad-009.md](/decisions/ad-009.md) — the earlier round of amendments this one follows
-- [/providers/index.md](/providers/index.md) — `subagentType` vs `spawnSubagentType` in the event mapping tables

package/docs/decisions/ad-017.md

@@ -1,65 +0,0 @@
----
-type: Decision
-title: "AD-017 — The docs gate delegates to the project's tool, and the catalog is the only source of capability metadata"
-description: "Path mapping was measured reporting on 82-100% of commits and removed; the docs gate runs the repository's own staleness tool through the grind path; the capability catalog generates the wizard menu and the architecture rails table."
-tags: [decision, docs, capabilities, gates]
-timestamp: "2026-07-30"
----
-
-# AD-017 — The docs gate delegates to the project's tool, and the catalog is the only source of capability metadata
-
-- **status**: active
-- **date**: 2026-07-30
-
-## Decision
-
-`docs.command` runs the repository's own documentation staleness tool on stop, through the same lock, artifact
-writer and failure path as the lint and test gates. `docs.severity` is `warn` or `deny`, defaulting to `warn`.
-A repository without such a tool gets no gate.
-
-`capabilities/catalog.json` is the only place a capability is described. `tools/render-capabilities.ts`
-generates the wizard's menu and the architecture rails table into marked regions, and `--check` is part of the
-gate.
-
-## Why
-
-Code changes pass lint, tests and the ship gate; the documents describing them pass nothing.
-
-The first implementation inferred staleness from a source-glob to docs-glob map. It was replayed over real
-history with its own evaluator and reported on 100% of applicable commits in one repository and 82–91% in
-another, at every granularity tried — any markdown, co-located markdown, excluding test paths, a specific
-artifact. The denominator is wrong: nearly every commit touches an area and few change documented behaviour.
-A gate that reports almost always detects nothing, so it was removed rather than kept as a fallback.
-
-The tools that do discriminate declare rather than infer. `drift` anchors a document to a file or symbol and
-hashes a normalized AST through tree-sitter. `oasdiff` compares generated specs and classifies changes by
-severity. `ast-grep` matches structure.
-
-Building an equivalent inside the harness was rejected on availability, not taste. Regex over source is the
-failure mode this project has already removed twice. The TypeScript compiler API is not guaranteed at runtime,
-since the installer runs no package install and a clean runtime has no `node_modules`. `Bun.Transpiler.scan()`
-is precise and free but Bun-only, which would make a gate's verdict depend on which runtime launched the hook.
-
-That leaves delegation, which is what `grind` already does: the harness runs the project's lint and test rather
-than implementing either. The docs gate is the same shape, so it inherits stagnation fingerprinting, gap
-feedback and progressive follow-up for free, and adds no second gate mechanism.
-
-## Consequences
-
-- Prose a catalog entry cannot express stays outside the markers: the floor table, the always-ask section, the
-  lessons subsection, and operator mode, which is posture rather than a capability.
-- Adding a capability is one edit to the catalog plus running the generator.
-- No skip token of our own: the tool owns its escape hatch, and `drift` already hardened that path by
-  requiring explicit confirmation that the document was read before re-stamping.
-- A repository with no such tool is told so and the capability stays off.
-
-## Applies to
-
-- `src/entrypoints/stop.ts`, `src/core/policy/`
-- `capabilities/catalog.json`, `tools/render-capabilities.ts`
-- `skills/harness-init/`
-
-## See also
-
-- [/decisions/ad-013.md](/decisions/ad-013.md) — the documentation bundle this gate protects
-- [/decisions/index.md](/decisions/index.md)

package/docs/decisions/ad-018.md

@@ -1,77 +0,0 @@
----
-type: Decision
-title: "AD-018 — Three rails adopted from an external review, each off by default and declared rather than inferred"
-description: "The plan gate, the untrusted-content framing and the global observability spool were adopted after validating each candidate against this codebase; two candidates were refuted and one turned out to be an active defect. All three are opt-in, and both detectors match declared inputs instead of inferring from content."
-tags: [decision, gates, capabilities, security, observability]
-timestamp: "2026-07-30"
----
-
-# AD-018 — Three rails adopted from an external review, each off by default and declared rather than inferred
-
-- **status**: active
-- **date**: 2026-07-30
-
-## Decision
-
-Three capabilities were added, all off by default: `planGate.enabled` (declared scope versus the diff),
-`untrustedContent.enabled` (framing for content read from outside the repository) and `obs.globalSpool`
-(cross-repository record spool).
-
-Both new detectors match **declared inputs**, never inferred ones. The plan gate reads a `HARNESS_PLAN:`
-protocol line and ignores prose about plans. The untrusted-content rail matches a fixed list of tool names,
-every MCP result, and command patterns anchored at the start of a command segment.
-
-## Why
-
-The candidates came from reading another agent-facing product. Each was validated against this codebase
-before being accepted, and the record matters more than the list:
-
-| Candidate | Outcome |
-| --- | --- |
-| Reclaim a stale grind lock | **Defect found here** — `describeHolder` ignored mtime and the stop short-circuited on it, so the steal path was unreachable |
-| Typed handoff phase machine | Refuted — the routing machine already exists in `last_gate_result`, `fingerprint_hits`, `last_failure_category` and `next_action` |
-| Persist state as it happens | Refuted — `stop.ts` already patches the handoff in every branch |
-| Plan versus diff conformance | Adopted |
-| Untrusted-content framing | Adopted |
-| Cross-repo observability | Adopted |
-| Ship evidence tied to a reproduction | Cut — depends on a `HARNESS_REPRO:` discipline nobody practises, and re-executing agent-authored argv is the riskiest surface proposed even behind the floor |
-
-Adopting on reputation would have shipped two mechanisms this product already had and missed the defect.
-
-**Off by default** is not timidity. `obs.globalSpool` writes outside the repository, which is the one thing
-an operator cannot undo by editing project policy. The plan gate changes what "done" means for a turn. A
-capability that changes either belongs in the wizard, presented with its trade-off, rather than arriving
-with an update.
-
-**Declared over inferred** is the lesson AD-017 already paid for with the docs gate: a check that fires on
-almost everything detects nothing. The untrusted rail proved it again on its first production run — the
-patterns were matched as substrings, so writing the documentation that names them tripped the rail on its
-own prose. Anchoring at the start of a command segment fixed it, and the false positive is now a test.
-
-**The plan gate's limit is stated, not hidden.** A turn that declares no plan is not gated. That is the same
-weakness that disqualified the reproduction gate; the difference is that the plan gate executes nothing, so
-the cost of the weakness is friction rather than a privilege-escalation path.
-
-## Consequences
-
-- `Policy` gained `planGate`, `untrustedContent` and `obs`; the loader merges each like every other section.
-- `ProviderPolicyDefaults` gained `untrustedTools`, so a new adapter cannot forget to declare which of its
-  own tools carry outside content — the provider contract test fails if it does.
-- The handoff carries `plan_paths`, `plan_at`, `plan_snippet` and `plan_deviations`.
-- The plan gate runs before the ship gate: a turn whose scope is invalid produced evidence for the wrong
-  change.
-- A deviation without a stated reason is refused, otherwise the gate is a formality satisfied by restating
-  the file just touched.
-- Catalog version 8, twenty-one capabilities, generated regions rewritten from the catalog per AD-017.
-
-## Applies to
-
-- `src/core/plan/`, `src/core/untrusted/`, `src/core/observability/`
-- `src/entrypoints/stop.ts`, `src/entrypoints/response-after.ts`, `src/entrypoints/tool-after.ts`
-- `capabilities/catalog.json`, `docs/concepts.md`, `docs/measure.md`
-
-## See also
-
-- [/decisions/ad-017.md](/decisions/ad-017.md) — declared over inferred, and the catalog as the only source
-- [/decisions/ad-019.md](/decisions/ad-019.md) — the identity bugs found while verifying these rails
-- [/concepts.md](/concepts.md)

package/docs/decisions/ad-019.md

@@ -1,75 +0,0 @@
----
-type: Decision
-title: "AD-019 — A resource is identified by what it resolves to, and a declared capability must be read where it matters"
-description: "Three defects of the same shape: a lock body that parses is not a holder, a launcher path string is not the launcher file, and a capability every adapter declares was consulted by nothing. Each let a gate report a state that was not true."
-tags: [decision, gates, capabilities, providers]
-timestamp: "2026-07-30"
----
-
-# AD-019 — A resource is identified by what it resolves to, and a declared capability must be read where it matters
-
-- **status**: active
-- **date**: 2026-07-30
-
-## Decision
-
-Three comparisons were corrected, all of the same shape — the check used a proxy for the thing instead of the
-thing:
-
-1. **A lock is a holder only if its body names one.** `readLockBody` returning non-null is not enough:
-   `JSON.parse` succeeds on `"a string"`, `42`, `{}` and `{"provider":"p"}`. `isUsableLockBody` checks for
-   `provider`, `session` and `pid`. A lock that names no holder is reclaimed after a five-second grace
-   window, alongside the existing age-based steal.
-2. **A launcher is the file, not the path string.** Wiring comparison canonicalises any argument naming the
-   launcher before deciding whether it changed.
-3. **`contextAtToolBefore` / `contextAtToolAfter` are now read.** `degrade` abstains when a `context`
-   decision lands on an event the provider cannot carry.
-
-## Why
-
-Each of the three let a gate report something untrue, which is worse than a gate that is absent.
-
-The lock case cost **120 seconds per stop, indefinitely**. `describeHolder` returned null for an unreadable
-body, so the stop fell through to `withGateLock`, which reclaimed only by mtime — a recent corrupt file was
-never stale, so the loop ran to the deadline and abstained with an `adapter.error`. The escape was deleting
-the file by hand. It was first written off as safe degradation; that was wrong. An unreadable file blocking
-every stop for two minutes is a defect, and the grace window has to outlast `tryAcquire`'s create-then-write
-gap by orders of magnitude without approaching the stale threshold — five seconds is roughly four orders
-above the gap and twenty-four times below the wait it replaces.
-
-The launcher case made `doctor` report "detected but not wired" for a provider whose eleven hooks were wired
-and firing, on every from-a-clone install, because `settings.json` holds the symlinked install path while the
-runtime resolves the checkout behind it. `bin/tlc-exec.mjs` already documents this hazard and reads `argv[1]`
-to preserve the caller's path — but `bin/tlc` walks `readlink` before invoking it, so the protection never
-applied to a CLI reached through `~/.local/bin/tlc`. Rather than unpick that resolution, the comparison was
-made canonical, which also stops `update` from rewriting a `settings.json` that was already correct.
-
-The capability case was found by verifying an acceptance criterion that assumed a degrade path existed. Both
-adapters declared the field and nothing consulted it, so a `context` returned on an unsupported event was
-rendered into a field the provider ignores and lost silently, while the caller believed it was delivered.
-Abstaining is the honest degradation: `context` is informative, so unlike `ask` there is nothing to escalate
-to.
-
-## Consequences
-
-- `describeHolder` returns null for a stale lock and for one whose body names no holder, so a caller that
-  short-circuits on it falls through to the reclaim path instead of reporting a dead owner.
-- `withGateLock` accepts `unreadableGraceMs`; `GATE_LOCK_UNREADABLE_GRACE_MS` is 5 000 ms.
-- Wiring equality is canonical, so a symlinked install is recognised and not rewritten. Only strings naming
-  the launcher are resolved: a foreign hook's own script path is untouched.
-- The untrusted-content rail keeps its own capability check in addition to `degrade`, because reaching
-  `degrade` would already have consumed the once-per-turn marker and cost the whole turn its framing.
-- A test that passed for the wrong reason was found the same way: it hardcoded `WebFetch` while
-  `providers[0]` is Cursor, whose untrusted list does not contain it. The tool name now comes from the
-  provider's own list.
-
-## Applies to
-
-- `src/core/gate/gate.lock.ts`
-- `src/providers/claude/claude.wiring.ts`, `src/providers/provider.degrade.ts`
-- `src/entrypoints/tool-after.ts`, `tools/doctor.ts`
-
-## See also
-
-- [/decisions/ad-018.md](/decisions/ad-018.md) — the rails whose verification surfaced these
-- [/diagnose.md](/diagnose.md) — operator-facing symptoms of all three

package/docs/decisions/ad-020.md

@@ -1,88 +0,0 @@
----
-type: Decision
-title: "AD-020 — One resolution for the install path, one source for posture, and a config that only advertises what it reads"
-description: "The wrappers collapsed the install symlink, so generated shims named the checkout; status derived posture separately from the loader and disagreed with it; the observability config section was read by nothing. Each is fixed at the root, and a gate refuses any operator home path in a tracked file."
-tags: [decision, runtime, cli, observability, security]
-timestamp: "2026-07-30"
----
-
-# AD-020 — One resolution for the install path, one source for posture, and a config that only advertises what it reads
-
-- **status**: active
-- **date**: 2026-07-30
-
-## Decision
-
-1. **`resolveHarnessHome` returns the conventional install path when `realpath` proves it names the same
-   runtime as the invoked launcher.** An explicit `TLC_HOME` still wins; a relocated install is untouched.
-2. **`status` reads `loadPolicy`.** It reports the posture a hook resolves and, under `--json` and in the text
-   form, where the mode came from (`config`, `file` or `flag`).
-3. **`Policy.obs` carries `globalSpool`, `includePayloads`, `maxAttrChars`, `sessionCostAlertUsd` and
-   `retentionDays`.** The `observability` section is removed, not honoured. `debugEnabled` is deliberately
-   absent.
-4. **A tracked file may not contain an operator's home path**, enforced by a test over `git ls-files` with a
-   per-line `leak-gate-allow` marker for fixtures.
-5. **Project shim hooks stay untracked**, and that is a decision rather than a deferral — see below.
-
-## Why
-
-**One resolution.** Both bash wrappers walk `readlink` before invoking the launcher, so `argv[1]` and `binDir`
-name the checkout. `resolveHarnessHome` documented that exact hazard and still returned the collapsed path.
-Everything derived from it is written to disk or compared: `init` wrote shim hooks pointing at a checkout that
-exists only on the machine that ran it, and `doctor` compared a checkout-shaped path against the install-shaped
-one recorded in the provider's config, reporting healthy wiring as broken. Preferring the conventional path
-only when `realpath` agrees fixes the source instead of each symptom, and refuses to guess: a deliberately
-relocated install still wins.
-
-**One source for posture.** `status` recomputed mode and grind from flag files and defaulted to `solo`. This
-repository, whose policy sets `heads-down`, therefore reported `mode: solo, grind: OFF` while every hook
-resolved focus with grind forced on. A second derivation of the same fact is the whole reason they could
-disagree. Reporting the origin matters as much as the value: the question after a surprising posture is always
-*why*, and a leftover flag is the usual answer.
-
-An earlier reading of this — that `tlc harness grind on` and `mode` were inert — was **wrong**, and is recorded
-as refuted: `policy.loader.ts` has always read those flags. Only the reporting was broken.
-
-**A config that only advertises what it reads.** The `observability` block sat in the example config and in
-this repository's policy, was documented in `concepts.md` with an instruction to set `debugEnabled: true`, and
-was read by nothing — the planes came from a module constant. Values happened to match the defaults, so it
-never diverged visibly; it simply promised configuration that did not exist. Honouring the key would have been
-back-compat this project refuses ([/decisions/ad-003.md](/decisions/ad-003.md)), so the fields that have a real effect moved to `obs` and the key was
-deleted.
-
-`debugEnabled` was implemented, then removed before shipping: every event that resolves to debug level is
-emitted with the audit configuration, which forces debug on for the audit trail (AD-016 item 7). Exposing a
-field with nothing to switch would have repeated the mistake being corrected. A mutation test confirmed the
-same danger elsewhere — `retentionDays` initially reached the runtime with no test covering it, and the
-mutation that ignored it survived until one was added.
-
-**The leak gate.** This product installs with a shell one-liner and tracks its own bundles, so a generated file
-is exactly where an account name slips in unnoticed. A denylist of one name would pass on every other machine,
-so the rule is the shape of the path. An audit before adding it found the tree clean.
-
-## Consequences
-
-- `bin/tlc-exec.d.mts` declares the four-argument resolver; the `.mjs` and its declarations are separate files
-  and both must move together.
-- `StatusReport` gained `modeOrigin`. Any consumer of `status --json` sees one more field.
-- `tlc harness obs prune` reads retention from policy, so two projects on one machine can differ.
-- The example config and this repository's policy no longer carry `observability`; a project that copied it
-  loses nothing, because nothing read it.
-- Fixtures that need a realistic account name carry `leak-gate-allow` on that line.
-
-**Project shims are not version-controllable, by decision.** A portable form needs shell expansion, and `args`
-arrays carry none — so every hook of every provider would need `sh -c` (or `cmd /c` on Windows), paying
-permanent per-hook latency for a file `tlc harness init` regenerates in under a second. They are ignored and
-documented instead.
-
-## Applies to
-
-- `bin/tlc-exec.mjs`, `bin/tlc-exec.d.mts`, `bin/tlc-cli.ts`
-- `src/core/policy/`, `src/entrypoints/support.ts`, `tools/obs-cli.ts`
-- `config.example.json`, `.gitignore`
-
-## See also
-
-- [/decisions/ad-019.md](/decisions/ad-019.md) — the same identity-versus-proxy mistake in three other places
-- [/decisions/ad-003.md](/decisions/ad-003.md) — no backward compatibility
-- [/diagnose.md](/diagnose.md), [/concepts.md](/concepts.md)