@tech-leads-club/harness-toolkit 0.2.1

package/docs/decisions/ad-002.md

@@ -0,0 +1,51 @@
+---
+type: Decision
+title: "AD-002 — Provider-neutral naming and layout"
+description: "The CLI binary is tlc with a harness subcommand group, the runtime home is ~/.tlc/harness/, and the repository is github.com/felipfr/tlc-agent-harness."
+tags: [decision, naming, cli, layout]
+timestamp: "2026-07-29"
+---
+
+# AD-002 — Provider-neutral naming and layout
+
+- **status**: active
+- **date**: 2026-07-29
+
+## Decision
+
+CLI binary is `tlc` with a `harness` subcommand group. Runtime home `~/.tlc/harness/`. Project source of
+truth `.tlc/harness/config.json` (tracked) + `.tlc/harness/state/` (ignored). Repository is
+`github.com/felipfr/tlc-agent-harness`; the predecessor keeps its own name.
+
+> **The repository clause is superseded by [/decisions/ad-052.md](/decisions/ad-052.md)**: the project lives at
+> `github.com/tech-leads-club/harness-toolkit`. Everything else in this decision — the binary, the runtime home and
+> the project policy path — is unchanged, and AD-052 says why moving them was rejected.
+
+## Why
+
+`harness` is the primary binary of Harness.io CLI 3.0 (public beta) — a PATH-order collision that fails
+silently. `.tlc/` namespaces the suite so future `.tlc/skills/` needs no new root dir. A Claude-only user
+must not install into `~/.cursor/`.
+
+## Applies to
+
+- installers (`install.sh`, `install.ps1`)
+- `bin/`
+- all path resolution (`src/platform/paths.ts`)
+- docs
+- the harness-init skill
+
+## Repo hygiene — `.specs/` stays local
+
+`.specs/` holds working specs and task ledgers for whoever is building, which is not part of the product
+tree and goes stale against the code the moment a task lands. The durable *why* lives in this decision
+bundle instead, which is versioned and validated by `tools/check-docs-bundle.ts`.
+
+`.gitignore` also dropped the stale blanket `.cursor/` and `state/` entries (predecessor layout) in favour
+of `.tlc/harness/state/`, since under this decision the provider adapters (`.cursor/hooks.json`, the
+`hooks` block of `.claude/settings.json`) and the project policy are meant to be tracked.
+
+## See also
+
+- [/decisions/ad-003.md](/decisions/ad-003.md) — no backward-compatible dual read of the old layout
+- [/decisions/ad-006.md](/decisions/ad-006.md) — Windows path handling under the new layout

package/docs/decisions/ad-003.md

@@ -0,0 +1,30 @@
+---
+type: Decision
+title: "AD-003 — No backward compatibility"
+description: "No dual-read of .cursor/harness*, no migrate command, no compatibility symlinks — single code path only."
+tags: [decision, migration, layout]
+timestamp: "2026-07-29"
+---
+
+# AD-003 — No backward compatibility
+
+- **status**: active
+- **date**: 2026-07-29
+
+## Decision
+
+No dual-read of `.cursor/harness*`, no migrate command, no compatibility symlinks. Single code path only.
+
+## Why
+
+Two repos, single operator, hand-adjusted. Compatibility layers would be permanent dead weight.
+
+## Applies to
+
+- path resolution
+- config loading
+- installers
+
+## See also
+
+- [/decisions/ad-002.md](/decisions/ad-002.md) — the new layout this decision refuses to bridge to the old one

package/docs/decisions/ad-004.md

@@ -0,0 +1,37 @@
+---
+type: Decision
+title: "AD-004 — Ports and adapters with an anti-corruption layer per provider"
+description: "Core steering logic is provider-agnostic; each provider is an ACL adapter exposing detect, capabilities, toEvent, render, and core degrades on a declarative capability descriptor, never on provider identity."
+tags: [decision, architecture, providers, core]
+timestamp: "2026-07-29"
+---
+
+# AD-004 — Ports and adapters with an anti-corruption layer per provider
+
+- **status**: active
+- **date**: 2026-07-29
+
+## Decision
+
+Core steering logic is provider-agnostic and organized flat-by-aggregate under `core/`. Each provider is an
+ACL adapter under `providers/<name>/` exposing `detect`, `capabilities`, `toEvent`, `render`. Core degrades
+on a declarative `ProviderCapabilities` descriptor, never on provider identity. Enforced by a registry
+contract test plus a lint asserting zero vendor identifiers inside `core/`.
+
+## Why
+
+The hook IO contract is the expensive coupling. A capability descriptor turns provider asymmetry into
+data, which is what makes a hookless provider (all capabilities false → instruction rendering) a new file
+rather than a refactor.
+
+## Applies to
+
+- `src/core/`
+- `src/providers/`
+- all entrypoint handlers
+
+## See also
+
+- [/architecture.md](/architecture.md) — the port shape in practice
+- [/providers/index.md](/providers/index.md) — the two adapters that implement this port today
+- [/decisions/ad-010.md](/decisions/ad-010.md) — where the shared vocabulary lives

package/docs/decisions/ad-005.md

@@ -0,0 +1,36 @@
+---
+type: Decision
+title: "AD-005 — Local test runner is the gate; CI matrix runs on every push"
+description: "tlc harness test is the per-task gate; .github/workflows/ci.yml runs the ubuntu|macos|windows matrix on push and pull_request, free on standard runners because the repository is public."
+tags: [decision, ci, gate, testing]
+timestamp: "2026-07-29"
+---
+
+# AD-005 — Local test runner is the gate; CI matrix runs on every push
+
+- **status**: active
+- **date**: 2026-07-29
+
+## Decision
+
+`tlc harness test` runs the full suite (golden-file wire formats, registry contract, core-purity lint,
+concurrency, platform units) and is the per-task gate. `.github/workflows/ci.yml` carries the
+`ubuntu|macos|windows` matrix on `push` to main, on `pull_request`, and on demand.
+
+## Why
+
+A task cannot be called done on inspection, so the gate must be runnable locally and must be the
+per-task gate. CI is the second, independent pass, and the only place the Windows leg runs.
+
+Standard GitHub-hosted runners are free and unlimited on public repositories, across Linux, macOS and
+Windows. Larger runners bill even there, so the matrix stays on standard ones.
+
+## Applies to
+
+- `.github/workflows/ci.yml`
+- `bin/tlc-cli.ts`
+- every task's definition of done
+
+## See also
+
+- [/decisions/ad-008.md](/decisions/ad-008.md) — what the local gate actually runs

package/docs/decisions/ad-006.md

@@ -0,0 +1,49 @@
+---
+type: Decision
+title: "AD-006 — Windows ships in scope, with CI covering the suite and the build"
+description: "Windows path resolution, exec-form hooks and the .cmd shim are in scope; the CI windows-latest leg runs the suite and the dist build; install.ps1 and the editor end sit outside CI coverage."
+tags: [decision, windows, platform]
+timestamp: "2026-07-29"
+---
+
+# AD-006 — Windows ships in scope, with CI covering the suite and the build
+
+- **status**: active
+- **date**: 2026-07-29
+
+## Decision
+
+Windows stays in scope for design and code (`os.homedir()` only, exec-form hooks, sanitized filenames,
+atomic-write retry, junctions + `.cmd` shim). The CI `windows-latest` leg runs the suite and the `dist/`
+build on every push. `install.ps1` and hooks firing inside an editor session sit outside that coverage
+hardware.
+
+## Why
+
+The portable choice is the correct choice independently of Windows, so deferring would relocate work rather
+than remove it — and would reopen every call site later. But the operator develops on WSL and cannot prove
+Windows behavior; claiming validation would be dishonest.
+
+## Amended 2026-08-03 — `install.sh` is covered on POSIX
+
+"Installers sit outside coverage" was read as *no installer test at all*, and that gap shipped a broken
+primary install path: `curl … | bash` aborted on `${BASH_SOURCE[0]}` under `set -u`, because a piped script has
+no file on disk. The README's first command could not run on any platform, and nothing failed to say so.
+
+`install.sh` now has a POSIX suite (`tools/__test__/install-sh.test.ts`) covering the piped invocation, the
+checkout invocation, and a guard against reading `BASH_SOURCE` without a default. It skips on `win32`, so the
+original decision is unchanged where it was actually about hardware: `install.ps1` and hooks firing inside an
+editor session remain uncovered, because the operator still cannot prove them.
+
+The distinction the first wording missed: *the shell installer is testable anywhere bash exists*, and only
+the PowerShell installer and the editor end depend on Windows.
+
+## Applies to
+
+- `src/platform/`
+- installers
+- README
+
+## See also
+
+- `README.md` (repo root, outside this bundle) — states this caveat to users directly

package/docs/decisions/ad-007.md

@@ -0,0 +1,36 @@
+---
+type: Decision
+title: "AD-007 — Vendor check applies to core tests; absence checks do not"
+description: "tools/check-boundaries.ts scans src/core/**/__test__/ for vendor identifiers but excludes __test__ from the HOME/.cursor absence checks, so core tests must use opaque provider names."
+tags: [decision, boundaries, testing, core]
+timestamp: "2026-07-29"
+---
+
+# AD-007 — Vendor check applies to core tests; absence checks do not
+
+- **status**: active
+- **date**: 2026-07-29
+
+## Decision
+
+`tools/check-boundaries.ts` scans `src/core/**/__test__/` for vendor identifiers, but excludes `__test__`
+from the `process.env.HOME` and `.cursor/…` absence checks. Consequence: **core tests must use opaque
+provider names** (`provider-a`, `provider-b`), never `cursor`/`claude`.
+
+## Why
+
+A test asserting a string is absent must contain that string as the literal it searches for — so excluding
+tests is correct for absence checks. But a core test that *needs* the literal `cursor` or `claude` is itself
+the smell the vendor rule exists to catch; writing core tests with opaque names is what proves core treats
+a provider name as an opaque string. Excluding tests there would have made the strongest guarantee opt-in.
+
+## Applies to
+
+- `tools/check-boundaries.ts`
+- every `src/core/**/__test__/` file
+- design guarantees
+
+## See also
+
+- [/decisions/ad-004.md](/decisions/ad-004.md) — the boundary this check enforces
+- [/decisions/ad-011.md](/decisions/ad-011.md) — real vendor literals the check caught

package/docs/decisions/ad-008.md

@@ -0,0 +1,54 @@
+---
+type: Decision
+title: "AD-008 — Biome + TypeScript in the gate; @types/node pinned to the declared floor"
+description: "devDependencies add @biomejs/biome@2.5.6 and typescript@7.0.2; the gate becomes biome check && tsc --noEmit && node --test && check-boundaries, and @types/node is pinned to ^24, not the latest 26.x."
+tags: [decision, gate, typescript, biome]
+timestamp: "2026-07-29"
+---
+
+# AD-008 — Biome + TypeScript in the gate; `@types/node` pinned to the declared floor
+
+- **status**: active
+- **date**: 2026-07-29
+
+## Decision
+
+devDependencies `@biomejs/biome@2.5.6` (lint + format) and `typescript@7.0.2` (`tsc --noEmit`). Gate becomes
+`biome check && tsc --noEmit && node --test && check-boundaries`. `@types/node` pinned to `^24`, **not** the
+latest 26.x. Both configs are scoped to the new module trees; a later widening task covers the rest of the
+tree.
+
+## Why
+
+The repo had no linter, no formatter, and no typechecker — `node --test`, esbuild, and Bun all strip types
+without validating, so a "no TypeScript errors" criterion was unverifiable. This matters most where
+`Decision` / `HarnessEvent` / `ProviderCapabilities` are discriminated unions that deliver nothing without
+checking. Biome does **not** substitute for `tsc`: its type engine is deliberately independent of the
+compiler and rule-scoped, which is fine for a lint rule and not for a build gate. `@types/node` is a
+compatibility contract, not a tool — typing against Node 26 while `engines` declares `>=24` would let
+Node-26-only APIs pass a gate that promises Node 24 support.
+
+`noUncheckedIndexedAccess` stays on. It produces most of the diagnostic noise but catches exactly the class
+of bug that appears when parsing vendor payloads (`match[1]`, `args[0]`, `parts[2]`) — the highest-value
+flag for an adapter layer.
+
+## Applies to
+
+- `tsconfig.json`
+- `biome.json`
+- `package.json`
+- `CONTRIBUTING.md`
+- every task's gate
+
+## Historical note — local Node below the declared floor
+
+Earlier in the port, local `node` was **v22.22.3** while `engines.node` and the launcher required **24+**
+(the launcher exits fatally below it), and `npm install` confirmed with `EBADENGINE`. Tests ran fine (type
+stripping is unflagged since Node 22.18), but the harness itself could not run end-to-end locally until Node
+was upgraded to 24 or 26. This was never a build blocker — only a blocker for a local end-to-end smoke of
+the installed harness — and has since been resolved by upgrading the local Node runtime.
+
+## See also
+
+- [/decisions/ad-005.md](/decisions/ad-005.md) — the gate this decision defines the contents of
+- `CONTRIBUTING.md` (repo root, outside this bundle) — the checks a contributor runs

package/docs/decisions/ad-009.md

@@ -0,0 +1,61 @@
+---
+type: Decision
+title: "AD-009 — Event kinds are provider-agnostic; capabilities are data, not flags"
+description: "The event-kind union covers what any provider emits, askSupportedOn is a list of kinds rather than a pair of booleans, and EffortLevel has five levels."
+tags: [decision, design, cursor, contracts]
+timestamp: "2026-07-29"
+---
+
+# AD-009 — Event kinds are provider-agnostic; capabilities are data, not flags
+
+- **status**: active
+- **date**: 2026-07-29
+
+## Decision
+
+Seven corrections to the event-kind union and the capability descriptor, each one settling how provider
+asymmetry is represented.
+
+1. **18 event kinds, not 16.** Added `mcp.after` and `thought.after`. Both are wired to observability
+   already — returning `null` for them would silently drop signal that already exists. A kind exists when
+   *any* provider produces it; a provider that cannot is gated by its descriptor, not by the kind's absence.
+2. **`askAtToolLevel` + `askAtShellLevel` → `askSupportedOn: HarnessEventKind[]`.** A boolean pair cannot
+   express Cursor's real behavior (`ask` on `beforeShellExecution` and `beforeMCPExecution`, but not
+   `preToolUse`). Data instead of flags; a hookless provider gets `[]`.
+3. **`contextAtToolTime` → `contextAtToolBefore` + `contextAtToolAfter`.** The table listed `partial` for
+   Cursor — a non-boolean in a boolean field. The split is what `partial` meant: `postToolUse` carries
+   `additional_context`, `preToolUse` does not.
+4. **`HarnessEvent.text?: string` added.** `response.after` ship-claim detection needs the response body,
+   and `raw` is adapter-only by contract. Also serves `prompt.submit` and `thought.after`.
+5. **`EffortLevel` is five levels** — `low | medium | high | xhigh | max`, per Claude Code's documented
+   `effort.level`. A three-value type makes `isEffortLevel` reject `xhigh`/`max`, so `minEffort` would skip
+   silently on exactly the high-effort sessions it governs.
+6. **`continue` under `enforcesHooks: false` keeps the `ADVISORY —` prefix.** Unenforced guidance must
+   announce itself.
+7. **Provider registration is part of each provider's final task.** `providers/<name>/index.ts` composing
+   the pieces + one line in `provider.registry.ts`.
+
+## Why
+
+The tables were written from vendor docs without being executed. Building Cursor against them — with
+goldens captured from the real pre-refactor handlers — surfaced what documentation review could not. Items
+1, 3, and 5 are outright defects that would have shipped as silent signal loss; the rest are precision.
+
+## Applies to
+
+- `src/providers/provider.types.ts` / `src/contracts/`
+- `provider.degrade.ts`
+- `cursor.capabilities.ts`
+- the Claude adapter
+- `minEffort` / ship-claim detection
+
+## Note — `ask` at `tool.before` is provider-specific
+
+Cursor's `askSupportedOn` excludes `tool.before`, so its golden asserts `ask` never reaches the renderer
+there. Claude's **includes** it (see [/providers/claude-code.md](/providers/claude-code.md)). That invariant
+is Cursor's, not general — do not generalize it from reading only Cursor's tests.
+
+## See also
+
+- [/providers/cursor.md](/providers/cursor.md), [/providers/claude-code.md](/providers/claude-code.md)
+- [/decisions/ad-010.md](/decisions/ad-010.md) — where these contract types now live

package/docs/decisions/ad-010.md

@@ -0,0 +1,45 @@
+---
+type: Decision
+title: "AD-010 — Shared vocabulary moves to src/contracts/"
+description: "HarnessEvent, Decision, Rendered, ProviderCapabilities, EffortLevel, and ProviderWiring live in a new src/contracts/ module holding types and pure helpers only; core and providers both import from it, neither imports the other."
+tags: [decision, architecture, contracts]
+timestamp: "2026-07-29"
+---
+
+# AD-010 — Shared vocabulary moves to `src/contracts/`
+
+- **status**: active
+- **date**: 2026-07-29
+
+## Decision
+
+`HarnessEvent`, `HarnessEventKind`, `Decision`, `Rendered`, `ProviderCapabilities`, `EffortLevel`,
+`ProviderWiring` move into a **`src/contracts/`** module holding types and pure helpers only — zero
+behavior, zero IO. Both `core/` and `providers/` import from it; neither imports the other.
+`check-boundaries` forbids `core ↔ providers` and additionally forbids
+`contracts → {core, providers, platform, entrypoints}`.
+
+## Why
+
+The design's dependency diagram said core never imports providers, and separately that core returns
+`Decision` values and that degradation consumes `HarnessEvent`. Those two statements are only compatible if
+the vocabulary lives somewhere both can reach. It never said where.
+
+## Why a third module rather than putting the types in `core/`
+
+Classic hexagonal would place port types in the domain and have adapters depend inward, which also works. A
+separate contracts module was chosen because it keeps the boundary rule symmetric and mechanically
+checkable (neither side may import the other, full stop), makes the shared surface explicit and small
+enough to review, and makes behavior coupling impossible rather than merely discouraged — an adapter cannot
+reach a core service even by accident.
+
+## Applies to
+
+- `src/contracts/` (new)
+- `src/providers/**` (imports)
+- `tools/check-boundaries.ts`
+
+## See also
+
+- [/architecture.md](/architecture.md) — how contracts sits between core and providers
+- [/decisions/ad-004.md](/decisions/ad-004.md) — the ports-and-adapters shape this vocabulary serves

package/docs/decisions/ad-011.md

@@ -0,0 +1,59 @@
+---
+type: Decision
+title: "AD-011 — Vendor-specific data belongs to the provider, not to core"
+description: "Model catalogs, cost pool names, and lessons rendering all move out of core and into each provider — four corrections surfaced by the vendor-identifier check hitting real code."
+tags: [decision, providers, core, policy, pricing]
+timestamp: "2026-07-29"
+---
+
+# AD-011 — Vendor-specific data belongs to the provider, not to core
+
+- **status**: active
+- **date**: 2026-07-29
+
+## Decision
+
+Four corrections, all surfaced by the vendor check hitting real code.
+
+1. **Model catalogs move to the provider.** `ProviderPort` gains
+   `policyDefaults(): { allowedModels, blockedPatterns, minEffort }`. Cursor supplies its own model list and
+   `-fast` patterns; Claude supplies its own. `core/policy` keeps only the *shape* and provider-neutral
+   patterns (`-fast`, `/fast`). `core/subagent-policy` receives the effective list as an argument, exactly
+   as it already receives `ProviderCapabilities`. Resolution at the entrypoint: project/user config →
+   provider defaults → core generic defaults.
+2. **Cost pool names in core become neutral**: `provider_native | other | auto | unknown`. Vendor-named
+   pools (e.g. a Cursor-specific catalog key) move to `platform/pricing.ts`, which is correctly outside the
+   vendor scan because pricing must name real vendors. `cost_source` is `"provider"`, not a vendor name.
+3. **`FailureCategory` and `GateGap` get one home** — `core/gate/gate.types.ts`. `core/handoff` and
+   `core/lesson` import the types from there instead of each hand-copying them. Sibling type imports inside
+   `core/` are fine; only cross-*module* imports are barred.
+4. **Provider-side lessons rendering is assigned.** `.tlc/harness/lessons.md` is the source of truth.
+   Rendering the provider-native view is each provider's own concern: Cursor's
+   `.cursor/rules/harness-lessons.mdc` and Claude's `@.tlc/harness/lessons.md` line in `CLAUDE.md` each
+   belong to that provider's wiring.
+
+## Why
+
+The vendor check did its job — it caught that a Cursor model catalog was sitting in what is supposed to be
+provider-agnostic core. Two vendor literals were also passing only because `_` suppresses the `\b` word
+boundary in the scan regex, i.e. tolerated by a regex accident rather than by design. Fixing them properly
+puts vendor knowledge where the anti-corruption layer says it goes.
+
+## Note
+
+An early interim shipped `allowedModels: []`, which is functionally inert while `enforceAllowlist` defaults
+`false` but becomes a footgun the moment a user enables it. Item 1 removes that footgun.
+
+## Applies to
+
+- `contracts/` (port shape)
+- `providers/cursor/`, `providers/claude/`
+- `core/policy`, `core/subagent-policy`
+- `core/observability`, `core/gate`, `core/handoff`, `core/lesson`
+- `platform/pricing.ts`
+
+## See also
+
+- [/measure.md](/measure.md) — the neutral cost pool names in the observability record shape
+- [/providers/index.md](/providers/index.md) — `policyDefaults()` on each provider
+- [/decisions/ad-007.md](/decisions/ad-007.md) — the check that caught this

package/docs/decisions/ad-012.md

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

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