Architecture Decision Records (ADR)

For humans. This is the project's governance-facing log of significant, durable architecture decisions — one decision per entry, with its rationale and the trade-offs it accepts. It is read on demand, not part of the per-session agent read path, so it adds zero default token cost (the same footing as docs/DESIGN-*.md). Proposals are not ADRs: work under consideration lives in the sibling register RFC.md (RFC-NNNN, its own sequence) and reaches this ledger only on acceptance (v4.41.2).

What an ADR is (and is not)

An ADR records why a load-bearing architectural choice was made — the kind of decision that is expensive to reverse and that a newcomer or auditor needs the reasoning behind. It is the Design altitude of the VBDI loop made durable (docs/DESIGN-vbdi-lifecycle.md §4): Current State → Vision → Blueprint → Design → Implementation → Feedback.

Map, don't duplicate. The live constraint text stays in memory/continuity.md (## Architectural Invariants / ## Key Decisions) — that is the what that holds now, carries an id, and is read every session. An ADR is the durable why: context, alternatives, and consequences. They cross-link: formalizes: here points to the continuity id, and each invariant/decision carries a visible (ADR-NNNN) tag in its title (a pointer for humans — not a cue for the agent to open this file). The constraint is never restated as competing truth.

Lifecycle (mirrors DECAY.md §9)

• Status: Accepted → Superseded / Deprecated. An entry is written only when a decision is accepted (v4.41.2); work under consideration would live in a sibling RFC.md register with its own RFC-NNNN ids, never here as Proposed — a withdrawn proposal has no honest ledger status.
• Never deleted. A decision that no longer holds is superseded (replaced by a newer ADR) or deprecated (no longer relevant, not replaced) — the old entry stays in place, its Status updated. History is the point.
• To supersede: add a new ADR, set the old one to Status: Superseded by ADR-NNNN, and the new one to Supersedes: ADR-NNNN.

Format

## ADR-NNNN — <Title>
**Status:** Accepted · **Date:** YYYY-MM-DDThh:mm:ss.mmmZ · **Serves:** <vision-id>
<!-- id: adr-NNNN | status: accepted | formalizes: <continuity-id> -->

**Abstract.** One paragraph: what was decided and its scope.

**Rationale.** Why this, why now, the alternatives weighed, **and the consequences /
trade-offs** the decision accepts.

• Numbering is monotonic (ADR-NNNN); entries are listed newest first.
• Date is the persist-time UTC ISO 8601 stamp (the session-log convention) at the moment the decision is recorded.

Seed note. ADR-0001…0006 below were seeded 2026-06-20 from the five standing ## Architectural Invariants in memory/continuity.md, plus the superseded no-code-markdown-only decision (ADR-0004, now archived) that ADR-0006 replaced; each Date is the original decision date (day granularity — the precise instant predates this log).

---

ADR-0009 — The governance pair is an opt-in seed: offered once, never imposed (the optional policy)

Status: Accepted · Date: 2026-09-18T23:50:01.095Z · Serves: vision-agent-memory

Abstract. The tool ships sample docs/arch-decisions/ADR.md and RFC.md skeletons, but installs them only when a team asks: a seventh MANIFEST policy, optional, whose row is copied only on an explicit --adopt <target>, is never touched when present, and is listed for reference when absent without ever counting as pending work. The fresh enable offers the pair once (ENABLE.md Step 10); an upgrade never re-asks. Governance is offered, never imposed.

Rationale. Two field repos had adopted an ADR ledger by hand, so a canonical starting shape has real demand — but the ledger is documented as opt-in and the Vision names "never heavyweight" as a non-goal. The obvious mechanism, a seed-copy row, was rejected: it installs the pair into every enabled repo, and because seed-copy copies whenever the target lacks the file, it re-offers the pair on every upgrade after a team deletes it — the "deliberately absent" hazard RFC-0002 records from the waiver-file incident. Alternatives weighed: seed-copy (fast, but ceremony everywhere and re-offers after deletion); no templates at all, with the tool's own files as the reference shape (leaves every adopting team to copy and generalize by hand); an optional policy scoped to guidance-only seeds (chosen — it is RFC-0002's option (b) made concrete, and the pair is its first use). Design points: --adopt is explicit and repeatable, a dir/ prefix adopts every optional row under it, an unmatched path is refused, and absent optional rows are excluded from the pending count so convergence is unaffected. The skeletons are project-neutral with no placeholders, so the mechanical copy is complete. Trade-offs: one more policy for operators to know, a [notes] line per unadopted row on every dry-run (reference, by design), and the question of which existing seed-copy rows should migrate to optional is deliberately left open in RFC-0002. Proposed as RFC-0005 and promoted at the maintainer's gate once the design was implemented.

ADR-0008 — The ADR ledger records decisions only; proposals live in the RFC register

Status: Accepted · Date: 2026-09-18T23:20:13.067Z · Serves: vision-agent-memory

Abstract. An entry is written into this ledger only when a decision is accepted. Work under consideration lives in the sibling register RFC.md, with its own RFC-NNNN sequence; a proposal does not reserve an ADR number, and it resolves either by promotion (the ADR is written and the register keeps a pointer) or by withdrawal (recorded with the reason). Nothing here ever carries a Proposed status. Superseded/Deprecated handling is unchanged — that is the post-decision stage.

Rationale. A ledger's value is that it is an immutable journey of decisions: a reader can tell what the project committed to, and when, without checking each entry's status. The prior guidance ("propose a newer ADR … and wait for human approval") named only this file, so a literal reading wrote non-decisions into the decision record. In the field (mercury-composable, 2026-09-18) five ADRs sat at Status: Proposed for a month for decisions that had already shipped, and a withdrawn proposal had no honest status at all — Superseded implies a successor, Deprecated implies it was once in force. Alternatives weighed: keep Proposed inside the ledger and rely on discipline to flip it (the field-tested failure: nothing in the protocol says to come back); no register at all, with proposals living only in conversation and Open Threads (loses the reasoning — options and trade-offs — that a later reader needs to judge a decision, and gives a reshaped proposal no place to be revised); a register named by the repo (chosen as the portable form: the protocol mandates the rule, not the filename, and names RFC.md only as the example). RFC- over P- because it is the industry-recognised marker for a design proposal open to comment and the RFC → ADR pairing is the established pattern. Trade-offs: one more on-demand file and two sequences to keep straight; promotion adds a copy step (the accepted form is written into the ledger, the register keeps a pointer). The cost buys the property the ledger exists for. Proposed as RFC-0004 and promoted at the maintainer's gate the same day — the first proposal to travel the path it describes.

ADR-0007 — Git hook entrypoints dispatch ordered fragments

Status: Accepted · Date: 2026-08-20T21:00:47.000Z · Serves: vision-agent-memory

Abstract. The committed .githooks/pre-commit and .githooks/post-commit files are stable, minimal dispatchers. Hook behavior lives in executable .githooks/<hook>.d/* fragments that run in deterministic C-locale filename order. Every fragment runs; the dispatcher returns the first non-zero status. Agent-memory owns only its managed 50- fragments, leaving ordered before/after slots for other hook layers.

Rationale. Single-file hooks made unrelated automation compete for one entrypoint: an install or upgrade could overwrite another layer, and embedded behavior was difficult to exercise in isolation. Alternatives were a shared sourced library (one more load-bearing indirection and shared shell state), stop-on-first-failure dispatch (later independent checks lose their report), or delegating composition to a vendor-specific hook manager (adds a dependency and weakens portability). Executed fragments isolate shell state while preserving Git's native status contract; running all fragments maximizes diagnostics, and returning the first failure keeps the result deterministic. Trade-offs: ordering becomes a filename convention, executable bits are part of the contract, and all pre-commit fragments run even after the commit is already destined to fail. The small cost buys composability, additive upgrades, and direct CI testability without a daemon or third-party manager.

ADR-0006 — No build step; the agent is the runtime

Status: Accepted · Date: 2026-06-16 · Serves: vision-agent-memory · Supersedes: ADR-0004

Abstract. The tool itself runs no code and needs none — no install, no daemon, no build/lint/test step. The markdown files are the product and an AI agent is the runtime. A skill MAY bundle optional helper scripts (e.g. memory-lint), but those are invoked by the agent/vendor at the user's direction — never executed by the tool.

Rationale. Maximizes portability and vendor-neutrality: any agent, on any machine, can read and act on the files with zero setup, and a human can audit the whole system by reading it. This supersedes ADR-0004 (the earlier "no-code, markdown-only" framing), which was too absolute once optional helper scripts appeared — the principle is the tool runs nothing, not no script may exist. Trade-off: the determinism a compiler or test gate would provide must instead come from convention + the optional verifier skills (memory-lint) + human review; correctness leans on the agent reading carefully rather than on a build gate.

ADR-0005 — Upgrades are additive and non-destructive

Status: Accepted · Date: 2026-06-13 · Serves: vision-agent-memory

Abstract. In-place upgrades (Mode B) only enrich and add — never rewrite or delete a user's content — except the tool's own managed built-ins (memory-lint, second-opinion, apply-critique, sync-adapters, harvest-knowledge, archive-fact, refresh-metadata), which are re-copied (overwritten) on upgrade. That overwrite is scoped to tool-owned files; a user customizes a built-in only by forking it under a new skill name.

Rationale. A repo enabled by an older version must be able to move forward safely without losing local customization or history, and idempotent re-runs must be harmless. The built-ins exception keeps the shared verifier/review machinery correct across every enabled repo. Trade-off: the tool must carry a version ladder (UPGRADE.md) and warn-before-overwrite logic for locally-modified built-ins; "additive-only" also means superseded guidance accumulates rather than being deleted — which is exactly what this ADR lifecycle and the memory decay model then manage.

ADR-0004 — No-code, markdown-only (the files are the product)

Status: Superseded by ADR-0006 · Date: 2026-06-13 · Serves: vision-agent-memory

Abstract. The system is no-code and markdown-only: the markdown files are the product and an AI agent is the runtime — no build, lint, or test step, nothing executes.

Rationale. Portability and vendor-neutrality with zero setup, and a system a human can audit by reading it; a CLI / daemon / index-server alternative was rejected as install + maintenance burden and vendor coupling. Superseded by ADR-0006 (2026-06-16): the v4.1.x skills layer introduced optional bundled helper scripts/ (e.g. memory-lint), so the absolute "markdown-only" no longer strictly held. ADR-0006 preserves the intent in refined form — the tool itself runs no code; a skill may carry optional scripts the agent/vendor runs at the user's direction. Consequence: the line moved from "no script may exist" to "the tool executes nothing," keeping the no-install / auditable guarantees while allowing optional, agent-invoked helpers.

ADR-0003 — Never overwrite, never pick a winner

Status: Accepted · Date: 2026-06-13 · Serves: vision-agent-memory

Abstract. When migrating a repo that already has vendor steering, never overwrite and never pick a winner between conflicting rules — fold each vendor's steering under a ## Migrated rules from <vendor> section and surface any contradiction as an Open Thread for a human to resolve.

Rationale. The tool cannot safely adjudicate a team's intent; silently choosing would destroy information and erode trust. Preserving both rules and flagging the conflict keeps the human in control of the resolution. Trade-off: the merged instructions may temporarily hold contradictory guidance until a human closes the Open Thread — the system favors faithful preservation over immediate tidiness.

ADR-0002 — Never delete vendor files; preserve under legacy/

Status: Accepted · Date: 2026-06-13 · Serves: vision-agent-memory

Abstract. Migration never deletes a vendor's original files — it moves them to legacy/<vendor>/, preserving their relative paths.

Rationale. Migration must be reversible and auditable: a user can always see, diff, and recover exactly what they had before enablement. Trade-off: the repo carries a legacy/ tree that is otherwise dead weight — accepted as the price of a non-destructive, trustable migration.

ADR-0001 — Target-repo scope only

Status: Accepted · Date: 2026-06-13 · Serves: vision-agent-memory

Abstract. Every read, modify, move, and list is scoped to the resolved target-repo root. The tool never touches anything outside it — never ~, ~/.claude/, Application Support, AppData, or system paths; symlinks are resolved first and any escaping path is reported, not followed.

Rationale. The user's home directory is their personal AI environment; the repo's memory/ is the team's shared layer. Hard isolation is the core safety guarantee that makes the tool safe to point at any repository. Trade-off: the tool deliberately gives up conveniences that would reach into personal/home config (e.g. syncing a user's global vendor settings) — the safety boundary is worth more than the feature.