@nikovirtala/adr 0.1.0 → 0.2.0

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/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 { n as DECISION_STATUSES, t as adrKind } from "./kind-BcHjCHvi.js";
+import { C as initDecisionLog, S as unavailableReason, a as noteDecision, c as scopeDecision, d as withdrawDecision, f as adrChecks, g as showDecision, h as listDecisions, i as linkDecision, m as decisionsFor, n as deprecateDecision, o as proposeDecision, r as followScopeRenames, s as rejectDecision, t as acceptDecision, u as supersedeDecision, v as openDecisionLog, x as resolveDecision, y as readDecisions } from "./write-9IaqHRrY.js";
 import { createRequire } from "node:module";
-import { UsageError, renderStateHeader, resolveActor, templateHistoryRef } from "@nikovirtala/ledger";
-import { processIO, runCli, verifyCommand } from "@nikovirtala/ledger/cli";
+import { UsageError, renderStateHeader, resolveAttribution, stagedRenames, templateHistoryRef } from "@nikovirtala/ledger";
+import { COMMIT_OPTIONS, commitChoice, confirm, processIO, runCli, verifyCommand } from "@nikovirtala/ledger/cli";
 import { spawn } from "node:child_process";
 // src/cli/open.ts
 /**
@@ -27,10 +27,6 @@ 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) {
@@ -90,18 +86,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 +102,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);
 /**
-* 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.
+* `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 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 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 +244,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 +254,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(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 +338,171 @@ 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 {
+			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,
+				copied: doc.ok ? seen.offer : null
+			}),
+			notes: doc.notes
+		};
+	}
+};
+// src/cli/deprecate.ts
+const USAGE$4 = "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$4,
+	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$4}`);
+		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: 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 {
@@ -198,7 +510,7 @@ 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: null
 			}),
 			notes: doc.notes
 		};
@@ -283,7 +595,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 +615,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 +627,7 @@ const newCommand = {
 			multiple: true
 		},
 		edit: { type: "boolean" },
-		commit: { type: "boolean" }
+		...COMMIT_OPTIONS
 	},
 	positionals: {
 		min: 1,
@@ -325,10 +637,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 +653,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, ...notes]
+			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
 		};
 	}
 };
@@ -389,16 +922,16 @@ const showCommand = {
 	}
 };
 // 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 +941,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 +966,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 +1032,17 @@ 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,
+			forCommand,
 			listCommand,
 			showCommand,
 			verify