@sdd-method/author-cli 0.16.0 → 0.16.2

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

@@ -129,10 +129,17 @@ export async function orderArchives(sddPath, archiveRel, names) {
     }
     return { order, ties, history: history !== null };
 }
+/**
+ * Whether the evidence's `**Observed in:**` line is the typed claim `none`: a baseline that admits no behaviour (no
+ * spec deltas), such as a structure-only removal, observed no repository serving any.
+ */
+export function observedNone(evidence) {
+    return /^\s*\*\*Observed in:\*\*\s*none\b/im.test(evidence);
+}
 /** The repositories a baseline was observed in: its evidence file's `**Observed in:** repo[@sha], repo[@sha]` line. */
 export function observedIn(evidence) {
     const m = /^\s*\*\*Observed in:\*\*\s*(.+)$/m.exec(evidence);
-    if (!m)
+    if (!m || observedNone(evidence))
         return [];
     return m[1]
         .split(",")
@@ -148,18 +155,30 @@ export function observedIn(evidence) {
  * `**Surfaces:**` line is read, so an earlier prose section under the same label does not shadow the list.
  * Covered needs evidence that exercises the surface as the service exposes it; evidence below the transport is
  * not coverage, so `covered at handler` is a problem, not an entry. A wildcard may only exclude.
+ *
+ * `**Surfaces:** none` on one line is the typed claim that the baseline lists no surface, which only a baseline that
+ * admits no behaviour may make (the caller decides; `none` is true and the list is empty).
  */
 export function parseSurfaces(evidence) {
     const lines = evidence.split("\n");
     // The LAST standalone line: an evidence file may carry an earlier prose section under the same label, and
     // the list is what the file ends up asserting.
     let at = -1;
+    let none = false;
     lines.forEach((l, i) => {
-        if (/^\s*\*\*Surfaces:\*\*\s*$/.test(l))
+        if (/^\s*\*\*Surfaces:\*\*\s*$/.test(l)) {
             at = i;
+            none = false;
+        }
+        else if (/^\s*\*\*Surfaces:\*\*\s*none\b/i.test(l)) {
+            at = i;
+            none = true;
+        }
     });
     if (at < 0)
-        return { present: false, entries: [], problems: [] };
+        return { present: false, none: false, entries: [], problems: [] };
+    if (none)
+        return { present: true, none: true, entries: [], problems: [] };
     const entries = [];
     const problems = [];
     for (const line of lines.slice(at + 1)) {
@@ -193,8 +212,8 @@ export function parseSurfaces(evidence) {
         }
     }
     if (entries.length + problems.length === 0)
-        problems.push("the **Surfaces:** line lists no contract");
-    return { present: true, entries, problems };
+        problems.push('the **Surfaces:** line lists no contract; a baseline that admits no behaviour writes "**Surfaces:** none"');
+    return { present: true, none: false, entries, problems };
 }
 /**
  * A structural delta's `moved: {contracts: [{from, to, from_path?}]}` block. A contract's id is derived from its path,

package/dist/lib/catalogue/builders/features.js

@@ -24,9 +24,18 @@
 //
 // Dedup ordering matters: walker (1) runs first (capability features),
 // then walker (2) (standalone specs), then walker (3) (bullets). When
-// a bullet's id is already in `seen` from a standalone spec the spec
-// wins — divergence finding fires for the bullet. This matches the
-// "standalone is more authoritative than bullet inventory" rule.
+// a bullet's id is already claimed by a standalone app spec (2), the two
+// are one feature and make one row (sdm-mbhi): the feature tree is the home
+// of its placement and inventory facts (parent_group_id, maturity, runway,
+// description), the spec of its lifecycle (status, kind), and source stays
+// feature-spec, since a spec exists. A spec does not restate the tree's
+// fields, and its H1 title is a name, not a description. A bullet whose id a
+// capability feature (1) already claims is still a divergence.
+//
+// A standalone spec's stem is the feature's slug, without the product
+// prefix: features/<group>/alerts.md is <productId>-alerts. A stem that
+// already starts with "<productId>-" would double the prefix, so it is
+// refused with a convention finding naming the stem to use.
 import { readdir, readFile } from "node:fs/promises";
 import { basename, join, relative, sep } from "node:path";
 import { featureGroupId, findFeatureTreeFile, walkFeatureTree, } from "./feature-tree-walker.js";
@@ -103,10 +112,15 @@ export async function buildFeatures(inputs) {
     // These features are owned by the SDD's product (not by a capability) —
     // capability_id is left empty; product_id carries the link.
     if (inputs.profile === "application-product") {
+        const appSpecRow = new Map();
         const appFeatures = await collectAppFeatureSpecs(inputs.sddPath);
         for (const path of appFeatures) {
             const relPath = relative(inputs.sddPath, path);
             const stem = basename(relPath).replace(/\.md$/i, "");
+            if (stem.startsWith(`${inputs.productId}-`)) {
+                inputs.findings.add("convention", `${relPath}: feature spec stem "${stem}" repeats the product prefix, so its id would read "${inputs.productId}-${stem}"; name the file after the feature's slug ("${stem.slice(inputs.productId.length + 1)}.md"), the slug feature-tree.md uses`);
+                continue;
+            }
             const id = `${inputs.productId}-${stem}`;
             if (seen.has(id)) {
                 inputs.findings.add("divergence", `${relPath}: feature id "${id}" already emitted by an earlier file`);
@@ -133,6 +147,7 @@ export async function buildFeatures(inputs) {
             idByPath.set(relPath, id);
             if (!idBySlug.has(stem))
                 idBySlug.set(stem, id);
+            appSpecRow.set(id, rows.length - 1);
         }
         // Bullet branch — feature-tree.md.
         await emitBulletRows({
@@ -143,6 +158,7 @@ export async function buildFeatures(inputs) {
             seen,
             rows,
             idBySlug,
+            appSpecRow,
         });
     }
     return { rows, idByPath, idBySlug };
@@ -178,7 +194,8 @@ async function emitBulletRows(ctx) {
             continue;
         bulletCount++;
         const id = `${ctx.productId}-${ev.slug}`;
-        if (ctx.seen.has(id)) {
+        const specIndex = ctx.appSpecRow.get(id);
+        if (ctx.seen.has(id) && specIndex === undefined) {
             ctx.findings.add("divergence", `${relPath}: feature-tree.md bullet "${ev.slug}" superseded by an earlier feature spec with id "${id}"`);
             continue;
         }
@@ -196,6 +213,19 @@ async function emitBulletRows(ctx) {
         const description = ev.description.length > DESCRIPTION_MAX
             ? ev.description.slice(0, DESCRIPTION_MAX)
             : ev.description;
+        if (specIndex !== undefined) {
+            // One feature, one row: the tree's placement and inventory facts, the spec's lifecycle.
+            ctx.rows[specIndex] = {
+                ...ctx.rows[specIndex],
+                parent_group_id: parentGroupId,
+                description,
+                maturity: maturityFromRunway(ev.runway),
+                runway: ev.runway,
+            };
+            if (!ctx.idBySlug.has(ev.slug))
+                ctx.idBySlug.set(ev.slug, id);
+            continue;
+        }
         ctx.rows.push({
             id,
             name: ev.slug,

package/dist/lib/catalogue/builders/requirements.js

@@ -276,7 +276,7 @@ export async function buildRequirements(inputs) {
             structureEffects.push(effectRow(scoped(dir), "structure", e.element, e.operation, e.base ?? "", e.target ?? ""));
         if (evidence !== null) {
             const repos = observedIn(evidence);
-            if (repos.length === 0) {
+            if (repos.length === 0 && delta.length > 0) {
                 findings.add("convention", `${rel(sddPath, join(changeDir, "baseline-evidence.md"))}: no "**Observed in:**" line, so its requirements carry no observed status`);
             }
             for (const repo of repos)

package/dist/lib/snapshot/land.js

@@ -6,7 +6,11 @@
 //   - a member observed after the set date;
 //   - a prior member absent from the export and not declared carried (with a
 //     reason) or removed (with a reason) — never left to be inferred;
-//   - a member re-exported at the same revision whose bytes differ;
+//   - a member re-exported at the same revision whose bytes differ, unless the only
+//     difference is files under a path declared --not-source (with a reason) that the
+//     prior export holds and the new one does not: analysis a tool wrote into the old
+//     export, not the repository. The prior baseline is never edited, the excused files
+//     and the reason are recorded, and a declaration that excuses nothing is refused;
 //   - no recorded credential scan, or one with findings but no disposition —
 //     a snapshot owner often cannot remediate upstream code, so findings land
 //     with the disposition on the record, never as a false `clean`;
@@ -68,6 +72,17 @@ export async function land(inputs, write) {
         const s = splitFolder(m.exported_folder_name);
         return s ? [[s.stem, m.canonical_repo_key]] : [];
     }));
+    const notSource = new Map();
+    for (const [raw, reason] of inputs.notSource ?? []) {
+        const p = raw.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+        if (p === "" || p.startsWith("/") || p.split("/").includes(".."))
+            throw new SnapshotError(`--not-source '${raw}' must be a relative path inside a member folder`);
+        if (!reason.trim())
+            throw new SnapshotError(`--not-source ${raw} needs a reason: --not-source <path>=<why it is not source>`);
+        notSource.set(p, reason.trim());
+    }
+    const declaredPath = (f) => [...notSource.keys()].find((p) => f === p || f.startsWith(`${p}/`));
+    const excusedBy = new Map();
     const known = inputs.sddPath ? await knownRepositoryIds(inputs.sddPath) : new Set();
     const keyProblems = [];
     const members = [];
@@ -105,18 +120,35 @@ export async function land(inputs, write) {
             const before = await hashTree(memberBytesDir(areaRoot, prior, p));
             const after = await hashTree(join(dir, folder));
             const d = diffTrees(before, after);
-            const changed = d.added.length + d.removed.length + d.modified.length;
+            // Only a file the prior export holds and the new one lacks, under a declared path, is excused.
+            const excused = d.removed.filter((f) => declaredPath(f) !== undefined);
+            const changed = d.added.length + d.modified.length + d.removed.length - excused.length;
             if (changed > 0) {
-                throw new SnapshotError(`${key} was re-exported at the same revision ${revision} as ${prior.snapshot_id}, but ${changed} file(s) differ — one of the two exports is not what its name says`);
+                throw new SnapshotError(`${key} was re-exported at the same revision ${revision} as ${prior.snapshot_id}, but ${changed} file(s) differ — one of the two exports is not what its name says` +
+                    (notSource.size > 0 ? ` (--not-source excuses only files the prior export holds and this one does not, under a declared path)` : ""));
             }
             entry.reverified_at = md ?? id;
             entry.reverification = `re-exported at the same revision as ${prior.snapshot_id}; ${after.size} file(s) byte-identical`;
+            if (excused.length > 0) {
+                const byPath = new Map();
+                for (const f of excused) {
+                    const p = declaredPath(f);
+                    byPath.set(p, (byPath.get(p) ?? 0) + 1);
+                    excusedBy.set(p, (excusedBy.get(p) ?? 0) + 1);
+                }
+                entry.reverification += `; ${[...byPath].map(([p, n]) => `${n} file(s) under ${p}/ in ${prior.snapshot_id} only, not source: ${notSource.get(p)}`).join("; ")}`;
+                write(`note: ${key}: ${excused.length} file(s) under a --not-source path excused (prior export only)\n`);
+            }
         }
         members.push(entry);
     }
     if (keyProblems.length > 0) {
         throw new SnapshotError(`${keyProblems.length} derived key(s) are not repository ids:\n  - ${keyProblems.join("\n  - ")}`);
     }
+    const unused = [...notSource.keys()].filter((p) => !excusedBy.has(p));
+    if (unused.length > 0) {
+        throw new SnapshotError(`--not-source ${unused.join(", ")} excused nothing: no same-revision member's prior export holds files there that this one lacks; drop the declaration`);
+    }
     const removed = [];
     const unaccounted = [];
     for (const p of prior?.members ?? []) {

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

@@ -838,6 +838,7 @@ export async function checkBehaviourStore(repo, options = {}) {
             openBaselines.push(change);
     const servedBy = baselines + openBaselines.length > 0 ? await catalogueContracts(repo) : null;
     let surfacesChecked = 0;
+    let structureOnly = 0;
     // The contract moves each archived change records, in archive order. A contract's id derives from its path, so a
     // move changes it; an archived baseline's list names the contract as it was, and is resolved through the moves
     // archived after it rather than edited (M-ADR 0222 §4.4). A surface that vanished with no move still fails.
@@ -900,10 +901,35 @@ export async function checkBehaviourStore(repo, options = {}) {
         }
         return out;
     };
+    /**
+     * Whether a baseline admits behaviour: any requirement in its spec deltas. One that admits none (a structure-only
+     * baseline, such as the removal of structure carved into another SDD) observes no served behaviour, so it has no
+     * surface to account for, and says so with the typed claim "**Surfaces:** none".
+     */
+    const admitsBehaviour = async (dir) => {
+        for (const feature of await dirs(join(repo, dir, "specs"))) {
+            if (parseRequirements((await readText(join(repo, dir, "specs", feature, "spec.md"))) ?? "").length > 0)
+                return true;
+        }
+        return false;
+    };
     /** What is wrong with a baseline's Surfaces list against the catalogue (M-ADR 0222 §4.3, §4.4). */
     const surfaceProblems = async (dir, evidence, after = -1) => {
         const out = [];
         const parsed = parseSurfaces(evidence);
+        const admits = await admitsBehaviour(dir);
+        if (!admits) {
+            if (parsed.none) {
+                structureOnly++;
+                return out;
+            }
+            if (parsed.entries.length === 0) {
+                return [`${dir}/baseline-evidence.md: the baseline admits no behaviour (no requirement in its spec deltas), so no surface is observed: write "**Surfaces:** none" (and "**Observed in:** none" where no repository is observed)`];
+            }
+        }
+        else if (parsed.none) {
+            return [`${dir}/baseline-evidence.md: **Surfaces:** none, but the baseline admits behaviour (requirements in ${dir}/specs/); name every contract the observed repositories serve, covered at transport or excluded with a reason`];
+        }
         if (!parsed.present)
             out.push(`${dir}/baseline-evidence.md: no **Surfaces:** list; name every contract the observed repositories serve, covered at transport or excluded with a reason`);
         for (const p of parsed.problems)
@@ -1022,7 +1048,7 @@ export async function checkBehaviourStore(repo, options = {}) {
     if (openBaselines.length > 0)
         lines.push(`open baselines: ${openBaselines.length}, asked the archive's questions as warnings`);
     const unseen = servedBy === null ? "" : `; repositories with no catalogue contracts: ${[...new Set(await observedInAll(repo, archiveRel, order))].filter((r) => (servedBy.get(r)?.served ?? []).length === 0).join(", ") || "none"}`;
-    lines.push(baselines === 0 ? "surfaces: vacuous (no baseline)" : `surfaces: ${baselines} baseline(s), ${surfacesChecked} served contract(s) checked against catalogues/repo_contract.csv less what service_contract records only consumed${unseen}${historical.size ? `; ${historical.size} historical baseline(s) not checked (every requirement they baselined has left the living specs)` : ""}`);
+    lines.push(baselines === 0 ? "surfaces: vacuous (no baseline)" : `surfaces: ${baselines} baseline(s), ${surfacesChecked} served contract(s) checked against catalogues/repo_contract.csv less what service_contract records only consumed${unseen}${structureOnly ? `; ${structureOnly} structure-only baseline(s) admitting no behaviour, Surfaces: none` : ""}${historical.size ? `; ${historical.size} historical baseline(s) not checked (every requirement they baselined has left the living specs)` : ""}`);
     lines.push(scopeChecked === 0 ? "scope: vacuous (no baseline removes, modifies or renames a requirement)" : `scope: ${scopeChecked} requirement(s) a baseline removes, modifies or renames, checked against their lineage`);
     if (!history && archived.length > 0)
         lines.push("order: no git history (not a git work tree, or git log failed), so same-day archives cannot be ordered");

package/dist/lib/validate/feature-spec-pointers.js

@@ -14,6 +14,9 @@
 //   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.
+// A pointer is not a restatement: under a behaviour heading, a line naming `openspec/specs/<feature-id>/` is the
+// pointer the template asks for there ("## Acceptance Criteria" with "shipped, see openspec/specs/…: <names>"), unless
+// it is itself a criterion (a checkbox) or a Given/When/Then line.
 // 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
@@ -29,6 +32,8 @@ 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/;
+const POINTER_LINE = /openspec\/specs\/[^/\s`)]+/;
+const CHECKBOX = /^\s*(?:[-*]|\d+\.)\s+\[[ xX]\]/;
 /** "## 3. Edge Cases (Revised)" -> "edge cases". */
 function headingKey(h) {
     return h.replace(/^\s*\d+(\.\d+)*\.?\s*/, "").replace(/\((revised|updated)\)\s*$/i, "").trim().toLowerCase();
@@ -72,6 +77,8 @@ export function scanRestated(text) {
         if (!line.trim() || /^\s*\|?[\s:|-]+\|[\s:|-]*$/.test(line))
             continue; // blank, or a table separator
         if (stack.some((s) => BEHAVIOUR_HEADING.test(s.key))) {
+            if (POINTER_LINE.test(line) && !CHECKBOX.test(line) && !GHERKIN.test(line))
+                continue; // the pointer itself
             out.sections.push(n);
             continue;
         }

package/dist/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.17.0",
-  "built_against_sdd_cli": "5.3.0"
+  "version": "0.17.2",
+  "built_against_sdd_cli": "5.3.2"
 }

package/dist/verbs/snapshot.js

@@ -72,6 +72,7 @@ export function registerSnapshot(program) {
         .option("--role-hint <key=role>", "role_hint for a member; continuing members otherwise keep the prior baseline's (repeatable)", collectPairs, new Map())
         .option("--credential-scan <record>", "tool=…,version=…,date=YYYY-MM-DD,result=clean — or result=<findings>,disposition=<what, and why it stands>")
         .option("--notes <text>", "coherence caveats for the manifest")
+        .option("--not-source <path=reason>", "a path inside member folders that is not source (a folder a tool wrote into the prior export), and why: a same-revision re-export may lack it, recorded on the member; nothing else is excused (repeatable)", collectPairs, new Map())
         .action(async (area, o) => {
         const scan = record(o.credentialScan);
         exit(await runSnapshotLand({
@@ -85,6 +86,7 @@ export function registerSnapshot(program) {
             removed: o.removed,
             keys: o.key,
             roleHints: o.roleHint,
+            notSource: o.notSource,
             ...(scan ? { credentialScan: scan } : {}),
             ...(o.notes !== undefined ? { notes: o.notes } : {}),
         }, out));

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "5.3.0",
-  "built_against_sdd_cli": "5.3.0"
+  "version": "5.3.2",
+  "built_against_sdd_cli": "5.3.2"
 }

package/package.json

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

package/scripts/validate-app-docs.sh

@@ -8,10 +8,16 @@
 #   1. service-architecture.md is present
 #   2. feature-tree.md is present (may be at docs/ or repo root)
 #   3. app-platform-dependencies.yaml is present
-#   4. Feature spec files under features/*/ have required sections:
+#   4. Feature spec files under features/ have required sections:
 #      - ## Overview
-#      - ## Acceptance Criteria
+#      - ## Acceptance Criteria (a prefix: the template's heading is
+#        "## Acceptance Criteria Summary"; once the feature ships it holds the
+#        pointer to its living spec, M-ADR 0221 §4.3)
 #      - ## Platform Contract Dependencies
+#   5. Feature specs sit at features/<feature>/<feature>.md, one directory per
+#      feature with its story files beside it (the app-feature-spec skill's
+#      path). A spec stored flat at features/<name>.md is reported as [WARN],
+#      advisory: it does not fail the run.
 #
 # Does NOT check:
 #   - Glossary alignment (no domain glossary in app repos)
@@ -142,6 +148,7 @@ check_feature_specs() {
     local specs_found=0
     local specs_failed=0
     local specs_passed=0
+    local specs_flat=0
 
     # Discover feature specs under features/*/
     local feature_spec
@@ -157,6 +164,12 @@ check_feature_specs() {
             fi
         done
 
+        if [[ "$(dirname "$feature_spec")" == "$APP_ROOT/features" ]]; then
+            local name; name="$(basename "$feature_spec" .md)"
+            log_warn "$rel: stored flat under features/; a feature spec's path is features/${name}/${name}.md, one directory per feature with its story files beside it (app-feature-spec skill). Advisory: reported, not failed"
+            specs_flat=$((specs_flat + 1))
+        fi
+
         if [[ "$file_failures" -eq 0 ]]; then
             log_pass "$rel: all required sections present"
             specs_passed=$((specs_passed + 1))
@@ -172,6 +185,9 @@ check_feature_specs() {
     fi
 
     log_info "Group 2: $specs_passed/$specs_found feature specs passed, $specs_failed failed"
+    if [[ "$specs_flat" -gt 0 ]]; then
+        log_warn "Group 2: $specs_flat of $specs_found feature spec(s) stored flat under features/ (advisory)"
+    fi
 }
 
 # ──────────────────────────────────────────────────────────────────────────────