manual page/ ADRs
Architecture Decision Records
- Sections
- 3
- Format
- Markdown
- Order
- 38 / 156
Most users do not need to read these. ADRs document why Suspec 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 fixture set (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 fixture set | New (kernel) — §33; refined by 0065; suspec 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 | 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 | 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 outside the replaceable kernel payload | Superseded by 0049 — no overlays dir; conventions live in AGENTS.md |
| 0046 | A task implementing a spec gets a worktree+branch; ad-hoc work stays in-place | New (kernel) — §18; refines 0039; operationalizes 0010 |
| 0047 | Skills are self-contained; citations are provenance, not a required read | New (kernel, from suspec-cli adoption) — refines 0016, 0042 |
| 0048 | The installed payload is the runtime surface, not the whole kernel | Superseded by 0049 — what to ship survives (skills + reference/ cards + templates), but it installs in place, not into a .suspec/kernel/ mount |
| 0049 | Minimal install — .agents/, no mount, a small flow-based folder set | New (from suspec-cli adoption skeptic review) — supersedes 0045, 0048; refines 0040, 0044; depends on 0047; flow folders shipped pre-built per 0069 |
| 0050 | Suspec is a spec-repo discipline; the code repo stays pristine | 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 spec-repo pivot — one authoring kit, specs top-level, code skills as reference | 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 — per-feature spec folders, one decisions/, memory for recall | New (cohesive scaffold, grounded) — refines 0051, 0050; aligns with 0032, 0043; partially superseded by 0060 (hybrid workspace layout) |
| 0053 | Suspec is a structured specification & review system (review-as-exceptions) | 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 | Drop the residual compiler vocabulary (complete the de-cosplay) | 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 (empty-set coverage, adequacy gating for high-RISK, uncovered-bug amendment) | 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 | New (dogfooding) — refines the implement step + persona-skeptic + the working rules; reaffirms 0053's independence; grounded by REFLEXION |
| 0057 | Practical-first repositioning and the six-step loop | New (repositioning) — refines 0053, 0054, 0029; supersedes the naming clauses of 0049 §2 |
| 0058 | Two-tier spec format, one data model | New (repositioning) — supersedes the spec-file clauses of 0041/0015; partially supersedes 0027, 0028 |
| 0059 | Frontmatter type: is the sole artifact discriminator | New (repositioning) — supersedes the infix-partition model; refines 0030, 0054 |
| 0060 | The Suspec Workspace: hybrid layout, committed flow artifacts, the review packet | New (repositioning) — supersedes 0004; partially supersedes 0052; refines 0049, 0050, 0032; layout shipped pre-built per 0069 |
| 0061 | The intake artifact and the Pull step | New (repositioning) — refines 0030; partially supersedes 0053's intake deferral |
| 0062 | Code-repo adapter: pristine today, gitignored CLI state when a CLI exists | New (repositioning) — reaffirms 0049, 0050 |
| 0063 | The honesty framework and the tooling boundary | New (repositioning) — refines 0023, 0026, 0034, 0043, 0055 |
| 0064 | Minimal starter kit: core copy surface, advanced tier, focused guides | New (repositioning) — partially supersedes 0019, 0002, 0009; refines 0042, 0036, 0047, 0056; adoption framing superseded by 0069 (kit copied whole) |
| 0065 | Three flagship examples; the large-PR review is the demo | 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: the adopter validity bar and the producer-internal reference values | 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: findings first, the heavier machinery as an advanced model | New (repositioning) — refines 0032 |
| 0068 | Inventory and Change Plan: the transformation tier | New (repositioning) — partially supersedes the per-kind routing clauses of 0029, 0042; refines 0030, 0046 |
| 0069 | The starter kit is a workspace, copied whole | New (scaffolding) — refines 0064 (copy-checklist framing superseded by copy-the-folder), 0060, 0049 |
| 0070 | checks/ is the home of the checks contract | New (scaffolding) — completes 0054's register sweep at tree level; refines 0066 |
| 0071 | Step bars: the per-step quality bars are product reference | New (scaffolding) — supersedes the standalone evals surface; refines 0065, 0066 |
| 0072 | The run summary digest and the DX format amendments | New (DX remediation) — partially supersedes 0060 (run-record addendum clause); refines 0064, 0066, 0070, 0063 |
| 0073 | The multi-repo workspace, named and finished | New (multi-repo) — refines 0050, 0060, 0062, 0072 |
| 0074 | The repo family realized: producer workspace and skills catalog | New (family) — refines 0064, 0069, 0073 |
| 0075 | The starter kit ships as its own template repo; essential guides ship installed | New (family) — refines 0064, 0069, 0073, 0074 |
| 0076 | Worker provenance surface and the adoption-experience conventions | New (adoption) — extends 0072; honors 0057, 0063; cross-links 0060, 0062 |
| 0077 | suspec-cli is a reconcile-only harness of composable parts | New (suspec-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 | 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 | New (checks) — enables SPEC-suspec-cli-m2-review; builds on 0077, 0078; honors 0063 |
| 0080 | Requirement ids are spec-scoped, not workspace-global | New (checks) — supersedes part of 0078; honors 0063 |
| 0081 | Re-adopt the kit provenance stamp (narrow reversal of ADR-0050 §6) | New (kit/cli) — narrowly reverses 0050 §6; honors 0063, 0077 |
| 0082 | Platform constraints are an advisory rule, not a new core section | New (docs) — builds on 0076; honors 0063 |
| 0083 | The structured-evidence format: binding a requirement's named Verify command to its recorded result | New (checks/docs) — builds on 0077, 0079; honors 0063, 0080 |
| 0084 | Boundary-safe prepare verbs; narrow the board-mutating close to scaffold-only | New (cli) — narrows 0077 D1, reaffirms D8; honors 0063 |
| 0085 | suspec-mcp adapts the CLI's --json contract (shells out), not the core library | New (cli/mcp) — refines 0077 D1a, reaffirms D8; honors 0063 |
| 0086 | Deterministic review scanning is the shipped reconcile wedge: accept C014, gate the measurement track, reject the off-boundary asks | New (checks/docs/cli) — refines 0077 D7/D8, builds on 0079, 0083; honors 0060, 0063 |
| 0087 | Mint C015 citation-resolves: the inline [[KEY]] anchor check (toolable, fact-not-verdict, measured before shipping) | 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 (neutral contract, runner-specific producers, fact-not-verdict) | New (canon → cli/kit) — extends 0076, honors 0077 D8 + 0063 |
| 0089 | The decision handoff: an ## Open decisions section that frames an open decision for the human (convention, fact-not-verdict, evidence-grounded) | New (canon → kit) — extends 0060, honors 0077 D8 + 0063 |
| 0090 | C015 tier-checks stay deferred: no high-precision form exists pre-measurement; the Rejected case is already covered by an invariant | New (canon) — refines 0087 D4; honors 0063, 0086 D3 |
| 0091 | suspec update: a reconcile-only kit refresh — ship --check, defer the merge | New (canon → cli) — reopens 0081 narrowly; honors 0077 D8 + 0063 |
| 0092 | suspec-agents: a Claude-Code-first member of self-contained, useful worker definitions (records, never an executor; toolable-not-enforced) | New (canon → suspec-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 | New (canon → catalog/kit/website) — refines 0042 + 0064; honors 0063 |
| 0094 | Decomposition into small untangled units; review scrutiny weighted by diffusion, churn, and change-type | New (canon → docs/kit) — honors 0063; the oversized-packet check is a suspec-cli follow-up (suspec-works #61) |
| 0095 | Ground the review model in evidence: maintainability-first value, independent distinct-lens reviewers, participation as the gate, agent-runs-the-app as evidence | New (canon → docs/suspec-agents) — honors 0063, reinforces 0056; no format change (0058/0089 stand) |
| 0096 | Artifact lifecycle at scale: durable-vs-ephemeral records, status + supersede, retention, freshness, and anti-duplication | New (canon → docs/kit) — honors 0063; the supersede/index check is a suspec-cli follow-up (suspec-works #61) |
| 0097 | Mint C016 (pass-needs-evidence) + C017 (orphaned-reference); the oversized-packet band is specified-not-shipped (measured) | New (canon → cli) — honors 0063 + 0086; resolves the 0094/0096 toolables |
| 0098 | Portability: ship a Codex emitter + the universal AGENTS.md discipline; drop Antigravity | New (canon → cli + suspec-agents) — narrows 0092; honors 0063 + 0077 |
| 0099 | Review-lead orchestration, agent role routing, and reviewer ≠ implementer | New (canon → docs/suspec-agents) — refines 0095; reaffirms 0056; honors 0063 |
| 0100 | Spec-external, ops-local: resolve the implementer straddle without committing ops artifacts | New (canon → docs/kit) — extends 0062/0050; reaffirms 0099 |
| 0101 | Open decisions carry options + a recommendation, in decision-bearing authoring | New (canon → kit) — reaffirms 0089, 0058, 0098 |
| 0102 | Lean the artifact surface: intake is an optional pointer; reference material single-sources to docs | New (canon → docs/kit) — reaffirms 0096; from RFC-lean-artifact-set |
| 0103 | The spec is a living form; the task is an on-demand split slice | New (canon → kit) — refines 0058/0030/0079; reaffirms 0056/0099/0100 |
| 0104 | Ephemeral by default: gitignore the working set, commit only durable truth | New (canon → kit) — reverses 0060; amends 0096; builds on 0103 |
| 0105 | Stretch and collapse: the artifact set is a dial, not a set of stations | New (canon → kit) — refines 0064; builds on 0103 |
| 0106 | Keep-clean tooling: make zero-noise structural, not a convention | New (canon) — realizes 0096; composes 0104/0105 |
| 0107 | Fast-track solo review via staleness detection, not an agent verdict | New (canon) — reaffirms 0077 / 0056; reuses the Stale marker |
| 0108 | Living specs: an Active container with per-requirement supersession, kept lightweight | New (canon) — refines 0103/0058/0096; ungates 0106 |
| 0109 | Output economy: a readable, economical agent-output convention (a floor, not a hook) | New (canon → kit) — refines 0057; honors 0063/0077 |
| 0110 | The ## Execution entry is a structured change-record (a durable evidence digest) | New (canon → kit/cli) — refines 0103/0108; extends 0107 |
| 0111 | Kit skills are Suspec concepts; style / stance / depth lives in the catalog | New (canon → kit/catalog) — refines 0064/0075; reaffirms 0093 |
| 0112 | Two-tier skills: a framework-free universal catalog, a Suspec-coupled kit | New (canon → kit/catalog) — refines 0111/0064; reaffirms 0105 |
| 0113 | Citations live in docs, not in products (the product-vs-docs boundary) | New (canon → all repos) — refines 0111/0112; honors 0063 |
| 0114 | A retired/relocated-artifact registry + cross-repo reference linter | New (canon) — accepted — references 0112 |
| 0115 | Synced workspace catalogs must be links or freshness-gated (no orphaned copies) | New (canon → kit/works) — refines 0064 |
| 0116 | Shipped-spec invariant + status/spec coherence check | New (canon → cli) — accepted — refines 0108/0110 |
| 0117 | No count-bearing ranges in bootstrap/reference prose — link-only pointers | New (canon) — single-sourcing corollary; relates 0108 |
| 0118 | Numeric/adoption claims must be ground-truthed by live query, not voted from recall | New (canon → workflows) — honors 0063 |
| 0119 | Independent review is the invariant; the formal review is risk-weighted | New (canon → docs/site) — refines 0094; relates 0056/0105 |
| 0120 | Re-baselining: reconciling when reality has drifted from the artifacts | New (canon) — extends 0068/0103/0108; relates 0096/0116 |
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, suspec, 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.
Starter kit: Set up a workspace