@nikovirtala/adr 0.2.0 → 0.4.0

package/dist/init-YgW7g9Fx.js

@@ -0,0 +1,588 @@
+import { C as headTree, D as renderDecisionIndex, E as indexPath, S as firstLine, b as INDEX_AFTER, c as followScopeRenames, j as numberDecisions, k as writeIndexCopy, v as BUILTIN_TEMPLATES, w as holdsText, x as decisionIndexCheck } from "./search-CwIPlNGd.js";
+import { t as adrKind } from "./kind-DjvA3dyA.js";
+import { ConfigError, InvalidArgumentError, UsageError, anchorCheck, assertNoHookConflicts, classifyPath, commitWithRecovery, exitCode, finding, foldChecks, gitTemplates, governedChanges, hookSnippet, installHooks, narrowedScopes, overlayTree, parseEventFileName, projectLog, readToolConfig, renderCommitMessage, replaceFile, resolveAttribution, scopeGlobCheck, stagedRenames, templateHistoryRef, uninstallHooks, verifyLog, worktreeReader, writeIndexFile, writeNewFile } from "@nikovirtala/ledger";
+import { access, constants, rm } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+// src/verify.ts
+/** At most this many paths are named in a `decision/scope-narrowed` message. */
+const NARROWED_PATHS = 3;
+/** The head's decision views with the read's numbering, for the displays in messages. */
+async function headViews(log, ctx) {
+	const head = ctx.folded?.head;
+	if (head === void 0) return /* @__PURE__ */ new Map();
+	return projectLog(adrKind, head, { numbering: await numberDecisions(log) }).views;
+}
+/**
+* `decision/governed-by-inactive` (`[verify] governed_by_inactive`, default warning): a changed
+* code file that a superseded or deprecated decision governs, by glob or anchor (01:366).
+*/
+function governedByInactive(log) {
+	return {
+		id: "decision-governed-by-inactive",
+		async run(ctx) {
+			const changes = await governedChanges(ctx, {
+				keyword: log.adr.anchorKeyword,
+				exclude: log.adr.anchorExclude,
+				statuses: ["superseded", "deprecated"]
+			});
+			if (changes.length === 0) return [];
+			const views = await headViews(log, ctx);
+			const display = (id) => views.get(id)?.display ?? id;
+			const message = (c) => {
+				const what = `${c.path} is governed by ${display(c.subject)}`;
+				if (c.status === "deprecated") return `${what}, which is deprecated; check whether the change still needs it`;
+				const next = views.get(c.subject)?.superseded_by ?? null;
+				return next === null ? `${what}, which is superseded; check the change against its successor` : `${what}, which is superseded by ${display(next)}; check the change against ${display(next)}`;
+			};
+			return changes.map((c) => finding({
+				severity: log.adr.governedByInactive,
+				rule: "decision/governed-by-inactive",
+				message: message(c),
+				file: c.path,
+				subject: c.subject
+			}));
+		}
+	};
+}
+/**
+* `decision/scope-narrowed` (warning): an accepted decision whose new scope stops covering files
+* that still exist (01:367), which calls for a check against its Scope section.
+*/
+function scopeNarrowed(log) {
+	return {
+		id: "decision-scope-narrowed",
+		async run(ctx) {
+			const narrowed = await narrowedScopes(ctx, { statuses: ["accepted"] });
+			if (narrowed.length === 0) return [];
+			const views = await headViews(log, ctx);
+			return narrowed.map((n) => {
+				const count = n.lost.length;
+				const files = count === 1 ? "1 file that still exists" : `${count} files that still exist`;
+				const named = n.lost.slice(0, NARROWED_PATHS).join(", ");
+				const more = count > NARROWED_PATHS ? ", …" : "";
+				return finding({
+					severity: "warning",
+					rule: "decision/scope-narrowed",
+					message: `${views.get(n.subject)?.display ?? n.subject}'s scope no longer covers ${files} (${named}${more}); check the change against its Scope section`,
+					file: n.file,
+					subject: n.subject
+				});
+			});
+		}
+	};
+}
+/**
+* Every check for the log: ledger's mechanical and fold checks with adr's actor policy, template
+* lint against the templates in the head tree and, for older versions, the history of
+* `historyRef`, the scope-glob and anchor checks, and the decision checks over code
+* (`decision/governed-by-inactive`, `decision/scope-narrowed`). With `[log] index = "committed"`,
+* also the freshness of `<root>/index.md`.
+*/
+function adrChecks(log, historyRef) {
+	return [
+		...foldChecks(adrKind, {
+			options: { acceptRequiresHuman: log.adr.acceptRequiresHuman },
+			templates: gitTemplates(log.git, { historyRef })
+		}),
+		scopeGlobCheck(),
+		anchorCheck({
+			keyword: log.adr.anchorKeyword,
+			exclude: log.adr.anchorExclude
+		}),
+		governedByInactive(log),
+		scopeNarrowed(log),
+		...log.adr.index === "committed" ? [decisionIndexCheck(log)] : []
+	];
+}
+/** Verifies the decision log in `mode` (staged, range or full) with `adrChecks`. */
+async function verifyDecisions(log, mode) {
+	return verifyLog({
+		git: log.git,
+		kind: adrKind,
+		layout: log.layout,
+		mode,
+		checks: adrChecks(log, await templateHistoryRef(log.git, mode))
+	});
+}
+// src/hooks.ts
+/** The hooks adr registers, in the order the text output lists them. */
+const HOOKS = [
+	"pre-commit",
+	"commit-msg",
+	"pre-push",
+	"post-merge"
+];
+/**
+* adr's command per hook (design 2b D4), after `adr`. `--root <root>` comes first only when the
+* root can't be found without it: no `<repo>/adr.toml` names it and it isn't `docs/adr`. So the
+* hooks see the same config as a plain `adr` run, and never print the root-override note.
+*/
+function decisionHookCommands(log) {
+	const r = log.configPath === "adr.toml" || log.layout.root === adrKind.def.defaultRoot ? [] : ["--root", log.layout.root];
+	return {
+		"pre-commit": [
+			...r,
+			"hooks",
+			"run",
+			"pre-commit"
+		],
+		"commit-msg": [
+			...r,
+			"hooks",
+			"trailers",
+			"{args}"
+		],
+		"pre-push": [
+			...r,
+			"verify",
+			"--base",
+			"@{upstream}",
+			"--ref",
+			"HEAD"
+		],
+		"post-merge": [
+			...r,
+			"list",
+			"--since",
+			"ORIG_HEAD"
+		]
+	};
+}
+function registrations(log) {
+	const commands = decisionHookCommands(log);
+	return HOOKS.flatMap((hook) => {
+		const argv = commands[hook];
+		return argv === void 0 ? [] : [{
+			hook,
+			argv
+		}];
+	});
+}
+/** A shim path as the user sees it: repo-relative, with `/`. */
+function shown(git, path) {
+	return relative(git.root ?? git.gitDir, path).split(sep).join("/");
+}
+/** The shims in hook order: `HOOKS`' order, as the text output lists them. */
+function inHookOrder(git, paths) {
+	const rank = (p) => HOOKS.findIndex((h) => p.endsWith(`/${h}`));
+	return paths.map((p) => shown(git, p)).sort((a, b) => rank(a) - rank(b));
+}
+function result(log, action, r, extra = {}) {
+	return {
+		format: "adr-hooks/v1",
+		action,
+		written: r === null ? [] : inHookOrder(log.git, r.written),
+		unchanged: r === null ? [] : inHookOrder(log.git, r.unchanged),
+		registrations: registrations(log),
+		snippet: extra.snippet ?? null,
+		trailers: extra.trailers ?? []
+	};
+}
+/**
+* Registers adr's four commands in ledger's shims, one per hook and shared with other ark tools
+* (design 2b D4). With `core.hooksPath` set or a foreign hook file present, it writes the rest and
+* then throws `HookConflictError` (exit 2), naming each conflict and the `print` command.
+*/
+async function installDecisionHooks(log) {
+	const r = await installHooks(log.git, {
+		tool: "adr",
+		commands: decisionHookCommands(log)
+	});
+	assertNoHookConflicts(r, { tool: "adr" });
+	return result(log, "install", r);
+}
+/** Removes adr from every shim; a shim left with no tool is deleted. */
+async function uninstallDecisionHooks(log) {
+	return result(log, "uninstall", await uninstallHooks(log.git, { tool: "adr" }));
+}
+/** The config to paste into a hook manager instead of installing shims. */
+function printDecisionHooks(log, manager) {
+	const regs = registrations(log).map((r) => ({
+		tool: "adr",
+		...r
+	}));
+	return result(log, "print", null, { snippet: hookSnippet(manager, regs) });
+}
+/** The `ADR-Event` trailer key as git compares keys: case-insensitively. */
+const ADR_EVENT = /^adr-event[ \t]*:/im;
+/**
+* The `commit-msg` step (P1 §7.1): appends one `ADR`/`ADR-Event` pair per staged added event file
+* of the log, by path, keeping repeats (`ifExists: "add"`). It does nothing for a message that
+* already has an `ADR-Event:` trailer (an `adr … --commit` message), or during a merge, whose
+* events came with their own commits' trailers. Throws `UsageError` when the file is missing.
+*/
+async function addHookTrailers(log, messageFile) {
+	const { git, layout } = log;
+	const file = resolve(git.root ?? git.gitDir, messageFile);
+	try {
+		await access(file, constants.R_OK | constants.W_OK);
+	} catch {
+		throw new UsageError(`no commit message file at ${messageFile}`);
+	}
+	const parsed = await git.run([
+		"interpret-trailers",
+		"--parse",
+		"--",
+		file
+	]);
+	if (ADR_EVENT.test(Buffer.from(parsed.stdout).toString("utf8"))) return result(log, "trailers", null);
+	if (await git.resolveCommit("MERGE_HEAD") !== null) return result(log, "trailers", null);
+	const trailers = (await git.stagedPaths([`${layout.root}/${layout.events}`], { addedOnly: true })).flatMap((p) => {
+		const c = classifyPath(layout, p);
+		const name = c.area === "event" && !c.file.includes("/") ? parseEventFileName(c.file) : null;
+		return c.area === "event" && c.subject !== null && name !== null ? [["ADR", c.subject], ["ADR-Event", name.type]] : [];
+	});
+	await git.appendTrailers(file, trailers, { ifExists: "add" });
+	return result(log, "trailers", null, { trailers });
+}
+/**
+* Whether the hook may stage: only into the commit's real index (design 2b D8). `git commit
+* <paths>` and `--only`, adr's own `--commit` included, run hooks on a temporary index, and
+* staging there leaves the user's index showing the file as deleted.
+*/
+function stagingSafe(git, env) {
+	const file = env.GIT_INDEX_FILE;
+	if (file === void 0 || file === "") return true;
+	const at = resolve(git.root ?? git.gitDir, file);
+	return at === resolve(git.gitDir, "index") || at === resolve(git.gitDir, "index.lock");
+}
+/** `ADR-0003, ADR-0004` for the decisions a rename following changes. */
+const displays = (views) => views.map((v) => v.display).join(", ");
+/**
+* `adr hooks run pre-commit` (design 2b D8): rename following, then the index, then `verify
+* --staged`, stopping at the first step that fails. `worktree` must be opened with the work-tree
+* reader, because rename following writes through `write()`; `index` with the index reader, for
+* the config as staged, the index render and verify. Only the index step stages `index.md`, and
+* only with `[hooks] index = "stage"`; rename following passes `index: "skip"`. Neither stages
+* into a temporary index (`stagingSafe`). A step that can't run throws (exit 2).
+*/
+async function runPreCommitHook(o) {
+	const { worktree, index, env } = o;
+	const config = index.adr;
+	const failOn = config.failOn;
+	const notes = [...index.notes];
+	const done = (exit, findings) => ({
+		exit,
+		findings,
+		notes: [...new Set(notes)],
+		failOn
+	});
+	const safe = stagingSafe(index.git, env);
+	if (config.scopeFollowRenames !== "off" && (await stagedRenames(worktree.git)).length > 0) {
+		const { actor, notes: attribution } = await resolveAttribution(worktree.git, { env });
+		if (config.scopeFollowRenames === "warn") {
+			const dry = await followScopeRenames(worktree, { actor }, { dryRun: true });
+			for (const v of dry.affected) notes.push(`${v.display}'s globs don't follow the renames in this commit (scope_follow_renames = "warn"); run adr scope --follow-renames`);
+		} else if (safe) {
+			const doc = await followScopeRenames(worktree, { actor }, {
+				index: "skip",
+				notes: attribution
+			});
+			notes.push(...doc.notes);
+			if (!doc.ok) return done(1, doc.findings);
+		} else {
+			const dry = await followScopeRenames(worktree, { actor }, { dryRun: true });
+			if (dry.affected.length > 0) {
+				notes.push(`the renames in this commit change the scope of ${displays(dry.affected)}; git commit <paths> can't take the scoped events. Run adr scope --follow-renames, then commit again including the files it lists, or set [hooks] scope_follow_renames = "warn"`);
+				return done(1, []);
+			}
+		}
+	}
+	if (config.index === "committed" && config.hookIndex === "stage" && safe) {
+		const path = indexPath(index.layout);
+		const text = await renderDecisionIndex(index.git, {
+			layout: index.layout,
+			adr: config,
+			tree: index.tree,
+			history: await index.git.resolveCommit("HEAD")
+		});
+		if (text !== null && !holdsText(await index.tree.read(path), text)) {
+			await writeIndexFile(index.git, path, text);
+			await index.git.add([path]);
+			notes.push(`regenerated and staged ${path}`);
+		}
+	}
+	const findings = await verifyDecisions(index, { type: "staged" });
+	return done(exitCode(findings, { failOn }), findings);
+}
+// src/skill.ts
+/**
+* The agent skill `adr init --skill` writes (01, "Agent skill (SKILL.md)"): the judgment of when
+* to use adr's MCP tools. `skill.test.ts` keeps it equal to the block in docs/01-adr-v1.md.
+*/
+const SKILL_MD = `---
+name: adr
+description: Use before changing architecture, data stores, integration patterns, dependencies or cross-cutting conventions, and whenever asked to record, propose or look up an architectural decision.
+---
+
+# Architectural decisions (adr)
+
+Decisions in this repo are managed by adr. Decision files do not
+show their own status, so never judge from the raw files whether a
+decision applies.
+
+## Before changing architecture
+
+1. Call adr_for_path for the files you will touch, and adr_search
+   for the area you are about to change. adr_search returns active
+   decisions only; adr_for_path also lists inactive ones, each with
+   a warning.
+2. If your change conflicts with an accepted decision, stop and tell
+   the user which ADR it conflicts with. Do not work around it silently.
+3. If the user still wants the change, propose a superseding ADR.
+
+## Reading decisions
+
+- Use adr_get or adr://decision/{id}, never docs/adr/decisions/*.md.
+- If a response says SUPERSEDED or DEPRECATED, follow it to the
+  effective decision before acting.
+- If it says REJECTED or WITHDRAWN, the decision was never in force;
+  do not apply it.
+
+## Proposing decisions
+
+1. Call adr_templates and fill every required section.
+2. Use only facts from the conversation and the code. Mark unknowns
+   as open questions instead of inventing them.
+3. List at least two options considered when the template has that section.
+4. Set supersedes when the proposal replaces an existing decision.
+5. Do not accept your own proposal. Tell the user the ADR id and
+   that they can review it and run: adr accept <id>
+6. If the user decides against your proposal, withdraw it with
+   adr_withdraw and give their reason. Don't withdraw other
+   people's proposals; tell the user instead.
+
+## Changing scope
+
+- When you move or rename code covered by a decision, let the
+  pre-commit hook update its globs (adr hooks install). For your
+  own proposals, you can use adr_scope. Rescoping an accepted
+  decision needs mcp_can_decide; otherwise tell the user and
+  suggest adr scope <id> ….
+- Before any scope change, read the decision's Scope section. If it
+  would no longer read true after the change, do not rescope: tell
+  the user the decision itself is changing and propose a
+  superseding ADR.
+
+## Never
+
+- Edit an accepted decision body, any file under docs/adr/events/,
+  or index.md by hand.
+- Use adr_note to change the meaning of a decision. Notes clarify;
+  changed decisions need a superseding ADR.
+
+## Without the MCP server
+
+Use the CLI with --json: adr search, adr for, adr show, adr new,
+adr note. Set ARK_AGENT=<your name> and ARK_ON_BEHALF_OF=<the user's
+email> so your writes are attributed.
+`;
+// src/init.ts
+/**
+* What the recovery hint says about rerunning `adr init` after `git commit` failed (design 2b D5):
+* init keeps existing files, so it would commit nothing.
+*/
+const INIT_RERUN = "Running adr init again won't commit them: the files exist now, so it keeps them and commits nothing.";
+const CONFIG = "adr.toml";
+const DEFAULT_ROOT = adrKind.def.defaultRoot;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const AGENTS = "AGENTS.md";
+/** The line `adr init --skill` adds to AGENTS.md for tools that don't load skills. */
+const agentsPointer = (skill) => `Architecture decisions in this repository are managed by adr: read ${skill} before changing architecture, and follow it.`;
+/** `text` with `line` appended after one blank line, ending with a newline. */
+function appendLine(text, line) {
+	if (text === "") return `${line}\n`;
+	const ended = text.endsWith("\n") ? text : `${text}\n`;
+	return `${ended.endsWith("\n\n") ? ended : `${ended}\n`}${line}\n`;
+}
+/** The starter config; `root` only for a repo-level file naming a log elsewhere. */
+function configText(o) {
+	return [
+		"# adr configuration. Every key is optional: https://github.com/nikovirtala/ark/tree/main/packages/adr#config-adrtoml",
+		"[log]",
+		...o.root === null ? [] : [`root = ${JSON.stringify(o.root)}`],
+		`default_template = ${JSON.stringify(o.template)}`,
+		"",
+		"[commit]",
+		"# subject = \"docs(adr): {action} {title}\"",
+		""
+	].join("\n");
+}
+/**
+* `adr init` (design §6.2): writes a config for the log, unless one is found, and each built-in
+* template in `o.templates` (default `nygard`) to `<root>/templates/`, never overwriting a file.
+* A `--root` other than `docs/adr` gets a repo-level `adr.toml` naming it, so later commands find
+* the log without `--root`; when that file exists for another log, the config goes in the root.
+* With `[log] index = "committed"` it also writes `<root>/index.md` unless one exists. With
+* `commit` (default `[policy] auto_commit`) the written files are committed on their own;
+* nothing written means nothing committed. No events are written. With `o.skill` it also writes
+* the agent skill, unless a SKILL.md is there, and adds the pointer line to `AGENTS.md`, unless a
+* line already names the skill; an AGENTS.md with unstaged changes or not tracked is refused
+* with a commit and left unstaged without one.
+*/
+async function initDecisionLog(log, o = {}) {
+	if (log.ref !== null || log.tree.label !== "worktree") throw new InvalidArgumentError("init writes the work tree; open the log without a ref");
+	const known = Object.keys(BUILTIN_TEMPLATES);
+	const templates = [...new Set(o.templates === void 0 ? ["nygard"] : o.templates)];
+	for (const name of templates) if (!known.includes(name)) throw new UsageError(`unknown built-in template ${name}; use nygard, madr or y-statement`);
+	const root = log.layout.root;
+	const notes = [...log.notes];
+	const files = [];
+	const kept = [];
+	let config = log.configPath;
+	if (config !== null) kept.push(config);
+	else {
+		const template = templates[0] ?? "nygard";
+		const repo = await readToolConfig(log.tree, CONFIG);
+		if (root === DEFAULT_ROOT) {
+			config = `${root}/${CONFIG}`;
+			files.push([config, configText({
+				root: null,
+				template
+			})]);
+		} else if (repo === null) {
+			config = CONFIG;
+			files.push([config, configText({
+				root,
+				template
+			})]);
+		} else {
+			const section = repo.raw.log;
+			const other = typeof section?.root === "string" ? section.root : DEFAULT_ROOT;
+			config = `${root}/${CONFIG}`;
+			files.push([config, configText({
+				root: null,
+				template
+			})]);
+			notes.push(`${CONFIG} names ${other}; pass --root ${root} to use this log`);
+		}
+	}
+	for (const name of templates) {
+		const path = `${root}/templates/${name}.md`;
+		if (await log.tree.read(path) !== null) kept.push(path);
+		else files.push([path, BUILTIN_TEMPLATES[name] ?? ""]);
+	}
+	const commitRequested = o.commit ?? log.adr.autoCommit;
+	const logFiles = files.length;
+	const skill = o.skill === void 0 ? null : o.skill.dir === "" ? "SKILL.md" : `${o.skill.dir}/SKILL.md`;
+	let agents = null;
+	if (skill !== null) {
+		const current = await log.tree.read(skill);
+		if (current === null) files.push([skill, SKILL_MD]);
+		else {
+			kept.push(skill);
+			if (decoder.decode(current) !== "---\nname: adr\ndescription: Use before changing architecture, data stores, integration patterns, dependencies or cross-cutting conventions, and whenever asked to record, propose or look up an architectural decision.\n---\n\n# Architectural decisions (adr)\n\nDecisions in this repo are managed by adr. Decision files do not\nshow their own status, so never judge from the raw files whether a\ndecision applies.\n\n## Before changing architecture\n\n1. Call adr_for_path for the files you will touch, and adr_search\n   for the area you are about to change. adr_search returns active\n   decisions only; adr_for_path also lists inactive ones, each with\n   a warning.\n2. If your change conflicts with an accepted decision, stop and tell\n   the user which ADR it conflicts with. Do not work around it silently.\n3. If the user still wants the change, propose a superseding ADR.\n\n## Reading decisions\n\n- Use adr_get or adr://decision/{id}, never docs/adr/decisions/*.md.\n- If a response says SUPERSEDED or DEPRECATED, follow it to the\n  effective decision before acting.\n- If it says REJECTED or WITHDRAWN, the decision was never in force;\n  do not apply it.\n\n## Proposing decisions\n\n1. Call adr_templates and fill every required section.\n2. Use only facts from the conversation and the code. Mark unknowns\n   as open questions instead of inventing them.\n3. List at least two options considered when the template has that section.\n4. Set supersedes when the proposal replaces an existing decision.\n5. Do not accept your own proposal. Tell the user the ADR id and\n   that they can review it and run: adr accept <id>\n6. If the user decides against your proposal, withdraw it with\n   adr_withdraw and give their reason. Don't withdraw other\n   people's proposals; tell the user instead.\n\n## Changing scope\n\n- When you move or rename code covered by a decision, let the\n  pre-commit hook update its globs (adr hooks install). For your\n  own proposals, you can use adr_scope. Rescoping an accepted\n  decision needs mcp_can_decide; otherwise tell the user and\n  suggest adr scope <id> ….\n- Before any scope change, read the decision's Scope section. If it\n  would no longer read true after the change, do not rescope: tell\n  the user the decision itself is changing and propose a\n  superseding ADR.\n\n## Never\n\n- Edit an accepted decision body, any file under docs/adr/events/,\n  or index.md by hand.\n- Use adr_note to change the meaning of a decision. Notes clarify;\n  changed decisions need a superseding ADR.\n\n## Without the MCP server\n\nUse the CLI with --json: adr search, adr for, adr show, adr new,\nadr note. Set ARK_AGENT=<your name> and ARK_ON_BEHALF_OF=<the user's\nemail> so your writes are attributed.\n") notes.push(`${skill} differs from adr ${o.skill?.version ?? ""}'s skill; delete it and run adr init --skill again to replace it`);
+		}
+		const old = await log.tree.read(AGENTS);
+		const text = old === null ? null : decoder.decode(old);
+		if ((text ?? "").split("\n").some((l) => l.includes(skill))) kept.push(AGENTS);
+		else {
+			let stage = true;
+			if (old !== null) {
+				const unstaged = (await log.git.unstagedPaths([AGENTS])).length > 0;
+				const untracked = (await log.git.untrackedPaths([AGENTS])).length > 0;
+				if (commitRequested && unstaged) throw new UsageError(`${AGENTS} has unstaged changes; stage or discard them, or run without --commit`);
+				if (commitRequested && untracked) throw new UsageError(`${AGENTS} is not tracked; git add it, or run without --commit`);
+				if (unstaged || untracked) {
+					stage = false;
+					notes.push(untracked ? `${AGENTS} is not tracked, so the pointer is added but not staged; review it and git add it` : `${AGENTS} had unstaged changes, so the pointer is added but not staged; review it and git add it`);
+				}
+			}
+			agents = {
+				bytes: encoder.encode(appendLine(text ?? "", agentsPointer(skill))),
+				expected: old,
+				stage
+			};
+		}
+	}
+	const at = indexPath(log.layout);
+	let indexed = false;
+	if (log.adr.index === "committed") {
+		if (await log.tree.read(at) !== null) kept.push(at);
+		else {
+			const head = await log.git.resolveCommit("HEAD");
+			const added = Object.fromEntries(files.map(([p, t]) => [p, encoder.encode(t)]));
+			const base = commitRequested ? await headTree(log.git, head) : log.tree;
+			const text = await renderDecisionIndex(log.git, {
+				layout: log.layout,
+				adr: log.adr,
+				tree: overlayTree(base, added),
+				history: head
+			});
+			if (text === null) notes.push(`${at} not updated: numbers need history in this shallow clone; run git fetch --unshallow, then adr index`);
+			else {
+				files.push([at, text]);
+				indexed = true;
+			}
+		}
+	}
+	const commit = (files.length > 0 || agents !== null) && commitRequested;
+	if (commit && (await log.git.identity() === null || await log.git.committerIdentity() === null)) throw new ConfigError("--commit needs a git identity; set git user.name and user.email");
+	const written = [];
+	let replaced = false;
+	try {
+		for (const [path, text] of files) {
+			await writeNewFile(log.git, path, encoder.encode(text));
+			written.push(path);
+		}
+		if (agents !== null) {
+			if (agents.expected === null) await writeNewFile(log.git, AGENTS, agents.bytes);
+			else await replaceFile(log.git, AGENTS, agents.bytes, { expected: agents.expected });
+			replaced = agents.expected !== null;
+			written.push(AGENTS);
+		}
+	} catch (err) {
+		const top = log.git.root ?? "";
+		const restore = replaced ? agents?.expected ?? null : null;
+		for (const path of written) if (path === AGENTS && restore !== null && agents !== null) await replaceFile(log.git, AGENTS, restore, { expected: agents.bytes }).catch(() => {});
+		else await rm(join(top, path), { force: true });
+		throw err;
+	}
+	const staged = written.filter((p) => p !== AGENTS || agents?.stage === true);
+	if (staged.length > 0) await log.git.add(staged);
+	let sha = null;
+	if (commit) {
+		const message = o.message ?? renderCommitMessage(log.adr.commitSubject, {
+			title: logFiles > 0 ? "the decision log" : "the adr agent skill",
+			vars: {
+				action: "set up",
+				id: "",
+				display: "",
+				command: "init"
+			}
+		}).message;
+		sha = await commitWithRecovery(log.git, {
+			message,
+			only: staged,
+			rerun: INIT_RERUN,
+			after: indexed ? INDEX_AFTER(root) : null
+		});
+		if (indexed) try {
+			const again = await renderDecisionIndex(log.git, {
+				layout: log.layout,
+				adr: log.adr,
+				tree: worktreeReader(log.git),
+				history: sha
+			});
+			if (again !== null) {
+				if ((await writeIndexCopy(log.git, at, again)).stage) await log.git.add([at]);
+			}
+		} catch (err) {
+			notes.push(`${at} may be stale: ${firstLine(err)}; run adr index`);
+		}
+	}
+	return {
+		format: "adr-init/v1",
+		root,
+		config,
+		written,
+		kept,
+		skill,
+		commit: sha,
+		notes
+	};
+}
+export { installDecisionHooks as a, uninstallDecisionHooks as c, decisionHookCommands as i, adrChecks as l, SKILL_MD as n, printDecisionHooks as o, addHookTrailers as r, runPreCommitHook as s, initDecisionLog as t, verifyDecisions as u };
+
+//# sourceMappingURL=init-YgW7g9Fx.js.map