@nikovirtala/adr 0.1.0 → 0.3.0

package/dist/cli.js

@@ -1,9 +1,10 @@
 #!/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 { A as openDecisionLog, C as adrChecks, D as runDecisionIndex, N as resolveDecision, O as changedSince, S as withdrawDecision, _ as proposeDecision, a as initDecisionLog, c as installDecisionHooks, d as uninstallDecisionHooks, f as acceptDecision, g as noteDecision, h as linkDecision, j as readDecisions, k as numberingNote, l as printDecisionHooks, m as followScopeRenames, n as listDecisions, o as addHookTrailers, p as deprecateDecision, r as showDecision, t as decisionsFor, u as runPreCommitHook, v as rejectDecision, x as supersedeDecision, y as scopeDecision } from "./scope-CLqH-q1y.js";
+import { n as DECISION_STATUSES, t as adrKind } from "./kind-DjvA3dyA.js";
 import { createRequire } from "node:module";
-import { UsageError, renderStateHeader, resolveActor, templateHistoryRef } from "@nikovirtala/ledger";
-import { processIO, runCli, verifyCommand } from "@nikovirtala/ledger/cli";
+import { UsageError, exitCode, findingsReport, formatText, renderStateHeader, resolveAttribution, stagedRenames, templateHistoryRef } from "@nikovirtala/ledger";
+import { resolve } from "node:path";
+import { COMMIT_OPTIONS, commitChoice, confirm, processIO, runCli, verifyCommand } from "@nikovirtala/ledger/cli";
 import { spawn } from "node:child_process";
 // src/cli/open.ts
 /**
@@ -27,10 +28,8 @@ 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;
-}
+/** `notes` with `note` appended when there is one. */
+const notesWith = (notes, note) => note === null ? notes : [...notes, note];
 // src/cli/text.ts
 /** A table: each column padded to its widest value, trailing spaces removed. */
 function columns(rows) {
@@ -43,6 +42,21 @@ function columns(rows) {
 /** `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 listRows(doc, display).join("\n");
+}
+/**
+* `adr list --since <rev>` (design 2b D7): a heading, then each row followed by the event types
+* added since `rev`; nothing at all when no decision changed, so the post-merge hook stays quiet.
+*/
+function sinceText(doc, since, display) {
+	if (doc.decisions.length === 0) return "";
+	const rows = listRows(doc, display);
+	return [`Changed since ${since.rev} (${since.commit.slice(0, 7)}):`, ...doc.decisions.flatMap((v, i) => {
+		const types = [...new Set(since.events.filter((e) => e.subject === v.id).map((e) => e.type))];
+		return [rows[i] ?? "", `  [new: ${types.join(", ")}]`];
+	})].join("\n");
+}
+function listRows(doc, display) {
 	return columns(doc.decisions.map((v) => {
 		const arrow = v.effective === null ? "→ (cycle)" : v.effective === v.id ? "" : `→ ${display(v.effective)}`;
 		return [
@@ -52,7 +66,7 @@ function listText(doc, display) {
 			v.title,
 			arrow
 		];
-	}));
+	})).split("\n");
 }
 /** `ADR-0003 (m2x7p4d2)`, or the id alone when it has no number. */
 function named(id, display) {
@@ -90,18 +104,15 @@ const REASONS = {
 	"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) {
+/** The section findings of a draft lint as headings and reasons, and the other findings. */
+function sectionGaps(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}]`);
+			other.push(f);
 			continue;
 		}
 		const [, heading = "", what = ""] = m;
@@ -109,47 +120,138 @@ function draftAdvice(findings) {
 		if (!headings.includes(heading)) headings.push(heading);
 		if (!reasons.includes(reason)) reasons.push(reason);
 	}
+	return {
+		headings,
+		reasons,
+		other
+	};
+}
+/**
+* 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, reasons, other } = sectionGaps(findings);
+	const n = headings.length;
+	return [...n === 0 ? [] : [`Fill in ${n === 1 ? "1 section" : `${n} sections`} before accepting: ${headings.join(", ")} (${reasons.join(", ")})`], ...other.map((f) => `Draft: ${f.message} [${f.rule}]`)];
+}
+/**
+* The stderr warning of `new` when the draft it wrote has unfilled sections (design §7.2), or
+* `null` when there are none.
+*/
+function unfilledWarning(doc) {
+	if (doc.command !== "new" || !doc.ok || doc.written.length === 0) return null;
+	const { headings, reasons } = sectionGaps(doc.findings);
 	const n = headings.length;
-	return [...n === 0 ? [] : [`Fill in ${n === 1 ? "1 section" : `${n} sections`} before accepting: ${headings.join(", ")} (${reasons.join(", ")})`], ...other];
+	const path = doc.findings.find((f) => f.file !== null)?.file ?? doc.decision?.body_path ?? null;
+	if (n === 0 || path === null) return null;
+	return `${path}: fill in ${n === 1 ? "1 required section" : `${n} required sections`} before committing or accepting: ${headings.join(", ")} (${reasons.join(", ")}); adr verify reports this until then`;
 }
 function findingLines(findings) {
 	return findings.map((f) => `  ${f.file === null ? "" : `${f.file}: `}${f.message} [${f.rule}]`);
 }
-const short = (sha) => sha.slice(0, 7);
+const short$1 = (sha) => sha.slice(0, 7);
+/**
+* `adr scope --follow-renames`: one `<named>: <old globs> → <new globs>` line per changed
+* decision (`affected`), whether or not a decision was given.
+*/
+function followRenamesText(doc, display, o) {
+	if (!o.renamed) return "No staged renames.";
+	if (doc.affected.length === 0) return "No scope globs follow the staged renames.";
+	return [...doc.affected.map((v) => {
+		const before = o.before.get(v.id) ?? [];
+		const old = before.filter((g) => !v.applies_to.includes(g));
+		const now = v.applies_to.filter((g) => !before.includes(g));
+		const change = old.length === 0 ? `+ ${now.join(", ")}` : `${old.join(", ")} → ${now.join(", ")}`;
+		return `${named(v.id, display)}: ${change}`;
+	}), "Staged; commit the scoped events with the renames."].join("\n");
+}
+/** The past participle of each write command, for `Not <verb>: …`. */
+const VERBS = {
+	new: "proposed",
+	accept: "accepted",
+	supersede: "superseded",
+	reject: "rejected",
+	withdraw: "withdrawn",
+	deprecate: "deprecated",
+	note: "noted",
+	link: "linked",
+	scope: "scoped"
+};
 /**
-* 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.
+* The text of a write command (design §5.6, §6.1). `subject` names what a refused command was
+* about; `number` is the decision's number in the write result, if it has one now; `reason` is
+* the reason a lifecycle exit recorded.
 */
 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 verb = VERBS[doc.command];
+	if (!doc.ok) {
+		const unfilled = doc.command === "new" && sectionGaps(doc.findings).headings.length > 0;
+		return [
+			`Not ${verb}: ${o.subject}`,
+			...findingLines(doc.findings),
+			...unfilled ? ["Fill them in with --section <id>=<markdown>, or run without --commit and edit the draft."] : []
+		].join("\n");
+	}
+	if (o.followRenames !== void 0) return followRenamesText(doc, display, o.followRenames);
 	const v = doc.decision;
 	if (v === null) return "";
-	const committed = doc.commit === null ? null : `Committed ${short(doc.commit)}`;
+	const committed = doc.commit === null ? null : `Committed ${short$1(doc.commit)}`;
+	const recorded = committed === null ? "Staged; commit to record it." : `${committed}.`;
 	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}`
+			o.actor?.kind === "agent" && o.acceptRequiresHuman === true ? `Next: ask a human to review and accept it (adr accept ${v.id})` : `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}`),
+			...o.copied === void 0 || o.copied === null ? [] : [`Copied scope from ${o.copied.displays.join(", ")}: ${o.copied.globs.join(", ")}`],
 			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}.`
+			recorded
 		].join("\n");
+		case "reject":
+		case "withdraw":
+		case "deprecate": return [
+			`${verb.charAt(0).toUpperCase()}${verb.slice(1)} ${named(v.id, display)}: ${v.title}`,
+			...o.reason === void 0 || o.reason === null ? [] : [`  reason: ${o.reason}`],
+			recorded
+		].join("\n");
+		case "note": return [`Noted on ${named(v.id, display)}: ${v.title}`, recorded].join("\n");
+		case "link": {
+			const link = doc.written.length === 0 ? void 0 : v.links.at(-1);
+			if (link === void 0) return `Links of ${named(v.id, display)} unchanged`;
+			return [`Linked ${named(v.id, display)} ${link.rel} ${named(link.to, display)}`, recorded].join("\n");
+		}
+		case "scope": {
+			const before = new Set(o.scopeBefore ?? []);
+			const after = new Set(v.applies_to);
+			const globs = v.applies_to.length === 0 ? "no globs" : v.applies_to.join(", ");
+			if (doc.written.length === 0) return `Scope of ${named(v.id, display)} unchanged: ${globs}`;
+			return [
+				`Scope of ${named(v.id, display)}: ${v.title}`,
+				...v.applies_to.filter((g) => !before.has(g)).map((g) => `  + ${g}`),
+				...[...before].filter((g) => !after.has(g)).map((g) => `  - ${g}`),
+				`  = ${globs}`,
+				recorded
+			].join("\n");
+		}
 	}
 }
+/**
+* "Applies to" without globs: nothing is recorded, which isn't "governs nothing" (design §7.3),
+* with the command that adds globs while the decision can still take them.
+*/
+function noGlobs(v, display) {
+	return adrKind.machine.allowed(v.status, "scoped") ? `no globs recorded; add them with adr scope ${display(v.id)} --add <glob>` : "no globs recorded";
+}
 /** `adr show`: the state header, the decision's fields and its body. */
 function showText(doc, display) {
 	const v = doc.decision;
@@ -160,7 +262,7 @@ function showText(doc, display) {
 		["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(", ")],
+		["Applies to", v.applies_to.length === 0 ? noGlobs(v, display) : v.applies_to.join(", ")],
 		["Body", bodyLine(v)]
 	];
 	if (doc.events === null) fields.push(["History", v.history.join(" · ")]);
@@ -170,13 +272,81 @@ function showText(doc, display) {
 	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}`;
 }
+/**
+* `adr for`: per path, one row per decision (named, status, title, how it matched), its warning
+* below it when it isn't in force, then the anchors that name no decision of this log.
+*/
+function forText(doc, display, keyword) {
+	const lines = [];
+	for (const p of doc.paths) {
+		lines.push(p.tracked ? p.path : `${p.path} (not tracked)`);
+		if (p.decisions.length === 0 && p.unresolved.length === 0) lines.push("  no decisions");
+		const rows = columns(p.decisions.map((d) => [
+			named(d.id, display),
+			d.status,
+			d.title,
+			d.via.map((v) => v.type === "glob" ? `glob ${v.glob}` : `anchor line ${v.line}`).join(", ")
+		])).split("\n");
+		p.decisions.forEach((d, i) => {
+			lines.push(`  ${rows[i] ?? ""}`);
+			if (d.warning !== null) lines.push(`    ${d.warning}`);
+		});
+		for (const u of p.unresolved) {
+			const why = u.reason === "other-log" ? "in another log" : "not in this log";
+			lines.push(`  unresolved: ${keyword}:${u.ref} (line ${u.line}, ${why})`);
+		}
+	}
+	return lines.join("\n");
+}
+/** `adr init`: what was written and kept, then the next step; or that nothing was needed. */
+function initText(doc) {
+	if (doc.written.length === 0) return `Already initialized: ${doc.root} (kept ${doc.kept.join(", ")})`;
+	return [
+		`Initialized ${doc.root}`,
+		...doc.written.map((p) => `  ${p}`),
+		...doc.kept.map((p) => `Kept ${p}`),
+		...doc.commit === null ? [] : [`Committed ${short$1(doc.commit)}.`],
+		"Next: adr new \"<title>\""
+	].join("\n");
+}
 // src/cli/accept.ts
-/** `adr accept <decision> [--commit | --no-commit]` (design §5.6). */
+const MAX_LISTED = 5;
+/** `Copy the scope of ADR-0002 (src/a/**, src/b/**) to k3f9q8a1? [y/N] ` (design §6.10). */
+function question(id, offer) {
+	const shown = offer.globs.slice(0, MAX_LISTED).join(", ");
+	const more = offer.globs.length - MAX_LISTED;
+	const globs = more > 0 ? `${shown} and ${more} more` : shown;
+	const ds = offer.displays;
+	return `Copy the scope of ${ds.length === 1 ? ds[0] : `${ds.slice(0, -1).join(", ")} and ${ds.at(-1)}`} (${ds.length === 1 ? globs : `${offer.globs.length} globs: ${globs}`}) to ${id}? [y/N] `;
+}
+/**
+* The flags decide; without them a person at a terminal is asked, and everyone else (scripts,
+* hooks, CI, `--json`) gets the note with the `adr scope` command (design §6.10, D-e). `seen`
+* receives the offer that was copied, for the text.
+*/
+function copyChoice(io, json, value, seen) {
+	const copy = async (offer) => {
+		seen(offer);
+		return true;
+	};
+	if (value === true) return copy;
+	if (value === false) return "skip";
+	if (json || !io.interactive) return "suggest";
+	return async (offer) => {
+		const yes = await confirm(io, question(offer.id, offer), { json });
+		if (yes) seen(offer);
+		return yes;
+	};
+}
+/** `adr accept <decision> [--copy-scope | --no-copy-scope] …` (design §5.6, §6.10). */
 const acceptCommand = {
 	name: "accept",
 	summary: "accept a proposed decision, superseding the decisions it declares",
-	usage: "accept <decision> [--commit | --no-commit]",
-	options: { commit: { type: "boolean" } },
+	usage: "accept <decision> [--copy-scope | --no-copy-scope] [--commit | --no-commit] [-m <message>]",
+	options: {
+		"copy-scope": { type: "boolean" },
+		...COMMIT_OPTIONS
+	},
 	positionals: {
 		min: 1,
 		max: 1,
@@ -186,11 +356,19 @@ const acceptCommand = {
 	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 { actor, notes: attribution } = await resolveAttribution(log.git, { env: io.env });
+		const seen = { offer: null };
+		const copyScope = copyChoice(io, flags.json, values["copy-scope"], (offer) => {
+			seen.offer = offer;
+		});
 		const doc = await acceptDecision(log, {
 			id: input,
 			actor
-		}, { commit: commitRequested(log, values) });
+		}, {
+			...commitChoice(values, { autoCommit: log.adr.autoCommit }),
+			notes: attribution,
+			copyScope
+		});
 		const { display } = await displayAfterWrite(log);
 		const v = doc.decision;
 		return {
@@ -198,7 +376,295 @@ const acceptCommand = {
 			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
+				number: v === null || doc.commit === null || v.number === null ? null : v.display,
+				copied: doc.ok ? seen.offer : null
+			}),
+			notes: doc.notes
+		};
+	}
+};
+// src/cli/deprecate.ts
+const USAGE$5 = "deprecate <decision> --reason <text> [--commit | --no-commit] [-m <message>]";
+/** `adr deprecate` (design §6.5): an accepted decision no longer in force. */
+const deprecateCommand = {
+	name: "deprecate",
+	summary: "deprecate an accepted decision",
+	usage: USAGE$5,
+	options: {
+		reason: { type: "string" },
+		...COMMIT_OPTIONS
+	},
+	positionals: {
+		min: 1,
+		max: 1,
+		names: ["decision"]
+	},
+	ref: "reject",
+	async run({ io, flags, values, positionals }) {
+		const input = positionals[0] ?? "";
+		if (typeof values.reason !== "string" || values.reason.trim() === "") throw new UsageError(`missing --reason <text>; usage: adr ${USAGE$5}`);
+		const reason = typeof values.reason === "string" ? values.reason.trim() : null;
+		const log = await openForCli(io, flags);
+		const { actor, notes } = await resolveAttribution(log.git, { env: io.env });
+		const doc = await deprecateDecision(log, {
+			id: input,
+			reason,
+			actor
+		}, {
+			...commitChoice(values, { autoCommit: log.adr.autoCommit }),
+			notes
+		});
+		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,
+				reason
+			}),
+			notes: doc.notes
+		};
+	}
+};
+// src/cli/for.ts
+/** `adr for <path>… [--ref <ref>]` (design §6.9): the decisions that govern each file. */
+const forCommand = {
+	name: "for",
+	summary: "list the decisions that govern files, by scope glob and code anchor",
+	usage: "for <path>…",
+	options: {},
+	positionals: {
+		min: 1,
+		max: 100,
+		names: ["path"]
+	},
+	ref: "read",
+	async run({ io, flags, positionals }) {
+		const log = await openForCli(io, flags);
+		const read = await readDecisions(log);
+		const doc = await decisionsFor(read, log, {
+			paths: positionals,
+			cwd: io.cwd
+		});
+		const display = (id) => read.projection.views.get(id)?.display ?? id;
+		return {
+			exit: 0,
+			json: doc,
+			text: forText(doc, display, read.adr.anchorKeyword),
+			notes: notesWith(doc.notes, numberingNote(read, { unavailable: false }))
+		};
+	}
+};
+// src/cli/hooks.ts
+const USAGE$4 = "hooks install | uninstall | print --manager lefthook|husky|pre-commit | run pre-commit | trailers <message-file>";
+const MANAGERS = [
+	"lefthook",
+	"husky",
+	"pre-commit"
+];
+const outcome = (doc, text, notes) => ({
+	exit: 0,
+	json: doc,
+	text,
+	notes
+});
+/**
+* `adr hooks install | uninstall | print --manager … | run pre-commit | trailers <message-file>`
+* (design 2b D4, D8, §4.3): adr's git hooks through ledger's shims, shared with other ark tools.
+*/
+const hooksCommand = {
+	name: "hooks",
+	summary: "install, remove or print adr's git hooks, and run their steps",
+	usage: USAGE$4,
+	options: { manager: { type: "string" } },
+	positionals: {
+		min: 1,
+		max: 2,
+		names: ["action", "argument"]
+	},
+	ref: "reject",
+	async run({ io, flags, values, positionals }) {
+		const [action = "", argument] = positionals;
+		const manager = values.manager;
+		if (manager !== void 0 && action !== "print") throw new UsageError(`--manager goes with hooks print only; usage: adr ${USAGE$4}`);
+		const noArgument = () => {
+			if (argument !== void 0) throw new UsageError(`unexpected argument ${JSON.stringify(argument)}; usage: adr ${USAGE$4}`);
+		};
+		switch (action) {
+			case "install": {
+				noArgument();
+				const log = await openForCli(io, flags);
+				const doc = await installDecisionHooks(log);
+				const lines = [...[...doc.written, ...doc.unchanged].map((p) => `${doc.written.includes(p) ? "wrote" : "unchanged"} ${p}`).sort((a, b) => order(a) - order(b)), `adr hooks: ${doc.registrations.map((r) => r.hook).join(", ")}`];
+				return outcome(doc, lines.join("\n"), log.notes);
+			}
+			case "uninstall": {
+				noArgument();
+				const log = await openForCli(io, flags);
+				const doc = await uninstallDecisionHooks(log);
+				const text = doc.written.length === 0 ? "adr hooks were not installed" : doc.written.map((p) => `removed adr from ${p}`).join("\n");
+				return outcome(doc, text, log.notes);
+			}
+			case "print": {
+				noArgument();
+				if (manager === void 0) throw new UsageError("hooks print needs --manager lefthook, husky or pre-commit");
+				if (!MANAGERS.includes(manager)) throw new UsageError(`unknown hook manager ${JSON.stringify(manager)}; use lefthook, husky or pre-commit`);
+				const log = await openForCli(io, flags);
+				const doc = printDecisionHooks(log, manager);
+				return outcome(doc, doc.snippet ?? "", log.notes);
+			}
+			case "run": {
+				if (argument !== "pre-commit") throw new UsageError("adr hooks run supports pre-commit");
+				const worktree = await openForCli(io, flags);
+				const index = await openForCli(io, flags, { reader: "index" });
+				const r = await runPreCommitHook({
+					worktree,
+					index,
+					env: io.env
+				});
+				return {
+					exit: r.exit,
+					json: findingsReport(r.findings, { failOn: r.failOn }),
+					text: r.findings.length === 0 ? "" : formatText(r.findings),
+					notes: r.notes
+				};
+			}
+			case "trailers": {
+				if (argument === void 0) throw new UsageError(`missing argument <message-file>; usage: adr ${USAGE$4}`);
+				const log = await openForCli(io, flags);
+				const doc = await addHookTrailers(log, resolve(io.cwd, argument));
+				return outcome(doc, "", log.notes);
+			}
+			default: throw new UsageError(`unknown hooks action ${JSON.stringify(action)}; use install, uninstall, print, run or trailers`);
+		}
+	}
+};
+/** A shim line's rank in hook order, for the install text. */
+function order(line) {
+	return [
+		"pre-commit",
+		"commit-msg",
+		"pre-push",
+		"post-merge"
+	].findIndex((h) => line.endsWith(`/${h}`));
+}
+// src/cli/index-command.ts
+const short = (sha) => sha.slice(0, 7);
+/** The text of `adr index` (design 2b §4.5). */
+function indexText({ doc, refreshed }) {
+	const { path } = doc;
+	if (doc.check) return doc.findings.length === 0 ? `${path} is up to date` : formatText(doc.findings);
+	if (doc.commit !== null) return [`Committed ${path} as ${short(doc.commit)}`, ...refreshed ? [`Wrote ${path} with uncommitted log changes`] : []].join("\n");
+	if (refreshed) return `${path} is up to date in HEAD; wrote the work tree's copy, which includes uncommitted log changes`;
+	if (doc.fresh) return `${path} is up to date`;
+	return doc.written.length > 0 ? `Wrote ${path}` : `Staged ${path}`;
+}
+/** `adr index [--check] [--commit | --no-commit] [-m <message>]` (design 2b §4.5). */
+const indexCommand = {
+	name: "index",
+	summary: "regenerate the decision index (index.md), or check that it is current",
+	usage: "index [--check] [--commit | --no-commit] [-m <message>]",
+	options: {
+		check: { type: "boolean" },
+		...COMMIT_OPTIONS
+	},
+	positionals: {
+		min: 0,
+		max: 0,
+		names: []
+	},
+	ref: "read",
+	async run({ io, flags, values }) {
+		const check = values.check === true;
+		if (check && (values.commit === true || typeof values.message === "string")) throw new UsageError("--check writes nothing; drop --commit and --message");
+		if (!check && flags.ref !== null) throw new UsageError("adr index writes the work tree; use --ref only with --check");
+		const log = await openForCli(io, flags);
+		const run = await runDecisionIndex(log, {
+			check,
+			...check ? {} : commitChoice(values, { autoCommit: log.adr.autoCommit })
+		});
+		return {
+			exit: check ? exitCode(run.doc.findings, { failOn: log.adr.failOn }) : 0,
+			json: run.doc,
+			text: indexText(run),
+			notes: run.doc.notes
+		};
+	}
+};
+// src/cli/init.ts
+/** `adr init [--template <name>]… [--commit | --no-commit] [-m <message>]` (design §6.2). */
+const initCommand = {
+	name: "init",
+	summary: "set up a decision log: a config file and starter templates",
+	usage: "init [--template <name>]… [--commit | --no-commit] [-m <message>]",
+	options: {
+		template: {
+			type: "string",
+			multiple: true
+		},
+		...COMMIT_OPTIONS
+	},
+	positionals: {
+		min: 0,
+		max: 0,
+		names: []
+	},
+	ref: "reject",
+	async run({ io, flags, values }) {
+		const templates = Array.isArray(values.template) ? values.template : void 0;
+		const log = await openForCli(io, flags);
+		const doc = await initDecisionLog(log, {
+			...templates === void 0 ? {} : { templates },
+			...commitChoice(values, { autoCommit: log.adr.autoCommit })
+		});
+		return {
+			exit: 0,
+			json: doc,
+			text: initText(doc),
+			notes: doc.notes
+		};
+	}
+};
+// src/cli/link.ts
+/** `adr link <decision> <target> [--rel <rel>]` (design §6.7): a typed link, in any state. */
+const linkCommand = {
+	name: "link",
+	summary: "link a decision to another one, here or in a configured source",
+	usage: "link <decision> <target> [--rel relates-to|refines|depends-on] [--commit | --no-commit] [-m <message>]",
+	options: {
+		rel: { type: "string" },
+		...COMMIT_OPTIONS
+	},
+	positionals: {
+		min: 2,
+		max: 2,
+		names: ["decision", "target"]
+	},
+	ref: "reject",
+	async run({ io, flags, values, positionals }) {
+		const [input = "", to = ""] = positionals;
+		const rel = typeof values.rel === "string" ? values.rel : "relates-to";
+		const log = await openForCli(io, flags);
+		const { actor, notes } = await resolveAttribution(log.git, { env: io.env });
+		const doc = await linkDecision(log, {
+			id: input,
+			to,
+			rel,
+			actor
+		}, {
+			...commitChoice(values, { autoCommit: log.adr.autoCommit }),
+			notes
+		});
+		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
 		};
@@ -212,15 +678,25 @@ function statuses(values) {
 		return s;
 	});
 }
-/** `adr list [--status <status>]…` (design §5.6). */
+/** `--since`'s revision: non-empty and not an option. */
+function sinceRev(values) {
+	const v = values.since;
+	if (typeof v !== "string") return null;
+	if (v.trim() === "" || v.startsWith("-")) throw new UsageError("--since must be a revision");
+	return v;
+}
+/** `adr list [--status <status>]… [--since <rev>]` (design §5.6, 2b D7). */
 const listCommand = {
 	name: "list",
 	summary: "list decisions with their computed status",
-	usage: "list [--status <status>]…",
-	options: { status: {
-		type: "string",
-		multiple: true
-	} },
+	usage: "list [--status <status>]… [--since <rev>]",
+	options: {
+		status: {
+			type: "string",
+			multiple: true
+		},
+		since: { type: "string" }
+	},
 	positionals: {
 		min: 0,
 		max: 0,
@@ -229,10 +705,17 @@ const listCommand = {
 	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 rev = sinceRev(values);
+		const log = await openForCli(io, flags);
+		const since = rev === null ? null : await changedSince(log, rev);
+		const read = await readDecisions(log);
+		const doc = listDecisions(read, {
+			status,
+			since
+		});
 		const notes = [...doc.notes];
-		if (!read.numbering.available && doc.decisions.length > 0) notes.push(`numbers are unavailable (${unavailableReason(read.numbering)}); decisions display by id`);
+		const numbering = numberingNote(read, { unavailable: true });
+		if (numbering !== null && doc.decisions.length > 0) notes.push(numbering);
 		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`);
@@ -240,7 +723,7 @@ const listCommand = {
 		return {
 			exit: 0,
 			json: doc,
-			text: listText(doc, display),
+			text: doc.since === null ? listText(doc, display) : sinceText(doc, doc.since, display),
 			notes
 		};
 	}
@@ -283,7 +766,7 @@ function editorFor(env, o) {
 	});
 }
 // src/cli/new.ts
-const strings = (v) => Array.isArray(v) ? v : [];
+const strings$1 = (v) => Array.isArray(v) ? v : [];
 /** `--section <id>=<markdown>` values, split at the first `=`; each id at most once. */
 function sections(values) {
 	const out = {};
@@ -303,7 +786,7 @@ function sections(values) {
 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]",
+	usage: "new <title> [--template <name>] [--supersedes <decision>]… [--section <id>=<markdown>]… [--edit | --no-edit] [--commit | --no-commit] [-m <message>]",
 	options: {
 		template: { type: "string" },
 		supersedes: {
@@ -315,7 +798,7 @@ const newCommand = {
 			multiple: true
 		},
 		edit: { type: "boolean" },
-		commit: { type: "boolean" }
+		...COMMIT_OPTIONS
 	},
 	positionals: {
 		min: 1,
@@ -325,10 +808,10 @@ const newCommand = {
 	ref: "reject",
 	async run({ io, flags, values, positionals }) {
 		const title = positionals[0] ?? "";
-		const given = sections(strings(values.section));
+		const given = sections(strings$1(values.section));
 		const log = await openForCli(io, flags);
-		const actor = await resolveActor(log.git, { env: io.env });
-		const requested = commitRequested(log, values);
+		const { actor, notes: attribution } = await resolveAttribution(log.git, { env: io.env });
+		const { commit: requested, message } = commitChoice(values, { autoCommit: log.adr.autoCommit });
 		const notes = [];
 		const editor = editorFor(io.env, { stdoutIsTTY: io.stdoutIsTTY });
 		const wantsEdit = values.edit === true || values.edit === void 0 && io.interactive;
@@ -341,24 +824,245 @@ const newCommand = {
 		const doc = await proposeDecision(log, {
 			title,
 			sections: given,
-			supersedes: strings(values.supersedes),
+			supersedes: strings$1(values.supersedes),
 			actor,
 			...typeof values.template === "string" ? { template: values.template } : {}
 		}, {
 			commit: requested,
+			message,
+			notes: attribution,
 			...edit === void 0 ? {} : { edit },
 			onNote: (note) => notes.push(requested ? `not committed: ${note}` : note)
 		});
 		const { display } = await displayAfterWrite(log);
 		const v = doc.decision;
+		const unfilled = unfilledWarning(doc);
 		return {
 			exit: doc.ok ? 0 : 1,
 			json: doc,
 			text: writeText(doc, display, {
 				subject: title.trim(),
-				number: v === null || v.number === null ? null : v.display
+				number: v === null || v.number === null ? null : v.display,
+				actor,
+				acceptRequiresHuman: log.adr.acceptRequiresHuman
+			}),
+			notes: [
+				...doc.notes,
+				...notes,
+				...unfilled === null ? [] : [unfilled]
+			]
+		};
+	}
+};
+// src/cli/note.ts
+/** `adr note <decision> <text>` (design §6.6): a note on a decision in any state. */
+const noteCommand = {
+	name: "note",
+	summary: "add a note to a decision, in any state",
+	usage: "note <decision> <text> [--commit | --no-commit] [-m <message>]",
+	options: { ...COMMIT_OPTIONS },
+	positionals: {
+		min: 2,
+		max: 2,
+		names: ["decision", "text"]
+	},
+	ref: "reject",
+	async run({ io, flags, values, positionals }) {
+		const [input = "", text = ""] = positionals;
+		const log = await openForCli(io, flags);
+		const { actor, notes } = await resolveAttribution(log.git, { env: io.env });
+		const doc = await noteDecision(log, {
+			id: input,
+			text,
+			actor
+		}, {
+			...commitChoice(values, { autoCommit: log.adr.autoCommit }),
+			notes
+		});
+		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/reject.ts
+const USAGE$3 = "reject <decision> --reason <text> [--commit | --no-commit] [-m <message>]";
+/** `adr reject` (design §6.3): a proposal that won't be adopted. */
+const rejectCommand = {
+	name: "reject",
+	summary: "reject a proposed decision",
+	usage: USAGE$3,
+	options: {
+		reason: { type: "string" },
+		...COMMIT_OPTIONS
+	},
+	positionals: {
+		min: 1,
+		max: 1,
+		names: ["decision"]
+	},
+	ref: "reject",
+	async run({ io, flags, values, positionals }) {
+		const input = positionals[0] ?? "";
+		if (typeof values.reason !== "string" || values.reason.trim() === "") throw new UsageError(`missing --reason <text>; usage: adr ${USAGE$3}`);
+		const reason = typeof values.reason === "string" ? values.reason.trim() : null;
+		const log = await openForCli(io, flags);
+		const { actor, notes } = await resolveAttribution(log.git, { env: io.env });
+		const doc = await rejectDecision(log, {
+			id: input,
+			reason,
+			actor
+		}, {
+			...commitChoice(values, { autoCommit: log.adr.autoCommit }),
+			notes
+		});
+		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,
+				reason
+			}),
+			notes: doc.notes
+		};
+	}
+};
+// src/cli/scope.ts
+const USAGE$2 = "scope <decision> ([--set <glob>]… | --clear | [--add <glob>]… [--remove <glob>]…) [--commit | --no-commit] [-m <message>] | scope [<decision>] --follow-renames";
+/** The flag names `applySetOp` uses in its messages (design §3.2). */
+const NAMES = {
+	set: "--set",
+	add: "--add",
+	remove: "--remove",
+	clear: "--clear"
+};
+const strings = (v) => Array.isArray(v) ? v : [];
+/** `--set`/`--clear`/`--add`/`--remove` as a set operation; `--clear` is `{ set: [] }`. */
+function setOp(values) {
+	const set = strings(values.set);
+	const add = strings(values.add);
+	const remove = strings(values.remove);
+	if (values.clear === true) {
+		if (set.length > 0 || add.length > 0 || remove.length > 0) throw new UsageError("--clear can't be combined with --set, --add or --remove");
+		return { set: [] };
+	}
+	return {
+		...set.length > 0 ? { set } : {},
+		add,
+		remove
+	};
+}
+/**
+* `--follow-renames` alone: no set operation, no commit and no message, all refused before
+* `commitChoice` so the answer doesn't depend on `auto_commit` (design §6.8).
+*/
+function checkFollowRenames(values) {
+	if ([
+		"set",
+		"add",
+		"remove"
+	].some((k) => strings(values[k]).length > 0) || values.clear === true) throw new UsageError("--follow-renames can't be combined with --set, --clear, --add or --remove");
+	if (values.commit === true) throw new UsageError("--follow-renames stages its events for the commit that contains the renames; commit them together");
+	if (typeof values.message === "string") throw new UsageError("--follow-renames never commits, so it takes no --message");
+}
+/**
+* `adr scope <decision> --set|--clear|--add|--remove …` (design §6.8): the globs of the code a
+* decision governs, written as one whole-set `scoped` event. `adr scope [<decision>]
+* --follow-renames` rewrites them after staged renames and stages the events, never committing.
+*/
+const scopeCommand = {
+	name: "scope",
+	summary: "set, add or remove the globs of the code a decision governs",
+	usage: USAGE$2,
+	options: {
+		set: {
+			type: "string",
+			multiple: true
+		},
+		add: {
+			type: "string",
+			multiple: true
+		},
+		remove: {
+			type: "string",
+			multiple: true
+		},
+		clear: { type: "boolean" },
+		"follow-renames": { type: "boolean" },
+		...COMMIT_OPTIONS
+	},
+	positionals: {
+		min: 0,
+		max: 1,
+		names: ["decision"]
+	},
+	ref: "reject",
+	async run({ io, flags, values, positionals }) {
+		const input = positionals[0];
+		if (values["follow-renames"] === true) {
+			checkFollowRenames(values);
+			const log = await openForCli(io, flags);
+			const { actor, notes } = await resolveAttribution(log.git, { env: io.env });
+			const read = await readDecisions(log);
+			const before = new Map([...read.projection.views].map(([id, v]) => [id, v.applies_to]));
+			const renamed = (await stagedRenames(log.git)).length > 0;
+			const doc = await followScopeRenames(log, {
+				...input === void 0 ? {} : { id: input },
+				actor
+			}, { notes });
+			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,
+					followRenames: {
+						before,
+						renamed
+					}
+				}),
+				notes: doc.notes
+			};
+		}
+		const op = setOp(values);
+		if (input === void 0) throw new UsageError(`missing argument <decision>; usage: adr ${USAGE$2}`);
+		const log = await openForCli(io, flags);
+		const { actor, notes } = await resolveAttribution(log.git, { env: io.env });
+		const choice = commitChoice(values, { autoCommit: log.adr.autoCommit });
+		const read = await readDecisions(log);
+		const before = read.projection.views.get(resolveDecision(read, input))?.applies_to ?? [];
+		const doc = await scopeDecision(log, {
+			id: input,
+			op,
+			actor,
+			names: NAMES
+		}, {
+			...choice,
+			notes
+		});
+		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,
+				scopeBefore: before
 			}),
-			notes: [...doc.notes, ...notes]
+			notes: doc.notes
 		};
 	}
 };
@@ -384,21 +1088,21 @@ const showCommand = {
 			exit: 0,
 			json: doc,
 			text: showText(doc, display),
-			notes: doc.notes
+			notes: notesWith(doc.notes, numberingNote(read, { unavailable: false }))
 		};
 	}
 };
 // src/cli/supersede.ts
-const USAGE = "supersede <decision> --by <decision> [--reason <text>] [--commit | --no-commit]";
+const USAGE$1 = "supersede <decision> --by <decision> [--reason <text>] [--commit | --no-commit] [-m <message>]";
 /** `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,
+	usage: USAGE$1,
 	options: {
 		by: { type: "string" },
 		reason: { type: "string" },
-		commit: { type: "boolean" }
+		...COMMIT_OPTIONS
 	},
 	positionals: {
 		min: 1,
@@ -408,15 +1112,18 @@ const supersedeCommand = {
 	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}`);
+		if (typeof values.by !== "string") throw new UsageError(`missing --by <decision>; usage: adr ${USAGE$1}`);
 		const log = await openForCli(io, flags);
-		const actor = await resolveActor(log.git, { env: io.env });
+		const { actor, notes: attribution } = await resolveAttribution(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) });
+		}, {
+			...commitChoice(values, { autoCommit: log.adr.autoCommit }),
+			notes: attribution
+		});
 		const { display } = await displayAfterWrite(log);
 		const v = doc.decision;
 		return {
@@ -430,6 +1137,49 @@ const supersedeCommand = {
 		};
 	}
 };
+/** `adr withdraw` (design §6.4): a proposal its author takes back. */
+const withdrawCommand = {
+	name: "withdraw",
+	summary: "withdraw a proposed decision",
+	usage: "withdraw <decision> [--reason <text>] [--commit | --no-commit] [-m <message>]",
+	options: {
+		reason: { type: "string" },
+		...COMMIT_OPTIONS
+	},
+	positionals: {
+		min: 1,
+		max: 1,
+		names: ["decision"]
+	},
+	ref: "reject",
+	async run({ io, flags, values, positionals }) {
+		const input = positionals[0] ?? "";
+		if (typeof values.reason === "string" && values.reason.trim() === "") throw new UsageError("--reason must not be empty");
+		const reason = typeof values.reason === "string" ? values.reason.trim() : null;
+		const log = await openForCli(io, flags);
+		const { actor, notes } = await resolveAttribution(log.git, { env: io.env });
+		const doc = await withdrawDecision(log, {
+			id: input,
+			reason,
+			actor
+		}, {
+			...commitChoice(values, { autoCommit: log.adr.autoCommit }),
+			notes
+		});
+		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,
+				reason
+			}),
+			notes: doc.notes
+		};
+	}
+};
 // src/cli/commands.ts
 /**
 * ledger's shared `verify`: the log as the mode reads it (the index for `--staged`, else the
@@ -453,9 +1203,19 @@ function adrCli(version) {
 		version,
 		summary: "Architecture decision records kept as event logs in git.",
 		commands: [
+			initCommand,
 			newCommand,
 			acceptCommand,
+			rejectCommand,
+			withdrawCommand,
+			deprecateCommand,
 			supersedeCommand,
+			noteCommand,
+			linkCommand,
+			scopeCommand,
+			indexCommand,
+			hooksCommand,
+			forCommand,
 			listCommand,
 			showCommand,
 			verify