@sdd-method/sdd-cli 1.41.0 → 1.43.0

package/scripts/author-acceptance.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+// Acceptance for the author CLI — M-ADR 0220 §4.3, the scope layer.
+//
+// The property: no author verb writes into the MAINTAIN-ONLY part of the derived-and-managed set —
+// the lock and the managed payload it records (0218 §4.3 items 1–2), the CI wrapper and its module
+// (item 3), the harness settings and hooks (item 5), ADR transitions (item 6, which land in
+// lock-managed ADR files), the derived model (item 7) or a pack (item 8). Tested, not asserted: each
+// SDD is cloned fresh, every author verb this run can exercise is run, and after each run every path
+// `git status --porcelain --ignored` reports is checked against that part of the set.
+//
+// Also, per verb: (b) PARITY, the full sdd-cli (--control-bin) on a twin clone leaves the same tree
+// and exit code, because scope cannot see a verb that crashes or renders differently; (c) a CRASH
+// (sdd-author: <message> on stderr) fails whatever the exit code. Fails closed on the CONTROL: a
+// write into the maintain-only part must be SEEN, or every PASS is vacuous. Verbs it cannot exercise
+// are listed under COVERAGE, never passed silently. Author verbs need not be deterministic (that is
+// maintain's property), so a verb runs once per clone.
+//
+// usage: author-acceptance.mjs --bin <author-bin.js> --control-bin <sdd-cli cli.js> <sdd-repo>...
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, 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 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(`author-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 maintain-only part of the set (M-ADR 0220 §4.3) -------------------------------------
+const MAINTAIN_ONLY = [
+  /^method-baseline\.lock$/, /^\.sdd-repo-kind$/,                     // items 1–2
+  /^\.github\/workflows\/method-validation\.yml$/, /^\.gitlab-ci\.yml$/,
+  /^\.jenkins\/method-validation\.Jenkinsfile$/, /^\.dagger\/method-validation\//, // item 3
+  /^\.claude\/settings\.json$/, /^\.github\/hooks\//,                // item 5
+  /^catalogues\//, /^catalogues-aggregated\//, /^catalogues(-aggregated)?-graph\.jsonl$/, // item 7
+  /^\.sdd\/bundle-cache\//,
+];
+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 changed(repo) {
+  const st = spawnSync("git", ["-C", repo, "status", "--porcelain", "--ignored", "--untracked-files=all"], { encoding: "utf8" });
+  return st.stdout.split("\n").filter(Boolean).map((l) => l.slice(3).split(" -> ").pop().replace(/^"|"$/g, ""));
+}
+const intoMaintainOnly = (repo, managed) => changed(repo).filter((p) => managed.has(p) || MAINTAIN_ONLY.some((rx) => rx.test(p)));
+function snapshot(repo, roots) {
+  const h = createHash("sha256");
+  for (const p of changed(repo).sort()) {
+    h.update(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 (removed on every exit; AUTHOR_ACC_KEEP=1 keeps it) ----------------------------
+const workspaces = [];
+process.on("exit", () => {
+  if (process.env.AUTHOR_ACC_KEEP) return void process.stderr.write(`author-acceptance: kept ${workspaces.join(" ")}\n`);
+  for (const ws of workspaces) rmSync(ws, { recursive: true, force: true });
+});
+function fresh(repo) {
+  const ws = mkdtempSync(join(tmpdir(), "author-acc-"));
+  workspaces.push(ws);
+  const clone = join(ws, basename(repo));
+  execFileSync("git", ["clone", "-q", "--no-hardlinks", repo, clone]);
+  return { ws, clone };
+}
+const run = (cwd, verbArgs, bin) => spawnSync("node", [bin, ...verbArgs], { cwd, encoding: "utf8" });
+
+// One verb on a fresh pair of clones: the author's run is scope-checked, the control's is its twin.
+function check(label, repo, verbArgsFor, opts = {}) {
+  const a = fresh(repo);
+  const b = fresh(repo);
+  try {
+    checkPair(label, a, b, verbArgsFor, opts);
+  } finally {
+    if (!process.env.AUTHOR_ACC_KEEP) for (const w of [a.ws, b.ws]) { rmSync(w, { recursive: true, force: true }); workspaces.splice(workspaces.indexOf(w), 1); }
+  }
+}
+function checkPair(label, a, b, verbArgsFor, { cwdFor = (c) => c, inspect = (c) => c, allowNonZero = true } = {}) {
+  const r = run(cwdFor(a.clone, a.ws), verbArgsFor(a.clone, a.ws), BIN);
+  const crashed = /^sdd-author: /m.test(r.stderr ?? "");
+  if (crashed || (r.status !== 0 && !allowNonZero)) {
+    fail(`${label}: ${crashed ? "CRASHED" : `exit ${r.status}`} — ${(r.stderr || r.stdout).trim().split("\n").pop()}`);
+    return;
+  }
+  const target = inspect(a.clone, a.ws);
+  const bad = intoMaintainOnly(target, lockManaged(a.clone));
+  if (bad.length) fail(`${label}: wrote into the maintain-only set: ${bad.slice(0, 5).join(", ")}`);
+  const rc = run(cwdFor(b.clone, b.ws), verbArgsFor(b.clone, b.ws), CONTROL);
+  const roots = [a.ws, b.ws];
+  const parity = snapshot(target, roots) === snapshot(inspect(b.clone, b.ws), roots) && rc.status === r.status;
+  if (!parity) fail(`${label}: PARITY — sdd-cli left a different tree or exited ${rc.status} where sdd-author exited ${r.status}`);
+  if (!bad.length && parity) ok(`${label} (exit ${r.status}; wrote ${changed(target).length} path(s)): none in the maintain-only set, = sdd-cli`);
+  exercised.add(label.split(" @")[0]);
+}
+
+// ---- control: the detector must see a write into the maintain-only set -----------------------
+{
+  const { clone } = fresh(REPOS[0]);
+  mkdirSync(join(clone, "catalogues"), { recursive: true });
+  writeFileSync(join(clone, "catalogues", "CONTROL.csv"), "x\n");
+  writeFileSync(join(clone, "method-baseline.lock"), readFileSync(join(clone, "method-baseline.lock"), "utf8") + "# control\n");
+  const seen = intoMaintainOnly(clone, lockManaged(clone));
+  if (seen.includes("catalogues/CONTROL.csv") && seen.includes("method-baseline.lock")) ok("CONTROL: writes into the maintain-only set are seen");
+  else fail(`CONTROL: a write into the maintain-only set was NOT seen (${seen.join(", ")}) — every scope PASS below would be vacuous`);
+}
+
+for (const repo of REPOS) {
+  const name = basename(repo);
+  process.stdout.write(`=== ${name} ===\n`);
+  const kind = existsSync(join(repo, ".sdd-repo-kind")) ? readFileSync(join(repo, ".sdd-repo-kind"), "utf8").trim() : "";
+  check(`catalogue check @${name}`, repo, () => ["catalogue", "check", "--sdd-path", "."]);
+  check(`generate-briefing @${name}`, repo, () => ["generate-briefing", "--target-dir", "."]);
+  check(`scaffold domain @${name}`, repo, () => ["scaffold", "domain", "author-acc-probe", "--target-repo", "."]);
+  check(`plan @${name}`, repo, () => ["plan", "--pilot", "--service", "acc-probe", "--capability", "acc-probe", "--domain", "acc-probe", "--workspace-root", "."]);
+  check(`contracts attest @${name}`, repo, () => ["contracts", "attest", "--target-repo", ".", "--refresh"]);
+  check(`conformance @${name}`, repo, (_c, ws) => ["conformance", "--target-repo", ".", "--emit-finding", join(ws, "findings")]);
+  check(`api-surface @${name}`, repo, (_c, ws) => ["api-surface", "--source", ".", "--out", join(ws, "surface.yaml")]);
+  const screens = join(repo, "screens");
+  if (existsSync(screens)) {
+    const spec = readdirSync(screens).find((f) => f.endsWith(".md"));
+    if (spec) check(`render screen @${name}`, repo, (_c, ws) => ["render", "screen", join("screens", spec), "--out", join(ws, "screen.svg")]);
+  }
+  // context pull: a scratch code repository beside the clone, named for a repository this SDD catalogues.
+  const repoCsv = join(repo, "catalogues", "repositories.csv");
+  if (existsSync(repoCsv) && existsSync(join(repo, "orchestration/templates/briefing/code-repo/agent-instructions.md.hbs"))) {
+    const id = readFileSync(repoCsv, "utf8").split("\n")[1]?.split(",")[0];
+    if (id) {
+      const codeOf = (ws) => {
+        const c = join(ws, id);
+        if (!existsSync(c)) { mkdirSync(c, { recursive: true }); execFileSync("git", ["-C", c, "init", "-q"]); }
+        return c;
+      };
+      // Scope is checked on the SDD clone (the code repository is not an SDD); parity on the code repository.
+      check(`context pull @${name}`, repo, (c) => ["context", "pull", "--sdd", c], { cwdFor: (_c, ws) => codeOf(ws), inspect: (c, ws) => { const bad = intoMaintainOnly(c, lockManaged(c)); if (bad.length) fail(`context pull @${name}: wrote into the SDD's maintain-only set: ${bad.join(", ")}`); return codeOf(ws); } });
+    }
+  }
+  void kind;
+}
+
+const SURFACE = ["catalogue check", "generate-briefing", "scaffold domain", "plan", "contracts attest", "conformance", "api-surface", "render screen", "context pull",
+  "snapshot fold", "snapshot land", "snapshot verify", "snapshot diff", "snapshot targets", "snapshot advance"];
+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, e.g. a snapshot store): ${missing.join(", ")}\n`);
+process.stdout.write(FAIL === 0 ? "ACCEPTANCE PASS — no author write reached the maintain-only set\n" : `ACCEPTANCE FAIL (${FAIL})\n`);
+process.exit(FAIL === 0 ? 0 : 1);

package/scripts/author-version.json

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

package/scripts/build-persona-package.mjs

@@ -0,0 +1,309 @@
+// Assemble a publishable persona package — @sdd-method/verify-cli (M-ADR 0212 §4.3b) or
+// @sdd-method/maintain-cli (M-ADR 0218) or @sdd-method/author-cli (M-ADR 0220). Usage: build-persona-package.mjs [verify|maintain|author]
+// (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 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
+// boundary pass while not holding:
+//   1. a relative import in the closure that does not resolve to a file;
+//   2. a bare import that is neither a Node built-in nor a declared dependency;
+//   3. a CANARY — a known authoring module — present in the closure;
+//   4. a canary that no longer EXISTS in dist. A canary that was renamed or
+//      deleted cannot be absent from anything, so the check above would pass
+//      vacuously; this makes it fail instead, and asks for the list to follow.
+//
+// The generated directory is gitignored and safe to delete.
+
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { builtinModules } from "node:module";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+// SDD_CLI_DIST: check a build made elsewhere. `dist/` is what a linked global `sdd-cli`
+// runs, so building it to run this check silently put unreleased code in front of every
+// 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 PERSONA = process.argv[2] ?? "verify";
+// Modules that must never reach a package. Each list names modules that EXIST, or the check below
+// fails rather than passing vacuously. ADMIN: sdd-cli's alone (M-ADR 0220 §4.2). AUTHOR_ONLY: the
+// author's own verbs, canaries for verify and maintain. MAINTAIN_WRITERS: the sync engine and the
+// model and pack writers, canaries for verify and author. The catalogue BUILDER is not one for the
+// author: `catalogue check` builds into temporary space through it (0220 §4.3 names the writers).
+const ADMIN_CANARIES = [
+  "cli.js",
+  "index.js",
+  "verbs/init.js",
+  "verbs/metamodel.js",
+  "verbs/catalogue.js",
+  "lib/catalogue/migration-map.js",
+];
+const AUTHOR_ONLY_MODULES = [
+  "verbs/conformance.js",
+  "verbs/scaffold.js",
+  "verbs/plan.js",
+  "verbs/contracts.js",
+  "verbs/api-surface.js",
+  "verbs/snapshot.js",
+  "lib/snapshot/land.js",
+];
+const MAINTAIN_WRITERS = [
+  "verbs/sync.js",
+  "verbs/catalogue-maintain.js",
+  "verbs/pack.js",
+  "verbs/pack-build.js",
+  "lib/sync/index.js",
+  "lib/catalogue/aggregate.js",
+  "lib/catalogue/graph-run.js",
+  "lib/snapshot/catalogue-diff.js",
+  "lib/pack/builder.js",
+];
+const AUTHOR_CANARIES = [...ADMIN_CANARIES, ...AUTHOR_ONLY_MODULES];
+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\` and the rest — are not present in it, ` +
+      `and are in \`@sdd-method/sdd-cli\`. Invoking one fails with exit 1.\n`,
+  },
+  author: {
+    entry: "author-bin.js",
+    out: "author-cli",
+    versionFile: "author-version.json",
+    versionEnv: "AUTHOR_VERSION",
+    name: "@sdd-method/author-cli",
+    bin: "sdd-author",
+    canaries: [...ADMIN_CANARIES, ...MAINTAIN_WRITERS],
+    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.",
+    readme:
+      `# @sdd-method/author-cli\n\n` +
+      `\`sdd-author\` is for the people and agents who own one SDD's content. It re-authors that content and **cannot move the baseline or rebuild the model** (M-ADR 0220).\n\n` +
+      `Verbs: everything in \`@sdd-method/verify-cli\`, plus \`scaffold domain\`, \`plan\`, \`contracts attest\`, \`conformance\`, \`api-surface\`, ` +
+      `the \`snapshot\` verbs, \`render screen\`, \`generate-briefing\`, \`context pull\` and \`catalogue check\`.\n\n` +
+      `\`catalogue check\` reports whether the committed catalogues are what the committed specifications build to, and writes nothing. ` +
+      `Rebuilding them (\`catalogue build\`), \`sync\` and \`pack build\` are in \`@sdd-method/maintain-cli\`; \`init\` and the administrator's verbs are in \`@sdd-method/sdd-cli\`. ` +
+      `They are not present in this package, and 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\`, \`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 | author)\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`);
+  process.exit(1);
+};
+
+if (!existsSync(ENTRY)) die(`${relative(ROOT, ENTRY)} missing — run \`npm run build\` first`);
+
+// ---- 1. closure over imports ----------------------------------------------
+// Line-based over tsc output, skipping comment lines. An earlier regex over the
+// whole text read `// from "changed" produces…` in a comment as an import of a
+// package called `changed` — prose parsed as code, the same failure a grep over
+// workflow comments made the same day. Fail-closed caught it; this stops it.
+const STATIC = /^\s*(?:import|export|\})[^\n]*?\bfrom\s*["']([^"']+)["']/;
+const SIDE = /^\s*import\s*["']([^"']+)["']/;
+const DYNAMIC = /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
+function specifiers(src) {
+  const out = [];
+  for (const line of src.split("\n")) {
+    const t = line.trimStart();
+    if (t.startsWith("//") || t.startsWith("*") || t.startsWith("/*")) continue;
+    const m = line.match(STATIC) ?? line.match(SIDE);
+    if (m) out.push(m[1]);
+    for (const d of line.matchAll(DYNAMIC)) out.push(d[1]);
+  }
+  return out;
+}
+const closure = new Set();
+const bare = new Set();
+const stack = [ENTRY];
+while (stack.length) {
+  const f = stack.pop();
+  if (closure.has(f)) continue;
+  closure.add(f);
+  for (const spec of specifiers(readFileSync(f, "utf8"))) {
+    if (spec.startsWith(".")) {
+      const target = resolve(dirname(f), spec);
+      if (!existsSync(target)) die(`${relative(DIST, f)} imports '${spec}', which does not resolve`);
+      stack.push(target);
+    } else {
+      bare.add(spec);
+    }
+  }
+}
+
+// ---- 2. dependencies = only what the closure imports -----------------------
+const main = JSON.parse(await readFile(join(ROOT, "package.json"), "utf8"));
+const pkgName = (spec) =>
+  spec.startsWith("@") ? spec.split("/").slice(0, 2).join("/") : spec.split("/")[0];
+const builtins = new Set(builtinModules);
+const deps = {};
+for (const spec of bare) {
+  if (spec.startsWith("node:") || builtins.has(spec) || builtins.has(spec.split("/")[0])) continue;
+  const name = pkgName(spec);
+  const range = main.dependencies?.[name];
+  if (!range) die(`closure imports '${spec}', which is not a declared dependency of sdd-cli`);
+  deps[name] = range;
+}
+
+// ---- 3 + 4. 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(`excluded module '${c}' is reachable from ${P.entry} — the ${PERSONA} boundary does not hold`);
+}
+
+// ---- bundled shell scripts -------------------------------------------------
+// Some validators are shell scripts SHIPPED WITH the package (dispatch.ts:
+// `kind: "bundled"`), resolved by lib/scripts.ts to <package-root>/scripts/.
+// They are launched by path, not imported, so the closure above cannot see
+// them. verify-cli 0.1.0 shipped without them and `app-docs` and
+// `integration-docs` failed with exit 127 on every app and integration repo —
+// found by a parity check against sdd-cli, not by the no-write acceptance,
+// because a validator that cannot find its script writes nothing.
+const bundled = new Set();
+for (const f of closure) {
+  for (const m of readFileSync(f, "utf8").matchAll(/kind:\s*"bundled",\s*script:\s*"([^"]+)"/g)) {
+    const p = join(ROOT, "scripts", m[1]);
+    if (!existsSync(p)) die(`${relative(DIST, f)} declares bundled script '${m[1]}', which does not exist in scripts/`);
+    bundled.add(p);
+  }
+}
+
+// ---- 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 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/<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", P.versionFile), "utf8"));
+const version = versionFile.version;
+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 and catalogue stamps. 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
+// ENOENT uv_cwd. That happened, twice, between a rebuild and a publish.
+await mkdir(OUT, { recursive: true });
+for (const entry of readdirSync(OUT)) await rm(join(OUT, entry), { recursive: true, force: true });
+for (const f of [...closure, ...assets]) {
+  const dest = join(OUT, "dist", relative(DIST, f));
+  await mkdir(dirname(dest), { recursive: true });
+  await cp(f, dest);
+}
+for (const p of bundled) {
+  await mkdir(join(OUT, "scripts"), { recursive: true });
+  await cp(p, join(OUT, "scripts", relative(join(ROOT, "scripts"), p)));
+}
+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 — ${P.name} would publish private`);
+
+const pkg = {
+  name: P.name,
+  version,
+  sddCliVersion: main.version,
+  description: P.description,
+  license: main.license,
+  type: main.type,
+  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 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"), 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/${P.out}\n` +
+    `  modules ${closure.size} (${kb([...closure])} kB) · assets ${assets.size} · bundled scripts ${bundled.size} · deps ${Object.keys(deps).join(", ")}\n` +
+    `  canaries absent: ${P.canaries.length}/${P.canaries.length}\n`,
+);

package/scripts/copy-yaml-assets.mjs

@@ -37,6 +37,8 @@ for await (const srcFile of walk(SRC)) {
 }
 // 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.
-await copyFile(join(__dirname, "verify-version.json"), join(DEST, "verify-version.json"));
-copied++;
+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)"