@sdd-method/author-cli 0.12.1 → 0.14.0

package/dist/lib/catalogue/retired-catalogues.js

@@ -7,7 +7,7 @@ import { rm, stat } from "node:fs/promises";
 import { join } from "node:path";
 /** name -> why it went, and what replaced it. */
 export const RETIRED_CATALOGUES = new Map([
-    ["requirement_status", "retired in catalogue schema 6.0.0: evidence about one revision of a requirement is requirement_assertions (M-ADR 0230 §4.7, Proposed)"],
+    ["requirement_status", "retired in catalogue schema 6.0.0: evidence about one revision of a requirement is requirement_assertions (M-ADR 0230 §4.7)"],
 ]);
 /** Remove each retired catalogue's file from `dir`. Returns the file names removed. */
 export async function removeRetiredCatalogues(dir, findings, label) {

package/dist/lib/catalogue/rubric-coverage-map.yaml

@@ -954,7 +954,7 @@ coverage:
   entity_attributes:
     kind: entity
     scoring: scored-at-source
-    instrument: an element of the structural model (M-ADR 0230, Proposed); scored with its domain model by rubrics/domain-architecture-rubric.md
+    instrument: an element of the structural model (M-ADR 0230); scored with its domain model by rubrics/domain-architecture-rubric.md
     relationships:
       entity_id:
         class: membership
@@ -962,7 +962,7 @@ coverage:
   entity_relationships:
     kind: entity
     scoring: scored-at-source
-    instrument: an element of the structural model (M-ADR 0230, Proposed); scored with its domain model by rubrics/domain-architecture-rubric.md
+    instrument: an element of the structural model (M-ADR 0230); scored with its domain model by rubrics/domain-architecture-rubric.md
     relationships:
       from_entity_id:
         class: membership
@@ -973,7 +973,7 @@ coverage:
   domain_invariants:
     kind: entity
     scoring: scored-at-source
-    instrument: an element of the structural model (M-ADR 0230, Proposed); scored with its domain model by rubrics/domain-architecture-rubric.md
+    instrument: an element of the structural model (M-ADR 0230); scored with its domain model by rubrics/domain-architecture-rubric.md
     relationships:
       entity_id:
         class: membership
@@ -1039,3 +1039,7 @@ coverage:
     kind: enum
     scoring: not-applicable
     reason: closed vocabulary, not an artefact
+  ppt_archetype:
+    kind: enum
+    scoring: not-applicable
+    reason: closed vocabulary, not an artefact

package/dist/lib/catalogue/schema-compat.js

@@ -27,7 +27,7 @@
  * M-ADR 0134 §4.6 (canonical builder + aggregator).
  */
 export const SCHEMA_COMPAT = {
-    catalogue_schema: "^6.0.0",
+    catalogue_schema: "^7.0.0",
     sdd_manifest: "^1.0.0",
     aggregation_manifest: "^1.0.0",
 };

package/dist/lib/catalogue/staleness-verdicts.js

@@ -40,7 +40,7 @@
 //   none — already reported by scores-coverage as unknown currency; not
 //       re-reported here.
 //
-// ASSESSED INPUTS (M-ADR 0230 §4.9, Proposed): a review that names its other inputs (`input_paths`) is read with
+// ASSESSED INPUTS (M-ADR 0230 §4.9): a review that names its other inputs (`input_paths`) is read with
 //   each of them, once its target is current. An input that moved stales the score, with the input named. So does an
 //   input gone from HEAD, and one the corpus did not hold at the anchor: unlike a missing target, the score can still
 //   be re-reviewed against its target, and a review cannot have read an input that was not there, so both prescribe a
@@ -171,7 +171,7 @@ export async function runStalenessVerdicts(session, options) {
         };
     }
     const asStr = (v) => v === null || v === undefined ? "" : String(v).trim();
-    // input_paths (schema 6.0.0, M-ADR 0230 §4.9, Proposed): a catalogue built before it has no such column, and its
+    // input_paths (schema 6.0.0, M-ADR 0230 §4.9): a catalogue built before it has no such column, and its
     // scores are read as naming no other input.
     const query = (inputs) => `SELECT rubric_id, target_ref, target_path, corpus_ref, scored_at, staleness_basis, ${inputs}
      FROM "quality_scores"
@@ -191,7 +191,7 @@ export async function runStalenessVerdicts(session, options) {
         const rubricId = asStr(rubricIdRaw);
         const targetRef = asStr(targetRefRaw);
         const basis = asStr(basisRaw);
-        // The review's other assessed inputs (M-ADR 0230 §4.9, Proposed): read with the target, so an edit to any of
+        // The review's other assessed inputs (M-ADR 0230 §4.9): read with the target, so an edit to any of
         // them makes the score stale as an edit to the target does.
         const inputs = asStr(inputPathsRaw).split(";").map((x) => x.trim()).filter((x) => x !== "");
         // Counted for BOTH bases, before the branch. The first cut of this counter

package/dist/lib/structure/apply.js

@@ -0,0 +1,71 @@
+// Writing a change's structural deltas into the model files, and the record of what they did (M-ADR 0230 §4.6).
+// The files are edited as YAML documents, so their comments and element order survive: a modified element
+// is replaced where it stands, a removed one is deleted, an added one is appended to its catalogue's list, and a
+// partition the model does not have yet gets a file. Writes files; the archive operation calls it in a scratch copy.
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isMap, isSeq, parseDocument, stringify } from "yaml";
+import { elementKey, FORMAT_VERSION, STRUCTURE_DIR } from "./model.js";
+export { APPLIED_FILE } from "./model.js";
+export { effectsOf, parseAppliedRecord } from "./effects.js";
+export function appliedRecord(change, baseCommit, effects) {
+    return stringify({ schema_version: FORMAT_VERSION, change, base_commit: baseCommit, effects: effects.map((e) => ({ ...e })) });
+}
+function itemIndex(seq, id) {
+    return seq.items.findIndex((it) => isMap(it) && String(it.get("id")) === id);
+}
+function catalogueSeq(doc, catalogue) {
+    let elements = doc.get("elements");
+    if (!isMap(elements)) {
+        doc.set("elements", doc.createNode({}));
+        elements = doc.get("elements");
+    }
+    const map = elements;
+    let seq = map.get(catalogue);
+    if (!isSeq(seq)) {
+        map.set(catalogue, doc.createNode([]));
+        seq = map.get(catalogue);
+    }
+    return seq;
+}
+/** Apply the change's deltas to the model files under `sddPath`, partition by partition. Returns the files written. */
+export async function applyToModel(sddPath, s) {
+    const written = [];
+    for (const d of s.deltas) {
+        const rel = join(STRUCTURE_DIR, `${d.partition}.yaml`);
+        const path = join(sddPath, rel);
+        let text;
+        try {
+            text = await readFile(path, "utf8");
+        }
+        catch {
+            text = stringify({ schema_version: FORMAT_VERSION, partition: d.partition, elements: {} });
+        }
+        const doc = parseDocument(text);
+        const node = (e) => doc.createNode({ id: e.id, ...e.columns });
+        for (const e of d.modified) {
+            const seq = catalogueSeq(doc, e.catalogue);
+            const i = itemIndex(seq, e.id);
+            if (i < 0)
+                throw new Error(`${rel}: MODIFIED ${elementKey(e.catalogue, e.id)} is not in this partition`);
+            seq.items[i] = node(e);
+        }
+        for (const r of d.removed) {
+            const seq = catalogueSeq(doc, r.catalogue);
+            const i = itemIndex(seq, r.id);
+            if (i < 0)
+                throw new Error(`${rel}: REMOVED ${elementKey(r.catalogue, r.id)} is not in this partition`);
+            seq.items.splice(i, 1);
+        }
+        for (const e of d.added) {
+            const seq = catalogueSeq(doc, e.catalogue);
+            if (itemIndex(seq, e.id) >= 0)
+                throw new Error(`${rel}: ADDED ${elementKey(e.catalogue, e.id)} is already in this partition`);
+            seq.add(node(e));
+        }
+        await writeFile(path, doc.toString(), "utf8");
+        written.push(rel);
+    }
+    return written;
+}
+//# sourceMappingURL=apply.js.map

package/dist/lib/structure/archive.js

@@ -0,0 +1,330 @@
+// The method's archive operation (M-ADR 0230 §4.6): behaviour and structure published as one unit.
+//   1. prepare   the full candidate in a scratch worktree at the store's current commit: OpenSpec archives the
+//                change there (behaviour), and its structural deltas are applied to the model with a record of
+//                their effect (structure/applied.yaml in the archived change)
+//   2. validate  the candidate as a whole: the change's deltas still apply (§4.5 again at archive), the model as it
+//                would stand fails nowhere the current model does not, and the behaviour-store check finds nothing
+//                wrong with the archived change (its agreed content, its verdict)
+//   3. publish   one commit, fast-forwarded onto the store only if the store has not moved since preparation; the
+//                model's generated views (docs/structure/) are rendered into it, since they are required and derived
+//                (M-ADR 0230 §4.3, at its acceptance)
+// Readers take a published commit, so they see the old state or the new. A retry is idempotent: an archived change
+// whose effect record holds at the commit that wrote it is reported as already archived. Recovery works from what
+// the store holds: an archived change with structural deltas and no effect record (a raw `openspec archive`) has its
+// deltas applied only if each element it writes is still at the revision it was written against.
+//
+// The store is the SDD's own `openspec/` in a git repository. Writes; never part of the verify-only CLI.
+import { execFile as execFileCb } from "node:child_process";
+import { mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, relative } from "node:path";
+import { promisify } from "node:util";
+import { parseRequirements, resolveImplements } from "../behaviour-store/archive.js";
+import { buildRequirements } from "../catalogue/builders/requirements.js";
+import { parseCatalogueCsv } from "../catalogue/csv-reader.js";
+import { FindingsLog } from "../catalogue/findings.js";
+import { loadCanonicalSchema } from "../catalogue/schema-loader.js";
+import { checkBehaviourStore, parseAgreementRecord } from "../validate/behaviour-store.js";
+import { appliedRecord, applyToModel, effectsOf, parseAppliedRecord } from "./apply.js";
+import { APPLIED_FILE, loadChangeStructure, loadModel } from "./model.js";
+import { renderViews } from "./render.js";
+import { revisionOf, validateDeltas, validateView, viewOf } from "./view.js";
+const execFile = promisify(execFileCb);
+const CHANGES = join("openspec", "changes");
+/** Exit codes: 0 archived or already archived, 1 refused, 75 interrupted (tests). */
+export const INTERRUPTED = 75;
+async function git(cwd, ...args) {
+    return (await execFile("git", ["-C", cwd, ...args], { maxBuffer: 64 * 1024 * 1024 })).stdout.trim();
+}
+async function exists(p) {
+    return stat(p).then(() => true, () => false);
+}
+async function subdirs(p) {
+    try {
+        return (await readdir(p, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+    }
+    catch {
+        return [];
+    }
+}
+async function archivedDir(sddPath, change) {
+    const found = (await subdirs(join(sddPath, CHANGES, "archive"))).filter((d) => d.replace(/^\d{4}-\d{2}-\d{2}-/, "") === change);
+    return found.length > 0 ? found[found.length - 1] : null;
+}
+async function defaultOpenspecArchive(cwd, change) {
+    try {
+        const r = await execFile("openspec", ["archive", change, "--yes"], { cwd, env: { ...process.env, OPENSPEC_TELEMETRY: "0" }, maxBuffer: 16 * 1024 * 1024 });
+        return { code: 0, output: r.stdout + r.stderr };
+    }
+    catch (err) {
+        const e = err;
+        return { code: typeof e.code === "number" ? e.code : 127, output: `${e.stdout ?? ""}${e.stderr ?? ""}` };
+    }
+}
+async function defaultBehaviourFindings(sddPath, archiveDir) {
+    const r = await checkBehaviourStore(sddPath);
+    return r.stdout.split("\n").filter((l) => l.startsWith("[FAIL]") && l.includes(archiveDir));
+}
+function viewProblems(schema, view) {
+    const out = [];
+    validateView(schema, view, () => null, out, new Set());
+    return new Set(out);
+}
+/** Does the effect record hold at `commit`? Each added or modified element at its target, each removed one absent. */
+async function verifyAt(root, relSdd, commit, effects) {
+    const scratch = await mkdtemp(join(tmpdir(), "sdd-archive-verify-"));
+    try {
+        await git(root, "worktree", "add", "--detach", "-q", scratch, commit);
+        const problems = [];
+        const files = (await loadModel(join(scratch, relSdd), problems)) ?? [];
+        const view = viewOf(files, problems);
+        const bad = [];
+        for (const e of effects) {
+            const [catalogue, ...rest] = e.element.split("/");
+            const el = view.get(catalogue)?.get(rest.join("/"));
+            if (e.operation === "REMOVED") {
+                if (el)
+                    bad.push(`${e.element} is still present`);
+            }
+            else if (!el)
+                bad.push(`${e.element} is absent`);
+            else if (revisionOf(el) !== e.target)
+                bad.push(`${e.element} is at ${revisionOf(el).slice(0, 19)}…, not the recorded ${String(e.target).slice(0, 19)}…`);
+        }
+        return bad;
+    }
+    finally {
+        await git(root, "worktree", "remove", "--force", scratch).catch(() => undefined);
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+export async function archiveChange(o) {
+    const say = (s) => o.write(`${s}\n`);
+    const refuse = (s) => {
+        say(`[FAIL] change archive ${o.change}: ${s}`);
+        return 1;
+    };
+    let root;
+    try {
+        root = await git(o.sddPath, "rev-parse", "--show-toplevel");
+    }
+    catch {
+        return refuse(`${o.sddPath} is not in a git repository; the archive is published as a commit`);
+    }
+    const relSdd = relative(root, o.sddPath) || ".";
+    const schema = o.schema ?? (await loadCanonicalSchema());
+    const openDir = join(CHANGES, o.change);
+    const isOpen = await exists(join(o.sddPath, openDir));
+    const archived = await archivedDir(o.sddPath, o.change);
+    // Already archived: verify, or recover a raw archive.
+    if (!isOpen && archived !== null) {
+        const archRel = join(CHANGES, "archive", archived);
+        const problems = [];
+        const s = await loadChangeStructure(o.sddPath, join("archive", archived), problems);
+        if (problems.length > 0)
+            return refuse(`its archived structural artifact is malformed: ${problems.join("; ")}`);
+        if (s.deltas.length === 0) {
+            say(`[PASS] change archive ${o.change}: already archived (${archRel}); it carries no structural deltas`);
+            return 0;
+        }
+        const recordPath = join(o.sddPath, archRel, "structure", APPLIED_FILE);
+        const text = await readFile(recordPath, "utf8").catch(() => null);
+        if (text !== null) {
+            const rec = parseAppliedRecord(text);
+            if (rec === null)
+                return refuse(`${join(archRel, "structure", APPLIED_FILE)} is not a valid effect record`);
+            const at = await git(root, "log", "-1", "--format=%H", "--", relative(root, recordPath));
+            if (at === "")
+                return refuse(`${join(archRel, "structure", APPLIED_FILE)} is not committed; the archive was not published`);
+            const bad = await verifyAt(root, relSdd, at, rec.effects);
+            if (bad.length > 0)
+                return refuse(`its effect record does not hold at ${at.slice(0, 12)}, the commit that wrote it: ${bad.join("; ")}`);
+            say(`[PASS] change archive ${o.change}: already archived at ${at.slice(0, 12)}; its ${rec.effects.length} structural effect(s) verified there`);
+            return 0;
+        }
+        // A raw archive: the behaviour moved, the structure did not. Apply it, guarded by each written element's base.
+        return publish(o, root, relSdd, schema, s, archRel, "recover");
+    }
+    if (!isOpen)
+        return refuse(`no open change ${openDir}, and none archived`);
+    // An open change: preconditions.
+    const baseline = await exists(join(o.sddPath, openDir, "baseline-evidence.md"));
+    if (!baseline) {
+        const recFile = join("docs", "agreements", `${o.change}.yaml`);
+        const recText = await readFile(join(o.sddPath, recFile), "utf8").catch(() => null);
+        if (recText === null)
+            return refuse(`no agreement record (${recFile}); a change archives on its judge's PASS`);
+        const { record } = parseAgreementRecord(recFile, recText);
+        if (!record)
+            return refuse(`${recFile} does not parse as an agreement record`);
+        if (record.status !== "agreed")
+            return refuse(`${recFile} says status ${record.status}, not agreed`);
+        if (String(record.verdict?.result ?? "") !== "PASS")
+            return refuse(`${recFile} has no verdict.result PASS; a change archives on its judge's PASS`);
+        const left = await leftOut(o.sddPath, o.change, record.workOrders, record.noLongerImplements);
+        if (left.length > 0)
+            return refuse(left.join("\n  "));
+    }
+    const problems = [];
+    const s = await loadChangeStructure(o.sddPath, o.change, problems);
+    if (problems.length > 0)
+        return refuse(`its structural artifact is malformed: ${problems.join("; ")}`);
+    for (const dep of new Set(s.deltas.flatMap((d) => [...d.dependsOn]))) {
+        if ((await archivedDir(o.sddPath, dep)) === null)
+            return refuse(`it depends on ${dep}, which has not archived; a change archives after its dependencies`);
+    }
+    return publish(o, root, relSdd, schema, s, openDir, "archive");
+}
+/**
+ * M-ADR 0230 §4.7: when a change moves a requirement to a new revision, each repository with evidence about the
+ * current one implements the new one too, through a work order, or the record says it no longer implements it
+ * (`no_longer_implements`). Otherwise the archive would leave that repository's evidence about a revision that is no
+ * longer live, and nothing about the one that is. Reads the store as the catalogue builder does.
+ */
+async function leftOut(sddPath, change, workOrders, noLonger) {
+    // Only a change that modifies a requirement can leave a repository behind; any change can name a requirement
+    // ambiguously.
+    const delta = [];
+    let modifies = false;
+    for (const feature of await subdirs(join(sddPath, CHANGES, change, "specs"))) {
+        const text = await readFile(join(sddPath, CHANGES, change, "specs", feature, "spec.md"), "utf8").catch(() => "");
+        for (const x of parseRequirements(text)) {
+            if (x.operation === "MODIFIED")
+                modifies = true;
+            if (x.operation !== "REMOVED")
+                delta.push({ feature, name: x.name });
+        }
+    }
+    // A requirement named in a work order or under no_longer_implements: `<feature>::<name>`, or a bare name only one
+    // feature in the change has, as the record schema says. An ambiguous bare name names neither, and is refused.
+    const ambiguous = [];
+    const resolve = (entry, where) => {
+        const r = resolveImplements(delta, entry);
+        if (r.ambiguous.length > 0)
+            ambiguous.push(`${where} names "${entry}", a requirement ${r.ambiguous.length} features in the change share (${r.ambiguous.join(", ")}); qualify it as <feature>::<name>`);
+        return new Set(r.matches.map((d) => `${d.feature}::${d.name}`));
+    };
+    const implementsOf = workOrders.map((w) => ({ repo: w.repo, ids: new Set(w.implements.flatMap((i) => [...resolve(i, `the work order for ${w.repo}`)])) }));
+    const excusedOf = noLonger.map((n) => ({ repo: n.repo, ids: resolve(n.requirement, `no_longer_implements for ${n.repo}`) }));
+    if (ambiguous.length > 0)
+        return ambiguous;
+    if (!modifies)
+        return [];
+    const ids = async (catalogue) => {
+        const text = await readFile(join(sddPath, "catalogues", `${catalogue}.csv`), "utf8").catch(() => null);
+        return text === null ? null : new Set(parseCatalogueCsv(text).rows.map((r) => String(r["id"])));
+    };
+    const features = await ids("features");
+    const repos = await ids("repositories");
+    if (features === null || repos === null)
+        return ["the catalogue (catalogues/features.csv and repositories.csv) is needed to tell which repositories implement the requirements this change modifies; build it first"];
+    const r = await buildRequirements({ sddPath, findings: new FindingsLog(), knownFeatureIds: features, knownRepoIds: repos, sddId: "local" });
+    const state = new Map(r.revisions.map((x) => [String(x["id"]), String(x["state"])]));
+    const modified = r.effects
+        .filter((e) => e["change_id"] === `local::${change}` && e["element_kind"] === "requirement" && e["operation"] === "MODIFIED")
+        .map((e) => String(e["element_id"]));
+    const out = [];
+    for (const req of modified) {
+        const implementers = new Set(r.assertions.filter((a) => a["requirement_id"] === req && state.get(String(a["revision_id"])) === "current").map((a) => String(a["repo_id"])));
+        const covered = new Set(implementsOf.filter((w) => w.ids.has(req)).map((w) => w.repo));
+        const excused = new Set(excusedOf.filter((n) => n.ids.has(req)).map((n) => n.repo));
+        const missing = [...implementers].filter((repo) => !covered.has(repo) && !excused.has(repo)).sort();
+        if (missing.length > 0) {
+            out.push(`${req}: ${missing.join(", ")} ${missing.length === 1 ? "implements" : "implement"} its current revision, and no work order of this change implements the new one; add a work order for ${missing.length === 1 ? "it" : "each"}, or record it under no_longer_implements`);
+        }
+    }
+    return out;
+}
+async function publish(o, root, relSdd, schema, s, changeRel, mode) {
+    const say = (x) => o.write(`${x}\n`);
+    const refuse = (x) => {
+        say(`[FAIL] change archive ${o.change}: ${x}`);
+        return 1;
+    };
+    const storeRel = join(relSdd, "openspec");
+    const viewsRel = join(relSdd, "docs", "structure");
+    const dirty = await git(root, "status", "--porcelain", "--", storeRel, viewsRel);
+    if (dirty !== "")
+        return refuse(`the store has uncommitted changes (${dirty.split("\n").length} path(s) under ${storeRel} or ${viewsRel}); the archive is published as one commit onto a clean store`);
+    const base = await git(root, "rev-parse", "HEAD");
+    // §4.5 again, against the model as it now is.
+    const problems = [];
+    const current = viewOf((await loadModel(o.sddPath, problems)) ?? [], problems);
+    const before = viewProblems(schema, current);
+    const deltaProblems = [];
+    validateDeltas(schema, current, s.deltas, new Map(), deltaProblems);
+    if (deltaProblems.length > 0)
+        return refuse(`its structural deltas no longer apply to the model as it stands:\n  ${deltaProblems.join("\n  ")}`);
+    const effects = effectsOf(s, current);
+    const scratch = await mkdtemp(join(tmpdir(), "sdd-archive-"));
+    let added = false;
+    try {
+        await git(root, "worktree", "add", "--detach", "-q", scratch, base);
+        added = true;
+        const scratchSdd = join(scratch, relSdd);
+        // 1. Prepare.
+        let archiveRel = changeRel;
+        if (mode === "archive") {
+            const beforeDirs = new Set(await subdirs(join(scratchSdd, CHANGES, "archive")));
+            const r = await (o.openspecArchive ?? defaultOpenspecArchive)(scratchSdd, o.change);
+            if (r.code !== 0)
+                return refuse(`openspec archive failed (exit ${r.code}): ${r.output.trim().split("\n").slice(-3).join(" ")}`);
+            const fresh = (await subdirs(join(scratchSdd, CHANGES, "archive"))).filter((d) => !beforeDirs.has(d));
+            if (fresh.length !== 1)
+                return refuse(`openspec archive left ${fresh.length} new archive folder(s), not one`);
+            archiveRel = join(CHANGES, "archive", fresh[0]);
+        }
+        await applyToModel(scratchSdd, s);
+        if (s.deltas.length > 0)
+            await writeFile(join(scratchSdd, archiveRel, "structure", APPLIED_FILE), appliedRecord(o.change, base, effects), "utf8");
+        // 2. Validate the candidate as a whole.
+        const cp = [];
+        const candidate = viewOf((await loadModel(scratchSdd, cp)) ?? [], cp);
+        const after = viewProblems(schema, candidate);
+        const worse = [...cp, ...[...after].filter((p) => !before.has(p))];
+        if (worse.length > 0)
+            return refuse(`the model as it would stand fails where it did not:\n  ${worse.join("\n  ")}`);
+        if (mode === "archive") {
+            const bf = await (o.behaviourFindings ?? defaultBehaviourFindings)(scratchSdd, archiveRel.split("/").pop());
+            if (bf.length > 0)
+                return refuse(`the behaviour-store check refuses the archived change:\n  ${bf.join("\n  ")}`);
+        }
+        if (o.interrupt === "prepared")
+            return INTERRUPTED;
+        // The generated views move with the model they render, in the same commit.
+        if (s.deltas.length > 0) {
+            for (const [path, text] of renderViews(candidate)) {
+                await mkdir(dirname(join(scratchSdd, path)), { recursive: true });
+                await writeFile(join(scratchSdd, path), text, "utf8");
+            }
+        }
+        // 3. Publish: one commit, fast-forwarded only onto the commit it was prepared from.
+        const withViews = await stat(join(scratch, viewsRel)).then(() => true, () => false);
+        await git(scratch, "add", "-A", "--", storeRel, ...(withViews ? [viewsRel] : []));
+        const message = mode === "archive"
+            ? `Archive ${o.change}: its behaviour and structure (M-ADR 0230 §4.6)`
+            : `Apply the structure of archived ${o.change}, which was archived without it (M-ADR 0230 §4.6)`;
+        await git(scratch, "commit", "-q", "-m", message);
+        const commit = await git(scratch, "rev-parse", "HEAD");
+        if (o.interrupt === "committed")
+            return INTERRUPTED;
+        if ((await git(root, "rev-parse", "HEAD")) !== base)
+            return refuse(`the store moved since the candidate was prepared (from ${base.slice(0, 12)}); run it again`);
+        try {
+            await git(root, "merge", "--ff-only", "-q", commit);
+        }
+        catch (err) {
+            return refuse(`the store moved since the candidate was prepared, so nothing was published: ${err.message.split("\n")[0]}`);
+        }
+        if (o.interrupt === "published")
+            return INTERRUPTED;
+        say(`[PASS] change archive ${o.change}: ${mode === "archive" ? "archived" : "its structure applied"} in ${commit.slice(0, 12)}, ${effects.length} structural effect(s)${s.deltas.length > 0 ? `, recorded in ${join(archiveRel, "structure", APPLIED_FILE)}` : ""}`);
+        return 0;
+    }
+    finally {
+        if (added)
+            await git(root, "worktree", "remove", "--force", scratch).catch(() => undefined);
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=archive.js.map

package/dist/lib/structure/catalogue.js

@@ -1,13 +1,15 @@
-// The catalogue from the structural model, and the model a built catalogue implies (M-ADR 0230 §4.3, §5.3,
-// Proposed). Where an SDD has a model, it is the record of structure, so every structure catalogue is built from it whole:
+// The catalogue from the structural model, and the model a built catalogue implies (M-ADR 0230 §4.3, §5.3).
+// Where an SDD has a model, it is the record of structure, so every structure catalogue is built from it whole:
 //   a row per element of the current view, with the model's structure columns;
 //   its other columns (every class but structure: derived, declaration, evidence, intent, execution) from the
 //   source-built row with the same id;
 //   for an element only the model holds, the derived columns the model itself settles (MODEL_DERIVED).
 // What the sources hold and the model does not, and a structure column where they disagree, is reported once per
-// catalogue. The model wins: either finding means the sources moved outside a change. Pure: no file is read or written.
+// catalogue. The model wins: either finding means the sources moved outside a change. A source row that states an
+// element as an agreed open change adds or modifies it is that change's intended element, not a disagreement: it is
+// listed apart, and catalogued once the change archives. Pure: no file is read or written.
 import { stringify } from "yaml";
-import { FORMAT_VERSION } from "./model.js";
+import { elementKey, FORMAT_VERSION } from "./model.js";
 import { STRUCTURE } from "./view.js";
 /** The view each generated file renders, for a derived path column of an element only the model holds. */
 export const VIEW_PATHS = {
@@ -44,8 +46,10 @@ function sample(ids) {
 /**
  * Replace every structure catalogue's rows with the view's. Rows of other catalogues are returned as they are. Source
  * rows sharing an id are merged first, later values filling earlier gaps, as the keyed-table dedupe would.
+ * `intended` holds the elements agreed open changes add or modify (intendedWrites); a source row agreeing with one is
+ * pushed to `intendedOut` as `<key> (<change>)` instead of being reported.
  */
-export function overlayModel(schema, view, rows, findings) {
+export function overlayModel(schema, view, rows, findings, intended = new Map(), intendedOut = []) {
     const out = new Map(rows);
     for (const cat of schema.catalogues) {
         if (cat.sourceOfTruth !== STRUCTURE)
@@ -66,6 +70,20 @@ export function overlayModel(schema, view, rows, findings) {
         const elements = view.get(cat.name) ?? new Map();
         const built = [];
         const differ = [];
+        const disagree = (from, e) => structural.filter((c) => cell(from[c]) !== "" && cell(from[c]) !== cell(e.columns[c]));
+        // The source row states the element as an agreed open change does; one stating it otherwise is reported as such.
+        const differIntended = [];
+        const asIntended = (id, from) => {
+            const w = intended.get(elementKey(cat.name, id));
+            if (w === undefined)
+                return false;
+            const cols = disagree(from, w.element);
+            if (cols.length > 0)
+                differIntended.push(`${id} (${cols.join(", ")}; ${w.change})`);
+            else
+                intendedOut.push(`${elementKey(cat.name, id)} (${w.change})`);
+            return true;
+        };
         for (const e of elements.values()) {
             const from = source.get(e.id);
             const row = {};
@@ -73,8 +91,8 @@ export function overlayModel(schema, view, rows, findings) {
                 for (const [k, v] of Object.entries(from))
                     if (!structural.includes(k))
                         row[k] = v;
-                const cols = structural.filter((c) => cell(from[c]) !== "" && cell(from[c]) !== cell(e.columns[c]));
-                if (cols.length > 0)
+                const cols = disagree(from, e);
+                if (cols.length > 0 && !asIntended(e.id, from))
                     differ.push(`${e.id} (${cols.join(", ")})`);
             }
             else {
@@ -85,12 +103,15 @@ export function overlayModel(schema, view, rows, findings) {
                 row[c] = e.columns[c];
             built.push(row);
         }
-        const missing = [...source.keys()].filter((id) => id !== "" && !elements.has(id)).sort();
+        const missing = [...source.keys()].filter((id) => id !== "" && !elements.has(id) && !asIntended(id, source.get(id))).sort();
         if (missing.length > 0) {
-            findings.add("divergence", `${cat.name}: the sources hold ${missing.length} row(s) the structural model does not (${sample(missing)}); the model is the record of structure, so they are not catalogued. Add them through a change's structural deltas, or remove them from the sources (M-ADR 0230 §4.3, Proposed)`, "warn", `catalogue:${cat.name}`);
+            findings.add("divergence", `${cat.name}: the sources hold ${missing.length} row(s) the structural model does not (${sample(missing)}); the model is the record of structure, so they are not catalogued. Add them through a change's structural deltas, or remove them from the sources (M-ADR 0230 §4.3)`, "warn", `catalogue:${cat.name}`);
+        }
+        if (differIntended.length > 0) {
+            findings.add("divergence", `${cat.name}: ${differIntended.length} source row(s) state an element an agreed open change adds or modifies, and disagree with it: ${sample(differIntended.sort())}. The change's delta is what archives; bring the source into line with it, or the delta with the source (M-ADR 0230 §4.3, §4.7)`, "warn", `catalogue:${cat.name}`);
         }
         if (differ.length > 0) {
-            findings.add("divergence", `${cat.name}: ${differ.length} element(s) where the sources and the structural model disagree, catalogued as the model states them: ${sample(differ.sort())}. A source that is a generated view is rendered again; any other is brought into line through a change (M-ADR 0230 §4.3, Proposed)`, "warn", `catalogue:${cat.name}`);
+            findings.add("divergence", `${cat.name}: ${differ.length} element(s) where the sources and the structural model disagree, catalogued as the model states them: ${sample(differ.sort())}. A source that is a generated view is rendered again; any other is brought into line through a change (M-ADR 0230 §4.3)`, "warn", `catalogue:${cat.name}`);
         }
         out.set(cat.name, built);
     }

package/dist/lib/structure/compose.js

@@ -1,4 +1,4 @@
-// Views over the structural model, and how changes compose (M-ADR 0230 §4.5, §4.7, Proposed).
+// Views over the structural model, and how changes compose (M-ADR 0230 §4.5, §4.7).
 //   current       the model as published
 //   at a change   current with that change's deltas and those of its dependency closure, dependencies first
 //   intended      current with every agreed change's deltas

package/dist/lib/structure/effects.js

@@ -1,4 +1,4 @@
-// A change's structural effect, and the effect record an archive leaves (M-ADR 0230 §4.6, §4.7, Proposed). Pure reads,
+// A change's structural effect, and the effect record an archive leaves (M-ADR 0230 §4.6, §4.7). Pure reads,
 // so the catalogue builder and the verify-only CLI can carry them; writing the record is apply.ts's.
 import { parseDocument } from "yaml";
 import { elementKey, revision } from "./model.js";