@nikovirtala/adr 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niko Virtala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# @nikovirtala/adr
+
+Architecture decision records kept as event logs in git, built on [`@nikovirtala/ledger`](https://www.npmjs.com/package/@nikovirtala/ledger). A decision is a Markdown body plus append-only event files. Its status (proposed, accepted, rejected, withdrawn, deprecated, superseded) is computed from the events, the body is frozen by its hash once accepted, and supersession chains always lead to the decision in force. See the [design doc](https://github.com/nikovirtala/ark/blob/main/docs/01-adr-v1.md).
+
+This is phase 1 ("Core"), released at 0.x: the decision kind, the library and the `adr` CLI with `new`, `accept`, `supersede`, `list`, `show` and `verify`.
+
+## Install
+
+```sh
+npm install --save-dev @nikovirtala/adr   # Node 24 or newer, git 2.32.0 or newer
+npx @nikovirtala/adr --help               # or run it without installing
+```
+
+## Layout
+
+```
+docs/adr/
+  adr.toml                                   # optional config (or adr.toml at the repository root)
+  decisions/k3f9q8a1-use-aurora-for-orders.md
+  events/k3f9q8a1/20261016T081030Z-p4d2-proposed.yaml
+  events/k3f9q8a1/20261016T091512Z-7aq5-accepted.yaml
+  templates/nygard.md                        # copied from the built-in on first use
+```
+
+Each decision has a canonical id (`k3f9q8a1`). Accepted decisions also get a number (`ADR-0001`), assigned in the order their acceptances land on the first-parent history of main and never stored or renumbered. Commands take an id or a number in any form: `k3f9q8a1`, `7`, `0007`, `ADR-7`, `adr-0007`.
+
+## Commands
+
+```sh
+# Propose: render a draft from a template, write the body and the proposed event, and stage them.
+adr new "Use Aurora for orders" --section context="We need SQL." --section scope=services/orders
+adr new "Use Aurora Serverless" --supersedes ADR-0002 --template madr --edit
+
+# Accept: lint the draft, hash the body, and write accepted (plus superseded on each declared target).
+adr accept k3f9q8a1 --commit
+
+# Supersede an accepted decision by another accepted one.
+adr supersede ADR-0001 --by ADR-0002 --reason "Aurora fits the query load" --commit
+
+# Read: list with computed status, show one decision with its state header.
+adr list --status accepted
+adr show ADR-0001 --history
+adr list --ref v1.2.0                      # time travel: the log as of any ref
+
+# Verify the log: the whole tree, a range, or the staged changes (for a pre-commit hook).
+adr verify
+adr verify --base origin/main --format github
+adr verify --staged
+```
+
+- `new` takes `--template <name>` (default `nygard`; built-ins `nygard`, `madr`, `y-statement`, or your own `<root>/templates/<name>.md`), `--section <id>=<markdown>` (repeatable), `--supersedes <decision>` (repeatable), and `--edit`/`--no-edit`. It opens `$VISUAL` or `$EDITOR` with `--edit`, or by default in an interactive terminal; an editor failure never loses your edits and never commits content you didn't confirm.
+- Writes stage their files and don't commit, unless you pass `--commit` or set `auto_commit`. A commit holds every file of the decisions it touches (body, events, template), so `adr verify --ref <commit>` is clean, and never your unrelated staged work. It refuses with exit 2 when a file it needs has unstaged changes or isn't tracked. Its `ADR: <id>` and `ADR-Event: <type>` trailers name one event each, in a fixed order, whatever your `trailer.*` config.
+- `show` leads with a state header. A decision that isn't in force says so and names what to read instead, for example `SUPERSEDED by ADR-0002 (accepted 2026-10-18). Do not apply this decision; read ADR-0002 instead.`
+
+Every command takes `--json`, `--root <dir>` (the log directory) and `--help`; reads also take `--ref <ref>`, and writes refuse it.
+
+## Exit codes and JSON
+
+- **0**: success.
+- **1**: failing findings from `verify`, or a write the log's rules forbid (an illegal transition, a draft that fails its template lint, an agent's acceptance, an unaccepted successor). Nothing is written, and the findings are in the output.
+- **2**: bad usage (unknown command, flag or decision, a missing argument, `--ref` on a write), and config or environment errors.
+
+With `--json`, stdout carries exactly one JSON document: `adr-list/v1`, `adr-show/v1`, `adr-write/v1` (for `new`, `accept` and `supersede`), ledger's `ledger-findings/v1` for `verify`, or `ark-error/v1` (`{ "format": "ark-error/v1", "error": { "code", "message" } }`) when the command exits 2. Every key is always present, with `null` where a value is unknown. Warnings and notes go to stderr.
+
+## Config (`adr.toml`)
+
+Every key is optional.
+
+```toml
+[log]
+root = "docs/adr"               # read from <repo>/adr.toml; the default
+default_template = "nygard"
+main_branch = "origin/main"     # the ref numbers come from; default origin/HEAD, origin/main, main, …
+index = "none"                  # validated now, used in phase 2
+
+[policy]
+accept_requires_human = true    # refuse acceptances by an agent
+auto_commit = false             # commit writes without --commit
+mcp_can_decide = false          # validated now, used in phase 3
+
+[verify]
+fail_on = "error"               # or "warning"
+```
+
+The config is `<repo>/adr.toml`, whose `[log] root` chooses the log directory, or `<root>/adr.toml`. `--root` uses a repository-level file that names the same root, and overrides one that names another root with a warning.
+
+## Agents
+
+An agent using the CLI sets `ARK_AGENT=<agent-id>`. Its events are recorded as the agent, acting on behalf of the git user, and with `accept_requires_human` on (the default) `adr accept` refuses them with exit 1 (`decision/agent-accepted`). The git identity comes from `user.name` and `user.email` and is never guessed.
+
+## Library
+
+The CLI is a thin layer over the library, and phase 3's MCP server uses the same functions and returns the same JSON documents.
+
+```ts
+import { listDecisions, openDecisionLog, readDecisions, showDecision, verifyDecisions } from "@nikovirtala/adr";
+
+const log = await openDecisionLog({ cwd: process.cwd() });
+const read = await readDecisions(log);
+const { decisions } = listDecisions(read, { status: ["accepted"] });
+const findings = await verifyDecisions(log, { type: "full" });
+```
+
+`proposeDecision`, `acceptDecision` and `supersedeDecision` write, `resolveDecision` turns an id or number into an id, and `stateHeader` gives the header `show` prints.
+
+`@nikovirtala/adr/kind` exports only the decision kind (`adrKind`, made with ledger's `defineKind`) and its types, without any CLI code, for tools that fold decision logs themselves, such as issues linking to decisions:
+
+```ts
+import { adrKind } from "@nikovirtala/adr/kind";
+```
+
+## Not yet included
+
+- **Reference checks are local in phase 1.** `verify` checks that `supersedes`, `superseded.by` and `linked.to` name decisions in the same log. Qualified references to other logs (`<source>:<id>`) are skipped; no phase 1 command writes them.
+- **Phase 2:** `init`, `reject`, `withdraw`, `deprecate`, `note`, `link`, `scope` and `for`; git hooks; a generated index (and the number fallback for shallow clones); scope globs and code anchors; cross-log reference checks and listing across sources.
+- **Phase 3:** an MCP server, a SKILL.md for agents, and search.

package/dist/cli.js

@@ -0,0 +1,470 @@
+#!/usr/bin/env node
+import { a as showDecision, f as resolveDecision, i as listDecisions, l as openDecisionLog, n as proposeDecision, p as unavailableReason, r as supersedeDecision, s as adrChecks, t as acceptDecision, u as readDecisions } from "./write-C3IW5WrA.js";
+import { n as DECISION_STATUSES, t as adrKind } from "./kind-DqFhApu7.js";
+import { createRequire } from "node:module";
+import { UsageError, renderStateHeader, resolveActor, templateHistoryRef } from "@nikovirtala/ledger";
+import { processIO, runCli, verifyCommand } from "@nikovirtala/ledger/cli";
+import { spawn } from "node:child_process";
+// src/cli/open.ts
+/**
+* The decision log a command works on: `--root` and `--ref` from the globals, git run with the
+* CLI's environment.
+*/
+function openForCli(io, flags, o = {}) {
+	return openDecisionLog({
+		cwd: io.cwd,
+		root: flags.root,
+		ref: flags.ref,
+		...o.reader === void 0 ? {} : { reader: o.reader },
+		gitOptions: { env: io.env }
+	});
+}
+/**
+* How other decisions display in a write's text, read again from the work tree, like the write
+* result's own views: a commit on the main ref has numbered the decisions it accepted.
+*/
+async function displayAfterWrite(log) {
+	const read = await readDecisions(log);
+	return { display: (id) => read.projection.views.get(id)?.display ?? id };
+}
+/** `--commit`/`--no-commit` when given, else `[policy] auto_commit`. */
+function commitRequested(log, values) {
+	return typeof values.commit === "boolean" ? values.commit : log.adr.autoCommit;
+}
+// src/cli/text.ts
+/** A table: each column padded to its widest value, trailing spaces removed. */
+function columns(rows) {
+	const widths = [];
+	for (const row of rows) row.forEach((cell, i) => {
+		widths[i] = Math.max(widths[i] ?? 0, cell.length);
+	});
+	return rows.map((row) => row.map((cell, i) => i === row.length - 1 ? cell : cell.padEnd(widths[i] ?? 0)).join("  ").trimEnd()).join("\n");
+}
+/** `adr list`: one row per decision, `→ <effective>` when it differs from the decision. */
+function listText(doc, display) {
+	if (doc.decisions.length === 0) return "No decisions.";
+	return columns(doc.decisions.map((v) => {
+		const arrow = v.effective === null ? "→ (cycle)" : v.effective === v.id ? "" : `→ ${display(v.effective)}`;
+		return [
+			v.number === null ? "-" : v.display,
+			v.id,
+			v.status,
+			v.title,
+			arrow
+		];
+	}));
+}
+/** `ADR-0003 (m2x7p4d2)`, or the id alone when it has no number. */
+function named(id, display) {
+	const shown = display(id);
+	return shown === id ? id : `${shown} (${id})`;
+}
+const day = (at) => (at ?? "").slice(0, 10);
+const list = (ids, display) => ids.length === 0 ? "none" : ids.map((id) => named(id, display)).join(", ");
+function bodyLine(v) {
+	if (v.body_path === null) return "missing";
+	if (v.body_intact === null) return v.body_path;
+	return `${v.body_path} (${v.body_intact ? "intact" : "changed after acceptance"})`;
+}
+function actorText(e) {
+	const a = e.actor;
+	return a.kind === "agent" ? `${a.name} (agent ${a.agent} for ${a.on_behalf_of})` : a.name;
+}
+/** The second line of an event in `show --history`: its reason, else a summary of its data. */
+function eventDetail(e) {
+	if (typeof e.reason === "string") return `reason: ${e.reason}`;
+	const entries = Object.entries(e.data);
+	if (entries.length === 0) return null;
+	return entries.map(([k, v]) => `${k}: ${typeof v === "string" ? v : JSON.stringify(v)}`).join(", ");
+}
+function historyLines(events) {
+	const width = Math.max(...events.map((e) => e.type.length));
+	return events.flatMap((e) => {
+		const detail = eventDetail(e);
+		return [`  ${e.at}  ${e.type.padEnd(width)}  ${actorText(e)}`, ...detail === null ? [] : [`    ${detail}`]];
+	});
+}
+const SECTION_FINDING = /^(?:required )?section (.+?) (is missing|is empty|still contains its guidance text)$/;
+const REASONS = {
+	"is missing": "missing",
+	"is empty": "empty",
+	"still contains its guidance text": "guidance text left"
+};
+/**
+* The draft lint of `new` as advice: `Fill in N sections before accepting: A, B (why)` for the
+* section findings, and one line per other finding.
+*/
+function draftAdvice(findings) {
+	const headings = [];
+	const reasons = [];
+	const other = [];
+	for (const f of findings) {
+		const m = SECTION_FINDING.exec(f.message);
+		if (m === null) {
+			other.push(`Draft: ${f.message} [${f.rule}]`);
+			continue;
+		}
+		const [, heading = "", what = ""] = m;
+		const reason = REASONS[what] ?? what;
+		if (!headings.includes(heading)) headings.push(heading);
+		if (!reasons.includes(reason)) reasons.push(reason);
+	}
+	const n = headings.length;
+	return [...n === 0 ? [] : [`Fill in ${n === 1 ? "1 section" : `${n} sections`} before accepting: ${headings.join(", ")} (${reasons.join(", ")})`], ...other];
+}
+function findingLines(findings) {
+	return findings.map((f) => `  ${f.file === null ? "" : `${f.file}: `}${f.message} [${f.rule}]`);
+}
+const short = (sha) => sha.slice(0, 7);
+/**
+* The text of `adr new|accept|supersede` (design §5.6). `subject` names what a refused command
+* was about; `number` is the decision's number in the write result, if it has one now.
+*/
+function writeText(doc, display, o) {
+	const verb = {
+		new: "proposed",
+		accept: "accepted",
+		supersede: "superseded"
+	}[doc.command];
+	if (!doc.ok) return [`Not ${verb}: ${o.subject}`, ...findingLines(doc.findings)].join("\n");
+	const v = doc.decision;
+	if (v === null) return "";
+	const committed = doc.commit === null ? null : `Committed ${short(doc.commit)}`;
+	switch (doc.command) {
+		case "new": return [
+			`Proposed ${v.id}: ${v.title}`,
+			...doc.written.map((p) => `  ${p}`),
+			...draftAdvice(doc.findings),
+			...committed === null ? [] : [`${committed}.`],
+			`Next: adr accept ${v.id}`
+		].join("\n");
+		case "accept": return [
+			`Accepted ${v.id}: ${v.title}`,
+			...doc.affected.map((a) => `Superseded ${named(a.id, display)}: ${a.title}`),
+			committed === null ? "Staged; commit to record it." : o.number === null ? `${committed}. The number is assigned when this commit lands on main.` : `${committed} as ${o.number}.`
+		].join("\n");
+		case "supersede": return [
+			`Superseded ${named(v.id, display)}: ${v.title}`,
+			`  by ${named(v.superseded_by ?? "", display)}`,
+			committed === null ? "Staged; commit to record it." : `${committed}.`
+		].join("\n");
+	}
+}
+/** `adr show`: the state header, the decision's fields and its body. */
+function showText(doc, display) {
+	const v = doc.decision;
+	const supersedes = v.supersedes.length === 0 && v.declared_supersedes.length > 0 ? `none (declared: ${list(v.declared_supersedes, display)})` : list(v.supersedes, display);
+	const fields = [
+		["Title", v.title],
+		["Status", `${v.status} (${day(v.status_at)})`],
+		["Effective", v.effective === null ? "none (supersession cycle)" : named(v.effective, display)],
+		["Chain", v.chain.map(display).join(" → ")],
+		["Supersedes", supersedes],
+		["Applies to", v.applies_to.length === 0 ? "none" : v.applies_to.join(", ")],
+		["Body", bodyLine(v)]
+	];
+	if (doc.events === null) fields.push(["History", v.history.join(" · ")]);
+	const width = Math.max(...fields.map(([k]) => k.length)) + 2;
+	const lines = fields.map(([k, value]) => `${`${k}:`.padEnd(width)}${value}`);
+	if (doc.events !== null) lines.push("History:", ...historyLines(doc.events));
+	const body = doc.body === null ? "" : `\n${doc.body.endsWith("\n") ? doc.body : `${doc.body}\n`}`;
+	return `${renderStateHeader(doc.header)}\n${lines.join("\n")}\n${body}`;
+}
+// src/cli/accept.ts
+/** `adr accept <decision> [--commit | --no-commit]` (design §5.6). */
+const acceptCommand = {
+	name: "accept",
+	summary: "accept a proposed decision, superseding the decisions it declares",
+	usage: "accept <decision> [--commit | --no-commit]",
+	options: { commit: { type: "boolean" } },
+	positionals: {
+		min: 1,
+		max: 1,
+		names: ["decision"]
+	},
+	ref: "reject",
+	async run({ io, flags, values, positionals }) {
+		const input = positionals[0] ?? "";
+		const log = await openForCli(io, flags);
+		const actor = await resolveActor(log.git, { env: io.env });
+		const doc = await acceptDecision(log, {
+			id: input,
+			actor
+		}, { commit: commitRequested(log, values) });
+		const { display } = await displayAfterWrite(log);
+		const v = doc.decision;
+		return {
+			exit: doc.ok ? 0 : 1,
+			json: doc,
+			text: writeText(doc, display, {
+				subject: v === null ? input.trim() : `${display(v.id)}: ${v.title}`,
+				number: v === null || doc.commit === null || v.number === null ? null : v.display
+			}),
+			notes: doc.notes
+		};
+	}
+};
+// src/cli/list.ts
+const plural = (n, one, many) => n === 1 ? `1 ${one}` : `${n} ${many}`;
+function statuses(values) {
+	return (Array.isArray(values.status) ? values.status : []).map((s) => {
+		if (!DECISION_STATUSES.includes(s)) throw new UsageError(`unknown status ${JSON.stringify(s)}; use one of ${DECISION_STATUSES.join(", ")}`);
+		return s;
+	});
+}
+/** `adr list [--status <status>]…` (design §5.6). */
+const listCommand = {
+	name: "list",
+	summary: "list decisions with their computed status",
+	usage: "list [--status <status>]…",
+	options: { status: {
+		type: "string",
+		multiple: true
+	} },
+	positionals: {
+		min: 0,
+		max: 0,
+		names: []
+	},
+	ref: "read",
+	async run({ io, flags, values }) {
+		const status = statuses(values);
+		const read = await readDecisions(await openForCli(io, flags));
+		const doc = listDecisions(read, { status });
+		const notes = [...doc.notes];
+		if (!read.numbering.available && doc.decisions.length > 0) notes.push(`numbers are unavailable (${unavailableReason(read.numbering)}); decisions display by id`);
+		if (doc.findings.length > 0) notes.push(`the decision log has ${plural(doc.findings.length, "problem", "problems")}; run adr verify`);
+		if (doc.unreadable.length > 0) notes.push(`${plural(doc.unreadable.length, "decision uses", "decisions use")} a newer format; upgrade adr`);
+		if (doc.unfoldable.length > 0) notes.push(`${plural(doc.unfoldable.length, "decision", "decisions")} can't be read; run adr verify`);
+		const display = (id) => read.projection.views.get(id)?.display ?? id;
+		return {
+			exit: 0,
+			json: doc,
+			text: listText(doc, display),
+			notes
+		};
+	}
+};
+// src/cli/editor.ts
+/**
+* The user's editor as an `edit` callback (design §5.7), or `null` when neither `VISUAL` nor
+* `EDITOR` is set. The editor string is run by `sh -c` the way git runs `core.editor`, with the
+* path as the positional parameter `$1`, never interpolated. When stdout isn't a TTY (piped
+* `--json`, say), the editor's stdout goes to stderr so the CLI's stdout stays one document.
+* The callback never throws: a spawn error or a non-zero exit becomes the note.
+*/
+function editorFor(env, o) {
+	const editor = [env.VISUAL, env.EDITOR].map((v) => v?.trim() ?? "").find((v) => v !== "");
+	if (editor === void 0) return null;
+	return (absPath) => new Promise((resolve) => {
+		const fail = (e) => resolve(`could not start the editor: ${e instanceof Error ? e.message : String(e)}`);
+		try {
+			const child = spawn("sh", [
+				"-c",
+				`${editor} "$1"`,
+				"sh",
+				absPath
+			], {
+				env,
+				stdio: o.stdoutIsTTY ? "inherit" : [
+					"inherit",
+					2,
+					"inherit"
+				]
+			});
+			child.on("error", fail);
+			child.on("close", (code, signal) => {
+				if (code === 0) resolve(null);
+				else resolve(`the editor ${code === null ? `was killed by ${signal ?? "a signal"}` : `exited with status ${code}`}; the draft is staged as rendered`);
+			});
+		} catch (e) {
+			fail(e);
+		}
+	});
+}
+// src/cli/new.ts
+const strings = (v) => Array.isArray(v) ? v : [];
+/** `--section <id>=<markdown>` values, split at the first `=`; each id at most once. */
+function sections(values) {
+	const out = {};
+	for (const value of values) {
+		const at = value.indexOf("=");
+		const id = at < 0 ? "" : value.slice(0, at).trim();
+		if (id === "") throw new UsageError(`--section needs <id>=<markdown>, not ${JSON.stringify(value)}`);
+		if (Object.hasOwn(out, id)) throw new UsageError(`--section ${id} is given twice`);
+		out[id] = value.slice(at + 1);
+	}
+	return out;
+}
+/**
+* `adr new <title> …` (design §5.6). The editor runs with `--edit`, or without `--no-edit` when
+* the terminal is interactive and an editor is set.
+*/
+const newCommand = {
+	name: "new",
+	summary: "propose a decision from a template and stage it",
+	usage: "new <title> [--template <name>] [--supersedes <decision>]… [--section <id>=<markdown>]… [--edit | --no-edit] [--commit | --no-commit]",
+	options: {
+		template: { type: "string" },
+		supersedes: {
+			type: "string",
+			multiple: true
+		},
+		section: {
+			type: "string",
+			multiple: true
+		},
+		edit: { type: "boolean" },
+		commit: { type: "boolean" }
+	},
+	positionals: {
+		min: 1,
+		max: 1,
+		names: ["title"]
+	},
+	ref: "reject",
+	async run({ io, flags, values, positionals }) {
+		const title = positionals[0] ?? "";
+		const given = sections(strings(values.section));
+		const log = await openForCli(io, flags);
+		const actor = await resolveActor(log.git, { env: io.env });
+		const requested = commitRequested(log, values);
+		const notes = [];
+		const editor = editorFor(io.env, { stdoutIsTTY: io.stdoutIsTTY });
+		const wantsEdit = values.edit === true || values.edit === void 0 && io.interactive;
+		if (values.edit === true && editor === null) notes.push("no editor: set VISUAL or EDITOR");
+		const edit = wantsEdit && editor !== null ? async (abs) => {
+			const note = await editor(abs);
+			if (note !== null) notes.push(note);
+			return note;
+		} : void 0;
+		const doc = await proposeDecision(log, {
+			title,
+			sections: given,
+			supersedes: strings(values.supersedes),
+			actor,
+			...typeof values.template === "string" ? { template: values.template } : {}
+		}, {
+			commit: requested,
+			...edit === void 0 ? {} : { edit },
+			onNote: (note) => notes.push(requested ? `not committed: ${note}` : note)
+		});
+		const { display } = await displayAfterWrite(log);
+		const v = doc.decision;
+		return {
+			exit: doc.ok ? 0 : 1,
+			json: doc,
+			text: writeText(doc, display, {
+				subject: title.trim(),
+				number: v === null || v.number === null ? null : v.display
+			}),
+			notes: [...doc.notes, ...notes]
+		};
+	}
+};
+// src/cli/show.ts
+/** `adr show <decision> [--history]` (design §5.6). */
+const showCommand = {
+	name: "show",
+	summary: "show a decision with its state header, chain, history and body",
+	usage: "show <decision> [--history]",
+	options: { history: { type: "boolean" } },
+	positionals: {
+		min: 1,
+		max: 1,
+		names: ["decision"]
+	},
+	ref: "read",
+	async run({ io, flags, values, positionals }) {
+		const read = await readDecisions(await openForCli(io, flags));
+		const id = resolveDecision(read, positionals[0] ?? "");
+		const doc = await showDecision(read, id, { history: values.history === true });
+		const display = (s) => read.projection.views.get(s)?.display ?? s;
+		return {
+			exit: 0,
+			json: doc,
+			text: showText(doc, display),
+			notes: doc.notes
+		};
+	}
+};
+// src/cli/supersede.ts
+const USAGE = "supersede <decision> --by <decision> [--reason <text>] [--commit | --no-commit]";
+/** `adr supersede <decision> --by <decision> …` (design §5.6). */
+const supersedeCommand = {
+	name: "supersede",
+	summary: "mark an accepted decision as superseded by another accepted one",
+	usage: USAGE,
+	options: {
+		by: { type: "string" },
+		reason: { type: "string" },
+		commit: { type: "boolean" }
+	},
+	positionals: {
+		min: 1,
+		max: 1,
+		names: ["decision"]
+	},
+	ref: "reject",
+	async run({ io, flags, values, positionals }) {
+		const input = positionals[0] ?? "";
+		if (typeof values.by !== "string") throw new UsageError(`missing --by <decision>; usage: adr ${USAGE}`);
+		const log = await openForCli(io, flags);
+		const actor = await resolveActor(log.git, { env: io.env });
+		const doc = await supersedeDecision(log, {
+			id: input,
+			by: values.by,
+			actor,
+			...typeof values.reason === "string" ? { reason: values.reason } : {}
+		}, { commit: commitRequested(log, values) });
+		const { display } = await displayAfterWrite(log);
+		const v = doc.decision;
+		return {
+			exit: doc.ok ? 0 : 1,
+			json: doc,
+			text: writeText(doc, display, {
+				subject: v === null ? input.trim() : `${display(v.id)}: ${v.title}`,
+				number: null
+			}),
+			notes: doc.notes
+		};
+	}
+};
+// src/cli/commands.ts
+/**
+* ledger's shared `verify`: the log as the mode reads it (the index for `--staged`, else the
+* `--ref` tree or the work tree), every phase-1 check, and `[verify] fail_on`.
+*/
+const verify = verifyCommand({ async open({ io, flags, mode }) {
+	const log = await openForCli(io, flags, { reader: mode.type === "staged" ? "index" : "worktree" });
+	return {
+		git: log.git,
+		kind: adrKind,
+		layout: log.layout,
+		checks: adrChecks(log, await templateHistoryRef(log.git, mode)),
+		failOn: log.adr.failOn,
+		notes: log.notes
+	};
+} });
+/** The `adr` tool: its commands, for ledger's `runCli`. */
+function adrCli(version) {
+	return {
+		name: "adr",
+		version,
+		summary: "Architecture decision records kept as event logs in git.",
+		commands: [
+			newCommand,
+			acceptCommand,
+			supersedeCommand,
+			listCommand,
+			showCommand,
+			verify
+		]
+	};
+}
+// src/cli.ts
+const { version } = createRequire(import.meta.url)("../package.json");
+process.exitCode = await runCli(adrCli(version), processIO());
+export {};
+
+//# sourceMappingURL=cli.js.map