@nikovirtala/adr 0.2.0 → 0.3.0

package/dist/{write-9IaqHRrY.js → scope-CLqH-q1y.js}

@@ -1,30 +1,85 @@
-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, 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: 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 +88,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 +124,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 +160,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,253 +177,50 @@ 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");
+// 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)
+	};
 }
 /**
-* `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.
+* `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 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`;
-* 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, …)`. */
 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
 	});
 }
+/** 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) {
@@ -405,6 +268,16 @@ async function readDecisionsFrom(tree, o) {
 		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";
@@ -428,269 +301,440 @@ 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$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]);
 }
-/** `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
 	};
 }
+/**
+* `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 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`.
+* 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 })
-	});
+	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) {
@@ -702,9 +746,117 @@ async function verifyDecisions(log, 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 = new TextEncoder();
-const decoder = new TextDecoder();
+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;
@@ -715,7 +867,7 @@ 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.encode(text).byteLength;
+	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) {
@@ -811,7 +963,7 @@ async function precheck(read, files) {
 	};
 }
 function filesOf(events, read) {
-	return Object.fromEntries(events.map((e) => [eventPath(read.layout, e), encoder.encode(serializeEvent(e))]));
+	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. */
@@ -821,7 +973,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$1.decode(bytes);
 	else {
 		const builtin = Object.hasOwn(c.builtins, name) ? c.builtins[name] : void 0;
 		if (builtin === void 0) {
@@ -908,9 +1060,9 @@ async function planPropose(read, input, c, o = {}) {
 		},
 		actor: input.actor
 	});
-	const body = encoder.encode(rendered.text);
+	const body = encoder$1.encode(rendered.text);
 	const files = { [bodyPath]: body };
-	if (chosen.materialize !== null) files[chosen.path] = encoder.encode(chosen.materialize);
+	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 {
@@ -1176,48 +1328,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 +1462,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 +1567,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,10 +1731,30 @@ 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.";
+/**
 * 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.
 */
+/**
+* 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");
@@ -1633,6 +1766,53 @@ 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] ?? 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 {
@@ -1641,16 +1821,26 @@ async function applyPlan(log, plan, o) {
 			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 });
 		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 +1848,104 @@ 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.files), ...indexWritten ? [at] : []],
 		commit: sha,
-		findings
+		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 = {
@@ -1783,10 +2052,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 +2078,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 +2128,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$1.decode(bytes ?? d.rendered);
 		const findings = lintDocument(d.template, text, {
 			file: d.path,
 			subject: plan.subject
@@ -1981,6 +2261,613 @@ 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/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=write-9IaqHRrY.js.map
+//# sourceMappingURL=scope-CLqH-q1y.js.map