@nikovirtala/adr 0.0.0 → 0.2.0

package/dist/write-9IaqHRrY.js

@@ -0,0 +1,1986 @@
+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
+/** adr's commit-subject placeholders, each with its longest value (design §4.2). */
+const COMMIT_VARS = Object.freeze({
+	action: 24,
+	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.
+*/
+const COMMIT_NAMES = Object.freeze([{
+	length: COMMIT_VARS.display * 2 + 6,
+	vars: { action: 9 }
+}, {
+	length: COMMIT_VARS.display + 29,
+	vars: { action: 4 }
+}]);
+const DEFAULT_ADR_CONFIG = Object.freeze({
+	defaultTemplate: "nygard",
+	mainBranch: null,
+	index: "none",
+	acceptRequiresHuman: true,
+	autoCommit: false,
+	mcpCanDecide: false,
+	failOn: "error",
+	commitSubject: parseCommitTemplate(DEFAULT_COMMIT_SUBJECT, {
+		vars: COMMIT_VARS,
+		where: "commit.subject",
+		names: COMMIT_NAMES
+	}),
+	anchorKeyword: adrKind.anchorKeyword,
+	anchorExclude: Object.freeze([])
+});
+const TEMPLATE = /^[a-z][a-z0-9-]*$/;
+const KEYWORD = /^[a-z][a-z0-9-]{0,31}$/;
+const MAX_ANCHOR_EXCLUDE = 100;
+function isTable(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v) && !(v instanceof Date);
+}
+/**
+* Validates `adr.toml` (ledger's parsed `ToolConfig`; `null` when there is none). A wrong type or
+* value throws `ConfigError` naming the file and key. Unknown keys are ignored, so newer files
+* still load. `[log] root` is ledger's (`openToolLog` already checked it).
+*/
+function parseAdrConfig(config, file) {
+	if (config === null) return DEFAULT_ADR_CONFIG;
+	const where = file ?? config.file ?? "adr.toml";
+	const fail = (message) => new ConfigError(`${where}: ${message}`, { file: where });
+	const table = (name) => {
+		const t = config.raw[name];
+		if (t === void 0) return {};
+		if (!isTable(t)) throw fail(`${name} must be a table`);
+		return t;
+	};
+	const log = table("log");
+	const policy = table("policy");
+	const verify = table("verify");
+	const scope = table("scope");
+	const bool = (t, section, key, fallback) => {
+		const v = t[key];
+		if (v === void 0) return fallback;
+		if (typeof v !== "boolean") throw fail(`${section}.${key} must be true or false`);
+		return v;
+	};
+	const oneOf = (t, section, key, values, fallback) => {
+		const v = t[key];
+		if (v === void 0) return fallback;
+		if (typeof v !== "string" || !values.includes(v)) throw fail(`${section}.${key} must be ${values.map((x) => JSON.stringify(x)).join(" or ")}`);
+		return v;
+	};
+	const template = log.default_template;
+	if (template !== void 0 && (typeof template !== "string" || template.length > 64 || !TEMPLATE.test(template))) throw fail(`log.default_template must be a template name matching ${TEMPLATE.source}`);
+	const main = log.main_branch;
+	if (main !== void 0 && (typeof main !== "string" || main.trim() === "" || main.startsWith("-") || main.includes("\0"))) throw fail("log.main_branch must be a ref name that doesn't start with -");
+	const keyword = scope.anchor_keyword;
+	if (keyword !== void 0 && (typeof keyword !== "string" || !KEYWORD.test(keyword))) throw fail(`scope.anchor_keyword must match ${KEYWORD.source}`);
+	const exclude = scope.anchor_exclude;
+	if (exclude !== void 0) {
+		if (!Array.isArray(exclude) || exclude.length > MAX_ANCHOR_EXCLUDE) throw fail(`scope.anchor_exclude must be an array of at most ${MAX_ANCHOR_EXCLUDE} globs`);
+		exclude.forEach((g, i) => {
+			if (typeof g !== "string") throw fail(`scope.anchor_exclude[${i}] must be a string`);
+			const parsed = parseGlob(g);
+			if (!parsed.ok) throw fail(`scope.anchor_exclude[${i}]: ${parsed.message}`);
+		});
+	}
+	return {
+		defaultTemplate: typeof template === "string" ? template : DEFAULT_ADR_CONFIG.defaultTemplate,
+		mainBranch: typeof main === "string" ? main : null,
+		index: oneOf(log, "log", "index", ["committed", "none"], "none"),
+		acceptRequiresHuman: bool(policy, "policy", "accept_requires_human", true),
+		autoCommit: bool(policy, "policy", "auto_commit", false),
+		mcpCanDecide: bool(policy, "policy", "mcp_can_decide", false),
+		failOn: oneOf(verify, "verify", "fail_on", ["error", "warning"], "error"),
+		commitSubject: readCommitTemplate(config, {
+			file: where,
+			vars: COMMIT_VARS,
+			defaultSubject: DEFAULT_COMMIT_SUBJECT,
+			names: COMMIT_NAMES
+		}),
+		anchorKeyword: typeof keyword === "string" ? keyword : DEFAULT_ADR_CONFIG.anchorKeyword,
+		anchorExclude: Array.isArray(exclude) ? exclude : []
+	};
+}
+/** The built-in templates by name: the file text `adr new` materializes. */
+const BUILTIN_TEMPLATES = Object.freeze({
+	nygard: `---
+template: nygard
+version: 1
+sections:
+  - id: context
+    heading: Context
+    required: true
+    guidance: What is the issue that motivates this decision? Describe the forces at play.
+  - id: decision
+    heading: Decision
+    required: true
+    guidance: What is the change that we're proposing or doing? Write it in the active voice.
+  - id: scope
+    heading: Scope
+    required: true
+    guidance: What does this decision govern? Name the systems, code paths or teams it applies to.
+  - id: consequences
+    heading: Consequences
+    required: true
+    guidance: What becomes easier or harder because of this change? Include the risks.
+---
+# {{title}}
+
+## Context
+{{context}}
+
+## Decision
+{{decision}}
+
+## Scope
+{{scope}}
+
+## Consequences
+{{consequences}}
+`,
+	madr: `---
+template: madr
+version: 1
+sections:
+  - id: context
+    heading: Context and Problem Statement
+    required: true
+    guidance: Describe the context and the problem in two or three sentences, or as a question.
+  - id: drivers
+    heading: Decision Drivers
+    required: false
+    guidance: List the forces and concerns that shape the decision.
+  - id: options
+    heading: Considered Options
+    required: true
+    guidance: List the options that were considered, one per line.
+  - id: decision
+    heading: Decision Outcome
+    required: true
+    guidance: Name the chosen option and say why it was chosen.
+  - id: scope
+    heading: Scope
+    required: true
+    guidance: What does this decision govern? Name the systems, code paths or teams it applies to.
+  - id: consequences
+    heading: Consequences
+    required: true
+    guidance: Describe the good and the bad consequences of the chosen option.
+---
+# {{title}}
+
+## Context and Problem Statement
+{{context}}
+
+## Decision Drivers
+{{drivers}}
+
+## Considered Options
+{{options}}
+
+## Decision Outcome
+{{decision}}
+
+## Scope
+{{scope}}
+
+## Consequences
+{{consequences}}
+`,
+	"y-statement": `---
+template: y-statement
+version: 1
+sections:
+  - id: statement
+    heading: Statement
+    required: true
+    guidance: In the context of <use case>, facing <concern>, we decided for <option>, to achieve <quality>, accepting <downside>.
+  - id: scope
+    heading: Scope
+    required: true
+    guidance: What does this decision govern? Name the systems, code paths or teams it applies to.
+---
+# {{title}}
+
+## Statement
+{{statement}}
+
+## Scope
+{{scope}}
+`
+});
+// src/init.ts
+const CONFIG = "adr.toml";
+const DEFAULT_ROOT = adrKind.def.defaultRoot;
+const encoder$1 = new TextEncoder();
+/** The starter config; `root` only for a repo-level file naming a log elsewhere. */
+function configText(o) {
+	return [
+		"# adr configuration. Every key is optional: https://github.com/nikovirtala/ark/tree/main/packages/adr#config-adrtoml",
+		"[log]",
+		...o.root === null ? [] : [`root = ${JSON.stringify(o.root)}`],
+		`default_template = ${JSON.stringify(o.template)}`,
+		"",
+		"[commit]",
+		"# subject = \"docs(adr): {action} {title}\"",
+		""
+	].join("\n");
+}
+/**
+* `adr init` (design §6.2): writes a config for the log, unless one is found, and each built-in
+* template in `o.templates` (default `nygard`) to `<root>/templates/`, never overwriting a file.
+* A `--root` other than `docs/adr` gets a repo-level `adr.toml` naming it, so later commands find
+* the log without `--root`; when that file exists for another log, the config goes in the root.
+* With `commit` (default `[policy] auto_commit`) the written files are committed on their own;
+* nothing written means nothing committed. No events are written.
+*/
+async function initDecisionLog(log, o = {}) {
+	if (log.ref !== null || log.tree.label !== "worktree") throw new InvalidArgumentError("init writes the work tree; open the log without a ref");
+	const known = Object.keys(BUILTIN_TEMPLATES);
+	const templates = [...new Set(o.templates === void 0 ? ["nygard"] : o.templates)];
+	for (const name of templates) if (!known.includes(name)) throw new UsageError(`unknown built-in template ${name}; use nygard, madr or y-statement`);
+	const root = log.layout.root;
+	const notes = [...log.notes];
+	const files = [];
+	const kept = [];
+	let config = log.configPath;
+	if (config !== null) kept.push(config);
+	else {
+		const template = templates[0] ?? "nygard";
+		const repo = await readToolConfig(log.tree, CONFIG);
+		if (root === DEFAULT_ROOT) {
+			config = `${root}/${CONFIG}`;
+			files.push([config, configText({
+				root: null,
+				template
+			})]);
+		} else if (repo === null) {
+			config = CONFIG;
+			files.push([config, configText({
+				root,
+				template
+			})]);
+		} else {
+			const section = repo.raw.log;
+			const other = typeof section?.root === "string" ? section.root : DEFAULT_ROOT;
+			config = `${root}/${CONFIG}`;
+			files.push([config, configText({
+				root: null,
+				template
+			})]);
+			notes.push(`${CONFIG} names ${other}; pass --root ${root} to use this log`);
+		}
+	}
+	for (const name of templates) {
+		const path = `${root}/templates/${name}.md`;
+		if (await log.tree.read(path) !== null) kept.push(path);
+		else files.push([path, BUILTIN_TEMPLATES[name] ?? ""]);
+	}
+	const commit = files.length > 0 && (o.commit ?? log.adr.autoCommit);
+	if (commit && (await log.git.identity() === null || await log.git.committerIdentity() === null)) throw new ConfigError("--commit needs a git identity; set git user.name and user.email");
+	const written = [];
+	try {
+		for (const [path, text] of files) {
+			await writeNewFile(log.git, path, encoder$1.encode(text));
+			written.push(path);
+		}
+	} catch (err) {
+		const top = log.git.root ?? "";
+		for (const path of written) await rm(join(top, path), { force: true });
+		throw err;
+	}
+	if (written.length > 0) await log.git.add(written);
+	let sha = null;
+	if (commit) {
+		const message = o.message ?? renderCommitMessage(log.adr.commitSubject, {
+			title: "the decision log",
+			vars: {
+				action: "set up",
+				id: "",
+				display: "",
+				command: "init"
+			}
+		}).message;
+		sha = await log.git.commit({
+			message,
+			only: written
+		});
+	}
+	return {
+		format: "adr-init/v1",
+		root,
+		config,
+		written,
+		kept,
+		commit: sha,
+		notes
+	};
+}
+// src/log.ts
+/**
+* Opens the decision log (design D3): `--root`, else `adr.toml`'s `[log] root`, else `docs/adr`;
+* 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,
+		ref: log.ref,
+		commit: log.commit,
+		notes: log.notes
+	});
+}
+const compiled$1 = compileKind(adrKind);
+/** The git-free core of `readDecisions`; tests pass a MemoryTree and a hand-made `Numbering`. */
+async function readDecisionsFrom(tree, o) {
+	const { layout, adr, numbering } = o;
+	const snapshot = await loadLog(tree, {
+		kind: compiled$1,
+		layout
+	});
+	const folded = foldLog(adrKind, snapshot);
+	const ctx = {
+		kind: compiled$1,
+		layout,
+		base: null,
+		head: snapshot,
+		changes: [],
+		scope: "all",
+		inScope: new Set(snapshot.subjects.keys()),
+		folded: {
+			head: folded,
+			base: null
+		}
+	};
+	const options = { acceptRequiresHuman: adr.acceptRequiresHuman };
+	const findings = [];
+	for (const check of [
+		loadFindings,
+		transitions,
+		invariantsCheck(options),
+		relateCheck(options)
+	]) findings.push(...await check.run(ctx));
+	return {
+		tree,
+		layout,
+		adr,
+		root: layout.root,
+		ref: o.ref ?? null,
+		commit: o.commit ?? null,
+		folded,
+		projection: projectLog(adrKind, folded, { numbering }),
+		numbering,
+		findings: sortFindings(findings.map((f) => ({
+			...f,
+			kind: adrKind.name
+		}))),
+		notes: o.notes ?? []
+	};
+}
+/** Why numbers are unavailable, in words: `shallow clone` or `no main branch`. */
+function unavailableReason(n) {
+	return n.reason === "shallow" ? "shallow clone" : "no main branch";
+}
+/**
+* The id a decision argument names: an id, or a number in any form `parseDecisionNumber` takes.
+* Throws `UsageError` (exit 2) naming the reason when it names nothing.
+*/
+function resolveDecision(read, input) {
+	const r = resolveSubjectInput(input, {
+		subjects: new Set(read.folded.subjects.keys()),
+		kind: adrKind,
+		numbering: read.numbering
+	});
+	if (r.ok) return r.id;
+	const shown = JSON.stringify(input.trim());
+	switch (r.reason) {
+		case "malformed": throw new UsageError(`invalid decision ${JSON.stringify(input)}`);
+		case "qualified": throw new UsageError(`decision ${shown} is in another log; cross-log references aren't supported yet`);
+		case "numbers-unavailable": throw new UsageError(`decision numbers are unavailable (${unavailableReason(read.numbering)}); use the decision's id instead of ${shown}`);
+		case "not-found": throw new UsageError(`unknown decision ${input.trim()}`);
+	}
+}
+// 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.
+*/
+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));
+	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
+	};
+}
+const decoder$1 = new TextDecoder();
+/**
+* The `adr-show/v1` document of the decision `id` (resolve it with `resolveDecision` first).
+* Throws `UsageError` for an unknown, unreadable or unfoldable decision.
+*/
+async function showDecision(read, id, o = {}) {
+	const view = read.projection.views.get(id);
+	if (view === void 0) {
+		if (read.projection.unreadable.includes(id)) throw new UsageError(`decision ${id} uses a newer format; upgrade adr`);
+		if (read.projection.unfoldable.includes(id)) throw new UsageError(`decision ${id} can't be read; run adr verify`);
+		throw new UsageError(`unknown decision ${id}`);
+	}
+	const loaded = read.folded.subjects.get(id)?.loaded;
+	const body = loaded?.body ?? null;
+	const events = o.history === true ? (loaded?.events ?? []).flatMap((e) => e.event === null ? [] : [{
+		path: e.path,
+		event: e.event
+	}]).sort((a, b) => compareEvents({
+		...a.event,
+		path: a.path
+	}, {
+		...b.event,
+		path: b.path
+	})).map((e) => e.event) : null;
+	return {
+		format: "adr-show/v1",
+		root: read.root,
+		ref: read.ref,
+		commit: read.commit,
+		numbering: numberingJson(read),
+		header: stateHeader(view, read),
+		decision: view,
+		body: body === null ? null : decoder$1.decode(body.bytes),
+		events,
+		findings: read.findings.filter((f) => f.subject === id),
+		notes: read.notes
+	};
+}
+const day = (at) => (at ?? "").slice(0, 10);
+/** The reason on the applied event that produced the decision's current status, if any. */
+function statusReason(read, id) {
+	const reason = (read.folded.subjects.get(id)?.applied ?? []).findLast((a) => a.from !== a.to)?.event.reason;
+	return typeof reason === "string" && reason.trim() !== "" ? reason.trim() : null;
+}
+/**
+* The state header (01:258–259): `<display> (<id>) · <status>`, and for a decision that isn't in
+* force a warning saying what to read instead. `refer` names where to read another decision. CLI
+* default: `display(id)`. Phase 3 MCP passes `id => "adr://decision/" + display(id)`, e.g.
+* `adr://decision/ADR-0012`, or the id when unnumbered.
+*/
+function stateHeader(view, read, o = {}) {
+	const display = (id) => read.projection.views.get(id)?.display ?? id;
+	const refer = o.refer ?? display;
+	const line = view.number === null ? `${view.id} · ${view.status}` : `${view.display} (${view.id}) · ${view.status}`;
+	const parts = [];
+	const reason = statusReason(read, view.id);
+	const when = day(view.status_at);
+	switch (view.status) {
+		case "superseded": {
+			const target = view.effective ?? view.superseded_by ?? view.id;
+			const accepted = read.projection.views.get(target)?.decided_at ?? null;
+			const date = accepted === null ? "" : ` (accepted ${day(accepted)})`;
+			parts.push(`SUPERSEDED by ${display(target)}${date}. Do not apply this decision; read ${refer(target)} instead.`);
+			if (view.chain.length > 2) parts.push(`Chain: ${view.chain.map(display).join(" → ")}.`);
+			break;
+		}
+		case "deprecated":
+			parts.push(`DEPRECATED on ${when}: ${reason ?? "no reason given"}. No decision replaces it.`);
+			break;
+		case "rejected":
+			parts.push(`REJECTED on ${when}: ${reason ?? "no reason given"}. This decision was never in force.`);
+			break;
+		case "withdrawn": parts.push(`WITHDRAWN on ${when}${reason === null ? "" : `: ${reason}`}. This decision was never in force.`);
+	}
+	if (view.body_intact === false) parts.push("WARNING: the body changed after acceptance; run adr verify.");
+	return {
+		line,
+		warning: parts.length === 0 ? null : parts.join(" ")
+	};
+}
+// src/scope.ts
+const MAX_PATHS = 100;
+const MAX_PATH_LENGTH = 4096;
+/** Statuses whose globs govern code; rejected and withdrawn decisions were never in force. */
+const GLOBS_APPLY = /* @__PURE__ */ new Set([
+	"proposed",
+	"accepted",
+	"deprecated",
+	"superseded"
+]);
+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
+	};
+}
+// src/verify.ts
+/**
+* Every phase-1 check for the log: ledger's mechanical and fold checks with adr's actor policy,
+* and template lint against the templates in the head tree and, for older versions, the history
+* of `historyRef`.
+*/
+function adrChecks(log, historyRef) {
+	return foldChecks(adrKind, {
+		options: { acceptRequiresHuman: log.adr.acceptRequiresHuman },
+		templates: gitTemplates(log.git, { historyRef })
+	});
+}
+/** Verifies the decision log in `mode` (staged, range or full) with `adrChecks`. */
+async function verifyDecisions(log, mode) {
+	return verifyLog({
+		git: log.git,
+		kind: adrKind,
+		layout: log.layout,
+		mode,
+		checks: adrChecks(log, await templateHistoryRef(log.git, mode))
+	});
+}
+// src/write.ts
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const compiled = compileKind(adrKind);
+const TEMPLATE_NAME = /^[a-z][a-z0-9-]*$/;
+const MAX_TEXT_BYTES = 65536;
+const SUBJECT_ATTEMPTS = 5;
+const QUALIFIED_SUPERSESSION = "cross-log supersession isn't supported yet";
+const sorted = (xs) => [...new Set(xs)].sort();
+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;
+	if (size > MAX_TEXT_BYTES) throw new UsageError(`${what} is ${size} bytes; the limit is ${MAX_TEXT_BYTES} (64 KiB)`);
+}
+function checkReason(reason) {
+	if (reason === void 0 || reason === null) return null;
+	const r = reason.trim();
+	if (r === "") throw new UsageError("--reason must not be empty");
+	checkText("--reason", r);
+	return r;
+}
+/** The view of a folded decision, else `UsageError` naming why it can't be used. */
+function viewOf(read, id) {
+	const view = read.projection.views.get(id);
+	if (view !== void 0) return view;
+	if (read.projection.unreadable.includes(id)) throw new UsageError(`decision ${id} uses a newer format; upgrade adr`);
+	throw new UsageError(`decision ${id} can't be read; run adr verify`);
+}
+/** A refusal finding about decision `subject`, on its body (or events directory). */
+function refusal(read, rule, message, subject) {
+	const loaded = read.folded.subjects.get(subject)?.loaded;
+	return finding({
+		severity: "error",
+		rule,
+		message,
+		file: loaded?.bodyPaths[0] ?? eventDir(read.layout, subject),
+		subject,
+		kind: adrKind.name
+	});
+}
+/** `"<type> is not allowed while <status>[; <status> is terminal]"`, as the fold words it. */
+function illegal(type, status) {
+	return `${type} is not allowed while ${status}${adrKind.machine.terminal.includes(status) ? `; ${status} is terminal` : ""}`;
+}
+/** A new event of `subject`, sorting after its existing ones. */
+function newEvent(read, c, o) {
+	const existing = (read.folded.subjects.get(o.subject)?.loaded.events ?? []).flatMap((e) => e.event === null ? [] : [e.event]);
+	const { at, id } = nextEventIdentity([...existing, ...o.after ?? []], {
+		now: c.now,
+		...c.random === void 0 ? {} : { random: c.random }
+	});
+	return {
+		envelope: ENVELOPE_VERSION,
+		kind: adrKind.name,
+		schema: adrKind.schema,
+		id,
+		subject: o.subject,
+		type: o.type,
+		at,
+		actor: o.actor,
+		...o.reason === void 0 || o.reason === null ? {} : { reason: o.reason },
+		data: o.data
+	};
+}
+/** Body, events directory and recorded template of each involved subject (D6). */
+function commitScope(read, involved, extra = {}) {
+	const paths = [];
+	const dirs = [];
+	for (const id of involved) {
+		const view = read.projection.views.get(id);
+		if (view?.body_path !== null && view?.body_path !== void 0) paths.push(view.body_path);
+		if (view !== void 0) paths.push(templatePath(read, view.template.name));
+		dirs.push(eventDir(read.layout, id));
+	}
+	if (extra.body !== void 0) paths.push(extra.body);
+	if (extra.template !== void 0) paths.push(extra.template);
+	return {
+		scope: sorted([...paths, ...dirs]),
+		eventDirs: sorted(dirs)
+	};
+}
+const findingKey = (f) => [
+	f.rule,
+	f.subject ?? "",
+	f.file ?? "",
+	f.message
+].join("\0");
+/**
+* The precheck (§6.3): folds the would-be log and refuses when the write adds any finding. Problems
+* that were already there don't block; the write can only add findings about what it touches.
+*/
+async function precheck(read, files) {
+	const after = await readDecisionsFrom(overlayTree(read.tree, files), {
+		layout: read.layout,
+		adr: read.adr,
+		numbering: read.numbering,
+		ref: read.ref,
+		commit: read.commit,
+		notes: read.notes
+	});
+	const before = new Set(read.findings.map(findingKey));
+	return {
+		after,
+		added: after.findings.filter((f) => !before.has(findingKey(f)))
+	};
+}
+function filesOf(events, read) {
+	return Object.fromEntries(events.map((e) => [eventPath(read.layout, e), encoder.encode(serializeEvent(e))]));
+}
+const pairsOf = (events) => events.flatMap((e) => [["ADR", e.subject], ["ADR-Event", e.type]]);
+/** The template `new` uses: the repo's `<root>/templates/<name>.md`, else a built-in to copy. */
+async function chooseTemplate(read, name, c) {
+	if (name.length > 64 || !TEMPLATE_NAME.test(name)) throw new UsageError(`invalid template name ${JSON.stringify(name)}`);
+	const path = templatePath(read, name);
+	const bytes = await read.tree.read(path);
+	let text;
+	let materialize = null;
+	if (bytes !== null) text = decoder.decode(bytes);
+	else {
+		const builtin = Object.hasOwn(c.builtins, name) ? c.builtins[name] : void 0;
+		if (builtin === void 0) {
+			const known = Object.keys(c.builtins).sort().join(", ");
+			throw new UsageError(`unknown template ${name}; add ${path} or use one of ${known}`);
+		}
+		text = builtin;
+		materialize = builtin;
+	}
+	const parsed = parseTemplate(text, { path });
+	if (!parsed.ok) return {
+		ok: false,
+		findings: parsed.findings
+	};
+	const lint = lintTemplate(parsed.template, { requireSections: adrKind.def.templates?.requireSections ?? [] });
+	if (lint.length > 0) return {
+		ok: false,
+		findings: lint
+	};
+	return {
+		ok: true,
+		template: parsed.template,
+		materialize,
+		path
+	};
+}
+/**
+* Plans `adr new`: a rendered body, a materialized template if needed, and `proposed`. With
+* `refuseIncomplete` (a commit with no editor to fill the draft in, design §7.2), a draft that
+* fails the template lint is refused with those findings before any file is planned.
+*/
+async function planPropose(read, input, c, o = {}) {
+	const title = input.title.trim();
+	if (title === "" || title.length > 200 || /[\r\n]/.test(title)) throw new UsageError("the title must be a single line of 1 to 200 characters");
+	const supersedes = sorted((input.supersedes ?? []).map((s) => {
+		if (s.includes(":")) throw new UsageError(`cannot supersede ${s.trim()}: ${QUALIFIED_SUPERSESSION}`);
+		return resolveDecision(read, s);
+	}));
+	const chosen = await chooseTemplate(read, input.template ?? read.adr.defaultTemplate, c);
+	if (!chosen.ok) return {
+		ok: false,
+		decision: null,
+		findings: chosen.findings
+	};
+	const t = chosen.template;
+	const sections = input.sections ?? {};
+	for (const [id, text] of Object.entries(sections)) {
+		if (!t.sections.some((s) => s.id === id)) {
+			const ids = t.sections.map((s) => s.id).join(", ");
+			throw new UsageError(`template ${t.name} has no section ${id}; its sections are ${ids}`);
+		}
+		checkText(`section ${id}`, text);
+	}
+	const rendered = renderTemplate(t, {
+		title,
+		sections
+	}, { missing: "guidance" });
+	if (!rendered.ok) throw new UsageError(rendered.findings.map((f) => f.message).join("; "));
+	let id = "";
+	let bodyPath = "";
+	for (let attempt = 0;; attempt++) {
+		id = newSubjectId(c.random);
+		bodyPath = `${read.root}/${read.layout.bodies}/${bodyFileName(id, slugify(title))}`;
+		if (!read.folded.subjects.has(id) && await read.tree.read(bodyPath) === null) break;
+		if (attempt + 1 >= SUBJECT_ATTEMPTS) throw new FileExistsError(bodyPath);
+	}
+	const lint = lintDocument(t, rendered.text, {
+		file: bodyPath,
+		subject: id
+	});
+	if (o.refuseIncomplete === true && lint.length > 0) return {
+		ok: false,
+		decision: null,
+		findings: lint
+	};
+	const event = newEvent(read, c, {
+		subject: id,
+		type: "proposed",
+		data: {
+			title,
+			template: t.name,
+			template_version: t.version,
+			...supersedes.length === 0 ? {} : { supersedes }
+		},
+		actor: input.actor
+	});
+	const body = encoder.encode(rendered.text);
+	const files = { [bodyPath]: body };
+	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 {
+		ok: false,
+		decision: null,
+		findings: added
+	};
+	const { scope, eventDirs } = commitScope(read, [id], {
+		body: bodyPath,
+		template: chosen.path
+	});
+	return {
+		ok: true,
+		plan: {
+			command: "new",
+			subject: id,
+			files,
+			events: [event],
+			stage: Object.keys(files),
+			involved: [id],
+			commitScope: scope,
+			eventDirs,
+			draft: {
+				path: bodyPath,
+				rendered: body,
+				template: t
+			},
+			commit: {
+				action: ACTIONS.proposed.action,
+				title,
+				id,
+				display: id,
+				body: []
+			},
+			trailers: pairsOf([event]),
+			decision: viewOf(after, id),
+			affected: [],
+			findings: lint
+		}
+	};
+}
+/** The draft lint of an `accept`: the body against the template version its proposal recorded. */
+async function acceptLint(read, view, c) {
+	const body = read.folded.subjects.get(view.id)?.loaded.body ?? null;
+	if (body === null) return {
+		findings: [refusal(read, "body/missing", "body file is missing", view.id)],
+		bytes: null
+	};
+	const { name, version } = view.template;
+	const found = await c.templates.get(name, version);
+	if (!found.ok) {
+		const message = found.reason === "not-found" ? `template ${name} not found at ${found.path}` : `template ${name} has no version ${version} at ${found.path}`;
+		return {
+			findings: [refusal(read, `template/${found.reason}`, message, view.id)],
+			bytes: body.bytes
+		};
+	}
+	let text;
+	try {
+		text = new TextDecoder("utf-8", { fatal: true }).decode(body.bytes);
+	} catch {
+		return {
+			findings: [refusal(read, "body/not-utf8", "body is not valid UTF-8", view.id)],
+			bytes: body.bytes
+		};
+	}
+	return {
+		findings: lintDocument(found.template, text, {
+			file: body.path,
+			subject: view.id
+		}).map((f) => ({
+			...f,
+			kind: adrKind.name
+		})),
+		bytes: body.bytes
+	};
+}
+/** Plans `adr accept`: `accepted` with the body hash, and `superseded` on each declared target. */
+async function planAccept(read, input, c, o = {}) {
+	const id = resolveDecision(read, input.id);
+	const view = viewOf(read, id);
+	const refused = (findings) => ({
+		ok: false,
+		decision: view,
+		findings
+	});
+	const findings = [];
+	if (view.status !== "proposed") findings.push(refusal(read, "transition/illegal", illegal("accepted", view.status), id));
+	const lint = await acceptLint(read, view, c);
+	findings.push(...lint.findings);
+	if (read.adr.acceptRequiresHuman && input.actor.kind === "agent") findings.push(refusal(read, "decision/agent-accepted", `accepted by agent ${input.actor.name}; accept_requires_human needs a human`, id));
+	const targets = [];
+	for (const target of view.declared_supersedes) {
+		if (target.includes(":")) {
+			findings.push(refusal(read, "decision/reference-missing", `supersedes ${target}: ${QUALIFIED_SUPERSESSION}`, id));
+			continue;
+		}
+		const t = read.projection.views.get(target);
+		if (t === void 0) findings.push(refusal(read, "decision/reference-missing", `supersedes ${target}, which is not in the log`, id));
+		else if (target === id) findings.push(refusal(read, "decision/supersession-cycle", `supersession cycle: ${id} → ${id}`, id));
+		else if (t.status !== "accepted" && t.status !== "deprecated") findings.push(refusal(read, "transition/illegal", illegal("superseded", t.status), target));
+		else targets.push(target);
+	}
+	if (findings.length > 0 || lint.bytes === null) return refused(findings);
+	const accepted = newEvent(read, c, {
+		subject: id,
+		type: "accepted",
+		data: { body_sha256: bodySha256(lint.bytes) },
+		actor: input.actor
+	});
+	const cascade = targets.map((target) => newEvent(read, c, {
+		subject: target,
+		type: "superseded",
+		data: { by: id },
+		actor: input.actor
+	}));
+	const copyGlobs = o.copyGlobs ?? [];
+	const copied = copyGlobs.length === 0 ? null : newEvent(read, c, {
+		subject: id,
+		type: "scoped",
+		data: { set: [...applySetOp(view.applies_to, { add: copyGlobs }, {
+			what: "glob",
+			maxItems: 200
+		}).set] },
+		actor: input.actor,
+		after: [accepted]
+	});
+	if (copied !== null) {
+		const valid = compiled.validate(copied, { file: null });
+		if (!valid.ok) return refused(valid.findings.map((f) => ({
+			...f,
+			subject: id,
+			kind: adrKind.name
+		})));
+	}
+	const sources = copied === null ? [] : scopeToCopy(read, id).sources;
+	const events = [
+		accepted,
+		...copied === null ? [] : [copied],
+		...cascade
+	];
+	const files = filesOf(events, read);
+	const { after, added } = await precheck(read, files);
+	if (added.length > 0) return refused(added);
+	const involved = sorted([id, ...targets]);
+	const { scope, eventDirs } = commitScope(read, involved);
+	const bodyPath = view.body_path ?? "";
+	return {
+		ok: true,
+		plan: {
+			command: "accept",
+			subject: id,
+			files,
+			events,
+			stage: [...Object.keys(files), bodyPath],
+			involved,
+			commitScope: scope,
+			eventDirs,
+			draft: null,
+			commit: {
+				action: ACTIONS.accepted.action,
+				title: view.title,
+				id,
+				display: view.display,
+				body: [...targets.map((t) => {
+					const v = viewOf(read, t);
+					return `Supersedes ${v.display}: ${sentenceTitle(v.title)}.`;
+				}), ...sources.map((t) => `Copies the scope of ${viewOf(read, t).display}.`)]
+			},
+			trailers: pairsOf(events),
+			decision: viewOf(after, id),
+			affected: targets.map((t) => viewOf(after, t)),
+			findings: []
+		}
+	};
+}
+/**
+* What accepting `id` could copy: the declared targets it will supersede (accepted or
+* deprecated, as `planAccept` selects them) and the globs of theirs it doesn't have yet.
+*/
+function scopeToCopy(read, id) {
+	const own = new Set(viewOf(read, id).applies_to);
+	const sources = [];
+	const globs = /* @__PURE__ */ new Set();
+	for (const target of sorted(viewOf(read, id).declared_supersedes)) {
+		const t = target === id ? void 0 : read.projection.views.get(target);
+		if (t === void 0 || t.status !== "accepted" && t.status !== "deprecated") continue;
+		const extra = t.applies_to.filter((g) => !own.has(g));
+		if (extra.length === 0) continue;
+		sources.push(target);
+		for (const g of extra) globs.add(g);
+	}
+	return {
+		id,
+		sources,
+		displays: sources.map((t) => viewOf(read, t).display),
+		globs: sorted(globs)
+	};
+}
+const shQuote = (s) => `'${s.replaceAll("'", "'\\''")}'`;
+const andList = (xs) => xs.length <= 1 ? xs.join("") : `${xs.slice(0, -1).join(", ")} and ${xs.at(-1)}`;
+/** The note of an offer not taken: the `adr scope` command that copies it. */
+function copyScopeNote(id, offer) {
+	const n = offer.globs.length;
+	const adds = offer.globs.map((g) => `--add ${shQuote(g)}`).join(" ");
+	return `not copying the scope of ${andList(offer.displays)} (${n} ${n === 1 ? "glob" : "globs"}); to copy it: adr scope ${id} ${adds}`;
+}
+/** Plans `adr supersede <id> --by <by>`: one `superseded` event on `id`. */
+async function planSupersede(read, input, c) {
+	if (input.by.includes(":")) throw new UsageError(`--by ${input.by.trim()}: ${QUALIFIED_SUPERSESSION}`);
+	const reason = checkReason(input.reason);
+	const id = resolveDecision(read, input.id);
+	const by = resolveDecision(read, input.by);
+	const view = viewOf(read, id);
+	const target = viewOf(read, by);
+	const findings = [];
+	if (view.status !== "accepted" && view.status !== "deprecated") findings.push(refusal(read, "transition/illegal", illegal("superseded", view.status), id));
+	if (by === id || target.chain.includes(id)) {
+		const cycle = by === id ? [id, id] : [id, ...target.chain.slice(0, target.chain.indexOf(id) + 1)];
+		findings.push(refusal(read, "decision/supersession-cycle", `supersession cycle: ${cycle.join(" → ")}`, id));
+	} else if (target.status !== "accepted") findings.push(refusal(read, "decision/superseded-by-unaccepted", `superseded by ${by}, which is not accepted`, id));
+	const refused = (fs) => ({
+		ok: false,
+		decision: view,
+		findings: fs
+	});
+	if (findings.length > 0) return refused(findings);
+	const event = newEvent(read, c, {
+		subject: id,
+		type: "superseded",
+		data: { by },
+		reason,
+		actor: input.actor
+	});
+	const files = filesOf([event], read);
+	const { after, added } = await precheck(read, files);
+	if (added.length > 0) return refused(added);
+	const involved = sorted([id, by]);
+	const { scope, eventDirs } = commitScope(read, involved);
+	return {
+		ok: true,
+		plan: {
+			command: "supersede",
+			subject: id,
+			files,
+			events: [event],
+			stage: Object.keys(files),
+			involved,
+			commitScope: scope,
+			eventDirs,
+			draft: null,
+			commit: {
+				action: ACTIONS.superseded.action,
+				title: `${view.display} with ${target.display}`,
+				id,
+				display: view.display,
+				body: [`Superseded by ${target.display}: ${sentenceTitle(target.title)}.`]
+			},
+			trailers: pairsOf([event]),
+			decision: viewOf(after, id),
+			affected: [viewOf(after, id)],
+			findings: []
+		}
+	};
+}
+/**
+* `{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"
+};
+/** A title in a body sentence: whitespace collapsed and trailing dots removed, as in a subject. */
+const sentenceTitle = (title) => title.replace(/\s+/g, " ").replace(/[. ]+$/, "").trim();
+/**
+* Plans any one event on an existing decision: the state machine and the event's validation
+* decide, then the precheck. Phase 2's reject, withdraw, deprecate, note, link and scope wrap it.
+*/
+async function planEvent(read, input, c) {
+	const id = resolveDecision(read, input.subject);
+	const view = viewOf(read, id);
+	if (!adrKind.machine.types.has(input.type) || input.type === adrKind.machine.initial.type) throw new InvalidArgumentError(`planEvent can't write a ${input.type} event`);
+	const reason = checkReason(input.reason);
+	const refused = (fs) => ({
+		ok: false,
+		decision: view,
+		findings: fs
+	});
+	if (!adrKind.machine.allowed(view.status, input.type)) return refused([refusal(read, "transition/illegal", illegal(input.type, view.status), id)]);
+	const event = newEvent(read, c, {
+		subject: id,
+		type: input.type,
+		data: input.data,
+		reason,
+		actor: input.actor
+	});
+	const valid = compiled.validate(event, { file: null });
+	if (!valid.ok) return refused(valid.findings.map((f) => ({
+		...f,
+		subject: id,
+		kind: adrKind.name
+	})));
+	const files = filesOf([event], read);
+	const { after, added } = await precheck(read, files);
+	if (added.length > 0) return refused(added);
+	const by = input.type === "superseded" ? String(input.data.by) : null;
+	const involved = sorted([id, ...by !== null && isSubjectId(by) ? [by] : []]);
+	const { scope, eventDirs } = commitScope(read, involved);
+	return {
+		ok: true,
+		plan: {
+			command: "event",
+			subject: id,
+			files,
+			events: [event],
+			stage: Object.keys(files),
+			involved,
+			commitScope: scope,
+			eventDirs,
+			draft: null,
+			commit: {
+				action: actionOf(input.type).action,
+				title: actionOf(input.type).names === "title" ? view.title : view.display,
+				id,
+				display: view.display,
+				body: reason === null ? [] : [`Reason: ${reason}`]
+			},
+			trailers: pairsOf([event]),
+			decision: viewOf(after, id),
+			affected: input.type === "superseded" ? [viewOf(after, id)] : [],
+			findings: []
+		}
+	};
+}
+/** Plans `adr reject`: `rejected` with its required reason, while proposed. */
+function planReject(read, input, c) {
+	return planEvent(read, {
+		...input,
+		subject: input.id,
+		type: "rejected",
+		data: {}
+	}, c);
+}
+/** Plans `adr withdraw`: `withdrawn`, with a reason when given, while proposed. */
+function planWithdraw(read, input, c) {
+	return planEvent(read, {
+		...input,
+		subject: input.id,
+		type: "withdrawn",
+		data: {}
+	}, c);
+}
+/** Plans `adr deprecate`: `deprecated` with its required reason, while accepted. */
+function planDeprecate(read, input, c) {
+	return planEvent(read, {
+		...input,
+		subject: input.id,
+		type: "deprecated",
+		data: {}
+	}, c);
+}
+/** Plans `adr note`: `noted` with the text as given, in every state. */
+function planNote(read, input, c) {
+	if (input.text.trim() === "") throw new UsageError("the note text must not be empty");
+	checkText("the note text", input.text);
+	return planEvent(read, {
+		subject: input.id,
+		type: "noted",
+		data: { text: input.text },
+		actor: input.actor
+	}, c);
+}
+const LINK_RELS = [
+	"relates-to",
+	"refines",
+	"depends-on"
+];
+const SOURCE_NAME = /^[a-z][a-z0-9-]{0,31}$/;
+/**
+* Plans `adr link` (design §6.7): `linked` in every state. A qualified target must name one of
+* `o.sources` (the log's `[[sources]]` names); it isn't looked up in the other log. A link that
+* already exists plans nothing, with a note.
+*/
+async function planLink(read, input, c, o = {}) {
+	const rel = input.rel ?? "relates-to";
+	if (!LINK_RELS.includes(rel)) throw new UsageError(`unknown --rel ${rel}; use relates-to, refines or depends-on`);
+	const id = resolveDecision(read, input.id);
+	const view = viewOf(read, id);
+	const target = input.to.trim();
+	let to;
+	let shown;
+	let described;
+	let named;
+	const at = target.indexOf(":");
+	if (at >= 0) {
+		const source = target.slice(0, at);
+		const local = target.slice(at + 1);
+		if (!SOURCE_NAME.test(source) || !isSubjectId(local)) throw new UsageError(`invalid decision ${JSON.stringify(input.to)}`);
+		if (!(o.sources ?? []).includes(source)) throw new UsageError(`unknown source ${source}; add a [[sources]] entry named ${source}`);
+		to = target;
+		shown = target;
+		described = `${rel} ${target}.`;
+		named = `${view.display} to a decision in another log`;
+	} else {
+		to = resolveDecision(read, target);
+		if (to === id) throw new UsageError("a decision can't link to itself");
+		const t = viewOf(read, to);
+		shown = t.display;
+		described = `${rel} ${t.display}: ${sentenceTitle(t.title)}.`;
+		named = `${view.display} to ${t.display}`;
+	}
+	if (view.links.some((l) => l.to === to && l.rel === rel)) return {
+		ok: true,
+		plan: {
+			command: "event",
+			subject: id,
+			files: {},
+			events: [],
+			stage: [],
+			involved: [id],
+			commitScope: [],
+			eventDirs: [],
+			draft: null,
+			commit: null,
+			trailers: [],
+			decision: view,
+			affected: [],
+			findings: [],
+			notes: [`already linked: ${view.display} ${rel} ${shown}; nothing written`]
+		}
+	};
+	const r = await planEvent(read, {
+		subject: id,
+		type: "linked",
+		data: {
+			to,
+			rel
+		},
+		actor: input.actor
+	}, c);
+	if (!r.ok || r.plan.commit === null) return r;
+	return {
+		ok: true,
+		plan: {
+			...r.plan,
+			commit: {
+				...r.plan.commit,
+				title: named,
+				body: [described]
+			}
+		}
+	};
+}
+/** `ADR-0003 (k3f9q8a1)`, or the id alone when the decision has no number. */
+const namedView = (v) => v.display === v.id ? v.id : `${v.display} (${v.id})`;
+/** The globs of `globs` that match none of `files`. */
+function unmatchedGlobs(globs, files) {
+	const matches = globMatcher(globs);
+	const hit = new Set(files.flatMap((f) => matches(f)));
+	return globs.filter((g) => !hit.has(g));
+}
+/**
+* Plans `adr scope` with a set operation (design §6.8): one `scoped` event with the whole new set
+* while proposed, accepted or deprecated, or nothing when the set doesn't change. Invalid globs,
+* conflicting operations and more than 200 globs are `UsageError`s. Notes name removed globs that
+* weren't there, added ones that were, resulting globs matching none of `o.tracked` (when given)
+* and a narrowed accepted scope.
+*/
+async function planScope(read, input, c, o = {}) {
+	const id = resolveDecision(read, input.id);
+	const view = viewOf(read, id);
+	const result = applySetOp(view.applies_to, input.op, {
+		what: "glob",
+		validate: (g) => {
+			const parsed = parseGlob(g);
+			return parsed.ok ? null : parsed.message;
+		},
+		maxItems: 200,
+		...input.names === void 0 ? {} : { names: input.names }
+	});
+	if (!adrKind.machine.allowed(view.status, "scoped")) return {
+		ok: false,
+		decision: view,
+		findings: [refusal(read, "transition/illegal", illegal("scoped", view.status), id)]
+	};
+	const named = namedView(view);
+	const notes = [...result.absent.map((g) => `${g} is not in the scope of ${named}`), ...result.present.map((g) => `${g} is already in the scope of ${named}`)];
+	if (!result.changed) return {
+		ok: true,
+		plan: {
+			command: "event",
+			subject: id,
+			files: {},
+			events: [],
+			stage: [],
+			involved: [id],
+			commitScope: [],
+			eventDirs: [],
+			draft: null,
+			commit: null,
+			trailers: [],
+			decision: view,
+			affected: [],
+			findings: [],
+			notes
+		}
+	};
+	if (o.tracked !== void 0) notes.push(...unmatchedGlobs(result.set, o.tracked).map((g) => `${g} matches no tracked file`));
+	if (result.removed.length > 0 && (view.status === "accepted" || view.status === "deprecated")) notes.push("this narrows the scope of an accepted decision; if its Scope section no longer reads true, propose a superseding decision instead");
+	const r = await planEvent(read, {
+		subject: id,
+		type: "scoped",
+		data: { set: [...result.set] },
+		actor: input.actor
+	}, c);
+	return r.ok ? {
+		ok: true,
+		plan: {
+			...r.plan,
+			notes
+		}
+	} : r;
+}
+/**
+* Plans one `scoped` event per change, in one batch (design §6.8 step 4): each decision's status
+* must allow `scoped` and each event must validate, else the first failing decision is refused.
+* The plan has no commit message, because `--follow-renames` never commits. `decision` is
+* `input.id`'s view after the write, or `null` without one; `affected` are the changed views.
+*/
+async function planScopeEvents(read, changes, input, c) {
+	const given = input.id === null ? null : viewOf(read, input.id);
+	const events = [];
+	for (const change of changes) {
+		const view = viewOf(read, change.id);
+		const refused = (findings) => ({
+			ok: false,
+			decision: given,
+			findings
+		});
+		if (!adrKind.machine.allowed(view.status, "scoped")) return refused([refusal(read, "transition/illegal", illegal("scoped", view.status), change.id)]);
+		const event = newEvent(read, c, {
+			subject: change.id,
+			type: "scoped",
+			data: { set: [...change.set] },
+			actor: input.actor
+		});
+		const valid = compiled.validate(event, { file: null });
+		if (!valid.ok) return refused(valid.findings.map((f) => ({
+			...f,
+			subject: change.id,
+			kind: adrKind.name
+		})));
+		events.push(event);
+	}
+	const files = filesOf(events, read);
+	const { after, added } = await precheck(read, files);
+	if (added.length > 0) return {
+		ok: false,
+		decision: given,
+		findings: added
+	};
+	const involved = sorted(changes.map((ch) => ch.id));
+	const { scope, eventDirs } = commitScope(read, involved);
+	return {
+		ok: true,
+		plan: {
+			command: "event",
+			subject: input.id ?? involved[0] ?? "",
+			files,
+			events,
+			stage: Object.keys(files),
+			involved,
+			commitScope: scope,
+			eventDirs,
+			draft: null,
+			commit: null,
+			trailers: pairsOf(events),
+			decision: input.id === null ? null : viewOf(after, input.id),
+			affected: changes.map((ch) => viewOf(after, ch.id)),
+			findings: []
+		}
+	};
+}
+/** A plan that writes nothing: the views as they are, and `notes`. */
+function emptyPlan(subject, decision, notes) {
+	return {
+		ok: true,
+		plan: {
+			command: "event",
+			subject,
+			files: {},
+			events: [],
+			stage: [],
+			involved: decision === null ? [] : [decision.id],
+			commitScope: [],
+			eventDirs: [],
+			draft: null,
+			commit: null,
+			trailers: [],
+			decision,
+			affected: [],
+			findings: [],
+			notes
+		}
+	};
+}
+/**
+* Plans `adr scope [<decision>] --follow-renames` (design §6.8 steps 1–4): the given decision's
+* globs, or every decision's, rewritten by `followRenames`. Decisions whose status forbids
+* `scoped` are skipped, with a note when the renames would have changed their scope; an explicit
+* one is refused.
+*/
+async function planFollowRenames(read, input, staged, c) {
+	const id = input.id === null ? null : resolveDecision(read, input.id);
+	const given = id === null ? null : viewOf(read, id);
+	if (staged.renames.length === 0) return emptyPlan(id ?? "", given, []);
+	if (given !== null && !adrKind.machine.allowed(given.status, "scoped")) return {
+		ok: false,
+		decision: given,
+		findings: [refusal(read, "transition/illegal", illegal("scoped", given.status), given.id)]
+	};
+	const views = given !== null ? [given] : [...read.projection.views.values()];
+	const notes = [];
+	const changes = [];
+	for (const view of [...views].sort((a, b) => a.id < b.id ? -1 : 1)) {
+		const result = followRenames({
+			globs: view.applies_to,
+			...staged
+		});
+		if (!result.changed) continue;
+		const named = namedView(view);
+		if (!adrKind.machine.allowed(view.status, "scoped")) {
+			const covers = globMatcher(view.applies_to);
+			const leaving = staged.renames.filter((r) => covers(r.from).length > 0).length;
+			notes.push(`${named} is ${view.status}; its scope can't follow renames (${leaving} renamed files leave it)`);
+			continue;
+		}
+		if (result.globs.length > 200) throw new UsageError(`following the renames gives ${named} ${result.globs.length} globs; the limit is 200`);
+		for (const s of result.skipped) notes.push(`${s.to} can't be written as a scope glob (${s.problem}); ${named} no longer covers it`);
+		for (const path of result.gained) notes.push(`${path} is now covered by ${named}'s scope but wasn't before the rename; check it`);
+		changes.push({
+			id: view.id,
+			set: result.globs
+		});
+	}
+	if (changes.length === 0) return emptyPlan(id ?? "", given, notes);
+	const r = await planScopeEvents(read, changes, {
+		id,
+		actor: input.actor
+	}, c);
+	return r.ok ? {
+		ok: true,
+		plan: {
+			...r.plan,
+			notes
+		}
+	} : r;
+}
+/** The paths of every file in `tree`. */
+async function filePaths(tree) {
+	return (await tree.list("")).filter((e) => e.type === "file").map((e) => e.path);
+}
+/** Every tracked file in the index, for the "matches no tracked file" notes. */
+async function trackedFiles(log) {
+	return filePaths(await indexReader(log.git));
+}
+const isYaml = (path) => /\.ya?ml$/.test(path);
+/**
+* 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.
+*/
+async function applyPlan(log, plan, o) {
+	const { git } = log;
+	if (o.commit && o.message === void 0) throw new InvalidArgumentError("applyPlan needs a message to commit");
+	const stage = new Set(plan.stage);
+	if (o.commit) {
+		const unstaged = new Set(await git.unstagedPaths(plan.commitScope));
+		const dirs = new Set(plan.eventDirs);
+		const untracked = /* @__PURE__ */ new Set([...await git.untrackedPaths(plan.commitScope.filter((p) => !dirs.has(p))), ...(await git.untrackedPaths(plan.eventDirs)).filter(isYaml)]);
+		const [first] = sorted([...unstaged, ...untracked]).filter((p) => !stage.has(p));
+		if (first !== void 0) throw new UsageError(unstaged.has(first) ? `${first} has unstaged changes; stage or discard them, or run without --commit` : `${first} is not tracked; git add it, or run without --commit`);
+	}
+	const eventPaths = new Set(plan.events.map((e) => eventPath(log.layout, e)));
+	const written = [];
+	try {
+		for (const [path, bytes] of Object.entries(plan.files)) {
+			if (eventPaths.has(path)) continue;
+			await writeNewFile(git, path, bytes, { stage: false });
+			written.push(path);
+		}
+		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 });
+		throw err;
+	}
+	await git.add(plan.stage);
+	let findings = plan.findings;
+	let commit = o.commit;
+	if (o.afterStage !== void 0) {
+		const after = await o.afterStage();
+		findings = after.findings ?? plan.findings;
+		commit = commit && after.commit;
+	}
+	let sha = null;
+	if (commit) {
+		const extra = (await git.stagedPaths(plan.commitScope)).filter((p) => !stage.has(p));
+		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])
+		});
+	}
+	return {
+		written: Object.keys(plan.files),
+		commit: sha,
+		findings
+	};
+}
+const DEFAULT_DEPS = {
+	now: Date.now,
+	apply: applyPlan
+};
+/**
+* The views `adr-write/v1` reports. Without a commit they are the plan's, folded on the overlay.
+* After a commit they come from a new read of the log, so a commit on the main ref shows the
+* numbers it assigned, as the CLI text and phase 3's MCP tools do. A commit that failed threw in
+* `applyPlan`, so nothing is read for it.
+*/
+async function viewsAfter(log, plan, sha) {
+	if (sha === null) return {
+		decision: plan.decision,
+		affected: plan.affected
+	};
+	const read = await readDecisions({
+		...log,
+		commit: sha
+	});
+	const view = (v) => read.projection.views.get(v.id) ?? v;
+	return {
+		decision: plan.decision === null ? null : view(plan.decision),
+		affected: plan.affected.map(view)
+	};
+}
+const SHORTENED_NOTE = "commit subject shortened to 72 characters; the full title is in the commit body";
+/**
+* `--commit` needs an author and a committer identity; checked before anything is written, since
+* `GIT_AUTHOR_*` alone satisfies the author while `git commit` still fails on the committer.
+*/
+async function checkCommitIdentity(log) {
+	if (await log.git.identity() === null || await log.git.committerIdentity() === null) throw new ConfigError("--commit needs a git identity; set git user.name and user.email");
+}
+/** The plan's commit message from `[commit] subject` (design §4), and whether it was shortened. */
+function commitMessage(log, command, plan) {
+	const parts = plan.commit;
+	if (parts === null) throw new InvalidArgumentError("this write can't be committed");
+	const r = renderCommitMessage(log.adr.commitSubject, {
+		title: parts.title,
+		vars: {
+			action: parts.action,
+			id: parts.id,
+			display: parts.display,
+			command
+		},
+		body: parts.body
+	});
+	return {
+		message: r.message,
+		shortened: r.shortened
+	};
+}
+/**
+* Plan, then apply, with the single `EventExistsError` retry (§5.4 steps 1–5). `o.message`
+* replaces the rendered commit message; `o.notes` come before the write's own notes. A plan with
+* no files and no events is reported as written without touching the repository, and so is
+* every plan with `dryRun` (its views are the plan's).
+*/
+async function write(log, command, plan, o, deps, afterStage) {
+	if (log.ref !== null) throw new InvalidArgumentError("writes read the work tree; open the log without a ref");
+	if (log.tree.label !== "worktree") throw new InvalidArgumentError("writes read the work tree; open the log with the worktree reader");
+	const commit = o.commit ?? log.adr.autoCommit;
+	if (commit) await checkCommitIdentity(log);
+	const notes = [...log.notes, ...o.notes ?? []];
+	for (let attempt = 0;; attempt++) {
+		const read = await readDecisions(log);
+		const ref = await templateHistoryRef(log.git, { type: "full" });
+		const r = await plan(read, {
+			now: deps.now,
+			...deps.random === void 0 ? {} : { random: deps.random },
+			templates: historyTemplates(log.git, log.tree, `${read.root}/templates`, { ref }),
+			builtins: BUILTIN_TEMPLATES
+		});
+		if (!r.ok) return {
+			format: "adr-write/v1",
+			command,
+			ok: false,
+			decision: r.decision,
+			affected: [],
+			written: [],
+			commit: null,
+			findings: r.findings,
+			notes
+		};
+		if (r.plan.events.length === 0 && Object.keys(r.plan.files).length === 0 || o.dryRun === true) return {
+			format: "adr-write/v1",
+			command,
+			ok: true,
+			decision: r.plan.decision,
+			affected: r.plan.affected,
+			written: [],
+			commit: null,
+			findings: r.plan.findings,
+			notes: [...notes, ...r.plan.notes ?? []]
+		};
+		const rendered = commit ? commitMessage(log, command, r.plan) : null;
+		const given = o.message ?? null;
+		try {
+			const applied = await deps.apply(log, r.plan, {
+				commit,
+				...rendered === null ? {} : {
+					message: given ?? rendered.message,
+					mergeTrailers: given !== null
+				},
+				...afterStage === void 0 ? {} : { afterStage: afterStage(r.plan, commit) }
+			});
+			const views = await viewsAfter(log, r.plan, applied.commit);
+			const own = [...r.plan.notes ?? [], ...applied.commit !== null && given === null && rendered?.shortened === true ? [SHORTENED_NOTE] : []];
+			return {
+				format: "adr-write/v1",
+				command,
+				ok: true,
+				decision: views.decision,
+				affected: views.affected,
+				written: applied.written,
+				commit: applied.commit,
+				findings: applied.findings,
+				notes: [...notes, ...own]
+			};
+		} catch (err) {
+			if (!(err instanceof EventExistsError) || attempt > 0) throw err;
+		}
+	}
+}
+const sameBytes = (a, b) => a.byteLength === b.byteLength && a.every((x, i) => x === b[i]);
+async function readIfPresent(path) {
+	try {
+		return await readFile(path);
+	} catch (err) {
+		if (err.code === "ENOENT") return null;
+		throw err;
+	}
+}
+/**
+* The editor step (§5.4): runs `edit` on the staged draft, re-stages the edited body when the
+* editor exited 0, and skips the commit when committing would take content nobody confirmed: the
+* body changed while the editor failed, the body is gone, or another path in the commit scope (a
+* materialized template, say) changed while the editor was open (design review NIT 2). The
+* findings are the lint of the draft as it now is.
+*/
+function editorStep(log, edit, onNote) {
+	return (plan, commitRequested) => async () => {
+		const d = plan.draft;
+		if (d === null) return {
+			findings: null,
+			commit: true
+		};
+		const abs = join(log.git.root ?? "", d.path);
+		const note = await edit(abs);
+		const bytes = await readIfPresent(abs);
+		let commit;
+		if (bytes === null) {
+			commit = false;
+			onNote?.(`${d.path} was removed while editing; the rendered draft is still staged. Restore it with \`git checkout -- ${d.path}\``);
+		} else if (note === null) {
+			await log.git.add([d.path]);
+			commit = true;
+		} else if (sameBytes(bytes, d.rendered)) commit = true;
+		else {
+			commit = false;
+			if (commitRequested) onNote?.(`${d.path} changed while the editor failed; review it, then git add it and commit`);
+		}
+		if (commit && commitRequested) {
+			const [first] = (await log.git.unstagedPaths(plan.commitScope)).filter((p) => p !== d.path);
+			if (first !== void 0) {
+				commit = false;
+				onNote?.(`${first} changed while the editor was open; review it, then git add it and commit`);
+			}
+		}
+		const text = decoder.decode(bytes ?? d.rendered);
+		const findings = lintDocument(d.template, text, {
+			file: d.path,
+			subject: plan.subject
+		});
+		if (commit && commitRequested && findings.length > 0) {
+			commit = false;
+			onNote?.(`${d.path} still has unfilled required sections; fill them in, then commit`);
+		}
+		return {
+			findings,
+			commit
+		};
+	};
+}
+/**
+* `adr new`: renders a draft, writes the body, any materialized template and the `proposed`
+* event, stages them, and commits with `commit` (default `[policy] auto_commit`).
+*
+* `edit` (CLI only; MCP never passes it) runs between staging and committing, on the absolute
+* body path. It resolves to `null` when the editor exited 0, else to a note for the user (spawn
+* error, exit status). `onNote` receives the notes about a skipped commit or a removed body,
+* without the "not committed: " prefix the CLI adds when a commit was requested.
+*
+* A draft with unfilled sections is never committed (design §7.2): without `edit` a commit is
+* refused (`ok: false`, nothing written); after `edit` the commit is skipped with a note.
+*/
+async function proposeDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	return write(log, "new", (read, c) => planPropose(read, input, c, { refuseIncomplete: (o.commit ?? log.adr.autoCommit) && o.edit === void 0 }), o, deps, o.edit === void 0 ? void 0 : editorStep(log, o.edit, o.onNote));
+}
+/**
+* `adr accept`: lints the draft, hashes the body, writes `accepted` and a `superseded` event on
+* each declared target, stages them with the body, and commits with `commit`. When the targets
+* have globs the decision lacks, `copyScope` decides whether a `scoped` event copies them
+* (default `"suggest"`: no copy, and a note with the `adr scope` command that would).
+*/
+async function acceptDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	const copyScope = o.copyScope ?? "suggest";
+	let copy = null;
+	return write(log, "accept", async (read, c) => {
+		const plain = await planAccept(read, input, c);
+		if (!plain.ok) return plain;
+		const id = plain.plan.subject;
+		const offer = scopeToCopy(read, id);
+		if (offer.globs.length === 0) return plain;
+		if (copy === null) copy = typeof copyScope === "function" ? await copyScope(offer) : copyScope === "copy";
+		if (copy) return planAccept(read, input, c, { copyGlobs: offer.globs });
+		if (copyScope === "skip") return plain;
+		const notes = [...plain.plan.notes ?? [], copyScopeNote(id, offer)];
+		return {
+			ok: true,
+			plan: {
+				...plain.plan,
+				notes
+			}
+		};
+	}, o, deps);
+}
+/** `adr supersede <id> --by <by>`: writes `superseded`, stages it, and commits with `commit`. */
+async function supersedeDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	return write(log, "supersede", (read, c) => planSupersede(read, input, c), o, deps);
+}
+/**
+* `adr reject <id> --reason <text>`: writes `rejected`, stages it, and commits with `commit`. The
+* kind requires the reason; without one the write is refused (findings, nothing written).
+*/
+async function rejectDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	return write(log, "reject", (read, c) => planReject(read, input, c), o, deps);
+}
+/** `adr withdraw <id> [--reason <text>]`: writes `withdrawn`, stages it, and commits with `commit`. */
+async function withdrawDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	return write(log, "withdraw", (read, c) => planWithdraw(read, input, c), o, deps);
+}
+/**
+* `adr deprecate <id> --reason <text>`: writes `deprecated`, stages it, and commits with `commit`.
+* The kind requires the reason, as for `rejectDecision`.
+*/
+async function deprecateDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	return write(log, "deprecate", (read, c) => planDeprecate(read, input, c), o, deps);
+}
+/** `adr note <id> <text>`: writes `noted`, stages it, and commits with `commit`. */
+async function noteDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	return write(log, "note", (read, c) => planNote(read, input, c), o, deps);
+}
+/**
+* `adr link <id> <target> [--rel <rel>]`: writes `linked`, stages it, and commits with `commit`.
+* Qualified targets name the log's `[[sources]]`; a link that exists already writes nothing.
+*/
+async function linkDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	const sources = (log.config?.sources ?? []).map((s) => s.name);
+	return write(log, "link", (read, c) => planLink(read, input, c, { sources }), o, deps);
+}
+/**
+* `adr scope <id> --set|--add|--remove …`: writes one `scoped` event with the new set, stages it,
+* and commits with `commit`. An unchanged set writes nothing.
+*/
+async function scopeDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	const tracked = await trackedFiles(log);
+	return write(log, "scope", (read, c) => planScope(read, input, c, { tracked }), o, deps);
+}
+const FOLLOW_NO_COMMIT_NOTE = "--follow-renames never commits; commit the scoped events with the renames";
+/**
+* `adr scope [<decision>] --follow-renames` (design §6.8): rewrites the scope globs of the given
+* decision, or of every decision, after the renames staged against `HEAD`, and stages one
+* `scoped` event per changed decision. It never commits, whatever `[policy] auto_commit` says
+* (the events belong in the commit with the renames), so `o.commit: true` and a message are
+* `InvalidArgumentError`s. `dryRun` plans the same events and notes without writing anything.
+*/
+async function followScopeRenames(log, input, o = {}, deps = DEFAULT_DEPS) {
+	if (o.commit === true) throw new InvalidArgumentError("followScopeRenames never commits; don't pass commit: true");
+	if (o.message !== void 0 && o.message !== null) throw new InvalidArgumentError("followScopeRenames never commits, so it takes no message");
+	const renames = await stagedRenames(log.git);
+	const staged = renames.length === 0 ? {
+		renames,
+		before: [],
+		after: []
+	} : {
+		renames,
+		before: await filePaths(await refReader(log.git, "HEAD")),
+		after: await filePaths(await indexReader(log.git))
+	};
+	const doc = await write(log, "scope", (read, c) => planFollowRenames(read, {
+		id: input.id ?? null,
+		actor: input.actor
+	}, staged, c), {
+		...o,
+		commit: false
+	}, deps);
+	return log.adr.autoCommit && doc.ok && doc.affected.length > 0 ? {
+		...doc,
+		notes: [...doc.notes, FOLLOW_NO_COMMIT_NOTE]
+	} : doc;
+}
+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 };
+
+//# sourceMappingURL=write-9IaqHRrY.js.map