@sdd-method/author-cli 0.10.0 → 0.12.0

package/dist/lib/validate/dispatch.js

@@ -1,7 +1,10 @@
 import { checkArchetypeCitations } from "./archetype-citations.js";
 import { checkBehaviourStore, checkBehaviourStoreOpenspec } from "./behaviour-store.js";
 import { checkBundleCoherence } from "./bundle-coherence.js";
+import { checkFeatureSpecPointers } from "./feature-spec-pointers.js";
 import { checkIntents } from "./intents.js";
+import { checkJourneyImpact } from "./journey-impact.js";
+import { checkStructuralModel } from "./structural-model.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.
@@ -28,6 +31,24 @@ const BEHAVIOUR_STORE_VALIDATORS = [
         source: { kind: "native", run: async (ctx) => checkIntents(ctx.targetRepo) },
         build: () => ({ status: "run", args: [] }),
     },
+    // Once behaviour is in the living specs, the feature spec points at it (M-ADR 0221 §4.3). Advisory; [N/A] without a store.
+    {
+        name: "feature-spec-pointers",
+        source: { kind: "native", run: async (ctx) => checkFeatureSpecPointers(ctx.targetRepo) },
+        build: () => ({ status: "run", args: [] }),
+    },
+    // The journeys a change can break, and whether its proposal names them (M-ADR 0229 §4.5, Proposed). Report only; [N/A] without journeys.
+    {
+        name: "journey-impact",
+        source: { kind: "native", run: async (ctx) => checkJourneyImpact(ctx.targetRepo) },
+        build: () => ({ status: "run", args: [] }),
+    },
+    // The structural model and each open change's structural artifact (M-ADR 0230, Proposed). Report only; [N/A] without a model.
+    {
+        name: "structural-model",
+        source: { kind: "native", run: async (ctx) => checkStructuralModel(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/feature-spec-pointers.js

@@ -0,0 +1,175 @@
+// feature-spec-pointers: once behaviour is in the living specs, the feature spec points at it and no longer states
+// it (M-ADR 0221 §4.3). Advisory: every finding is a [WARN] and the check exits 0.
+//
+// The population is the store's, never the feature specs': each living spec (openspec/specs/<feature-id>/) should
+// be pointed at by a feature spec, one naming `openspec/specs/<feature-id>/`. A living spec no feature spec points
+// at is reported, whatever its feature spec says, because the feature spec that should point is the one not yet
+// converted.
+//
+// Each feature spec that points at the store is then read whole, not one heading of it, since behaviour is
+// restated in stories, API, Events and Security as well as under Behavior. Reported, as shipped behaviour still
+// stated in the feature spec:
+//   criteria  list lines of an **Acceptance Criteria** block (a story's criteria are behaviour; its narrative is
+//             intent and stays);
+//   gherkin   Given/When/Then lines anywhere else;
+//   sections  content lines under a heading that states behaviour: Happy Path, Edge Cases, Error Handling,
+//             Business Rules, Validation Rules, Acceptance Criteria.
+// Intent not yet shipped is allowed where it is marked. A heading reading "Not yet shipped or agreed" covers its
+// section, to the next heading of the same or a higher level. A bold line reading so covers what follows it, to the
+// next heading of any level. Open Questions' checkboxes are not
+// criteria. A check cannot tell shipped from unshipped text by reading it, so the marking is what it reads.
+//
+// Feature specs live under docs/domains/<domain>/product/features/ and, in an application SDD, features/. With no
+// living specs the check reports [N/A], an empty population, not a pass.
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+const SPECS_DIR = join("openspec", "specs");
+const BEHAVIOUR_HEADING = /^(happy path|edge cases?|error handling|business rules|validation rules|acceptance criteria)$/;
+const NOT_YET = /not yet (shipped|agreed)/i;
+const CRITERIA_START = /^\*\*Acceptance Criteria:?\*\*/i;
+const GHERKIN = /^\s*(?:[-*]\s+(?:\[[ xX]\]\s+)?)?(?:\*\*)?(Given|When|Then)\b/;
+const LIST_LINE = /^\s*(?:[-*]|\d+\.)\s+\S/;
+/** "## 3. Edge Cases (Revised)" -> "edge cases". */
+function headingKey(h) {
+    return h.replace(/^\s*\d+(\.\d+)*\.?\s*/, "").replace(/\((revised|updated)\)\s*$/i, "").trim().toLowerCase();
+}
+/** Line numbers (1-based) of shipped behaviour still stated in a feature spec, by kind. */
+export function scanRestated(text) {
+    const out = { criteria: [], gherkin: [], sections: [] };
+    const stack = [];
+    let inCriteria = false;
+    let notYetBlock = false; // after a bold "Not yet shipped or agreed" line, to the next heading
+    let fence = false;
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const n = i + 1;
+        if (/^\s*```/.test(line)) {
+            fence = !fence;
+            continue;
+        }
+        const h = fence ? null : /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+        if (h) {
+            const level = h[1].length;
+            while (stack.length && stack[stack.length - 1].level >= level)
+                stack.pop();
+            stack.push({ level, key: headingKey(h[2]), notYet: NOT_YET.test(h[2]) });
+            inCriteria = false;
+            notYetBlock = false;
+            continue;
+        }
+        if (!fence && /^\*\*[^*]+\*\*:?\s*$/.test(line.trim()) && NOT_YET.test(line)) {
+            notYetBlock = true;
+            inCriteria = false;
+            continue;
+        }
+        if (notYetBlock || stack.some((s) => s.notYet))
+            continue;
+        if (!fence && CRITERIA_START.test(line.trim())) {
+            inCriteria = true;
+            continue;
+        }
+        if (!line.trim() || /^\s*\|?[\s:|-]+\|[\s:|-]*$/.test(line))
+            continue; // blank, or a table separator
+        if (stack.some((s) => BEHAVIOUR_HEADING.test(s.key))) {
+            out.sections.push(n);
+            continue;
+        }
+        if (inCriteria && LIST_LINE.test(line)) {
+            out.criteria.push(n);
+            continue;
+        }
+        if (!fence && GHERKIN.test(line) && !stack.some((s) => s.key === "open questions"))
+            out.gherkin.push(n);
+    }
+    return out;
+}
+async function subdirs(p) {
+    try {
+        return (await readdir(p, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+    }
+    catch {
+        return [];
+    }
+}
+async function markdownUnder(dir) {
+    const out = [];
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        const p = join(dir, e.name);
+        if (e.isDirectory())
+            out.push(...(await markdownUnder(p)));
+        else if (e.isFile() && e.name.endsWith(".md") && e.name.toLowerCase() !== "readme.md")
+            out.push(p);
+    }
+    return out;
+}
+async function featureSpecs(repo) {
+    const files = [];
+    for (const domain of await subdirs(join(repo, "docs", "domains"))) {
+        files.push(...(await markdownUnder(join(repo, "docs", "domains", domain, "product", "features"))));
+    }
+    files.push(...(await markdownUnder(join(repo, "features"))));
+    return files.sort();
+}
+function firstLines(ns) {
+    return ns.slice(0, 3).join(", ") + (ns.length > 3 ? ", ..." : "");
+}
+export async function checkFeatureSpecPointers(repo) {
+    const living = [];
+    for (const id of await subdirs(join(repo, SPECS_DIR))) {
+        try {
+            await readFile(join(repo, SPECS_DIR, id, "spec.md"));
+            living.push(id);
+        }
+        catch {
+            // a directory without a spec is not a living spec
+        }
+    }
+    if (living.length === 0)
+        return { exitCode: 0, stdout: "[N/A] no living specs (openspec/specs/<feature>/spec.md) in this repository\n" };
+    const pointedBy = new Map(living.map((id) => [id, []]));
+    const warnings = [];
+    let pointing = 0;
+    let restating = 0;
+    for (const file of await featureSpecs(repo)) {
+        const text = await readFile(file, "utf8");
+        const rel = relative(repo, file);
+        const targets = living.filter((id) => text.includes(`openspec/specs/${id}/`));
+        if (targets.length === 0)
+            continue;
+        pointing++;
+        for (const id of targets)
+            pointedBy.get(id).push(rel);
+        const r = scanRestated(text);
+        const parts = [];
+        if (r.criteria.length)
+            parts.push(`${r.criteria.length} acceptance-criteria line(s) (from line ${firstLines(r.criteria)})`);
+        if (r.gherkin.length)
+            parts.push(`${r.gherkin.length} Given/When/Then line(s) (from line ${firstLines(r.gherkin)})`);
+        if (r.sections.length)
+            parts.push(`${r.sections.length} line(s) under a behaviour heading (from line ${firstLines(r.sections)})`);
+        if (parts.length) {
+            restating++;
+            warnings.push(`${rel}: points at the store but still states behaviour outside "Not yet shipped or agreed": ${parts.join("; ")}. Point shipped behaviour at its requirements, and mark intent not yet shipped (M-ADR 0221 §4.3)`);
+        }
+    }
+    const unpointed = living.filter((id) => pointedBy.get(id).length === 0);
+    for (const id of unpointed) {
+        warnings.unshift(`${SPECS_DIR}/${id}: no feature spec points at this living spec; its feature spec should name openspec/specs/${id}/ and stop stating what shipped (M-ADR 0221 §4.3)`);
+    }
+    const head = `feature-spec-pointers: ${living.length} living spec(s), ${living.length - unpointed.length} pointed at by a feature spec; ${pointing} feature spec(s) point at the store, ${restating} still state shipped behaviour\n`;
+    if (warnings.length === 0)
+        return { exitCode: 0, stdout: `${head}[PASS] feature-spec-pointers: every living spec is pointed at, and no pointing feature spec restates it\n` };
+    return {
+        exitCode: 0,
+        stdout: `${head}${warnings.map((w) => `[WARN] ${w}\n`).join("")}[WARN] feature-spec-pointers: ${warnings.length} finding(s), advisory: reported, not failed\n`,
+    };
+}
+//# sourceMappingURL=feature-spec-pointers.js.map

package/dist/lib/validate/journey-impact.js

@@ -0,0 +1,193 @@
+// journey-impact: the journeys a change can break, and whether its proposal names them (M-ADR 0229 §4.5, Proposed).
+// Report only (M-ADR 0229 §4.5, Proposed): every finding is a [WARN] and the check exits 0. Gate 0 carries this report; nothing
+// blocks on it, and the judge does not fail a change for it.
+//
+// For each open change in the behaviour store (openspec/changes/<change>/, not the archive):
+//   listed     every journey whose journey_requirement rows name a requirement the change's deltas MODIFY, REMOVE
+//              or RENAME (by its former name), and every untraced journey (no journey_requirement row) whose
+//              journey_feature rows touch a feature the change has a delta for. The population is the catalogue's,
+//              never the proposal's.
+//   unnamed    a listed journey the proposal's `## Affected Journeys` section does not name.
+//   unshown    a journey named `altered` with nothing to show it: no delta in the change to a feature of kind journey
+//              whose id is the journey's id or ends with it (option B), and no task naming it (option A).
+// A proposal line is `- <journey-id>: altered ...` or `- <journey-id>: unaffected, <reason>`; an unaffected line
+// with no reason is reported too.
+//
+// Also reported: a journey citing a requirement of a feature its journey_feature rows do not name (one record or
+// the other is wrong, M-ADR 0229 §4.4, Proposed); and an SDD with catalogued journeys whose manifest declares no journey master and that names no
+// platform it inherits from (an unresolved root, M-ADR 0229 §4.2, Proposed). A member that names its platform inherits the
+// root's declaration, which is checked at the root.
+//
+// Reads the aggregated catalogue (catalogues-aggregated/*.csv) where this SDD has one, since a root's changes can
+// break journeys its members catalogue and only the aggregate joins the two; otherwise the SDD's own catalogues/.
+// Without journey_requirement.csv the catalogue predates schema 4.4.0 and the check is unresolved, not passed. Without a store or open changes it reports [N/A] for the change
+// part, an empty population.
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseDocument } from "yaml";
+import { parseRequirements, renamedFrom } from "../behaviour-store/archive.js";
+import { parseCatalogueCsv } from "../catalogue/csv-reader.js";
+const CHANGES_DIR = join("openspec", "changes");
+async function readText(p) {
+    try {
+        return await readFile(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+async function subdirs(p) {
+    try {
+        return (await readdir(p, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+    }
+    catch {
+        return [];
+    }
+}
+async function catalogueDir(repo) {
+    return (await readText(join(repo, "catalogues-aggregated", "user_journeys.csv"))) !== null ? "catalogues-aggregated" : "catalogues";
+}
+async function csv(repo, name, dir = "catalogues") {
+    const text = await readText(join(repo, dir, `${name}.csv`));
+    return text === null ? null : parseCatalogueCsv(text).rows;
+}
+/** The `## Affected Journeys` section: journey id -> what the proposal says of it. */
+export function parseAffectedJourneys(proposal) {
+    const out = new Map();
+    let inSection = false;
+    for (const line of proposal.split("\n")) {
+        const h = /^##\s+(.+?)\s*$/.exec(line);
+        if (h) {
+            inSection = /^affected journeys$/i.test(h[1].trim());
+            continue;
+        }
+        if (!inSection)
+            continue;
+        const m = /^\s*[-*]\s+`?([a-z0-9][a-z0-9-]*)`?\s*:\s*(altered|unaffected)?\b[\s,;:.—-]*(.*)$/i.exec(line);
+        if (!m)
+            continue;
+        const verdict = m[2]?.toLowerCase() ?? "other";
+        out.set(m[1], { verdict, rest: (m[3] ?? "").trim() });
+    }
+    return out;
+}
+export async function checkJourneyImpact(repo) {
+    const lines = [];
+    const warnings = [];
+    const dir = await catalogueDir(repo);
+    const journeys = await csv(repo, "user_journeys", dir);
+    if (journeys === null || journeys.length === 0) {
+        return { exitCode: 0, stdout: "[N/A] journey-impact: no catalogued user journeys (catalogues/ or catalogues-aggregated/ user_journeys.csv) in this repository\n" };
+    }
+    // The journey master (§4.2).
+    const manifest = (await readText(join(repo, ".sdd", "sdd-manifest.yaml"))) ?? "";
+    let declared = false;
+    let platform = "";
+    try {
+        const m = parseDocument(manifest).toJS();
+        declared = typeof m?.journeys?.master === "string";
+        platform = String(m?.platform_sdd_id ?? m?.ecosystem_root ?? "");
+    }
+    catch {
+        // an unparseable manifest is the manifest check's to report
+    }
+    if (declared)
+        lines.push("journey master: declared in this SDD's manifest");
+    else if (platform)
+        lines.push(`journey master: not declared here; inherited from platform ${platform}, where it is checked`);
+    else
+        warnings.push(`.sdd/sdd-manifest.yaml: ${journeys.length} catalogued journey(s) and no journey master (journeys.master: test-file or store), and no platform to inherit one from: unresolved (M-ADR 0229 §4.2, Proposed)`);
+    const jr = await csv(repo, "journey_requirement", dir);
+    const jf = (await csv(repo, "journey_feature", dir)) ?? [];
+    const featureKinds = new Map(((await csv(repo, "features", dir)) ?? []).map((f) => [f["id"], f["kind"] ?? ""]));
+    lines.push(`catalogue: ${dir}/`);
+    if (jr === null) {
+        warnings.push(`${dir}/journey_requirement.csv: missing, so the catalogue predates schema 4.4.0; rebuild it. The journeys a change can break are unresolved`);
+    }
+    const byRequirement = new Map();
+    const traced = new Set();
+    for (const r of jr ?? []) {
+        traced.add(r["journey_id"]);
+        const s = byRequirement.get(r["requirement_id"]) ?? new Set();
+        s.add(r["journey_id"]);
+        byRequirement.set(r["requirement_id"], s);
+    }
+    const untracedByFeature = new Map();
+    for (const r of jf) {
+        if (traced.has(r["journey_id"]))
+            continue;
+        const s = untracedByFeature.get(r["feature_id"]) ?? new Set();
+        s.add(r["journey_id"]);
+        untracedByFeature.set(r["feature_id"], s);
+    }
+    const touched = new Map();
+    for (const r of jf) {
+        const s = touched.get(r["journey_id"]) ?? new Set();
+        s.add(r["feature_id"]);
+        touched.set(r["journey_id"], s);
+    }
+    const mismatched = new Set();
+    for (const r of jr ?? []) {
+        const feature = r["requirement_id"].split("::")[0];
+        const key = `${r["journey_id"]}|${feature}`;
+        if (touched.get(r["journey_id"])?.has(feature) || mismatched.has(key))
+            continue;
+        mismatched.add(key);
+        warnings.push(`journey ${r["journey_id"]} cites requirements of ${feature}, which its journey_feature rows do not name: the journey's related features or its tags are wrong (M-ADR 0229 §4.4, Proposed)`);
+    }
+    const untracedCount = journeys.filter((j) => !traced.has(j["id"])).length;
+    lines.push(`journeys: ${journeys.length} catalogued, ${journeys.length - untracedCount} traced to requirements, ${untracedCount} untraced`);
+    const changes = (await subdirs(join(repo, CHANGES_DIR))).filter((c) => c !== "archive");
+    if (changes.length === 0)
+        lines.push("[N/A] changes: no open changes in openspec/changes/");
+    for (const change of changes) {
+        const dir = join(repo, CHANGES_DIR, change);
+        const listed = new Map(); // journey -> why
+        for (const feature of await subdirs(join(dir, "specs"))) {
+            const text = (await readText(join(dir, "specs", feature, "spec.md"))) ?? "";
+            const targets = new Set();
+            for (const r of parseRequirements(text))
+                if (r.operation === "MODIFIED" || r.operation === "REMOVED")
+                    targets.add(r.name);
+            for (const from of renamedFrom(text))
+                targets.add(from);
+            for (const name of targets) {
+                for (const j of byRequirement.get(`${feature}::${name}`) ?? [])
+                    if (!listed.has(j))
+                        listed.set(j, `cites ${feature}::${name}`);
+            }
+            for (const j of untracedByFeature.get(feature) ?? [])
+                if (!listed.has(j))
+                    listed.set(j, `untraced, touches ${feature}`);
+        }
+        if (listed.size === 0) {
+            lines.push(`${change}: no journey cites what it changes`);
+            continue;
+        }
+        const proposal = (await readText(join(dir, "proposal.md"))) ?? "";
+        const tasks = (await readText(join(dir, "tasks.md"))) ?? "";
+        const named = parseAffectedJourneys(proposal);
+        const deltaFeatures = new Set(await subdirs(join(dir, "specs")));
+        lines.push(`${change}: ${listed.size} journey(s) listed (${[...listed.entries()].map(([j, why]) => `${j}: ${why}`).join("; ")})`);
+        for (const [j, why] of listed) {
+            const n = named.get(j);
+            if (!n || n.verdict === "other") {
+                warnings.push(`${CHANGES_DIR}/${change}/proposal.md: journey ${j} is listed (${why}) and the proposal's ## Affected Journeys does not name it as altered or unaffected`);
+                continue;
+            }
+            if (n.verdict === "unaffected" && n.rest === "")
+                warnings.push(`${CHANGES_DIR}/${change}/proposal.md: journey ${j} is named unaffected without a reason`);
+            if (n.verdict === "altered") {
+                const journeyDelta = [...deltaFeatures].some((f) => featureKinds.get(f) === "journey" && (f === j || f.endsWith(`-${j}`)));
+                const shown = journeyDelta || tasks.includes(j);
+                if (!shown)
+                    warnings.push(`${CHANGES_DIR}/${change}/proposal.md: journey ${j} is named altered, and the change shows nothing for it: no delta to its journey feature and no task naming it`);
+            }
+        }
+    }
+    const body = lines.map((l) => `${l}\n`).join("");
+    if (warnings.length === 0)
+        return { exitCode: 0, stdout: `journey-impact:\n${body}[PASS] journey-impact: every listed journey is named\n` };
+    return { exitCode: 0, stdout: `journey-impact:\n${body}${warnings.map((w) => `[WARN] ${w}\n`).join("")}[WARN] journey-impact: ${warnings.length} finding(s), report only (M-ADR 0229 §4.5, Proposed)\n` };
+}
+//# sourceMappingURL=journey-impact.js.map

package/dist/lib/validate/structural-model.js

@@ -0,0 +1,265 @@
+// structural-model: the structural model and each open change's structural artifact (M-ADR 0230 §4.3, §4.4, Proposed;
+// docs/method/methods/guides/structural-model-format.md).
+//
+// The model (openspec/structure/<partition>.yaml), as the current view:
+//   files       valid YAML, schema_version, a partition matching its file name and naming one this SDD has
+//               (a platform SDD: its domains and `platform`; an application or integration SDD: its sdd_id)
+//   elements    a `structure` catalogue, its `structure` columns only, an id held once, required columns,
+//               value types and vocabularies (the catalogue metamodel's)
+//   references  resolved in the view; into a catalogue of another class, against that catalogue as built
+//   hierarchies no cycle through a self-reference; natural keys unique; domain invariants naming their entity's own
+//               attributes and relationships
+//   views       each generated view under docs/structure/ missing, stale (rendered from an earlier model) or edited by
+//               hand (its body no longer matches the digest in its header)
+// Each open change (openspec/changes/<change>/structure/):
+//   artifact    where the model exists, a change has partition deltas or none.yaml, never both
+//   deltas      well formed; ADDED ids new; MODIFIED and REMOVED ids held by the delta's partition; a base
+//               revision for every element modified, removed or read, still the current one; a reference into an
+//               element another open change adds names that change in depends_on
+//   no-op       contradicted by a behaviour delta for a feature the model does not hold; a structural delta
+//               must add that feature
+// Composition (§4.5; lib/structure/compose.ts), with a change agreed when its agreement record says so:
+//   overlap     two agreed changes writing one element or adding one id; a change overlapping an agreed one
+//   composed    each change's view (with its dependency closure) and the intended view (every agreed change)
+//               validated on their own; what fails there and not in current is reported against the changes
+//               that write the elements it names
+//   reads       a dependency withdrawn (record withdrawn or superseded, or neither open nor archived), an agreed
+//               change depending on one not agreed, a cycle of dependencies
+// Archived changes (§4.6):
+//   archived    a change archived with structural deltas and no effect record (a raw `openspec archive`): its
+//               structure is not applied, so its transition is not shipped
+//
+// Report only while M-ADR 0230 is Proposed (ENFORCED): every finding is a [WARN] and the check exits 0. Without
+// openspec/structure/ and with no change carrying a structure/ directory it reports [N/A].
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseDocument } from "yaml";
+import { parseCatalogueCsv } from "../catalogue/csv-reader.js";
+import { loadCanonicalSchema } from "../catalogue/schema-loader.js";
+import { APPLIED_FILE, elementKey, loadChangeStructure, loadModel, STRUCTURE_DIR } from "../structure/model.js";
+import { agreedOrder, attribute, checkDependencies, checkOverlap, intended, viewAt } from "../structure/compose.js";
+import { describeState, renderViews, VIEW_PATHS, viewState } from "../structure/render.js";
+import { validateDeltas, validateView, viewOf } from "../structure/view.js";
+const VIEW_COUNT = Object.keys(VIEW_PATHS).length;
+/** Flipped when M-ADR 0230 is accepted: findings then FAIL. */
+export const ENFORCED = false;
+const CHANGES_DIR = join("openspec", "changes");
+async function readText(p) {
+    try {
+        return await readFile(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+async function subdirs(p) {
+    try {
+        return (await readdir(p, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** The change's agreement record status (docs/agreements/<change>.yaml), or `unrecorded`. */
+async function agreementStatus(repo, change) {
+    const text = await readText(join(repo, "docs", "agreements", `${change}.yaml`));
+    if (text === null)
+        return "unrecorded";
+    try {
+        const status = String(parseDocument(text).toJS()?.agreement_record?.status ?? "");
+        return ["proposed", "agreed", "withdrawn", "superseded"].find((s) => s === status) ?? "unrecorded";
+    }
+    catch {
+        return "unrecorded";
+    }
+}
+/** Names of archived changes: openspec/changes/archive/<YYYY-MM-DD>-<name>. */
+async function archivedNames(repo) {
+    return new Set((await subdirs(join(repo, CHANGES_DIR, "archive"))).map((d) => d.replace(/^\d{4}-\d{2}-\d{2}-/, "")));
+}
+function builtLookup(repo) {
+    const cache = new Map();
+    const fn = ((catalogue, column) => {
+        const rows = cache.get(catalogue);
+        if (rows === undefined || rows === null)
+            return null;
+        return new Set(rows.map((r) => r[column] ?? ""));
+    });
+    fn.load = async (catalogue) => {
+        if (cache.has(catalogue))
+            return;
+        const text = await readText(join(repo, "catalogues", `${catalogue}.csv`));
+        cache.set(catalogue, text === null ? null : parseCatalogueCsv(text).rows);
+    };
+    return fn;
+}
+export async function checkStructuralModel(repo, options = {}) {
+    const enforced = options.enforced ?? ENFORCED;
+    const problems = [];
+    const lines = [];
+    const files = await loadModel(repo, problems);
+    const changes = (await subdirs(join(repo, CHANGES_DIR))).filter((c) => c !== "archive");
+    const structures = [];
+    for (const c of changes)
+        structures.push(await loadChangeStructure(repo, c, problems));
+    if (files === null && !structures.some((s) => s.present)) {
+        return { exitCode: 0, stdout: `[N/A] structural-model: no structural model (${STRUCTURE_DIR}/) and no change with structural deltas in this repository\n` };
+    }
+    const schema = options.schema ?? (await loadCanonicalSchema());
+    // Partitions this SDD has.
+    const manifest = (await readText(join(repo, ".sdd", "sdd-manifest.yaml"))) ?? "";
+    let profile = "";
+    let sddId = "";
+    try {
+        const m = parseDocument(manifest).toJS();
+        profile = String(m?.profile ?? "");
+        sddId = String(m?.sdd_id ?? "");
+    }
+    catch {
+        // the manifest check reports an unparseable manifest
+    }
+    const view = viewOf(files ?? [], problems);
+    const built = builtLookup(repo);
+    for (const c of schema.catalogues)
+        if (c.sourceOfTruth !== "structure")
+            await built.load(c.name);
+    let allowed = null;
+    if (profile === "platform-profile") {
+        allowed = new Set(["platform", ...(view.get("domains")?.keys() ?? []), ...(built("domains", "id") ?? [])]);
+    }
+    else if (sddId !== "") {
+        allowed = new Set([sddId]);
+    }
+    else {
+        lines.push("partitions: not checked (no profile or sdd_id in .sdd/sdd-manifest.yaml)");
+    }
+    const checkPartition = (partition, file) => {
+        if (allowed !== null && !allowed.has(partition)) {
+            problems.push(`${file}: partition ${partition} is not one this SDD has (${profile === "platform-profile" ? "a domain id, or platform" : `its sdd_id, ${sddId}`})`);
+        }
+    };
+    for (const f of files ?? [])
+        checkPartition(f.partition, f.file);
+    // The current view.
+    const unresolved = new Set();
+    const currentProblems = [];
+    validateView(schema, view, built, currentProblems, unresolved);
+    problems.push(...currentProblems);
+    const elementCount = [...view.values()].reduce((n, m) => n + m.size, 0);
+    lines.push(files === null ? `model: none (${STRUCTURE_DIR}/ absent)` : `model: ${files.length} partition file(s), ${elementCount} element(s) in ${view.size} catalogue(s)`);
+    if (unresolved.size > 0)
+        lines.push(`references into ${[...unresolved].sort().join(", ")}: unresolved (no built catalogue)`);
+    // The generated views, against a render of the current view. An SDD that has not rendered them yet (no
+    // docs/structure/) is adopting the model, which keeps its originals until the review is complete (§6 step 1).
+    if (files !== null && (await subdirs(join(repo, "docs"))).includes("structure")) {
+        let current = 0;
+        for (const [path, rendered] of renderViews(view)) {
+            const state = viewState(rendered, await readText(join(repo, path)));
+            if (state === "current")
+                current++;
+            else
+                problems.push(describeState(path, state));
+        }
+        lines.push(`generated views: ${current} of ${VIEW_COUNT} current`);
+    }
+    else if (files !== null) {
+        lines.push("generated views: not rendered (no docs/structure/); `sdd-cli structure render` writes them");
+    }
+    // Open changes.
+    const addedBy = new Map();
+    for (const s of structures)
+        for (const d of s.deltas)
+            for (const e of d.added)
+                addedBy.set(elementKey(e.catalogue, e.id), s.change);
+    const features = new Set(view.get("features")?.keys() ?? []);
+    let withDeltas = 0;
+    let noOps = 0;
+    let without = 0;
+    for (const s of structures) {
+        const dir = join(CHANGES_DIR, s.change);
+        for (const d of s.deltas)
+            checkPartition(d.partition, d.file);
+        if (s.deltas.length > 0)
+            withDeltas++;
+        if (s.noOp)
+            noOps++;
+        if (!s.present || (s.deltas.length === 0 && !s.noOp)) {
+            without++;
+            if (files !== null)
+                problems.push(`${dir}: no structural artifact; the model exists, so a change states its structural deltas or claims none (structure/none.yaml)`);
+        }
+        if (s.noOp && s.deltas.length > 0)
+            problems.push(`${s.noOp.file}: a no-op claim beside ${s.deltas.length} partition delta(s); state one or the other`);
+        const elsewhere = new Map([...addedBy].filter(([, c]) => c !== s.change));
+        validateDeltas(schema, view, s.deltas, elsewhere, problems);
+        // A behaviour delta for a feature the model does not hold needs that feature added here.
+        const adds = new Set(s.deltas.flatMap((d) => d.added.filter((e) => e.catalogue === "features").map((e) => e.id)));
+        for (const feature of await subdirs(join(repo, dir, "specs"))) {
+            if (features.has(feature) || adds.has(feature))
+                continue;
+            if (files === null && features.size === 0 && !s.present)
+                continue;
+            if (s.noOp)
+                problems.push(`${s.noOp.file}: claims no structural effect, and the change's behaviour deltas create a living spec for ${feature}, a feature the model does not hold`);
+            else
+                problems.push(`${dir}: a behaviour delta for ${feature}, a feature the model does not hold, and no structural delta adds features/${feature}`);
+        }
+    }
+    lines.push(`changes: ${changes.length} open, ${withDeltas} with structural deltas, ${noOps} claiming none, ${without} without the artifact`);
+    // Composition (M-ADR 0230 §4.5): the three views and the three checks.
+    const open = new Map();
+    for (const s of structures)
+        open.set(s.change, { structure: s, status: await agreementStatus(repo, s.change) });
+    const archived = await archivedNames(repo);
+    checkOverlap(open, problems);
+    checkDependencies(open, archived, problems);
+    const known = new Set(currentProblems);
+    const atAgreed = new Set();
+    for (const [name, oc] of open) {
+        if (oc.structure.deltas.length === 0)
+            continue;
+        const at = [];
+        validateView(schema, viewAt(view, name, open), built, at, new Set());
+        for (const p of at) {
+            if (known.has(p))
+                continue;
+            problems.push(`at ${name}: ${p}`);
+            if (oc.status === "agreed")
+                atAgreed.add(p);
+        }
+    }
+    const agreed = agreedOrder(open);
+    if (agreed.length > 0) {
+        const inIntended = [];
+        validateView(schema, intended(view, open), built, inIntended, new Set());
+        for (const p of inIntended) {
+            if (known.has(p) || atAgreed.has(p))
+                continue;
+            const by = attribute(p, open, agreed);
+            problems.push(`in the intended view, from ${by.length > 0 ? by.join(" with ") : "the agreed changes together"}: ${p}`);
+        }
+    }
+    // An archived change with structural deltas and no effect record: archived by a raw `openspec archive`, so its
+    // behaviour moved and its structure did not. Its structural transition is not shipped (§4.6).
+    let raw = 0;
+    for (const dir of await subdirs(join(repo, CHANGES_DIR, "archive"))) {
+        const ap = [];
+        const s = await loadChangeStructure(repo, join("archive", dir), ap);
+        if (s.deltas.length === 0)
+            continue;
+        if ((await readText(join(repo, CHANGES_DIR, "archive", dir, "structure", APPLIED_FILE))) !== null)
+            continue;
+        raw++;
+        problems.push(`${join(CHANGES_DIR, "archive", dir)}: archived with structural deltas and no effect record (structure/${APPLIED_FILE}), as a raw \`openspec archive\` leaves it; its structure is not applied, so the transition is not shipped. Run \`sdd-cli change archive ${dir.replace(/^\d{4}-\d{2}-\d{2}-/, "")}\` to apply it, guarded by its base revisions`);
+    }
+    if (raw > 0)
+        lines.push(`archived changes whose structure is not applied: ${raw}`);
+    lines.push(`views: current; at each of ${[...open.values()].filter((o) => o.structure.deltas.length > 0).length} change(s) with deltas; intended from ${agreed.length} agreed change(s)`);
+    const body = lines.map((l) => `${l}\n`).join("");
+    if (problems.length === 0)
+        return { exitCode: 0, stdout: `structural-model:\n${body}[PASS] structural-model: ok\n` };
+    const tag = enforced ? "FAIL" : "WARN";
+    const tail = enforced ? `[FAIL] structural-model: ${problems.length} finding(s)\n` : `[WARN] structural-model: ${problems.length} finding(s), report only (M-ADR 0230, Proposed)\n`;
+    return { exitCode: enforced ? 1 : 0, stdout: `structural-model:\n${body}${problems.map((p) => `[${tag}] ${p}\n`).join("")}${tail}` };
+}
+//# sourceMappingURL=structural-model.js.map