@sdd-method/author-cli 0.9.0 → 0.10.0

package/dist/author-program.js

@@ -47,6 +47,7 @@ export const AUTHOR_ONLY_SURFACE = [
     "context pull",
     "catalogue check",
     "migrate vocabulary",
+    "migrate intents",
 ];
 /** The full surface: verify's, plus the author's own. */
 export const AUTHOR_SURFACE = [...VERIFY_SURFACE, ...AUTHOR_ONLY_SURFACE];

package/dist/lib/intents/format.js

@@ -0,0 +1,77 @@
+// The intent artefact's shape (M-ADR 0227 §4.1), shared by the migration that writes intents and the check
+// that reads them. The section names and header lines are the shipped template's
+// (docs/method/methods/templates/intent-template.md), so a change there is a change here.
+export const INTENT_DIRS = ["content/method/intents", "content/product/intents"];
+export const INTENT_SECTIONS = [
+    "Problem",
+    "Proposed outcome",
+    "Affected users and systems",
+    "Constraints",
+    "Open questions",
+    "Decision to resolve in exploration",
+    "ADR requirement",
+    "Where it went",
+];
+/** Header fields of the retired Idea and the idea map: planning state, which belongs in the work item (§4.3). */
+export const PLANNING_FIELDS = [
+    "Status",
+    "Priority",
+    "Blocked by",
+    "Enables",
+    "Parent Idea",
+    "Child Ideas",
+    "Idea ID",
+    "Epic ID",
+    "Theme",
+];
+/** A "Where it went" line naming a path: "- `<path>` (<sdd-id>; <source>)". */
+export const WHERE_PATH_LINE = /^-\s+`([^`]+)`\s+\(([^;)]+);\s*([^)]+)\)\s*$/;
+/** "## 3. Why Explore This (Revised)" -> "why explore this". */
+export function normaliseHeading(h) {
+    return h
+        .replace(/^\s*\d+[A-Za-z]?(\.\d+)*\.?\s*/, "")
+        .replace(/\((revised|updated)\)\s*$/i, "")
+        .trim()
+        .toLowerCase();
+}
+export function parseMarkdown(text) {
+    const lines = text.split("\n");
+    let title = "";
+    const fields = new Map();
+    const sections = new Map();
+    const headings = [];
+    let current = null;
+    let buf = [];
+    const flush = () => {
+        if (current !== null) {
+            const prev = sections.get(current);
+            const body = buf.join("\n").trim();
+            sections.set(current, prev ? `${prev}\n\n${body}` : body);
+        }
+        buf = [];
+    };
+    for (const line of lines) {
+        const h1 = /^#\s+(.+?)\s*$/.exec(line);
+        if (h1 && !title && current === null) {
+            title = h1[1];
+            continue;
+        }
+        const h2 = /^##\s+(.+?)\s*$/.exec(line);
+        if (h2) {
+            flush();
+            headings.push(h2[1]);
+            current = normaliseHeading(h2[1]);
+            continue;
+        }
+        if (current === null) {
+            const f = /^\*\*([^*:]+):\*\*\s*(.*?)\s*$/.exec(line);
+            if (f)
+                fields.set(f[1].trim(), f[2]);
+            continue;
+        }
+        buf.push(line);
+    }
+    flush();
+    return { title, fields, sections, headings };
+}
+//# sourceMappingURL=format.js.map

package/dist/lib/intents/migrate.js

@@ -0,0 +1,644 @@
+// `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);
+//   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).
+// 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;
+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
+    }
+    return { dir, id, repoNames, managed: await managedPaths(dir), renames };
+}
+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)");
+    // 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: [], 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;
+            if (hits.length > opts.indexThreshold) {
+                indexFiles.push(`${s.id}: ${rel} (${hits.length} ids)`);
+                continue;
+            }
+            for (const id of hits) {
+                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.mentioned = e.mentioned.filter((x) => !has(e.cited, x));
+        e.committed = e.committed.filter((x) => !has(e.cited, x) && !has(e.mentioned, x));
+        e.planned = e.planned.filter((x) => !has(e.cited, 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);
+        const ranked = [...count.entries()].sort((a, b) => b[1] - a[1]);
+        let home = sdds[0];
+        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.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.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")}, 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

package/dist/lib/validate/dispatch.js

@@ -1,6 +1,7 @@
 import { checkArchetypeCitations } from "./archetype-citations.js";
 import { checkBehaviourStore, checkBehaviourStoreOpenspec } from "./behaviour-store.js";
 import { checkBundleCoherence } from "./bundle-coherence.js";
+import { checkIntents } from "./intents.js";
 import { checkYamlParse } from "./yaml-parse.js";
 // The behaviour store (M-ADR 0221-0223) can sit in an SDD of any profile, so every profile carries
 // its two checks; without a store both report [N/A], an empty population, not a pass.
@@ -21,6 +22,12 @@ const BEHAVIOUR_STORE_VALIDATORS = [
         source: { kind: "native", run: async (ctx) => checkArchetypeCitations(ctx.targetRepo) },
         build: () => ({ status: "run", args: [] }),
     },
+    // Intents (M-ADR 0227) can sit in an SDD of any profile; without any the check reports [N/A].
+    {
+        name: "intents",
+        source: { kind: "native", run: async (ctx) => checkIntents(ctx.targetRepo) },
+        build: () => ({ status: "run", args: [] }),
+    },
 ];
 // Validators that accept --app-root / --repo-root flags work fine from the
 // bundled location because they override their internal ROOT_DIR via the

package/dist/lib/validate/intents.js

@@ -0,0 +1,76 @@
+// intents: every intent file (M-ADR 0227 §4.1) has the template's shape, carries no planning state, names its
+// work item, and every path its "Where it went" names in this SDD exists.
+//
+// Read from content/method/intents/ and content/product/intents/. A path line in "Where it went" is
+// "- `<path>` (<sdd-id>; <source>)"; only paths labelled with this SDD's id are checked here, since another
+// SDD's paths resolve in that SDD. Commit and plan lines are records, not paths, and are not checked. An
+// intent with nothing yet in "Where it went" is captured but not explored: counted, not failed. With no
+// intents the check reports [N/A], an empty population, not a pass.
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { parseDocument } from "yaml";
+import { INTENT_DIRS, INTENT_SECTIONS, PLANNING_FIELDS, WHERE_PATH_LINE, parseMarkdown } from "../intents/format.js";
+async function sddId(repo) {
+    try {
+        const m = parseDocument(await readFile(join(repo, ".sdd/sdd-manifest.yaml"), "utf8")).toJS();
+        if (typeof m?.sdd_id === "string" && m.sdd_id)
+            return m.sdd_id;
+    }
+    catch {
+        // fall through
+    }
+    return basename(repo);
+}
+export async function checkIntents(repo) {
+    const files = [];
+    for (const d of INTENT_DIRS) {
+        try {
+            for (const e of await readdir(join(repo, d), { withFileTypes: true })) {
+                if (e.isFile() && e.name.endsWith(".md") && e.name.toLowerCase() !== "readme.md")
+                    files.push(`${d}/${e.name}`);
+            }
+        }
+        catch {
+            // no such directory
+        }
+    }
+    if (files.length === 0)
+        return { exitCode: 0, stdout: "[N/A] no intents (content/{method,product}/intents/*.md) in this repository\n" };
+    const self = await sddId(repo);
+    const problems = [];
+    let unexplored = 0;
+    let pathsChecked = 0;
+    for (const rel of files.sort()) {
+        const text = await readFile(join(repo, rel), "utf8");
+        const doc = parseMarkdown(text);
+        if (!/^Intent:\s*\S/.test(doc.title))
+            problems.push(`${rel}: no "# Intent: <title>" line`);
+        for (const s of INTENT_SECTIONS)
+            if (!doc.sections.has(s.toLowerCase()))
+                problems.push(`${rel}: no "## ${s}" section`);
+        const wi = doc.fields.get("Work item")?.trim() ?? "";
+        if (!wi || /^<.*>$/.test(wi))
+            problems.push(`${rel}: no work item named (**Work item:**)`);
+        for (const f of PLANNING_FIELDS)
+            if (doc.fields.has(f))
+                problems.push(`${rel}: planning field **${f}:** belongs in the work item (M-ADR 0227 §4.3)`);
+        const where = (doc.sections.get("where it went") ?? "").split("\n").map((l) => l.trim()).filter((l) => l.startsWith("- "));
+        if (where.length === 0)
+            unexplored++;
+        for (const line of where) {
+            const m = WHERE_PATH_LINE.exec(line);
+            if (!m || m[2].trim() !== self)
+                continue;
+            pathsChecked++;
+            const p = m[1].replace(/[#?].*$/, "");
+            if (!existsSync(join(repo, p)))
+                problems.push(`${rel}: "Where it went" names ${p}, which does not exist`);
+        }
+    }
+    const head = `intents: ${files.length} intent(s); ${pathsChecked} "Where it went" path(s) in this SDD checked; ${unexplored} not yet explored\n`;
+    if (problems.length === 0)
+        return { exitCode: 0, stdout: `${head}[PASS] intents: ok\n` };
+    return { exitCode: 1, stdout: `${head}${problems.map((p) => `[FAIL] ${p}\n`).join("")}[FAIL] intents: ${problems.length} problem(s)\n` };
+}
+//# sourceMappingURL=intents.js.map

package/dist/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.10.0",
-  "built_against_sdd_cli": "2.4.0"
+  "version": "0.11.0",
+  "built_against_sdd_cli": "2.5.0"
 }

package/dist/verbs/migrate.js

@@ -1,4 +1,5 @@
 import { resolve } from "node:path";
+import { migrateIntents } from "../lib/intents/migrate.js";
 import { migrateVocabulary } from "../lib/vocabulary/migrate.js";
 /**
  * `migrate vocabulary` (M-ADR 0222 §4.1): rewrite the SDD's own files from the former tool-read values to the
@@ -28,5 +29,48 @@ export function registerMigrate(program) {
         if (r.rewrites.length > 0)
             process.exit(1);
     });
+    const many = (v, prev) => [...prev, v];
+    migrate
+        .command("intents")
+        .description("Turn Ideas and Epic Briefs into intents (M-ADR 0227), one per request id: an Idea and its Epic Brief are one " +
+        "request at two stages. Rebuilds each intent's \"Where it went\" from evidence (paths the sources cite, SDD files " +
+        "and commits naming the id, plan files naming it) and writes the planning state to a tool-neutral work-item " +
+        "import file, with a table of old paths to intents for re-pointing citations. Dry run unless --write; never " +
+        "overwrites an existing intent")
+        .requiredOption("--source <dir>", "a directory of Idea and Epic Brief files, searched recursively (repeatable)", many, [])
+        .option("--sdd <dir>", "an SDD searched for evidence and offered as a home; the first is the default home (repeatable; default: the current directory)", many, [])
+        .option("--plans <dir>", "a directory of plan files: evidence only, never converted (repeatable)", many, [])
+        .option("--idea-map <file>", "the idea map, for status, priority and dependency edges")
+        .option("--out <dir>", "where the report, work-items.json and citations.tsv go", "intent-migration")
+        .option("--index-threshold <n>", "a file naming more request ids than this is an index, not evidence", "5")
+        .option("--home <id=sdd-id>", "a reviewer's home for a request id (repeatable)", many, [])
+        .option("--status <id=open|closed>", "a reviewer's status for a request id (repeatable)", many, [])
+        .option("--write", "write each intent into the SDD it is placed in, under every --sdd named (default: a dry run that writes them under --out)")
+        .action(async (o) => {
+        const pairs = (list, name) => new Map(list.map((x) => {
+            const [k, v] = x.split("=");
+            if (!k || !v)
+                throw new Error(`--${name} takes <id>=<value>, not "${x}"`);
+            return [k.trim(), v.trim()];
+        }));
+        const statuses = pairs(o.status, "status");
+        for (const [k, v] of statuses)
+            if (v !== "open" && v !== "closed")
+                throw new Error(`--status ${k}=${v}: the status is open or closed`);
+        const r = await migrateIntents({
+            sources: o.source,
+            sdds: o.sdd.length ? o.sdd : [process.cwd()],
+            plans: o.plans,
+            ...(o.ideaMap ? { ideaMap: o.ideaMap } : {}),
+            out: resolve(o.out),
+            write: o.write === true,
+            indexThreshold: Number(o.indexThreshold),
+            homes: pairs(o.home, "home"),
+            statuses: statuses,
+        });
+        process.stdout.write(`[INFO] migrate intents: ${r.ids} request id(s); ${r.flags.size} flagged; ${r.unrecognised.length} file(s) not read as an Idea or Epic Brief\n` +
+            (o.write ? `[INFO] migrate intents: wrote ${r.written.length} intent(s); ${r.skippedExisting.length} not written (a file exists)\n` : "") +
+            `[INFO] migrate intents: report, work-items.json and citations.tsv in ${resolve(o.out)}\n`);
+    });
 }
 //# sourceMappingURL=migrate.js.map

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "2.4.0",
-  "built_against_sdd_cli": "2.4.0"
+  "version": "2.5.0",
+  "built_against_sdd_cli": "2.5.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sdd-method/author-cli",
-  "version": "0.9.0",
-  "sddCliVersion": "2.4.0",
+  "version": "0.10.0",
+  "sddCliVersion": "2.5.0",
   "description": "Re-author one SDD's content — scaffold, plan, contracts, conformance, api-surface, snapshots, briefings, catalogue check — plus every read-only verify verb. Ships only the code those verbs reach; it cannot sync the baseline or rebuild the catalogues. Maintenance is in @sdd-method/maintain-cli, administration in @sdd-method/sdd-cli.",
   "license": "UNLICENSED",
   "type": "module",