@sdd-method/author-cli 0.8.0 → 0.10.0

package/dist/lib/scaffold/archetype-behaviour.js

@@ -1,4 +1,4 @@
-// Archetype behaviour, seeded once and then cited (reference architecture sdm-d93u.4.1).
+// Archetype behaviour, seeded once and then cited.
 //
 // A reference-architecture archetype ships its behaviour as canonical rows (behaviour.tql, rows of the
 // behaviour schema in the M-ADR 0210 subset). An estate does not sync them: it takes them ONCE, when it
@@ -131,7 +131,7 @@ async function writeAt(path, content) {
 export async function seedArchetypeBehaviour(input) {
     const store = join(input.targetRepo, "openspec");
     if (!(await exists(store)))
-        return { filesWritten: [], skipped: "no behaviour store (openspec/) in this repository" };
+        return { filesWritten: [], skipped: "no behaviour store (openspec/) in this repository; `sdd-cli scaffold behaviour-store` creates one" };
     const reqs = await loadArchetypeBehaviour(input.bundleCacheDir, input.seeds);
     if (!reqs || reqs.length === 0)
         return { filesWritten: [], skipped: `archetype ${input.archetypeId} ships no behaviour rows` };
@@ -154,8 +154,10 @@ export async function seedArchetypeBehaviour(input) {
         `# ${CITATIONS_FILE} — the ${input.domain} domain's requirements that answer to reference-architecture archetype requirements.`,
         "# Seeded once from the archetype; the requirements are this estate's. Per citation: `requirement` is this estate's",
         "# requirement title, `cites` the archetype requirement id, `digest` that requirement at `version`, and `relation` one of",
-        "# derived | extended | narrowed | departed (departed needs `reason` and `decision`). Checked by",
-        "# `sdd-cli validate --validator archetype-citations`: a changed source is reported until reviewed and re-pinned.",
+        "# derived | extended | narrowed | departed (departed needs `reason` and `decision`; narrowed and extended may give",
+        "# a `reason`). Keep `digest` quoted. An archetype requirement this estate decides not to take goes under",
+        "# `not_adopted:` as {cites, reason, decision}. Checked by `sdd-cli validate --validator archetype-citations`: a",
+        "# changed source is reported until reviewed and re-pinned, and requirements neither cited nor not adopted are listed.",
         "",
     ].join("\n");
     const files = [

package/dist/lib/scaffold/behaviour-store.js

@@ -0,0 +1,60 @@
+// Create an SDD's behaviour store, inside the SDD (M-ADR 0221 §4.2): an OpenSpec project at
+// openspec/ that selects the method's sdd-change schema (M-ADR 0223 §4.2). A store is created when
+// its SDD first drafts a proposed change, agrees a change or baselines behaviour, not in advance, so this is an authoring step,
+// never part of sync. Sync keeps the schema copy current afterwards.
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { parseDocument } from "yaml";
+import { SHIPPED_CONFIG_TEMPLATE, SHIPPED_SCHEMA_DIR, STORE_CONFIG, STORE_SCHEMA_DIR, writeStoreSchema } from "../behaviour-store/schema.js";
+import { MANIFEST_REL_PATH } from "../catalogue/manifest-loader.js";
+export const STORE_KEEP_FILES = ["openspec/specs/.gitkeep", "openspec/changes/archive/.gitkeep", "docs/agreements/.gitkeep"];
+async function exists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The refusal, or null when the store can be created. */
+export async function storeScaffoldRefusal(repo) {
+    if (await exists(join(repo, "openspec"))) {
+        return "openspec/ already exists: this SDD has a behaviour store. Sync keeps its schema copy current.";
+    }
+    if (!(await exists(join(repo, SHIPPED_SCHEMA_DIR, "schema.yaml"))) || !(await exists(join(repo, SHIPPED_CONFIG_TEMPLATE)))) {
+        return `this SDD holds no shipped ${SHIPPED_SCHEMA_DIR}/ and ${SHIPPED_CONFIG_TEMPLATE}: sync a method bundle that carries them first.`;
+    }
+    return null;
+}
+export async function scaffoldBehaviourStore(repo) {
+    const refusal = await storeScaffoldRefusal(repo);
+    if (refusal !== null)
+        throw new Error(refusal);
+    let sddId = null;
+    try {
+        const m = parseDocument(await readFile(join(repo, MANIFEST_REL_PATH), "utf8")).toJS();
+        if (typeof m?.sdd_id === "string" && m.sdd_id.length > 0)
+            sddId = m.sdd_id;
+    }
+    catch {
+        sddId = null;
+    }
+    const template = await readFile(join(repo, SHIPPED_CONFIG_TEMPLATE), "utf8");
+    const config = sddId === null ? template : template.replaceAll("<sdd-id>", sddId);
+    const filesWritten = [];
+    await mkdir(dirname(join(repo, STORE_CONFIG)), { recursive: true });
+    await writeFile(join(repo, STORE_CONFIG), config);
+    filesWritten.push(STORE_CONFIG);
+    for (const rel of STORE_KEEP_FILES) {
+        if (await exists(join(repo, dirname(rel))))
+            continue;
+        await mkdir(join(repo, dirname(rel)), { recursive: true });
+        await writeFile(join(repo, rel), "");
+        filesWritten.push(rel);
+    }
+    const copied = await writeStoreSchema(repo);
+    filesWritten.push(...copied.missing.map((f) => `${STORE_SCHEMA_DIR}/${f}`));
+    return { filesWritten, sddId };
+}
+//# sourceMappingURL=behaviour-store.js.map

package/dist/lib/validate/archetype-citations.js

@@ -11,6 +11,13 @@
 //               (move `digest` and `version`), or record that the estate departs.
 // A departed citation is never stale: departing is a decision, recorded with its reason, not drift. With no
 // citations anywhere the check reports [N/A], an empty population, not a pass.
+//
+// A digest must be a quoted string: YAML reads an unquoted all-digit value, or digits around one `e`, as a
+// number, which would compare as a false stale. A narrowed or extended citation may say why in `reason`
+// (`note` is read as the same). `not_adopted` records archetype requirements the estate has decided not to
+// take, each with its reason and decision; every id must resolve, and none may be both cited and not adopted.
+// A coverage line names the archetype requirements neither cited nor recorded as not adopted: the gaps, which
+// are reported, not failed, since an estate may be part-way through adopting.
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
@@ -92,12 +99,34 @@ export async function checkArchetypeCitations(repo) {
         const byId = new Map((reqs ?? []).map((r) => [r.id, r]));
         const at = cachedVersion(archetype.bundleCacheDir) ?? "the cached bundle";
         const cites = Array.isArray(doc.citations) ? doc.citations : [];
-        if (cites.length === 0)
+        const notAdopted = Array.isArray(doc.not_adopted) ? doc.not_adopted : [];
+        if (cites.length === 0 && notAdopted.length === 0)
             bad("unresolved", `${rel}: lists no citations`);
+        const citedIds = new Set(cites.map((c) => String(c.cites)));
+        for (const n of notAdopted) {
+            total++;
+            const tag = `${rel}: not adopted ${String(n.cites)}`;
+            if (!byId.has(String(n.cites))) {
+                bad("unresolved", `${tag}: ${archetype.bundleName} ${at} has no archetype requirement ${String(n.cites)}`);
+            }
+            else if (!n.reason || !n.decision) {
+                bad("unresolved", `${tag}: a non-adoption needs its reason and the decision that took it`);
+            }
+            else if (citedIds.has(String(n.cites))) {
+                bad("unresolved", `${tag}: it is also cited; an archetype requirement is either answered or not adopted`);
+            }
+            else {
+                lines.push(`[ok] ${tag} (${String(n.reason)})`);
+            }
+        }
         for (const c of cites) {
             total++;
             const tag = `${rel}: '${String(c.requirement)}' -> ${String(c.cites)}`;
             const relation = String(c.relation);
+            if (typeof c.digest !== "string") {
+                bad("unresolved", `${tag}: digest must be a quoted string (YAML read ${String(c.digest)} as a ${typeof c.digest}); quote it`);
+                continue;
+            }
             if (!RELATIONS.includes(relation)) {
                 bad("unresolved", `${tag}: relation must be one of ${RELATIONS.join(", ")} (got ${relation})`);
                 continue;
@@ -122,9 +151,15 @@ export async function checkArchetypeCitations(repo) {
                 bad("stale", `${tag}: the archetype requirement changed (${String(c.digest)} at ${String(doc.version)} -> ${src.digest} at ${at}); review it and re-pin, or record a departure`);
             }
             else {
-                lines.push(`[ok] ${tag} (${relation})`);
+                const why = c.reason ?? c.note;
+                lines.push(`[ok] ${tag} (${relation}${why && relation !== "derived" ? `: ${String(why)}` : ""})`);
             }
         }
+        const answered = new Set([...citedIds, ...notAdopted.map((n) => String(n.cites))]);
+        const gaps = [...byId.keys()].filter((id) => !answered.has(id));
+        lines.push(`[coverage] ${rel}: ${byId.size - gaps.length} of ${byId.size} ${archetype.id} requirements answered ` +
+            `(${[...citedIds].filter((id) => byId.has(id)).length} cited, ${notAdopted.length} not adopted)` +
+            (gaps.length ? `; not yet answered: ${gaps.join(", ")}` : ""));
     }
     const verdict = problems
         ? `[FAIL] archetype citations: ${problems} of ${total} unresolved or stale`

package/dist/lib/validate/behaviour-store.js

@@ -25,6 +25,11 @@
 //                 build finding; this check makes it a failure, so a shipped requirement cannot vanish from the
 //                 catalogue with every check green. Without catalogues/features.csv the check is unresolved, not
 //                 passed.
+//   8. overlap:  no requirement of a living spec is named by two open, agreed changes, whether added,
+//                 modified, removed or renamed (M-ADR 0223 §4.10). Proposals may overlap.
+//   9. schema:   the store's config.yaml selects the method's sdd-change schema, and the store's copy of it
+//                 (openspec/schemas/sdd-change/) is identical to the one the SDD's bundle shipped
+//                 (docs/method/foundations/openspec/sdd-change/). Sync refreshes the copy (M-ADR 0223 §4.2).
 //   6. scope:    a baseline ADDS requirements; it REMOVES, MODIFIES or RENAMES only a requirement whose
 //                 latest archived change was a baseline, which is how a corrective baseline withdraws
 //                 what a baseline admitted wrongly. A requirement a judged change shipped is changed only
@@ -34,14 +39,18 @@
 //
 // OPENSPEC'S OWN VALIDATION is the separate validator `behaviour-store-openspec`, because it needs
 // the OpenSpec CLI at OPENSPEC_VERSION (the Method Validation module installs it). Without a store
-// both report [N/A], an empty population, never a pass.
+// both report [N/A], an empty population, never a pass. It also archives each open, agreed change in a
+// scratch copy of the store and validates the specs it would leave (M-ADR 0223 §4.5): a change's own
+// --strict run exempts its MODIFIED requirements from the 500-character limit the specs are held to.
 import { execFile } from "node:child_process";
-import { access, readdir, readFile } from "node:fs/promises";
+import { access, cp, mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import { promisify } from "node:util";
 import { parseDocument } from "yaml";
 import { observedIn, orderArchives, parseRequirements, parseSurfaces, renamedFrom, surfaceMatches } from "../behaviour-store/archive.js";
 import { parseCatalogueCsv } from "../catalogue/csv-reader.js";
+import { compareStoreSchema, SCHEMA_NAME, SHIPPED_SCHEMA_DIR, STORE_CONFIG, STORE_SCHEMA_DIR, storeSchemaName } from "../behaviour-store/schema.js";
 const execFileAsync = promisify(execFile);
 /** The OpenSpec release the method depends on (M-ADR 0223 ruling 2). The module installs exactly this. */
 export const OPENSPEC_VERSION = "1.14.3";
@@ -241,7 +250,9 @@ export async function checkBehaviourStore(repo) {
         const record = records.get(change);
         if (tasks !== null && TASK_DONE_RE.test(tasks)) {
             started++;
-            if (!record)
+            if (!record && recordFiles.some((f) => f.replace(/\.ya?ml$/, "") === change))
+                failures.push(`${dir}: has completed tasks but its agreement record (${AGREEMENTS_DIR}/${change}.yaml) is malformed; see its record failures`);
+            else if (!record)
                 failures.push(`${dir}: has completed tasks but no agreement record (${AGREEMENTS_DIR}/${change}.yaml)`);
             else if (record.status !== "agreed")
                 failures.push(`${dir}: has completed tasks but its agreement record is ${record.status}, not agreed`);
@@ -264,6 +275,29 @@ export async function checkBehaviourStore(repo) {
     }
     lines.push(`agreement: ${open.length} open change(s), ${started} with completed tasks`);
     lines.push(staleChecked === 0 ? "stale: vacuous (no open agreed change modifies, removes or renames a requirement)" : `stale: ${staleChecked} targeted living spec(s) checked against their agreed commits`);
+    // 8. overlap: two open, agreed changes never name the same requirement of one living spec (M-ADR 0223 §4.10).
+    // A name counts whether the delta adds, modifies, removes or renames it (both FROM and TO). Proposals may overlap.
+    const claimed = new Map();
+    let agreedOpen = 0;
+    for (const change of open) {
+        if (records.get(change)?.status !== "agreed")
+            continue;
+        agreedOpen++;
+        const specsDir = join(repo, STORE_DIR, "changes", change, "specs");
+        for (const spec of await dirs(specsDir)) {
+            const text = (await readText(join(specsDir, spec, "spec.md"))) ?? "";
+            const names = new Set([...parseRequirements(text).filter((r) => r.operation).map((r) => r.name), ...renamedFrom(text)]);
+            for (const name of names) {
+                const key = `${spec}::${name}`;
+                const other = claimed.get(key);
+                if (other)
+                    failures.push(`${STORE_DIR}/changes/${change}: OVERLAP: requirement "${name}" of ${spec} is also named by agreed change ${other}; one waits for the other to archive, or the two become one change (M-ADR 0223 §4.10)`);
+                else
+                    claimed.set(key, change);
+            }
+        }
+    }
+    lines.push(agreedOpen < 2 ? `overlap: vacuous (${agreedOpen} open agreed change)` : `overlap: ${claimed.size} requirement name(s) across ${agreedOpen} open agreed changes`);
     // 4. archived changes
     const archived = await dirs(join(repo, STORE_DIR, "changes", "archive"));
     let baselines = 0;
@@ -290,7 +324,31 @@ export async function checkBehaviourStore(repo) {
     lines.push(`verdicts: ${archived.length} archived change(s), ${baselines} baseline(s), ${archived.length - baselines} needing a PASS verdict`);
     // 5. surfaces, and 6. what each baseline may change, in archive order
     const archiveRel = `${STORE_DIR}/changes/archive`;
-    const { order, ties } = await orderArchives(repo, archiveRel, archived);
+    const { order, ties, history } = await orderArchives(repo, archiveRel, archived);
+    // Same-day archives the history cannot order sit in one group. A scope verdict that a group peer could reverse
+    // (it touches the same requirement) depends on an order nobody knows, so it is unresolved, not a violation. Without
+    // git history (a worktree upload, a plain copy, an export) every same-day pair is such a group.
+    const peers = new Map();
+    for (const [a, b] of ties) {
+        const group = peers.get(a) ?? peers.get(b) ?? new Set();
+        group.add(a).add(b);
+        peers.set(a, group).set(b, group);
+    }
+    const touches = new Map();
+    for (const name of peers.keys()) {
+        const keys = new Set();
+        for (const feature of await dirs(join(repo, archiveRel, name, "specs"))) {
+            const text = (await readText(join(repo, archiveRel, name, "specs", feature, "spec.md"))) ?? "";
+            for (const r of parseRequirements(text))
+                if (r.operation)
+                    keys.add(`${feature}::${r.name}`);
+            for (const from of renamedFrom(text))
+                keys.add(`${feature}::${from}`);
+        }
+        touches.set(name, keys);
+    }
+    const orderDecides = (name, key) => [...(peers.get(name) ?? [])].some((p) => p !== name && touches.get(p)?.has(key));
+    let scopeUnresolved = 0;
     const servedBy = baselines > 0 ? await catalogueContracts(repo) : null;
     let surfacesChecked = 0;
     const lastTouch = new Map();
@@ -338,7 +396,11 @@ export async function checkBehaviourStore(repo) {
                 if (isBaseline) {
                     scopeChecked++;
                     const last = lastTouch.get(key);
-                    if (last !== "baseline") {
+                    if (last !== "baseline" && orderDecides(name, key)) {
+                        scopeUnresolved++;
+                        failures.push(`${dir}: scope unresolved for "${t}" (${feature}): the verdict depends on the order of same-day archives the history cannot give${history ? "" : " (no git history here: run from a clone)"}`);
+                    }
+                    else if (last !== "baseline") {
                         failures.push(`${dir}: a baseline changes "${t}" (${feature}), which ${last === "change" ? "a judged change last shipped" : "no earlier archived change admitted"}; a baseline may remove or modify only what a baseline admitted, and anything else takes a change (M-ADR 0222 §4.4)`);
                     }
                 }
@@ -357,6 +419,10 @@ export async function checkBehaviourStore(repo) {
     const unseen = servedBy === null ? "" : `; repositories with no catalogue contracts: ${[...new Set(await observedInAll(repo, archiveRel, order))].filter((r) => (servedBy.get(r) ?? []).length === 0).join(", ") || "none"}`;
     lines.push(baselines === 0 ? "surfaces: vacuous (no baseline)" : `surfaces: ${baselines} baseline(s), ${surfacesChecked} served contract(s) checked against catalogues/repo_contract.csv${unseen}`);
     lines.push(scopeChecked === 0 ? "scope: vacuous (no baseline removes, modifies or renames a requirement)" : `scope: ${scopeChecked} requirement(s) a baseline removes, modifies or renames, checked against their lineage`);
+    if (!history && archived.length > 0)
+        lines.push("order: no git history (not a git work tree, or git log failed), so same-day archives cannot be ordered");
+    if (scopeUnresolved > 0)
+        lines.push(`scope: ${scopeUnresolved} verdict(s) unresolved, depending on an order the history cannot give`);
     for (const [a, b] of ties)
         lines.push(`order: ${a} and ${b} were archived the same day and the history does not order them; ordered by name`);
     // 7. living specs keyed by a catalogue feature
@@ -378,6 +444,30 @@ export async function checkBehaviourStore(repo) {
     else {
         lines.push("features: vacuous (no living spec)");
     }
+    // 9. schema: the store uses the method's sdd-change schema, and its copy is the one the SDD's bundle
+    // shipped (M-ADR 0223 §4.2). OpenSpec reads the copy, so an edited or stale copy changes what every
+    // change is asked for, with nothing else noticing.
+    const selected = await storeSchemaName(repo);
+    if (selected !== SCHEMA_NAME) {
+        failures.push(`${STORE_CONFIG}: ${selected === null ? "missing" : selected === "" ? "names no schema" : `selects schema "${selected}"`}; a behaviour store uses the method's ${SCHEMA_NAME} schema (M-ADR 0223 §4.2)`);
+    }
+    else {
+        const c = await compareStoreSchema(repo);
+        if (!c.shipped) {
+            failures.push(`schema unresolved: this SDD holds no shipped ${SCHEMA_NAME} schema (${SHIPPED_SCHEMA_DIR}/); sync a method bundle that carries it`);
+        }
+        else {
+            const fix = "sdd-cli sync refreshes it; put adopter guidance in the store's config.yaml rules, not in the schema";
+            for (const f of c.missing)
+                failures.push(`${STORE_SCHEMA_DIR}/${f}: missing from the store's copy of the schema; ${fix}`);
+            for (const f of c.differing)
+                failures.push(`${STORE_SCHEMA_DIR}/${f}: differs from the shipped ${SHIPPED_SCHEMA_DIR}/${f}; ${fix}`);
+            for (const f of c.extra)
+                failures.push(`${STORE_SCHEMA_DIR}/${f}: not in the shipped schema; ${fix}`);
+            const drift = c.missing.length + c.differing.length + c.extra.length;
+            lines.push(drift === 0 ? `schema: ${SCHEMA_NAME}, identical to the shipped copy` : `schema: ${SCHEMA_NAME}, ${drift} file(s) differ from the shipped copy`);
+        }
+    }
     const population = recordFiles.length + open.length + archived.length;
     const body = lines.map((l) => `  ${l}`).join("\n") + "\n";
     if (failures.length > 0) {
@@ -385,7 +475,7 @@ export async function checkBehaviourStore(repo) {
     }
     if (population === 0)
         return { exitCode: 0, stdout: body + `[N/A] the behaviour store has no changes and no agreement records yet\n` };
-    return { exitCode: 0, stdout: body + "[PASS] behaviour store: records, agreement, stale, verdict, surfaces, scope and feature checks hold\n" };
+    return { exitCode: 0, stdout: body + "[PASS] behaviour store: records, agreement, stale, overlap, verdict, surfaces, scope, feature and schema checks hold\n" };
 }
 /** Per repository, the contracts the catalogue says it serves (repo_contract ⋈ contracts.spec_path); null when either file is missing. */
 async function catalogueContracts(repo) {
@@ -476,6 +566,47 @@ export async function checkBehaviourStoreOpenspec(repo) {
         if (r.code !== 0 && (t.failed ?? 0) === 0)
             failures.push(`${label}: OpenSpec exited ${r.code} with no failed item reported`);
     }
+    // Each open, agreed change, archived in a scratch copy: the specs it would leave must validate --strict.
+    let dryArchived = 0;
+    for (const change of (await dirs(join(repo, STORE_DIR, "changes"))).filter((d) => d !== "archive")) {
+        const rel = `${AGREEMENTS_DIR}/${change}.yaml`;
+        const text = await readText(join(repo, rel));
+        if (text === null || parseAgreementRecord(rel, text).record?.status !== "agreed")
+            continue;
+        const scratch = await mkdtemp(join(tmpdir(), "sdd-dry-archive-"));
+        try {
+            await cp(join(repo, STORE_DIR), join(scratch, STORE_DIR), { recursive: true });
+            const label = `specs after archiving ${change} (dry, in a copy)`;
+            const a = await runOpenspec(scratch, ["archive", change, "--yes", "--json"]);
+            if (a.code !== 0) {
+                const said = [...a.raw.matchAll(/"(?:message|error)":\s*"((?:[^"\\]|\\.)*)"/g)].map((m) => m[1]);
+                failures.push(`${label}: the change does not archive (exit ${a.code}): ${said.length > 0 ? said.join("; ") : a.raw.trim().split("\n").slice(-3).join(" | ")}`);
+                continue;
+            }
+            dryArchived++;
+            const v = await runOpenspec(scratch, ["validate", "--specs", "--strict", "--json", "--no-interactive"]);
+            const t = v.json?.summary?.totals;
+            if (!t) {
+                failures.push(`${label}: OpenSpec returned no report (exit ${v.code}): ${v.raw.trim().split("\n").slice(-3).join(" | ")}`);
+                continue;
+            }
+            lines.push(`${label}: ${t.items ?? 0} spec(s), ${t.passed ?? 0} passed, ${t.failed ?? 0} failed`);
+            for (const item of v.json?.items ?? []) {
+                if (item.valid)
+                    continue;
+                for (const i of item.issues ?? [])
+                    failures.push(`${label}: ${item.id}${i.path ? ` (${i.path})` : ""}: ${i.level} ${i.message}`);
+                if ((item.issues ?? []).length === 0)
+                    failures.push(`${label}: ${item.id}: invalid`);
+            }
+            if (v.code !== 0 && (t.failed ?? 0) === 0)
+                failures.push(`${label}: OpenSpec exited ${v.code} with no failed spec reported`);
+        }
+        finally {
+            await rm(scratch, { recursive: true, force: true });
+        }
+    }
+    lines.push(`dry archive: ${dryArchived} open, agreed change(s) archived in a copy`);
     const body = [`  OpenSpec ${version}`, ...lines.map((l) => `  ${l}`)].join("\n") + "\n";
     if (failures.length > 0)
         return { exitCode: 1, stdout: body + failures.map((f) => `[FAIL] ${f}`).join("\n") + "\n" };

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.9.0",
-  "built_against_sdd_cli": "2.3.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/verbs/scaffold.js

@@ -2,12 +2,14 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { isMethodDomainArchetype, METHOD_DOMAIN_ARCHETYPES, scaffoldDomain, } from "../lib/scaffold/domain.js";
 import { resolveArchetype } from "../lib/scaffold/registry.js";
+import { scaffoldBehaviourStore, storeScaffoldRefusal } from "../lib/scaffold/behaviour-store.js";
 import { resolvePathOption } from "./path-option.js";
 const DOMAIN_NAME = /^[a-z][a-z0-9-]*$/;
 export function registerScaffold(program) {
     const scaffold = program
         .command("scaffold")
         .description("Scaffold method-shaped artefacts into an existing SDD repo (M-ADR 0173)");
+    registerScaffoldBehaviourStore(scaffold);
     scaffold
         .command("domain <name>")
         .description("Scaffold a platform domain (docs/domains/<name>/) into a platform-root SDD. " +
@@ -65,6 +67,33 @@ export function registerScaffold(program) {
             process.stdout.write(`  ${f}\n`);
     });
 }
+function registerScaffoldBehaviourStore(scaffold) {
+    scaffold
+        .command("behaviour-store")
+        .description("Create this SDD's behaviour store at openspec/ (M-ADR 0221 §4.2): openspec/config.yaml from the method's " +
+        "template, selecting the sdd-change schema, the schema's copy at openspec/schemas/sdd-change/, and empty " +
+        "specs/, changes/archive/ and docs/agreements/. Create it when the SDD first drafts a proposed change, agrees a change or " +
+        "baselines behaviour; sync keeps the schema copy current afterwards.")
+        .option("--target-repo <dir>", "the SDD repo", resolvePathOption, process.cwd())
+        .option("--dry-run", "report the refusal or the planned store without writing")
+        .action(async (opts) => {
+        const targetRepo = opts.targetRepo ?? process.cwd();
+        const refusal = await storeScaffoldRefusal(targetRepo);
+        if (refusal !== null) {
+            process.stderr.write(`[FAIL] scaffold behaviour-store: ${refusal}\n`);
+            process.exit(1);
+        }
+        if (opts.dryRun === true) {
+            process.stdout.write("[DRY-RUN] would create openspec/ (config.yaml, schemas/sdd-change/, specs/, changes/archive/) and docs/agreements/\n");
+            return;
+        }
+        const { filesWritten, sddId } = await scaffoldBehaviourStore(targetRepo);
+        process.stdout.write(`[PASS] created the behaviour store (${filesWritten.length} files):\n`);
+        for (const f of filesWritten)
+            process.stdout.write(`  ${f}\n`);
+        process.stdout.write(`[INFO] fill in openspec/config.yaml's context${sddId === null ? " (the SDD id, no sdd_id in .sdd/sdd-manifest.yaml)" : ""}: the code repositories beside this SDD and where they are checked out\n`);
+    });
+}
 function fail(message) {
     process.stderr.write(`[FAIL] scaffold domain: ${message}\n`);
     process.exit(1);

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "2.3.0",
-  "built_against_sdd_cli": "2.3.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.8.0",
-  "sddCliVersion": "2.3.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",