@nikovirtala/adr 0.3.0 → 0.5.0

package/dist/{scope-CLqH-q1y.js → search-CTspg2pd.js}

@@ -1,6 +1,6 @@
-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 { t as adrKind } from "./kind-C3DiBuUp.js";
+import { CommitFailedError, ConfigError, ENVELOPE_VERSION, EventExistsError, FileExistsError, InvalidArgumentError, MemoryTree, NO_NUMBERING, UsageError, applySetOp, bodyFileName, bodySha256, classifyPath, commitWithRecovery, compareEvents, compileKind, diffTrees, escapeMarkdown, eventDir, eventPath, eventTrailers, extractSections, finding, firstLine, foldLog, followRenames, globMatcher, headBytes, headTree, historyTemplates, holdsText, indexCheck, indexReader, invariantsCheck, isSubjectId, joinActions, lintDocument, lintTemplate, loadFindings, loadLog, newSubjectId, nextEventIdentity, numberLog, openToolLog, overlayTree, parseCommitTemplate, parseEventFileName, parseGlob, parseTemplate, projectLog, projectNumbering, readCommitTemplate, readIndexNumbers, readSources, refReader, relateCheck, renderCommitMessage, renderIndex, renderTemplate, replaceFile, replaceSections, resolveSubjectInput, saveCommitRecovery, scanAnchors, scopeLookup, serializeEvent, slugify, sortFindings, sourceLogRef, sourcesOfKinds, stagedRenames, templateHistoryRef, transitions, verifyLog, withoutPaths, worktreeReader, writeEvents, writeIndexCopy, 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
 /**
@@ -45,8 +45,34 @@ const ACTIONS = {
 		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);
+/**
+* The verb of each display-named event type in a batch subject (?6, design §4.4), and the order
+* they are joined in: `link and scope ADR-0003`, `add a note to` last so it reads before the name.
+*/
+const BATCH_ACTIONS = {
+	deprecated: "deprecate",
+	superseded: "supersede",
+	linked: "link",
+	scoped: "scope",
+	noted: "add a note to"
+};
+const BATCH_ORDER = [
+	"deprecated",
+	"superseded",
+	"linked",
+	"scoped",
+	"noted"
+];
+/** `{action}` of a batch of more than three verbs. */
+const UPDATE_ACTION = "update";
+/** `{action}` of a draft update (`adr_update_draft`), whose title slot holds the display. */
+const DRAFT_ACTION = "update the draft of";
+/**
+* The longest `{action}` that goes with a title, which `[commit] subject` must leave a title room
+* for. A batch action (up to `LONGEST_BATCH`) only ever goes with a display, so `COMMIT_NAMES`
+* covers it instead.
+*/
+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). */
@@ -75,6 +101,10 @@ const COMMIT_NAMES = Object.freeze([
 	{
 		length: 18,
 		vars: { action: 10 }
+	},
+	{
+		length: 13,
+		vars: { action: 6 }
 	}
 ]);
 // src/config.ts
@@ -206,7 +236,8 @@ async function readDecisions(log) {
 		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`. */
@@ -221,17 +252,17 @@ async function numberDecisions(log) {
 		} } : {}
 	});
 }
-const compiled$1 = compileKind(adrKind);
+const compiled$2 = compileKind(adrKind);
 /** The git-free core of `readDecisions`; tests pass a MemoryTree and a hand-made `Numbering`. */
 async function readDecisionsFrom(tree, o) {
 	const { layout, adr, numbering } = o;
 	const snapshot = await loadLog(tree, {
-		kind: compiled$1,
+		kind: compiled$2,
 		layout
 	});
 	const folded = foldLog(adrKind, snapshot);
 	const ctx = {
-		kind: compiled$1,
+		kind: compiled$2,
 		layout,
 		base: null,
 		head: snapshot,
@@ -243,7 +274,10 @@ async function readDecisionsFrom(tree, o) {
 			base: null
 		}
 	};
-	const options = { acceptRequiresHuman: adr.acceptRequiresHuman };
+	const options = {
+		acceptRequiresHuman: adr.acceptRequiresHuman,
+		sources: null
+	};
 	const findings = [];
 	for (const check of [
 		loadFindings,
@@ -265,10 +299,25 @@ async function readDecisionsFrom(tree, o) {
 			...f,
 			kind: adrKind.name
 		}))),
-		notes: o.notes ?? []
+		notes: o.notes ?? [],
+		sources: o.sources ?? [],
+		source: o.source ?? null
 	};
 }
 /**
+* The note listing reads add for a log with `[[sources]]`: the other logs are listed with
+* `--source`, from cached copies. `null` without sources, and for a `--source` read.
+*/
+function sourcesNote(read) {
+	if (read.sources.length === 0 || read.source !== null) return null;
+	return `the logs in [[sources]] (${read.sources.join(", ")}) are listed with --source <name>, from cached copies; run adr sources fetch to update them`;
+}
+/** `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.
 */
@@ -489,37 +538,6 @@ function decisionIndexCheck(log) {
 		}
 	};
 }
-const encoder$2 = new TextEncoder();
-/** Whether `bytes` (null: absent) hold exactly `text`. */
-function holdsText(bytes, text) {
-	if (bytes === null) return false;
-	const want = encoder$2.encode(text);
-	return bytes.byteLength === want.byteLength && bytes.every((x, i) => x === want[i]);
-}
-/** HEAD's copy of `path`; `null` when it is absent or HEAD is unborn. */
-async function headBytes(git, path) {
-	const head = await git.resolveCommit("HEAD");
-	return head === null ? null : (await refReader(git, head)).read(path);
-}
-/** HEAD's tree, or an empty tree on an unborn HEAD. */
-async function headTree(git, head) {
-	return head === null ? new MemoryTree({}) : refReader(git, head);
-}
-/**
-* Brings the work-tree copy of `path` to `text` (atomically, when it differs) and reports whether
-* the staged copy differs, so the caller stages it. `old` is the work-tree copy before the write
-* (`null` when absent), for rollback.
-*/
-async function writeIndexCopy(git, path, text) {
-	const old = await worktreeReader(git).read(path);
-	return {
-		wrote: !holdsText(old, text) && await writeIndexFile(git, path, text),
-		old,
-		stage: !holdsText(await (await indexReader(git)).read(path), text)
-	};
-}
-/** The first line of an error's message, for notes and headlines. */
-const firstLine = (err) => (err instanceof Error ? err.message : String(err)).split("\n")[0] ?? "";
 /**
 * `adr index` (design 2b §4.5) with what the text output needs; `indexDecisionLog` is the
 * library entry.
@@ -645,105 +663,115 @@ async function runDecisionIndex(log, o = {}) {
 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;
+// src/sources.ts
+/** The kinds adr reads from `[[sources]]`: only decision logs. */
+const DECISION_SOURCE_KINDS = ["adr"];
+const compiled$1 = compileKind(adrKind);
+/** Numbers recorded in a source's committed index, as a `Numbering`. */
+function indexNumbering(byId) {
+	if (byId === null) return NO_NUMBERING;
+	return {
+		available: true,
+		reason: "index",
+		ref: null,
+		commit: null,
+		byId,
+		byNumber: new Map([...byId].map(([id, n]) => [n, id]))
+	};
 }
-/**
-* `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) {
+/** The `[[sources]]` entries adr reads and the ones it skips, in config order. */
+function decisionSourceConfigs(log) {
+	const all = log.config?.sources ?? [];
+	const sources = sourcesOfKinds(all, DECISION_SOURCE_KINDS);
 	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
-			}));
-		}
+		sources,
+		skipped: all.filter((s) => !sources.includes(s))
 	};
 }
 /**
-* `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.
+* Reads the decision logs of the `kind = "adr"` `[[sources]]` entries (other kinds are never
+* fetched): from the local cache only with `fetch: "cache"` (the default), else fetched first
+* (`readSources`; a failed fetch throws `SourceFetchError`). A cached source's decisions are folded
+* with adr's kind and numbered from its committed `index.md` (the cache is a depth-1 clone, so
+* history numbering can't work), else shown by id.
 */
-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
-				});
+async function readDecisionSources(log, o = {}) {
+	const { sources } = decisionSourceConfigs(log);
+	const reads = await readSources(log.git, sources, { fetch: o.fetch ?? "cache" });
+	const logs = /* @__PURE__ */ new Map();
+	const notes = [];
+	for (const r of reads) {
+		if (r.source === null) {
+			logs.set(r.config.name, {
+				subjects: null,
+				commit: null
 			});
+			continue;
 		}
+		const ref = sourceLogRef(r.source, {
+			layout: adrKind.def.layout,
+			defaultRoot: adrKind.def.defaultRoot
+		});
+		const snapshot = await loadLog(ref.tree, {
+			kind: compiled$1,
+			layout: ref.layout
+		});
+		if (snapshot.subjects.size === 0) notes.push(`source ${r.config.name} has no decision log at ${ref.layout.root} in ${r.source.commit.slice(0, 12)}`);
+		const numbering = indexNumbering(await readIndexNumbers(ref.tree, `${ref.layout.root}/index.md`));
+		const projected = projectLog(adrKind, foldLog(adrKind, snapshot), { numbering }).views;
+		logs.set(r.config.name, {
+			commit: r.source.commit,
+			subjects: new Map([...projected].map(([id, v]) => [id, {
+				status: v.status,
+				display: v.display,
+				title: v.title
+			}]))
+		});
+	}
+	return {
+		logs,
+		statuses: reads.map((r) => r.status),
+		notes
 	};
 }
+const SOURCE_NAME$1 = /^[a-z][a-z0-9-]{0,31}$/;
 /**
-* 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`.
+* The cached decision log of the `[[sources]]` entry `name`, as a `DecisionsRead` for `adr list
+* --source` and `adr search --source` (cache only, never the network). An uncached source reads as
+* an empty log with the note `<name> not fetched; run adr sources fetch`. Throws `UsageError` for a
+* name that isn't configured or whose kind adr doesn't read.
 */
-function adrChecks(log, historyRef) {
-	return [
-		...foldChecks(adrKind, {
-			options: { acceptRequiresHuman: log.adr.acceptRequiresHuman },
-			templates: gitTemplates(log.git, { historyRef })
-		}),
-		scopeGlobCheck(),
-		anchorCheck({
-			keyword: log.adr.anchorKeyword,
-			exclude: log.adr.anchorExclude
-		}),
-		governedByInactive(log),
-		scopeNarrowed(log),
-		...log.adr.index === "committed" ? [decisionIndexCheck(log)] : []
-	];
-}
-/** Verifies the decision log in `mode` (staged, range or full) with `adrChecks`. */
-async function verifyDecisions(log, mode) {
-	return verifyLog({
-		git: log.git,
-		kind: adrKind,
-		layout: log.layout,
-		mode,
-		checks: adrChecks(log, await templateHistoryRef(log.git, mode))
+async function readSourceDecisions(log, name) {
+	if (!SOURCE_NAME$1.test(name)) throw new UsageError(`--source must match ${SOURCE_NAME$1.source}: ${name}`);
+	const { sources, skipped } = decisionSourceConfigs(log);
+	const other = skipped.find((s) => s.name === name);
+	if (other !== void 0) throw new UsageError(`source ${name} has kind ${other.kind}, which adr doesn't read`);
+	const config = sources.find((s) => s.name === name);
+	if (config === void 0) {
+		const known = [...sources, ...skipped].map((s) => s.name);
+		throw new UsageError(known.length === 0 ? `unknown source ${name}; there are no sources` : `unknown source ${name}; the sources are ${known.join(", ")}`);
+	}
+	const [r] = await readSources(log.git, [config], { fetch: "cache" });
+	const base = {
+		adr: log.adr,
+		notes: [...log.notes],
+		source: name
+	};
+	if (r?.source === void 0 || r.source === null) return readDecisionsFrom(new MemoryTree({}), {
+		...base,
+		layout: adrKind.layoutAt(config.root ?? adrKind.def.defaultRoot),
+		numbering: NO_NUMBERING,
+		notes: [...base.notes, `${name} not fetched; run adr sources fetch`]
+	});
+	const ref = sourceLogRef(r.source, {
+		layout: adrKind.def.layout,
+		defaultRoot: adrKind.def.defaultRoot
+	});
+	return readDecisionsFrom(ref.tree, {
+		...base,
+		layout: ref.layout,
+		numbering: indexNumbering(await readIndexNumbers(ref.tree, `${ref.layout.root}/index.md`)),
+		commit: r.source.commit
 	});
 }
 /** The built-in templates by name: the file text `adr new` materializes. */
@@ -855,8 +883,8 @@ sections:
 `
 });
 // src/write.ts
-const encoder$1 = new TextEncoder();
-const decoder$1 = new TextDecoder();
+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;
@@ -867,7 +895,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$1.encode(text).byteLength;
+	const size = encoder.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) {
@@ -947,14 +975,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 {
@@ -963,7 +995,7 @@ async function precheck(read, files) {
 	};
 }
 function filesOf(events, read) {
-	return Object.fromEntries(events.map((e) => [eventPath(read.layout, e), encoder$1.encode(serializeEvent(e))]));
+	return Object.fromEntries(events.map((e) => [eventPath(read.layout, e), encoder.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. */
@@ -973,7 +1005,7 @@ async function chooseTemplate(read, name, c) {
 	const bytes = await read.tree.read(path);
 	let text;
 	let materialize = null;
-	if (bytes !== null) text = decoder$1.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) {
@@ -1060,9 +1092,9 @@ async function planPropose(read, input, c, o = {}) {
 		},
 		actor: input.actor
 	});
-	const body = encoder$1.encode(rendered.text);
+	const body = encoder.encode(rendered.text);
 	const files = { [bodyPath]: body };
-	if (chosen.materialize !== null) files[chosen.path] = encoder$1.encode(chosen.materialize);
+	if (chosen.materialize !== null) files[chosen.path] = encoder.encode(chosen.materialize);
 	Object.assign(files, filesOf([event], read));
 	const { after, added } = await precheck(read, files);
 	if (added.length > 0) return {
@@ -1140,6 +1172,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);
@@ -1210,9 +1362,12 @@ async function planAccept(read, input, c, o = {}) {
 	const involved = sorted([id, ...targets]);
 	const { scope, eventDirs } = commitScope(read, involved);
 	const bodyPath = view.body_path ?? "";
+	const globs = copied === null ? view.applies_to : copied.data.set;
+	const unmatched = o.tracked === void 0 ? [] : unmatchedGlobs(globs, o.tracked);
 	return {
 		ok: true,
 		plan: {
+			...unmatched.length === 0 ? {} : { notes: unmatched.map((g) => `${g} matches no tracked file; from this commit verify reports scope/glob-unmatched until a file matches, so commit the files with it or change the scope`) },
 			command: "accept",
 			subject: id,
 			files,
@@ -1440,8 +1595,9 @@ const LINK_RELS = [
 const SOURCE_NAME = /^[a-z][a-z0-9-]{0,31}$/;
 /**
 * Plans `adr link` (design §6.7): `linked` in every state. A qualified target must name one of
-* `o.sources` (the log's `[[sources]]` names); it isn't looked up in the other log. A link that
-* already exists plans nothing, with a note.
+* `o.sources` (the log's `[[sources]]` names) of kind `adr` (`o.logs`, from the local cache): a
+* cached source must hold the id, else `UsageError`; into an uncached one the link is written with
+* a note that it isn't checked. A link that already exists plans nothing, with a note.
 */
 async function planLink(read, input, c, o = {}) {
 	const rel = input.rel ?? "relates-to";
@@ -1453,12 +1609,19 @@ async function planLink(read, input, c, o = {}) {
 	let shown;
 	let described;
 	let named;
+	let foreignNote = null;
 	const at = target.indexOf(":");
 	if (at >= 0) {
 		const source = target.slice(0, at);
 		const local = target.slice(at + 1);
 		if (!SOURCE_NAME.test(source) || !isSubjectId(local)) throw new UsageError(`invalid decision ${JSON.stringify(input.to)}`);
 		if (!(o.sources ?? []).includes(source)) throw new UsageError(`unknown source ${source}; add a [[sources]] entry named ${source}`);
+		const kind = o.kinds?.get(source);
+		if (kind !== void 0 && kind !== "adr") throw new UsageError(`source ${source} has kind ${kind}, which adr doesn't read`);
+		const cached = o.logs?.get(source);
+		if (cached?.subjects !== null && cached?.subjects !== void 0) {
+			if (!cached.subjects.has(local)) throw new UsageError(`${target} is not in source ${source} (pinned at ${(cached.commit ?? "").slice(0, 12)})`);
+		} else if (o.logs !== void 0) foreignNote = `${source} not fetched; the reference isn't checked`;
 		to = target;
 		shown = target;
 		described = `${rel} ${target}.`;
@@ -1509,7 +1672,8 @@ async function planLink(read, input, c, o = {}) {
 				...r.plan.commit,
 				title: named,
 				body: [described]
-			}
+			},
+			notes: [...r.plan.notes ?? [], ...foreignNote === null ? [] : [foreignNote]]
 		}
 	};
 }
@@ -1568,7 +1732,7 @@ async function planScope(read, input, c, o = {}) {
 		}
 	};
 	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" : "";
+		const checked = (adrKind.def.scope?.requireMatchIn ?? []).includes(view.status) ? "; verify (hooks and CI) reports scope/glob-unmatched until a file matches" : view.status === "proposed" ? `; verify reports scope/glob-unmatched once ${view.display} is accepted, 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");
@@ -1736,13 +1900,6 @@ const isYaml = (path) => /\.ya?ml$/.test(path);
 */
 const WRITE_RERUN = "Don't run the command again: the log already holds the change, so a rerun would be refused, do nothing, or write it a second time.";
 /**
-* Applies a plan (§5.4): refuses a commit whose scope has unstaged or needed untracked paths,
-* writes the files (removing them again if a write fails), stages them, runs `afterStage`, and
-* commits `plan.stage` plus the involved subjects' already-staged files with exact trailers. A
-* failed `git commit` throws `CommitFailedError` with the manual command (design 2b D5) and the
-* notes made so far.
-*/
-/**
 * A write leaves the work tree's render of `index.md` (`staged`) staged, and it lists decision
 * files that may not be staged. When some aren't and the index's own render differs, the next
 * plain commit's hook fails; the note says so, as its `index/stale` finding does. `null`
@@ -1755,9 +1912,17 @@ async function unstagedIndexNote(log, at, staged, history, render) {
 	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. 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;
-	if (o.commit && o.message === void 0) throw new InvalidArgumentError("applyPlan needs a message to commit");
+	if (o.commit && o.message === void 0 && o.compose === void 0) throw new InvalidArgumentError("applyPlan needs a message to commit");
+	if (o.message !== void 0 && o.compose !== void 0) throw new InvalidArgumentError("applyPlan takes a message or compose, not both");
 	const stage = new Set(plan.stage);
 	if (o.commit) {
 		const unstaged = new Set(await git.unstagedPaths(plan.commitScope));
@@ -1776,7 +1941,7 @@ async function applyPlan(log, plan, o) {
 		const files = {};
 		const gone = /* @__PURE__ */ new Set();
 		for (const p of sorted([...plan.stage, ...extra])) {
-			const bytes = plan.files[p] ?? await work.read(p);
+			const bytes = plan.files[p] ?? plan.replace?.[p]?.bytes ?? await work.read(p);
 			if (bytes === null) gone.add(p);
 			else files[p] = bytes;
 		}
@@ -1785,7 +1950,10 @@ async function applyPlan(log, plan, o) {
 	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);
+		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`);
 	}
@@ -1815,7 +1983,12 @@ async function applyPlan(log, plan, o) {
 	};
 	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 });
@@ -1833,6 +2006,10 @@ async function applyPlan(log, plan, o) {
 			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, ...toStage]);
@@ -1850,16 +2027,24 @@ async function applyPlan(log, plan, o) {
 	}
 	const stale = (err) => `${at} may be stale: ${firstLine(err)}; run adr index`;
 	let sha = null;
+	let rendered = null;
 	if (commit) {
 		const extra = await extraOf();
-		const staged = extra.filter(isYaml).flatMap((p) => {
-			const c = classifyPath(log.layout, p);
-			const name = c.area === "event" && !c.file.includes("/") ? parseEventFileName(c.file) : null;
-			return c.area === "event" && c.subject !== null && name !== null ? [["ADR", c.subject], ["ADR-Event", name.type]] : [];
+		const extraRefs = stagedEventRefs(log.layout, extra);
+		const planRefs = plan.events.map((e) => ({
+			subject: e.subject,
+			type: e.type
+		}));
+		rendered = o.compose === void 0 ? null : o.compose({
+			plan: planRefs,
+			extra: extraRefs,
+			tree: await commitTree(extra)
 		});
-		const message = o.message ?? "";
+		const message = rendered?.message ?? o.message ?? "";
 		const mergeTrailers = o.mergeTrailers === true;
-		const trailers = [...staged, ...plan.trailers];
+		const pairs = eventTrailers([...extraRefs, ...planRefs], TRAILER_KEYS);
+		const named = new Set(pairs.filter(([k]) => k === "ADR").map(([, v]) => v));
+		const trailers = [...pairs, ...plan.events.length === 0 ? plan.trailers.filter(([k, v]) => k !== "ADR" || !named.has(v)) : []];
 		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);
@@ -1931,23 +2116,47 @@ async function applyPlan(log, plan, o) {
 		if (note !== null) notes.push(note);
 	}
 	return {
-		written: [...Object.keys(plan.files), ...indexWritten ? [at] : []],
+		written: [
+			...Object.keys(plan.replace ?? {}),
+			...Object.keys(plan.files),
+			...indexWritten ? [at] : []
+		],
 		commit: sha,
 		findings,
-		notes
+		notes,
+		rendered
 	};
 }
-/** `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)))
-	};
+/** The `ADR`/`ADR-Event` trailer keys. */
+const TRAILER_KEYS = {
+	subject: "ADR",
+	event: "ADR-Event"
+};
+/**
+* The staged event files among `paths` as (decision, type) refs, in path order (by decision,
+* then event time), deduplicated by decision and type.
+*/
+function stagedEventRefs(layout, paths) {
+	const found = [];
+	for (const p of sorted(paths.filter(isYaml))) {
+		const c = classifyPath(layout, p);
+		if (c.area !== "event" || c.subject === null || c.file.includes("/")) continue;
+		const name = parseEventFileName(c.file);
+		if (name !== null) found.push({
+			subject: c.subject,
+			type: name.type
+		});
+	}
+	const seen = /* @__PURE__ */ new Set();
+	return found.filter((r) => {
+		const key = `${r.subject}\0${r.type}`;
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
 }
+/** The new bytes of each file a plan replaces. */
+const replaceBytes = (plan) => Object.fromEntries(Object.entries(plan.replace ?? {}).map(([p, r]) => [p, r.bytes]));
 const DEFAULT_DEPS = {
 	now: Date.now,
 	apply: applyPlan
@@ -1973,7 +2182,6 @@ async function viewsAfter(log, plan, sha) {
 		affected: plan.affected.map(view)
 	};
 }
-const SHORTENED_NOTE = "commit subject shortened to 72 characters; the full title is in the commit body";
 /**
 * `--commit` needs an author and a committer identity; checked before anything is written, since
 * `GIT_AUTHOR_*` alone satisfies the author while `git commit` still fails on the committer.
@@ -1981,24 +2189,63 @@ const SHORTENED_NOTE = "commit subject shortened to 72 characters; the full titl
 async function checkCommitIdentity(log) {
 	if (await log.git.identity() === null || await log.git.committerIdentity() === null) throw new ConfigError("--commit needs a git identity; set git user.name and user.email");
 }
-/** The plan's commit message from `[commit] subject` (design §4), and whether it was shortened. */
-function commitMessage(log, command, plan) {
+const STATUS_TYPES = /* @__PURE__ */ new Set([
+	"proposed",
+	"accepted",
+	"rejected",
+	"withdrawn"
+]);
+/**
+* The commit's action and title slot (ADR-0008, ?6), chosen once the staged events the commit
+* sweeps in are known: when `plan` or `extra` holds a status event (proposed, accepted, rejected,
+* withdrawn), the title form of the last one, since that is what the commit decides. Otherwise
+* the plan's own subject when the extra events add no other verb; with two or three verbs those
+* joined (`link and scope ADR-0003`), and beyond three (or where the joined verbs don't fit a
+* custom template) `update ADR-0003`. Every single-action subject stays the plan's own, byte for
+* byte.
+*/
+function composeSubject(read, parts, c) {
+	const status = [...c.extra, ...c.plan].filter((e) => STATUS_TYPES.has(e.type)).at(-1);
+	if (status !== void 0) {
+		if (c.plan.some((e) => e.subject === status.subject && e.type === status.type)) return {
+			action: parts.action,
+			title: parts.title
+		};
+		return {
+			action: ACTIONS[status.type].action,
+			title: read.projection.views.get(status.subject)?.title ?? status.subject
+		};
+	}
+	const primary = c.plan[0]?.type;
+	const verbs = /* @__PURE__ */ new Set();
+	for (const t of [primary, ...c.extra.map((e) => e.type)]) if (t !== void 0 && Object.hasOwn(BATCH_ACTIONS, t)) verbs.add(t);
+	if (verbs.size <= 1 || primary === void 0 || !verbs.has(primary)) return {
+		action: parts.action,
+		title: parts.title
+	};
+	const ordered = BATCH_ORDER.filter((t) => verbs.has(t)).map((t) => BATCH_ACTIONS[t]);
+	return {
+		action: ordered.length > 3 ? UPDATE_ACTION : joinActions(ordered),
+		title: parts.display
+	};
+}
+/** The plan's commit message from `[commit] subject` (design §4), with `composeSubject`'s slot. */
+function commitMessage(log, command, read, plan, c) {
 	const parts = plan.commit;
 	if (parts === null) throw new InvalidArgumentError("this write can't be committed");
-	const r = renderCommitMessage(log.adr.commitSubject, {
-		title: parts.title,
+	const { action, title } = composeSubject(read, parts, c);
+	const render = (a) => renderCommitMessage(log.adr.commitSubject, {
+		title,
 		vars: {
-			action: parts.action,
+			action: a,
 			id: parts.id,
 			display: parts.display,
 			command
 		},
 		body: parts.body
 	});
-	return {
-		message: r.message,
-		shortened: r.shortened
-	};
+	const r = render(action);
+	return r.shortened && title === parts.display && action !== parts.action ? render(UPDATE_ACTION) : r;
 }
 /**
 * Plan, then apply, with the single `EventExistsError` retry (§5.4 steps 1–5). `o.message`
@@ -2032,7 +2279,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,
@@ -2043,15 +2290,15 @@ async function write(log, command, plan, o, deps, afterStage) {
 			findings: r.plan.findings,
 			notes: [...notes, ...r.plan.notes ?? []]
 		};
-		const rendered = commit ? commitMessage(log, command, r.plan) : null;
+		if (commit && r.plan.commit === null) throw new InvalidArgumentError("this write can't be committed");
 		const given = o.message ?? null;
 		try {
 			const applied = await deps.apply(log, r.plan, {
 				commit,
-				...rendered === null ? {} : {
-					message: given ?? rendered.message,
-					mergeTrailers: given !== null
-				},
+				...!commit ? {} : given !== null ? {
+					message: given,
+					mergeTrailers: true
+				} : { compose: (c) => commitMessage(log, command, read, r.plan, c) },
 				...afterStage === void 0 ? {} : { afterStage: afterStage(r.plan, commit) },
 				...log.adr.index === "committed" && o.index !== "skip" ? { index: (tree, history) => renderDecisionIndex(log.git, {
 					layout: log.layout,
@@ -2064,7 +2311,7 @@ async function write(log, command, plan, o, deps, afterStage) {
 			const own = [
 				...r.plan.notes ?? [],
 				...applied.notes,
-				...applied.commit !== null && given === null && rendered?.shortened === true ? [SHORTENED_NOTE] : []
+				...applied.commit !== null && applied.rendered?.note != null ? [applied.rendered.note] : []
 			];
 			return {
 				format: "adr-write/v1",
@@ -2128,7 +2375,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$1.decode(bytes ?? d.rendered);
+		const text = decoder$2.decode(bytes ?? d.rendered);
 		const findings = lintDocument(d.template, text, {
 			file: d.path,
 			subject: plan.subject
@@ -2167,14 +2414,18 @@ async function proposeDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
 async function acceptDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
 	const copyScope = o.copyScope ?? "suggest";
 	let copy = null;
+	const tracked = await trackedFiles(log);
 	return write(log, "accept", async (read, c) => {
-		const plain = await planAccept(read, input, c);
+		const plain = await planAccept(read, input, c, { tracked });
 		if (!plain.ok) return plain;
 		const id = plain.plan.subject;
 		const offer = scopeToCopy(read, id);
 		if (offer.globs.length === 0) return plain;
 		if (copy === null) copy = typeof copyScope === "function" ? await copyScope(offer) : copyScope === "copy";
-		if (copy) return planAccept(read, input, c, { copyGlobs: offer.globs });
+		if (copy) return planAccept(read, input, c, {
+			copyGlobs: offer.globs,
+			tracked
+		});
 		if (copyScope === "skip") return plain;
 		const notes = [...plain.plan.notes ?? [], copyScopeNote(id, offer)];
 		return {
@@ -2217,8 +2468,15 @@ async function noteDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
 * Qualified targets name the log's `[[sources]]`; a link that exists already writes nothing.
 */
 async function linkDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
-	const sources = (log.config?.sources ?? []).map((s) => s.name);
-	return write(log, "link", (read, c) => planLink(read, input, c, { sources }), o, deps);
+	const configs = log.config?.sources ?? [];
+	const sources = configs.map((s) => s.name);
+	const kinds = new Map(configs.map((s) => [s.name, s.kind]));
+	const logs = input.to.includes(":") ? (await readDecisionSources(log, { fetch: "cache" })).logs : void 0;
+	return write(log, "link", (read, c) => planLink(read, input, c, {
+		sources,
+		kinds,
+		...logs === void 0 ? {} : { logs }
+	}), o, deps);
 }
 /**
 * `adr scope <id> --set|--add|--remove …`: writes one `scoped` event with the new set, stages it,
@@ -2228,6 +2486,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
@@ -2261,357 +2532,6 @@ async function followScopeRenames(log, input, o = {}, deps = DEFAULT_DEPS) {
 		notes: [...doc.notes, FOLLOW_NO_COMMIT_NOTE]
 	} : doc;
 }
-// src/hooks.ts
-/** The hooks adr registers, in the order the text output lists them. */
-const HOOKS = [
-	"pre-commit",
-	"commit-msg",
-	"pre-push",
-	"post-merge"
-];
-/**
-* adr's command per hook (design 2b D4), after `adr`. `--root <root>` comes first only when the
-* root can't be found without it: no `<repo>/adr.toml` names it and it isn't `docs/adr`. So the
-* hooks see the same config as a plain `adr` run, and never print the root-override note.
-*/
-function decisionHookCommands(log) {
-	const r = log.configPath === "adr.toml" || log.layout.root === adrKind.def.defaultRoot ? [] : ["--root", log.layout.root];
-	return {
-		"pre-commit": [
-			...r,
-			"hooks",
-			"run",
-			"pre-commit"
-		],
-		"commit-msg": [
-			...r,
-			"hooks",
-			"trailers",
-			"{args}"
-		],
-		"pre-push": [
-			...r,
-			"verify",
-			"--base",
-			"@{upstream}",
-			"--ref",
-			"HEAD"
-		],
-		"post-merge": [
-			...r,
-			"list",
-			"--since",
-			"ORIG_HEAD"
-		]
-	};
-}
-function registrations(log) {
-	const commands = decisionHookCommands(log);
-	return HOOKS.flatMap((hook) => {
-		const argv = commands[hook];
-		return argv === void 0 ? [] : [{
-			hook,
-			argv
-		}];
-	});
-}
-/** A shim path as the user sees it: repo-relative, with `/`. */
-function shown(git, path) {
-	return relative(git.root ?? git.gitDir, path).split(sep).join("/");
-}
-/** The shims in hook order: `HOOKS`' order, as the text output lists them. */
-function inHookOrder(git, paths) {
-	const rank = (p) => HOOKS.findIndex((h) => p.endsWith(`/${h}`));
-	return paths.map((p) => shown(git, p)).sort((a, b) => rank(a) - rank(b));
-}
-function result(log, action, r, extra = {}) {
-	return {
-		format: "adr-hooks/v1",
-		action,
-		written: r === null ? [] : inHookOrder(log.git, r.written),
-		unchanged: r === null ? [] : inHookOrder(log.git, r.unchanged),
-		registrations: registrations(log),
-		snippet: extra.snippet ?? null,
-		trailers: extra.trailers ?? []
-	};
-}
-/**
-* Registers adr's four commands in ledger's shims, one per hook and shared with other ark tools
-* (design 2b D4). With `core.hooksPath` set or a foreign hook file present, it writes the rest and
-* then throws `HookConflictError` (exit 2), naming each conflict and the `print` command.
-*/
-async function installDecisionHooks(log) {
-	const r = await installHooks(log.git, {
-		tool: "adr",
-		commands: decisionHookCommands(log)
-	});
-	assertNoHookConflicts(r, { tool: "adr" });
-	return result(log, "install", r);
-}
-/** Removes adr from every shim; a shim left with no tool is deleted. */
-async function uninstallDecisionHooks(log) {
-	return result(log, "uninstall", await uninstallHooks(log.git, { tool: "adr" }));
-}
-/** The config to paste into a hook manager instead of installing shims. */
-function printDecisionHooks(log, manager) {
-	const regs = registrations(log).map((r) => ({
-		tool: "adr",
-		...r
-	}));
-	return result(log, "print", null, { snippet: hookSnippet(manager, regs) });
-}
-/** The `ADR-Event` trailer key as git compares keys: case-insensitively. */
-const ADR_EVENT = /^adr-event[ \t]*:/im;
-/**
-* The `commit-msg` step (P1 §7.1): appends one `ADR`/`ADR-Event` pair per staged added event file
-* of the log, by path, keeping repeats (`ifExists: "add"`). It does nothing for a message that
-* already has an `ADR-Event:` trailer (an `adr … --commit` message), or during a merge, whose
-* events came with their own commits' trailers. Throws `UsageError` when the file is missing.
-*/
-async function addHookTrailers(log, messageFile) {
-	const { git, layout } = log;
-	const file = resolve(git.root ?? git.gitDir, messageFile);
-	try {
-		await access(file, constants.R_OK | constants.W_OK);
-	} catch {
-		throw new UsageError(`no commit message file at ${messageFile}`);
-	}
-	const parsed = await git.run([
-		"interpret-trailers",
-		"--parse",
-		"--",
-		file
-	]);
-	if (ADR_EVENT.test(Buffer.from(parsed.stdout).toString("utf8"))) return result(log, "trailers", null);
-	if (await git.resolveCommit("MERGE_HEAD") !== null) return result(log, "trailers", null);
-	const trailers = (await git.stagedPaths([`${layout.root}/${layout.events}`], { addedOnly: true })).flatMap((p) => {
-		const c = classifyPath(layout, p);
-		const name = c.area === "event" && !c.file.includes("/") ? parseEventFileName(c.file) : null;
-		return c.area === "event" && c.subject !== null && name !== null ? [["ADR", c.subject], ["ADR-Event", name.type]] : [];
-	});
-	await git.appendTrailers(file, trailers, { ifExists: "add" });
-	return result(log, "trailers", null, { trailers });
-}
-/**
-* Whether the hook may stage: only into the commit's real index (design 2b D8). `git commit
-* <paths>` and `--only`, adr's own `--commit` included, run hooks on a temporary index, and
-* staging there leaves the user's index showing the file as deleted.
-*/
-function stagingSafe(git, env) {
-	const file = env.GIT_INDEX_FILE;
-	if (file === void 0 || file === "") return true;
-	const at = resolve(git.root ?? git.gitDir, file);
-	return at === resolve(git.gitDir, "index") || at === resolve(git.gitDir, "index.lock");
-}
-/** `ADR-0003, ADR-0004` for the decisions a rename following changes. */
-const displays = (views) => views.map((v) => v.display).join(", ");
-/**
-* `adr hooks run pre-commit` (design 2b D8): rename following, then the index, then `verify
-* --staged`, stopping at the first step that fails. `worktree` must be opened with the work-tree
-* reader, because rename following writes through `write()`; `index` with the index reader, for
-* the config as staged, the index render and verify. Only the index step stages `index.md`, and
-* only with `[hooks] index = "stage"`; rename following passes `index: "skip"`. Neither stages
-* into a temporary index (`stagingSafe`). A step that can't run throws (exit 2).
-*/
-async function runPreCommitHook(o) {
-	const { worktree, index, env } = o;
-	const config = index.adr;
-	const failOn = config.failOn;
-	const notes = [...index.notes];
-	const done = (exit, findings) => ({
-		exit,
-		findings,
-		notes: [...new Set(notes)],
-		failOn
-	});
-	const safe = stagingSafe(index.git, env);
-	if (config.scopeFollowRenames !== "off" && (await stagedRenames(worktree.git)).length > 0) {
-		const { actor, notes: attribution } = await resolveAttribution(worktree.git, { env });
-		if (config.scopeFollowRenames === "warn") {
-			const dry = await followScopeRenames(worktree, { actor }, { dryRun: true });
-			for (const v of dry.affected) notes.push(`${v.display}'s globs don't follow the renames in this commit (scope_follow_renames = "warn"); run adr scope --follow-renames`);
-		} else if (safe) {
-			const doc = await followScopeRenames(worktree, { actor }, {
-				index: "skip",
-				notes: attribution
-			});
-			notes.push(...doc.notes);
-			if (!doc.ok) return done(1, doc.findings);
-		} else {
-			const dry = await followScopeRenames(worktree, { actor }, { dryRun: true });
-			if (dry.affected.length > 0) {
-				notes.push(`the renames in this commit change the scope of ${displays(dry.affected)}; git commit <paths> can't take the scoped events. Run adr scope --follow-renames, then commit again including the files it lists, or set [hooks] scope_follow_renames = "warn"`);
-				return done(1, []);
-			}
-		}
-	}
-	if (config.index === "committed" && config.hookIndex === "stage" && safe) {
-		const path = indexPath(index.layout);
-		const text = await renderDecisionIndex(index.git, {
-			layout: index.layout,
-			adr: config,
-			tree: index.tree,
-			history: await index.git.resolveCommit("HEAD")
-		});
-		if (text !== null && !holdsText(await index.tree.read(path), text)) {
-			await writeIndexFile(index.git, path, text);
-			await index.git.add([path]);
-			notes.push(`regenerated and staged ${path}`);
-		}
-	}
-	const findings = await verifyDecisions(index, { type: "staged" });
-	return done(exitCode(findings, { failOn }), findings);
-}
-// src/init.ts
-/**
-* What the recovery hint says about rerunning `adr init` after `git commit` failed (design 2b D5):
-* init keeps existing files, so it would commit nothing.
-*/
-const INIT_RERUN = "Running adr init again won't commit them: the files exist now, so it keeps them and commits nothing.";
-const CONFIG = "adr.toml";
-const DEFAULT_ROOT = adrKind.def.defaultRoot;
-const encoder = new TextEncoder();
-/** The starter config; `root` only for a repo-level file naming a log elsewhere. */
-function configText(o) {
-	return [
-		"# adr configuration. Every key is optional: https://github.com/nikovirtala/ark/tree/main/packages/adr#config-adrtoml",
-		"[log]",
-		...o.root === null ? [] : [`root = ${JSON.stringify(o.root)}`],
-		`default_template = ${JSON.stringify(o.template)}`,
-		"",
-		"[commit]",
-		"# subject = \"docs(adr): {action} {title}\"",
-		""
-	].join("\n");
-}
-/**
-* `adr init` (design §6.2): writes a config for the log, unless one is found, and each built-in
-* template in `o.templates` (default `nygard`) to `<root>/templates/`, never overwriting a file.
-* A `--root` other than `docs/adr` gets a repo-level `adr.toml` naming it, so later commands find
-* the log without `--root`; when that file exists for another log, the config goes in the root.
-* With `[log] index = "committed"` it also writes `<root>/index.md` unless one exists. With
-* `commit` (default `[policy] auto_commit`) the written files are committed on their own;
-* nothing written means nothing committed. No events are written.
-*/
-async function initDecisionLog(log, o = {}) {
-	if (log.ref !== null || log.tree.label !== "worktree") throw new InvalidArgumentError("init writes the work tree; open the log without a ref");
-	const known = Object.keys(BUILTIN_TEMPLATES);
-	const templates = [...new Set(o.templates === void 0 ? ["nygard"] : o.templates)];
-	for (const name of templates) if (!known.includes(name)) throw new UsageError(`unknown built-in template ${name}; use nygard, madr or y-statement`);
-	const root = log.layout.root;
-	const notes = [...log.notes];
-	const files = [];
-	const kept = [];
-	let config = log.configPath;
-	if (config !== null) kept.push(config);
-	else {
-		const template = templates[0] ?? "nygard";
-		const repo = await readToolConfig(log.tree, CONFIG);
-		if (root === DEFAULT_ROOT) {
-			config = `${root}/${CONFIG}`;
-			files.push([config, configText({
-				root: null,
-				template
-			})]);
-		} else if (repo === null) {
-			config = CONFIG;
-			files.push([config, configText({
-				root,
-				template
-			})]);
-		} else {
-			const section = repo.raw.log;
-			const other = typeof section?.root === "string" ? section.root : DEFAULT_ROOT;
-			config = `${root}/${CONFIG}`;
-			files.push([config, configText({
-				root: null,
-				template
-			})]);
-			notes.push(`${CONFIG} names ${other}; pass --root ${root} to use this log`);
-		}
-	}
-	for (const name of templates) {
-		const path = `${root}/templates/${name}.md`;
-		if (await log.tree.read(path) !== null) kept.push(path);
-		else files.push([path, BUILTIN_TEMPLATES[name] ?? ""]);
-	}
-	const commitRequested = o.commit ?? log.adr.autoCommit;
-	const at = indexPath(log.layout);
-	let indexed = false;
-	if (log.adr.index === "committed") {
-		if (await log.tree.read(at) !== null) kept.push(at);
-		else {
-			const head = await log.git.resolveCommit("HEAD");
-			const added = Object.fromEntries(files.map(([p, t]) => [p, encoder.encode(t)]));
-			const base = commitRequested ? await headTree(log.git, head) : log.tree;
-			const text = await renderDecisionIndex(log.git, {
-				layout: log.layout,
-				adr: log.adr,
-				tree: overlayTree(base, added),
-				history: head
-			});
-			if (text === null) notes.push(`${at} not updated: numbers need history in this shallow clone; run git fetch --unshallow, then adr index`);
-			else {
-				files.push([at, text]);
-				indexed = true;
-			}
-		}
-	}
-	const commit = files.length > 0 && commitRequested;
-	if (commit && (await log.git.identity() === null || await log.git.committerIdentity() === null)) throw new ConfigError("--commit needs a git identity; set git user.name and user.email");
-	const written = [];
-	try {
-		for (const [path, text] of files) {
-			await writeNewFile(log.git, path, encoder.encode(text));
-			written.push(path);
-		}
-	} catch (err) {
-		const top = log.git.root ?? "";
-		for (const path of written) await rm(join(top, path), { force: true });
-		throw err;
-	}
-	if (written.length > 0) await log.git.add(written);
-	let sha = null;
-	if (commit) {
-		const message = o.message ?? renderCommitMessage(log.adr.commitSubject, {
-			title: "the decision log",
-			vars: {
-				action: "set up",
-				id: "",
-				display: "",
-				command: "init"
-			}
-		}).message;
-		sha = await commitWithRecovery(log.git, {
-			message,
-			only: written,
-			rerun: INIT_RERUN,
-			after: indexed ? INDEX_AFTER(root) : null
-		});
-		if (indexed) try {
-			const again = await renderDecisionIndex(log.git, {
-				layout: log.layout,
-				adr: log.adr,
-				tree: worktreeReader(log.git),
-				history: sha
-			});
-			if (again !== null) {
-				if ((await writeIndexCopy(log.git, at, again)).stage) await log.git.add([at]);
-			}
-		} catch (err) {
-			notes.push(`${at} may be stale: ${firstLine(err)}; run adr index`);
-		}
-	}
-	return {
-		format: "adr-init/v1",
-		root,
-		config,
-		written,
-		kept,
-		commit: sha,
-		notes
-	};
-}
 // src/views.ts
 /** The `numbering` key of `adr-list/v1`, `adr-show/v1` and `adr-for/v1`. */
 const numberingJson = (read) => ({
@@ -2642,6 +2562,7 @@ function listDecisions(read, o = {}) {
 	const listed = new Set(decisions.map((v) => v.id));
 	return {
 		format: "adr-list/v1",
+		source: read.source,
 		root: read.root,
 		ref: read.ref,
 		commit: read.commit,
@@ -2651,10 +2572,10 @@ function listDecisions(read, o = {}) {
 		unreadable: read.projection.unreadable,
 		unfoldable: read.projection.unfoldable,
 		findings: read.findings.filter((f) => f.subject === null || listed.has(f.subject)),
-		notes: read.notes
+		notes: listingNotes(read)
 	};
 }
-const decoder = new TextDecoder();
+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.
@@ -2686,7 +2607,7 @@ async function showDecision(read, id, o = {}) {
 		numbering: numberingJson(read),
 		header: stateHeader(view, read),
 		decision: view,
-		body: body === null ? null : decoder.decode(body.bytes),
+		body: body === null ? null : decoder$1.decode(body.bytes),
 		events,
 		findings: read.findings.filter((f) => f.subject === id),
 		notes: read.notes
@@ -2744,6 +2665,7 @@ const GLOBS_APPLY = /* @__PURE__ */ new Set([
 	"deprecated",
 	"superseded"
 ]);
+/** The order `adr for` and `adr search` list statuses in: in force first. */
 const STATUS_ORDER = [
 	"accepted",
 	"proposed",
@@ -2865,9 +2787,181 @@ async function decisionsFor(read, log, o) {
 		numbering: numberingJson(read),
 		paths: out,
 		findings: read.findings.filter((f) => f.subject === null || listed.has(f.subject)),
-		notes: read.notes
+		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",
+		source: read.source,
+		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 { 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 };
+export { numberDecisions as A, INDEX_AFTER as C, renderDecisionIndex as D, indexPath as E, resolveDecision as F, sourcesNote as I, DEFAULT_ADR_CONFIG as L, openDecisionLog as M, readDecisions as N, runDecisionIndex as O, readDecisionsFrom as P, parseAdrConfig as R, DECISION_INDEX as S, indexDecisionLog as T, withdrawDecision as _, stateHeader as a, readDecisionSources as b, followScopeRenames as c, proposeDecision as d, rejectDecision as f, updateDraft as g, supersedeDecision as h, showDecision as i, numberingNote as j, changedSince 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, decisionIndexCheck as w, readSourceDecisions as x, decisionSourceConfigs as y };
 
-//# sourceMappingURL=scope-CLqH-q1y.js.map
+//# sourceMappingURL=search-CTspg2pd.js.map