@sdd-method/author-cli 0.9.0 → 0.11.0

package/dist/lib/intents/migrate.js

@@ -0,0 +1,670 @@
+// `migrate intents` (M-ADR 0227 §5.2): turn an adopter's Ideas and Epic Briefs into intents, one per request id.
+//
+// An Idea and its Epic Brief are one request at two stages, so they make one intent. The intent takes the
+// originator's words from the Idea where it has them and the Brief's otherwise (a request with no Idea takes
+// its outcome from the Brief's Scope); the Brief's other elaboration (evidence, handoff, exit criteria) is not
+// copied, because the artefacts it produced hold it. The method shipped no Brief template, so Brief headings
+// are matched by name, and the report lists every heading the converter did not recognise. Its
+// "Where it went" is rebuilt from evidence, each line saying which source supports it:
+//   cited      a path the Idea or Brief names that is a file the SDD owns in its working tree (a repository-
+//              relative path, or a blob URL whose repository is one of the SDDs);
+//   mentioned  a tracked file in an SDD that names the request id, unless the file names many request ids
+//              (an index lists requests; it is not where one went);
+//   titled     a tracked file whose title names the request id (an application's own Epic Brief): it is
+//              about that request whatever else it cites, so it counts even when it names many ids, and it
+//              weighs more than any other evidence in choosing the intent's home;
+//   commit     a commit in an SDD whose message names the id, unless its subject moves, renames, archives or
+//              marks the Ideas and Briefs themselves. When it names at most a few ids (a plan
+//              bundle delivers several), the files it changed that the SDD still owns are evidence too
+//              (committed, naming the other ids it shares with), unless it touched so many that it was a sweep;
+//   plan       a plan file (from --plans) that names the id. A plan says what was planned, not what shipped,
+//              so an id whose only evidence is a plan is flagged for a check that the work landed. A plan
+//              naming at most a few ids also contributes the paths it cites that an SDD owns now (planned).
+// With no evidence, an intent goes to the platform among the SDDs (the first one named when none is a
+// platform), and is flagged. A path that moved since it was cited or committed is followed through the SDD's git renames to where it is
+// now. A reviewer's decisions are given back as --home ID=<sdd-id> and --status ID=open|closed.
+// Planning state (status, priority, relations) goes to a tool-neutral work-item import file, never into the
+// intent (M-ADR 0227 §4.3, M-ADR 0035). A dry run writes the report, the import file, the citation table and
+// the intents, all under --out; --write writes the intents into the SDDs instead, never over an existing file.
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+import { parseDocument } from "yaml";
+import { normaliseHeading, parseMarkdown } from "./format.js";
+const run = promisify(execFile);
+const ID_TOKEN = /\b[A-Z][A-Z0-9]*-\d+\b/g;
+const CLOSED = new Set(["completed", "complete", "done", "delivered", "shipped", "closed"]);
+const DECLINED = new Set(["dropped", "rejected", "declined", "obsolete", "withdrawn"]);
+const IDEA_MAP_IDS = /\b[A-Z][A-Z0-9]*-\d+\b/g;
+const NOT_OWN = /^(docs\/method\/|catalogues|\.sdd\/|openspec\/schemas\/|content\/(method|product)\/intents\/)/;
+/** A commit changing more owned files than this was a sweep (a rename, a reformat), not a delivery. */
+const SWEEP = 25;
+/** A commit or plan naming more request ids than this is not evidence for any one of them. */
+const SHARED = 3;
+/** How much a file titled with the id weighs in choosing a home, against one for any other evidence line. */
+const TITLED_WEIGHT = 100;
+const HOUSEKEEPING = /\b(move[sd]?|moving|rename[sd]?|renaming|archive[sd]?|mark(s|ed)?|retire[sd]?|close[sd]?|complete[sd]?)\b.*\b(idea|ideas|idea-map|epic|epics|brief|briefs)\b|\b(idea|ideas|idea-map|epic|epics|brief|briefs)\b.*\b(moved|renamed|archived|marked|retired|closed|completed)\b/i;
+async function walk(dir, accept) {
+    const out = [];
+    const go = async (d) => {
+        let entries;
+        try {
+            entries = await readdir(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name === ".git" || e.name === "node_modules")
+                continue;
+            const p = join(d, e.name);
+            if (e.isDirectory())
+                await go(p);
+            else if (e.isFile() && accept(p))
+                out.push(p);
+        }
+    };
+    await go(dir);
+    return out.sort();
+}
+async function gitTop(dir) {
+    try {
+        return (await run("git", ["-C", dir, "rev-parse", "--show-toplevel"])).stdout.trim();
+    }
+    catch {
+        return dir;
+    }
+}
+async function gitHead(dir) {
+    try {
+        return (await run("git", ["-C", dir, "rev-parse", "--short", "HEAD"])).stdout.trim();
+    }
+    catch {
+        return "uncommitted";
+    }
+}
+async function loadSdd(dir) {
+    let id = basename(dir);
+    try {
+        const m = parseDocument(await readFile(join(dir, ".sdd/sdd-manifest.yaml"), "utf8")).toJS();
+        if (typeof m?.sdd_id === "string" && m.sdd_id)
+            id = m.sdd_id;
+    }
+    catch {
+        // no manifest: the directory name
+    }
+    const repoNames = new Set([basename(dir)]);
+    try {
+        const url = (await run("git", ["-C", dir, "remote", "get-url", "origin"])).stdout.trim();
+        repoNames.add(basename(url).replace(/\.git$/, ""));
+    }
+    catch {
+        // no remote
+    }
+    const renames = new Map();
+    try {
+        const { stdout } = await run("git", ["-C", dir, "log", "--format=", "--name-status", "-M", "--diff-filter=R"], { maxBuffer: 256 * 1024 * 1024 });
+        for (const line of stdout.split("\n")) {
+            const [st, from, to] = line.split("\t");
+            if (st?.startsWith("R") && from && to && !renames.has(from))
+                renames.set(from, to);
+        }
+    }
+    catch {
+        // not a git repository
+    }
+    let kind = "";
+    try {
+        kind = (await readFile(join(dir, ".sdd-repo-kind"), "utf8")).trim();
+    }
+    catch {
+        // no marker
+    }
+    return { dir, id, repoNames, managed: await managedPaths(dir), renames, kind };
+}
+function readSource(path, text) {
+    const doc = parseMarkdown(text);
+    // The title decides first, then the id field, then the folder: a Brief often repeats its Idea's id field.
+    const t = doc.title.toLowerCase();
+    const kind = t.startsWith("epic brief")
+        ? "brief"
+        : t.startsWith("idea")
+            ? "idea"
+            : doc.fields.has("Epic ID")
+                ? "brief"
+                : /(^|\/)epics\//.test(path)
+                    ? "brief"
+                    : doc.fields.has("Idea ID") || /(^|\/)ideas\//.test(path)
+                        ? "idea"
+                        : null;
+    if (!kind)
+        return null;
+    const id = doc.fields.get("Idea ID") ?? doc.fields.get("Epic ID") ?? /^([A-Z][A-Z0-9]*-\d+)/.exec(basename(path))?.[1];
+    if (!id)
+        return null;
+    return { kind, path, id: id.replace(/`/g, "").trim(), doc };
+}
+function titleOf(f) {
+    return f.doc.title
+        .replace(/^(idea|epic brief)\s*:\s*/i, "")
+        .replace(new RegExp(`^${f.id}\\s*[—–:-]\\s*`), "")
+        .trim();
+}
+function section(f, ...names) {
+    if (!f)
+        return "";
+    for (const n of names) {
+        for (const [k, v] of f.doc.sections)
+            if ((k === n || k.startsWith(`${n} `)) && v)
+                return v;
+    }
+    return "";
+}
+/** Every section whose normalised heading passes the test, in order. */
+function matching(f, test) {
+    if (!f)
+        return [];
+    return [...f.doc.sections.entries()].filter(([h, v]) => test(h) && v).map(([, v]) => v);
+}
+const isGuardrails = (h) => h.startsWith("guardrails");
+function idsIn(s) {
+    return s ? [...new Set(s.match(IDEA_MAP_IDS) ?? [])] : [];
+}
+/** Required | Optional | None, keeping the source's own words after it. */
+function adrRequirement(raw) {
+    const v = raw.trim();
+    if (!v)
+        return "None (not recorded in the source).";
+    const w = v.split(/[\s—–(-]/)[0].toLowerCase();
+    const norm = w === "required" || w === "likely" ? "Required" : w === "optional" ? "Optional" : w === "none" || w === "unlikely" ? "None" : null;
+    return norm ? `${norm}. Source: ${v}` : `${v} (not one of Required, Optional or None: review)`;
+}
+const KNOWN_BRIEF = [
+    "problem statement",
+    "decision to resolve",
+    "scope",
+    "resolved and open questions",
+    "resolved vs open",
+    "resolved vs open questions",
+    "dependencies and constraints",
+    "dependencies",
+    "evidence and draft artifacts",
+    "planning handoff targets",
+    "planning handoff",
+    "exit criteria for planning readiness",
+    "exit criteria",
+];
+const KNOWN_IDEA = [
+    "problem or opportunity",
+    "idea summary",
+    "why explore this",
+    "open questions",
+    "early impact notes",
+    "explore next",
+    "related ideas",
+    "exit criteria to become an epic brief",
+];
+function readIdeaMap(text) {
+    const rows = new Map();
+    let cols = null;
+    for (const line of text.split("\n")) {
+        if (!line.trim().startsWith("|")) {
+            cols = null;
+            continue;
+        }
+        const cells = line.trim().replace(/^\||\|$/g, "").split("|").map((c) => c.trim());
+        if (cells.every((c) => /^:?-+:?$/.test(c)))
+            continue;
+        if (!cols) {
+            cols = cells.map((c) => c.toLowerCase());
+            continue;
+        }
+        const at = (name) => {
+            const i = cols.indexOf(name);
+            return i >= 0 ? cells[i] : undefined;
+        };
+        const id = at("id");
+        if (!id || !/^[A-Z][A-Z0-9]*-\d+$/.test(id))
+            continue;
+        rows.set(id, { status: at("status"), priority: at("priority"), depends: idsIn(at("depends on")) });
+    }
+    return rows;
+}
+const PATHISH = /`([^`\s][^`]*\/[^`]*)`/g;
+const LINK = /\]\(([^)\s]+)\)/g;
+const BLOB = /^https?:\/\/[^/]+\/[^/]+\/([^/]+)\/(?:blob|tree)\/[^/]+\/(.+)$/;
+/** A file the SDD owns: not a directory, not a method path, not a synced copy, not generated or migrated output. */
+function owned(s, p) {
+    if (s.managed.has(p) || NOT_OWN.test(p))
+        return false;
+    try {
+        return statSync(join(s.dir, p)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Where a path is now: itself if the SDD owns it, else followed through the SDD's renames; null if neither. */
+function current(s, p) {
+    const seen = new Set();
+    let q = p;
+    while (!owned(s, q)) {
+        const next = s.renames.get(q);
+        if (!next || seen.has(q))
+            return null;
+        seen.add(q);
+        q = next;
+    }
+    return q;
+}
+function citedPaths(text, sdds) {
+    const out = [];
+    const consider = (raw) => {
+        let t = raw.trim();
+        try {
+            t = decodeURIComponent(t);
+        }
+        catch {
+            // a literal % that is not an escape: keep the text as written
+        }
+        t = t.replace(/[#?].*$/, "").replace(/:\d+(-\d+)?$/, "");
+        const blob = BLOB.exec(t);
+        if (blob) {
+            const s = sdds.find((x) => x.repoNames.has(blob[1]));
+            const now = s ? current(s, blob[2]) : null;
+            if (s && now)
+                out.push({ sdd: s.id, path: now });
+            return;
+        }
+        if (/^[a-z]+:/i.test(t) || t.startsWith("/") || t.startsWith(".."))
+            return;
+        for (const s of sdds) {
+            const now = current(s, t);
+            if (now)
+                out.push({ sdd: s.id, path: now });
+        }
+    };
+    for (const m of text.matchAll(PATHISH))
+        consider(m[1]);
+    for (const m of text.matchAll(LINK))
+        consider(m[1]);
+    return out;
+}
+/** Paths every bundle in the SDD's lock manages: synced copies (method files, context-pack ADRs), not its own content. */
+async function managedPaths(dir) {
+    try {
+        const text = await readFile(join(dir, "method-baseline.lock"), "utf8");
+        return new Set([...text.matchAll(/^\s+-\s+[0-9a-f]{64}\s{2}(.+?)\s*$/gm)].map((m) => m[1]));
+    }
+    catch {
+        return new Set();
+    }
+}
+async function trackedText(dir, managed) {
+    try {
+        const { stdout } = await run("git", ["-C", dir, "ls-files", "-z", "--", "*.md", "*.yaml", "*.yml", "*.feature"], {
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        return stdout
+            .split("\0")
+            .filter((p) => p && !managed.has(p) && !NOT_OWN.test(p));
+    }
+    catch {
+        return [];
+    }
+}
+export async function migrateIntents(opts) {
+    const sdds = await Promise.all(opts.sdds.map((d) => loadSdd(resolve(d))));
+    if (sdds.length === 0)
+        throw new Error("name at least one SDD (--sdd)");
+    const defaultHome = sdds.find((s) => s.kind === "platform-product") ?? sdds[0];
+    // 1. Sources, grouped by request id.
+    const byId = new Map();
+    const unrecognised = [];
+    const sourceRepos = new Map();
+    for (const dir of opts.sources) {
+        const top = await gitTop(resolve(dir));
+        sourceRepos.set(resolve(dir), { top, head: await gitHead(top) });
+        for (const p of await walk(resolve(dir), (x) => x.endsWith(".md") && basename(x).toLowerCase() !== "readme.md")) {
+            if (opts.ideaMap && resolve(p) === resolve(opts.ideaMap))
+                continue;
+            const f = readSource(p, await readFile(p, "utf8"));
+            if (!f) {
+                unrecognised.push(p);
+                continue;
+            }
+            const e = byId.get(f.id) ?? {};
+            if (e[f.kind])
+                unrecognised.push(`${p} (a second ${f.kind} for ${f.id}; the first is kept)`);
+            else
+                e[f.kind] = f;
+            byId.set(f.id, e);
+        }
+    }
+    const ids = new Set(byId.keys());
+    const map = opts.ideaMap ? readIdeaMap(await readFile(opts.ideaMap, "utf8")) : new Map();
+    // 2. Evidence.
+    const ev = new Map([...ids].map((i) => [i, { cited: [], mentioned: [], titled: [], committed: [], planned: [], commits: [], plans: [] }]));
+    const indexFiles = [];
+    for (const [id, e] of byId) {
+        const text = [e.idea, e.brief].filter(Boolean).map((f) => readFileSyncSafe(f.path)).join("\n");
+        const seen = new Set();
+        for (const c of citedPaths(text, sdds)) {
+            const k = `${c.sdd}\0${c.path}`;
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            ev.get(id).cited.push(c);
+        }
+    }
+    for (const s of sdds) {
+        for (const rel of await trackedText(s.dir, s.managed)) {
+            let text;
+            try {
+                text = await readFile(join(s.dir, rel), "utf8");
+            }
+            catch {
+                continue;
+            }
+            const hits = [...new Set((text.match(ID_TOKEN) ?? []).filter((t) => ids.has(t)))];
+            if (hits.length === 0)
+                continue;
+            // A file titled with a request id is about that request, however many others it cites.
+            const title = /^#\s+(.+)$/m.exec(text)?.[1] ?? "";
+            const titled = (title.match(ID_TOKEN) ?? []).filter((t) => ids.has(t));
+            for (const id of titled)
+                ev.get(id).titled.push({ sdd: s.id, path: rel });
+            if (hits.length > opts.indexThreshold) {
+                indexFiles.push(`${s.id}: ${rel} (${hits.length} ids)`);
+                continue;
+            }
+            for (const id of hits) {
+                if (titled.includes(id))
+                    continue;
+                const e = ev.get(id);
+                if (!e.cited.some((c) => c.sdd === s.id && c.path === rel))
+                    e.mentioned.push({ sdd: s.id, path: rel });
+            }
+        }
+        try {
+            const { stdout } = await run("git", ["-C", s.dir, "log", "--name-only", "--format=%x1e%h%x09%s%x09%b%x1f"], { maxBuffer: 256 * 1024 * 1024 });
+            for (const rec of stdout.split("\x1e")) {
+                const [head, names = ""] = rec.split("\x1f");
+                const [sha, subject = "", ...rest] = (head ?? "").trim().split("\t");
+                if (!sha)
+                    continue;
+                // A commit that only kept the Ideas and Briefs themselves (moved, renamed, marked done) is not where one went.
+                if (HOUSEKEEPING.test(subject))
+                    continue;
+                const named = [...new Set(`${subject} ${rest.join(" ")}`.match(ID_TOKEN) ?? [])].filter((i) => ids.has(i));
+                for (const id of named)
+                    ev.get(id).commits.push({ sdd: s.id, sha, subject });
+                // Its files are evidence when it names at most a few requests, and was not a sweep.
+                if (named.length === 0 || named.length > SHARED)
+                    continue;
+                const files = [...new Set(names.split("\n").map((n) => n.trim()).filter(Boolean).map((n) => current(s, n)).filter((n) => n !== null))];
+                if (files.length === 0 || files.length > SWEEP)
+                    continue;
+                for (const id of named) {
+                    const e = ev.get(id);
+                    for (const f of files) {
+                        if (!e.committed.some((c) => c.sdd === s.id && c.path === f))
+                            e.committed.push({ sdd: s.id, path: f, sha, with: named.filter((n) => n !== id) });
+                    }
+                }
+            }
+        }
+        catch {
+            // not a git repository
+        }
+    }
+    for (const dir of opts.plans) {
+        const top = await gitTop(resolve(dir));
+        for (const p of await walk(resolve(dir), (x) => x.endsWith(".md"))) {
+            const text = readFileSyncSafe(p);
+            const named = [...new Set((text.match(ID_TOKEN) ?? []).filter((t) => ids.has(t)))];
+            const where = relative(top, p);
+            const paths = named.length > 0 && named.length <= SHARED ? citedPaths(text, sdds) : [];
+            for (const id of named) {
+                const e = ev.get(id);
+                e.plans.push({ repo: basename(top), path: where });
+                for (const c of paths) {
+                    if (!e.planned.some((x) => x.sdd === c.sdd && x.path === c.path))
+                        e.planned.push({ ...c, plan: where, with: named.filter((n) => n !== id) });
+                }
+            }
+        }
+    }
+    // 3. Intents, work items and citations.
+    const flags = new Map();
+    const notCarried = new Map();
+    const flag = (id, why) => flags.set(id, [...(flags.get(id) ?? []), why]);
+    const items = [];
+    const citations = ["id\tkind\tsource_repository\tsource_path\ttarget_sdd\ttarget_path"];
+    const written = [];
+    const skippedExisting = [];
+    const intents = [];
+    for (const id of [...ids].sort(compareIds)) {
+        const { idea, brief } = byId.get(id);
+        const e = ev.get(id);
+        const primary = (idea ?? brief);
+        const fields = (k) => idea?.doc.fields.get(k) ?? brief?.doc.fields.get(k) ?? "";
+        for (const f of [idea, brief]) {
+            if (!f)
+                continue;
+            const known = f.kind === "idea" ? KNOWN_IDEA : KNOWN_BRIEF;
+            const extra = f.doc.headings
+                .map(normaliseHeading)
+                .filter((h) => !known.some((k) => h === k || h.startsWith(`${k} `)) && !h.includes("decision questions") && h !== "impact" && !isGuardrails(h));
+            for (const h of extra)
+                notCarried.set(`${f.kind}: ${h}`, (notCarried.get(`${f.kind}: ${h}`) ?? 0) + 1);
+        }
+        // Mentioned and committed paths already cited are listed once, as cited.
+        const has = (l, x) => l.some((c) => c.sdd === x.sdd && c.path === x.path);
+        e.titled = e.titled.filter((x) => !has(e.cited, x));
+        e.mentioned = e.mentioned.filter((x) => !has(e.cited, x) && !has(e.titled, x));
+        e.committed = e.committed.filter((x) => !has(e.cited, x) && !has(e.titled, x) && !has(e.mentioned, x));
+        e.planned = e.planned.filter((x) => !has(e.cited, x) && !has(e.titled, x) && !has(e.mentioned, x) && !has(e.committed, x));
+        // Home: the SDD most of the evidence is in, unless a reviewer set it.
+        const count = new Map();
+        for (const x of [...e.cited, ...e.mentioned, ...e.committed, ...e.planned])
+            count.set(x.sdd, (count.get(x.sdd) ?? 0) + 1);
+        // A file titled with the id outweighs the rest: an application's own Epic Brief places its request there.
+        for (const x of e.titled)
+            count.set(x.sdd, (count.get(x.sdd) ?? 0) + TITLED_WEIGHT);
+        const ranked = [...count.entries()].sort((a, b) => b[1] - a[1]);
+        let home = defaultHome;
+        const set = opts.homes?.get(id);
+        if (set) {
+            const s = sdds.find((x) => x.id === set);
+            if (s)
+                home = s;
+            else
+                flag(id, `--home names ${set}, which is not one of the SDDs`);
+        }
+        else if (ranked.length === 0) {
+            flag(id, e.plans.length || e.commits.length ? (e.commits.length ? "no artefact found; commits only" : "plan only: check that the work landed") : "no evidence found");
+        }
+        else {
+            if (ranked.length > 1 && ranked[0][1] === ranked[1][1])
+                flag(id, `home ambiguous: ${ranked.map(([s, n]) => `${s} ${n}`).join(", ")}`);
+            home = sdds.find((s) => s.id === ranked[0][0]);
+            if (e.cited.length + e.titled.length + e.mentioned.length + e.committed.length === 0)
+                flag(id, "planned paths only: check that the work landed");
+        }
+        const classification = (fields("Classification") || "").toLowerCase();
+        const isMethod = classification.startsWith("method") || /(^|\/)method\//.test(relative(sourceRoot(primary.path, sourceRepos), primary.path));
+        const dir = isMethod ? "content/method/intents" : "content/product/intents";
+        const path = `${dir}/${slug(primary.path, id)}`;
+        const where = [
+            ...e.cited.map((c) => `- \`${c.path}\` (${c.sdd}; cited)`),
+            ...e.titled.map((c) => `- \`${c.path}\` (${c.sdd}; titled)`),
+            ...e.mentioned.map((c) => `- \`${c.path}\` (${c.sdd}; mentioned)`),
+            ...e.committed.map((c) => `- \`${c.path}\` (${c.sdd}; committed in ${c.sha}${c.with.length ? ` with ${c.with.join(", ")}` : ""})`),
+            ...e.planned.map((c) => `- \`${c.path}\` (${c.sdd}; planned in ${c.plan}${c.with.length ? ` with ${c.with.join(", ")}` : ""})`),
+            ...e.commits.slice(0, 8).map((c) => `- commit \`${c.sha}\` in ${c.sdd}: ${c.subject}`),
+            ...e.plans.map((p) => `- plan \`${p.path}\` in ${p.repo}`),
+        ];
+        if (e.commits.length > 8)
+            where.push(`- ${e.commits.length - 8} more commit(s) name ${id}`);
+        const srcs = [idea, brief].filter(Boolean).map((f) => {
+            const r = sourceRepos.get(sourceDirOf(f.path, sourceRepos));
+            return { f: f, repo: basename(r.top), rel: relative(r.top, f.path), head: r.head };
+        });
+        const originator = `${fields("Owner") || "not recorded"}. Migrated from ${srcs.map((s) => `the ${s.f.kind === "idea" ? "Idea" : "Epic Brief"} \`${s.rel}\``).join(" and ")} in ${srcs[0].repo} at ${srcs[0].head}.`;
+        const outcome = [section(idea, "idea summary"), section(idea, "why explore this")].filter(Boolean).join("\n\n") || section(brief, "scope");
+        const open = [section(idea, "open questions"), ...matching(idea, (h) => h.includes("decision questions"))].filter(Boolean).join("\n\n") ||
+            section(brief, "resolved and open questions", "resolved vs open questions", "resolved vs open");
+        const affected = [section(idea, "early impact notes"), ...matching(idea, (h) => h === "impact")].filter(Boolean).join("\n\n");
+        const constraints = [section(brief, "dependencies and constraints", "dependencies"), ...matching(idea, isGuardrails), ...matching(brief, isGuardrails)]
+            .filter(Boolean)
+            .join("\n\n");
+        const decision = fields("Decision to Resolve in Exploration") || section(brief, "decision to resolve");
+        const body = [
+            `# Intent: ${titleOf(primary)}`,
+            "",
+            `**Work item:** ${id}`,
+            `**Captured:** ${fields("Created") || "not recorded"}`,
+            `**Originator:** ${originator}`,
+            "",
+            "## Problem",
+            "",
+            section(idea, "problem or opportunity") || section(brief, "problem statement") || "Not recorded in the source.",
+            "",
+            "## Proposed outcome",
+            "",
+            outcome || "Not recorded in the source.",
+            "",
+            "## Affected users and systems",
+            "",
+            affected || "Not recorded in the source.",
+            "",
+            "## Constraints",
+            "",
+            constraints || "Not recorded in the source.",
+            "",
+            "## Open questions",
+            "",
+            open || "None recorded.",
+            "",
+            "## Decision to resolve in exploration",
+            "",
+            decision || "None.",
+            "",
+            "## ADR requirement",
+            "",
+            adrRequirement(fields("ADR Requirement")),
+            "",
+            "## Where it went",
+            "",
+            ...(where.length ? where : ["- Nothing found: see the migration report."]),
+            "",
+        ].join("\n");
+        intents.push({ sdd: home, path, body });
+        for (const s of srcs)
+            citations.push([id, s.f.kind, s.repo, s.rel, home.id, path].join("\t"));
+        const row = map.get(id);
+        const statusRaw = row?.status || brief?.doc.fields.get("Status") || idea?.doc.fields.get("Status") || "";
+        const st = statusRaw.toLowerCase().replace(/[`*]/g, "").trim();
+        const reviewed = opts.statuses?.get(id);
+        const closed = reviewed ? reviewed === "closed" : CLOSED.has(st) || DECLINED.has(st);
+        items.push({
+            alias: id,
+            title: titleOf(primary),
+            status: closed ? "closed" : "open",
+            ...(closed ? { closed_reason: !reviewed && DECLINED.has(st) ? "declined" : "completed" } : {}),
+            ...(row?.priority ? { priority: row.priority } : {}),
+            intent: { sdd: home.id, path },
+            ...(idsIn(fields("Parent Idea"))[0] ? { parent: idsIn(fields("Parent Idea"))[0] } : {}),
+            children: idsIn(fields("Child Ideas")),
+            depends_on: [...new Set([...(row?.depends ?? []), ...idsIn(fields("Blocked by"))])].filter((d) => d !== id),
+            labels: (fields("Theme") || "").split("|").map((s) => s.trim()).filter(Boolean),
+            ...(statusRaw ? { source_status: statusRaw } : {}),
+        });
+    }
+    // 4. Write.
+    await mkdir(opts.out, { recursive: true });
+    await writeFile(join(opts.out, "work-items.json"), `${JSON.stringify(items, null, 2)}\n`);
+    await writeFile(join(opts.out, "citations.tsv"), `${citations.join("\n")}\n`);
+    if (opts.write) {
+        for (const i of intents) {
+            const full = join(i.sdd.dir, i.path);
+            if (existsSync(full)) {
+                skippedExisting.push(`${i.sdd.id}: ${i.path}`);
+                continue;
+            }
+            await mkdir(dirname(full), { recursive: true });
+            await writeFile(full, i.body);
+            written.push(`${i.sdd.id}: ${i.path}`);
+        }
+    }
+    else {
+        for (const i of intents) {
+            const full = join(opts.out, "intents", i.sdd.id, i.path);
+            await mkdir(dirname(full), { recursive: true });
+            await writeFile(full, i.body);
+        }
+    }
+    const homes = new Map();
+    for (const i of intents)
+        homes.set(i.sdd.id, (homes.get(i.sdd.id) ?? 0) + 1);
+    const pairs = [...byId.values()];
+    const supported = (k) => [...ev.values()].filter((e) => e[k].length > 0).length;
+    const report = [
+        "# Intent migration report",
+        "",
+        `Mode: ${opts.write ? "write" : "dry run (intents under intents/ here, not in the SDDs)"}.`,
+        `Request ids: ${ids.size} (${pairs.filter((p) => p.idea && p.brief).length} with an Idea and an Epic Brief, ${pairs.filter((p) => p.idea && !p.brief).length} with an Idea only, ${pairs.filter((p) => !p.idea && p.brief).length} with a Brief only).`,
+        `Work items: ${items.filter((i) => i.status === "closed").length} closed, ${items.filter((i) => i.status === "open").length} open.`,
+        `Homes: ${[...homes.entries()].map(([s, n]) => `${s} ${n}`).join(", ")}.`,
+        `Evidence, ids supported by each source: cited ${supported("cited")}, titled ${supported("titled")}, mentioned ${supported("mentioned")}, committed ${supported("committed")}, planned ${supported("planned")}, commit ${supported("commits")}, plan ${supported("plans")}.`,
+        "",
+        `## Flagged (${flags.size})`,
+        "",
+        ...([...flags.entries()].sort((a, b) => compareIds(a[0], b[0])).map(([id, w]) => `- ${id}: ${w.join("; ")}`)),
+        "",
+        `## Source headings not recognised (${notCarried.size} distinct)`,
+        "",
+        "Not carried into intents. Review the list for a heading that should map to an intent section.",
+        "",
+        ...[...notCarried.entries()].sort((a, b) => b[1] - a[1]).map(([h, n]) => `- ${n} × ${h}`),
+        "",
+        `## Index files, not counted as evidence (${indexFiles.length}; threshold ${opts.indexThreshold} ids)`,
+        "",
+        ...indexFiles.map((f) => `- ${f}`),
+        "",
+        `## Not read as an Idea or Epic Brief (${unrecognised.length})`,
+        "",
+        ...unrecognised.map((f) => `- ${f}`),
+        "",
+        ...(opts.write ? [`## Written (${written.length})`, "", ...written.map((w) => `- ${w}`), "", `## Not written: a file exists (${skippedExisting.length})`, "", ...skippedExisting.map((w) => `- ${w}`), ""] : []),
+    ].join("\n");
+    await writeFile(join(opts.out, "report.md"), report);
+    return { ids: ids.size, written, skippedExisting, flags, unrecognised };
+}
+function readFileSyncSafe(p) {
+    try {
+        return readFileSync(p, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function compareIds(a, b) {
+    const na = Number(/\d+$/.exec(a)?.[0] ?? 0);
+    const nb = Number(/\d+$/.exec(b)?.[0] ?? 0);
+    return a.replace(/\d+$/, "").localeCompare(b.replace(/\d+$/, "")) || na - nb;
+}
+function slug(path, id) {
+    const b = basename(path, ".md").toLowerCase();
+    return b.startsWith(id.toLowerCase()) ? `${b}.md` : `${id.toLowerCase()}-${b}.md`;
+}
+function sourceDirOf(p, repos) {
+    return [...repos.keys()].filter((d) => p.startsWith(`${d}/`)).sort((a, b) => b.length - a.length)[0] ?? dirname(p);
+}
+function sourceRoot(p, repos) {
+    return repos.get(sourceDirOf(p, repos))?.top ?? dirname(p);
+}
+//# sourceMappingURL=migrate.js.map