@nikovirtala/adr 0.0.0 → 0.1.0

package/dist/write-C3IW5WrA.js

@@ -0,0 +1,1011 @@
+import { t as adrKind } from "./kind-DqFhApu7.js";
+import { ConfigError, ENVELOPE_VERSION, EventExistsError, FileExistsError, InvalidArgumentError, UsageError, bodyFileName, bodySha256, classifyPath, compareEvents, compileKind, eventDir, eventPath, finding, foldChecks, foldLog, gitTemplates, historyTemplates, invariantsCheck, lintDocument, lintTemplate, loadFindings, loadLog, newSubjectId, nextEventIdentity, numberLog, openToolLog, overlayTree, parseEventFileName, parseTemplate, projectLog, relateCheck, renderTemplate, resolveSubjectInput, serializeEvent, slugify, sortFindings, templateHistoryRef, transitions, verifyLog, writeEvents, writeNewFile } from "@nikovirtala/ledger";
+import { readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+// src/config.ts
+const DEFAULT_ADR_CONFIG = Object.freeze({
+	defaultTemplate: "nygard",
+	mainBranch: null,
+	index: "none",
+	acceptRequiresHuman: true,
+	autoCommit: false,
+	mcpCanDecide: false,
+	failOn: "error"
+});
+const TEMPLATE = /^[a-z][a-z0-9-]*$/;
+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 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 -");
+	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")
+	};
+}
+// 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 arrive in phase 2`);
+		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/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/views.ts
+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(" ")
+	};
+}
+/** The built-in templates by name: the file text `adr new` materializes. */
+const BUILTIN_TEMPLATES = Object.freeze({
+	nygard: `---
+template: nygard
+version: 1
+sections:
+  - id: context
+    heading: Context
+    required: true
+    guidance: What is the issue that motivates this decision? Describe the forces at play.
+  - id: decision
+    heading: Decision
+    required: true
+    guidance: What is the change that we're proposing or doing? Write it in the active voice.
+  - id: scope
+    heading: Scope
+    required: true
+    guidance: What does this decision govern? Name the systems, code paths or teams it applies to.
+  - id: consequences
+    heading: Consequences
+    required: true
+    guidance: What becomes easier or harder because of this change? Include the risks.
+---
+# {{title}}
+
+## Context
+{{context}}
+
+## Decision
+{{decision}}
+
+## Scope
+{{scope}}
+
+## Consequences
+{{consequences}}
+`,
+	madr: `---
+template: madr
+version: 1
+sections:
+  - id: context
+    heading: Context and Problem Statement
+    required: true
+    guidance: Describe the context and the problem in two or three sentences, or as a question.
+  - id: drivers
+    heading: Decision Drivers
+    required: false
+    guidance: List the forces and concerns that shape the decision.
+  - id: options
+    heading: Considered Options
+    required: true
+    guidance: List the options that were considered, one per line.
+  - id: decision
+    heading: Decision Outcome
+    required: true
+    guidance: Name the chosen option and say why it was chosen.
+  - id: scope
+    heading: Scope
+    required: true
+    guidance: What does this decision govern? Name the systems, code paths or teams it applies to.
+  - id: consequences
+    heading: Consequences
+    required: true
+    guidance: Describe the good and the bad consequences of the chosen option.
+---
+# {{title}}
+
+## Context and Problem Statement
+{{context}}
+
+## Decision Drivers
+{{drivers}}
+
+## Considered Options
+{{options}}
+
+## Decision Outcome
+{{decision}}
+
+## Scope
+{{scope}}
+
+## Consequences
+{{consequences}}
+`,
+	"y-statement": `---
+template: y-statement
+version: 1
+sections:
+  - id: statement
+    heading: Statement
+    required: true
+    guidance: In the context of <use case>, facing <concern>, we decided for <option>, to achieve <quality>, accepting <downside>.
+  - id: scope
+    heading: Scope
+    required: true
+    guidance: What does this decision govern? Name the systems, code paths or teams it applies to.
+---
+# {{title}}
+
+## Statement
+{{statement}}
+
+## Scope
+{{scope}}
+`
+});
+// src/write.ts
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+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 arrives in phase 2";
+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`. */
+async function planPropose(read, input, c) {
+	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 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
+			},
+			message: `Propose decision ${id}: ${title}`,
+			trailers: pairsOf([event]),
+			decision: viewOf(after, id),
+			affected: [],
+			findings: lintDocument(t, rendered.text, {
+				file: bodyPath,
+				subject: id
+			})
+		}
+	};
+}
+/** 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) {
+	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 events = [newEvent(read, c, {
+		subject: id,
+		type: "accepted",
+		data: { body_sha256: bodySha256(lint.bytes) },
+		actor: input.actor
+	}), ...targets.map((target) => newEvent(read, c, {
+		subject: target,
+		type: "superseded",
+		data: { by: id },
+		actor: input.actor
+	}))];
+	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,
+			message: [`Accept decision ${id}: ${view.title}`, ...targets.length === 0 ? [] : ["", ...targets.map((t) => `Supersedes ${t}.`)]].join("\n"),
+			trailers: pairsOf(events),
+			decision: viewOf(after, id),
+			affected: targets.map((t) => viewOf(after, t)),
+			findings: []
+		}
+	};
+}
+/** 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,
+			message: `Supersede decision ${id}: ${view.title}\n\nSuperseded by ${by}.`,
+			trailers: pairsOf([event]),
+			decision: viewOf(after, id),
+			affected: [viewOf(after, id)],
+			findings: []
+		}
+	};
+}
+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;
+	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: plan.message,
+			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: view(plan.decision),
+		affected: plan.affected.map(view)
+	};
+}
+/** Plan, then apply, with the single `EventExistsError` retry (§5.4 steps 1–5). */
+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;
+	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: log.notes
+		};
+		try {
+			const applied = await deps.apply(log, r.plan, {
+				commit,
+				...afterStage === void 0 ? {} : { afterStage: afterStage(r.plan, commit) }
+			});
+			const views = await viewsAfter(log, r.plan, applied.commit);
+			return {
+				format: "adr-write/v1",
+				command,
+				ok: true,
+				decision: views.decision,
+				affected: views.affected,
+				written: applied.written,
+				commit: applied.commit,
+				findings: applied.findings,
+				notes: log.notes
+			};
+		} 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);
+		return {
+			findings: lintDocument(d.template, text, {
+				file: d.path,
+				subject: plan.subject
+			}),
+			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.
+*/
+async function proposeDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	return write(log, "new", (read, c) => planPropose(read, input, c), 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`.
+*/
+async function acceptDecision(log, input, o = {}, deps = DEFAULT_DEPS) {
+	return write(log, "accept", (read, c) => planAccept(read, input, c), 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);
+}
+export { showDecision as a, verifyDecisions as c, readDecisionsFrom as d, resolveDecision as f, parseAdrConfig as h, listDecisions as i, openDecisionLog as l, DEFAULT_ADR_CONFIG as m, proposeDecision as n, stateHeader as o, unavailableReason as p, supersedeDecision as r, adrChecks as s, acceptDecision as t, readDecisions as u };
+
+//# sourceMappingURL=write-C3IW5WrA.js.map