@sdd-method/sdd-cli 1.40.0 → 1.42.0

package/scripts/{build-verify-package.mjs → build-persona-package.mjs}

@@ -1,9 +1,11 @@
-// Assemble the publishable @sdd-method/verify-cli package — M-ADR 0212 §4.3b.
+// Assemble a publishable persona package — @sdd-method/verify-cli (M-ADR 0212 §4.3b) or
+// @sdd-method/maintain-cli (M-ADR 0218). Usage: build-persona-package.mjs [verify|maintain]
+// (default verify). One script, so both packages hold the same boundary discipline.
 //
 // ONE SOURCE, and this time a genuinely smaller ARTEFACT. The conformance
 // package copied the whole of dist/ under a second manifest, so its "excluded"
 // verbs were one `node dist/cli.js …` away. This script ships only the import
-// CLOSURE of dist/verify-bin.js: an excluded verb's code is not in the package
+// CLOSURE of the persona's entrypoint (dist/verify-bin.js, dist/maintain-bin.js): an excluded verb's code is not in the package
 // to be reached by any path.
 //
 // Fails closed on four conditions, each of which would otherwise let the
@@ -29,29 +31,85 @@ const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 // session on the machine (2026-10-01, about nine hours). `npm run verify:boundary` builds
 // into build/check-dist and checks that instead; only a release should write dist/.
 const DIST = process.env.SDD_CLI_DIST ? resolve(process.env.SDD_CLI_DIST) : join(ROOT, "dist");
-const OUT = join(ROOT, "build", "verify-cli");
-const ENTRY = join(DIST, "verify-bin.js");
-
-// Authoring and maintenance code that must never reach this package. Entry
-// modules of excluded verbs plus the full CLI's own entrypoints.
-const CANARIES = [
+const PERSONA = process.argv[2] ?? "verify";
+// Modules that must never reach a package. Authoring for both; maintain's own verbs are
+// canaries only for verify (they are maintain's payload). Each list names modules that EXIST,
+// or the check below fails rather than passing vacuously.
+const AUTHOR_CANARIES = [
   "cli.js",
   "index.js",
-  "verbs/sync.js",
-  "verbs/catalogue.js",
-  "verbs/pack.js",
   "verbs/mcp.js",
   "verbs/init.js",
-  "verbs/render.js",
   "verbs/metamodel.js",
   "verbs/conformance.js",
-  "lib/sync/index.js",
-  "lib/catalogue/build.js",
-  "lib/catalogue/aggregate.js",
-  "lib/catalogue/graph-run.js",
+  "verbs/scaffold.js",
+  "verbs/plan.js",
+  "verbs/contracts.js",
+  "verbs/api-surface.js",
+  "verbs/snapshot.js",
+  "verbs/catalogue.js",
   "lib/catalogue/migration-map.js",
-  "lib/pack/builder.js",
+  "lib/mcp/server.js",
+  "lib/snapshot/land.js",
 ];
+const PERSONAS = {
+  verify: {
+    entry: "verify-bin.js",
+    out: "verify-cli",
+    versionFile: "verify-version.json",
+    versionEnv: "VERIFY_VERSION",
+    name: "@sdd-method/verify-cli",
+    bin: "sdd-verify",
+    canaries: [
+      ...AUTHOR_CANARIES,
+      "verbs/sync.js",
+      "verbs/pack.js",
+      "verbs/render.js",
+      "lib/sync/index.js",
+      "lib/catalogue/build.js",
+      "lib/catalogue/aggregate.js",
+      "lib/catalogue/graph-run.js",
+      "lib/pack/builder.js",
+    ],
+    description:
+      "Verify an SDD repository without changing it — validate, list, and read-only catalogue and pack checks. Ships only the code those verbs reach; it cannot write to the repository it is pointed at. Authoring and maintenance are in @sdd-method/sdd-cli.",
+    readme:
+      `# @sdd-method/verify-cli\n\n` +
+      `\`sdd-verify\` checks an SDD repository and **cannot change it**.\n\n` +
+      `Verbs: \`validate\`, \`list\`, \`pack validate\`, \`catalogue validate\` (incl. \`--coverage\`), ` +
+      `\`catalogue impact\`, \`catalogue baseline-check\`, \`catalogue version\`.\n\n` +
+      `The package contains only the code those verbs reach. Authoring and maintenance verbs — ` +
+      `\`sync\`, \`catalogue build\`, \`init\`, \`scaffold\`, \`mcp\` and the rest — are not present in it, ` +
+      `and are in \`@sdd-method/sdd-cli\`. Invoking one fails with exit 1.\n`,
+  },
+  maintain: {
+    entry: "maintain-bin.js",
+    out: "maintain-cli",
+    versionFile: "maintain-version.json",
+    versionEnv: "MAINTAIN_VERSION",
+    name: "@sdd-method/maintain-cli",
+    bin: "sdd-maintain",
+    canaries: AUTHOR_CANARIES,
+    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.",
+    readme:
+      `# @sdd-method/maintain-cli\n\n` +
+      `\`sdd-maintain\` brings an SDD repository current and rebuilds its derived model, and **cannot author specification content** (M-ADR 0218).\n\n` +
+      `Verbs: everything in \`@sdd-method/verify-cli\`, plus \`sync\`, \`generate-briefing\`, \`context pull\`, ` +
+      `\`catalogue build\`, \`catalogue aggregate\`, \`catalogue graph\`, \`catalogue diff\`, \`pack build\`, \`render screen\`.\n\n` +
+      `Each writes only derived or method-managed content, and two runs on the same commit write the same bytes. ` +
+      `Authoring verbs — \`init\`, \`scaffold\`, \`plan\`, \`mcp\`, \`conformance\` and the rest — are not present in it, ` +
+      `and are in \`@sdd-method/sdd-cli\`. Invoking one fails with exit 1.\n`,
+  },
+};
+const P = PERSONAS[PERSONA];
+if (!P) {
+  process.stderr.write(`build-persona-package: FAIL — unknown persona '${PERSONA}' (verify | maintain)\n`);
+  process.exit(1);
+}
+const OUT = join(ROOT, "build", P.out);
+const ENTRY = join(DIST, P.entry);
+
 
 const die = (msg) => {
   process.stderr.write(`build-verify-package: FAIL — ${msg}\n`);
@@ -112,10 +170,10 @@ for (const spec of bare) {
 }
 
 // ---- 3 + 4. canaries -------------------------------------------------------
-for (const c of CANARIES) {
+for (const c of P.canaries) {
   const abs = join(DIST, c);
   if (!existsSync(abs)) die(`canary '${c}' no longer exists in dist — the check would pass vacuously; update CANARIES`);
-  if (closure.has(abs)) die(`authoring module '${c}' is reachable from verify-bin.js — the boundary does not hold`);
+  if (closure.has(abs)) die(`excluded module '${c}' is reachable from ${P.entry} — the ${PERSONA} boundary does not hold`);
 }
 
 // ---- bundled shell scripts -------------------------------------------------
@@ -136,24 +194,42 @@ for (const f of closure) {
 }
 
 // ---- assets: yaml/json data beside a closure module ------------------------
+// Data a module reads by path at runtime is invisible to the import closure. Beside the module, and
+// in DATA-ONLY subdirectories under it (no .js inside): maintain-cli's first build missed
+// lib/catalogue/archetype/maps/*.yaml, so `render screen` crashed with ENOENT where sdd-cli rendered.
 const assets = new Set();
+const dataOnlyFiles = (dir) => {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  if (entries.some((e) => e.isFile() && e.name.endsWith(".js"))) return [];
+  return entries.flatMap((e) => {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) return dataOnlyFiles(p);
+    return /\.(ya?ml|json)$/.test(e.name) ? [p] : [];
+  });
+};
 for (const f of closure) {
   const dir = dirname(f);
-  for (const name of readdirSync(dir)) {
-    const p = join(dir, name);
-    if (/\.(ya?ml|json)$/.test(name) && statSync(p).isFile()) assets.add(p);
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isFile() && /\.(ya?ml|json)$/.test(e.name)) assets.add(p);
+    else if (e.isDirectory()) for (const d of dataOnlyFiles(p)) assets.add(d);
   }
 }
 
 // ---- assemble --------------------------------------------------------------
-// The version is COMMITTED (scripts/verify-version.json), not defaulted. Defaulting to "0.1.0" let a build
+// The version is COMMITTED (scripts/<persona>-version.json), not defaulted. Defaulting to "0.1.0" let a build
 // of new source carry an old version silently; verify-cli then fell two sdd-cli releases behind unnoticed.
 // Bump the file in every sdd-cli release commit (minor with the CLI's minor; patch for fixes).
-const versionFile = JSON.parse(readFileSync(join(ROOT, "scripts", "verify-version.json"), "utf8"));
+const versionFile = JSON.parse(readFileSync(join(ROOT, "scripts", P.versionFile), "utf8"));
 const version = versionFile.version;
-if (!/^\d+\.\d+\.\d+$/.test(version ?? "")) die("scripts/verify-version.json has no semver `version`");
-if (process.env.VERIFY_VERSION && process.env.VERIFY_VERSION !== version)
-  die(`VERIFY_VERSION=${process.env.VERIFY_VERSION} disagrees with scripts/verify-version.json (${version}); edit the file`);
+if (!/^\d+\.\d+\.\d+$/.test(version ?? "")) die(`scripts/${P.versionFile} has no semver \`version\``);
+// The engine this package is built from. Every engine-meaning check reads it (getSddCliVersion):
+// a bundle's floor, catalogue stamps, the MCP identity. A stale built_against in the version file
+// would ship a package claiming an engine it is not, so the build refuses it.
+if (versionFile.built_against_sdd_cli !== main.version)
+  die(`scripts/${P.versionFile} says built_against_sdd_cli ${versionFile.built_against_sdd_cli}, but this sdd-cli is ${main.version}; update the file`);
+if (process.env[P.versionEnv] && process.env[P.versionEnv] !== version)
+  die(`${P.versionEnv}=${process.env[P.versionEnv]} disagrees with scripts/${P.versionFile} (${version}); edit the file`);
 // Empty the directory, never remove it: a shell sitting in build/verify-cli
 // (to run `npm publish`) keeps a handle on the directory itself, and deleting
 // it leaves that shell in a path that no longer exists — npm then dies with
@@ -171,40 +247,30 @@ for (const p of bundled) {
 }
 for (const f of ["LICENSE", "NOTICE"]) await cp(join(ROOT, f), join(OUT, f));
 
-if (main.publishConfig?.access !== "public") die("sdd-cli's package.json has no publishConfig.access=public — the verify package would publish private");
+if (main.publishConfig?.access !== "public") die(`sdd-cli's package.json has no publishConfig.access=public — ${P.name} would publish private`);
 
 const pkg = {
-  name: "@sdd-method/verify-cli",
+  name: P.name,
   version,
-  description:
-    "Verify an SDD repository without changing it — validate, list, and read-only catalogue and pack checks. Ships only the code those verbs reach; it cannot write to the repository it is pointed at. Authoring and maintenance are in @sdd-method/sdd-cli.",
+  sddCliVersion: main.version,
+  description: P.description,
   license: main.license,
   type: main.type,
-  bin: { "sdd-verify": "dist/verify-bin.js" },
+  bin: { [P.bin]: `dist/${P.entry}` },
   engines: main.engines,
   dependencies: deps,
   repository: main.repository,
   // Inherited, not assumed: a scoped package publishes PRIVATE by default, and
-  // the first publish of this one failed with E402 (private packages need a
-  // paid plan) because this field was missing. sdd-cli carries it; so must this.
+  // the first publish of verify-cli failed with E402 because this was missing.
   publishConfig: main.publishConfig,
   files: ["dist", "scripts", "README.md", "LICENSE", "NOTICE"],
 };
 await writeFile(join(OUT, "package.json"), `${JSON.stringify(pkg, null, 2)}\n`);
-await writeFile(
-  join(OUT, "README.md"),
-  `# @sdd-method/verify-cli\n\n` +
-    `\`sdd-verify\` checks an SDD repository and **cannot change it**.\n\n` +
-    `Verbs: \`validate\`, \`list\`, \`pack validate\`, \`catalogue validate\` (incl. \`--coverage\`), ` +
-    `\`catalogue impact\`, \`catalogue baseline-check\`, \`catalogue version\`.\n\n` +
-    `The package contains only the code those verbs reach. Authoring and maintenance verbs — ` +
-    `\`sync\`, \`catalogue build\`, \`init\`, \`scaffold\`, \`mcp\` and the rest — are not present in it, ` +
-    `and are in \`@sdd-method/sdd-cli\`. Invoking one fails with exit 1.\n`,
-);
+await writeFile(join(OUT, "README.md"), P.readme);
 
 const kb = (fs) => Math.round(fs.reduce((n, f) => n + statSync(f).size, 0) / 1024);
 process.stdout.write(
-  `assembled ${pkg.name}@${version} at build/verify-cli\n` +
+  `assembled ${pkg.name}@${version} at build/${P.out}\n` +
     `  modules ${closure.size} (${kb([...closure])} kB) · assets ${assets.size} · bundled scripts ${bundled.size} · deps ${Object.keys(deps).join(", ")}\n` +
-    `  canaries absent: ${CANARIES.length}/${CANARIES.length}\n`,
+    `  canaries absent: ${P.canaries.length}/${P.canaries.length}\n`,
 );

package/scripts/copy-yaml-assets.mjs

@@ -35,4 +35,10 @@ for await (const srcFile of walk(SRC)) {
   await copyFile(srcFile, destFile);
   copied++;
 }
+// The verify-cli version the CI workflow pins (getVerifyCliVersion). Copied, not read live from
+// scripts/, so it moves with dist/ and never ahead of it.
+for (const persona of ["verify", "maintain"]) {
+  await copyFile(join(__dirname, `${persona}-version.json`), join(DEST, `${persona}-version.json`));
+  copied++;
+}
 console.log(`copy-yaml-assets: ${copied} file(s) copied to dist/`);

package/scripts/dagger-parity.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# dagger-parity.sh — per-step parity between the Method Validation Dagger module and the same plan
+# (sdd-verify validate --list) run directly with the same CLIs (sdm-dd6.3; Dagger ruling sdm-s48).
+# Run it on a release candidate: build the persona packages (npm run verify:boundary), then
+# scripts/dagger-parity.sh <sdd-repo>...   It packs them unless PKGS names a directory already
+# holding the tarballs. Needs the dagger CLI and a container engine (M-ADR 0219 §4.5).
+set -u
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+if [ -n "${SCRATCH:-}" ]; then SP=$SCRATCH; else SP=$(mktemp -d); trap 'rm -rf "$SP"' EXIT; fi
+CLI=$ROOT/build
+PKGS=${PKGS:-$SP/pkgs}
+if [ ! -d "$PKGS" ]; then
+  mkdir -p "$PKGS"
+  (cd "$CLI/verify-cli" && npm pack --silent --pack-destination "$PKGS" >/dev/null)
+  (cd "$CLI/maintain-cli" && npm pack --silent --pack-destination "$PKGS" >/dev/null)
+fi
+VV=$(node -p "require('$CLI/verify-cli/package.json').version"); MV=$(node -p "require('$CLI/maintain-cli/package.json').version")
+# The module exactly as sync renders it (M-ADR 0219 §6), from the built maintain-cli, with the
+# candidate versions as its pins.
+MOD=$SP/module
+node --input-type=module -e "
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const { renderModuleFiles } = await import('$CLI/maintain-cli/dist/lib/ci-binding/module.js');
+for (const [rel, c] of renderModuleFiles({ verify: '$VV', maintain: '$MV' })) {
+  const p = join('$MOD', rel); mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, c);
+}"
+VERIFY="node $CLI/verify-cli/dist/verify-bin.js"
+MAINTAIN="node $CLI/maintain-cli/dist/maintain-bin.js"
+OUT=$SP/dagger-spike-out; mkdir -p "$OUT"
+FAIL=0
+for repo in "$@"; do
+  name=$(basename "$repo")
+  W=$(mktemp -d -p "$SP")
+  git clone -q --no-hardlinks "$repo" "$W/$name"
+  sha=$(git -C "$W/$name" rev-parse --short=8 HEAD)
+  echo "=== $name @ $sha"
+  # 1. Dagger, on Docker
+  start=$(date +%s)
+  ( cd "$MOD" && DAGGER_NO_NAG=1 timeout 1500 dagger -q call method-validation \
+      --source="$W/$name" --verify-version=$VV --maintain-version=$MV \
+      --verify-tarball="$PKGS/sdd-method-verify-cli-$VV.tgz" --maintain-tarball="$PKGS/sdd-method-maintain-cli-$MV.tgz" ) > "$OUT/$name.dagger.log" 2>&1
+  drc=$?; secs=$(( $(date +%s) - start ))
+  sed "s/\x1b\[[0-9;]*m//g" "$OUT/$name.dagger.log" | grep -oE "^ *(PASS|FAIL|ADVISORY) +exit [0-9]+  [a-z0-9-]+" | sed "s/^ *//" | awk '{print $4, $3}' | sort > "$OUT/$name.dagger.steps"
+  # 2. The same plan, directly on the host (a second clone, so neither run sees the other)
+  git clone -q --no-hardlinks "$repo" "$W/direct"
+  ( cd "$W/direct" && $VERIFY validate --list ) > "$OUT/$name.plan.json"
+  python3 - "$OUT/$name.plan.json" > "$OUT/$name.cmds" <<'PY'
+import json, sys
+for s in json.load(open(sys.argv[1]))["steps"]:
+    print(s["id"], s["tool"], " ".join(s["args"]))
+PY
+  : > "$OUT/$name.direct.steps"
+  while read -r id tool args; do
+    case "$tool" in
+      sdd-verify) cmd="$VERIFY $args" ;;
+      sdd-maintain) cmd="$MAINTAIN $args" ;;
+      bash) cmd="bash $args" ;;
+    esac
+    ( cd "$W/direct" && eval "$cmd" ) > "$OUT/$name.direct.$id.log" 2>&1
+    echo "$id $?" >> "$OUT/$name.direct.steps"
+  done < "$OUT/$name.cmds"
+  sort -o "$OUT/$name.direct.steps" "$OUT/$name.direct.steps"
+  n=$(wc -l < "$OUT/$name.direct.steps")
+  if [ "$(wc -l < "$OUT/$name.dagger.steps")" -ne "$n" ]; then
+    echo "  FAIL dagger reported $(wc -l < "$OUT/$name.dagger.steps") steps, the plan has $n (dagger exit $drc; see $name.dagger.log)"; FAIL=$((FAIL+1))
+  elif diff -q "$OUT/$name.dagger.steps" "$OUT/$name.direct.steps" >/dev/null; then
+    echo "  PARITY $n/$n steps, identical exit codes (dagger exit $drc, ${secs}s); $(awk '$2!=0' "$OUT/$name.direct.steps" | wc -l) step(s) non-zero in both"
+  else
+    echo "  FAIL step exit codes differ:"; diff "$OUT/$name.dagger.steps" "$OUT/$name.direct.steps" | sed 's/^/    /'; FAIL=$((FAIL+1))
+  fi
+  rm -rf "$W"   # the logs are in $OUT; two clones per repo add up across an estate
+done
+[ $FAIL -eq 0 ] && echo "SPIKE PARITY: PASS" || echo "SPIKE PARITY: FAIL ($FAIL)"

package/scripts/maintain-acceptance.mjs

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+// Acceptance for the maintain CLI — M-ADR 0218 §4.2–4.3.
+//
+// The property: every write sdd-maintain makes is DERIVED or METHOD-MANAGED, and is a
+// deterministic function of its inputs. Tested, not asserted. For each workspace: fresh clones,
+// each maintain verb run twice, and after each run
+//   (a) SCOPE: every path `git status --porcelain --ignored` reports is in the
+//       derived-and-managed set (the lock's own managed paths included);
+//   (b) DETERMINISM: the second run on the same commit leaves exactly the bytes the first did.
+// Fails closed on: an out-of-set write, a second run that changes anything, a verb that crashes,
+// and the CONTROL: a deliberate out-of-set write must be SEEN, or every PASS is vacuous.
+// Verbs it cannot exercise in a workspace are listed under COVERAGE, never passed silently.
+//
+//   (c) PARITY: the same verb run by the full sdd-cli (--control-bin) on a twin workspace leaves a
+//       byte-identical tree. Scope and determinism cannot see a verb that crashes or renders
+//       differently; verify-cli learned the same lesson (0.1.0 shipped missing bundled scripts).
+// usage: maintain-acceptance.mjs --bin <maintain-bin.js> --control-bin <sdd-cli cli.js> --dist <sdd-method dist dir> <sdd-repo>...
+//   Each <sdd-repo> is cloned with the siblings its aggregation manifest names (paths kept),
+//   so `catalogue aggregate` runs on a platform root.
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, relative, resolve } from "node:path";
+
+const args = process.argv.slice(2);
+const opt = (k) => { const i = args.indexOf(k); if (i === -1) return undefined; const v = args[i + 1]; args.splice(i, 2); return v; };
+const BIN = resolve(opt("--bin") ?? die("--bin required"));
+const DIST = resolve(opt("--dist") ?? die("--dist required"));
+const CONTROL = resolve(opt("--control-bin") ?? die("--control-bin required (the full sdd-cli, for parity)"));
+const REPOS = args.map((a) => resolve(a));
+if (REPOS.length === 0) die("give at least one SDD repository");
+
+function die(m) { process.stderr.write(`maintain-acceptance: ${m}\n`); process.exit(2); }
+let FAIL = 0;
+const fail = (m) => { FAIL++; process.stdout.write(`  FAIL ${m}\n`); };
+const ok = (m) => process.stdout.write(`  ok   ${m}\n`);
+const exercised = new Set();
+
+// ---- the derived-and-managed set (M-ADR 0218 §4.3) -------------------------------------------
+const FIXED = [
+  /^method-baseline\.lock$/, /^\.sdd-repo-kind$/,                    // item 2
+  /^\.github\/workflows\/method-validation\.yml$/,                   // item 3 (block-merged)
+  /^\.gitlab-ci\.yml$/, /^\.jenkins\/method-validation\.Jenkinsfile$/, // item 3, the other CI bindings (M-ADR 0219 §4.4)
+  /^\.dagger\/method-validation\//,                                   // item 3, the module every binding calls (M-ADR 0219 §4.3)
+  /^agent-instructions\.md$/, /^CLAUDE\.md$/, /^AGENTS\.md$/,        // item 4
+  /^\.claude\/settings\.json$/, /^\.github\/hooks\//, /^\.github\/copilot\//, // item 5
+  /^catalogues\//, /^catalogues-aggregated\//, /^catalogues(-aggregated)?-graph\.jsonl$/, // item 7
+  /^\.sdd\/bundle-cache\//,                                           // sync's cache of the last-applied bundle (managed by sync itself)
+  /^MCP_SETUP\.md$/,                                                  // item 9 (code repo)
+];
+function lockManaged(repo) {
+  const p = join(repo, "method-baseline.lock");
+  if (!existsSync(p)) return new Set();
+  const out = new Set();
+  for (const line of readFileSync(p, "utf8").split("\n")) {
+    const m = /^ {6}- "?(?:[0-9a-f]{64} {2})?([^"]+)"?$/.exec(line);
+    if (m) out.add(m[1]);
+  }
+  return out;
+}
+function outOfSet(repo, managed) {
+  const st = spawnSync("git", ["-C", repo, "status", "--porcelain", "--ignored", "--untracked-files=all"], { encoding: "utf8" });
+  const bad = [];
+  for (const line of st.stdout.split("\n").filter(Boolean)) {
+    let p = line.slice(3);
+    if (p.includes(" -> ")) p = p.split(" -> ")[1];
+    p = p.replace(/^"|"$/g, "");
+    if (managed.has(p) || FIXED.some((rx) => rx.test(p))) continue;
+    bad.push(p);
+  }
+  return bad;
+}
+// A digest of every file git reports as changed, for the determinism check.
+// Workspace roots are normalised so the twin (another temp path) can be compared: context pull, for
+// one, writes the SDD's absolute path into what it renders.
+function snapshot(repo, roots = []) {
+  const st = spawnSync("git", ["-C", repo, "status", "--porcelain", "--ignored", "--untracked-files=all"], { encoding: "utf8" });
+  const h = createHash("sha256");
+  for (const line of st.stdout.split("\n").filter(Boolean).sort()) {
+    const p = line.slice(3).split(" -> ").pop().replace(/^"|"$/g, "");
+    h.update(line.slice(0, 3) + p + "\0");
+    const abs = join(repo, p);
+    if (existsSync(abs) && statSync(abs).isFile()) {
+      let text = readFileSync(abs, "latin1");
+      for (const r of roots) text = text.split(r).join("<WS>");
+      h.update(text, "latin1");
+    }
+  }
+  return h.digest("hex");
+}
+
+// ---- workspace -------------------------------------------------------------------------------
+// Each workspace clones a whole manifest tree (up to ~55k inodes), and /tmp is a tmpfs whose inode
+// table is the real limit: one release's runs leaked ~450k and filled it. Removed on every exit,
+// failures included; MAINTAIN_ACC_KEEP=1 keeps them for inspection.
+const workspaces = [];
+process.on("exit", () => {
+  if (process.env.MAINTAIN_ACC_KEEP) return void process.stderr.write(`maintain-acceptance: kept ${workspaces.join(" ")}\n`);
+  for (const ws of workspaces) rmSync(ws, { recursive: true, force: true });
+});
+function cloneTree(root) {
+  const ws = mkdtempSync(join(tmpdir(), "maintain-acc-"));
+  workspaces.push(ws);
+  const base = dirname(root);
+  const todo = [root];
+  const seen = new Set();
+  const missing = [];
+  while (todo.length) {
+    const src = todo.pop();
+    if (seen.has(src)) continue;
+    seen.add(src);
+    const dest = join(ws, relative(base, src));
+    mkdirSync(dirname(dest), { recursive: true });
+    execFileSync("git", ["clone", "-q", "--no-hardlinks", src, dest]);
+    const man = join(src, "orchestration", "aggregation-manifest.yaml");
+    if (existsSync(man)) {
+      for (const m of readFileSync(man, "utf8").matchAll(/path: "([^"]+)"/g)) {
+        let p = resolve(src, m[1]);
+        if (["catalogues", "catalogues-aggregated"].includes(basename(p))) p = dirname(p);
+        if (existsSync(join(p, ".git"))) todo.push(p);
+        else missing.push(relative(base, p));
+      }
+    }
+  }
+  return { ws, clone: join(ws, basename(root)), base, missing };
+}
+const run = (repo, verbArgs, bin = BIN) => spawnSync("node", [bin, ...verbArgs], { cwd: repo, encoding: "utf8" });
+// The twin workspace's path for a path in the primary one (parity runs mirror every call).
+let TWIN = null;
+const twinOf = (p) => (TWIN && p.startsWith(TWIN.from) ? TWIN.to + p.slice(TWIN.from.length) : p);
+function twice(label, repo, verbArgs, managedFn, { allowNonZero = false } = {}) {
+  const r1 = run(repo, verbArgs);
+  // An uncaught error (maintain-bin prints "sdd-maintain: <message>") is a CRASH, never a finding,
+  // whatever the exit code allowance: allowNonZero once let an ENOENT pass as render screen's "exit 1".
+  const crashed = /^sdd-maintain: /m.test(r1.stderr ?? "");
+  if (crashed || (r1.status !== 0 && !allowNonZero)) { fail(`${label}: ${crashed ? "CRASHED" : `exit ${r1.status}`} — ${(r1.stderr || r1.stdout).trim().split("\n").pop()}`); return; }
+  const bad1 = outOfSet(repo, managedFn());
+  if (bad1.length) fail(`${label}: wrote outside the derived-and-managed set: ${bad1.slice(0, 5).join(", ")}`);
+  const roots = TWIN ? [TWIN.from, TWIN.to] : [];
+  const s1 = snapshot(repo, roots);
+  const r2 = run(repo, verbArgs);
+  const s2 = snapshot(repo, roots);
+  // parity: the full CLI, same verb, same arguments, on the twin
+  const twinArgs = verbArgs.map((a) => twinOf(a));
+  const rc = run(twinOf(repo), twinArgs, CONTROL);
+  run(twinOf(repo), twinArgs, CONTROL); // keep the twin in step with the primary's second run
+  const sc = snapshot(twinOf(repo), roots);
+  const parity = sc === s2 && rc.status === r1.status;
+  if (!parity) fail(`${label}: PARITY — sdd-cli ${sc === s2 ? "" : "left a different tree, "}exited ${rc.status} where sdd-maintain exited ${r1.status}`);
+  if (s1 !== s2) fail(`${label}: NOT deterministic — the second run on the same commit changed the tree`);
+  else if (!bad1.length && parity) ok(`${label} (exit ${r1.status}): in scope, second run byte-identical, = sdd-cli`);
+  exercised.add(label.split(" @")[0]);
+  void r2;
+}
+
+// ---- control: the detector must see an out-of-set write --------------------------------------
+{
+  const { clone } = cloneTree(REPOS[0]);
+  writeFileSync(join(clone, "docs", "CONTROL-out-of-set.md"), "x\n");
+  if (outOfSet(clone, lockManaged(clone)).includes("docs/CONTROL-out-of-set.md")) ok("CONTROL: an out-of-set write is seen");
+  else fail("CONTROL: an out-of-set write was NOT seen — every scope PASS below would be vacuous");
+}
+
+for (const repo of REPOS) {
+  const { clone, ws, missing } = cloneTree(repo);
+  const twin = cloneTree(repo);
+  TWIN = { from: ws, to: twin.ws };
+  const name = basename(repo);
+  process.stdout.write(`=== ${name} ===\n`);
+  const managed = () => lockManaged(clone);
+  // Bundle the lock is on: re-applying it is a real sync with nothing upstream changed.
+  const lock = readFileSync(join(clone, "method-baseline.lock"), "utf8");
+  const fwd = /- name: ([\w-]+)\n\s+bundle_version: "([^"]+)"(?:[\s\S]*?)is_forward_base: true/.exec(lock);
+  if (fwd) {
+    const tb = join(DIST, fwd[1], `${fwd[1]}-${fwd[2]}.tar.gz`);
+    // A lock that predates the CI digest (written before M-ADR 0218 §4.7) refuses its first sync on
+    // a newer CI render by design, and the wave passes --allow-overwrite exactly once; do the same.
+    const firstDigest = /^ci_workflow_block_sha256:/m.test(lock) ? [] : ["--allow-overwrite"];
+    if (existsSync(tb)) twice(`sync @${name}`, clone, ["sync", "--bundle", tb, "--target-repo", ".", ...firstDigest], managed);
+    else process.stdout.write(`  skip sync: ${tb} not on disk\n`);
+  }
+  twice(`generate-briefing @${name}`, clone, ["generate-briefing", "--target-dir", "."], managed);
+  // A build may exit 1 on pre-existing estate findings; scope and determinism hold either way.
+  twice(`catalogue build @${name}`, clone, ["catalogue", "build", "--sdd-path", "."], managed, { allowNonZero: true });
+  twice(`catalogue graph @${name}`, clone, ["catalogue", "graph", "--sdd-path", "."], managed, { allowNonZero: true });
+  if (existsSync(join(clone, "orchestration", "aggregation-manifest.yaml")) && missing.length > 0) {
+    process.stdout.write(`  skip catalogue aggregate: ${missing.length} manifest sibling(s) not on disk to clone (e.g. ${missing[0]})\n`);
+  } else if (existsSync(join(clone, "orchestration", "aggregation-manifest.yaml"))) {
+    // members first, so the aggregate reads current member catalogues
+    for (const d of readdirSync(ws, { recursive: true }).filter((p) => p.endsWith(".sdd-repo-kind"))) {
+      const member = join(ws, dirname(d));
+      if (member !== clone) {
+        run(member, ["catalogue", "build", "--sdd-path", "."]);
+        run(twinOf(member), ["catalogue", "build", "--sdd-path", "."], CONTROL);
+      }
+    }
+    twice(`catalogue aggregate @${name}`, clone, ["catalogue", "aggregate", "--sdd-path", "."], managed, { allowNonZero: true });
+  }
+  // catalogue diff: from HEAD with an empty delta, so attribution is trivially complete; it writes nothing into the SDD.
+  {
+    const delta = join(ws, `${name}-delta.yaml`);
+    writeFileSync(delta, "findings: []\n");
+    writeFileSync(twinOf(delta), "findings: []\n");
+    twice(`catalogue diff @${name}`, clone, ["catalogue", "diff", "--from", "HEAD", "--attribute", delta, "--sdd-path", "."], managed, { allowNonZero: true });
+  }
+  // pack build: every seed the SDD produces, to an output OUTSIDE its tracked content (§4.3 item 8).
+  const distDir = join(clone, "orchestration", "distribution");
+  if (existsSync(distDir)) {
+    const seed = readdirSync(distDir).find((f) => f.endsWith("-seed.yaml"));
+    if (seed) twice(`pack build @${name}`, clone, ["pack", "build", "--seed", join(distDir, seed), "--producer-repo", ".", "--out-dir", join(ws, "pack-out")], managed, { allowNonZero: true });
+  }
+  // render screen: the first screen spec, to an explicit --out outside the tree (§4.3 item 8).
+  const screens = join(clone, "screens");
+  if (existsSync(screens)) {
+    const spec = readdirSync(screens).find((f) => f.endsWith(".md"));
+    if (spec) twice(`render screen @${name}`, clone, ["render", "screen", join("screens", spec), "--out", join(ws, "screen.svg")], managed);
+  }
+  // context pull: a scratch code repo beside the clone, named for a repository this SDD catalogues.
+  const repoCsv = join(clone, "catalogues", "repositories.csv");
+  if (existsSync(repoCsv)) {
+    const id = readFileSync(repoCsv, "utf8").split("\n")[1]?.split(",")[0];
+    if (id && existsSync(join(clone, "orchestration/templates/briefing/code-repo/agent-instructions.md.hbs"))) {
+      const code = join(dirname(clone), id);
+      for (const c of [code, twinOf(code)]) {
+        mkdirSync(c, { recursive: true });
+        execFileSync("git", ["-C", c, "init", "-q"]);
+      }
+      twice(`context pull @${name}`, code, ["context", "pull", "--sdd", clone], () => new Set());
+    } else process.stdout.write(`  skip context pull: ${id ? "the SDD's baseline has no code-repo templates yet" : "no repositories catalogued"}\n`);
+  }
+}
+
+const SURFACE = ["sync", "generate-briefing", "catalogue build", "catalogue graph", "catalogue aggregate", "context pull", "catalogue diff", "pack build", "render screen"];
+const missing = SURFACE.filter((v) => !exercised.has(v));
+process.stdout.write(`COVERAGE exercised: ${[...exercised].join(", ")}\n`);
+if (missing.length) process.stdout.write(`COVERAGE NOT exercised here (needs inputs this run lacks): ${missing.join(", ")}\n`);
+process.stdout.write(FAIL === 0 ? "ACCEPTANCE PASS — every maintain write in scope and deterministic\n" : `ACCEPTANCE FAIL (${FAIL})\n`);
+process.exit(FAIL === 0 ? 0 : 1);

package/scripts/maintain-version.json

@@ -0,0 +1,4 @@
+{
+  "version": "0.1.0",
+  "built_against_sdd_cli": "1.42.0"
+}

package/scripts/release-gate.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// Release gate for @sdd-method/sdd-cli. Run by `prepublishOnly`, so `npm publish` refuses unless the
+// version being published is traceable: the tree is clean, HEAD is on origin/main, and the tag
+// v<version> is on origin and points at HEAD. A publish whose commit was never pushed, or never tagged,
+// cannot be traced back to its source afterwards; this makes both impossible rather than remembered.
+//
+//   node scripts/release-gate.mjs           the pre-publish gate (exit 1 on any failure)
+//   node scripts/release-gate.mjs --audit   every version on npm has its tag on origin
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf-8"));
+const run = (cmd, args) => execFileSync(cmd, args, { cwd: root, encoding: "utf-8" }).trim();
+
+// The commit a tag names on origin (an annotated tag's peeled target wins), or "" when absent.
+function remoteTags() {
+  const out = new Map();
+  for (const line of run("git", ["ls-remote", "--tags", "origin"]).split("\n")) {
+    const m = /^([0-9a-f]+)\s+refs\/tags\/(.+?)(\^\{\})?$/.exec(line);
+    if (m && (m[3] || !out.has(m[2]))) out.set(m[2], m[1]);
+  }
+  return out;
+}
+
+const fail = (msg) => {
+  console.error(`[FAIL] release-gate: ${msg}`);
+  process.exit(1);
+};
+
+if (process.argv.includes("--audit")) {
+  const published = JSON.parse(run("npm", ["view", pkg.name, "versions", "--json"]));
+  const tags = remoteTags();
+  const missing = published.filter((v) => !tags.has(`v${v}`));
+  if (missing.length) fail(`${missing.length} of ${published.length} published versions have no tag on origin: ${missing.map((v) => `v${v}`).join(" ")}`);
+  console.log(`[PASS] release-gate --audit: all ${published.length} published versions are tagged on origin`);
+  process.exit(0);
+}
+
+// M-ADR 0218 §4.6: the persona packages are released WITH sdd-cli, in one change-set. A release that
+// bumps sdd-cli without re-stamping a persona's version file would build a package that claims an
+// engine it is not, so the publish refuses (the build refuses it too).
+for (const persona of ["verify", "maintain"]) {
+  const f = JSON.parse(readFileSync(join(root, "scripts", `${persona}-version.json`), "utf-8"));
+  if (f.built_against_sdd_cli !== pkg.version)
+    fail(`scripts/${persona}-version.json says built_against_sdd_cli ${f.built_against_sdd_cli}, but this release is ${pkg.version}; bump the persona's version and re-stamp it in the release commit`);
+}
+
+const tag = `v${pkg.version}`;
+if (run("git", ["status", "--porcelain", "--untracked-files=no"]) !== "") fail("the working tree has uncommitted changes to tracked files");
+const head = run("git", ["rev-parse", "HEAD"]);
+run("git", ["fetch", "-q", "origin", "main"]);
+const main = run("git", ["rev-parse", "origin/main"]);
+if (head !== main) fail(`HEAD ${head.slice(0, 7)} is not origin/main ${main.slice(0, 7)} — push main, and publish from the release commit`);
+const at = remoteTags().get(tag);
+if (!at) fail(`${tag} is not on origin — git tag ${tag} && git push origin ${tag}`);
+if (at !== head) fail(`${tag} on origin names ${at.slice(0, 7)}, not HEAD ${head.slice(0, 7)}`);
+console.log(`[PASS] release-gate: ${tag} at ${head.slice(0, 7)}, pushed and tagged on origin`);

package/scripts/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.4.0",
-  "built_against_sdd_cli": "1.40.0"
+  "version": "1.1.0",
+  "built_against_sdd_cli": "1.42.0"
 }