@sdd-method/maintain-cli 0.14.0 → 0.15.1

package/dist/lib/structure/view.js

@@ -121,7 +121,12 @@ function naturalKey(cat, e) {
  * catalogue of another class, against its built rows), no cycle through a self-reference, natural keys unique, and
  * domain invariants naming their entity's own attributes and relationships.
  */
-export function validateView(schema, view, built, problems, unresolved) {
+export function validateView(schema, view, built, problems, unresolved, addedBy = () => undefined) {
+    // A reference to an open change's addition, from outside that change and its dependants (§4.11 proof 3).
+    const outside = (catalogue, id) => {
+        const by = addedBy(catalogue, id);
+        return by === undefined ? "" : `; open change ${by} adds it, and only that change and those depending on it can name it`;
+    };
     for (const [catalogue, byId] of view) {
         const cat = catalogueOf(schema, catalogue);
         for (const e of byId.values()) {
@@ -133,14 +138,14 @@ export function validateView(schema, view, built, problems, unresolved) {
             for (const r of referencesOf(schema, e)) {
                 if (r.structural) {
                     if (!find(view, r.catalogue, r.targetColumn, r.value))
-                        problems.push(`${e.file}: ${elementKey(catalogue, e.id)}: ${r.column} ${JSON.stringify(r.value)} names no ${r.catalogue} element in this view (${elementKey(r.catalogue, r.value)})`);
+                        problems.push(`${e.file}: ${elementKey(catalogue, e.id)}: ${r.column} ${JSON.stringify(r.value)} names no ${r.catalogue} element in this view (${elementKey(r.catalogue, r.value)})${r.targetColumn === "id" ? outside(r.catalogue, r.value) : ""}`);
                 }
                 else {
                     const rows = built(r.catalogue, r.targetColumn);
                     if (rows === null)
                         unresolved.add(r.catalogue);
                     else if (!rows.has(r.value))
-                        problems.push(`${e.file}: ${elementKey(catalogue, e.id)}: ${r.column} ${JSON.stringify(r.value)} names no row of ${r.catalogue} as built`);
+                        problems.push(`${e.file}: ${elementKey(catalogue, e.id)}: ${r.column} ${JSON.stringify(r.value)} names no row of ${r.catalogue} as built${outside(r.catalogue, r.value)}`);
                 }
             }
         }

package/dist/lib/validate/agreement-evidence.js

@@ -3,7 +3,7 @@
 //
 //   agreed content   the change's proposal, deltas, Gate 0, design, tasks (checkboxes ignored), the test plan's
 //                    scenario-to-test rows (its Before and After cells ignored) and its structural deltas with their
-//                    base revisions (M-ADR 0230 §4.4, Proposed; report only until it is accepted) are what was approved. Each is compared
+//                    base revisions (M-ADR 0230 §4.4; report only until it is accepted) are what was approved. Each is compared
 //                    with its state at the record's pinned commit: the latest amendment's commit, else sdd.commit.
 //   requirement      a requirement's block in a spec: its heading to the next requirement or section heading. The
 //                    stale check compares the blocks a change targets, not the whole file.
@@ -16,7 +16,7 @@ export function boundFile(rel) {
     return /^(proposal|design|gate-0|tasks|test-plan)\.md$/.test(rel) || /^specs\/.+\/spec\.md$/.test(rel) || structuralFile(rel);
 }
 /**
- * A change's structural artifact (M-ADR 0230 §4.4, Proposed): a partition delta or the no-op claim, both agreed
+ * A change's structural artifact (M-ADR 0230 §4.4): a partition delta or the no-op claim, both agreed
  * content, so a delta's base revisions are pinned with it. The effect record (structure/applied.yaml) is written by
  * the archive, after agreement, and is not.
  */

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

@@ -16,10 +16,12 @@
 //                 check is vacuous, and says so.
 //      agreed content: the change's proposal, deltas, Gate 0, design, tasks (checkboxes ignored), test
 //                 plan (its execution results ignored) and structural deltas equal their state at that commit
-//                 (M-ADR 0222 §4.6; a structural delta's change is a [WARN] while M-ADR 0230 is Proposed).
+//                 (M-ADR 0222 §4.6; a structural delta's change fails like the rest, a [WARN] only with ENFORCED false).
 //      kinds:    on a record held to 1.1.0, each test-plan row's Kind (changed or carried) is the one computed
-//                 from the deltas and the living spec, a row naming no scenario of the deltas fails, and a
-//                 filled Before is a fail for changed and a pass for carried (M-ADR 0223 §4.4).
+//                 from the deltas and the living spec, or repaired (declared, on a carried scenario); a row
+//                 naming no scenario of the deltas fails; and a filled Before, read as whole-word results, is a
+//                 fail for changed, a pass for carried, and a fail citing the test double's correcting commit
+//                 for repaired (M-ADR 0223 §4.4).
 //   4. verdicts: every archived change except a baseline has a verdict.md whose verdict line agrees with
 //                 its record's PASS (M-ADR 0223 §4.6). A record held to 1.1.0 (by its own history, or by the
 //                 schema the SDD shipped when the change archived) also needs: an agreed record; archived
@@ -186,6 +188,16 @@ export function parseAgreementRecord(file, text) {
                     noLongerImplements.push({ repo: e.repo, requirement: e.requirement });
             }
     }
+    // Record 1.3.0 (M-ADR 0230 §4.2): a contracts entry may deprecate its version, stating the sunset. A
+    // deprecation that names no date states no runway, so it is refused rather than read as a deprecation without one.
+    for (const [i, x] of (Array.isArray(r.contracts) ? r.contracts : []).entries()) {
+        const d = x?.deprecates;
+        if (d === undefined)
+            continue;
+        const sunset = d?.sunset;
+        if (typeof sunset !== "string" || !isCalendarDate(sunset))
+            problems.push(`${file}: contracts[${i}].deprecates must be {sunset: YYYY-MM-DD}, a calendar date as a string; found ${JSON.stringify(d)}`);
+    }
     if (problems.length > 0)
         return { problems };
     return {
@@ -205,6 +217,13 @@ export function parseAgreementRecord(file, text) {
         problems,
     };
 }
+/** A YYYY-MM-DD string naming a day that exists. */
+function isCalendarDate(s) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(s))
+        return false;
+    const t = new Date(`${s}T00:00:00Z`);
+    return !Number.isNaN(t.getTime()) && t.toISOString().slice(0, 10) === s;
+}
 /** Every pinned commit in a record: any key named `commit` or ending `_commit`, and each value under verdict.merged and current. */
 function commitFields(r) {
     const out = [];
@@ -489,7 +508,7 @@ export async function checkBehaviourStore(repo, options = {}) {
                         if (a === null || b === null || normaliseBound(f, a) !== normaliseBound(f, b)) {
                             const what = `${dir}: AGREED CONTENT CHANGED: ${f} ${a === null ? "was added" : b === null ? "was removed" : "differs"} since ${base}, with no amendment recording a commit and an approver; amend the agreement or renew it (M-ADR 0222 §4.6)`;
                             if (structuralFile(f) && !STRUCTURE_ENFORCED)
-                                warnings.push(`${what}; a structural delta, report only while M-ADR 0230 is Proposed`);
+                                warnings.push(`${what}; a structural delta, reported only because ENFORCED is off`);
                             else
                                 failures.push(what);
                         }
@@ -497,14 +516,14 @@ export async function checkBehaviourStore(repo, options = {}) {
                 }
             }
         }
-        // A test plan's kinds (M-ADR 0223 §4.4 as amended): changed scenarios go red then green, carried ones stay green.
+        // A test plan's kinds (M-ADR 0223 §4.4 as amended): changed and repaired scenarios go red then green, carried ones stay green.
         if (versionAtLeast(record?.schemaVersion, "1.1.0") && record?.status === "agreed") {
             const plan = await readText(join(repo, dir, "test-plan.md"));
             if (plan !== null) {
                 const header = testPlanHeader(plan);
                 const col = (name) => header.indexOf(name);
                 if (col("kind") < 0)
-                    failures.push(`${dir}/test-plan.md: the scenario table has no Kind column (changed | carried)`);
+                    failures.push(`${dir}/test-plan.md: the scenario table has no Kind column (changed | carried | repaired)`);
                 else {
                     for (const row of testPlanMapping(plan)) {
                         const cell = row[col("requirement")] ?? "";
@@ -533,13 +552,31 @@ export async function checkBehaviourStore(repo, options = {}) {
                             continue;
                         }
                         kindsChecked++;
-                        if (kind !== expected)
+                        // `repaired` is declared, never computed: a carried scenario whose earlier pass was false-green.
+                        const repaired = kind === "repaired";
+                        if (repaired && expected === "changed")
+                            failures.push(`${dir}/test-plan.md: "${req}" / "${scen}" is changed against the living spec, so it cannot be repaired: repaired is a scenario carried as the living spec states it, whose code did not meet it`);
+                        else if (!repaired && kind !== expected)
                             failures.push(`${dir}/test-plan.md: "${req}" / "${scen}" is ${expected} against the living spec, and the plan says ${JSON.stringify(kind)}`);
                         const before = col("before") >= 0 ? (row[col("before")] ?? "") : "";
-                        if (before !== "" && expected === "changed" && !/fail|red/i.test(before))
-                            failures.push(`${dir}/test-plan.md: "${req}" / "${scen}" is changed, so its test fails before the code; the scenario table's Before cell says ${JSON.stringify(before)}`);
-                        if (before !== "" && expected === "carried" && !/pass|green/i.test(before))
-                            failures.push(`${dir}/test-plan.md: "${req}" / "${scen}" is carried, so its test passes before the code as regression; the scenario table's Before cell says ${JSON.stringify(before)}`);
+                        if (before !== "") {
+                            // The cell's results, as whole words: "PASS at x; FAIL at y" holds both, and "setup required" or "bypass" holds neither.
+                            const pass = /\b(?:pass(?:es|ed)?|green)\b/i.test(before);
+                            const fail = /\b(?:fail(?:s|ed)?|red)\b/i.test(before);
+                            const said = `the scenario table's Before cell says ${JSON.stringify(before)}`;
+                            if (repaired) {
+                                if (!fail)
+                                    failures.push(`${dir}/test-plan.md: "${req}" / "${scen}" is repaired, so its test fails before the code; ${said}`);
+                                else if (!/\b[0-9a-f]{7,40}\b/i.test(before))
+                                    failures.push(`${dir}/test-plan.md: "${req}" / "${scen}" is repaired, so its Before cell cites the commit that corrects the test double, with its own red run; ${said}`);
+                            }
+                            else if (expected === "changed" && (!fail || pass)) {
+                                failures.push(`${dir}/test-plan.md: "${req}" / "${scen}" is changed, so its test fails before the code${pass && fail ? ", and a cell holding both results is not a result" : ""}; ${said}`);
+                            }
+                            else if (expected === "carried" && (!pass || fail)) {
+                                failures.push(`${dir}/test-plan.md: "${req}" / "${scen}" is carried, so its test passes before the code as regression${fail ? "; if its earlier pass was false-green, declare it repaired and cite the commit that corrects the test double" : ""}; ${said}`);
+                            }
+                        }
                     }
                 }
             }
@@ -640,7 +677,7 @@ export async function checkBehaviourStore(repo, options = {}) {
                 if (a === null || b === null || normaliseBound(f, a) !== normaliseBound(f, b)) {
                     const what = `${dir}: AGREED CONTENT CHANGED: ${f} ${a === null ? "was added" : b === null ? "was removed" : "differs"} from what was agreed at ${base}, with no amendment recording a commit and an approver (M-ADR 0222 §4.6)`;
                     if (structuralFile(f) && !STRUCTURE_ENFORCED)
-                        warnings.push(`${what}; a structural delta, report only while M-ADR 0230 is Proposed`);
+                        warnings.push(`${what}; a structural delta, reported only because ENFORCED is off`);
                     else
                         failures.push(what);
                 }

package/dist/lib/validate/dispatch.js

@@ -43,7 +43,7 @@ const BEHAVIOUR_STORE_VALIDATORS = [
         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.
+    // The structural model and each open change's structural artifact (M-ADR 0230). Report only; [N/A] without a model.
     {
         name: "structural-model",
         source: { kind: "native", run: async (ctx) => checkStructuralModel(ctx.targetRepo) },

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

@@ -1,4 +1,4 @@
-// structural-model: the structural model and each open change's structural artifact (M-ADR 0230 §4.3, §4.4, Proposed;
+// structural-model: the structural model and each open change's structural artifact (M-ADR 0230 §4.3, §4.4;
 // docs/method/methods/guides/structural-model-format.md).
 //
 // The model (openspec/structure/<partition>.yaml), as the current view:
@@ -6,11 +6,13 @@
 //               (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
+//   references  resolved in the view; into a catalogue of another class, against that catalogue as built, less the
+//               contracts open changes' records agree as new (lib/structure/intended.ts): those are in their change's
+//               view, its dependants' and the intended one, so a current reference to one is refused (§4.11 proof 3)
 //   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)
+//   views       docs/structure/ absent where the model is admitted, and each generated view under it 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
@@ -29,20 +31,22 @@
 //   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].
+// Enforced (the release that accepts M-ADR 0230): every finding is a [FAIL] and the check
+// exits 1; with ENFORCED false it reports them as [WARN] and exits 0. Without openspec/structure/ and with no change
+// carrying a structure/ directory it reports [N/A], so an SDD without a model is unaffected.
 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 { agreedOrder, attribute, checkDependencies, checkOverlap, closure, intended, viewAt } from "../structure/compose.js";
 import { describeState, renderViews, VIEW_PATHS, viewState } from "../structure/render.js";
+import { Additions, CONTRACTS, readAgreement } from "../structure/intended.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;
+/** Findings FAIL (from M-ADR 0230's acceptance); false reports them only, as while M-ADR 0230 was Proposed. Also binds a change's structural deltas as agreed content in the behaviour-store check. */
+export const ENFORCED = true;
 const CHANGES_DIR = join("openspec", "changes");
 async function readText(p) {
     try {
@@ -60,19 +64,6 @@ async function subdirs(p) {
         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}-/, "")));
@@ -91,8 +82,22 @@ function builtLookup(repo) {
         const text = await readText(join(repo, "catalogues", `${catalogue}.csv`));
         cache.set(catalogue, text === null ? null : parseCatalogueCsv(text).rows);
     };
+    fn.rows = (catalogue) => cache.get(catalogue) ?? [];
     return fn;
 }
+/**
+ * The built catalogues as one view sees them. A contract an open change's record agrees as new is built from the
+ * change's own sources, so it is in no view but that change's, its dependants' and, once agreed, the intended one.
+ */
+function builtIn(built, all, mine) {
+    return (catalogue, column) => {
+        const rows = built(catalogue, column);
+        if (rows === null || catalogue !== CONTRACTS || column !== "id")
+            return rows;
+        const out = new Set([...rows].filter((id) => !all.has(id) || mine.has(id)));
+        return out;
+    };
+}
 export async function checkStructuralModel(repo, options = {}) {
     const enforced = options.enforced ?? ENFORCED;
     const problems = [];
@@ -123,6 +128,16 @@ export async function checkStructuralModel(repo, options = {}) {
     for (const c of schema.catalogues)
         if (c.sourceOfTruth !== "structure")
             await built.load(c.name);
+    const open = new Map();
+    const newContracts = new Map();
+    for (const s of structures) {
+        const agreement = await readAgreement(repo, s.change);
+        open.set(s.change, { structure: s, status: agreement.status });
+        newContracts.set(s.change, agreement.newContracts);
+    }
+    const additions = new Additions(open, newContracts, built.rows(CONTRACTS));
+    const allNew = additions.contracts(open.keys());
+    const addedBy = (catalogue, id) => additions.addedBy(catalogue, id);
     let allowed = null;
     if (profile === "platform-profile") {
         allowed = new Set(["platform", ...(view.get("domains")?.keys() ?? []), ...(built("domains", "id") ?? [])]);
@@ -143,14 +158,14 @@ export async function checkStructuralModel(repo, options = {}) {
     // The current view.
     const unresolved = new Set();
     const currentProblems = [];
-    validateView(schema, view, built, currentProblems, unresolved);
+    validateView(schema, view, builtIn(built, allNew, new Set()), currentProblems, unresolved, addedBy);
     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).
+    // The generated views, against a render of the current view. Where a model is admitted they are required (M-ADR
+    // 0230 §4.3): an SDD reviews an extraction before writing it (§6 step 1), so none is mid-adoption with a model.
     if (files !== null && (await subdirs(join(repo, "docs"))).includes("structure")) {
         let current = 0;
         for (const [path, rendered] of renderViews(view)) {
@@ -163,14 +178,15 @@ export async function checkStructuralModel(repo, options = {}) {
         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");
+        problems.push("docs/structure/: the generated views are not rendered; where a structural model is admitted they are required. `structure render` writes them (sdd-maintain or sdd-cli)");
+        lines.push(`generated views: 0 of ${VIEW_COUNT} (no docs/structure/)`);
     }
     // Open changes.
-    const addedBy = new Map();
+    const addedByChange = 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);
+                addedByChange.set(elementKey(e.catalogue, e.id), s.change);
     const features = new Set(view.get("features")?.keys() ?? []);
     let withDeltas = 0;
     let noOps = 0;
@@ -190,7 +206,7 @@ export async function checkStructuralModel(repo, options = {}) {
         }
         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));
+        const elsewhere = new Map([...addedByChange].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)));
@@ -207,9 +223,6 @@ export async function checkStructuralModel(repo, options = {}) {
     }
     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);
@@ -219,7 +232,7 @@ export async function checkStructuralModel(repo, options = {}) {
         if (oc.structure.deltas.length === 0)
             continue;
         const at = [];
-        validateView(schema, viewAt(view, name, open), built, at, new Set());
+        validateView(schema, viewAt(view, name, open), builtIn(built, allNew, additions.contracts(closure(name, open))), at, new Set(), addedBy);
         for (const p of at) {
             if (known.has(p))
                 continue;
@@ -231,7 +244,7 @@ export async function checkStructuralModel(repo, options = {}) {
     const agreed = agreedOrder(open);
     if (agreed.length > 0) {
         const inIntended = [];
-        validateView(schema, intended(view, open), built, inIntended, new Set());
+        validateView(schema, intended(view, open), builtIn(built, allNew, additions.contracts(agreed)), inIntended, new Set(), addedBy);
         for (const p of inIntended) {
             if (known.has(p) || atAgreed.has(p))
                 continue;
@@ -259,7 +272,7 @@ export async function checkStructuralModel(repo, options = {}) {
     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`;
+    const tail = enforced ? `[FAIL] structural-model: ${problems.length} finding(s)\n` : `[WARN] structural-model: ${problems.length} finding(s), report only (M-ADR 0230)\n`;
     return { exitCode: enforced ? 1 : 0, stdout: `structural-model:\n${body}${problems.map((p) => `[${tag}] ${p}\n`).join("")}${tail}` };
 }
 //# sourceMappingURL=structural-model.js.map

package/dist/maintain-program.js

@@ -7,7 +7,8 @@
 // (M-ADR 0218 §4.2–4.3): the method payload, lock, CI block and briefing (`sync`,
 // `generate-briefing`), the derived model (`catalogue build | aggregate | graph | diff`), an
 // output the caller names (`pack build`, `render screen`), and a code repository's briefing
-// (`context pull`). Plus the whole verify surface, because the personas nest.
+// (`context pull`), and the structural model's generated views (`structure render`, with `structure show` beside
+// them). Plus the whole verify surface, because the personas nest.
 //
 // ⚠ As with sdd-verify, the boundary is ABSENCE, not a menu: the package ships only the import
 // closure of maintain-bin.js, so authoring verbs (init, scaffold, plan, conformance,
@@ -23,6 +24,7 @@ import { registerContext } from "./verbs/context.js";
 import { registerGenerateBriefing } from "./verbs/generate-briefing.js";
 import { registerPackBuild } from "./verbs/pack-build.js";
 import { registerRender } from "./verbs/render.js";
+import { registerStructure } from "./verbs/structure.js";
 import { registerSync } from "./verbs/sync.js";
 const SPEC_URL = "docs/method/cli/sdd-cli-specification.md (in the method distribution)";
 /** The verbs maintain adds to verify, as `<verb>` or `<verb> <subcommand>`. Asserted by test. */
@@ -37,6 +39,8 @@ export const MAINTAIN_ONLY_SURFACE = [
     "catalogue diff",
     "pack build",
     "render screen",
+    "structure show",
+    "structure render",
 ];
 /** The full surface: verify's, plus maintain's own. */
 export const MAINTAIN_SURFACE = [...VERIFY_SURFACE, ...MAINTAIN_ONLY_SURFACE];
@@ -79,6 +83,8 @@ export function buildMaintainProgram() {
     registerGenerateBriefing(program);
     registerContext(program);
     registerRender(program);
+    // The structural model's generated views are derived (M-ADR 0230 §4.3); show is the read beside them.
+    registerStructure(program);
     const catalogue = program.commands.find((c) => c.name() === "catalogue");
     catalogue.description("Build, aggregate, validate and query per-SDD catalogues (M-ADR 0134) — the derived model");
     registerCatalogueBuild(catalogue);

package/dist/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.14.0",
-  "built_against_sdd_cli": "5.0.0"
+  "version": "0.15.1",
+  "built_against_sdd_cli": "5.1.1"
 }

package/dist/verbs/structure.js

@@ -0,0 +1,95 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { stringify } from "yaml";
+import { elementKey, loadModel, STRUCTURE_DIR } from "../lib/structure/model.js";
+import { describeState, renderViews, viewState } from "../lib/structure/render.js";
+import { revisionOf, viewOf } from "../lib/structure/view.js";
+// `structure show <catalogue>/<id>`: one element of the structural model and its revision, the value a change's
+// `base:` records for it (M-ADR 0230 §4.4). Read only.
+export async function runStructureShow(sddPath, ref, write) {
+    const slash = ref.indexOf("/");
+    if (slash <= 0 || slash === ref.length - 1) {
+        write(`[FAIL] structure show: name an element as <catalogue>/<id>, not ${JSON.stringify(ref)}\n`);
+        return 2;
+    }
+    const catalogue = ref.slice(0, slash);
+    const id = ref.slice(slash + 1);
+    const problems = [];
+    const files = await loadModel(sddPath, problems);
+    if (files === null) {
+        write(`[FAIL] structure show: no structural model (${STRUCTURE_DIR}/) in ${sddPath}\n`);
+        return 1;
+    }
+    const e = viewOf(files, problems).get(catalogue)?.get(id);
+    if (!e) {
+        write(`[FAIL] structure show: the model holds no ${elementKey(catalogue, id)}\n`);
+        for (const p of problems)
+            write(`  ${p}\n`);
+        return 1;
+    }
+    write(`# ${elementKey(catalogue, id)} in ${e.file} (partition ${e.partition})\n`);
+    write(`revision: ${revisionOf(e)}\n`);
+    write(stringify({ id: e.id, ...e.columns }));
+    return 0;
+}
+// `structure render [--check]`: write the generated views of the current view (M-ADR 0230 §4.3), or, with
+// --check, write nothing and report each view that is missing, stale or edited by hand (exit 1 if any is).
+export async function runStructureRender(sddPath, options, write) {
+    const problems = [];
+    const files = await loadModel(sddPath, problems);
+    if (files === null) {
+        write(`[FAIL] structure render: no structural model (${STRUCTURE_DIR}/) in ${sddPath}\n`);
+        return 1;
+    }
+    const view = viewOf(files, problems);
+    if (problems.length > 0) {
+        write(`[FAIL] structure render: the model does not load cleanly; run \`sdd-cli validate --validator structural-model\`\n`);
+        for (const p of problems)
+            write(`  ${p}\n`);
+        return 1;
+    }
+    let off = 0;
+    for (const [path, rendered] of renderViews(view)) {
+        const abs = join(sddPath, path);
+        const text = await readFile(abs, "utf8").catch(() => null);
+        const state = viewState(rendered, text);
+        if (options.check) {
+            if (state !== "current") {
+                off++;
+                write(`[WARN] ${describeState(path, state)}\n`);
+            }
+            continue;
+        }
+        if (state === "hand-edited")
+            write(`[WARN] ${describeState(path, state)}; the edit is overwritten\n`);
+        if (state !== "current") {
+            await mkdir(dirname(abs), { recursive: true });
+            await writeFile(abs, rendered, "utf8");
+        }
+        write(`${state === "current" ? "unchanged" : "wrote"} ${path}\n`);
+    }
+    if (options.check)
+        write(off === 0 ? "[PASS] structure render --check: every view is current\n" : `[FAIL] structure render --check: ${off} view(s) not current\n`);
+    return options.check && off > 0 ? 1 : 0;
+}
+// Read the model and write its generated views: maintain's and sdd-cli's (M-ADR 0230 §4.3, at its acceptance).
+// Extraction is the author's (migrate-structure.ts), registered apart so this module's closure carries no extractor.
+export function registerStructure(program) {
+    const structure = program.command("structure").description("Read the structural model, and write its generated views (M-ADR 0230)");
+    structure
+        .command("show <element>")
+        .description("Print one element of the structural model, <catalogue>/<id>, with its revision")
+        .option("--sdd-path <path>", "the SDD (default: the current directory)", ".")
+        .action(async (element, opts) => {
+        process.exitCode = await runStructureShow(opts.sddPath, element, (s) => process.stdout.write(s));
+    });
+    structure
+        .command("render")
+        .description("Write the generated views of the structural model under docs/structure/; --check reports instead")
+        .option("--sdd-path <path>", "the SDD (default: the current directory)", ".")
+        .option("--check", "write nothing; report each view that is missing, stale or edited by hand", false)
+        .action(async (opts) => {
+        process.exitCode = await runStructureRender(opts.sddPath, { check: opts.check }, (s) => process.stdout.write(s));
+    });
+}
+//# sourceMappingURL=structure.js.map

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "5.0.0",
-  "built_against_sdd_cli": "5.0.0"
+  "version": "5.1.1",
+  "built_against_sdd_cli": "5.1.1"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sdd-method/maintain-cli",
-  "version": "0.14.0",
-  "sddCliVersion": "5.0.0",
+  "version": "0.15.1",
+  "sddCliVersion": "5.1.1",
   "description": "Bring an SDD repository current and rebuild its derived model — sync, briefing, catalogue build and aggregate, pack build, context pull — plus every read-only verify verb. Ships only the code those verbs reach; it cannot author specification content. Authoring is in @sdd-method/sdd-cli.",
   "license": "UNLICENSED",
   "type": "module",