@nikovirtala/adr 0.2.0 → 0.4.0

package/dist/{write-9IaqHRrY.js → search-CwIPlNGd.js}

@@ -1,30 +1,87 @@
-import { t as adrKind } from "./kind-BcHjCHvi.js";
-import { ConfigError, ENVELOPE_VERSION, EventExistsError, FileExistsError, InvalidArgumentError, UsageError, applySetOp, bodyFileName, bodySha256, classifyPath, compareEvents, compileKind, eventDir, eventPath, finding, foldChecks, foldLog, followRenames, gitTemplates, globMatcher, historyTemplates, indexReader, invariantsCheck, isSubjectId, lintDocument, lintTemplate, loadFindings, loadLog, newSubjectId, nextEventIdentity, numberLog, openToolLog, overlayTree, parseCommitTemplate, parseEventFileName, parseGlob, parseTemplate, projectLog, readCommitTemplate, readToolConfig, refReader, relateCheck, renderCommitMessage, renderTemplate, resolveSubjectInput, scanAnchors, scopeLookup, serializeEvent, slugify, sortFindings, stagedRenames, templateHistoryRef, transitions, verifyLog, writeEvents, writeNewFile } from "@nikovirtala/ledger";
-import { lstat, readFile, realpath, rm } from "node:fs/promises";
-import { isAbsolute, join, relative, resolve, sep } from "node:path";
-// src/config.ts
+import { t as adrKind } from "./kind-DjvA3dyA.js";
+import { CommitFailedError, ConfigError, ENVELOPE_VERSION, EventExistsError, FileExistsError, InvalidArgumentError, MemoryTree, UsageError, applySetOp, bodyFileName, bodySha256, classifyPath, commitWithRecovery, compareEvents, compileKind, diffTrees, escapeMarkdown, eventDir, eventPath, extractSections, finding, foldLog, followRenames, globMatcher, historyTemplates, indexCheck, indexReader, invariantsCheck, isSubjectId, lintDocument, lintTemplate, loadFindings, loadLog, newSubjectId, nextEventIdentity, numberLog, openToolLog, overlayTree, parseCommitTemplate, parseEventFileName, parseGlob, parseTemplate, projectLog, projectNumbering, readCommitTemplate, readIndexNumbers, refReader, relateCheck, renderCommitMessage, renderIndex, renderTemplate, replaceFile, replaceSections, resolveSubjectInput, saveCommitRecovery, scanAnchors, scopeLookup, serializeEvent, slugify, sortFindings, stagedRenames, templateHistoryRef, transitions, verifyLog, worktreeReader, writeEvents, writeIndexFile, writeNewFile } from "@nikovirtala/ledger";
+import { 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"
+	}
+};
+/** `{action}` of a draft update (`adr_update_draft`), whose title slot holds the display. */
+const DRAFT_ACTION = "update the draft of";
+/** The longest `{action}`, which `[commit] subject` must leave room for. */
+const LONGEST_ACTION = Math.max(...Object.values(ACTIONS).map((a) => a.action.length), 10, 19);
+/** 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: 24,
+	action: LONGEST_ACTION,
 	id: 8,
 	display: 13,
 	command: 9
 });
-/** The default `[commit] subject`. */
-const DEFAULT_COMMIT_SUBJECT = "docs(adr): {action} {title}";
 /**
 * 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). The shorter names (a display,
-* at most 13 characters) always fit in the room a title gets.
+* `<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: COMMIT_VARS.display * 2 + 6,
-	vars: { action: 9 }
-}, {
-	length: COMMIT_VARS.display + 29,
-	vars: { action: 4 }
-}]);
+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,
@@ -33,6 +90,9 @@ const DEFAULT_ADR_CONFIG = Object.freeze({
 	autoCommit: false,
 	mcpCanDecide: false,
 	failOn: "error",
+	governedByInactive: "warning",
+	scopeFollowRenames: "stage",
+	hookIndex: "check",
 	commitSubject: parseCommitTemplate(DEFAULT_COMMIT_SUBJECT, {
 		vars: COMMIT_VARS,
 		where: "commit.subject",
@@ -66,6 +126,7 @@ function parseAdrConfig(config, file) {
 	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;
@@ -101,6 +162,13 @@ function parseAdrConfig(config, file) {
 		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,
@@ -111,221 +179,6 @@ function parseAdrConfig(config, file) {
 		anchorExclude: Array.isArray(exclude) ? exclude : []
 	};
 }
-/** 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/init.ts
-const CONFIG = "adr.toml";
-const DEFAULT_ROOT = adrKind.def.defaultRoot;
-const encoder$1 = 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 `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 commit = files.length > 0 && (o.commit ?? log.adr.autoCommit);
-	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$1.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 log.git.commit({
-			message,
-			only: written
-		});
-	}
-	return {
-		format: "adr-init/v1",
-		root,
-		config,
-		written,
-		kept,
-		commit: sha,
-		notes
-	};
-}
 // src/log.ts
 /**
 * Opens the decision log (design D3): `--root`, else `adr.toml`'s `[log] root`, else `docs/adr`;
@@ -342,20 +195,33 @@ async function openDecisionLog(o) {
 		adr: parseAdrConfig(log.config, log.configPath)
 	};
 }
-/** `numberLog` on the repository, then `readDecisionsFrom(log.tree, …)`. */
+/**
+* `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) {
-	const numbering = await numberLog(log.git, {
-		kind: adrKind,
-		layout: log.layout,
-		mainRef: log.adr.mainBranch
-	});
 	return readDecisionsFrom(log.tree, {
 		layout: log.layout,
 		adr: log.adr,
-		numbering,
+		numbering: await numberDecisions(log),
 		ref: log.ref,
 		commit: log.commit,
-		notes: log.notes
+		notes: log.notes,
+		sources: (log.config?.sources ?? []).map((s) => s.name)
+	});
+}
+/** 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);
@@ -402,9 +268,33 @@ async function readDecisionsFrom(tree, o) {
 			...f,
 			kind: adrKind.name
 		}))),
-		notes: o.notes ?? []
+		notes: o.notes ?? [],
+		sources: o.sources ?? []
 	};
 }
+/**
+* The note listing reads add while only the local log is read: the logs of `[[sources]]` aren't
+* listed or searched until ark's step 4. `null` without sources.
+*/
+function sourcesNote(read) {
+	if (read.sources.length === 0) return null;
+	return `only this repository's decision log is read; the logs in [[sources]] (${read.sources.join(", ")}) aren't listed or searched until ark's step 4`;
+}
+/** `read.notes`, then the sources note when there is one. */
+function listingNotes(read) {
+	const note = sourcesNote(read);
+	return note === null ? read.notes : [...read.notes, note];
+}
+/**
+* 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";
@@ -428,289 +318,467 @@ function resolveDecision(read, input) {
 		case "not-found": throw new UsageError(`unknown decision ${input.trim()}`);
 	}
 }
-// 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 truncated to
-* `limit` after ordering. `findings` are those of the listed decisions and of the log as a whole.
+* 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.
 */
-function listDecisions(read, o = {}) {
-	const statuses = o.status === void 0 || o.status.length === 0 ? null : new Set(o.status);
-	const decisions = [...read.projection.views.values()].filter((v) => statuses === null || statuses.has(v.status)).sort(compareViews).slice(0, o.limit ?? Number.POSITIVE_INFINITY);
-	const listed = new Set(decisions.map((v) => v.id));
+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 {
-		format: "adr-list/v1",
-		root: read.root,
-		ref: read.ref,
-		commit: read.commit,
-		numbering: numberingJson(read),
-		decisions,
-		unreadable: read.projection.unreadable,
-		unfoldable: read.projection.unfoldable,
-		findings: read.findings.filter((f) => f.subject === null || listed.has(f.subject)),
-		notes: read.notes
+		rev,
+		commit: base.commit ?? "",
+		events
 	};
 }
-const decoder$1 = new TextDecoder();
+// src/log-index.ts
 /**
-* The `adr-show/v1` document of the decision `id` (resolve it with `resolveDecision` first).
-* Throws `UsageError` for an unknown, unreadable or unfoldable decision.
+* 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.
 */
-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 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 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$1.decode(body.bytes),
-		events,
-		findings: read.findings.filter((f) => f.subject === id),
-		notes: read.notes
-	};
+];
+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);
 }
-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;
+/** 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 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.
+* 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.
 */
-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;
+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
+			});
 		}
-		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(" ")
+		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);
+		}
 	};
 }
-// 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;
+const encoder$1 = new TextEncoder();
+/** Whether `bytes` (null: absent) hold exactly `text`. */
+function holdsText(bytes, text) {
+	if (bytes === null) return false;
+	const want = encoder$1.encode(text);
+	return bytes.byteLength === want.byteLength && bytes.every((x, i) => x === want[i]);
 }
-/** `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("/");
+/** 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);
 }
 /**
-* 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.
+* 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 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;
+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)
 	};
-	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);
+}
+/** 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
+		};
 	}
-	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
+	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 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);
+	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 {
-			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
+			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 {
-		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
+		doc: {
+			format: "adr-index/v1",
+			path,
+			check: false,
+			fresh,
+			written: written ? [path] : [],
+			commit: sha,
+			findings: [],
+			notes
+		},
+		refreshed
 	};
 }
-// src/verify.ts
 /**
-* Every phase-1 check for the log: ledger's mechanical and fold checks with adr's actor policy,
-* and template lint against the templates in the head tree and, for older versions, the history
-* of `historyRef`.
+* `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.
 */
-function adrChecks(log, historyRef) {
-	return foldChecks(adrKind, {
-		options: { acceptRequiresHuman: log.adr.acceptRequiresHuman },
-		templates: gitTemplates(log.git, { historyRef })
-	});
-}
-/** 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))
-	});
+async function indexDecisionLog(log, o = {}) {
+	return (await runDecisionIndex(log, o)).doc;
 }
-// src/write.ts
-const encoder = new TextEncoder();
-const decoder = 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();
+/** 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 = new TextEncoder();
+const decoder$2 = 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) {
@@ -795,14 +863,18 @@ const findingKey = (f) => [
 * 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), {
+async function precheck(read, files, replace = {}) {
+	const after = await readDecisionsFrom(overlayTree(read.tree, {
+		...files,
+		...replace
+	}), {
 		layout: read.layout,
 		adr: read.adr,
 		numbering: read.numbering,
 		ref: read.ref,
 		commit: read.commit,
-		notes: read.notes
+		notes: read.notes,
+		sources: read.sources
 	});
 	const before = new Set(read.findings.map(findingKey));
 	return {
@@ -821,7 +893,7 @@ async function chooseTemplate(read, name, c) {
 	const bytes = await read.tree.read(path);
 	let text;
 	let materialize = null;
-	if (bytes !== null) text = decoder.decode(bytes);
+	if (bytes !== null) text = decoder$2.decode(bytes);
 	else {
 		const builtin = Object.hasOwn(c.builtins, name) ? c.builtins[name] : void 0;
 		if (builtin === void 0) {
@@ -988,6 +1060,126 @@ async function acceptLint(read, view, c) {
 		bytes: body.bytes
 	};
 }
+const MAX_SECTIONS = 50;
+/**
+* Plans a draft update (design §6.6): the given sections of a proposed decision's body replaced in
+* place, every other line kept, written only if the body still holds the bytes read. Refused
+* (`ok: false`) when the decision isn't proposed or its body or template version is missing or
+* unreadable, and with `refuseIncomplete` when the new draft fails its template lint. An unknown
+* section, a missing heading or a heading in the content is a `UsageError`.
+*/
+async function planUpdateDraft(read, input, c, o = {}) {
+	const id = resolveDecision(read, input.id);
+	const view = viewOf(read, id);
+	const refused = (fs) => ({
+		ok: false,
+		decision: view,
+		findings: fs
+	});
+	if (view.status !== "proposed") return refused([refusal(read, "decision/not-a-draft", `${namedView(view)} is ${view.status}; only a proposed decision's draft can change`, id)]);
+	const ids = Object.keys(input.sections);
+	if (ids.length === 0 || ids.length > MAX_SECTIONS) throw new UsageError(`a draft update takes 1 to ${MAX_SECTIONS} sections`);
+	for (const [section, text] of Object.entries(input.sections)) checkText(`section ${section}`, text);
+	const { findings: problems, template, text, body } = await draftOf(read, view, c);
+	if (problems.length > 0 || template === null || text === null || body === null) return refused(problems);
+	const r = replaceSections(template, text, input.sections);
+	if (!r.ok) {
+		const [first] = r.findings;
+		if (first?.rule === "render/unknown-section") {
+			const known = template.sections.map((s) => s.id).join(", ");
+			const unknown = ids.find((s) => !template.sections.some((t) => t.id === s)) ?? "";
+			throw new UsageError(`template ${template.name} has no section ${unknown}; its sections are ${known}`);
+		}
+		if (first?.rule === "render/section-missing") {
+			const gone = new Set(extractSections(template, text).missing);
+			const missing = template.sections.find((s) => ids.includes(s.id) && gone.has(s.id));
+			throw new UsageError(`${body.path} has no '${missing?.heading ?? ""}' heading; edit the file by hand`);
+		}
+		throw new UsageError(r.findings.map((f) => f.message).join("; "));
+	}
+	if (r.text === text) return emptyPlan(id, view, ["the draft already has this content; nothing written"]);
+	const bytes = encoder.encode(r.text);
+	const lint = lintDocument(template, r.text, {
+		file: body.path,
+		subject: id
+	}).map((f) => ({
+		...f,
+		kind: adrKind.name
+	}));
+	if (o.refuseIncomplete === true && lint.length > 0) return refused(lint);
+	const { after, added } = await precheck(read, {}, { [body.path]: bytes });
+	if (added.length > 0) return refused(added);
+	const { scope, eventDirs } = commitScope(read, [id]);
+	const order = template.sections.map((s) => s.id).filter((s) => ids.includes(s));
+	return {
+		ok: true,
+		plan: {
+			command: "event",
+			subject: id,
+			files: {},
+			replace: { [body.path]: {
+				bytes,
+				expected: body.bytes
+			} },
+			events: [],
+			stage: [body.path],
+			involved: [id],
+			commitScope: scope,
+			eventDirs,
+			draft: null,
+			commit: {
+				action: DRAFT_ACTION,
+				title: view.display,
+				id,
+				display: view.display,
+				body: [`Sections: ${order.join(", ")}.`]
+			},
+			trailers: [["ADR", id]],
+			decision: after.projection.views.get(id) ?? view,
+			affected: [],
+			findings: lint
+		}
+	};
+}
+/**
+* A proposed decision's body, its text and the template version its proposal recorded, or the
+* refusal findings when one of them is missing or the body isn't UTF-8.
+*/
+async function draftOf(read, view, c) {
+	const none = {
+		template: null,
+		text: null,
+		body: null
+	};
+	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)],
+		...none
+	};
+	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)],
+			...none
+		};
+	}
+	try {
+		const text = new TextDecoder("utf-8", { fatal: true }).decode(body.bytes);
+		return {
+			findings: [],
+			template: found.template,
+			text,
+			body
+		};
+	} catch {
+		return {
+			findings: [refusal(read, "body/not-utf8", "body is not valid UTF-8", view.id)],
+			...none
+		};
+	}
+}
 /** 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);
@@ -1176,48 +1368,6 @@ async function planSupersede(read, input, c) {
 		}
 	};
 }
-/**
-* `{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"
-	}
-};
 const actionOf = (type) => Object.hasOwn(ACTIONS, type) ? ACTIONS[type] : {
 	action: type,
 	names: "display"
@@ -1352,7 +1502,7 @@ async function planLink(read, input, c, o = {}) {
 		to = target;
 		shown = target;
 		described = `${rel} ${target}.`;
-		named = `${view.display} to a decision in another log`;
+		named = `${view.display} ${CROSS_LOG_LINK}`;
 	} else {
 		to = resolveDecision(read, target);
 		if (to === id) throw new UsageError("a decision can't link to itself");
@@ -1457,7 +1607,10 @@ async function planScope(read, input, c, o = {}) {
 			notes
 		}
 	};
-	if (o.tracked !== void 0) notes.push(...unmatchedGlobs(result.set, o.tracked).map((g) => `${g} matches no tracked file`));
+	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,
@@ -1618,9 +1771,29 @@ async function trackedFiles(log) {
 }
 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.";
+/**
+* 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`;
+}
+/**
 * 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.
+* 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.
 */
 async function applyPlan(log, plan, o) {
 	const { git } = log;
@@ -1633,24 +1806,93 @@ async function applyPlan(log, plan, o) {
 		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] ?? plan.replace?.[p]?.bytes ?? 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,
+			...replaceBytes(plan)
+		});
+		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 = [];
+	const replaced = [];
 	try {
+		for (const [path, r] of Object.entries(plan.replace ?? {})) {
+			await replaceFile(git, path, r.bytes, { expected: r.expected });
+			replaced.push(path);
+		}
 		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 root = git.root ?? "";
-		for (const path of written) await rm(join(root, path), { force: true });
+		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 });
+		for (const path of replaced) {
+			const r = plan.replace?.[path];
+			if (r !== void 0) await replaceFile(git, path, r.expected, { expected: r.bytes }).catch(() => {});
+		}
 		throw err;
 	}
-	await git.add(plan.stage);
+	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) {
@@ -1658,25 +1900,110 @@ async function applyPlan(log, plan, o) {
 		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 git.stagedPaths(plan.commitScope)).filter((p) => !stage.has(p));
+		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]] : [];
 		});
-		sha = await git.commit({
-			message: o.message ?? "",
-			mergeTrailers: o.mergeTrailers === true,
-			trailers: [...staged, ...plan.trailers],
-			only: sorted([...plan.stage, ...extra])
-		});
+		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),
+		written: [
+			...Object.keys(plan.replace ?? {}),
+			...Object.keys(plan.files),
+			...indexWritten ? [at] : []
+		],
 		commit: sha,
-		findings
+		findings,
+		notes
+	};
+}
+/** The new bytes of each file a plan replaces. */
+const replaceBytes = (plan) => Object.fromEntries(Object.entries(plan.replace ?? {}).map(([p, r]) => [p, r.bytes]));
+/** `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 = {
@@ -1763,7 +2090,7 @@ async function write(log, command, plan, o, deps, afterStage) {
 			findings: r.findings,
 			notes
 		};
-		if (r.plan.events.length === 0 && Object.keys(r.plan.files).length === 0 || o.dryRun === true) return {
+		if (r.plan.events.length === 0 && Object.keys(r.plan.files).length === 0 && Object.keys(r.plan.replace ?? {}).length === 0 || o.dryRun === true) return {
 			format: "adr-write/v1",
 			command,
 			ok: true,
@@ -1783,10 +2110,20 @@ async function write(log, command, plan, o, deps, afterStage) {
 					message: given ?? rendered.message,
 					mergeTrailers: given !== null
 				},
-				...afterStage === void 0 ? {} : { afterStage: afterStage(r.plan, commit) }
+				...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.commit !== null && given === null && rendered?.shortened === true ? [SHORTENED_NOTE] : []];
+			const own = [
+				...r.plan.notes ?? [],
+				...applied.notes,
+				...applied.commit !== null && given === null && rendered?.shortened === true ? [SHORTENED_NOTE] : []
+			];
 			return {
 				format: "adr-write/v1",
 				command,
@@ -1799,6 +2136,7 @@ async function write(log, command, plan, o, deps, afterStage) {
 				notes: [...notes, ...own]
 			};
 		} catch (err) {
+			if (err instanceof CommitFailedError) throw err.withNotes([...notes, ...r.plan.notes ?? []]);
 			if (!(err instanceof EventExistsError) || attempt > 0) throw err;
 		}
 	}
@@ -1848,7 +2186,7 @@ function editorStep(log, edit, onNote) {
 				onNote?.(`${first} changed while the editor was open; review it, then git add it and commit`);
 			}
 		}
-		const text = decoder.decode(bytes ?? d.rendered);
+		const text = decoder$2.decode(bytes ?? d.rendered);
 		const findings = lintDocument(d.template, text, {
 			file: d.path,
 			subject: plan.subject
@@ -1948,6 +2286,19 @@ 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);
 }
+/**
+* Replaces sections of a proposed decision's draft (design §6.6), stages the body, and commits
+* with `commit` (default `[policy] auto_commit`). A body with unstaged changes is a `UsageError`,
+* so nobody's unsaved edit is folded into this write; a body changed between plan and write is
+* `FileChangedError`. A commit is never made of a draft that fails its template lint: it is
+* refused (`ok: false`, nothing written), as for `proposeDecision` without an editor.
+*/
+async function updateDraft(log, input, o = {}, deps = DEFAULT_DEPS) {
+	const read = await readDecisions(log);
+	const view = viewOf(read, resolveDecision(read, input.id));
+	if (view.body_path !== null && (await log.git.unstagedPaths([view.body_path])).length > 0) throw new UsageError(`${view.body_path} has unstaged changes; stage or discard them, or edit the draft by hand`);
+	return write(log, "update", (read, c) => planUpdateDraft(read, input, c, { refuseIncomplete: o.commit ?? log.adr.autoCommit }), 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
@@ -1981,6 +2332,434 @@ async function followScopeRenames(log, input, o = {}, deps = DEFAULT_DEPS) {
 		notes: [...doc.notes, FOLLOW_NO_COMMIT_NOTE]
 	} : doc;
 }
-export { initDecisionLog as C, unavailableReason as S, parseAdrConfig as T, stateHeader as _, noteDecision as a, readDecisionsFrom as b, scopeDecision as c, withdrawDecision as d, adrChecks as f, showDecision as g, listDecisions as h, linkDecision as i, scopeToCopy as l, decisionsFor as m, deprecateDecision as n, proposeDecision as o, verifyDecisions as p, followScopeRenames as r, rejectDecision as s, acceptDecision as t, supersedeDecision as u, openDecisionLog as v, DEFAULT_ADR_CONFIG as w, resolveDecision as x, readDecisions as y };
+// 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: listingNotes(read)
+	};
+}
+const decoder$1 = 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$1.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"
+]);
+/** The order `adr for` and `adr search` list statuses in: in force first. */
+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: listingNotes(read)
+	};
+}
+// src/search.ts
+const MAX_QUERY = 200;
+const MAX_TERMS = 10;
+const EXCERPT = 160;
+const LEAD = 60;
+const WORD_SLACK = 15;
+const ACTIVE = /* @__PURE__ */ new Set(["proposed", "accepted"]);
+const decoder = new TextDecoder("utf-8", { fatal: true });
+/**
+* Case- and accent-insensitive form: per code point NFKD, combining marks dropped, lower-cased.
+* `Café` → `cafe` and `fi` → `fi`; `ß` and `ø` have no decomposition and stay as they are.
+*/
+function fold(s) {
+	let text = "";
+	const at = [];
+	let offset = 0;
+	for (const c of s) {
+		const f = c.normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase();
+		text += f;
+		for (let i = 0; i < f.length; i++) at.push(offset);
+		offset += c.length;
+	}
+	at.push(offset);
+	return {
+		text,
+		at
+	};
+}
+const count = (hay, needle) => {
+	let n = 0;
+	for (let i = hay.indexOf(needle); i >= 0; i = hay.indexOf(needle, i + needle.length)) n++;
+	return n;
+};
+/** The query's terms, or a `UsageError` for an empty, long, control-character or many-word query. */
+function queryTerms(query) {
+	const q = query.trim();
+	if (q === "" || q.length > MAX_QUERY || /[\u0000-\u001f\u007f]/.test(q)) throw new UsageError(`the search query must be 1 to ${MAX_QUERY} characters without control characters`);
+	const terms = [...new Set(fold(q).text.split(/\s+/).filter((t) => t !== ""))];
+	if (terms.length > MAX_TERMS) throw new UsageError(`a search takes at most ${MAX_TERMS} words`);
+	if (terms.length === 0) throw new UsageError("the search query must contain a letter, digit or symbol");
+	return terms;
+}
+/** The body text without its first `# ` title line; `""` when missing or not UTF-8. */
+function bodyText(read, id) {
+	const bytes = read.folded.subjects.get(id)?.loaded?.body?.bytes;
+	if (bytes === void 0) return "";
+	let text;
+	try {
+		text = decoder.decode(bytes).replace(/\r\n/g, "\n");
+	} catch {
+		return "";
+	}
+	const lines = text.split("\n");
+	const title = lines.findIndex((l) => l.startsWith("# "));
+	if (title >= 0) lines.splice(title, 1);
+	return lines.join("\n");
+}
+function noteTexts(read, id) {
+	return (read.folded.subjects.get(id)?.applied ?? []).flatMap((a) => {
+		const text = a.event.data?.text;
+		return a.event.type === "noted" && typeof text === "string" ? [text] : [];
+	});
+}
+/** The excerpt of the first line with the most distinct terms, windowed around the first hit. */
+function excerpt(lines, terms) {
+	let best = null;
+	for (const raw of lines) {
+		const line = raw.replace(/\s+/g, " ").trim();
+		const folded = fold(line).text;
+		const hits = terms.filter((t) => folded.includes(t)).length;
+		if (hits > 0 && (best === null || hits > best.hits)) best = {
+			line,
+			hits
+		};
+	}
+	if (best === null) return null;
+	const { line } = best;
+	if (line.length <= EXCERPT) return line;
+	const f = fold(line);
+	const first = Math.min(...terms.map((t) => f.text.indexOf(t)).filter((i) => i >= 0));
+	let start = Math.max(0, (f.at[first] ?? 0) - LEAD);
+	if (start > 0 && line[start - 1] !== " ") {
+		const space = line.indexOf(" ", start);
+		if (space >= 0 && space - start <= WORD_SLACK) start = space + 1;
+	}
+	let end = Math.min(line.length, start + EXCERPT);
+	if (end < line.length && line[end] !== " ") {
+		const space = line.lastIndexOf(" ", end);
+		if (space > start && end - space <= WORD_SLACK) end = space;
+	}
+	const cut = line.slice(start, end).trim();
+	return `${start > 0 ? "…" : ""}${cut}${end < line.length ? "…" : ""}`;
+}
+/**
+* Full-text search of the log (design §8.1): a decision matches when every term of the folded
+* query is a substring of its folded id, display number, title, body or note texts. Ranked by
+* score (10 for a term equal to the id or number, 5 in the title, up to 3 for body hits and 2
+* for note hits), then status as `adr for` orders them, then list order. Only proposed and
+* accepted decisions unless `includeInactive`. Throws `UsageError` for an invalid query.
+*/
+function searchDecisions(read, o) {
+	const terms = queryTerms(o.query);
+	if (o.limit !== void 0 && (!Number.isInteger(o.limit) || o.limit < 1)) throw new UsageError("the search limit must be a positive integer");
+	const includeInactive = o.includeInactive === true;
+	const found = [];
+	let inactive = 0;
+	for (const view of read.projection.views.values()) {
+		const body = bodyText(read, view.id);
+		const notes = noteTexts(read, view.id);
+		const id = fold(view.id).text;
+		const display = fold(view.display).text;
+		const title = fold(view.title).text;
+		const foldedBody = fold(body).text;
+		const foldedNotes = notes.map((n) => fold(n).text).join("\n");
+		const hit = /* @__PURE__ */ new Set();
+		let score = 0;
+		let all = true;
+		for (const t of terms) {
+			const inId = id.includes(t) || display.includes(t);
+			const inTitle = title.includes(t);
+			const inBody = count(foldedBody, t);
+			const inNotes = count(foldedNotes, t);
+			if (!inId && !inTitle && inBody === 0 && inNotes === 0) {
+				all = false;
+				break;
+			}
+			if (inId) hit.add("id");
+			if (inTitle) hit.add("title");
+			if (inBody > 0) hit.add("body");
+			if (inNotes > 0) hit.add("notes");
+			score += (t === id || t === display ? 10 : 0) + (inTitle ? 5 : 0) + Math.min(3, inBody) + Math.min(2, inNotes);
+		}
+		if (!all) continue;
+		if (!includeInactive && !ACTIVE.has(view.status)) {
+			inactive++;
+			continue;
+		}
+		const lines = [...body.split("\n").filter((l) => l.trim() !== "" && !l.startsWith("#")), ...notes.flatMap((n) => n.split("\n"))];
+		found.push({
+			view,
+			decision: view,
+			header: stateHeader(view, read),
+			score,
+			matched: [
+				"id",
+				"title",
+				"body",
+				"notes"
+			].filter((f) => hit.has(f)),
+			excerpt: excerpt(lines, terms)
+		});
+	}
+	found.sort((a, b) => b.score - a.score || STATUS_ORDER.indexOf(a.view.status) - STATUS_ORDER.indexOf(b.view.status) || compareViews(a.view, b.view));
+	const results = found.slice(0, o.limit ?? Number.POSITIVE_INFINITY).map(({ view: _, ...r }) => r);
+	const listed = new Set(results.map((r) => r.decision.id));
+	return {
+		format: "adr-search/v1",
+		root: read.root,
+		ref: read.ref,
+		commit: read.commit,
+		numbering: numberingJson(read),
+		query: o.query.trim(),
+		terms,
+		include_inactive: includeInactive,
+		total: found.length,
+		inactive_omitted: inactive,
+		results,
+		findings: read.findings.filter((f) => f.subject === null || listed.has(f.subject)),
+		notes: listingNotes(read)
+	};
+}
+export { changedSince as A, headTree as C, renderDecisionIndex as D, indexPath as E, readDecisionsFrom as F, resolveDecision as I, sourcesNote as L, numberingNote as M, openDecisionLog as N, runDecisionIndex as O, readDecisions as P, DEFAULT_ADR_CONFIG as R, firstLine as S, indexDecisionLog as T, withdrawDecision as _, stateHeader as a, INDEX_AFTER as b, followScopeRenames as c, proposeDecision as d, rejectDecision as f, updateDraft as g, supersedeDecision as h, showDecision as i, numberDecisions as j, writeIndexCopy as k, linkDecision as l, scopeToCopy as m, decisionsFor as n, acceptDecision as o, scopeDecision as p, listDecisions as r, deprecateDecision as s, searchDecisions as t, noteDecision as u, BUILTIN_TEMPLATES as v, holdsText as w, decisionIndexCheck as x, DECISION_INDEX as y, parseAdrConfig as z };
 
-//# sourceMappingURL=write-9IaqHRrY.js.map
+//# sourceMappingURL=search-CwIPlNGd.js.map