mainflow 0.6.0

package/dist/dist-BktkzRuK.js

@@ -0,0 +1,1615 @@
+import { A as mainlineSchema, C as TASK_SECTIONS, D as findingSchema, E as decisionSchema, F as refMainline, I as sessionSchema, L as taskSchema, M as parseOpsLine, N as parseRef, O as formatOpsEntry, P as refExample, S as TASK_REQUIRED_SECTIONS, T as configSchema, b as SESSION_STATUS, c as FINDING_STATUS, d as ISSUE_SECTIONS, g as MERGE_STATES, h as MAINLINE_STATUS, i as DECISION_SECTIONS, j as opsEntrySchema, k as issueSchema, m as MAINLINE_SECTIONS, n as CLOSED_STATUS, o as DEFAULT_CATEGORIES, r as DECIDERS, s as FINDING_SECTIONS, t as CHECKLIST_REF, v as REF_EXAMPLES, w as WORK_STATUS, x as SLUG, y as RESERVED_HUB_NAMES } from "./dist-D2NK-QQP.js";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { parse, stringify } from "yaml";
+//#region ../core/dist/paths.js
+const DATA_DIR = ".mainflow";
+const ENTRY_DIR = /^([mtdif]\d{3})-(.+)$/;
+const isHub = (dir) => existsSync(join(dir, DATA_DIR, "config.yaml"));
+const git = (cwd, ...args) => {
+	const result = spawnSync("git", [
+		"-C",
+		cwd,
+		...args
+	], { encoding: "utf8" });
+	return result.status === 0 ? result.stdout.trim() : "";
+};
+/** The main working tree and the current working tree of the repository containing `cwd`, or null outside git. */
+function worktreesOf(cwd) {
+	const common = git(cwd, "rev-parse", "--path-format=absolute", "--git-common-dir");
+	const current = git(cwd, "rev-parse", "--show-toplevel");
+	if (!common.endsWith(`${sep}.git`) || !current) return null;
+	return {
+		main: dirname(common),
+		current
+	};
+}
+/** The branch checked out at `cwd`, or null outside git or on a detached HEAD. */
+function currentBranch(cwd) {
+	return git(cwd, "branch", "--show-current") || null;
+}
+/**
+* The hub for `cwd`: the first directory upwards holding `.mainflow/config.yaml`, except that a linked
+* worktree's checkout of a hub resolves to the same hub in the main working tree. A worktree is another
+* checkout of the same repository, so without this every worktree would write its own copy of the hub and
+* the copies would conflict on merge. A different hub nested inside a worktree (a scratch hub under tmp/,
+* say) has no counterpart in the main tree and stays as found.
+*/
+function findHubRoot(cwd) {
+	let found = null;
+	for (let dir = cwd;; dir = dirname(dir)) {
+		if (isHub(dir)) {
+			found = dir;
+			break;
+		}
+		if (dirname(dir) === dir) break;
+	}
+	const trees = worktreesOf(cwd);
+	if (!trees || trees.main === trees.current) return found;
+	const counterpart = join(trees.main, relative(trees.current, found ?? trees.current));
+	return isHub(counterpart) ? counterpart : found;
+}
+function subdirs(dir) {
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => join(dir, entry.name)).sort();
+}
+/** Split a Markdown file into its YAML front matter and the body after it. */
+function splitFrontMatter(source) {
+	const match = /^---\n([\s\S]*?)\n---\n?/.exec(source);
+	if (!match) return {
+		data: null,
+		body: source
+	};
+	return {
+		data: parse(match[1] ?? ""),
+		body: source.slice(match[0].length)
+	};
+}
+/** Find the entry directory whose name starts with `{id}-` inside `parent`. */
+function findEntryDir(parent, id) {
+	return subdirs(parent).find((dir) => ENTRY_DIR.exec(dir.split("/").at(-1) ?? "")?.[1] === id) ?? null;
+}
+/** The next free id with the given prefix, e.g. `m003` after `m001` and `m002`. */
+function nextId(prefix, existing) {
+	const max = existing.filter((id) => id.startsWith(prefix)).map((id) => Number(id.slice(prefix.length))).reduce((a, b) => Math.max(a, b), 0);
+	if (max >= 999) throw new Error(`no ${prefix} ids left after ${prefix}999`);
+	return `${prefix}${String(max + 1).padStart(3, "0")}`;
+}
+const contentHash = (text) => createHash("sha1").update(text).digest("hex");
+/** Read a UTF-8 file, or return null when it does not exist. */
+function readText(file) {
+	return existsSync(file) ? readFileSync(file, "utf8") : null;
+}
+/** List every file below `dir`, sorted, skipping dot files. */
+function listFiles(dir) {
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir, {
+		recursive: true,
+		withFileTypes: true
+	}).filter((entry) => entry.isFile() && !entry.name.startsWith(".")).map((entry) => join(entry.parentPath, entry.name)).sort();
+}
+//#endregion
+//#region ../core/dist/io.js
+var WriteError = class extends Error {};
+/** The file changed after the caller read it; the caller must reload and retry. */
+var ConflictError = class extends WriteError {};
+const LOCK_WAIT_MS = 5e3;
+const LOCK_STALE_MS = 3e4;
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+/** Run `fn` while holding the hub-wide write lock in `.mainflow/local/`. */
+function withLock(root, fn) {
+	const dir = join(root, DATA_DIR, "local");
+	mkdirSync(dir, { recursive: true });
+	const lock = join(dir, "write.lock");
+	const deadline = Date.now() + LOCK_WAIT_MS;
+	for (;;) try {
+		const fd = openSync(lock, "wx");
+		writeSync(fd, String(process.pid));
+		closeSync(fd);
+		break;
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+		if (Date.now() - statSync(lock, { throwIfNoEntry: false }).mtimeMs > LOCK_STALE_MS) {
+			rmSync(lock, { force: true });
+			continue;
+		}
+		if (Date.now() > deadline) throw new WriteError(`hub is locked by another writer (${lock}); retry in a moment`);
+		sleep(50);
+	}
+	try {
+		return fn();
+	} finally {
+		rmSync(lock, { force: true });
+	}
+}
+const today = () => (/* @__PURE__ */ new Date()).toLocaleDateString("sv-SE");
+/** Local time to the minute, the form sessions, actions and decisions use: 2026-09-24T15:30. */
+const nowMinute = () => {
+	const d = /* @__PURE__ */ new Date();
+	return `${d.toLocaleDateString("sv-SE")}T${d.toTimeString().slice(0, 5)}`;
+};
+function validate(schema, data, file) {
+	const result = schema.safeParse(data);
+	if (result.success) return result.data;
+	throw new WriteError(`${file} would become invalid: ${result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+}
+function writeAtomic(file, text) {
+	const temp = `${file}.${process.pid}.tmp`;
+	writeFileSync(temp, text);
+	renameSync(temp, file);
+}
+const toYaml = (data) => stringify(data, { lineWidth: 0 });
+function readYaml(file, schema) {
+	const text = readFileSync(file, "utf8");
+	return {
+		data: validate(schema, parse(text), file),
+		version: contentHash(text)
+	};
+}
+/** Read, mutate, validate and write back a YAML document under the hub lock. */
+function mutateYaml(root, file, schema, mutate, expectedVersion) {
+	return withLock(root, () => {
+		const text = readFileSync(file, "utf8");
+		if (expectedVersion && contentHash(text) !== expectedVersion) throw new ConflictError(`${file} changed since it was read; reload and retry`);
+		const data = validate(schema, parse(text), file);
+		mutate(data);
+		const next = validate(schema, data, file);
+		writeAtomic(file, toYaml(next));
+		return next;
+	});
+}
+const frontMatterText = (data, body) => `---\n${toYaml(data)}---\n${body}`;
+/** Read and validate the front matter of a Markdown file, with its body and content hash. */
+function readFrontMatter(file, schema) {
+	const text = readFileSync(file, "utf8");
+	const { data, body } = splitFrontMatter(text);
+	return {
+		data: validate(schema, data, file),
+		body,
+		version: contentHash(text)
+	};
+}
+/**
+* Read, mutate, validate and write back the front matter of a Markdown file. The body is kept unless
+* `mutate` returns a new one.
+*/
+function mutateFrontMatter(root, file, schema, mutate, expectedVersion) {
+	return withLock(root, () => {
+		const text = readFileSync(file, "utf8");
+		if (expectedVersion && contentHash(text) !== expectedVersion) throw new ConflictError(`${file} changed since it was read; reload and retry`);
+		const { data, body } = splitFrontMatter(text);
+		const current = validate(schema, data, file);
+		const nextBody = mutate(current, body) ?? body;
+		const next = validate(schema, current, file);
+		writeAtomic(file, frontMatterText(next, nextBody));
+		return next;
+	});
+}
+//#endregion
+//#region ../core/dist/resolve.js
+const mainlinesDir = (root) => join(root, DATA_DIR, "mainlines");
+/** The document inside each mainline and task directory: front matter for attributes, body for prose. */
+const MAINLINE_FILE = "mainline.md";
+const TASK_FILE = "task.md";
+function requireRef(input, kind) {
+	const ref = parseRef(input);
+	if (ref?.kind !== kind) throw new WriteError(`expected a ${kind} reference like ${refExample(kind)}, got "${input}"`);
+	return ref;
+}
+function mainlineDir(root, id) {
+	const dir = findEntryDir(mainlinesDir(root), id);
+	if (!dir) throw new WriteError(`mainline ${id} not found; run "mainflow status --all" to list mainlines`);
+	return dir;
+}
+function taskDir(root, mainline, task) {
+	const dir = findEntryDir(join(mainlineDir(root, mainline), "tasks"), task);
+	if (!dir) throw new WriteError(`task ${mainline}/${task} not found`);
+	return dir;
+}
+const mainlineFile = (root, id) => join(mainlineDir(root, id), MAINLINE_FILE);
+const taskFile = (root, mainline, task) => join(taskDir(root, mainline, task), TASK_FILE);
+function decisionFile(root, mainline, decision) {
+	const dir = join(mainlineDir(root, mainline), "decisions");
+	const name = existsSync(dir) ? readdirSync(dir).find((n) => n.startsWith(`${decision}-`) && n.endsWith(".md")) : void 0;
+	if (!name) throw new WriteError(`decision ${mainline}/${decision} not found`);
+	return join(dir, name);
+}
+function requireSlug(slug) {
+	if (!SLUG.test(slug)) throw new WriteError(`slug "${slug}" must be kebab-case, e.g. mainflow-rebuild`);
+}
+function requireOneOf(value, allowed, what) {
+	if (!allowed.includes(value)) throw new WriteError(`${what} "${value}" must be one of: ${allowed.join(", ")}`);
+	return value;
+}
+function readConfig(root) {
+	return readYaml(join(root, DATA_DIR, "config.yaml"), configSchema).data;
+}
+/** Entry ids (m001, t002, d003) found among the names in `dir`. */
+const idsIn = (dir) => (existsSync(dir) ? readdirSync(dir) : []).map((n) => ENTRY_DIR.exec(n)?.[1]).filter((id) => !!id);
+//#endregion
+//#region ../core/dist/refs.js
+const itemStatus = (item) => item.done ? "done" : item.dropped ? "dropped" : "open";
+/** Every reference a hub can resolve, keyed by the reference without a hub prefix. */
+function refIndex(hub) {
+	const index = /* @__PURE__ */ new Map();
+	for (const m of hub.mainlines) {
+		index.set(m.id, {
+			kind: "mainline",
+			title: m.title,
+			status: m.status,
+			mainline: m.id
+		});
+		for (const r of m.criteria) index.set(`${m.id}#${r.id}`, {
+			kind: "criterion",
+			title: r.text,
+			status: itemStatus(r),
+			mainline: m.id
+		});
+		for (const d of m.decisions) index.set(`${m.id}/${d.id}`, {
+			kind: "decision",
+			title: d.title,
+			status: d.status,
+			mainline: m.id
+		});
+		for (const t of m.tasks) {
+			index.set(`${m.id}/${t.id}`, {
+				kind: "task",
+				title: t.title,
+				status: t.status,
+				mainline: m.id
+			});
+			for (const c of t.checklist) index.set(`${m.id}/${t.id}#${c.id}`, {
+				kind: "checklistItem",
+				title: c.text,
+				status: itemStatus(c),
+				mainline: m.id
+			});
+		}
+	}
+	for (const i of hub.issues) index.set(i.id, {
+		kind: "issue",
+		title: i.title,
+		status: i.status
+	});
+	for (const f of hub.findings) index.set(f.id, {
+		kind: "finding",
+		title: f.title,
+		status: f.status
+	});
+	return index;
+}
+const isHubRoot = (dir) => existsSync(join(dir, DATA_DIR, "config.yaml"));
+/** Absolute root of a registered hub; `path` is relative to the registering hub's root. */
+const remoteRoot = (root, path) => resolve(root, path);
+/** Documents in `hub` whose links point at `hubName`'s documents; `hubName` undefined means links without a prefix. */
+function linksInto(hub, hubName) {
+	const out = [];
+	const add = (from, links) => {
+		for (const l of links ?? []) {
+			const colon = l.to.indexOf(":");
+			const prefix = colon < 0 ? void 0 : l.to.slice(0, colon);
+			const local = colon < 0 ? l.to : l.to.slice(colon + 1);
+			if (prefix === hubName || prefix === hub.config.hub && hubName === void 0) out.push({
+				to: local,
+				link: {
+					from,
+					rel: l.rel,
+					...l.note ? { note: l.note } : {}
+				}
+			});
+		}
+	};
+	for (const m of hub.mainlines) {
+		add(m.id, m.links);
+		for (const d of m.decisions) add(`${m.id}/${d.id}`, d.links);
+		for (const t of m.tasks) add(`${m.id}/${t.id}`, t.links);
+	}
+	for (const i of hub.issues) add(i.id, i.links);
+	for (const f of hub.findings) add(f.id, f.links);
+	return out;
+}
+//#endregion
+//#region ../core/dist/templates.js
+const body = (headings) => ["", ...headings.flatMap((h) => [`## ${h}`, ""])].join("\n");
+const MAINLINE_BODY = body(MAINLINE_SECTIONS);
+const TASK_BODY = body(TASK_SECTIONS);
+/** 建議 carries the recommendation while a decision is proposed; 決定 is filled once it is accepted. */
+const DECISION_BODY = body(DECISION_SECTIONS);
+const ISSUE_BODY = body(ISSUE_SECTIONS);
+const FINDING_BODY = body(FINDING_SECTIONS);
+/** The text under `## {heading}` up to the next H2, trimmed; null when the heading is missing. */
+function sectionText(markdown, heading) {
+	const lines = markdown.split("\n");
+	const start = lines.findIndex((l) => l.trim() === `## ${heading}`);
+	if (start === -1) return null;
+	const end = lines.findIndex((l, i) => i > start && l.startsWith("## "));
+	return lines.slice(start + 1, end === -1 ? void 0 : end).join("\n").trim();
+}
+/** Put `text` under `## {heading}`, replacing what was there; appends the section when it is missing. */
+function withSection(markdown, heading, text) {
+	const lines = markdown.split("\n");
+	const start = lines.findIndex((l) => l.trim() === `## ${heading}`);
+	if (start === -1) return `${markdown.trimEnd()}\n\n## ${heading}\n\n${text}\n`;
+	const found = lines.findIndex((l, i) => i > start && l.startsWith("## "));
+	const end = found === -1 ? lines.length : found;
+	const rest = lines.slice(end);
+	return [
+		...lines.slice(0, start + 1),
+		"",
+		text,
+		...rest.length ? ["", ...rest] : [""]
+	].join("\n");
+}
+//#endregion
+//#region ../core/dist/load.js
+function loadHub(root, options = {}) {
+	const problems = [];
+	const warnings = [];
+	/** References checked once everything they may point at is loaded */
+	const pending = [];
+	/** Documents whose file is there but failed to load; references into them are not reported twice */
+	const unreadable = /* @__PURE__ */ new Set();
+	const idOf = (path) => ENTRY_DIR.exec(path.split("/").at(-1)?.replace(/\.md$/, "") ?? "")?.[1];
+	const dataDir = join(root, DATA_DIR);
+	const rel = (path) => relative(root, path);
+	const read = (file, schema, raw) => {
+		let data = raw;
+		if (data === void 0) try {
+			data = parse(readText(file) ?? "");
+		} catch (error) {
+			problems.push({
+				file: rel(file),
+				field: "",
+				message: `cannot parse YAML: ${error.message}`
+			});
+			return null;
+		}
+		const result = schema.safeParse(data);
+		if (result.success) return result.data;
+		for (const issue of result.error.issues) problems.push({
+			file: rel(file),
+			field: issue.path.join("."),
+			message: issue.message
+		});
+		return null;
+	};
+	const checkDirName = (dir, id) => {
+		const match = ENTRY_DIR.exec(dir.split("/").at(-1) ?? "");
+		if (!match || match[1] !== id || !SLUG.test(match[2] ?? "")) problems.push({
+			file: rel(dir),
+			field: "",
+			message: `directory name must be "${id}-{slug}" in kebab-case`
+		});
+	};
+	const config = read(join(dataDir, "config.yaml"), configSchema);
+	if (!config) throw new HubError("invalid config.yaml", problems);
+	if (config.formatVersion !== 2) throw new HubError(config.formatVersion < 2 ? `data format version ${config.formatVersion} is older than this CLI's (2); run "mainflow migrate --dry-run" to preview the conversion, then "mainflow migrate"` : `data format version ${config.formatVersion} is newer than this CLI supports (2); install the matching mainflow version in this hub`, problems);
+	const categories = /* @__PURE__ */ new Set([...DEFAULT_CATEGORIES, ...config.categories ?? []]);
+	/** Read a Markdown document's front matter against `schema`, with the attributes every document shares. */
+	const readDocument = (file, schema) => {
+		const text = readText(file);
+		if (text === null) {
+			problems.push({
+				file: rel(file),
+				field: "",
+				message: "file is missing"
+			});
+			return null;
+		}
+		let split;
+		try {
+			split = splitFrontMatter(text);
+		} catch (error) {
+			problems.push({
+				file: rel(file),
+				field: "",
+				message: `cannot parse front matter: ${error.message}`
+			});
+			return null;
+		}
+		const doc = read(file, schema, split.data);
+		if (!doc) return null;
+		if (doc.category && !categories.has(doc.category)) problems.push({
+			file: rel(file),
+			field: "category",
+			message: `category "${doc.category}" is not one of ${[...categories].join(", ")}; add it under categories in config.yaml or pick one of these`
+		});
+		const updated = new Date(statSync(file).mtimeMs).toLocaleDateString("sv-SE");
+		return {
+			...doc,
+			file: rel(file),
+			body: split.body,
+			version: contentHash(text),
+			updated
+		};
+	};
+	const mainlines = [];
+	for (const mainlineDir of subdirs(join(dataDir, "mainlines"))) {
+		const mainline = readDocument(join(mainlineDir, MAINLINE_FILE), mainlineSchema);
+		if (!mainline) {
+			const id = idOf(mainlineDir);
+			if (id) unreadable.add(id);
+			continue;
+		}
+		checkDirName(mainlineDir, mainline.id);
+		const decisions = [];
+		const decisionsDir = join(mainlineDir, "decisions");
+		for (const name of existsSync(decisionsDir) ? readdirSync(decisionsDir).filter((n) => n.endsWith(".md")).sort() : []) {
+			const file = join(decisionsDir, name);
+			const decision = readDocument(file, decisionSchema);
+			if (!decision) unreadable.add(`${mainline.id}/${idOf(file)}`);
+			if (decision) {
+				checkDirName(file.replace(/\.md$/, ""), decision.id);
+				decisions.push(decision);
+			}
+		}
+		const tasks = [];
+		for (const taskDir of subdirs(join(mainlineDir, "tasks"))) {
+			const task = readDocument(join(taskDir, TASK_FILE), taskSchema);
+			if (!task) {
+				unreadable.add(`${mainline.id}/${idOf(taskDir)}`);
+				continue;
+			}
+			checkDirName(taskDir, task.id);
+			if (task.repo && !(task.repo in config.repos)) problems.push({
+				file: task.file,
+				field: "repo",
+				message: `repo "${task.repo}" is not listed in config.yaml`
+			});
+			tasks.push({
+				...task,
+				dir: rel(taskDir),
+				artifacts: listFiles(join(taskDir, "artifacts")).map(rel)
+			});
+		}
+		problems.push(...contentGaps(mainline, tasks));
+		const taskIds = new Set(tasks.map((t) => t.id));
+		const criterionIds = new Set(mainline.criteria.map((c) => c.id));
+		const itemRefs = new Set(tasks.flatMap((t) => t.checklist.map((c) => `${mainline.id}/${t.id}#${c.id}`)));
+		for (const task of tasks) {
+			if (task.parent && !taskIds.has(task.parent)) problems.push({
+				file: task.file,
+				field: "parent",
+				message: `parent task ${task.parent} does not exist`
+			});
+			task.dependsOn?.forEach((dep, i) => {
+				if (!taskIds.has(dep)) problems.push({
+					file: task.file,
+					field: `dependsOn.${i}`,
+					message: `task ${dep} does not exist`
+				});
+			});
+			task.checklist.forEach((item, i) => {
+				item.serves?.forEach((r, j) => {
+					if (!criterionIds.has(r)) problems.push({
+						file: task.file,
+						field: `checklist.${i}.serves.${j}`,
+						message: `criterion ${mainline.id}#${r} does not exist`
+					});
+				});
+			});
+		}
+		for (const decision of decisions) decision.affects?.forEach((ref, i) => {
+			if (!(ref.includes("#") ? itemRefs.has(ref) : taskIds.has(ref.split("/")[1] ?? "") && ref.startsWith(`${mainline.id}/`))) problems.push({
+				file: decision.file,
+				field: `affects.${i}`,
+				message: `${ref} is not a task or checklist item of ${mainline.id}`
+			});
+		});
+		mainlines.push({
+			...mainline,
+			dir: rel(mainlineDir),
+			views: listFiles(join(mainlineDir, "views")).map(rel),
+			decisions,
+			tasks
+		});
+	}
+	const hubDocs = (dir, schema) => (existsSync(dir) ? readdirSync(dir).filter((n) => n.endsWith(".md")).sort() : []).flatMap((name) => {
+		const file = join(dir, name);
+		const doc = readDocument(file, schema);
+		if (!doc) {
+			const id = idOf(file);
+			if (id) unreadable.add(id);
+			return [];
+		}
+		checkDirName(file.replace(/\.md$/, ""), doc.id);
+		return [doc];
+	});
+	const hubIssues = hubDocs(join(dataDir, "issues"), issueSchema);
+	const taskRefs = new Set(mainlines.flatMap((m) => m.tasks.map((t) => `${m.id}/${t.id}`)));
+	for (const issue of hubIssues) if (issue.plannedIn && !taskRefs.has(issue.plannedIn)) problems.push({
+		file: issue.file,
+		field: "plannedIn",
+		message: `task ${issue.plannedIn} does not exist`
+	});
+	const findings = hubDocs(join(dataDir, "findings"), findingSchema);
+	const ops = [];
+	const opsPath = join(dataDir, "ops");
+	for (const name of existsSync(opsPath) ? readdirSync(opsPath).filter((n) => n.endsWith(".log")).sort() : []) readFileSync(join(opsPath, name), "utf8").split("\n").forEach((line, index) => {
+		if (!line.trim()) return;
+		const entry = parseOpsLine(line);
+		if (entry?.ref) pending.push({
+			ref: entry.ref,
+			file: rel(join(opsPath, name)),
+			field: `line ${index + 1}`
+		});
+		if (entry) ops.push(entry);
+		else problems.push({
+			file: rel(join(opsPath, name)),
+			field: `line ${index + 1}`,
+			message: "expected \"YYYY-MM-DDTHH:mm | target | operation | result [| ref]\""
+		});
+	});
+	const remotes = options.remotes === false ? [] : loadRemotes(root, config, problems, warnings);
+	checkReferences({
+		config,
+		mainlines,
+		issues: hubIssues,
+		findings,
+		remotes,
+		pending,
+		unreadable,
+		problems
+	});
+	return {
+		root,
+		config,
+		mainlines,
+		issues: hubIssues,
+		findings,
+		ops,
+		problems,
+		warnings,
+		remotes
+	};
+}
+/** Load every hub registered in config.yaml, read-only and without its own remotes. */
+function loadRemotes(root, config, problems, warnings) {
+	const file = `${DATA_DIR}/config.yaml`;
+	return Object.entries(config.hubs ?? {}).map(([name, path]) => {
+		const remote = {
+			name,
+			path,
+			root: remoteRoot(root, path)
+		};
+		if (name === config.hub) {
+			problems.push({
+				file,
+				field: `hubs.${name}`,
+				message: `"${name}" is this hub's own name; references without a prefix already point here`
+			});
+			return {
+				...remote,
+				unavailable: "this hub"
+			};
+		}
+		if (!isHubRoot(remote.root)) {
+			warnings.push({
+				file,
+				field: `hubs.${name}`,
+				message: `hub "${name}" is not at ${path} on this machine; references into it are not checked`
+			});
+			return {
+				...remote,
+				unavailable: `not found at ${path}`
+			};
+		}
+		try {
+			const hub = loadHub(remote.root, { remotes: false });
+			if (hub.config.hub !== name) {
+				problems.push({
+					file,
+					field: `hubs.${name}`,
+					message: `${path} holds hub "${hub.config.hub}", not "${name}"; register it under its own name`
+				});
+				return {
+					...remote,
+					unavailable: `holds hub "${hub.config.hub}"`
+				};
+			}
+			return {
+				...remote,
+				hub
+			};
+		} catch (error) {
+			warnings.push({
+				file,
+				field: `hubs.${name}`,
+				message: `hub "${name}" at ${path} cannot be loaded: ${error.message}`
+			});
+			return {
+				...remote,
+				unavailable: error.message
+			};
+		}
+	});
+}
+/**
+* Every reference in a document must point at something that exists: in this hub, or in a registered
+* hub that is on this machine. A reference into a registered hub that is missing here is left unchecked,
+* since another machine may not keep every hub; the missing hub itself is reported once as a warning.
+* Links are for relations across mainlines; inside one mainline, parent, dependsOn and affects say it.
+*/
+function checkReferences(input) {
+	const { config, mainlines, issues, findings, remotes, pending, unreadable, problems } = input;
+	/** A target inside a document that failed to load: its schema problem is already reported. */
+	const inUnreadable = (target) => [
+		target,
+		target.split(/[#/]/)[0],
+		target.split("#")[0]
+	].some((t) => unreadable.has(t));
+	const local = refIndex({
+		mainlines,
+		issues,
+		findings
+	});
+	const remoteIndex = new Map(remotes.map((r) => [r.name, r.hub ? refIndex(r.hub) : null]));
+	/** The document's own mainline, when it sits in one; links may not point back into it. */
+	const add = (file, doc, self, mainline) => {
+		if (doc.origin) pending.push({
+			ref: doc.origin,
+			file,
+			field: "origin"
+		});
+		doc.links?.forEach((link, i) => {
+			pending.push({
+				ref: link.to,
+				file,
+				field: `links.${i}.to`
+			});
+			const parsed = parseRef(link.to);
+			const here = parsed && (parsed.hub === void 0 || parsed.hub === config.hub);
+			if (!parsed || !here) return;
+			if (link.to.slice(link.to.indexOf(":") + 1) === self) problems.push({
+				file,
+				field: `links.${i}.to`,
+				message: "a document cannot link to itself"
+			});
+			else if (mainline && refMainline(parsed) === mainline) problems.push({
+				file,
+				field: `links.${i}.to`,
+				message: `${link.to} is inside ${mainline}; links are for other mainlines, so use parent, dependsOn or affects within one`
+			});
+		});
+	};
+	const items = (file, field, list) => list.forEach((item, i) => item.supersededBy && pending.push({
+		ref: item.supersededBy,
+		file,
+		field: `${field}.${i}.supersededBy`
+	}));
+	for (const m of mainlines) {
+		add(m.file, m, m.id, m.id);
+		items(m.file, "criteria", m.criteria);
+		for (const d of m.decisions) add(d.file, d, `${m.id}/${d.id}`, m.id);
+		for (const t of m.tasks) {
+			add(t.file, t, `${m.id}/${t.id}`, m.id);
+			items(t.file, "checklist", t.checklist);
+		}
+	}
+	for (const i of issues) add(i.file, i, i.id);
+	for (const f of findings) add(f.file, f, f.id);
+	for (const p of pending) {
+		const parsed = parseRef(p.ref);
+		if (!parsed) continue;
+		const target = p.ref.slice(p.ref.indexOf(":") + 1);
+		if (parsed.hub === void 0 || parsed.hub === config.hub) {
+			if (!local.has(target) && !inUnreadable(target)) problems.push({
+				file: p.file,
+				field: p.field,
+				message: `${p.ref} does not exist in this hub`
+			});
+			continue;
+		}
+		if (!remoteIndex.has(parsed.hub)) {
+			problems.push({
+				file: p.file,
+				field: p.field,
+				message: `hub "${parsed.hub}" is not registered; run "mainflow hub add ${parsed.hub} <path>"`
+			});
+			continue;
+		}
+		const index = remoteIndex.get(parsed.hub);
+		if (index && !index.has(target)) problems.push({
+			file: p.file,
+			field: p.field,
+			message: `${p.ref} does not exist in hub "${parsed.hub}"`
+		});
+	}
+}
+const isOpen = (kind, status) => !CLOSED_STATUS[kind].includes(status);
+/**
+* What a reader without the conversation needs to pick the work up: every open task says what it is for
+* and when it is done, and every open criterion or item says what has to be true to check it. Closed
+* entries are skipped, because their evidence already says what was done. Ids must also be unique within
+* a list, since the files are edited directly and nothing else allocates them.
+*/
+function contentGaps(mainline, tasks) {
+	const gaps = [];
+	const list = (file, field, items, open) => {
+		const seen = /* @__PURE__ */ new Set();
+		items.forEach((item, i) => {
+			if (seen.has(item.id)) gaps.push({
+				file,
+				field: `${field}.${i}.id`,
+				message: `${item.id} is used twice; give it the next free id`
+			});
+			seen.add(item.id);
+			if (open && !item.done && !item.dropped && !item.doneWhen?.trim()) gaps.push({
+				file,
+				field: `${field}.${i}.doneWhen`,
+				message: `${item.id} is open and needs doneWhen: what has to be true to check it`
+			});
+		});
+	};
+	const mainlineOpen = isOpen("mainline", mainline.status);
+	list(mainline.file, "criteria", mainline.criteria, mainlineOpen);
+	for (const task of tasks) {
+		const open = mainlineOpen && isOpen("task", task.status);
+		list(task.file, "checklist", task.checklist, open);
+		if (!open) continue;
+		for (const section of TASK_REQUIRED_SECTIONS) if (!sectionText(task.body, section)) gaps.push({
+			file: task.file,
+			field: `## ${section}`,
+			message: `the task is open and needs text under "## ${section}"`
+		});
+	}
+	return gaps;
+}
+var HubError = class extends Error {
+	problems;
+	constructor(message, problems) {
+		super(message);
+		this.problems = problems;
+	}
+};
+//#endregion
+//#region ../core/dist/hub-items.js
+const issuesDir = (root) => join(root, DATA_DIR, "issues");
+const findingsDir = (root) => join(root, DATA_DIR, "findings");
+const opsDir = (root) => join(root, DATA_DIR, "ops");
+function entryFile(dir, id, what) {
+	const name = existsSync(dir) ? readdirSync(dir).find((n) => n.startsWith(`${id}-`) && n.endsWith(".md")) : void 0;
+	if (!name) throw new WriteError(`${what} ${id} not found`);
+	return join(dir, name);
+}
+/**
+* Any reference the schema accepts must also point at something that exists. A reference into another
+* hub only needs that hub registered here; check verifies the target when that hub is on this machine.
+*/
+function requireExisting(root, ref) {
+	const parsed = parseRef(ref);
+	if (!parsed) throw new WriteError(`"${ref}" is not a reference like ${REF_EXAMPLES}`);
+	const config = readConfig(root);
+	if (parsed.hub !== void 0 && parsed.hub !== config.hub) {
+		if (!config.hubs?.[parsed.hub]) throw new WriteError(`hub "${parsed.hub}" is not registered; run "mainflow hub add ${parsed.hub} <path>" first`);
+		return;
+	}
+	switch (parsed.kind) {
+		case "issue":
+			entryFile(issuesDir(root), parsed.issue, "issue");
+			return;
+		case "finding":
+			entryFile(findingsDir(root), parsed.finding, "finding");
+			return;
+		default:
+			mainlineDir(root, parsed.mainline);
+			if ("task" in parsed) taskDir(root, parsed.mainline, parsed.task);
+			if (parsed.kind === "decision") decisionFile(root, parsed.mainline, parsed.decision);
+	}
+}
+function createIssue(root, input) {
+	requireSlug(input.slug);
+	if (input.origin) requireExisting(root, input.origin);
+	return withLock(root, () => {
+		const dir = issuesDir(root);
+		mkdirSync(dir, { recursive: true });
+		const id = nextId("i", idsIn(dir));
+		const issue = validate(issueSchema, {
+			id,
+			title: input.title,
+			status: "open",
+			created: today(),
+			...input.origin ? { origin: input.origin } : {}
+		}, "issue");
+		const file = join(dir, `${id}-${input.slug}.md`);
+		writeAtomic(file, frontMatterText(issue, ISSUE_BODY));
+		return {
+			id,
+			file
+		};
+	});
+}
+/** Schedule an issue into the task that will carry it out. */
+function planIssue(root, id, taskRef, expectedVersion) {
+	const ref = requireRef(taskRef, "task");
+	taskDir(root, ref.mainline, ref.task);
+	return mutateFrontMatter(root, entryFile(issuesDir(root), id, "issue"), issueSchema, (i) => {
+		i.status = "planned";
+		i.plannedIn = taskRef;
+	}, expectedVersion);
+}
+function closeIssue(root, id, resolution, expectedVersion) {
+	if (!resolution) throw new WriteError(`closing ${id} needs what closed it, e.g. --by "mainflow@3fdd5ac" or --by "不再需要"`);
+	return mutateFrontMatter(root, entryFile(issuesDir(root), id, "issue"), issueSchema, (i) => {
+		i.status = "closed";
+		i.resolution = resolution;
+		i.closedAt ??= today();
+	}, expectedVersion);
+}
+function reopenIssue(root, id, expectedVersion) {
+	return mutateFrontMatter(root, entryFile(issuesDir(root), id, "issue"), issueSchema, (i) => {
+		i.status = "open";
+		delete i.plannedIn;
+		delete i.resolution;
+		delete i.closedAt;
+	}, expectedVersion);
+}
+/** Archive or unarchive an issue; the status stays as it is, so a closed issue is visible until archived. */
+function setIssueArchived(root, id, archived, expectedVersion) {
+	return mutateFrontMatter(root, entryFile(issuesDir(root), id, "issue"), issueSchema, (i) => {
+		if (archived) i.archivedAt ??= today();
+		else delete i.archivedAt;
+	}, expectedVersion);
+}
+function createFinding(root, input) {
+	requireSlug(input.slug);
+	if (input.origin) requireExisting(root, input.origin);
+	return withLock(root, () => {
+		const dir = findingsDir(root);
+		mkdirSync(dir, { recursive: true });
+		const id = nextId("f", idsIn(dir));
+		const finding = validate(findingSchema, {
+			id,
+			title: input.title,
+			status: "valid",
+			created: today(),
+			...input.origin ? { origin: input.origin } : {},
+			...input.labels?.length ? { labels: input.labels } : {}
+		}, "finding");
+		const file = join(dir, `${id}-${input.slug}.md`);
+		writeAtomic(file, frontMatterText(finding, FINDING_BODY));
+		return {
+			id,
+			file
+		};
+	});
+}
+function setFindingStatus(root, id, status, expectedVersion) {
+	const value = requireOneOf(status, FINDING_STATUS, "finding status");
+	return mutateFrontMatter(root, entryFile(findingsDir(root), id, "finding"), findingSchema, (f) => {
+		f.status = value;
+		if (value === "obsolete") f.closedAt ??= today();
+		else delete f.closedAt;
+	}, expectedVersion);
+}
+/** Archive or unarchive a finding; the status stays as it is, so an obsolete finding is visible until archived. */
+function setFindingArchived(root, id, archived, expectedVersion) {
+	return mutateFrontMatter(root, entryFile(findingsDir(root), id, "finding"), findingSchema, (f) => {
+		if (archived) f.archivedAt ??= today();
+		else delete f.archivedAt;
+	}, expectedVersion);
+}
+/** Append one external operation to ops/{YYYY-MM}.log; the log is never rewritten. */
+function appendOps(root, input) {
+	if (input.ref) requireExisting(root, input.ref);
+	const entry = validate(opsEntrySchema, {
+		...input,
+		at: input.at ?? nowMinute()
+	}, "ops entry");
+	for (const field of [
+		"target",
+		"operation",
+		"result"
+	]) if (entry[field].includes(" | ")) throw new WriteError(`${field} cannot contain " | ", the ops log's separator`);
+	return withLock(root, () => {
+		mkdirSync(opsDir(root), { recursive: true });
+		appendFileSync(join(opsDir(root), `${entry.at.slice(0, 7)}.log`), `${formatOpsEntry(entry)}\n`);
+		return entry;
+	});
+}
+//#endregion
+//#region ../core/dist/briefing.js
+function describe(root, ref) {
+	const parsed = parseRef(ref);
+	if (parsed?.kind !== "checklistItem") return null;
+	try {
+		const mainline = readFrontMatter(mainlineFile(root, parsed.mainline), mainlineSchema).data;
+		const task = readFrontMatter(taskFile(root, parsed.mainline, parsed.task), taskSchema).data;
+		const item = task.checklist.find((c) => c.id === parsed.item);
+		if (!item) return null;
+		return {
+			ref,
+			text: item.text,
+			checked: item.done,
+			where: `${mainline.id} ${mainline.title} › ${task.id} ${task.title}`
+		};
+	} catch {
+		return null;
+	}
+}
+/** Problems in a session's queue that the executor should fix before going on, each with the command that fixes it. */
+function queueWarnings(root, session, cli) {
+	const warnings = [];
+	const doing = session.actions.filter((a) => a.status === "doing");
+	if (doing.length > 1) warnings.push(`同時有 ${doing.length} 個進行中的行動（${doing.map((a) => a.id).join("、")}）。一次只推進一個，其餘改回 todo。`);
+	for (const action of doing) {
+		const served = action.serves.map((ref) => describe(root, ref));
+		if (served.some((s) => s === null)) warnings.push(`${action.id} 服務的項目有的已不存在，用 ${cli} action set ${action.id} --serves <m/t#c> 改正。`);
+		else if (served.length > 0 && served.every((s) => s.checked)) warnings.push(`${action.id} 服務的項目都已勾選。做完了就執行 ${cli} action set ${action.id} --status done。`);
+	}
+	const next = session.actions.find((a) => a.status === "todo");
+	if (doing.length === 0 && next) warnings.push(`下一個行動是 ${next.id}。開始前先執行 ${cli} action set ${next.id} --status doing。`);
+	return warnings;
+}
+const current = (session) => session.actions.find((a) => a.status === "doing");
+const servedLine = (root, action) => action.serves.map((ref) => {
+	const s = describe(root, ref);
+	return s ? `${ref} ${s.text}（${s.where}）` : `${ref}（找不到這個項目）`;
+}).join("；") || "沒有指定服務的 checklist 項目";
+/** Full briefing for the start of a session, after resuming, clearing or compacting. */
+function sessionBriefing(root, session, options) {
+	const { cli } = options;
+	const lines = [`[mainflow] 這場會話的 id 是 ${session.id}${options.envNote ? `（${options.envNote}）` : ""}。`];
+	const doing = current(session);
+	const upcoming = session.actions.filter((a) => a.status === "todo").slice(0, 3);
+	if (session.actions.length === 0) {
+		const active = loadHub(root).mainlines.filter((m) => !m.archivedAt && (m.status === "active" || m.status === "planning"));
+		lines.push("這場會話還沒有行動。");
+		if (active.length > 0) {
+			lines.push("進行中的主脈絡：");
+			for (const m of active) lines.push(`- ${m.id} ${m.title}`);
+			lines.push(`要推進其中一個時，先用 ${cli} status 與它的任務 checklist 決定要做什麼，再列出行動。`);
+		}
+	} else {
+		lines.push(doing ? `目前行動：${doing.id} ${doing.do}` : "目前沒有進行中的行動。");
+		if (doing) lines.push(`服務：${servedLine(root, doing)}`);
+		if (upcoming.length > 0) lines.push(`接下來：${upcoming.map((a) => `${a.id} ${a.do}`).join("、")}`);
+	}
+	const warnings = queueWarnings(root, session, cli);
+	if (warnings.length > 0) lines.push("需要處理：", ...warnings.map((w) => `- ${w}`));
+	lines.push("工作方式：", `- 開始一件新工作前，先列進佇列：${cli} action add "<做法>" --serves <m/t#c>。`, `- 開始做標 doing，做完標 done：${cli} action set <a編號> --status doing。`, `- 勾選 checklist 要附證據：${cli} item check <m/t#c> --evidence <commit、檔案:行號或指令輸出>。`, `- 內容直接寫進檔案：意圖或需求寫進 mainline.md 的內文，任務的目標與完成定義寫進 task.md，選擇寫成決策（${cli} new decision <m> <slug> --title <標題> 建檔後再寫內文）。`, `- 改完 .mainflow/ 的檔案跑 ${cli} check，把它列出的問題修到沒有。`, "- 用完其他 skill 或子流程後，回到上面的目前行動再繼續。", "- 要開主脈絡、拆任務、記決策、延後或收尾時，用 mainflow skill，它依序帶過並告訴你資訊該寫在哪裡。");
+	return lines.join("\n");
+}
+/** One or two lines for every user turn; null when the session has no actions to anchor to. */
+function turnReminder(root, session, options) {
+	if (session.actions.length === 0) return null;
+	const doing = current(session);
+	const open = session.actions.filter((a) => a.status === "todo" || a.status === "doing");
+	return [doing ? `[mainflow] 目前行動 ${doing.id} ${doing.do}，服務 ${doing.serves.join("、") || "（未指定）"}。這一輪的工作若不屬於它，先調整佇列再做。` : open.length === 0 ? `[mainflow] ${session.id} 的行動都已結束。繼續工作前先用 ${options.cli} action add 列出下一個行動。` : `[mainflow] ${session.id} 目前沒有進行中的行動。`, ...queueWarnings(root, session, options.cli).map((w) => `- ${w}`)].join("\n");
+}
+//#endregion
+//#region ../core/dist/sessions.js
+const sessionsDir = (root) => join(root, DATA_DIR, "local", "sessions");
+const sessionFile = (root, id) => join(sessionsDir(root), `${id}.yaml`);
+/** Read every session under `.mainflow/local/sessions/`; sessions are local and never version-controlled. */
+function loadSessions(root) {
+	const dir = sessionsDir(root);
+	const sessions = [];
+	const problems = [];
+	let names = [];
+	try {
+		names = readdirSync(dir).filter((n) => n.endsWith(".yaml")).sort();
+	} catch {
+		return {
+			sessions,
+			problems
+		};
+	}
+	for (const name of names) {
+		const file = join(dir, name);
+		let data;
+		try {
+			data = parse(readText(file) ?? "");
+		} catch (error) {
+			problems.push({
+				file: relative(root, file),
+				field: "",
+				message: `cannot parse YAML: ${error.message}`
+			});
+			continue;
+		}
+		const result = sessionSchema.safeParse(data);
+		if (result.success) sessions.push(result.data);
+		else for (const i of result.error.issues) problems.push({
+			file: relative(root, file),
+			field: i.path.join("."),
+			message: i.message
+		});
+	}
+	return {
+		sessions,
+		problems
+	};
+}
+function readSession(root, id) {
+	const file = sessionFile(root, id);
+	return existsSync(file) ? readYaml(file, sessionSchema).data : null;
+}
+function requireSession(root, id) {
+	const file = sessionFile(root, id);
+	if (!existsSync(file)) throw new WriteError(`session ${id} not found; start one with "mainflow session start"`);
+	return file;
+}
+/** Split `claude-code-1a2b3c4d#a003` into its session and action ids. */
+function splitActionRef(ref) {
+	const hash = ref.lastIndexOf("#");
+	const action = ref.slice(hash + 1);
+	if (hash <= 0 || !/^a\d{3}$/.test(action)) throw new WriteError(`expected an action reference like claude-code-1a2b3c4d#a003, got "${ref}"`);
+	return {
+		session: ref.slice(0, hash),
+		action
+	};
+}
+/** Every served checklist item must exist, so a session never points at work that is not in a mainline. */
+function requireServes(root, serves) {
+	for (const ref of serves) {
+		const parsed = parseRef(ref);
+		if (!CHECKLIST_REF.test(ref) || parsed?.kind !== "checklistItem") throw new WriteError(`--serves takes checklist references like m001/t002#c003, got "${ref}"`);
+		if (!readFrontMatter(taskFile(root, parsed.mainline, parsed.task), taskSchema).data.checklist.some((c) => c.id === parsed.item)) throw new WriteError(`checklist item ${ref} not found`);
+	}
+}
+/**
+* Start a session. Taking over from another session copies its unfinished actions into this one and marks
+* the other session handed-off, so the queue continues where it stopped.
+*/
+function startSession(root, input) {
+	const id = input.id ?? `${input.agent}-${randomBytes(4).toString("hex")}`;
+	if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) throw new WriteError(`session id "${id}" must be lowercase letters, digits and hyphens`);
+	return withLock(root, () => {
+		const file = sessionFile(root, id);
+		if (existsSync(file)) throw new WriteError(`session ${id} already exists`);
+		if (input.delegatedFrom) requireSession(root, input.delegatedFrom);
+		let carried = [];
+		if (input.handoffFrom) {
+			const previousFile = requireSession(root, input.handoffFrom);
+			const previous = readYaml(previousFile, sessionSchema).data;
+			carried = previous.actions.filter((a) => a.status === "todo" || a.status === "doing").map((a, i) => ({
+				...a,
+				id: `a${String(i + 1).padStart(3, "0")}`
+			}));
+			writeAtomic(previousFile, toYaml(validate(sessionSchema, {
+				...previous,
+				status: "handed-off"
+			}, previousFile)));
+		}
+		const session = validate(sessionSchema, {
+			id,
+			agent: input.agent,
+			status: "active",
+			started: nowMinute(),
+			delegatedFrom: input.delegatedFrom ?? null,
+			handoffFrom: input.handoffFrom ?? null,
+			cwd: input.cwd,
+			actions: carried
+		}, file);
+		mkdirSync(sessionsDir(root), { recursive: true });
+		writeAtomic(file, toYaml(session));
+		return session;
+	});
+}
+/**
+* Start the session unless it already exists. An existing paused or ended session becomes active again, and
+* an archived one comes back into view, since resumed work should not stay hidden.
+*/
+function ensureSession(root, input) {
+	const existing = readSession(root, input.id);
+	if (!existing) return {
+		session: startSession(root, input),
+		created: true
+	};
+	if (existing.status === "active" && !existing.archivedAt) return {
+		session: existing,
+		created: false
+	};
+	return {
+		session: mutateYaml(root, requireSession(root, input.id), sessionSchema, (s) => {
+			s.status = "active";
+			delete s.archivedAt;
+		}),
+		created: false
+	};
+}
+/** Where a session's transcript is on disk: a platform records an absolute path, a hub may record one relative to its root. */
+function transcriptPath(root, transcript) {
+	return isAbsolute(transcript) ? transcript : join(root, transcript);
+}
+function setSessionInfo(root, id, info) {
+	return mutateYaml(root, requireSession(root, id), sessionSchema, (s) => {
+		for (const [key, value] of Object.entries(info)) if (value !== void 0 && value !== null && value !== "") s[key] = value;
+	});
+}
+function setSessionStatus(root, id, status) {
+	const value = requireOneOf(status, SESSION_STATUS, "session status");
+	return mutateYaml(root, requireSession(root, id), sessionSchema, (s) => {
+		s.status = value;
+	});
+}
+/** Archive or unarchive a session; the status stays as it is, so an ended session is visible until archived. */
+function setSessionArchived(root, id, archived) {
+	return mutateYaml(root, requireSession(root, id), sessionSchema, (s) => {
+		if (archived) s.archivedAt ??= today();
+		else delete s.archivedAt;
+	});
+}
+function place(actions, action, before) {
+	if (!before) {
+		actions.push(action);
+		return;
+	}
+	const index = actions.findIndex((a) => a.id === before);
+	if (index < 0) throw new WriteError(`--before ${before} is not an action in this session`);
+	actions.splice(index, 0, action);
+}
+function addAction(root, sessionId, input) {
+	requireServes(root, input.serves);
+	let created = "";
+	mutateYaml(root, requireSession(root, sessionId), sessionSchema, (s) => {
+		created = nextId("a", s.actions.map((a) => a.id));
+		place(s.actions, {
+			id: created,
+			do: input.do,
+			status: "todo",
+			serves: input.serves
+		}, input.before);
+	});
+	return `${sessionId}#${created}`;
+}
+function updateAction(root, ref, patch) {
+	const { session, action } = splitActionRef(ref);
+	const status = patch.status === void 0 ? void 0 : requireOneOf(patch.status, WORK_STATUS, "action status");
+	if (patch.serves) requireServes(root, patch.serves);
+	if (patch.before === action) throw new WriteError(`action ${action} cannot be placed before itself`);
+	let updated;
+	mutateYaml(root, requireSession(root, session), sessionSchema, (s) => {
+		const index = s.actions.findIndex((a) => a.id === action);
+		if (index < 0) throw new WriteError(`action ${ref} not found`);
+		const [current] = s.actions.splice(index, 1);
+		const next = {
+			...current,
+			...status && { status },
+			...patch.do && { do: patch.do },
+			...patch.serves && { serves: patch.serves },
+			...patch.note && { note: patch.note }
+		};
+		if (status === "doing" && current.status !== "doing") {
+			next.startedAt = nowMinute();
+			delete next.doneAt;
+		}
+		if ((status === "done" || status === "dropped") && current.status !== status) next.doneAt = nowMinute();
+		if (status === "todo") {
+			delete next.startedAt;
+			delete next.doneAt;
+		}
+		updated = next;
+		if (patch.before) place(s.actions, next, patch.before);
+		else s.actions.splice(index, 0, next);
+	});
+	return updated;
+}
+//#endregion
+//#region ../core/dist/write.js
+function checkTaskLinks(root, mainline, task) {
+	if (task.repo && !(task.repo in readConfig(root).repos)) throw new WriteError(`repo "${task.repo}" is not listed in .mainflow/config.yaml; add it under repos first`);
+	if (task.parent) {
+		if (task.parent === task.id) throw new WriteError(`task ${task.id} cannot be its own parent`);
+		taskDir(root, mainline, task.parent);
+	}
+}
+function initHub(root, hub) {
+	const dataDir = join(root, DATA_DIR);
+	if (existsSync(join(dataDir, "config.yaml"))) throw new WriteError(`${dataDir} already holds a hub`);
+	const config = validate(configSchema, {
+		hub,
+		formatVersion: 2,
+		repos: {}
+	}, "config.yaml");
+	mkdirSync(join(dataDir, "mainlines"), { recursive: true });
+	writeFileSync(join(dataDir, "config.yaml"), toYaml(config));
+	writeFileSync(join(dataDir, ".gitignore"), "local/\n**/scratch/\n!ops/*.log\n");
+	return dataDir;
+}
+/** Register a repository the hub's tasks may point at; `path` is relative to the hub root. */
+function addRepo(root, name, path) {
+	requireSlug(name);
+	const target = resolve(root, path);
+	if (!existsSync(target) || !statSync(target).isDirectory()) throw new WriteError(`repo path ${path} does not exist from the hub root (${target})`);
+	mutateYaml(root, join(root, DATA_DIR, "config.yaml"), configSchema, (c) => {
+		if (c.repos[name] !== void 0 && c.repos[name] !== path) throw new WriteError(`repo "${name}" is already registered as ${c.repos[name]}`);
+		c.repos[name] = path;
+	});
+	return name;
+}
+/**
+* Register another hub whose documents this hub's references may point at, as `{name}:m001`. `path` is
+* relative to this hub's root and must hold that hub, registered under its own name, so a reference reads
+* the same in every hub that mentions it.
+*/
+function addHub(root, name, path) {
+	requireSlug(name);
+	if (RESERVED_HUB_NAMES.includes(name)) throw new WriteError(`${RESERVED_HUB_NAMES.join(" and ")} are reserved and cannot name a hub`);
+	const target = resolve(root, path);
+	if (name === readConfig(root).hub) throw new WriteError(`"${name}" is this hub's own name; references without a prefix already point here`);
+	if (!existsSync(join(target, ".mainflow", "config.yaml"))) throw new WriteError(`no hub at ${path} from the hub root (${target})`);
+	const other = readConfig(target).hub;
+	if (other !== name) throw new WriteError(`${path} holds hub "${other}"; register it as "${other}"`);
+	mutateYaml(root, join(root, DATA_DIR, "config.yaml"), configSchema, (c) => {
+		const hubs = c.hubs ??= {};
+		if (hubs[name] !== void 0 && hubs[name] !== path) throw new WriteError(`hub "${name}" is already registered as ${hubs[name]}`);
+		hubs[name] = path;
+	});
+	return name;
+}
+/** Stamp closedAt when a status closes the entity and clear it when the entity reopens. */
+function stampClosed(doc, closed, at) {
+	if (closed) doc.closedAt ??= at;
+	else delete doc.closedAt;
+}
+const closes = (kind, status) => CLOSED_STATUS[kind].includes(status);
+function createMainline(root, input) {
+	requireSlug(input.slug);
+	return withLock(root, () => {
+		const id = nextId("m", idsIn(mainlinesDir(root)));
+		const dir = join(mainlinesDir(root), `${id}-${input.slug}`);
+		const mainline = validate(mainlineSchema, {
+			id,
+			title: input.title,
+			status: "planning",
+			created: today(),
+			criteria: []
+		}, MAINLINE_FILE);
+		mkdirSync(join(dir, "tasks"), { recursive: true });
+		writeAtomic(join(dir, MAINLINE_FILE), frontMatterText(mainline, MAINLINE_BODY));
+		return {
+			id,
+			dir
+		};
+	});
+}
+/** Decisions of a mainline still waiting for a ruling, by id. */
+function proposedDecisions(root, id) {
+	return listFiles(join(mainlineDir(root, id), "decisions")).filter((file) => file.endsWith(".md")).map((file) => splitFrontMatter(readText(file) ?? "").data).filter((d) => d?.status === "proposed").map((d) => d.id ?? "?");
+}
+/**
+* Marking a mainline done is a claim that its criteria hold and nothing is left to decide, so it is
+* refused while a criterion is still open or a decision is still proposed. The message names each one and
+* the ways to settle it; dropping the mainline instead is not checked.
+*/
+function requireDone(root, id, m) {
+	const open = m.criteria.filter((c) => !c.done && !c.dropped).map((c) => `${id}#${c.id}`);
+	const proposed = proposedDecisions(root, id).map((d) => `${id}/${d}`);
+	if (!open.length && !proposed.length) return;
+	throw new WriteError(`${id} cannot be marked done: ${[open.length ? `unmet criteria ${open.join(", ")} (check each with evidence, e.g. criterion check ${open[0]} --evidence <commit>, or reword or drop it in ${MAINLINE_FILE})` : "", proposed.length ? `proposed decisions ${proposed.join(", ")} (decision accept or decision supersede first)` : ""].filter(Boolean).join("; ")}`);
+}
+/** Move a mainline to another status; done is refused while criteria are open or decisions are proposed. */
+function setMainlineStatus(root, id, status, expectedVersion) {
+	requireRef(id, "mainline");
+	const next = requireOneOf(status, MAINLINE_STATUS, "mainline status");
+	return mutateFrontMatter(root, mainlineFile(root, id), mainlineSchema, (m) => {
+		if (next === "done" && m.status !== "done") requireDone(root, id, m);
+		m.status = next;
+		stampClosed(m, closes("mainline", next), today());
+	}, expectedVersion);
+}
+function setArchived(root, id, archived, expectedVersion) {
+	requireRef(id, "mainline");
+	return mutateFrontMatter(root, mainlineFile(root, id), mainlineSchema, (m) => {
+		if (archived) m.archivedAt ??= today();
+		else delete m.archivedAt;
+	}, expectedVersion);
+}
+function setCriterion(root, refInput, done, evidence, expectedVersion) {
+	const ref = requireRef(refInput, "criterion");
+	if (done && !evidence) throw new WriteError(`marking ${refInput} as met needs evidence, e.g. --evidence mainflow@25e4165`);
+	return mutateFrontMatter(root, mainlineFile(root, ref.mainline), mainlineSchema, (m) => {
+		const criterion = m.criteria.find((c) => c.id === ref.criterion);
+		if (!criterion) throw new WriteError(`criterion ${refInput} not found`);
+		setListItem(criterion, done, evidence);
+	}, expectedVersion);
+}
+/** Check or uncheck a criterion or checklist item; checking clears a drop. */
+function setListItem(item, done, evidence) {
+	item.done = done;
+	if (done) {
+		item.evidence = evidence;
+		item.doneAt = today();
+		delete item.dropped;
+		delete item.supersededBy;
+	} else {
+		delete item.evidence;
+		delete item.doneAt;
+	}
+}
+function createTask(root, mainline, input) {
+	requireRef(mainline, "mainline");
+	requireSlug(input.slug);
+	const kind = requireOneOf(input.kind ?? "phase", ["phase", "branch"], "task kind");
+	return withLock(root, () => {
+		const tasksDir = join(mainlineDir(root, mainline), "tasks");
+		const id = nextId("t", idsIn(tasksDir));
+		const task = validate(taskSchema, {
+			id,
+			title: input.title,
+			kind,
+			status: "todo",
+			created: today(),
+			checklist: [],
+			...input.parent ? { parent: input.parent } : {},
+			...input.repo ? { repo: input.repo } : {}
+		}, TASK_FILE);
+		checkTaskLinks(root, mainline, task);
+		const dir = join(tasksDir, `${id}-${input.slug}`);
+		mkdirSync(dir, { recursive: true });
+		writeAtomic(join(dir, TASK_FILE), frontMatterText(task, TASK_BODY));
+		return {
+			ref: `${mainline}/${id}`,
+			dir
+		};
+	});
+}
+function updateTask(root, refInput, patch, expectedVersion) {
+	const ref = requireRef(refInput, "task");
+	const status = patch.status === void 0 ? void 0 : requireOneOf(patch.status, WORK_STATUS, "task status");
+	const merge = patch.merge === void 0 ? void 0 : requireOneOf(patch.merge, MERGE_STATES, "merge state");
+	if (status === "blocked" && !patch.blockedBy?.reason) throw new WriteError(`blocking ${refInput} needs a reason, e.g. --reason "等使用者提供 API key" --waiting-for 使用者`);
+	return mutateFrontMatter(root, taskFile(root, ref.mainline, ref.task), taskSchema, (t) => {
+		if (status !== void 0) {
+			t.status = status;
+			if (status === "doing") t.startedAt ??= today();
+			stampClosed(t, closes("task", status), today());
+			if (status !== "blocked") delete t.blockedBy;
+		}
+		if (patch.repo !== void 0) {
+			if (patch.repo) t.repo = patch.repo;
+			else delete t.repo;
+		}
+		if (patch.blockedBy !== void 0) t.blockedBy = patch.blockedBy;
+		if (patch.branch !== void 0) t.branch = patch.branch;
+		if (patch.worktree !== void 0) t.worktree = patch.worktree;
+		if (patch.base !== void 0) t.base = patch.base;
+		if (merge !== void 0) t.merge = merge;
+		checkTaskLinks(root, ref.mainline, t);
+	}, expectedVersion);
+}
+function setChecklistItem(root, refInput, done, evidence, expectedVersion) {
+	const ref = requireRef(refInput, "checklistItem");
+	if (done && !evidence) throw new WriteError(`checking ${refInput} needs evidence, e.g. --evidence mainflow@25e4165`);
+	return mutateFrontMatter(root, taskFile(root, ref.mainline, ref.task), taskSchema, (t) => {
+		const item = t.checklist.find((c) => c.id === ref.item);
+		if (!item) throw new WriteError(`checklist item ${refInput} not found`);
+		setListItem(item, done, evidence);
+	}, expectedVersion);
+}
+/** Mark an item as no longer needed, naming what replaced it when something did. */
+function dropChecklistItem(root, refInput, input = {}, expectedVersion) {
+	const ref = requireRef(refInput, "checklistItem");
+	return mutateFrontMatter(root, taskFile(root, ref.mainline, ref.task), taskSchema, (t) => {
+		const item = t.checklist.find((c) => c.id === ref.item);
+		if (!item) throw new WriteError(`checklist item ${refInput} not found`);
+		if (item.done) throw new WriteError(`${refInput} is checked; uncheck it before dropping it`);
+		item.dropped = true;
+		if (input.supersededBy) item.supersededBy = input.supersededBy;
+		if (input.note) item.note = input.note;
+	}, expectedVersion);
+}
+function createDecision(root, mainline, input) {
+	requireRef(mainline, "mainline");
+	requireSlug(input.slug);
+	const status = requireOneOf(input.status ?? "accepted", ["proposed", "accepted"], "new decision status");
+	const by = input.by === void 0 ? void 0 : requireOneOf(input.by, DECIDERS, "decided by");
+	for (const ref of input.affects ?? []) requireAffected(root, mainline, ref);
+	return withLock(root, () => {
+		const dir = join(mainlineDir(root, mainline), "decisions");
+		mkdirSync(dir, { recursive: true });
+		const id = nextId("d", idsIn(dir));
+		const at = nowMinute();
+		const decision = validate(decisionSchema, {
+			id,
+			title: input.title,
+			created: at,
+			status,
+			...status === "accepted" ? { decidedAt: at } : {},
+			...by ? { by } : {},
+			...input.affects?.length ? { affects: input.affects } : {}
+		}, "decision");
+		const file = join(dir, `${id}-${input.slug}.md`);
+		writeAtomic(file, frontMatterText(decision, DECISION_BODY));
+		return {
+			ref: `${mainline}/${id}`,
+			file
+		};
+	});
+}
+/** A decision affects tasks or checklist items of its own mainline, and they must exist. */
+function requireAffected(root, mainline, input) {
+	const ref = parseRefIn(input);
+	if (!ref || ref.mainline !== mainline) throw new WriteError(`--affects takes tasks or checklist items of ${mainline}, like ${mainline}/t001 or ${mainline}/t001#c002; got "${input}"`);
+	taskDir(root, ref.mainline, ref.task);
+}
+const parseRefIn = (input) => {
+	const task = /^(m\d{3})\/(t\d{3})(?:#c\d{3})?$/.exec(input);
+	return task ? {
+		mainline: task[1],
+		task: task[2]
+	} : null;
+};
+/** Settle a proposed decision: record who decided and when; the items it affects stop waiting for it. */
+function acceptDecision(root, refInput, by, expectedVersion) {
+	const ref = requireRef(refInput, "decision");
+	const decider = by === void 0 ? void 0 : requireOneOf(by, DECIDERS, "decided by");
+	return mutateFrontMatter(root, decisionFile(root, ref.mainline, ref.decision), decisionSchema, (d) => {
+		if (d.status !== "proposed") throw new WriteError(`${refInput} is ${d.status}; only a proposed decision can be accepted`);
+		d.status = "accepted";
+		d.decidedAt = nowMinute();
+		if (decider) d.by = decider;
+	}, expectedVersion);
+}
+function supersedeDecision(root, refInput, by, expectedVersion) {
+	const ref = requireRef(refInput, "decision");
+	const successor = requireRef(by.includes("/") ? by : `${ref.mainline}/${by}`, "decision");
+	if (successor.mainline !== ref.mainline) throw new WriteError(`a decision can only be superseded within its own mainline (${ref.mainline})`);
+	if (successor.decision === ref.decision) throw new WriteError(`decision ${refInput} cannot supersede itself`);
+	decisionFile(root, successor.mainline, successor.decision);
+	return mutateFrontMatter(root, decisionFile(root, ref.mainline, ref.decision), decisionSchema, (d) => {
+		d.status = "superseded";
+		d.supersededBy = successor.decision;
+		stampClosed(d, true, nowMinute());
+	}, expectedVersion);
+}
+//#endregion
+//#region ../core/dist/migrate.js
+const drop = (o, ...keys) => keys.forEach((k) => delete o[k]);
+const dropNull = (o, ...keys) => keys.forEach((k) => o[k] === null && delete o[k]);
+const rename = (o, from, to) => {
+	if (from in o) {
+		if (o[from] !== null && o[from] !== void 0) o[to] = o[from];
+		delete o[from];
+	}
+};
+const isClosed = (kind, status) => CLOSED_STATUS[kind].includes(status);
+/** Drop the file's own H1, which format 2 replaces with the title in the front matter. */
+const withoutTitle = (markdown) => markdown.replace(/^\s*# [^\n]*\n/, "").replace(/^\n+/, "");
+/**
+* Fold format 1's notes.md into the task body. Sections the task body also has keep their place; any
+* other section, and text before the first section, moves under 紀錄 one heading level deeper.
+*/
+function foldNotes(body, notes) {
+	const lines = withoutTitle(notes).split("\n");
+	const sections = [{
+		heading: null,
+		lines: []
+	}];
+	for (const line of lines) {
+		const h2 = /^## (.+)$/.exec(line);
+		if (h2) sections.push({
+			heading: h2[1].trim(),
+			lines: []
+		});
+		else sections.at(-1).lines.push(line);
+	}
+	const extra = [];
+	for (const section of sections) {
+		const text = section.lines.join("\n").trim();
+		if (section.heading && TASK_SECTIONS.includes(section.heading)) {
+			if (!text) continue;
+			const current = sectionText(body, section.heading) ?? "";
+			body = withSection(body, section.heading, current ? `${current}\n\n${text}` : text);
+		} else if (section.heading) extra.push(`### ${section.heading}`, "", text.replace(/^(#{3,5}) /gm, "#$1 "), "");
+		else if (text) extra.push(text, "");
+	}
+	if (extra.length) {
+		const current = sectionText(body, "紀錄") ?? "";
+		body = withSection(body, "紀錄", [current, extra.join("\n").trim()].filter(Boolean).join("\n\n"));
+	}
+	return body;
+}
+/** Criteria and checklist items: format 2 omits nulls and names a met criterion done. */
+function migrateListItem(item) {
+	rename(item, "met", "done");
+	dropNull(item, "evidence", "doneAt");
+	return item;
+}
+const openItem = (item) => !item.done && !item.dropped;
+/** Convert a format 1 hub to the current format, writing nothing when `dryRun` is set. */
+function migrateHub(root, options = {}) {
+	const dataDir = join(root, DATA_DIR);
+	const configFile = join(dataDir, "config.yaml");
+	if (!existsSync(configFile)) throw new WriteError(`no hub at ${root}; run mainflow init first`);
+	const rel = (path) => relative(root, path);
+	return withLock(root, () => {
+		const config = parse(readFileSync(configFile, "utf8"));
+		const from = Number(config.formatVersion);
+		if (from === 2) throw new WriteError(`${rel(configFile)} is already format 2; nothing to migrate`);
+		if (from !== 1) throw new WriteError(`cannot migrate from format ${String(config.formatVersion)}; this CLI migrates format 1 to 2`);
+		const writes = /* @__PURE__ */ new Map();
+		const removes = [];
+		const missing = [];
+		const document = (file, schema, data, body) => {
+			writes.set(file, frontMatterText(validate(schema, data, rel(file)), body));
+		};
+		for (const mainlineDir of subdirs(join(dataDir, "mainlines"))) {
+			const yamlFile = join(mainlineDir, "mainline.yaml");
+			if (!existsSync(yamlFile)) continue;
+			const m = parse(readFileSync(yamlFile, "utf8"));
+			dropNull(m, "archivedAt");
+			if (isClosed("mainline", m.status) && m.archivedAt) m.closedAt = m.archivedAt;
+			const criteria = (m.criteria ?? []).map(migrateListItem);
+			m.criteria = criteria;
+			const id = String(m.id);
+			const open = !isClosed("mainline", m.status);
+			if (open) {
+				for (const c of criteria) if (openItem(c) && !c.doneWhen) missing.push(`${id}#${c.id} doneWhen`);
+			}
+			const contextFile = join(mainlineDir, "context.md");
+			const context = existsSync(contextFile) ? withoutTitle(readFileSync(contextFile, "utf8")) : "";
+			document(join(mainlineDir, MAINLINE_FILE), mainlineSchema, m, `\n${context.trimEnd()}\n`);
+			removes.push(yamlFile, ...existsSync(contextFile) ? [contextFile] : []);
+			for (const taskDir of subdirs(join(mainlineDir, "tasks"))) {
+				const taskYaml = join(taskDir, "task.yaml");
+				if (!existsSync(taskYaml)) continue;
+				const t = parse(readFileSync(taskYaml, "utf8"));
+				const content = typeof t.content === "string" ? t.content.trim() : "";
+				drop(t, "content");
+				dropNull(t, "parent", "repo");
+				t.created ??= m.created;
+				const checklist = (t.checklist ?? []).map(migrateListItem);
+				t.checklist = checklist;
+				const doneDays = checklist.map((c) => c.doneAt).filter((d) => typeof d === "string").sort();
+				if (isClosed("task", t.status) && doneDays.length) t.closedAt = doneDays.at(-1);
+				let body = content ? withSection(TASK_BODY, "目標", content) : TASK_BODY;
+				const notesFile = join(taskDir, "notes.md");
+				if (existsSync(notesFile)) {
+					body = foldNotes(body, readFileSync(notesFile, "utf8"));
+					removes.push(notesFile);
+				}
+				const taskRef = `${id}/${String(t.id)}`;
+				if (open && !isClosed("task", t.status)) {
+					for (const section of TASK_REQUIRED_SECTIONS) if (!sectionText(body, section)) missing.push(`${taskRef} ${section}`);
+					for (const c of checklist) if (openItem(c) && !c.doneWhen) missing.push(`${taskRef}#${c.id} doneWhen`);
+				}
+				document(join(taskDir, TASK_FILE), taskSchema, t, body);
+				removes.push(taskYaml);
+			}
+			const decisionsDir = join(mainlineDir, "decisions");
+			for (const name of existsSync(decisionsDir) ? readdirSync(decisionsDir).filter((n) => n.endsWith(".md")).sort() : []) {
+				const file = join(decisionsDir, name);
+				const { data, body } = splitFrontMatter(readFileSync(file, "utf8"));
+				const d = data;
+				rename(d, "date", "created");
+				if (d.status !== "proposed") d.decidedAt = d.created;
+				dropNull(d, "supersededBy");
+				rename(d, "blocks", "affects");
+				document(file, decisionSchema, d, body);
+			}
+		}
+		const hubDocs = (dir, migrate, schema) => {
+			for (const name of existsSync(dir) ? readdirSync(dir).filter((n) => n.endsWith(".md")).sort() : []) {
+				const file = join(dir, name);
+				const { data, body } = splitFrontMatter(readFileSync(file, "utf8"));
+				migrate(data);
+				document(file, schema, data, body);
+			}
+		};
+		hubDocs(join(dataDir, "issues"), (i) => rename(i, "closedBy", "resolution"), issueSchema);
+		hubDocs(join(dataDir, "findings"), (f) => {
+			rename(f, "date", "created");
+			rename(f, "tags", "labels");
+		}, findingSchema);
+		config.formatVersion = 2;
+		writes.set(configFile, toYaml(validate(configSchema, config, rel(configFile))));
+		if (!options.dryRun) {
+			for (const [file, text] of writes) writeAtomic(file, text);
+			for (const file of removes) rmSync(file);
+		}
+		return {
+			from,
+			to: 2,
+			written: [...writes.keys()].map(rel),
+			removed: removes.map(rel),
+			missingDefinitions: missing
+		};
+	});
+}
+//#endregion
+export { createFinding as A, refIndex as B, startSession as C, turnReminder as D, sessionBriefing as E, setFindingStatus as F, DATA_DIR as G, TASK_FILE as H, setIssueArchived as I, worktreesOf as J, currentBranch as K, HubError as L, planIssue as M, reopenIssue as N, appendOps as O, setFindingArchived as P, loadHub as R, setSessionStatus as S, updateAction as T, ConflictError as U, MAINLINE_FILE as V, WriteError as W, ensureSession as _, createDecision as a, setSessionArchived as b, dropChecklistItem as c, setChecklistItem as d, setCriterion as f, addAction as g, updateTask as h, addRepo as i, createIssue as j, closeIssue as k, initHub as l, supersedeDecision as m, acceptDecision as n, createMainline as o, setMainlineStatus as p, findHubRoot as q, addHub as r, createTask as s, migrateHub as t, setArchived as u, loadSessions as v, transcriptPath as w, setSessionInfo as x, readSession as y, linksInto as z };