@nikovirtala/adr 0.1.0 → 0.3.0

package/dist/scope-CLqH-q1y.js

@@ -0,0 +1,2873 @@
+import { t as adrKind } from "./kind-DjvA3dyA.js";
+import { CommitFailedError, ConfigError, ENVELOPE_VERSION, EventExistsError, FileExistsError, InvalidArgumentError, MemoryTree, UsageError, anchorCheck, applySetOp, assertNoHookConflicts, bodyFileName, bodySha256, classifyPath, commitWithRecovery, compareEvents, compileKind, diffTrees, escapeMarkdown, eventDir, eventPath, exitCode, finding, foldChecks, foldLog, followRenames, gitTemplates, globMatcher, governedChanges, historyTemplates, hookSnippet, indexCheck, indexReader, installHooks, invariantsCheck, isSubjectId, lintDocument, lintTemplate, loadFindings, loadLog, narrowedScopes, newSubjectId, nextEventIdentity, numberLog, openToolLog, overlayTree, parseCommitTemplate, parseEventFileName, parseGlob, parseTemplate, projectLog, projectNumbering, readCommitTemplate, readIndexNumbers, readToolConfig, refReader, relateCheck, renderCommitMessage, renderIndex, renderTemplate, resolveAttribution, resolveSubjectInput, saveCommitRecovery, scanAnchors, scopeGlobCheck, scopeLookup, serializeEvent, slugify, sortFindings, stagedRenames, templateHistoryRef, transitions, uninstallHooks, verifyLog, worktreeReader, writeEvents, writeIndexFile, writeNewFile } from "@nikovirtala/ledger";
+import { access, constants, lstat, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { isAbsolute, join, posix, relative, resolve, sep } from "node:path";
+// src/commit-actions.ts
+/**
+* `{action}` of a commit that writes one event of each type (design §4.3), and what the title slot
+* names: the decision's title for the events that change whether it is decided, else its display.
+*/
+const ACTIONS = {
+	proposed: {
+		action: "propose to",
+		names: "title"
+	},
+	accepted: {
+		action: "decide to",
+		names: "title"
+	},
+	rejected: {
+		action: "decide not to",
+		names: "title"
+	},
+	withdrawn: {
+		action: "withdraw the proposal to",
+		names: "title"
+	},
+	deprecated: {
+		action: "deprecate",
+		names: "display"
+	},
+	superseded: {
+		action: "supersede",
+		names: "display"
+	},
+	noted: {
+		action: "add a note to",
+		names: "display"
+	},
+	linked: {
+		action: "link",
+		names: "display"
+	},
+	scoped: {
+		action: "set the scope of",
+		names: "display"
+	}
+};
+/** The longest `{action}`, which `[commit] subject` must leave room for. */
+const LONGEST_ACTION = Math.max(...Object.values(ACTIONS).map((a) => a.action.length), 10);
+/** What a link's title slot names after the display when the target is in another log. */
+const CROSS_LOG_LINK = "to a decision in another log";
+/** adr's commit-subject placeholders, each with its longest value (design §4.2). */
+const COMMIT_VARS = Object.freeze({
+	action: LONGEST_ACTION,
+	id: 8,
+	display: 13,
+	command: 9
+});
+/**
+* The names the title placeholder holds instead of a title, which are never shortened, each with
+* its action: supersede's `<display> with <display>` and a link's `<display> to <display>` or
+* `<display> to a decision in another log` (`planLink` in write.ts), and `adr index`'s
+* `the decision index`. The shorter names (a display, at most 13 characters) always fit in the
+* room a title gets.
+*/
+const COMMIT_NAMES = Object.freeze([
+	{
+		length: 32,
+		vars: { action: ACTIONS.superseded.action.length }
+	},
+	{
+		length: 42,
+		vars: { action: ACTIONS.linked.action.length }
+	},
+	{
+		length: 18,
+		vars: { action: 10 }
+	}
+]);
+// src/config.ts
+/** The default `[commit] subject`. */
+const DEFAULT_COMMIT_SUBJECT = "docs(adr): {action} {title}";
+const DEFAULT_ADR_CONFIG = Object.freeze({
+	defaultTemplate: "nygard",
+	mainBranch: null,
+	index: "none",
+	acceptRequiresHuman: true,
+	autoCommit: false,
+	mcpCanDecide: false,
+	failOn: "error",
+	governedByInactive: "warning",
+	scopeFollowRenames: "stage",
+	hookIndex: "check",
+	commitSubject: parseCommitTemplate(DEFAULT_COMMIT_SUBJECT, {
+		vars: COMMIT_VARS,
+		where: "commit.subject",
+		names: COMMIT_NAMES
+	}),
+	anchorKeyword: adrKind.anchorKeyword,
+	anchorExclude: Object.freeze([])
+});
+const TEMPLATE = /^[a-z][a-z0-9-]*$/;
+const KEYWORD = /^[a-z][a-z0-9-]{0,31}$/;
+const MAX_ANCHOR_EXCLUDE = 100;
+function isTable(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v) && !(v instanceof Date);
+}
+/**
+* Validates `adr.toml` (ledger's parsed `ToolConfig`; `null` when there is none). A wrong type or
+* value throws `ConfigError` naming the file and key. Unknown keys are ignored, so newer files
+* still load. `[log] root` is ledger's (`openToolLog` already checked it).
+*/
+function parseAdrConfig(config, file) {
+	if (config === null) return DEFAULT_ADR_CONFIG;
+	const where = file ?? config.file ?? "adr.toml";
+	const fail = (message) => new ConfigError(`${where}: ${message}`, { file: where });
+	const table = (name) => {
+		const t = config.raw[name];
+		if (t === void 0) return {};
+		if (!isTable(t)) throw fail(`${name} must be a table`);
+		return t;
+	};
+	const log = table("log");
+	const policy = table("policy");
+	const verify = table("verify");
+	const scope = table("scope");
+	const hooks = table("hooks");
+	const bool = (t, section, key, fallback) => {
+		const v = t[key];
+		if (v === void 0) return fallback;
+		if (typeof v !== "boolean") throw fail(`${section}.${key} must be true or false`);
+		return v;
+	};
+	const oneOf = (t, section, key, values, fallback) => {
+		const v = t[key];
+		if (v === void 0) return fallback;
+		if (typeof v !== "string" || !values.includes(v)) throw fail(`${section}.${key} must be ${values.map((x) => JSON.stringify(x)).join(" or ")}`);
+		return v;
+	};
+	const template = log.default_template;
+	if (template !== void 0 && (typeof template !== "string" || template.length > 64 || !TEMPLATE.test(template))) throw fail(`log.default_template must be a template name matching ${TEMPLATE.source}`);
+	const main = log.main_branch;
+	if (main !== void 0 && (typeof main !== "string" || main.trim() === "" || main.startsWith("-") || main.includes("\0"))) throw fail("log.main_branch must be a ref name that doesn't start with -");
+	const keyword = scope.anchor_keyword;
+	if (keyword !== void 0 && (typeof keyword !== "string" || !KEYWORD.test(keyword))) throw fail(`scope.anchor_keyword must match ${KEYWORD.source}`);
+	const exclude = scope.anchor_exclude;
+	if (exclude !== void 0) {
+		if (!Array.isArray(exclude) || exclude.length > MAX_ANCHOR_EXCLUDE) throw fail(`scope.anchor_exclude must be an array of at most ${MAX_ANCHOR_EXCLUDE} globs`);
+		exclude.forEach((g, i) => {
+			if (typeof g !== "string") throw fail(`scope.anchor_exclude[${i}] must be a string`);
+			const parsed = parseGlob(g);
+			if (!parsed.ok) throw fail(`scope.anchor_exclude[${i}]: ${parsed.message}`);
+		});
+	}
+	return {
+		defaultTemplate: typeof template === "string" ? template : DEFAULT_ADR_CONFIG.defaultTemplate,
+		mainBranch: typeof main === "string" ? main : null,
+		index: oneOf(log, "log", "index", ["committed", "none"], "none"),
+		acceptRequiresHuman: bool(policy, "policy", "accept_requires_human", true),
+		autoCommit: bool(policy, "policy", "auto_commit", false),
+		mcpCanDecide: bool(policy, "policy", "mcp_can_decide", false),
+		failOn: oneOf(verify, "verify", "fail_on", ["error", "warning"], "error"),
+		governedByInactive: oneOf(verify, "verify", "governed_by_inactive", ["warning", "error"], "warning"),
+		scopeFollowRenames: oneOf(hooks, "hooks", "scope_follow_renames", [
+			"stage",
+			"warn",
+			"off"
+		], "stage"),
+		hookIndex: oneOf(hooks, "hooks", "index", ["check", "stage"], "check"),
+		commitSubject: readCommitTemplate(config, {
+			file: where,
+			vars: COMMIT_VARS,
+			defaultSubject: DEFAULT_COMMIT_SUBJECT,
+			names: COMMIT_NAMES
+		}),
+		anchorKeyword: typeof keyword === "string" ? keyword : DEFAULT_ADR_CONFIG.anchorKeyword,
+		anchorExclude: Array.isArray(exclude) ? exclude : []
+	};
+}
+// src/log.ts
+/**
+* Opens the decision log (design D3): `--root`, else `adr.toml`'s `[log] root`, else `docs/adr`;
+* read from the `ref` tree, the index or the work tree.
+*/
+async function openDecisionLog(o) {
+	const log = await openToolLog({
+		...o,
+		tool: "adr",
+		kind: adrKind
+	});
+	return {
+		...log,
+		adr: parseAdrConfig(log.config, log.configPath)
+	};
+}
+/**
+* `numberLog` on the repository, then `readDecisionsFrom(log.tree, …)`. In a shallow clone of a
+* log with `[log] index = "committed"`, the numbers come from `<root>/index.md` in the commit
+* being read (`--ref`, else HEAD, resolved when the numbers are needed), never from the work tree's
+* copy, which may number acceptances that exist only there (design 2b D1, §4.6).
+*/
+async function readDecisions(log) {
+	return readDecisionsFrom(log.tree, {
+		layout: log.layout,
+		adr: log.adr,
+		numbering: await numberDecisions(log),
+		ref: log.ref,
+		commit: log.commit,
+		notes: log.notes
+	});
+}
+/** The display numbers `readDecisions` uses, with its shallow-clone fallback to `index.md`. */
+async function numberDecisions(log) {
+	return numberLog(log.git, {
+		kind: adrKind,
+		layout: log.layout,
+		mainRef: log.adr.mainBranch,
+		...log.adr.index === "committed" ? { fallback: async () => {
+			const c = await log.git.resolveCommit(log.ref ?? "HEAD");
+			return c === null ? null : readIndexNumbers(await refReader(log.git, c), `${log.layout.root}/index.md`);
+		} } : {}
+	});
+}
+const compiled$1 = compileKind(adrKind);
+/** The git-free core of `readDecisions`; tests pass a MemoryTree and a hand-made `Numbering`. */
+async function readDecisionsFrom(tree, o) {
+	const { layout, adr, numbering } = o;
+	const snapshot = await loadLog(tree, {
+		kind: compiled$1,
+		layout
+	});
+	const folded = foldLog(adrKind, snapshot);
+	const ctx = {
+		kind: compiled$1,
+		layout,
+		base: null,
+		head: snapshot,
+		changes: [],
+		scope: "all",
+		inScope: new Set(snapshot.subjects.keys()),
+		folded: {
+			head: folded,
+			base: null
+		}
+	};
+	const options = { acceptRequiresHuman: adr.acceptRequiresHuman };
+	const findings = [];
+	for (const check of [
+		loadFindings,
+		transitions,
+		invariantsCheck(options),
+		relateCheck(options)
+	]) findings.push(...await check.run(ctx));
+	return {
+		tree,
+		layout,
+		adr,
+		root: layout.root,
+		ref: o.ref ?? null,
+		commit: o.commit ?? null,
+		folded,
+		projection: projectLog(adrKind, folded, { numbering }),
+		numbering,
+		findings: sortFindings(findings.map((f) => ({
+			...f,
+			kind: adrKind.name
+		}))),
+		notes: o.notes ?? []
+	};
+}
+/**
+* The note a read command adds about where numbers come from: the shallow-clone index, or why
+* they are unavailable (`unavailable: false` leaves that one out); `null` for none.
+*/
+function numberingNote(read, o) {
+	const n = read.numbering;
+	if (n.reason === "index") return `numbers come from ${read.root}/index.md (shallow clone)`;
+	if (n.available || !o.unavailable) return null;
+	return n.reason === "shallow" ? "numbers are unavailable (shallow clone); run git fetch --unshallow, or commit an index with [log] index = \"committed\"" : `numbers are unavailable (${unavailableReason(n)}); decisions display by id`;
+}
+/** Why numbers are unavailable, in words: `shallow clone` or `no main branch`. */
+function unavailableReason(n) {
+	return n.reason === "shallow" ? "shallow clone" : "no main branch";
+}
+/**
+* The id a decision argument names: an id, or a number in any form `parseDecisionNumber` takes.
+* Throws `UsageError` (exit 2) naming the reason when it names nothing.
+*/
+function resolveDecision(read, input) {
+	const r = resolveSubjectInput(input, {
+		subjects: new Set(read.folded.subjects.keys()),
+		kind: adrKind,
+		numbering: read.numbering
+	});
+	if (r.ok) return r.id;
+	const shown = JSON.stringify(input.trim());
+	switch (r.reason) {
+		case "malformed": throw new UsageError(`invalid decision ${JSON.stringify(input)}`);
+		case "qualified": throw new UsageError(`decision ${shown} is in another log; cross-log references aren't supported yet`);
+		case "numbers-unavailable": throw new UsageError(`decision numbers are unavailable (${unavailableReason(read.numbering)}); use the decision's id instead of ${shown}`);
+		case "not-found": throw new UsageError(`unknown decision ${input.trim()}`);
+	}
+}
+/**
+* The event files in `--ref`'s tree (else HEAD's) that `rev`'s tree lacks (design 2b D7). Diffing
+* trees answers "what did this pull bring" for fast-forwards and merges (`ORIG_HEAD` is the tip
+* before them), and lists nothing for a rebase of your own work, whose events are in both trees.
+* Throws `RefNotFoundError` when either revision doesn't resolve.
+*/
+async function changedSince(log, rev) {
+	const base = await refReader(log.git, rev);
+	const head = await refReader(log.git, log.ref ?? "HEAD");
+	const events = (await diffTrees(base, head, `${log.layout.root}/${log.layout.events}`)).flatMap((c) => {
+		if (c.status !== "added") return [];
+		const p = classifyPath(log.layout, c.path);
+		if (p.area !== "event" || p.subject === null || p.file.includes("/")) return [];
+		const name = parseEventFileName(p.file);
+		return name === null ? [] : [{
+			subject: p.subject,
+			type: name.type,
+			path: c.path
+		}];
+	});
+	events.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+	return {
+		rev,
+		commit: base.commit ?? "",
+		events
+	};
+}
+// src/log-index.ts
+/**
+* What the recovery hint says about rerunning `adr index --commit` after `git commit` failed
+* (design 2b D5). It names the file, not the path, which the hint lists above it.
+*/
+const INDEX_RERUN = "You can also run adr index --commit again once git accepts the commit; it commits index.md while it differs from HEAD's.";
+/**
+* The step before the manual commit when a write's second index render failed after staging
+* (design 2b §4.5 step 4).
+*/
+const INDEX_BEFORE = (root) => `Run adr index --no-commit first; it writes and stages ${root}/index.md from the work tree. If other decisions in ${root} have uncommitted changes, the work tree's index includes them; append their paths after -- in the command below, so the commit matches the index.`;
+/**
+* The step after the manual commit when the commit carried the index: the commit's render leaves
+* out other decisions' uncommitted entries (design 2b D5, §4.5 step 5).
+*/
+const INDEX_AFTER = (root) => `Then run adr index --no-commit to restore other decisions' entries in ${root}/index.md.`;
+/** The repo-relative path of a log's generated index. */
+const indexPath = (layout) => `${layout.root}/index.md`;
+const GROUPS = [
+	{
+		heading: "Accepted",
+		statuses: ["accepted"]
+	},
+	{
+		heading: "Proposed",
+		statuses: ["proposed"]
+	},
+	{
+		heading: "Superseded and deprecated",
+		statuses: ["superseded", "deprecated"]
+	},
+	{
+		heading: "Rejected and withdrawn",
+		statuses: ["rejected", "withdrawn"]
+	}
+];
+const cmp = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+/**
+* adr's index spec (01:209: active decisions first), built per render so that a superseded
+* decision's status can name its successor's display from `views`.
+*/
+const DECISION_INDEX = (root, views) => ({
+	tool: "adr",
+	title: "Architecture decisions",
+	groups: GROUPS.map((g) => ({
+		heading: g.heading,
+		filter: (v) => g.statuses.includes(v.status)
+	})),
+	columns: [
+		{
+			heading: "Decision",
+			cell: (v) => escapeMarkdown(v.display)
+		},
+		{
+			heading: "Title",
+			cell: (v) => v.body_path === null ? escapeMarkdown(v.title) : `[${escapeMarkdown(v.title)}](${encodeURI(posix.relative(root, v.body_path))})`
+		},
+		{
+			heading: "Status",
+			cell: (v) => v.status === "superseded" && v.superseded_by !== null ? `superseded by ${escapeMarkdown(views.get(v.superseded_by)?.display ?? v.superseded_by)}` : v.status
+		},
+		{
+			heading: "Since",
+			cell: (v) => v.status_at.slice(0, 10)
+		}
+	],
+	order: (a, b) => (a.number ?? Number.POSITIVE_INFINITY) - (b.number ?? Number.POSITIVE_INFINITY) || cmp(a.status_at, b.status_at) || cmp(a.id, b.id)
+});
+/**
+* The index `tree` must hold: its decisions, numbered as they will be once the commit holding
+* `tree` (which builds on `history`: HEAD, a commit, or null on an unborn HEAD) is on main
+* (design 2b D2), with `[log] main_branch`'s numbers first. A tree that isn't a commit's (the work
+* tree, the index) also merges `MERGE_HEAD` while a merge is in progress. In a shallow clone the
+* numbers continue from those `history`'s index recorded; `null` when there are none, so the
+* numbers can't be projected.
+*/
+async function renderDecisionIndex(git, o) {
+	const { layout, history } = o;
+	const mergeHead = o.tree.commit === null && history !== null ? await git.resolveCommit("MERGE_HEAD") : null;
+	const numbering = await projectNumbering(git, {
+		kind: adrKind,
+		layout,
+		history,
+		tree: o.tree,
+		mainRef: o.adr.mainBranch,
+		merging: mergeHead === null ? [] : [mergeHead],
+		recorded: async () => history === null ? null : readIndexNumbers(await refReader(git, history), indexPath(layout))
+	});
+	if (!numbering.available) return null;
+	const views = (await readDecisionsFrom(o.tree, {
+		layout,
+		adr: o.adr,
+		numbering
+	})).projection.views;
+	return renderIndex(DECISION_INDEX(layout.root, views), [...views.values()], numbering);
+}
+/** At most this many paths are named in the unstaged-files `index/stale` message. */
+const UNSTAGED_NAMED = 5;
+/**
+* What the unstaged-files `index/stale` finding and the matching write note both start with:
+* `path` lists `files` (some of them), which aren't staged.
+*/
+function unstagedIndexText(path, files) {
+	return `${path} lists decision files that aren't staged (${files.slice(0, UNSTAGED_NAMED).join(", ")}${files.length > UNSTAGED_NAMED ? ", …" : ""})`;
+}
+/**
+* The log's event and body files whose work-tree content isn't staged (untracked or modified),
+* sorted: the cause of a staged `index.md` that only the work tree's render matches.
+*/
+async function unstagedLogFiles(git, layout) {
+	const paths = [...await git.unstagedPaths([layout.root]), ...await git.untrackedPaths([layout.root])];
+	return [...new Set(paths)].filter((p) => {
+		const area = classifyPath(layout, p).area;
+		return area === "event" || area === "body";
+	}).sort();
+}
+/**
+* The verify check that `<root>/index.md` is current (design 2b §4.5, "Freshness in verify"). In
+* staged mode (the pre-commit hook), a stale staged copy that equals the work tree's render
+* means another decision's files aren't staged: writes stage the work tree's render (D2), and
+* `adr index` would change nothing. The finding then names those files and says to stage them.
+*/
+function decisionIndexCheck(log) {
+	const path = indexPath(log.layout);
+	const check = indexCheck({
+		path,
+		fix: "run adr index",
+		async expected(ctx) {
+			const head = ctx.repo?.head;
+			const history = head === void 0 ? null : typeof head === "object" ? head.commit : await log.git.resolveCommit("HEAD");
+			return renderDecisionIndex(log.git, {
+				layout: log.layout,
+				adr: log.adr,
+				tree: ctx.head.tree,
+				history
+			});
+		}
+	});
+	return {
+		id: check.id,
+		async run(ctx) {
+			const findings = await check.run(ctx);
+			const stale = findings.find((f) => f.rule === "index/stale");
+			if (stale === void 0 || ctx.repo?.head !== "index") return findings;
+			const files = await unstagedLogFiles(log.git, log.layout);
+			if (files.length === 0) return findings;
+			const worktree = await renderDecisionIndex(log.git, {
+				layout: log.layout,
+				adr: log.adr,
+				tree: worktreeReader(log.git),
+				history: await log.git.resolveCommit("HEAD")
+			});
+			if (worktree === null || !holdsText(await ctx.head.tree.read(path), worktree)) return findings;
+			const message = `${unstagedIndexText(path, files)}; git add them and commit again, or move them out of the work tree and run adr index`;
+			return findings.map((f) => f === stale ? {
+				...f,
+				message
+			} : f);
+		}
+	};
+}
+const encoder$2 = new TextEncoder();
+/** Whether `bytes` (null: absent) hold exactly `text`. */
+function holdsText(bytes, text) {
+	if (bytes === null) return false;
+	const want = encoder$2.encode(text);
+	return bytes.byteLength === want.byteLength && bytes.every((x, i) => x === want[i]);
+}
+/** HEAD's copy of `path`; `null` when it is absent or HEAD is unborn. */
+async function headBytes(git, path) {
+	const head = await git.resolveCommit("HEAD");
+	return head === null ? null : (await refReader(git, head)).read(path);
+}
+/** HEAD's tree, or an empty tree on an unborn HEAD. */
+async function headTree(git, head) {
+	return head === null ? new MemoryTree({}) : refReader(git, head);
+}
+/**
+* Brings the work-tree copy of `path` to `text` (atomically, when it differs) and reports whether
+* the staged copy differs, so the caller stages it. `old` is the work-tree copy before the write
+* (`null` when absent), for rollback.
+*/
+async function writeIndexCopy(git, path, text) {
+	const old = await worktreeReader(git).read(path);
+	return {
+		wrote: !holdsText(old, text) && await writeIndexFile(git, path, text),
+		old,
+		stage: !holdsText(await (await indexReader(git)).read(path), text)
+	};
+}
+/** The first line of an error's message, for notes and headlines. */
+const firstLine = (err) => (err instanceof Error ? err.message : String(err)).split("\n")[0] ?? "";
+/**
+* `adr index` (design 2b §4.5) with what the text output needs; `indexDecisionLog` is the
+* library entry.
+*/
+async function runDecisionIndex(log, o = {}) {
+	const path = indexPath(log.layout);
+	const root = log.layout.root;
+	const check = o.check === true;
+	const notes = [...log.notes, ...o.notes ?? []];
+	if (log.adr.index !== "committed") throw new UsageError("adr index needs [log] index = \"committed\" in adr.toml");
+	if (check) {
+		if (o.commit === true || o.message !== void 0 && o.message !== null) throw new UsageError("--check writes nothing; drop --commit and --message");
+		const findings = await verifyLog({
+			git: log.git,
+			kind: adrKind,
+			layout: log.layout,
+			mode: {
+				type: "full",
+				...log.ref === null ? {} : { head: log.ref }
+			},
+			checks: [decisionIndexCheck(log)]
+		});
+		return {
+			doc: {
+				format: "adr-index/v1",
+				path,
+				check: true,
+				fresh: findings.length === 0,
+				written: [],
+				commit: null,
+				findings,
+				notes
+			},
+			refreshed: false
+		};
+	}
+	if (log.ref !== null || log.tree.label !== "worktree") throw new UsageError("adr index writes the work tree; use --ref only with --check");
+	const { git } = log;
+	const commit = o.commit ?? log.adr.autoCommit;
+	if (commit && (await git.identity() === null || await git.committerIdentity() === null)) throw new ConfigError("--commit needs a git identity; set git user.name and user.email");
+	const head = await git.resolveCommit("HEAD");
+	const render = (tree, history) => renderDecisionIndex(git, {
+		layout: log.layout,
+		adr: log.adr,
+		tree,
+		history
+	});
+	const shallow = () => new UsageError("numbers need history in this shallow clone; run git fetch --unshallow");
+	let written = false;
+	const place = async (text) => {
+		const r = await writeIndexCopy(git, path, text);
+		if (r.stage) await git.add([path]);
+		written ||= r.wrote;
+		return r.wrote || r.stage;
+	};
+	if (!commit) {
+		const text = await render(worktreeReader(git), head);
+		if (text === null) throw shallow();
+		return {
+			doc: {
+				format: "adr-index/v1",
+				path,
+				check: false,
+				fresh: !await place(text),
+				written: written ? [path] : [],
+				commit: null,
+				findings: [],
+				notes
+			},
+			refreshed: false
+		};
+	}
+	const text = await render(await headTree(git, head), head);
+	if (text === null) throw shallow();
+	const fresh = holdsText(await headBytes(git, path), text);
+	let sha = null;
+	if (!fresh) {
+		await place(text);
+		const message = o.message ?? renderCommitMessage(log.adr.commitSubject, {
+			title: "the decision index",
+			vars: {
+				action: "regenerate",
+				id: "index.md",
+				display: "index.md",
+				command: "index"
+			}
+		}).message;
+		sha = await commitWithRecovery(git, {
+			message,
+			only: [path],
+			rerun: INDEX_RERUN,
+			after: INDEX_AFTER(root)
+		});
+	}
+	let refreshed = false;
+	try {
+		const again = await render(worktreeReader(git), sha ?? head);
+		if (again !== null) refreshed = await place(again);
+	} catch (err) {
+		notes.push(`${path} may be stale: ${firstLine(err)}; run adr index`);
+	}
+	return {
+		doc: {
+			format: "adr-index/v1",
+			path,
+			check: false,
+			fresh,
+			written: written ? [path] : [],
+			commit: sha,
+			findings: [],
+			notes
+		},
+		refreshed
+	};
+}
+/**
+* `adr index [--check] [--commit | --no-commit] [-m <message>]` (design 2b §4.5): renders
+* `<root>/index.md` and writes and stages it where the work tree or the index differ. With
+* `commit` (default `[policy] auto_commit`) it renders HEAD's tree and commits the file alone when
+* HEAD's copy differs, then refreshes the work tree's copy, which may include other decisions'
+* uncommitted entries. `check` writes nothing and reports `index/*` findings.
+*/
+async function indexDecisionLog(log, o = {}) {
+	return (await runDecisionIndex(log, o)).doc;
+}
+// src/verify.ts
+/** At most this many paths are named in a `decision/scope-narrowed` message. */
+const NARROWED_PATHS = 3;
+/** The head's decision views with the read's numbering, for the displays in messages. */
+async function headViews(log, ctx) {
+	const head = ctx.folded?.head;
+	if (head === void 0) return /* @__PURE__ */ new Map();
+	return projectLog(adrKind, head, { numbering: await numberDecisions(log) }).views;
+}
+/**
+* `decision/governed-by-inactive` (`[verify] governed_by_inactive`, default warning): a changed
+* code file that a superseded or deprecated decision governs, by glob or anchor (01:366).
+*/
+function governedByInactive(log) {
+	return {
+		id: "decision-governed-by-inactive",
+		async run(ctx) {
+			const changes = await governedChanges(ctx, {
+				keyword: log.adr.anchorKeyword,
+				exclude: log.adr.anchorExclude,
+				statuses: ["superseded", "deprecated"]
+			});
+			if (changes.length === 0) return [];
+			const views = await headViews(log, ctx);
+			const display = (id) => views.get(id)?.display ?? id;
+			const message = (c) => {
+				const what = `${c.path} is governed by ${display(c.subject)}`;
+				if (c.status === "deprecated") return `${what}, which is deprecated; check whether the change still needs it`;
+				const next = views.get(c.subject)?.superseded_by ?? null;
+				return next === null ? `${what}, which is superseded; check the change against its successor` : `${what}, which is superseded by ${display(next)}; check the change against ${display(next)}`;
+			};
+			return changes.map((c) => finding({
+				severity: log.adr.governedByInactive,
+				rule: "decision/governed-by-inactive",
+				message: message(c),
+				file: c.path,
+				subject: c.subject
+			}));
+		}
+	};
+}
+/**
+* `decision/scope-narrowed` (warning): an accepted decision whose new scope stops covering files
+* that still exist (01:367), which calls for a check against its Scope section.
+*/
+function scopeNarrowed(log) {
+	return {
+		id: "decision-scope-narrowed",
+		async run(ctx) {
+			const narrowed = await narrowedScopes(ctx, { statuses: ["accepted"] });
+			if (narrowed.length === 0) return [];
+			const views = await headViews(log, ctx);
+			return narrowed.map((n) => {
+				const count = n.lost.length;
+				const files = count === 1 ? "1 file that still exists" : `${count} files that still exist`;
+				const named = n.lost.slice(0, NARROWED_PATHS).join(", ");
+				const more = count > NARROWED_PATHS ? ", …" : "";
+				return finding({
+					severity: "warning",
+					rule: "decision/scope-narrowed",
+					message: `${views.get(n.subject)?.display ?? n.subject}'s scope no longer covers ${files} (${named}${more}); check the change against its Scope section`,
+					file: n.file,
+					subject: n.subject
+				});
+			});
+		}
+	};
+}
+/**
+* Every check for the log: ledger's mechanical and fold checks with adr's actor policy, template
+* lint against the templates in the head tree and, for older versions, the history of
+* `historyRef`, the scope-glob and anchor checks, and the decision checks over code
+* (`decision/governed-by-inactive`, `decision/scope-narrowed`). With `[log] index = "committed"`,
+* also the freshness of `<root>/index.md`.
+*/
+function adrChecks(log, historyRef) {
+	return [
+		...foldChecks(adrKind, {
+			options: { acceptRequiresHuman: log.adr.acceptRequiresHuman },
+			templates: gitTemplates(log.git, { historyRef })
+		}),
+		scopeGlobCheck(),
+		anchorCheck({
+			keyword: log.adr.anchorKeyword,
+			exclude: log.adr.anchorExclude
+		}),
+		governedByInactive(log),
+		scopeNarrowed(log),
+		...log.adr.index === "committed" ? [decisionIndexCheck(log)] : []
+	];
+}
+/** Verifies the decision log in `mode` (staged, range or full) with `adrChecks`. */
+async function verifyDecisions(log, mode) {
+	return verifyLog({
+		git: log.git,
+		kind: adrKind,
+		layout: log.layout,
+		mode,
+		checks: adrChecks(log, await templateHistoryRef(log.git, mode))
+	});
+}
+/** The built-in templates by name: the file text `adr new` materializes. */
+const BUILTIN_TEMPLATES = Object.freeze({
+	nygard: `---
+template: nygard
+version: 1
+sections:
+  - id: context
+    heading: Context
+    required: true
+    guidance: What is the issue that motivates this decision? Describe the forces at play.
+  - id: decision
+    heading: Decision
+    required: true
+    guidance: What is the change that we're proposing or doing? Write it in the active voice.
+  - id: scope
+    heading: Scope
+    required: true
+    guidance: What does this decision govern? Name the systems, code paths or teams it applies to.
+  - id: consequences
+    heading: Consequences
+    required: true
+    guidance: What becomes easier or harder because of this change? Include the risks.
+---
+# {{title}}
+
+## Context
+{{context}}
+
+## Decision
+{{decision}}
+
+## Scope
+{{scope}}
+
+## Consequences
+{{consequences}}
+`,
+	madr: `---
+template: madr
+version: 1
+sections:
+  - id: context
+    heading: Context and Problem Statement
+    required: true
+    guidance: Describe the context and the problem in two or three sentences, or as a question.
+  - id: drivers
+    heading: Decision Drivers
+    required: false
+    guidance: List the forces and concerns that shape the decision.
+  - id: options
+    heading: Considered Options
+    required: true
+    guidance: List the options that were considered, one per line.
+  - id: decision
+    heading: Decision Outcome
+    required: true
+    guidance: Name the chosen option and say why it was chosen.
+  - id: scope
+    heading: Scope
+    required: true
+    guidance: What does this decision govern? Name the systems, code paths or teams it applies to.
+  - id: consequences
+    heading: Consequences
+    required: true
+    guidance: Describe the good and the bad consequences of the chosen option.
+---
+# {{title}}
+
+## Context and Problem Statement
+{{context}}
+
+## Decision Drivers
+{{drivers}}
+
+## Considered Options
+{{options}}
+
+## Decision Outcome
+{{decision}}
+
+## Scope
+{{scope}}
+
+## Consequences
+{{consequences}}
+`,
+	"y-statement": `---
+template: y-statement
+version: 1
+sections:
+  - id: statement
+    heading: Statement
+    required: true
+    guidance: In the context of <use case>, facing <concern>, we decided for <option>, to achieve <quality>, accepting <downside>.
+  - id: scope
+    heading: Scope
+    required: true
+    guidance: What does this decision govern? Name the systems, code paths or teams it applies to.
+---
+# {{title}}
+
+## Statement
+{{statement}}
+
+## Scope
+{{scope}}
+`
+});
+// src/write.ts
+const encoder$1 = new TextEncoder();
+const decoder$1 = new TextDecoder();
+const compiled = compileKind(adrKind);
+const TEMPLATE_NAME = /^[a-z][a-z0-9-]*$/;
+const MAX_TEXT_BYTES = 65536;
+const SUBJECT_ATTEMPTS = 5;
+const QUALIFIED_SUPERSESSION = "cross-log supersession isn't supported yet";
+const sorted = (xs) => [...new Set(xs)].sort();
+const templatePath = (read, name) => `${read.root}/templates/${name}.md`;
+/** A text argument within the 64 KiB cap and without NUL characters, else `UsageError`. */
+function checkText(what, text) {
+	if (text.includes("\0")) throw new UsageError(`${what} must not contain NUL characters`);
+	const size = encoder$1.encode(text).byteLength;
+	if (size > MAX_TEXT_BYTES) throw new UsageError(`${what} is ${size} bytes; the limit is ${MAX_TEXT_BYTES} (64 KiB)`);
+}
+function checkReason(reason) {
+	if (reason === void 0 || reason === null) return null;
+	const r = reason.trim();
+	if (r === "") throw new UsageError("--reason must not be empty");
+	checkText("--reason", r);
+	return r;
+}
+/** The view of a folded decision, else `UsageError` naming why it can't be used. */
+function viewOf(read, id) {
+	const view = read.projection.views.get(id);
+	if (view !== void 0) return view;
+	if (read.projection.unreadable.includes(id)) throw new UsageError(`decision ${id} uses a newer format; upgrade adr`);
+	throw new UsageError(`decision ${id} can't be read; run adr verify`);
+}
+/** A refusal finding about decision `subject`, on its body (or events directory). */
+function refusal(read, rule, message, subject) {
+	const loaded = read.folded.subjects.get(subject)?.loaded;
+	return finding({
+		severity: "error",
+		rule,
+		message,
+		file: loaded?.bodyPaths[0] ?? eventDir(read.layout, subject),
+		subject,
+		kind: adrKind.name
+	});
+}
+/** `"<type> is not allowed while <status>[; <status> is terminal]"`, as the fold words it. */
+function illegal(type, status) {
+	return `${type} is not allowed while ${status}${adrKind.machine.terminal.includes(status) ? `; ${status} is terminal` : ""}`;
+}
+/** A new event of `subject`, sorting after its existing ones. */
+function newEvent(read, c, o) {
+	const existing = (read.folded.subjects.get(o.subject)?.loaded.events ?? []).flatMap((e) => e.event === null ? [] : [e.event]);
+	const { at, id } = nextEventIdentity([...existing, ...o.after ?? []], {
+		now: c.now,
+		...c.random === void 0 ? {} : { random: c.random }
+	});
+	return {
+		envelope: ENVELOPE_VERSION,
+		kind: adrKind.name,
+		schema: adrKind.schema,
+		id,
+		subject: o.subject,
+		type: o.type,
+		at,
+		actor: o.actor,
+		...o.reason === void 0 || o.reason === null ? {} : { reason: o.reason },
+		data: o.data
+	};
+}
+/** Body, events directory and recorded template of each involved subject (D6). */
+function commitScope(read, involved, extra = {}) {
+	const paths = [];
+	const dirs = [];
+	for (const id of involved) {
+		const view = read.projection.views.get(id);
+		if (view?.body_path !== null && view?.body_path !== void 0) paths.push(view.body_path);
+		if (view !== void 0) paths.push(templatePath(read, view.template.name));
+		dirs.push(eventDir(read.layout, id));
+	}
+	if (extra.body !== void 0) paths.push(extra.body);
+	if (extra.template !== void 0) paths.push(extra.template);
+	return {
+		scope: sorted([...paths, ...dirs]),
+		eventDirs: sorted(dirs)
+	};
+}
+const findingKey = (f) => [
+	f.rule,
+	f.subject ?? "",
+	f.file ?? "",
+	f.message
+].join("\0");
+/**
+* The precheck (§6.3): folds the would-be log and refuses when the write adds any finding. Problems
+* that were already there don't block; the write can only add findings about what it touches.
+*/
+async function precheck(read, files) {
+	const after = await readDecisionsFrom(overlayTree(read.tree, files), {
+		layout: read.layout,
+		adr: read.adr,
+		numbering: read.numbering,
+		ref: read.ref,
+		commit: read.commit,
+		notes: read.notes
+	});
+	const before = new Set(read.findings.map(findingKey));
+	return {
+		after,
+		added: after.findings.filter((f) => !before.has(findingKey(f)))
+	};
+}
+function filesOf(events, read) {
+	return Object.fromEntries(events.map((e) => [eventPath(read.layout, e), encoder$1.encode(serializeEvent(e))]));
+}
+const pairsOf = (events) => events.flatMap((e) => [["ADR", e.subject], ["ADR-Event", e.type]]);
+/** The template `new` uses: the repo's `<root>/templates/<name>.md`, else a built-in to copy. */
+async function chooseTemplate(read, name, c) {
+	if (name.length > 64 || !TEMPLATE_NAME.test(name)) throw new UsageError(`invalid template name ${JSON.stringify(name)}`);
+	const path = templatePath(read, name);
+	const bytes = await read.tree.read(path);
+	let text;
+	let materialize = null;
+	if (bytes !== null) text = decoder$1.decode(bytes);
+	else {
+		const builtin = Object.hasOwn(c.builtins, name) ? c.builtins[name] : void 0;
+		if (builtin === void 0) {
+			const known = Object.keys(c.builtins).sort().join(", ");
+			throw new UsageError(`unknown template ${name}; add ${path} or use one of ${known}`);
+		}
+		text = builtin;
+		materialize = builtin;
+	}
+	const parsed = parseTemplate(text, { path });
+	if (!parsed.ok) return {
+		ok: false,
+		findings: parsed.findings
+	};
+	const lint = lintTemplate(parsed.template, { requireSections: adrKind.def.templates?.requireSections ?? [] });
+	if (lint.length > 0) return {
+		ok: false,
+		findings: lint
+	};
+	return {
+		ok: true,
+		template: parsed.template,
+		materialize,
+		path
+	};
+}
+/**
+* Plans `adr new`: a rendered body, a materialized template if needed, and `proposed`. With
+* `refuseIncomplete` (a commit with no editor to fill the draft in, design §7.2), a draft that
+* fails the template lint is refused with those findings before any file is planned.
+*/
+async function planPropose(read, input, c, o = {}) {
+	const title = input.title.trim();
+	if (title === "" || title.length > 200 || /[\r\n]/.test(title)) throw new UsageError("the title must be a single line of 1 to 200 characters");
+	const supersedes = sorted((input.supersedes ?? []).map((s) => {
+		if (s.includes(":")) throw new UsageError(`cannot supersede ${s.trim()}: ${QUALIFIED_SUPERSESSION}`);
+		return resolveDecision(read, s);
+	}));
+	const chosen = await chooseTemplate(read, input.template ?? read.adr.defaultTemplate, c);
+	if (!chosen.ok) return {
+		ok: false,
+		decision: null,
+		findings: chosen.findings
+	};
+	const t = chosen.template;
+	const sections = input.sections ?? {};
+	for (const [id, text] of Object.entries(sections)) {
+		if (!t.sections.some((s) => s.id === id)) {
+			const ids = t.sections.map((s) => s.id).join(", ");
+			throw new UsageError(`template ${t.name} has no section ${id}; its sections are ${ids}`);
+		}
+		checkText(`section ${id}`, text);
+	}
+	const rendered = renderTemplate(t, {
+		title,
+		sections
+	}, { missing: "guidance" });
+	if (!rendered.ok) throw new UsageError(rendered.findings.map((f) => f.message).join("; "));
+	let id = "";
+	let bodyPath = "";
+	for (let attempt = 0;; attempt++) {
+		id = newSubjectId(c.random);
+		bodyPath = `${read.root}/${read.layout.bodies}/${bodyFileName(id, slugify(title))}`;
+		if (!read.folded.subjects.has(id) && await read.tree.read(bodyPath) === null) break;
+		if (attempt + 1 >= SUBJECT_ATTEMPTS) throw new FileExistsError(bodyPath);
+	}
+	const lint = lintDocument(t, rendered.text, {
+		file: bodyPath,
+		subject: id
+	});
+	if (o.refuseIncomplete === true && lint.length > 0) return {
+		ok: false,
+		decision: null,
+		findings: lint
+	};
+	const event = newEvent(read, c, {
+		subject: id,
+		type: "proposed",
+		data: {
+			title,
+			template: t.name,
+			template_version: t.version,
+			...supersedes.length === 0 ? {} : { supersedes }
+		},
+		actor: input.actor
+	});
+	const body = encoder$1.encode(rendered.text);
+	const files = { [bodyPath]: body };
+	if (chosen.materialize !== null) files[chosen.path] = encoder$1.encode(chosen.materialize);
+	Object.assign(files, filesOf([event], read));
+	const { after, added } = await precheck(read, files);
+	if (added.length > 0) return {
+		ok: false,
+		decision: null,
+		findings: added
+	};
+	const { scope, eventDirs } = commitScope(read, [id], {
+		body: bodyPath,
+		template: chosen.path
+	});
+	return {
+		ok: true,
+		plan: {
+			command: "new",
+			subject: id,
+			files,
+			events: [event],
+			stage: Object.keys(files),
+			involved: [id],
+			commitScope: scope,
+			eventDirs,
+			draft: {
+				path: bodyPath,
+				rendered: body,
+				template: t
+			},
+			commit: {
+				action: ACTIONS.proposed.action,
+				title,
+				id,
+				display: id,
+				body: []
+			},
+			trailers: pairsOf([event]),
+			decision: viewOf(after, id),
+			affected: [],
+			findings: lint
+		}
+	};
+}
+/** The draft lint of an `accept`: the body against the template version its proposal recorded. */
+async function acceptLint(read, view, c) {
+	const body = read.folded.subjects.get(view.id)?.loaded.body ?? null;
+	if (body === null) return {
+		findings: [refusal(read, "body/missing", "body file is missing", view.id)],
+		bytes: null
+	};
+	const { name, version } = view.template;
+	const found = await c.templates.get(name, version);
+	if (!found.ok) {
+		const message = found.reason === "not-found" ? `template ${name} not found at ${found.path}` : `template ${name} has no version ${version} at ${found.path}`;
+		return {
+			findings: [refusal(read, `template/${found.reason}`, message, view.id)],
+			bytes: body.bytes
+		};
+	}
+	let text;
+	try {
+		text = new TextDecoder("utf-8", { fatal: true }).decode(body.bytes);
+	} catch {
+		return {
+			findings: [refusal(read, "body/not-utf8", "body is not valid UTF-8", view.id)],
+			bytes: body.bytes
+		};
+	}
+	return {
+		findings: lintDocument(found.template, text, {
+			file: body.path,
+			subject: view.id
+		}).map((f) => ({
+			...f,
+			kind: adrKind.name
+		})),
+		bytes: body.bytes
+	};
+}
+/** Plans `adr accept`: `accepted` with the body hash, and `superseded` on each declared target. */
+async function planAccept(read, input, c, o = {}) {
+	const id = resolveDecision(read, input.id);
+	const view = viewOf(read, id);
+	const refused = (findings) => ({
+		ok: false,
+		decision: view,
+		findings
+	});
+	const findings = [];
+	if (view.status !== "proposed") findings.push(refusal(read, "transition/illegal", illegal("accepted", view.status), id));
+	const lint = await acceptLint(read, view, c);
+	findings.push(...lint.findings);
+	if (read.adr.acceptRequiresHuman && input.actor.kind === "agent") findings.push(refusal(read, "decision/agent-accepted", `accepted by agent ${input.actor.name}; accept_requires_human needs a human`, id));
+	const targets = [];
+	for (const target of view.declared_supersedes) {
+		if (target.includes(":")) {
+			findings.push(refusal(read, "decision/reference-missing", `supersedes ${target}: ${QUALIFIED_SUPERSESSION}`, id));
+			continue;
+		}
+		const t = read.projection.views.get(target);
+		if (t === void 0) findings.push(refusal(read, "decision/reference-missing", `supersedes ${target}, which is not in the log`, id));
+		else if (target === id) findings.push(refusal(read, "decision/supersession-cycle", `supersession cycle: ${id} → ${id}`, id));
+		else if (t.status !== "accepted" && t.status !== "deprecated") findings.push(refusal(read, "transition/illegal", illegal("superseded", t.status), target));
+		else targets.push(target);
+	}
+	if (findings.length > 0 || lint.bytes === null) return refused(findings);
+	const accepted = newEvent(read, c, {
+		subject: id,
+		type: "accepted",
+		data: { body_sha256: bodySha256(lint.bytes) },
+		actor: input.actor
+	});
+	const cascade = targets.map((target) => newEvent(read, c, {
+		subject: target,
+		type: "superseded",
+		data: { by: id },
+		actor: input.actor
+	}));
+	const copyGlobs = o.copyGlobs ?? [];
+	const copied = copyGlobs.length === 0 ? null : newEvent(read, c, {
+		subject: id,
+		type: "scoped",
+		data: { set: [...applySetOp(view.applies_to, { add: copyGlobs }, {
+			what: "glob",
+			maxItems: 200
+		}).set] },
+		actor: input.actor,
+		after: [accepted]
+	});
+	if (copied !== null) {
+		const valid = compiled.validate(copied, { file: null });
+		if (!valid.ok) return refused(valid.findings.map((f) => ({
+			...f,
+			subject: id,
+			kind: adrKind.name
+		})));
+	}
+	const sources = copied === null ? [] : scopeToCopy(read, id).sources;
+	const events = [
+		accepted,
+		...copied === null ? [] : [copied],
+		...cascade
+	];
+	const files = filesOf(events, read);
+	const { after, added } = await precheck(read, files);
+	if (added.length > 0) return refused(added);
+	const involved = sorted([id, ...targets]);
+	const { scope, eventDirs } = commitScope(read, involved);
+	const bodyPath = view.body_path ?? "";
+	return {
+		ok: true,
+		plan: {
+			command: "accept",
+			subject: id,
+			files,
+			events,
+			stage: [...Object.keys(files), bodyPath],
+			involved,
+			commitScope: scope,
+			eventDirs,
+			draft: null,
+			commit: {
+				action: ACTIONS.accepted.action,
+				title: view.title,
+				id,
+				display: view.display,
+				body: [...targets.map((t) => {
+					const v = viewOf(read, t);
+					return `Supersedes ${v.display}: ${sentenceTitle(v.title)}.`;
+				}), ...sources.map((t) => `Copies the scope of ${viewOf(read, t).display}.`)]
+			},
+			trailers: pairsOf(events),
+			decision: viewOf(after, id),
+			affected: targets.map((t) => viewOf(after, t)),
+			findings: []
+		}
+	};
+}
+/**
+* What accepting `id` could copy: the declared targets it will supersede (accepted or
+* deprecated, as `planAccept` selects them) and the globs of theirs it doesn't have yet.
+*/
+function scopeToCopy(read, id) {
+	const own = new Set(viewOf(read, id).applies_to);
+	const sources = [];
+	const globs = /* @__PURE__ */ new Set();
+	for (const target of sorted(viewOf(read, id).declared_supersedes)) {
+		const t = target === id ? void 0 : read.projection.views.get(target);
+		if (t === void 0 || t.status !== "accepted" && t.status !== "deprecated") continue;
+		const extra = t.applies_to.filter((g) => !own.has(g));
+		if (extra.length === 0) continue;
+		sources.push(target);
+		for (const g of extra) globs.add(g);
+	}
+	return {
+		id,
+		sources,
+		displays: sources.map((t) => viewOf(read, t).display),
+		globs: sorted(globs)
+	};
+}
+const shQuote = (s) => `'${s.replaceAll("'", "'\\''")}'`;
+const andList = (xs) => xs.length <= 1 ? xs.join("") : `${xs.slice(0, -1).join(", ")} and ${xs.at(-1)}`;
+/** The note of an offer not taken: the `adr scope` command that copies it. */
+function copyScopeNote(id, offer) {
+	const n = offer.globs.length;
+	const adds = offer.globs.map((g) => `--add ${shQuote(g)}`).join(" ");
+	return `not copying the scope of ${andList(offer.displays)} (${n} ${n === 1 ? "glob" : "globs"}); to copy it: adr scope ${id} ${adds}`;
+}
+/** Plans `adr supersede <id> --by <by>`: one `superseded` event on `id`. */
+async function planSupersede(read, input, c) {
+	if (input.by.includes(":")) throw new UsageError(`--by ${input.by.trim()}: ${QUALIFIED_SUPERSESSION}`);
+	const reason = checkReason(input.reason);
+	const id = resolveDecision(read, input.id);
+	const by = resolveDecision(read, input.by);
+	const view = viewOf(read, id);
+	const target = viewOf(read, by);
+	const findings = [];
+	if (view.status !== "accepted" && view.status !== "deprecated") findings.push(refusal(read, "transition/illegal", illegal("superseded", view.status), id));
+	if (by === id || target.chain.includes(id)) {
+		const cycle = by === id ? [id, id] : [id, ...target.chain.slice(0, target.chain.indexOf(id) + 1)];
+		findings.push(refusal(read, "decision/supersession-cycle", `supersession cycle: ${cycle.join(" → ")}`, id));
+	} else if (target.status !== "accepted") findings.push(refusal(read, "decision/superseded-by-unaccepted", `superseded by ${by}, which is not accepted`, id));
+	const refused = (fs) => ({
+		ok: false,
+		decision: view,
+		findings: fs
+	});
+	if (findings.length > 0) return refused(findings);
+	const event = newEvent(read, c, {
+		subject: id,
+		type: "superseded",
+		data: { by },
+		reason,
+		actor: input.actor
+	});
+	const files = filesOf([event], read);
+	const { after, added } = await precheck(read, files);
+	if (added.length > 0) return refused(added);
+	const involved = sorted([id, by]);
+	const { scope, eventDirs } = commitScope(read, involved);
+	return {
+		ok: true,
+		plan: {
+			command: "supersede",
+			subject: id,
+			files,
+			events: [event],
+			stage: Object.keys(files),
+			involved,
+			commitScope: scope,
+			eventDirs,
+			draft: null,
+			commit: {
+				action: ACTIONS.superseded.action,
+				title: `${view.display} with ${target.display}`,
+				id,
+				display: view.display,
+				body: [`Superseded by ${target.display}: ${sentenceTitle(target.title)}.`]
+			},
+			trailers: pairsOf([event]),
+			decision: viewOf(after, id),
+			affected: [viewOf(after, id)],
+			findings: []
+		}
+	};
+}
+const actionOf = (type) => Object.hasOwn(ACTIONS, type) ? ACTIONS[type] : {
+	action: type,
+	names: "display"
+};
+/** A title in a body sentence: whitespace collapsed and trailing dots removed, as in a subject. */
+const sentenceTitle = (title) => title.replace(/\s+/g, " ").replace(/[. ]+$/, "").trim();
+/**
+* Plans any one event on an existing decision: the state machine and the event's validation
+* decide, then the precheck. Phase 2's reject, withdraw, deprecate, note, link and scope wrap it.
+*/
+async function planEvent(read, input, c) {
+	const id = resolveDecision(read, input.subject);
+	const view = viewOf(read, id);
+	if (!adrKind.machine.types.has(input.type) || input.type === adrKind.machine.initial.type) throw new InvalidArgumentError(`planEvent can't write a ${input.type} event`);
+	const reason = checkReason(input.reason);
+	const refused = (fs) => ({
+		ok: false,
+		decision: view,
+		findings: fs
+	});
+	if (!adrKind.machine.allowed(view.status, input.type)) return refused([refusal(read, "transition/illegal", illegal(input.type, view.status), id)]);
+	const event = newEvent(read, c, {
+		subject: id,
+		type: input.type,
+		data: input.data,
+		reason,
+		actor: input.actor
+	});
+	const valid = compiled.validate(event, { file: null });
+	if (!valid.ok) return refused(valid.findings.map((f) => ({
+		...f,
+		subject: id,
+		kind: adrKind.name
+	})));
+	const files = filesOf([event], read);
+	const { after, added } = await precheck(read, files);
+	if (added.length > 0) return refused(added);
+	const by = input.type === "superseded" ? String(input.data.by) : null;
+	const involved = sorted([id, ...by !== null && isSubjectId(by) ? [by] : []]);
+	const { scope, eventDirs } = commitScope(read, involved);
+	return {
+		ok: true,
+		plan: {
+			command: "event",
+			subject: id,
+			files,
+			events: [event],
+			stage: Object.keys(files),
+			involved,
+			commitScope: scope,
+			eventDirs,
+			draft: null,
+			commit: {
+				action: actionOf(input.type).action,
+				title: actionOf(input.type).names === "title" ? view.title : view.display,
+				id,
+				display: view.display,
+				body: reason === null ? [] : [`Reason: ${reason}`]
+			},
+			trailers: pairsOf([event]),
+			decision: viewOf(after, id),
+			affected: input.type === "superseded" ? [viewOf(after, id)] : [],
+			findings: []
+		}
+	};
+}
+/** Plans `adr reject`: `rejected` with its required reason, while proposed. */
+function planReject(read, input, c) {
+	return planEvent(read, {
+		...input,
+		subject: input.id,
+		type: "rejected",
+		data: {}
+	}, c);
+}
+/** Plans `adr withdraw`: `withdrawn`, with a reason when given, while proposed. */
+function planWithdraw(read, input, c) {
+	return planEvent(read, {
+		...input,
+		subject: input.id,
+		type: "withdrawn",
+		data: {}
+	}, c);
+}
+/** Plans `adr deprecate`: `deprecated` with its required reason, while accepted. */
+function planDeprecate(read, input, c) {
+	return planEvent(read, {
+		...input,
+		subject: input.id,
+		type: "deprecated",
+		data: {}
+	}, c);
+}
+/** Plans `adr note`: `noted` with the text as given, in every state. */
+function planNote(read, input, c) {
+	if (input.text.trim() === "") throw new UsageError("the note text must not be empty");
+	checkText("the note text", input.text);
+	return planEvent(read, {
+		subject: input.id,
+		type: "noted",
+		data: { text: input.text },
+		actor: input.actor
+	}, c);
+}
+const LINK_RELS = [
+	"relates-to",
+	"refines",
+	"depends-on"
+];
+const SOURCE_NAME = /^[a-z][a-z0-9-]{0,31}$/;
+/**
+* Plans `adr link` (design §6.7): `linked` in every state. A qualified target must name one of
+* `o.sources` (the log's `[[sources]]` names); it isn't looked up in the other log. A link that
+* already exists plans nothing, with a note.
+*/
+async function planLink(read, input, c, o = {}) {
+	const rel = input.rel ?? "relates-to";
+	if (!LINK_RELS.includes(rel)) throw new UsageError(`unknown --rel ${rel}; use relates-to, refines or depends-on`);
+	const id = resolveDecision(read, input.id);
+	const view = viewOf(read, id);
+	const target = input.to.trim();
+	let to;
+	let shown;
+	let described;
+	let named;
+	const at = target.indexOf(":");
+	if (at >= 0) {
+		const source = target.slice(0, at);
+		const local = target.slice(at + 1);
+		if (!SOURCE_NAME.test(source) || !isSubjectId(local)) throw new UsageError(`invalid decision ${JSON.stringify(input.to)}`);
+		if (!(o.sources ?? []).includes(source)) throw new UsageError(`unknown source ${source}; add a [[sources]] entry named ${source}`);
+		to = target;
+		shown = target;
+		described = `${rel} ${target}.`;
+		named = `${view.display} ${CROSS_LOG_LINK}`;
+	} else {
+		to = resolveDecision(read, target);
+		if (to === id) throw new UsageError("a decision can't link to itself");
+		const t = viewOf(read, to);
+		shown = t.display;
+		described = `${rel} ${t.display}: ${sentenceTitle(t.title)}.`;
+		named = `${view.display} to ${t.display}`;
+	}
+	if (view.links.some((l) => l.to === to && l.rel === rel)) return {
+		ok: true,
+		plan: {
+			command: "event",
+			subject: id,
+			files: {},
+			events: [],
+			stage: [],
+			involved: [id],
+			commitScope: [],
+			eventDirs: [],
+			draft: null,
+			commit: null,
+			trailers: [],
+			decision: view,
+			affected: [],
+			findings: [],
+			notes: [`already linked: ${view.display} ${rel} ${shown}; nothing written`]
+		}
+	};
+	const r = await planEvent(read, {
+		subject: id,
+		type: "linked",
+		data: {
+			to,
+			rel
+		},
+		actor: input.actor
+	}, c);
+	if (!r.ok || r.plan.commit === null) return r;
+	return {
+		ok: true,
+		plan: {
+			...r.plan,
+			commit: {
+				...r.plan.commit,
+				title: named,
+				body: [described]
+			}
+		}
+	};
+}
+/** `ADR-0003 (k3f9q8a1)`, or the id alone when the decision has no number. */
+const namedView = (v) => v.display === v.id ? v.id : `${v.display} (${v.id})`;
+/** The globs of `globs` that match none of `files`. */
+function unmatchedGlobs(globs, files) {
+	const matches = globMatcher(globs);
+	const hit = new Set(files.flatMap((f) => matches(f)));
+	return globs.filter((g) => !hit.has(g));
+}
+/**
+* Plans `adr scope` with a set operation (design §6.8): one `scoped` event with the whole new set
+* while proposed, accepted or deprecated, or nothing when the set doesn't change. Invalid globs,
+* conflicting operations and more than 200 globs are `UsageError`s. Notes name removed globs that
+* weren't there, added ones that were, resulting globs matching none of `o.tracked` (when given)
+* and a narrowed accepted scope.
+*/
+async function planScope(read, input, c, o = {}) {
+	const id = resolveDecision(read, input.id);
+	const view = viewOf(read, id);
+	const result = applySetOp(view.applies_to, input.op, {
+		what: "glob",
+		validate: (g) => {
+			const parsed = parseGlob(g);
+			return parsed.ok ? null : parsed.message;
+		},
+		maxItems: 200,
+		...input.names === void 0 ? {} : { names: input.names }
+	});
+	if (!adrKind.machine.allowed(view.status, "scoped")) return {
+		ok: false,
+		decision: view,
+		findings: [refusal(read, "transition/illegal", illegal("scoped", view.status), id)]
+	};
+	const named = namedView(view);
+	const notes = [...result.absent.map((g) => `${g} is not in the scope of ${named}`), ...result.present.map((g) => `${g} is already in the scope of ${named}`)];
+	if (!result.changed) return {
+		ok: true,
+		plan: {
+			command: "event",
+			subject: id,
+			files: {},
+			events: [],
+			stage: [],
+			involved: [id],
+			commitScope: [],
+			eventDirs: [],
+			draft: null,
+			commit: null,
+			trailers: [],
+			decision: view,
+			affected: [],
+			findings: [],
+			notes
+		}
+	};
+	if (o.tracked !== void 0) {
+		const checked = (adrKind.def.scope?.activeIn ?? []).includes(view.status) ? "; verify (hooks and CI) reports scope/glob-unmatched until a file matches" : "";
+		notes.push(...unmatchedGlobs(result.set, o.tracked).map((g) => `${g} matches no tracked file${checked}`));
+	}
+	if (result.removed.length > 0 && (view.status === "accepted" || view.status === "deprecated")) notes.push("this narrows the scope of an accepted decision; if its Scope section no longer reads true, propose a superseding decision instead");
+	const r = await planEvent(read, {
+		subject: id,
+		type: "scoped",
+		data: { set: [...result.set] },
+		actor: input.actor
+	}, c);
+	return r.ok ? {
+		ok: true,
+		plan: {
+			...r.plan,
+			notes
+		}
+	} : r;
+}
+/**
+* Plans one `scoped` event per change, in one batch (design §6.8 step 4): each decision's status
+* must allow `scoped` and each event must validate, else the first failing decision is refused.
+* The plan has no commit message, because `--follow-renames` never commits. `decision` is
+* `input.id`'s view after the write, or `null` without one; `affected` are the changed views.
+*/
+async function planScopeEvents(read, changes, input, c) {
+	const given = input.id === null ? null : viewOf(read, input.id);
+	const events = [];
+	for (const change of changes) {
+		const view = viewOf(read, change.id);
+		const refused = (findings) => ({
+			ok: false,
+			decision: given,
+			findings
+		});
+		if (!adrKind.machine.allowed(view.status, "scoped")) return refused([refusal(read, "transition/illegal", illegal("scoped", view.status), change.id)]);
+		const event = newEvent(read, c, {
+			subject: change.id,
+			type: "scoped",
+			data: { set: [...change.set] },
+			actor: input.actor
+		});
+		const valid = compiled.validate(event, { file: null });
+		if (!valid.ok) return refused(valid.findings.map((f) => ({
+			...f,
+			subject: change.id,
+			kind: adrKind.name
+		})));
+		events.push(event);
+	}
+	const files = filesOf(events, read);
+	const { after, added } = await precheck(read, files);
+	if (added.length > 0) return {
+		ok: false,
+		decision: given,
+		findings: added
+	};
+	const involved = sorted(changes.map((ch) => ch.id));
+	const { scope, eventDirs } = commitScope(read, involved);
+	return {
+		ok: true,
+		plan: {
+			command: "event",
+			subject: input.id ?? involved[0] ?? "",
+			files,
+			events,
+			stage: Object.keys(files),
+			involved,
+			commitScope: scope,
+			eventDirs,
+			draft: null,
+			commit: null,
+			trailers: pairsOf(events),
+			decision: input.id === null ? null : viewOf(after, input.id),
+			affected: changes.map((ch) => viewOf(after, ch.id)),
+			findings: []
+		}
+	};
+}
+/** A plan that writes nothing: the views as they are, and `notes`. */
+function emptyPlan(subject, decision, notes) {
+	return {
+		ok: true,
+		plan: {
+			command: "event",
+			subject,
+			files: {},
+			events: [],
+			stage: [],
+			involved: decision === null ? [] : [decision.id],
+			commitScope: [],
+			eventDirs: [],
+			draft: null,
+			commit: null,
+			trailers: [],
+			decision,
+			affected: [],
+			findings: [],
+			notes
+		}
+	};
+}
+/**
+* Plans `adr scope [<decision>] --follow-renames` (design §6.8 steps 1–4): the given decision's
+* globs, or every decision's, rewritten by `followRenames`. Decisions whose status forbids
+* `scoped` are skipped, with a note when the renames would have changed their scope; an explicit
+* one is refused.
+*/
+async function planFollowRenames(read, input, staged, c) {
+	const id = input.id === null ? null : resolveDecision(read, input.id);
+	const given = id === null ? null : viewOf(read, id);
+	if (staged.renames.length === 0) return emptyPlan(id ?? "", given, []);
+	if (given !== null && !adrKind.machine.allowed(given.status, "scoped")) return {
+		ok: false,
+		decision: given,
+		findings: [refusal(read, "transition/illegal", illegal("scoped", given.status), given.id)]
+	};
+	const views = given !== null ? [given] : [...read.projection.views.values()];
+	const notes = [];
+	const changes = [];
+	for (const view of [...views].sort((a, b) => a.id < b.id ? -1 : 1)) {
+		const result = followRenames({
+			globs: view.applies_to,
+			...staged
+		});
+		if (!result.changed) continue;
+		const named = namedView(view);
+		if (!adrKind.machine.allowed(view.status, "scoped")) {
+			const covers = globMatcher(view.applies_to);
+			const leaving = staged.renames.filter((r) => covers(r.from).length > 0).length;
+			notes.push(`${named} is ${view.status}; its scope can't follow renames (${leaving} renamed files leave it)`);
+			continue;
+		}
+		if (result.globs.length > 200) throw new UsageError(`following the renames gives ${named} ${result.globs.length} globs; the limit is 200`);
+		for (const s of result.skipped) notes.push(`${s.to} can't be written as a scope glob (${s.problem}); ${named} no longer covers it`);
+		for (const path of result.gained) notes.push(`${path} is now covered by ${named}'s scope but wasn't before the rename; check it`);
+		changes.push({
+			id: view.id,
+			set: result.globs
+		});
+	}
+	if (changes.length === 0) return emptyPlan(id ?? "", given, notes);
+	const r = await planScopeEvents(read, changes, {
+		id,
+		actor: input.actor
+	}, c);
+	return r.ok ? {
+		ok: true,
+		plan: {
+			...r.plan,
+			notes
+		}
+	} : r;
+}
+/** The paths of every file in `tree`. */
+async function filePaths(tree) {
+	return (await tree.list("")).filter((e) => e.type === "file").map((e) => e.path);
+}
+/** Every tracked file in the index, for the "matches no tracked file" notes. */
+async function trackedFiles(log) {
+	return filePaths(await indexReader(log.git));
+}
+const isYaml = (path) => /\.ya?ml$/.test(path);
+/**
+* What the recovery hint says about rerunning a write command after `git commit` failed (design
+* 2b D5): the batch is already in the log, so a rerun is refused, writes nothing or duplicates it.
+*/
+const WRITE_RERUN = "Don't run the command again: the log already holds the change, so a rerun would be refused, do nothing, or write it a second time.";
+/**
+* Applies a plan (§5.4): refuses a commit whose scope has unstaged or needed untracked paths,
+* writes the files (removing them again if a write fails), stages them, runs `afterStage`, and
+* commits `plan.stage` plus the involved subjects' already-staged files with exact trailers. A
+* failed `git commit` throws `CommitFailedError` with the manual command (design 2b D5) and the
+* notes made so far.
+*/
+/**
+* A write leaves the work tree's render of `index.md` (`staged`) staged, and it lists decision
+* files that may not be staged. When some aren't and the index's own render differs, the next
+* plain commit's hook fails; the note says so, as its `index/stale` finding does. `null`
+* otherwise, or when that render fails.
+*/
+async function unstagedIndexNote(log, at, staged, history, render) {
+	const files = await unstagedLogFiles(log.git, log.layout);
+	if (files.length === 0) return null;
+	const own = await render(await indexReader(log.git), history).catch(() => null);
+	if (own === null || own === staged) return null;
+	return `${unstagedIndexText(at, files)}; git add them before you commit, or move them out of the work tree and run adr index`;
+}
+async function applyPlan(log, plan, o) {
+	const { git } = log;
+	if (o.commit && o.message === void 0) throw new InvalidArgumentError("applyPlan needs a message to commit");
+	const stage = new Set(plan.stage);
+	if (o.commit) {
+		const unstaged = new Set(await git.unstagedPaths(plan.commitScope));
+		const dirs = new Set(plan.eventDirs);
+		const untracked = /* @__PURE__ */ new Set([...await git.untrackedPaths(plan.commitScope.filter((p) => !dirs.has(p))), ...(await git.untrackedPaths(plan.eventDirs)).filter(isYaml)]);
+		const [first] = sorted([...unstaged, ...untracked]).filter((p) => !stage.has(p));
+		if (first !== void 0) throw new UsageError(unstaged.has(first) ? `${first} has unstaged changes; stage or discard them, or run without --commit` : `${first} is not tracked; git add it, or run without --commit`);
+	}
+	const root = log.layout.root;
+	const at = indexPath(log.layout);
+	const notes = [];
+	const head = await git.resolveCommit("HEAD");
+	const extraOf = async () => (await git.stagedPaths(plan.commitScope)).filter((p) => !stage.has(p));
+	const commitTree = async (extra) => {
+		const work = worktreeReader(git);
+		const files = {};
+		const gone = /* @__PURE__ */ new Set();
+		for (const p of sorted([...plan.stage, ...extra])) {
+			const bytes = plan.files[p] ?? await work.read(p);
+			if (bytes === null) gone.add(p);
+			else files[p] = bytes;
+		}
+		return withoutPaths(overlayTree(await headTree(git, head), files), gone);
+	};
+	const extra0 = o.commit && o.index !== void 0 ? await extraOf() : [];
+	let text = null;
+	if (o.index !== void 0) {
+		const tree = o.commit ? await commitTree(extra0) : overlayTree(worktreeReader(git), plan.files);
+		text = await o.index(tree, head);
+		if (text === null) notes.push(`${at} not updated: numbers need history in this shallow clone; run git fetch --unshallow, then adr index`);
+	}
+	const toStage = [];
+	let indexWritten = false;
+	let indexOld = null;
+	let indexInCommit = false;
+	/** Brings the work-tree copy to `t` and stages it (now, or with the batch) where they differ. */
+	const refresh = async (t, now) => {
+		const r = await writeIndexCopy(git, at, t);
+		if (r.wrote && !indexWritten) indexOld = r.old;
+		indexWritten ||= r.wrote;
+		if (r.stage) {
+			if (now) await git.add([at]);
+			else toStage.push(at);
+		}
+		return r.wrote || r.stage;
+	};
+	/** Step 3's rules: committing, HEAD's copy decides; otherwise the work tree and the index. */
+	const place = async (t, committing, now) => {
+		if (!committing) {
+			await refresh(t, now);
+			return;
+		}
+		indexInCommit = !holdsText(await headBytes(git, at), t);
+		if (indexInCommit) await refresh(t, now);
+	};
+	const eventPaths = new Set(plan.events.map((e) => eventPath(log.layout, e)));
+	const written = [];
+	try {
+		for (const [path, bytes] of Object.entries(plan.files)) {
+			if (eventPaths.has(path)) continue;
+			await writeNewFile(git, path, bytes, { stage: false });
+			written.push(path);
+		}
+		if (text !== null) await place(text, o.commit, false);
+		await writeEvents(git, log.layout, plan.events, {
+			kind: log.compiled,
+			stage: false
+		});
+	} catch (err) {
+		const top = git.root ?? "";
+		if (indexWritten) {
+			if (indexOld === null) await rm(join(top, at), { force: true });
+			else await writeFile(join(top, at), indexOld);
+		}
+		for (const path of written) await rm(join(top, path), { force: true });
+		throw err;
+	}
+	await git.add([...plan.stage, ...toStage]);
+	/** The work tree's render that ends up staged, and the commit it builds on. */
+	let stagedIndex = !o.commit && text !== null ? {
+		text,
+		history: head
+	} : null;
+	let findings = plan.findings;
+	let commit = o.commit;
+	if (o.afterStage !== void 0) {
+		const after = await o.afterStage();
+		findings = after.findings ?? plan.findings;
+		commit = commit && after.commit;
+	}
+	const stale = (err) => `${at} may be stale: ${firstLine(err)}; run adr index`;
+	let sha = null;
+	if (commit) {
+		const extra = await extraOf();
+		const staged = extra.filter(isYaml).flatMap((p) => {
+			const c = classifyPath(log.layout, p);
+			const name = c.area === "event" && !c.file.includes("/") ? parseEventFileName(c.file) : null;
+			return c.area === "event" && c.subject !== null && name !== null ? [["ADR", c.subject], ["ADR-Event", name.type]] : [];
+		});
+		const message = o.message ?? "";
+		const mergeTrailers = o.mergeTrailers === true;
+		const trailers = [...staged, ...plan.trailers];
+		const sameEvents = sorted(extra.filter(isYaml)).join("\0") === sorted(extra0.filter(isYaml)).join("\0");
+		if (text !== null && o.index !== void 0 && o.afterStage !== void 0 && !sameEvents) try {
+			const again = await o.index(await commitTree(extra), head);
+			if (again !== null) await place(again, true, true);
+		} catch (err) {
+			const recovery = await saveCommitRecovery(git, {
+				message,
+				mergeTrailers,
+				trailers,
+				only: sorted([
+					...plan.stage,
+					...extra,
+					at
+				])
+			});
+			throw new CommitFailedError({
+				recovery,
+				headline: `${at} couldn't be refreshed: ${firstLine(err)}`,
+				detail: "",
+				rerun: WRITE_RERUN,
+				before: INDEX_BEFORE(root),
+				after: null,
+				notes
+			}, { cause: err });
+		}
+		try {
+			sha = await commitWithRecovery(git, {
+				message,
+				mergeTrailers,
+				trailers,
+				only: sorted([
+					...plan.stage,
+					...extra,
+					...indexInCommit ? [at] : []
+				]),
+				rerun: WRITE_RERUN,
+				after: indexInCommit ? INDEX_AFTER(root) : null
+			});
+		} catch (err) {
+			throw err instanceof CommitFailedError ? err.withNotes(notes) : err;
+		}
+		if (text !== null && o.index !== void 0) try {
+			const again = await o.index(worktreeReader(git), sha);
+			if (again !== null) {
+				await refresh(again, true);
+				stagedIndex = {
+					text: again,
+					history: sha
+				};
+			}
+		} catch (err) {
+			notes.push(stale(err));
+		}
+	} else if (o.commit && text !== null && o.index !== void 0) try {
+		const again = await o.index(worktreeReader(git), head);
+		if (again !== null) {
+			await refresh(again, true);
+			stagedIndex = {
+				text: again,
+				history: head
+			};
+		}
+	} catch (err) {
+		notes.push(stale(err));
+	}
+	if (stagedIndex !== null && o.index !== void 0) {
+		const { text: t, history } = stagedIndex;
+		const note = await unstagedIndexNote(log, at, t, history, o.index);
+		if (note !== null) notes.push(note);
+	}
+	return {
+		written: [...Object.keys(plan.files), ...indexWritten ? [at] : []],
+		commit: sha,
+		findings,
+		notes
+	};
+}
+/** `tree` without the paths in `gone` (a staged deletion in a commit's `only` list). */
+function withoutPaths(tree, gone) {
+	if (gone.size === 0) return tree;
+	return {
+		label: tree.label,
+		commit: null,
+		list: async (prefix) => (await tree.list(prefix)).filter((e) => !gone.has(e.path)),
+		read: async (path) => gone.has(path) ? null : tree.read(path),
+		readMany: (paths) => tree.readMany(paths.filter((p) => !gone.has(p)))
+	};
+}
+const DEFAULT_DEPS = {
+	now: Date.now,
+	apply: applyPlan
+};
+/**
+* The views `adr-write/v1` reports. Without a commit they are the plan's, folded on the overlay.
+* After a commit they come from a new read of the log, so a commit on the main ref shows the
+* numbers it assigned, as the CLI text and phase 3's MCP tools do. A commit that failed threw in
+* `applyPlan`, so nothing is read for it.
+*/
+async function viewsAfter(log, plan, sha) {
+	if (sha === null) return {
+		decision: plan.decision,
+		affected: plan.affected
+	};
+	const read = await readDecisions({
+		...log,
+		commit: sha
+	});
+	const view = (v) => read.projection.views.get(v.id) ?? v;
+	return {
+		decision: plan.decision === null ? null : view(plan.decision),
+		affected: plan.affected.map(view)
+	};
+}
+const SHORTENED_NOTE = "commit subject shortened to 72 characters; the full title is in the commit body";
+/**
+* `--commit` needs an author and a committer identity; checked before anything is written, since
+* `GIT_AUTHOR_*` alone satisfies the author while `git commit` still fails on the committer.
+*/
+async function checkCommitIdentity(log) {
+	if (await log.git.identity() === null || await log.git.committerIdentity() === null) throw new ConfigError("--commit needs a git identity; set git user.name and user.email");
+}
+/** The plan's commit message from `[commit] subject` (design §4), and whether it was shortened. */
+function commitMessage(log, command, plan) {
+	const parts = plan.commit;
+	if (parts === null) throw new InvalidArgumentError("this write can't be committed");
+	const r = renderCommitMessage(log.adr.commitSubject, {
+		title: parts.title,
+		vars: {
+			action: parts.action,
+			id: parts.id,
+			display: parts.display,
+			command
+		},
+		body: parts.body
+	});
+	return {
+		message: r.message,
+		shortened: r.shortened
+	};
+}
+/**
+* Plan, then apply, with the single `EventExistsError` retry (§5.4 steps 1–5). `o.message`
+* replaces the rendered commit message; `o.notes` come before the write's own notes. A plan with
+* no files and no events is reported as written without touching the repository, and so is
+* every plan with `dryRun` (its views are the plan's).
+*/
+async function write(log, command, plan, o, deps, afterStage) {
+	if (log.ref !== null) throw new InvalidArgumentError("writes read the work tree; open the log without a ref");
+	if (log.tree.label !== "worktree") throw new InvalidArgumentError("writes read the work tree; open the log with the worktree reader");
+	const commit = o.commit ?? log.adr.autoCommit;
+	if (commit) await checkCommitIdentity(log);
+	const notes = [...log.notes, ...o.notes ?? []];
+	for (let attempt = 0;; attempt++) {
+		const read = await readDecisions(log);
+		const ref = await templateHistoryRef(log.git, { type: "full" });
+		const r = await plan(read, {
+			now: deps.now,
+			...deps.random === void 0 ? {} : { random: deps.random },
+			templates: historyTemplates(log.git, log.tree, `${read.root}/templates`, { ref }),
+			builtins: BUILTIN_TEMPLATES
+		});
+		if (!r.ok) return {
+			format: "adr-write/v1",
+			command,
+			ok: false,
+			decision: r.decision,
+			affected: [],
+			written: [],
+			commit: null,
+			findings: r.findings,
+			notes
+		};
+		if (r.plan.events.length === 0 && Object.keys(r.plan.files).length === 0 || o.dryRun === true) return {
+			format: "adr-write/v1",
+			command,
+			ok: true,
+			decision: r.plan.decision,
+			affected: r.plan.affected,
+			written: [],
+			commit: null,
+			findings: r.plan.findings,
+			notes: [...notes, ...r.plan.notes ?? []]
+		};
+		const rendered = commit ? commitMessage(log, command, r.plan) : null;
+		const given = o.message ?? null;
+		try {
+			const applied = await deps.apply(log, r.plan, {
+				commit,
+				...rendered === null ? {} : {
+					message: given ?? rendered.message,
+					mergeTrailers: given !== null
+				},
+				...afterStage === void 0 ? {} : { afterStage: afterStage(r.plan, commit) },
+				...log.adr.index === "committed" && o.index !== "skip" ? { index: (tree, history) => renderDecisionIndex(log.git, {
+					layout: log.layout,
+					adr: log.adr,
+					tree,
+					history
+				}) } : {}
+			});
+			const views = await viewsAfter(log, r.plan, applied.commit);
+			const own = [
+				...r.plan.notes ?? [],
+				...applied.notes,
+				...applied.commit !== null && given === null && rendered?.shortened === true ? [SHORTENED_NOTE] : []
+			];
+			return {
+				format: "adr-write/v1",
+				command,
+				ok: true,
+				decision: views.decision,
+				affected: views.affected,
+				written: applied.written,
+				commit: applied.commit,
+				findings: applied.findings,
+				notes: [...notes, ...own]
+			};
+		} catch (err) {
+			if (err instanceof CommitFailedError) throw err.withNotes([...notes, ...r.plan.notes ?? []]);
+			if (!(err instanceof EventExistsError) || attempt > 0) throw err;
+		}
+	}
+}
+const sameBytes = (a, b) => a.byteLength === b.byteLength && a.every((x, i) => x === b[i]);
+async function readIfPresent(path) {
+	try {
+		return await readFile(path);
+	} catch (err) {
+		if (err.code === "ENOENT") return null;
+		throw err;
+	}
+}
+/**
+* The editor step (§5.4): runs `edit` on the staged draft, re-stages the edited body when the
+* editor exited 0, and skips the commit when committing would take content nobody confirmed: the
+* body changed while the editor failed, the body is gone, or another path in the commit scope (a
+* materialized template, say) changed while the editor was open (design review NIT 2). The
+* findings are the lint of the draft as it now is.
+*/
+function editorStep(log, edit, onNote) {
+	return (plan, commitRequested) => async () => {
+		const d = plan.draft;
+		if (d === null) return {
+			findings: null,
+			commit: true
+		};
+		const abs = join(log.git.root ?? "", d.path);
+		const note = await edit(abs);
+		const bytes = await readIfPresent(abs);
+		let commit;
+		if (bytes === null) {
+			commit = false;
+			onNote?.(`${d.path} was removed while editing; the rendered draft is still staged. Restore it with \`git checkout -- ${d.path}\``);
+		} else if (note === null) {
+			await log.git.add([d.path]);
+			commit = true;
+		} else if (sameBytes(bytes, d.rendered)) commit = true;
+		else {
+			commit = false;
+			if (commitRequested) onNote?.(`${d.path} changed while the editor failed; review it, then git add it and commit`);
+		}
+		if (commit && commitRequested) {
+			const [first] = (await log.git.unstagedPaths(plan.commitScope)).filter((p) => p !== d.path);
+			if (first !== void 0) {
+				commit = false;
+				onNote?.(`${first} changed while the editor was open; review it, then git add it and commit`);
+			}
+		}
+		const text = decoder$1.decode(bytes ?? d.rendered);
+		const findings = lintDocument(d.template, text, {
+			file: d.path,
+			subject: plan.subject
+		});
+		if (commit && commitRequested && findings.length > 0) {
+			commit = false;
+			onNote?.(`${d.path} still has unfilled required sections; fill them in, then commit`);
+		}
+		return {
+			findings,
+			commit
+		};
+	};
+}
+/**
+* `adr new`: renders a draft, writes the body, any materialized template and the `proposed`
+* event, stages them, and commits with `commit` (default `[policy] auto_commit`).
+*
+* `edit` (CLI only; MCP never passes it) runs between staging and committing, on the absolute
+* body path. It resolves to `null` when the editor exited 0, else to a note for the user (spawn
+* error, exit status). `onNote` receives the notes about a skipped commit or a removed body,
+* without the "not committed: " prefix the CLI adds when a commit was requested.
+*
+* A draft with unfilled sections is never committed (design §7.2): without `edit` a commit is
+* refused (`ok: false`, nothing written); after `edit` the commit is skipped with a note.
+*/
+async function proposeDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	return write(log, "new", (read, c) => planPropose(read, input, c, { refuseIncomplete: (o.commit ?? log.adr.autoCommit) && o.edit === void 0 }), o, deps, o.edit === void 0 ? void 0 : editorStep(log, o.edit, o.onNote));
+}
+/**
+* `adr accept`: lints the draft, hashes the body, writes `accepted` and a `superseded` event on
+* each declared target, stages them with the body, and commits with `commit`. When the targets
+* have globs the decision lacks, `copyScope` decides whether a `scoped` event copies them
+* (default `"suggest"`: no copy, and a note with the `adr scope` command that would).
+*/
+async function acceptDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	const copyScope = o.copyScope ?? "suggest";
+	let copy = null;
+	return write(log, "accept", async (read, c) => {
+		const plain = await planAccept(read, input, c);
+		if (!plain.ok) return plain;
+		const id = plain.plan.subject;
+		const offer = scopeToCopy(read, id);
+		if (offer.globs.length === 0) return plain;
+		if (copy === null) copy = typeof copyScope === "function" ? await copyScope(offer) : copyScope === "copy";
+		if (copy) return planAccept(read, input, c, { copyGlobs: offer.globs });
+		if (copyScope === "skip") return plain;
+		const notes = [...plain.plan.notes ?? [], copyScopeNote(id, offer)];
+		return {
+			ok: true,
+			plan: {
+				...plain.plan,
+				notes
+			}
+		};
+	}, o, deps);
+}
+/** `adr supersede <id> --by <by>`: writes `superseded`, stages it, and commits with `commit`. */
+async function supersedeDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	return write(log, "supersede", (read, c) => planSupersede(read, input, c), o, deps);
+}
+/**
+* `adr reject <id> --reason <text>`: writes `rejected`, stages it, and commits with `commit`. The
+* kind requires the reason; without one the write is refused (findings, nothing written).
+*/
+async function rejectDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	return write(log, "reject", (read, c) => planReject(read, input, c), o, deps);
+}
+/** `adr withdraw <id> [--reason <text>]`: writes `withdrawn`, stages it, and commits with `commit`. */
+async function withdrawDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	return write(log, "withdraw", (read, c) => planWithdraw(read, input, c), o, deps);
+}
+/**
+* `adr deprecate <id> --reason <text>`: writes `deprecated`, stages it, and commits with `commit`.
+* The kind requires the reason, as for `rejectDecision`.
+*/
+async function deprecateDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	return write(log, "deprecate", (read, c) => planDeprecate(read, input, c), o, deps);
+}
+/** `adr note <id> <text>`: writes `noted`, stages it, and commits with `commit`. */
+async function noteDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	return write(log, "note", (read, c) => planNote(read, input, c), o, deps);
+}
+/**
+* `adr link <id> <target> [--rel <rel>]`: writes `linked`, stages it, and commits with `commit`.
+* Qualified targets name the log's `[[sources]]`; a link that exists already writes nothing.
+*/
+async function linkDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	const sources = (log.config?.sources ?? []).map((s) => s.name);
+	return write(log, "link", (read, c) => planLink(read, input, c, { sources }), o, deps);
+}
+/**
+* `adr scope <id> --set|--add|--remove …`: writes one `scoped` event with the new set, stages it,
+* and commits with `commit`. An unchanged set writes nothing.
+*/
+async function scopeDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	const tracked = await trackedFiles(log);
+	return write(log, "scope", (read, c) => planScope(read, input, c, { tracked }), o, deps);
+}
+const FOLLOW_NO_COMMIT_NOTE = "--follow-renames never commits; commit the scoped events with the renames";
+/**
+* `adr scope [<decision>] --follow-renames` (design §6.8): rewrites the scope globs of the given
+* decision, or of every decision, after the renames staged against `HEAD`, and stages one
+* `scoped` event per changed decision. It never commits, whatever `[policy] auto_commit` says
+* (the events belong in the commit with the renames), so `o.commit: true` and a message are
+* `InvalidArgumentError`s. `dryRun` plans the same events and notes without writing anything.
+*/
+async function followScopeRenames(log, input, o = {}, deps = DEFAULT_DEPS) {
+	if (o.commit === true) throw new InvalidArgumentError("followScopeRenames never commits; don't pass commit: true");
+	if (o.message !== void 0 && o.message !== null) throw new InvalidArgumentError("followScopeRenames never commits, so it takes no message");
+	const renames = await stagedRenames(log.git);
+	const staged = renames.length === 0 ? {
+		renames,
+		before: [],
+		after: []
+	} : {
+		renames,
+		before: await filePaths(await refReader(log.git, "HEAD")),
+		after: await filePaths(await indexReader(log.git))
+	};
+	const doc = await write(log, "scope", (read, c) => planFollowRenames(read, {
+		id: input.id ?? null,
+		actor: input.actor
+	}, staged, c), {
+		...o,
+		commit: false
+	}, deps);
+	return log.adr.autoCommit && doc.ok && doc.affected.length > 0 ? {
+		...doc,
+		notes: [...doc.notes, FOLLOW_NO_COMMIT_NOTE]
+	} : doc;
+}
+// src/hooks.ts
+/** The hooks adr registers, in the order the text output lists them. */
+const HOOKS = [
+	"pre-commit",
+	"commit-msg",
+	"pre-push",
+	"post-merge"
+];
+/**
+* adr's command per hook (design 2b D4), after `adr`. `--root <root>` comes first only when the
+* root can't be found without it: no `<repo>/adr.toml` names it and it isn't `docs/adr`. So the
+* hooks see the same config as a plain `adr` run, and never print the root-override note.
+*/
+function decisionHookCommands(log) {
+	const r = log.configPath === "adr.toml" || log.layout.root === adrKind.def.defaultRoot ? [] : ["--root", log.layout.root];
+	return {
+		"pre-commit": [
+			...r,
+			"hooks",
+			"run",
+			"pre-commit"
+		],
+		"commit-msg": [
+			...r,
+			"hooks",
+			"trailers",
+			"{args}"
+		],
+		"pre-push": [
+			...r,
+			"verify",
+			"--base",
+			"@{upstream}",
+			"--ref",
+			"HEAD"
+		],
+		"post-merge": [
+			...r,
+			"list",
+			"--since",
+			"ORIG_HEAD"
+		]
+	};
+}
+function registrations(log) {
+	const commands = decisionHookCommands(log);
+	return HOOKS.flatMap((hook) => {
+		const argv = commands[hook];
+		return argv === void 0 ? [] : [{
+			hook,
+			argv
+		}];
+	});
+}
+/** A shim path as the user sees it: repo-relative, with `/`. */
+function shown(git, path) {
+	return relative(git.root ?? git.gitDir, path).split(sep).join("/");
+}
+/** The shims in hook order: `HOOKS`' order, as the text output lists them. */
+function inHookOrder(git, paths) {
+	const rank = (p) => HOOKS.findIndex((h) => p.endsWith(`/${h}`));
+	return paths.map((p) => shown(git, p)).sort((a, b) => rank(a) - rank(b));
+}
+function result(log, action, r, extra = {}) {
+	return {
+		format: "adr-hooks/v1",
+		action,
+		written: r === null ? [] : inHookOrder(log.git, r.written),
+		unchanged: r === null ? [] : inHookOrder(log.git, r.unchanged),
+		registrations: registrations(log),
+		snippet: extra.snippet ?? null,
+		trailers: extra.trailers ?? []
+	};
+}
+/**
+* Registers adr's four commands in ledger's shims, one per hook and shared with other ark tools
+* (design 2b D4). With `core.hooksPath` set or a foreign hook file present, it writes the rest and
+* then throws `HookConflictError` (exit 2), naming each conflict and the `print` command.
+*/
+async function installDecisionHooks(log) {
+	const r = await installHooks(log.git, {
+		tool: "adr",
+		commands: decisionHookCommands(log)
+	});
+	assertNoHookConflicts(r, { tool: "adr" });
+	return result(log, "install", r);
+}
+/** Removes adr from every shim; a shim left with no tool is deleted. */
+async function uninstallDecisionHooks(log) {
+	return result(log, "uninstall", await uninstallHooks(log.git, { tool: "adr" }));
+}
+/** The config to paste into a hook manager instead of installing shims. */
+function printDecisionHooks(log, manager) {
+	const regs = registrations(log).map((r) => ({
+		tool: "adr",
+		...r
+	}));
+	return result(log, "print", null, { snippet: hookSnippet(manager, regs) });
+}
+/** The `ADR-Event` trailer key as git compares keys: case-insensitively. */
+const ADR_EVENT = /^adr-event[ \t]*:/im;
+/**
+* The `commit-msg` step (P1 §7.1): appends one `ADR`/`ADR-Event` pair per staged added event file
+* of the log, by path, keeping repeats (`ifExists: "add"`). It does nothing for a message that
+* already has an `ADR-Event:` trailer (an `adr … --commit` message), or during a merge, whose
+* events came with their own commits' trailers. Throws `UsageError` when the file is missing.
+*/
+async function addHookTrailers(log, messageFile) {
+	const { git, layout } = log;
+	const file = resolve(git.root ?? git.gitDir, messageFile);
+	try {
+		await access(file, constants.R_OK | constants.W_OK);
+	} catch {
+		throw new UsageError(`no commit message file at ${messageFile}`);
+	}
+	const parsed = await git.run([
+		"interpret-trailers",
+		"--parse",
+		"--",
+		file
+	]);
+	if (ADR_EVENT.test(Buffer.from(parsed.stdout).toString("utf8"))) return result(log, "trailers", null);
+	if (await git.resolveCommit("MERGE_HEAD") !== null) return result(log, "trailers", null);
+	const trailers = (await git.stagedPaths([`${layout.root}/${layout.events}`], { addedOnly: true })).flatMap((p) => {
+		const c = classifyPath(layout, p);
+		const name = c.area === "event" && !c.file.includes("/") ? parseEventFileName(c.file) : null;
+		return c.area === "event" && c.subject !== null && name !== null ? [["ADR", c.subject], ["ADR-Event", name.type]] : [];
+	});
+	await git.appendTrailers(file, trailers, { ifExists: "add" });
+	return result(log, "trailers", null, { trailers });
+}
+/**
+* Whether the hook may stage: only into the commit's real index (design 2b D8). `git commit
+* <paths>` and `--only`, adr's own `--commit` included, run hooks on a temporary index, and
+* staging there leaves the user's index showing the file as deleted.
+*/
+function stagingSafe(git, env) {
+	const file = env.GIT_INDEX_FILE;
+	if (file === void 0 || file === "") return true;
+	const at = resolve(git.root ?? git.gitDir, file);
+	return at === resolve(git.gitDir, "index") || at === resolve(git.gitDir, "index.lock");
+}
+/** `ADR-0003, ADR-0004` for the decisions a rename following changes. */
+const displays = (views) => views.map((v) => v.display).join(", ");
+/**
+* `adr hooks run pre-commit` (design 2b D8): rename following, then the index, then `verify
+* --staged`, stopping at the first step that fails. `worktree` must be opened with the work-tree
+* reader, because rename following writes through `write()`; `index` with the index reader, for
+* the config as staged, the index render and verify. Only the index step stages `index.md`, and
+* only with `[hooks] index = "stage"`; rename following passes `index: "skip"`. Neither stages
+* into a temporary index (`stagingSafe`). A step that can't run throws (exit 2).
+*/
+async function runPreCommitHook(o) {
+	const { worktree, index, env } = o;
+	const config = index.adr;
+	const failOn = config.failOn;
+	const notes = [...index.notes];
+	const done = (exit, findings) => ({
+		exit,
+		findings,
+		notes: [...new Set(notes)],
+		failOn
+	});
+	const safe = stagingSafe(index.git, env);
+	if (config.scopeFollowRenames !== "off" && (await stagedRenames(worktree.git)).length > 0) {
+		const { actor, notes: attribution } = await resolveAttribution(worktree.git, { env });
+		if (config.scopeFollowRenames === "warn") {
+			const dry = await followScopeRenames(worktree, { actor }, { dryRun: true });
+			for (const v of dry.affected) notes.push(`${v.display}'s globs don't follow the renames in this commit (scope_follow_renames = "warn"); run adr scope --follow-renames`);
+		} else if (safe) {
+			const doc = await followScopeRenames(worktree, { actor }, {
+				index: "skip",
+				notes: attribution
+			});
+			notes.push(...doc.notes);
+			if (!doc.ok) return done(1, doc.findings);
+		} else {
+			const dry = await followScopeRenames(worktree, { actor }, { dryRun: true });
+			if (dry.affected.length > 0) {
+				notes.push(`the renames in this commit change the scope of ${displays(dry.affected)}; git commit <paths> can't take the scoped events. Run adr scope --follow-renames, then commit again including the files it lists, or set [hooks] scope_follow_renames = "warn"`);
+				return done(1, []);
+			}
+		}
+	}
+	if (config.index === "committed" && config.hookIndex === "stage" && safe) {
+		const path = indexPath(index.layout);
+		const text = await renderDecisionIndex(index.git, {
+			layout: index.layout,
+			adr: config,
+			tree: index.tree,
+			history: await index.git.resolveCommit("HEAD")
+		});
+		if (text !== null && !holdsText(await index.tree.read(path), text)) {
+			await writeIndexFile(index.git, path, text);
+			await index.git.add([path]);
+			notes.push(`regenerated and staged ${path}`);
+		}
+	}
+	const findings = await verifyDecisions(index, { type: "staged" });
+	return done(exitCode(findings, { failOn }), findings);
+}
+// src/init.ts
+/**
+* What the recovery hint says about rerunning `adr init` after `git commit` failed (design 2b D5):
+* init keeps existing files, so it would commit nothing.
+*/
+const INIT_RERUN = "Running adr init again won't commit them: the files exist now, so it keeps them and commits nothing.";
+const CONFIG = "adr.toml";
+const DEFAULT_ROOT = adrKind.def.defaultRoot;
+const encoder = new TextEncoder();
+/** The starter config; `root` only for a repo-level file naming a log elsewhere. */
+function configText(o) {
+	return [
+		"# adr configuration. Every key is optional: https://github.com/nikovirtala/ark/tree/main/packages/adr#config-adrtoml",
+		"[log]",
+		...o.root === null ? [] : [`root = ${JSON.stringify(o.root)}`],
+		`default_template = ${JSON.stringify(o.template)}`,
+		"",
+		"[commit]",
+		"# subject = \"docs(adr): {action} {title}\"",
+		""
+	].join("\n");
+}
+/**
+* `adr init` (design §6.2): writes a config for the log, unless one is found, and each built-in
+* template in `o.templates` (default `nygard`) to `<root>/templates/`, never overwriting a file.
+* A `--root` other than `docs/adr` gets a repo-level `adr.toml` naming it, so later commands find
+* the log without `--root`; when that file exists for another log, the config goes in the root.
+* With `[log] index = "committed"` it also writes `<root>/index.md` unless one exists. With
+* `commit` (default `[policy] auto_commit`) the written files are committed on their own;
+* nothing written means nothing committed. No events are written.
+*/
+async function initDecisionLog(log, o = {}) {
+	if (log.ref !== null || log.tree.label !== "worktree") throw new InvalidArgumentError("init writes the work tree; open the log without a ref");
+	const known = Object.keys(BUILTIN_TEMPLATES);
+	const templates = [...new Set(o.templates === void 0 ? ["nygard"] : o.templates)];
+	for (const name of templates) if (!known.includes(name)) throw new UsageError(`unknown built-in template ${name}; use nygard, madr or y-statement`);
+	const root = log.layout.root;
+	const notes = [...log.notes];
+	const files = [];
+	const kept = [];
+	let config = log.configPath;
+	if (config !== null) kept.push(config);
+	else {
+		const template = templates[0] ?? "nygard";
+		const repo = await readToolConfig(log.tree, CONFIG);
+		if (root === DEFAULT_ROOT) {
+			config = `${root}/${CONFIG}`;
+			files.push([config, configText({
+				root: null,
+				template
+			})]);
+		} else if (repo === null) {
+			config = CONFIG;
+			files.push([config, configText({
+				root,
+				template
+			})]);
+		} else {
+			const section = repo.raw.log;
+			const other = typeof section?.root === "string" ? section.root : DEFAULT_ROOT;
+			config = `${root}/${CONFIG}`;
+			files.push([config, configText({
+				root: null,
+				template
+			})]);
+			notes.push(`${CONFIG} names ${other}; pass --root ${root} to use this log`);
+		}
+	}
+	for (const name of templates) {
+		const path = `${root}/templates/${name}.md`;
+		if (await log.tree.read(path) !== null) kept.push(path);
+		else files.push([path, BUILTIN_TEMPLATES[name] ?? ""]);
+	}
+	const commitRequested = o.commit ?? log.adr.autoCommit;
+	const at = indexPath(log.layout);
+	let indexed = false;
+	if (log.adr.index === "committed") {
+		if (await log.tree.read(at) !== null) kept.push(at);
+		else {
+			const head = await log.git.resolveCommit("HEAD");
+			const added = Object.fromEntries(files.map(([p, t]) => [p, encoder.encode(t)]));
+			const base = commitRequested ? await headTree(log.git, head) : log.tree;
+			const text = await renderDecisionIndex(log.git, {
+				layout: log.layout,
+				adr: log.adr,
+				tree: overlayTree(base, added),
+				history: head
+			});
+			if (text === null) notes.push(`${at} not updated: numbers need history in this shallow clone; run git fetch --unshallow, then adr index`);
+			else {
+				files.push([at, text]);
+				indexed = true;
+			}
+		}
+	}
+	const commit = files.length > 0 && commitRequested;
+	if (commit && (await log.git.identity() === null || await log.git.committerIdentity() === null)) throw new ConfigError("--commit needs a git identity; set git user.name and user.email");
+	const written = [];
+	try {
+		for (const [path, text] of files) {
+			await writeNewFile(log.git, path, encoder.encode(text));
+			written.push(path);
+		}
+	} catch (err) {
+		const top = log.git.root ?? "";
+		for (const path of written) await rm(join(top, path), { force: true });
+		throw err;
+	}
+	if (written.length > 0) await log.git.add(written);
+	let sha = null;
+	if (commit) {
+		const message = o.message ?? renderCommitMessage(log.adr.commitSubject, {
+			title: "the decision log",
+			vars: {
+				action: "set up",
+				id: "",
+				display: "",
+				command: "init"
+			}
+		}).message;
+		sha = await commitWithRecovery(log.git, {
+			message,
+			only: written,
+			rerun: INIT_RERUN,
+			after: indexed ? INDEX_AFTER(root) : null
+		});
+		if (indexed) try {
+			const again = await renderDecisionIndex(log.git, {
+				layout: log.layout,
+				adr: log.adr,
+				tree: worktreeReader(log.git),
+				history: sha
+			});
+			if (again !== null) {
+				if ((await writeIndexCopy(log.git, at, again)).stage) await log.git.add([at]);
+			}
+		} catch (err) {
+			notes.push(`${at} may be stale: ${firstLine(err)}; run adr index`);
+		}
+	}
+	return {
+		format: "adr-init/v1",
+		root,
+		config,
+		written,
+		kept,
+		commit: sha,
+		notes
+	};
+}
+// src/views.ts
+/** The `numbering` key of `adr-list/v1`, `adr-show/v1` and `adr-for/v1`. */
+const numberingJson = (read) => ({
+	available: read.numbering.available,
+	reason: read.numbering.reason,
+	ref: read.numbering.ref
+});
+/** Numbered decisions by number, then unnumbered ones by `proposed_at`, then id. */
+function compareViews(a, b) {
+	if (a.number !== null || b.number !== null) {
+		if (a.number === null) return 1;
+		if (b.number === null) return -1;
+		return a.number - b.number;
+	}
+	if (a.proposed_at !== b.proposed_at) return a.proposed_at < b.proposed_at ? -1 : 1;
+	return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+/**
+* The `adr-list/v1` document: decisions in list order, filtered by `status` and by `since` (only
+* the decisions with event files added since its revision, from `changedSince`), and truncated to
+* `limit` after ordering. `findings` are those of the listed decisions and of the log as a whole.
+*/
+function listDecisions(read, o = {}) {
+	const statuses = o.status === void 0 || o.status.length === 0 ? null : new Set(o.status);
+	const since = o.since ?? null;
+	const changed = since === null ? null : new Set(since.events.map((e) => e.subject));
+	const decisions = [...read.projection.views.values()].filter((v) => statuses === null || statuses.has(v.status)).filter((v) => changed === null || changed.has(v.id)).sort(compareViews).slice(0, o.limit ?? Number.POSITIVE_INFINITY);
+	const listed = new Set(decisions.map((v) => v.id));
+	return {
+		format: "adr-list/v1",
+		root: read.root,
+		ref: read.ref,
+		commit: read.commit,
+		numbering: numberingJson(read),
+		decisions,
+		since,
+		unreadable: read.projection.unreadable,
+		unfoldable: read.projection.unfoldable,
+		findings: read.findings.filter((f) => f.subject === null || listed.has(f.subject)),
+		notes: read.notes
+	};
+}
+const decoder = new TextDecoder();
+/**
+* The `adr-show/v1` document of the decision `id` (resolve it with `resolveDecision` first).
+* Throws `UsageError` for an unknown, unreadable or unfoldable decision.
+*/
+async function showDecision(read, id, o = {}) {
+	const view = read.projection.views.get(id);
+	if (view === void 0) {
+		if (read.projection.unreadable.includes(id)) throw new UsageError(`decision ${id} uses a newer format; upgrade adr`);
+		if (read.projection.unfoldable.includes(id)) throw new UsageError(`decision ${id} can't be read; run adr verify`);
+		throw new UsageError(`unknown decision ${id}`);
+	}
+	const loaded = read.folded.subjects.get(id)?.loaded;
+	const body = loaded?.body ?? null;
+	const events = o.history === true ? (loaded?.events ?? []).flatMap((e) => e.event === null ? [] : [{
+		path: e.path,
+		event: e.event
+	}]).sort((a, b) => compareEvents({
+		...a.event,
+		path: a.path
+	}, {
+		...b.event,
+		path: b.path
+	})).map((e) => e.event) : null;
+	return {
+		format: "adr-show/v1",
+		root: read.root,
+		ref: read.ref,
+		commit: read.commit,
+		numbering: numberingJson(read),
+		header: stateHeader(view, read),
+		decision: view,
+		body: body === null ? null : decoder.decode(body.bytes),
+		events,
+		findings: read.findings.filter((f) => f.subject === id),
+		notes: read.notes
+	};
+}
+const day = (at) => (at ?? "").slice(0, 10);
+/** The reason on the applied event that produced the decision's current status, if any. */
+function statusReason(read, id) {
+	const reason = (read.folded.subjects.get(id)?.applied ?? []).findLast((a) => a.from !== a.to)?.event.reason;
+	return typeof reason === "string" && reason.trim() !== "" ? reason.trim() : null;
+}
+/**
+* The state header (01:258–259): `<display> (<id>) · <status>`, and for a decision that isn't in
+* force a warning saying what to read instead. `refer` names where to read another decision. CLI
+* default: `display(id)`. Phase 3 MCP passes `id => "adr://decision/" + display(id)`, e.g.
+* `adr://decision/ADR-0012`, or the id when unnumbered.
+*/
+function stateHeader(view, read, o = {}) {
+	const display = (id) => read.projection.views.get(id)?.display ?? id;
+	const refer = o.refer ?? display;
+	const line = view.number === null ? `${view.id} · ${view.status}` : `${view.display} (${view.id}) · ${view.status}`;
+	const parts = [];
+	const reason = statusReason(read, view.id);
+	const when = day(view.status_at);
+	switch (view.status) {
+		case "superseded": {
+			const target = view.effective ?? view.superseded_by ?? view.id;
+			const accepted = read.projection.views.get(target)?.decided_at ?? null;
+			const date = accepted === null ? "" : ` (accepted ${day(accepted)})`;
+			parts.push(`SUPERSEDED by ${display(target)}${date}. Do not apply this decision; read ${refer(target)} instead.`);
+			if (view.chain.length > 2) parts.push(`Chain: ${view.chain.map(display).join(" → ")}.`);
+			break;
+		}
+		case "deprecated":
+			parts.push(`DEPRECATED on ${when}: ${reason ?? "no reason given"}. No decision replaces it.`);
+			break;
+		case "rejected":
+			parts.push(`REJECTED on ${when}: ${reason ?? "no reason given"}. This decision was never in force.`);
+			break;
+		case "withdrawn": parts.push(`WITHDRAWN on ${when}${reason === null ? "" : `: ${reason}`}. This decision was never in force.`);
+	}
+	if (view.body_intact === false) parts.push("WARNING: the body changed after acceptance; run adr verify.");
+	return {
+		line,
+		warning: parts.length === 0 ? null : parts.join(" ")
+	};
+}
+// src/scope.ts
+const MAX_PATHS = 100;
+const MAX_PATH_LENGTH = 4096;
+/** Statuses whose globs govern code; rejected and withdrawn decisions were never in force. */
+const GLOBS_APPLY = /* @__PURE__ */ new Set([
+	"proposed",
+	"accepted",
+	"deprecated",
+	"superseded"
+]);
+const STATUS_ORDER = [
+	"accepted",
+	"proposed",
+	"deprecated",
+	"superseded",
+	"rejected",
+	"withdrawn"
+];
+/** Accepted first (design §6.9 step 5); within a status by number, then by id. */
+function compareFor(a, b) {
+	const s = STATUS_ORDER.indexOf(a.status) - STATUS_ORDER.indexOf(b.status);
+	if (s !== 0) return s;
+	if (a.number !== null || b.number !== null) {
+		if (a.number === null) return 1;
+		if (b.number === null) return -1;
+		return a.number - b.number;
+	}
+	return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+/** `path` (relative to `cwd`) as a repo-relative POSIX path; `UsageError` outside the work tree. */
+async function repoPath(root, cwd, path) {
+	if (path.length > MAX_PATH_LENGTH) throw new UsageError(`a path can be at most ${MAX_PATH_LENGTH} characters`);
+	const base = await realpath(cwd).catch(() => cwd);
+	const rel = relative(root, resolve(base, path));
+	if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new UsageError(`${path} is outside the repository`);
+	return rel.split(sep).join("/");
+}
+/**
+* Which decisions govern each path (design §6.9): globs of decisions that were ever in force, and
+* comment anchors of any decision, read from the work tree or, with a `--ref` log, that commit.
+* Paths are relative to `o.cwd` (default the repository root); directories and paths outside the
+* repository are `UsageError`s. Paths need not be tracked.
+*/
+async function decisionsFor(read, log, o) {
+	const root = log.git.root;
+	if (root === null) throw new UsageError("adr for needs a work tree");
+	if (o.paths.length === 0 || o.paths.length > MAX_PATHS) throw new UsageError(`adr for takes 1 to ${MAX_PATHS} paths`);
+	let index = null;
+	const indexed = () => {
+		index ??= indexReader(log.git);
+		return index;
+	};
+	const hasUnder = async (tree, path) => (await tree.list(path)).some((e) => e.path !== path);
+	const paths = [];
+	for (const given of o.paths) {
+		const path = await repoPath(root, o.cwd ?? root, given);
+		let directory = path === "";
+		if (!directory && read.ref === null) {
+			const st = await lstat(join(root, path)).catch(() => null);
+			directory = st === null ? await hasUnder(await indexed(), path) : st.isDirectory();
+		} else if (!directory) directory = await hasUnder(read.tree, path);
+		if (directory) throw new UsageError(`${given} is a directory; adr for takes file paths, for example adr for $(git ls-files ${given})`);
+		if (!paths.includes(path)) paths.push(path);
+	}
+	const atRef = read.ref !== null && read.commit !== null;
+	const trackedIn = atRef ? read.tree : await indexed();
+	const tracked = /* @__PURE__ */ new Set();
+	for (const p of paths) if ((await trackedIn.list(p)).some((e) => e.path === p)) tracked.add(p);
+	const anchors = await scanAnchors(log.git, {
+		keyword: read.adr.anchorKeyword,
+		tree: atRef ? { commit: read.commit } : "worktree",
+		paths,
+		excludeDirs: [read.layout.root],
+		exclude: read.adr.anchorExclude
+	});
+	const views = read.projection.views;
+	const lookup = scopeLookup({
+		subjects: [...views.values()].filter((v) => GLOBS_APPLY.has(v.status)).map((v) => ({
+			id: v.id,
+			globs: v.applies_to
+		})),
+		anchors
+	});
+	const listed = /* @__PURE__ */ new Set();
+	const out = paths.map((path) => {
+		const decisions = [];
+		const unresolved = [];
+		for (const m of lookup(path)) {
+			const view = m.source === null ? views.get(m.id) : void 0;
+			if (view === void 0) {
+				for (const v of m.via) {
+					if (v.type !== "anchor") continue;
+					unresolved.push({
+						ref: m.source === null ? m.id : `${m.source}:${m.id}`,
+						line: v.line,
+						reason: m.source === null ? "not-found" : "other-log"
+					});
+				}
+				continue;
+			}
+			decisions.push({
+				view,
+				via: m.via
+			});
+			listed.add(view.id);
+		}
+		decisions.sort((a, b) => compareFor(a.view, b.view));
+		unresolved.sort((a, b) => a.line - b.line);
+		return {
+			path,
+			tracked: tracked.has(path),
+			decisions: decisions.map(({ view: v, via }) => ({
+				id: v.id,
+				display: v.display,
+				title: v.title,
+				status: v.status,
+				effective: v.effective,
+				warning: stateHeader(v, read).warning,
+				via
+			})),
+			unresolved
+		};
+	});
+	return {
+		format: "adr-for/v1",
+		root: read.root,
+		ref: read.ref,
+		commit: read.commit,
+		numbering: numberingJson(read),
+		paths: out,
+		findings: read.findings.filter((f) => f.subject === null || listed.has(f.subject)),
+		notes: read.notes
+	};
+}
+export { openDecisionLog as A, adrChecks as C, runDecisionIndex as D, renderDecisionIndex as E, parseAdrConfig as F, readDecisionsFrom as M, resolveDecision as N, changedSince as O, DEFAULT_ADR_CONFIG as P, withdrawDecision as S, indexDecisionLog as T, proposeDecision as _, initDecisionLog as a, scopeToCopy as b, installDecisionHooks as c, uninstallDecisionHooks as d, acceptDecision as f, noteDecision as g, linkDecision as h, stateHeader as i, readDecisions as j, numberingNote as k, printDecisionHooks as l, followScopeRenames as m, listDecisions as n, addHookTrailers as o, deprecateDecision as p, showDecision as r, decisionHookCommands as s, decisionsFor as t, runPreCommitHook as u, rejectDecision as v, verifyDecisions as w, supersedeDecision as x, scopeDecision as y };
+
+//# sourceMappingURL=scope-CLqH-q1y.js.map