Architecture Decision Records
Most users do not need to read these. ADRs document why corpus is shaped the way it is — the decision history, including supersessions, lives here and only here.
Each ADR is a dated, immutable record of one load-bearing decision — its context, the decision, and its consequences — so a fork can judge whether the choice still fits. The full truth of any decision is the chain of ADRs that touch it, not the latest one alone.
This ledger is the index. It carries a row for every ADR — kept, amended, already-superseded, and new — with its current disposition. (The §N markers throughout this ledger and the topic tables below reference the historical kernel spec — a monolithic document since folded into docs/; they are retained as decision-provenance, not live links.)
Governance (Nygard immutability)
An accepted ADR MUST NOT be edited in place. "Amending" a decision means publishing a new, superseding ADR; the original keeps its body and gains only a
Superseded by ADR-NNNNstatus line. Rewriting an ADR destroys the historical record that makes the chain auditable.
Two consequences of that rule govern this ledger:
- Numbers
0011and0012are intentionally vacant — vacated in an earlier consolidation and left unfilled so references to higher numbers do not shift. - The pre-kernel ADRs (
0001–0026) are immutable history. Their bodies still name the pre-kernel vocabulary and paths (scaffold/,personas/, the consolidatedSKILL.md, the earlier flow-graph) as they were decided. Those bodies are not subject to the kernel's active-construct rules (the §34 / A19–A28 retirements) — those rules govern canonical/active prose, not the historical record. The current truth of any amended decision is its superseding0027+ADR; read the chain, not the earlier body in isolation.
The ledger
| ADR | Title | Disposition |
|---|---|---|
| 0001 | Four core document types | Kept — recast onto the unified artifact set by 0030 |
| 0002 | Personas pair 1:1 with task types | Superseded by 0020; the persona model it sits in was later recast by the profile × pass model (0036, §27.4); persona shipping partially superseded by 0064 |
| 0003 | Distillation flows downhill only | Kept |
| 0004 | Task files are gitignored | Superseded by 0060 — tasks are committed workspace flow artifacts |
| 0005 | Template placeholder syntax {{name}} | Kept |
| 0006 | Skeptic mindset on fix tasks | Amended → Superseded by 0036 (Skeptic is a profile on fix/review passes) |
| 0007 | Bug report is diagnosis-only | Kept — the epistemic-stance invariant of the bug-report.md source artifact (§29) |
| 0008 | Empirical proof is framework-level | Kept |
| 0009 | Personas are mindsets, not org roles | Amended → Superseded by 0036 (personas become heuristic profiles); partially superseded by 0064 (personas fold into focused guides) |
| 0010 | Writes single-thread through orchestrator | Kept — preserved by the write-surface model (0039) |
| 0011 | (intentionally vacant) | — |
| 0012 | (intentionally vacant) | — |
| 0013 | Iron law + red-flags persona format | Amended → Superseded by 0036 (iron law → a profile's ## Refuses table, §27.2) |
| 0014 | Delegation vs internal recursion | Kept |
| 0015 | Framework versioning for consumers | Kept, extended by 0041 — scoped to the package axis; the language axis is added alongside (§25); spec-file versioning clauses superseded by 0058 (specs carry no language version) |
| 0016 | Skill bodies are self-contained | Kept — governs pass-guide bodies (§26) |
| 0017 | No always-loaded skills | Kept — pass guides and profiles are lazily loaded (§26.4, §31) |
| 0018 | Commands resolve through the AGENTS.md contract | Amended → Superseded by 0038 (VERIFY BY adapters resolve through AGENTS.md > Commands) |
| 0019 | Personas ship as individual skills | Amended → Superseded by 0036 (a standalone file is one carrier option, §27.1); partially superseded by 0064 (persona shipping model) |
| 0020 | Activation by self-assessment | Amended → Superseded by 0037 (doctrine is "load what the task names"; description-match is the fallback) |
| 0021 | Verification contract | Kept — a verification layer of the single SOL VERIFY BY model (§15) |
| 0022 | Acceptance criteria are executable checks | Kept — a verification layer of the SOL VERIFY BY model (§15) |
| 0023 | Harness-enforcement contract | Kept — a verification layer of the SOL VERIFY BY model (§15) |
| 0024 | Self-reviewed vs independently-reviewed confidence tiers | Amended → Superseded by 0035 (tiers map onto the 7-value verdict taxonomy) |
| 0025 | Orchestration coordination artifact | Amended → Superseded by 0039 (owned/forbidden paths → the lowered write-surface) |
| 0026 | Machine-readable conformance contract + fixtures | Kept — a verification layer of the SOL VERIFY BY model (§15); realized by the golden corpus (0033); refined by 0063; validity clauses partially superseded by 0066 |
| 0027 | SOL is the obligation language | New (kernel) — §5, §6; partially superseded by 0058 (SOL becomes the optional stricter surface, a notation) |
| 0028 | APS is the prose standard | New (kernel) — §7; partially superseded by 0058 (APS becomes advisory writing rules) |
| 0029 | The 9-pass compiler model | New (kernel) — §9; refined by 0057 (nine steps become the advanced lifecycle); per-kind routing clauses partially superseded by 0068 |
| 0030 | The unified artifact set | New (kernel) — §20, §29 |
| 0031 | The source-authority two-axis model | New (kernel) — §22 |
| 0032 | The memory model | New (kernel) — §23 |
| 0033 | The golden corpus | New (kernel) — §33; refined by 0065; corpus framing superseded by 0066 |
| 0034 | The unified SOL-<LAYER><NNN> lint namespace | New (kernel) — §8 |
| 0035 | The 7-value verdict model | New (kernel) — §14; supersedes 0024 |
| 0036 | Personas become heuristic profiles | New (kernel) — §27; supersedes 0006, 0009, 0013, 0019 |
| 0037 | Loading doctrine: load what the task names | New (kernel) — §26.4; supersedes 0020 |
| 0038 | VERIFY BY adapters resolve through AGENTS.md Commands | New (kernel) — §15, §31.3; supersedes 0018 |
| 0039 | The write-surface model | New (kernel) — §18, §19; supersedes 0025 |
| 0040 | The kernel payload ships under starter-kit/ | New (kernel) — §20.5, §34.0 (rename from scaffold/, pulled forward from the v0.2 deferral) |
| 0041 | Two-axis versioning (language axis + package axis) | New (kernel) — §25; extends 0015; spec-file clauses superseded by 0058 (no per-file language version) |
| 0042 | Skills carry as SKILL.md; conditioning ships as many standalone surgically-activated skills | New (kernel) — §26, §27; refines 0016, 0017, 0019, 0029, 0036, 0037; refined by 0064; per-kind routing clauses partially superseded by 0068 |
| 0043 | Checkable documents: what is lintable, and with what (obligation-blocks spec-only; non-spec artifacts get a subtractive, deterministic, mostly-advisory check surface) | Proposed / parked — direction only; no document-lint rule built yet (SOL-P is still spec-prose-only). Its backlog plan was retired (see git history) |
| 0044 | The kernel is a derived, self-contained payload — docs/ is canonical for the language/passes twins (kernel resolves offline: no unshipped §N/Appendix refs, no docs-only links); derivation transform + eyeball-diff check + §-resolution policy + coherence gate | New (kernel) — §20.5/§34; refines 0040; twin mechanism retired by 0051 (docs/ is now the sole canonical home) |
| 0045 | Overlays are project-owned and live at .corpus/overlays/ (outside the replaceable .corpus/kernel/), so a kernel upgrade can't clobber project rules; producer seed moves starter-kit/.agents/overlays/ → starter-kit/overlays/ | Superseded by 0049 — no overlays dir; conventions live in AGENTS.md |
| 0046 | Isolation binary: a code task implementing a spec/audit gets a worktree+branch (corpus/<spec-slug>) off the base; ad-hoc/doc/review work stays in-place. Orthogonal to parallel_group; isolation:/base: frame fields override | New (kernel) — §18; refines 0039; operationalizes 0010 |
| 0047 | Skills are self-contained — each carries the operational rules inline (single-sourced from the spec) and only names the deep reference; citations are provenance, not a required read (LLMs don't reliably follow them) | New (kernel, from corpus-cli adoption) — refines 0016, 0042 |
| 0048 | The installed payload is the runtime surface (skills + templates + memory seed + bootloader + config/overlays); passes/, language/, conformance/ are NOT shipped — they're the human reference + corpus in the corpus repo | Superseded by 0049 — what to ship survives (skills + reference/ cards + templates), but it installs in place, not into a .corpus/kernel/ mount |
| 0049 | Minimal install (as amended same-day): copy the kit in place next to your own skills — no .corpus/kernel/ mount, no symlink bridge; six prescribed flow folders (the goldilocks update reversed the original zero-folder form); future-toolchain dirs created lazily; conventions go in AGENTS.md | New (from corpus-cli adoption skeptic review) — supersedes 0045, 0048; refines 0040, 0044; depends on 0047; flow folders shipped pre-built per 0069 |
| 0050 | corpus is a spec-repo discipline: intent lives in a spec/docs repo (the authoring kit), code repos stay pristine (no required footprint; SOL is self-legible so no reading skill; scratch gitignored; durable outcomes → linked docs-repo PR; the PR is the default trace/verdict). Co-located = the collapse case. Multi-repo via namespaced IDs. Drops the per-repo version marker | New (spec-repo topology) — refines 0049, 0041; depends on 0047; §6 narrowly reversed by 0081 (the kit provenance stamp is re-adopted) |
| 0051 | Complete the pivot: specs live top-level (.agents/ = tooling only); the starter kit is one authoring kit (20 skills); the 17 code-implementation skills become docs/library/code-skills/ reference (a code repo's only optional skill is implement-and-verify); the kit ships no language/passes/conformance — the twins are deleted (docs/ is the sole home) and the corpus moves to top-level conformance/ | New (complete the pivot) — refines 0050, 0048, 0042; retires the twin mechanism of 0044; refined by 0057; validity bar partially superseded by 0066 |
| 0052 | One artifact-home model: feature-scoped artifacts live in per-feature folders specs/<NNN-feature>/ (spec + its audit/research/bug-report/… co-located); ADRs live in a numbered decisions/; findings stay in .agents/memory/. Removes the open-ended top-level type-folder cloud and the contradictory "under .agents/" routing; lint stays spec-only (per 0043) | New (cohesive scaffold, grounded) — refines 0051, 0050; aligns with 0032, 0043; partially superseded by 0060 (hybrid workspace layout) |
| 0053 | Positioning reframe: corpus is a structured specification & review system for agentic work (messy inputs → verifiable specs → bounded work → reviewable evidence); foregrounds review-as-exceptions as the merge-gate payoff / the control layer the evidence says adoption lacks. Adds no new artifacts, dirs, roles, or runtime — reframes existing machinery (merge gate, WAIVED, status, source authority); only adds an optional ## Source inputs spec section + the grounding sources | New (grounded positioning) — refines 0050, 0051, 0052; grounded by HARNESSBENCH/AHE/HAL/TERMBENCH/ORCHID/METR/DORA2025; refined by 0057; intake-directory deferral partially superseded by 0061 |
| 0054 | Complete the de-cosplay: drop the residual compiler vocabulary from reader-facing content — class label compiler-visible → corpus-format, conformance tier corpus-compilable → lowerable, and the structured-form provenance fields compiler_version → tool_version / compiled_at → emitted_at (a reserved-schema rename, safe under NO RUNTIME). Keeps the lower step + *.ir.json filename + genuine other-ecosystem compiler refs | New (honesty sweep) — enforces 0053 §4 + Invariant 1 (NO RUNTIME) in the contract layer; grounded by the skeptic audit; tree-level register completed by 0070 |
| 0055 | Close the gate's soft-control gaps the simulation audit found: (1) an empty in-scope obligation set does not pass by vacuity — an uncovered change BLOCKs until a covering obligation is authored; (2) oracle adequacy (SOL-V011) is BLOCKING for RISK high|critical (advisory stays for low|medium) so the gate consults adequacy where consequence is highest; (3) an uncovered bug forces a spec amendment as the fix task's first obligation. Accompanying single-source reconciliations: SOL-M001 aligned to its canonical definition; hash fields marked by-hand placeholders. No closed-set / grammar / step / verdict change | New (close the soft-control gaps) — refines 0053, 0043; grounded by the 10-aspect simulation audit + SWEBENCH-ADQ/UTBOOST |
| 0056 | Adversarial self-review is a mandatory completion discipline. Before any work is done, the actor MUST adopt the skeptic stance over their own output (refute-by-default — re-run proofs, hunt the unexercised path, check scope/semantic drift) and record it in ## Self-review. Necessary but not sufficient, and not the gate: it yields fixes + a recorded critique, never a verdict — implementer ≠ reviewer and the independent merge gate are reaffirmed. Strengthens the checklist ## Self-review + broadens persona-skeptic to one's own work. No closed-set/step/verdict change | New (dogfooding) — refines the implement step + persona-skeptic + the working rules; reaffirms 0053's independence; grounded by REFLEXION |
| 0057 | Practical-first repositioning: corpus is a lightweight spec & review workflow for teams using coding agents; the six-step loop (Pull → Spec → Task → Run → Review → Close, + conditional Inventory/Change Plan) is primary; the nine-step lifecycle becomes one advanced reference page; docs become a numbered happy path + reference; "source of truth" → "intended behavior"; full rename scope, page labels, no counts ceremony | New (repositioning) — refines 0053, 0054, 0029; supersedes the naming clauses of 0049 §2 |
| 0058 | Two-tier spec format, one data model: plain structured markdown default (### AC-NNN + Verify with:); SOL as the optional stricter surface via format: sol (a notation, unversioned); one form-agnostic requirement record; writing rules become advisory practice | New (repositioning) — supersedes the spec-file clauses of 0041/0015; partially supersedes 0027, 0028 |
| 0059 | Frontmatter type: is the sole artifact discriminator — plain .md everywhere; no filename infix; format: sol is the only spec-surface selector; *.ir.json/*.plan.json survive only as reserved future-CLI contract names (per the addendum) | New (repositioning) — supersedes the infix-partition model; refines 0030, 0054 |
| 0060 | The corpus Workspace: hybrid layout (feature folders for intent, committed type folders for flow artifacts incl. tasks/reviews/findings), hand-edited status.md board, co-located and external co-equal; pins the task-packet and review-packet formats (evidence rules, spot-check, exception triggers) | New (repositioning) — supersedes 0004; partially supersedes 0052; refines 0049, 0050, 0032; layout shipped pre-built per 0069 |
| 0061 | Intake artifact + Pull step: verbatim snapshot of the upstream ticket (source, url, captured); recommended for externally-sourced work; no connectors ship | New (repositioning) — refines 0030; partially supersedes 0053's intake deferral |
| 0062 | Code-repo adapter: pristine today (one-line AGENTS.md pointer at most; PR links the workspace review packet); a future CLI may own a fully gitignored .corpus/ local-state dir, specified on the future-CLI page only | New (repositioning) — reaffirms 0049, 0050 |
| 0063 | Honesty framework + tooling boundary: every rule carries a level (convention / checklist / toolable / enforced); check codes are review checklists; corpus-cli is the named reference implementation (corpus spec check, shipped early); "aim for ~100 lines" replaces cap language | New (repositioning) — refines 0023, 0026, 0034, 0043, 0055 |
| 0064 | Minimal kit: 12-file core copy surface (8 templates + AGENTS.md + write-spec / implement-task / review-output guides); advanced tier optional; personas fold into the guides (surveyor stays standalone); manual-first adoption | New (repositioning) — partially supersedes 0019, 0002, 0009; refines 0042, 0036, 0047, 0056; adoption framing superseded by 0069 (kit copied whole) |
| 0065 | Three flagship examples (feature-from-ticket, bug-fix, large-pr-review); the large-PR change-plan refactor review is the README demo; checks fixtures stay separate producer test data | New (repositioning) — refines 0033; refined by 0071 (step bars score the examples); happy-path example genericized feature-from-jira→feature-from-ticket by #58 (de-Jira) |
| 0066 | Checks redefinition: adopter validity bar = populated AGENTS.md + core templates + ≥1 spec passing core checks; evidence rules (non-empty-paste, no-open-critical) survive verbatim; reference values/counts are producer-internal; fixtures = "checks fixtures" incl. simple/SOL equivalence pairs (anti-fork proof) | New (repositioning) — partially supersedes 0026, 0051 validity clauses, 0033 framing; refines 0063; fixtures home renamed by 0070; scoring moved to step bars by 0071 |
| 0067 | Memory tiering: core = findings/ + the Close rule + the status.md board; the load-when index / glossary / patterns / promotion statuses / ledger become one advanced reference page | New (repositioning) — refines 0032 |
| 0068 | Inventory & Change Plan (the transformation tier): change plans (kinds, baseline/target, preservation guarantees, waves, rollback, cutover, task split) and inventories (brownfield contract maps) as conditionally-core artifacts; tasks may source from spec and/or change plan; review packets gain change-plan coverage | New (repositioning) — partially supersedes the per-kind routing clauses of 0029, 0042; refines 0030, 0046 |
| 0069 | The starter kit is a workspace, copied whole: kit root = a complete workspace (AGENTS.md + symlinks, templates/, seeded flow folders, status.md, example); guides at .agents/skills/ with tool-adapter symlinks (.claude/skills → ../.agents/skills); agent/ staging dir retired; advanced/ stays piecemeal-by-design; separate template repo deferred to public launch; addendum: copy with cp -R | New (scaffolding) — refines 0064 (copy-checklist framing superseded by copy-the-folder), 0060, 0049 |
| 0070 | checks/ is the home of the checks contract: conformance/ → checks/, conformance.yaml → checks/checks.yaml (version 0.3.0); the counts registry's producer home moves with its file; ADR bodies keep the historical name | New (scaffolding) — completes 0054's register sweep at tree level; refines 0066 |
| 0071 | Step bars replace evals/: the per-step quality bars are product reference — one page (docs/reference/step-bars.md, checklist level) carrying the six step bars + cross-step predicates, linked from the happy path; evals/ deleted; predicate ids (P/S/T/R/V/C) survive | New (scaffolding) — supersedes the standalone evals surface; refines 0065, 0066 |
| 0072 | The run summary digest + DX format amendments: ## Run summary joins the task packet (digest citing Verify pastes — never a second paste home); waivers = record (who·rows·why·expiry) + additive terminal review status waived, row results closed at four; blocked is board-only vocabulary; multi-context Commands via per-context sub-tables; Pass-evidence sentence admits manual evidence, amended once and swept; checks.yaml v0.4.0 | New (DX remediation) — partially supersedes 0060 (run-record addendum clause); refines 0064, 0066, 0070, 0063 |
| 0073 | The multi-repo workspace, named and finished: a dedicated workspace repo governing several code repos gets its one canonical name (the "External" label retires; no hub/spoke vocabulary); the placement decision rule states both recorded arms; the context carve-out covers repos gated by independent verifiability; Affected areas may carry a Commands-sub-heading context prefix (one context per task; checks.yaml comment only); future-cli states multi-repo as composition of the per-repo contracts | New (multi-repo) — refines 0050, 0060, 0062, 0072 |
| 0074 | The repo family realized: the producer workspace moves to corpus-works (the family's multi-repo workspace — this repo and corpus-cli carry the code-repo footprint; accepted decisions still land in docs/adrs/); the optional guides move to the corpus-skills catalog (Agent Skills format, installable piecemeal; the kit keeps the three core guides, advanced/ keeps templates + cards; docs/library/ retires); the dev subset shrinks to implementation-side guides | New (family) — refines 0064, 0069, 0073 |
| 0075 | The starter kit is its own template repo; essential guides ship installed: starter-kit/ leaves this repo for corpus-starter-kit (copy-whole at repo root; kit content edited there, rules canon here); the eleven workspace authoring guides (write-audit, write-research, write-rfc, write-prd, write-bug-report, write-change-plan, write-inventory, spec-check, split-work, save-findings, adversarial-review) ship in the kit's .agents/skills/; the catalog keeps the six personas + empirical-proof (persona set since narrowed to the cross-cutting trio by 0093) + the code-depth guides and gains the skill-design research layer under docs/ | New (family) — refines 0064, 0069, 0073, 0074 |
| 0076 | Worker-provenance surface + the adoption-experience conventions: the task packet's ## Run summary gains an optional, risk-scaled Provenance line (sources read, guide(s) loaded, worker identity, isolation mode) for delegated/worker-run tasks; the review packet gains a missing-boot-provenance exception trigger and a task-status checkpoint (board and the packet's own status:); docs point to the canonical Fail/Blocked rule (no restatement), add rare-state/precondition/diagnostic-runtime + commit-hygiene + runtime-isolation + workspace-version-control conventions; placeholder-in-a-live-file is a checklist failure. From CHANGE-adoption-experience (codex/kimi field evidence), itself adversarially reviewed | New (adoption) — extends 0072; honors 0057, 0063; cross-links 0060, 0062 |
| 0077 | corpus-cli is a reconcile-only harness of composable parts: it prepares/launches/reconciles agent runs, never performs the coding loop. Three layers (reconcile-only core library · standalone primitives · corpus-composed supercharge); every command a well-behaved Unix part (--json, exit 0/1/2, --no-workspace, corpus-* PATH-plugins); a canonical adapter event contract (init/assistant/tool_call/result, versioned); supercharge = MCP server + hook generation (enforcement BY the agent CLI) + launch-envelope provenance + diff-vs-self-report reconciliation + deterministic coverage/drift + gated close. No corpus ir.json/plan.json artifact — the IR is tool-internal, optional --json only (Option A). Boundary: never the model loop, sandbox runtime, or the review verdict. Derived fresh from research + corpus principles — the future-cli sketch and SOL-era specs are suggestive priors, not inherited. From RFC-corpus-cli-vision (accepted) | New (corpus-cli) — reframes [future-cli] as suggestive; refines 0054; builds on 0072, 0076; honors 0057, 0063 |
| 0078 | C002 (duplicate-id) exempts draft specs from cross-spec requirement-id reuse: the second clause (no requirement id reused across specs) exempts draft specs only and applies to every non-draft spec (ready, done, …) — a draft's stub ids (a fresh scaffold's AC-001) are not finalized claims; frontmatter-id: uniqueness still applies to every file. Surfaced by dogfooding corpus-cli against the real starter kit. | New (checks) — clarifies 0066; honors 0063; requirement-id carve-out subsumed by 0080 (the cross-spec requirement-id clause is dropped; ids are spec-scoped); the frontmatter-id: clause and the draft-is-not-final principle survive |
| 0079 | C012 (coverage): mint the deterministic review-coverage check at warning severity, keyed on the review packet — every in-scope requirement id from a non-draft source spec appears as exactly one coverage row (uncovered), and no row names an absent id (orphan); coverage keys on the task's declared scope. The mechanically defensible wedge ADR-0077 Decision 7 names; absorbs 008-trace's claim→evidence reconcile. Scope-guarded to non-draft specs (mirrors [0078]); warning is deliberately conservative for a new check (teams may block by policy; a future ADR may promote it). Bumps the contract 0.4.1 → 0.5.0; the checks.yaml/checks.md edit + corpus-cli implementation land coordinated (the drift guard). | New (checks) — enables SPEC-corpus-cli-m2-review; builds on 0077, 0078; honors 0063 |
| 0080 | Requirement ids are spec-scoped, not workspace-global. A bare AC-NNN is unique only within its spec (C001); it may recur across specs; a cross-spec reference qualifies as SPEC-x#AC-NNN. C002 keeps only its frontmatter-id: uniqueness clause — its cross-spec requirement-id clause is dropped. Resolves the question 0078 left open (and subsumes its draft carve-out for requirement ids); surfaced by dogfooding (corpus check was red on every spec numbering from AC-001). C002 id/name/severity unchanged → no contract-version bump. | New (checks) — supersedes part of 0078; honors 0063 |
| 0081 | Re-adopt the kit provenance stamp (narrow reversal of 0050 §6). The kit carries a machine-readable VERSION; corpus init stamps .agents/.corpus-version in the new workspace from it — a provenance pin (which kit version this workspace was copied from), turning ADOPTING's manual watch into an exact local-vs-CHANGELOG compare. 0050 §6's premise ("nothing reads it") is now false (corpus-cli reads the workspace, 0077). Provenance pin, not a staleness check — corpus check has no honest "latest" source yet (network breaks hermeticity; a pinned constant goes stale), so the behind-latest warning is explicitly deferred to a future evidence-backed ADR. No checks.yaml rule, no contract-version bump. | New (kit/cli) — narrowly reverses 0050 §6; honors 0063, 0077 |
| 0082 | Platform constraints: an advisory rule, not a new core section. Quota/permission/rate-limit/runtime research is served by spec writing-rule 11 (lift an unknown limit into Open questions, bind a known one as a requirement + Verify with:, record an unhandled one as a Non-goal) + a change-plan Review-focus note — no new heading, no frozen-format change. ADR-0076 already owns the runtime-hazard half. A spec/change-plan section was rejected (redundant with Open questions); a standalone advanced/platform-constraints.md input doc is the deferred, demand-gated escalation. | New (docs) — builds on 0076; honors 0063 |
| 0083 | The structured-evidence format: bind a requirement's named Verify command to its recorded result. An optional fenced verify block, sibling to the coverage row and keyed to the requirement id, carries the named command (cmd="…") and a closed-value result (pass/fail) in its info-string; the fenced body stays verbatim, unparsed, self-reported. The closed-value form lets a checker surface a consistency fact — the recorded evidence names the requirement's own command and a pass — hard-checkable only on the structured form; a free-form-only Evidence cell stays a warning (command-in-prose matching is fuzzy, [SMELLS]). Surfaces a fact, never a verdict (0077 D8); moves the form/truth boundary without dissolving it (the body is self-reported and unparsed — recorded as run-and-passed, not proven). Toolable in prose, never enforced. Decides mint C013 (not strengthen C012); the C-id mint, the 0.5.0 → 0.6.0 bump, and the kit/cli derivations are the W4 deliverable, not W2. | New (checks/docs) — builds on 0077, 0079; honors 0063, 0080 |
| 0084 | Boundary-safe prepare verbs; narrow the board-mutating close to scaffold-only. corpus pull <ref> writes one verbatim intake snapshot (never a spec); the finding scaffold corpus promote writes one candidate finding (never the board, never asserting a learning) — both prepare engines (0077 D1, toolable). The board-mutating close stays parked (the open DECIDE #1.2): no corpus-cli command writes status.md (a boundary regression test asserts it), narrowing D1's enumerated "gated close" to scaffold-only; a board-mutating close needs its own future ADR. No checks.yaml/contract change. | New (cli) — narrows 0077 D1, reaffirms D8; honors 0063 |
| 0085 | corpus-mcp adapts the CLI's --json contract (shells out), not the core library. The corpus MCP server (corpus-mcp, a sibling package) is a thin stdio adapter that spawns corpus <cmd> --json with fixed args and reshapes the output — it does not import corpus-cli's Core. Coupling is only through the public, tested --json interface (footprint isolation — the MCP SDK's ~16 deps stay out of corpus-cli's 2; "many libraries, nothing entirely depends on anything else"; parse-in-one-place with a zod drift tripwire). corpus-cli grows an independently-useful corpus show … --json read family to feed it. Reconcile-only holds end to end (no verdict, no write). Reverses ADR-0077's "reuse the core library without shelling out" sketch. | New (cli/mcp) — refines 0077 D1a, reaffirms D8; honors 0063 |
| 0086 | Deterministic review scanning is the shipped reconcile wedge. corpus review already reconciles coverage/C012, verify-binding/C013, scope drift, run-summary↔diff mismatch, empty-evidence Pass, and packet structure — verdict-free (0077 D8) — so two strategy reports are a decision/measurement/positioning agenda, not a build list. Accept C014 do-not-change-touched (warning; the one in-boundary new fact — ## Do not change is required but unread, missed by outsideScope when the protected file is inside Affected areas; bumps the contract 0.6.0 → 0.7.0). Accept the review-gate benchmark as the gating next investment (precision and recall; doubles as the corpus-mcp real-world test). Defer behind a measure-first gate: SARIF/JUnit import-and-correlate [SARIF], a mechanical risky-path matcher, project-policy config. Reject as non-goals: corpus verify executing commands (crosses D8 + the 2-dep footprint), per-language analysis adapters (the refuted architecture bet), a rival SCOPE-/RISK- id namespace (forks the C0xx contract), a corpus scan verb (a rename of corpus review), the "Agent Work Protocol" coinage. Correct the precision target to ≤10% effective false positives [GOOGLESA] (not the reports' <30%). Re-grounds the differentiation onto four properties (deterministic · local-spec-keyed · verdict-free · git-durable) now that CodeRabbit/Qodo ship acceptance-criteria binding [CODERABBIT-PRVAL] [QODO]. | New (checks/docs/cli) — refines 0077 D7/D8, builds on 0079, 0083; honors 0060, 0063 |
| 0087 | Mint C015 citation-resolves. A spec's inline [[KEY]] citation that does not resolve to an <a id="KEY"> anchor in the workspace's sources.md is surfaced (warning, toolable) — closing the gap 0086/#29 found (the load-bearing "citations are contextual" rule had no checker; a dangling [[FAROS2025]] shipped green). Pure check + an injected anchor_resolves (mirrors C009); skips when no sources.md is resolvable (no false-flag). v0 = dangling-anchor only; the tier checks (a MUST-claim citing a Caveated/Rejected entry) defer to v1. Measured before shipping: 0 warnings over the real corpus-works specs + fires on a seeded fixture. Bumps the contract 0.7.0 → 0.8.0 across the two-repo set. | New (checks/docs/cli) — surfaces a fact not a verdict (0077 D8); toolable not enforced (0063); the 0086+C014 mint precedent |
| 0088 | Delegation provenance: a reviewable trace when an agent delegates to a subagent. A neutral, frozen contract (worker · reason · inputs · filtered · tools · could_edit · evidence) with two runner-specific producers — corpus run's run-record (the D1 extension) and a Claude Code SubagentStart/SubagentStop hook recipe, because in-session subagents bypass the CLI. A record, never a verdict (0077 D8); convention-first — no check, no contract bump this cycle (0063). Extends 0076 + the future-cli run-record form; from corpus-works #43 / RFC-delegation-provenance. | New (canon → cli/kit) — extends 0076, honors 0077 D8 + 0063 |
| 0089 | The decision handoff: an ## Open decisions review-packet section that frames an open decision for the human. A developer orchestrating many deep agents is context-poor at decision time; the agent that did the work frames the fork instead of dumping bullets. Optional section, present only when a decision is genuinely open: the decision · 2–4 comparable options (the case for and against) · a recommendation + a brief why · the context/impact · what it blocks. Routes a decision to the human — a fact, never a verdict (0077 D8); convention-first — no check, no contract bump (0063, the 0088 precedent). Evidence-grounded but honestly hedged: over-trust [OVERRELIANCE-REVIEW] and algorithm aversion [ALGOAVERSION] are the failure modes; a light forcing function beats more justification [OVERTRUST-CFF]; option count is not the lever [CHOICEOVERLOAD]; the options-over-recommendation stance is a contested position paper [EVALAI], reducing over-reliance but not proven to fix calibration [RELYORNOT]. From the owner's 2026-06-20 decision-handoff preference + a /deep-research run. | New (canon → kit) — extends 0060, honors 0077 D8 + 0063 |
| 0090 | C015 tier-checks stay deferred — no high-precision form exists pre-measurement. Resolving the v1 ADR-0087 D4 deferred: (a) the Rejected case is already covered — rejected entries carry no <a id> anchor (verified: zero), so a [[KEY]] citing one already dangles and C015 v0 surfaces it; recorded as an invariant in sources.md (don't anchor a rejected entry) — a high-precision safeguard with zero new code. (b) The Caveated-MUST case needs a fuzzy MUST-claim detector that likely exceeds the ≤10% effective-FP bar [GOOGLESA] — so it stays a review-checklist item until corpus-bench measures a structural signal. No check, no contract bump. | New (canon) — refines 0087 D4; honors 0063, 0086 D3 |
| 0091 | corpus update: a reconcile-only kit refresh — ship --check, defer the merge. Reopens 0081's deferral for the explicit-update case only: the network-touching corpus update --check reads the .agents/.corpus-version pin, resolves the kit via the same source as corpus init (clone / --from), reads its VERSION, and reports drift + the CHANGELOG delta — exit 1 behind / 0 clean / 2 error, writes nothing. The network lives in update, not in hermetic corpus check (what ADR-0081 lacked). The 3-way line-merge stays deferred — the precedent's merge is abandoned-on-conflict (Dumont 2025) and the kit's edit-the-files onboarding makes conflict the common case. Update (2026-06-22): --write shipped (corpus-cli 4536fc7) — but as a scoped conflict-safe copy of the kit-owned guidance (templates/, .agents/skills/, advanced/, hooks/), --on-conflict backup/overwrite/skip, never the user's content and never a line-merge; the deferred merge is still not built. Toolable, not enforced (0063); reconcile-only (0077 D8). From corpus-works #12 / RFC-corpus-update. | New (canon → cli) — reopens 0081 narrowly; honors 0077 D8 + 0063 |
| 0092 | corpus-agents: a Claude-Code-first member of self-contained, useful worker definitions — records, never an executor; toolable-not-enforced. Founds the family member that ships Claude Code worker definitions for corpus roles (read-only corpus-reviewer/-explorer/-evidence-checker/-challenger; bounded-authoring corpus-spec-author/-researcher/-auditor/-documentarian), the producer-2 delegation hook, and a read-only-guard hook. Agents are self-contained and useful (persona-OPTIONAL; grounded in canon ADRs, not in the unaudited personas). Two honesty tiers: read-only scoping is toolable/partial (defeasible — inherit-all default, parent permission modes, plugin subagents ignore hooks, claude-code#25000); authoring is discipline+isolation+trace — nothing labeled "enforced" (0063). A record never a verdict (0077 D8). Founding is a conscious override of the unmet measure-first gate ([FINDING-delegation-provenance-measurement]), conditioned on a post-ship measurement wave. Supersedes only ADR-0088's producer-2 destination (hook home → corpus-agents); 0088's body stays intact. From corpus-works #43 / SURVEY-corpus-agents-shipping. | New (canon → corpus-agents/kit) — supersedes 0088's producer-2 destination; honors 0077 D8 + 0063 |
| 0093 | Collapse the 1:1 authoring personas; the catalog ships only cross-cutting stances. The kit work guides already fold in each stance's substance (0064), so the four personas that map 1:1 to one guide (persona-architect/-auditor/-researcher/-documentarian) were a redundant second carrier that had drifted into a third copy. Remove them — each discipline keeps its single canonical carrier, the folded form in its kit guide. The catalog keeps only the genuinely cross-cutting stances (persona-skeptic/-challenger/-surveyor) + empirical-proof, rebuilt grounding-first (the lever is external grounding, not the attitude — [SELFCORRECT]). Identity adds no measured gain ([ZHENG-PERSONA]); role framing helps via the procedure it evokes ([KONG-ROLEPLAY]). From RESEARCH-personas-as-skills. | New (canon → catalog/kit/website) — refines 0042 + 0064; honors 0063 |
| 0094 | Decomposition into small untangled units; review scrutiny weighted by diffusion/churn/change-type. Makes small, single-concern, untangled, refactor-separated the primary task-decomposition rule (convention), names an oversized-packet heuristic as a corpus-cli toolable (changed-LOC + files-touched, anchored to the [SMARTBEAR] 200–400 LOC heuristic; specified-not-shipped), and reframes greenfield↔brownfield as risk-weighted review by change-type/diffusion/churn with the Hindle caveat (net-new is not intrinsically safe once size is controlled — [HINDLE11]). Splitting is sold as cleaner reviews, not more bugs caught ([DIBIASE19]). Nine sources web-verified. From corpus-works #53. | New (canon → docs/kit) — honors 0063; the oversized-packet check is a corpus-cli follow-up (corpus-works #61) |
| 0095 | Ground the review model in evidence. Review's primary payload is the maintainability/design layer tests cannot reach (~75% of review findings are evolvability, [MANTYLA09]; defect comments ~14%, [BACCHELLI13]) — complementary to tests, not a substitute. Reviewer ≠ author as a desk-checking design rationale ([WIEGERS95], reinforces 0056); default two distinct-lens reviewers + a risk-based third ([RIGBY13]); participation is the gate — an empty-evidence Pass reads Unverified ([MCINTOSH14]; the already-shipped reconcile, refining #52's "Blocked"); agent-runs-the-app is evidence, not a verdict ([GPTDROID]/[WEBAGENTILLUSION], deterministic accessibility-tree tooling [PLAYWRIGHTMCP]). Eight sources web-verified. From corpus-works #52. | New (canon → docs/corpus-agents) — honors 0063, reinforces 0056; no format change (0058/0089 stand) |
| 0096 | Artifact lifecycle at scale. A durable-vs-ephemeral split (decisions/specs/findings persist + supersede-not-delete; review/check/run output ages out to git history or archive/ on a 30–90-day window — [NARAGRS52]/[ISO15489]/[GHRETENTION]); a stated status + superseded_by pointer lifecycle ([NYGARDADR]/[MADR]) with a specified-not-shipped corpus check that the pointer resolves + the index lists; named ownership + freshness for durable artifacts ([SWEGBOOKDOCS], [DOCROT]); single-sourcing as the anti-duplication control (the dominant failure at scale is duplication, not absence); a generated index/board for discoverability (convention). Seven sources web-verified. From corpus-works #54. | New (canon → docs/kit) — honors 0063; the supersede/index check is a corpus-cli follow-up (corpus-works #61) |
| 0097 | Mint C016 + C017; defer the oversized-packet band (measured). Builds the deferred backlog under measure-before-ship: C016 pass-needs-evidence (hard error) closes the verified B2 gate gap — corpus check <review> now blocks an empty-Evidence Pass (the reconcile path stays advisory, 0077 D8); C017 orphaned-reference (warning) flags a bundled skill reference no SKILL.md names (measured 0-orphan / 6 references). The oversized-packet band (0094) is specified-not-shipped — measured ~15% FP at 600 LOC on real code task diffs (feature-with-tests shares the 600–1200 LOC range), so a raw band can't be useful and low-FP; the diff size ships as neutral info instead. Contract 0.8.0 → 0.9.0. From the NOTHING-DEFERRED backlog clearance (corpus-works #61 §B; #50, #45). | New (canon → cli) — honors 0063 + 0086; resolves the 0094/0096 toolables |
| 0098 | Portability: ship a Codex emitter + the universal AGENTS.md discipline; drop Antigravity. Narrows 0092's hold-until-2-runners gate: the second runner (OpenAI Codex, file-based .codex/agents/*.toml) is real, so corpus agents emit --codex (corpus-cli) generates the Codex form from the single-source agents/*.md — reuse, not duplication. The shared discipline (ADR-0056/0077/0088/0063) is single-sourced in corpus-agents' AGENTS.md, the open cross-tool format; the per-worker files are its Claude-Code specialization (no hand-duplicated SKILL.md). Enforcement does not travel — the tools allowlist + hooks are Claude-Code-only; every emitted file says so. Antigravity dropped (managed agents are programmatic, no file target). The value-measurement wave (≥2 real runner teams) stays the honest exception. The emitter is a runner adapter → corpus-cli's Workspace leaf, not Core. Toolable. From the NOTHING-DEFERRED clearance. | New (canon → cli + corpus-agents) — narrows 0092; honors 0063 + 0077 |
The new kernel ADRs (0027+), by topic
The initial rework introduced sixteen ADRs (0027–0042); four follow-on decisions (0043–0046) refine the installable kernel's shape and are covered below and in the ledger above. Of the initial sixteen, the nine the spec enumerates as mandatory kernel decisions (§30.3) record decisions that must not be left implicit in prose:
| ADR | Records | Spec |
|---|---|---|
| 0027 | SOL is the single home of obligation semantics | §5, §6 |
| 0028 | APS is the controlled-prose standard around SOL | §7 |
| 0029 | author → lint → improve → lower → decompose → implement → verify → review → promote | §9 |
| 0030 | the kernel artifact set incl. trace, VERDICT block, finding, memory | §20, §29 |
| 0031 | domain axis × artifact axis, lexicographic | §22 |
| 0032 | two-tier, provenance-anchored promotion | §23 |
| 0033 | positive + negative conformance fixtures over the three domains | §33 |
| 0034 | one prefix, five layers; APS violations surface under the SOL- prefix, not a separate APS- code prefix | §8 |
| 0035 | 4 core + 3 lifecycle verdicts | §14 |
The remaining seven carry the Group-B recasts, the kernel-rename/versioning extensions, and the skill-carrier packaging refinement: 0036 (profiles, §27), 0037 (loading doctrine, §26.4), 0038 (the VERIFY BY/Commands binding, §15/§31.3), 0039 (the write-surface, §18/§19), 0040 (the starter-kit/ payload, §20.5/§34), 0041 (two-axis versioning, §25), and 0042 (skills carry as SKILL.md + standalone surgically-activated conditioning, §26/§27; refines 0016, 0017, 0019, 0029, 0036, 0037).
The kernel spec required a conformant repo to carry these ADRs (or equivalents) so the chain would explain why the obligation language, prose standard, pipeline, artifact set, authority model, memory, corpus, lint namespace, and verdict set had their shape — historical context; the current validity bar is the one in checks (per 0066).
0043 is proposed / parked — it records a direction (keep obligation-blocks spec-only; give other agent docs a subtractive, deterministic, advisory check surface) but builds no lint rule and changes nothing in the live lint pass. It is design intent, not an in-force decision; its backlog plan was retired with the practical-first repositioning (see git history).
0044 settles the shape of the installable payload: docs/ is the single canonical source for the language/ and passes/ twins and the kernel is a derived, checked, self-contained copy that resolves offline (no §N/Appendix-X refs to unshipped documents, no links into docs-only trees). The kernel is derived by mechanical rewrites (strip citations/§-refs, rewrite links to resolve offline) and kept honest by an eyeball-diff on edit + a grep-based coherence gate — refining the kernel-payload decision (0040). The one-time reconciling merge it authorized (the K2 work) is done.
Ready to run the loop on your own repo? Get started — copy the kit and write your first spec.