@sdd-method/sdd-cli 1.42.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

@@ -1,5 +1,5 @@
 // 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]
+// @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
@@ -32,26 +32,40 @@ const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 // 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. 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 = [
+// 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/mcp.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",
-  "verbs/catalogue.js",
-  "lib/catalogue/migration-map.js",
-  "lib/mcp/server.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",
@@ -79,9 +93,28 @@ const PERSONAS = {
       `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, ` +
+      `\`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",
@@ -98,13 +131,13 @@ const PERSONAS = {
       `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, ` +
+      `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)\n`);
+  process.stderr.write(`build-persona-package: FAIL — unknown persona '${PERSONA}' (verify | maintain | author)\n`);
   process.exit(1);
 }
 const OUT = join(ROOT, "build", P.out);
@@ -224,7 +257,7 @@ const versionFile = JSON.parse(readFileSync(join(ROOT, "scripts", P.versionFile)
 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, catalogue stamps, the MCP identity. A stale built_against in the version file
+// 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`);

package/scripts/maintain-version.json

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

package/scripts/release-gate.mjs

@@ -42,7 +42,7 @@ if (process.argv.includes("--audit")) {
 // 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"]) {
+for (const persona of ["verify", "maintain", "author"]) {
   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`);

package/scripts/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "1.1.0",
-  "built_against_sdd_cli": "1.42.0"
+  "version": "1.2.0",
+  "built_against_sdd_cli": "1.43.0"
 }

package/scripts/vitest-tmpdir.mjs

@@ -0,0 +1,26 @@
+// Gives each test run its own temp directory and removes it whole when the run ends.
+//
+// Every fixture is created under os.tmpdir(), which reads TMPDIR. Setting TMPDIR here, in the
+// main process before any worker starts, sends every fixture of this run (and of the bash
+// scripts the tests spawn, which honour TMPDIR via mktemp) into one directory, whatever prefix
+// its test chose. vitest-teardown.mjs could only sweep the prefixes it listed: 3 of the 129 the
+// tests used, so the rest accumulated in /tmp (14,203 directories on 2026-10-16). A concurrent
+// run on the same machine has its own directory, so neither run can touch the other's fixtures.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import sweepLegacy from "./vitest-teardown.mjs";
+
+export default function setup() {
+  const original = process.env.TMPDIR;
+  const dir = mkdtempSync(join(tmpdir(), "sdd-cli-vitest-"));
+  process.env.TMPDIR = dir;
+  return async () => {
+    if (process.env.SDD_CLI_KEEP_TMP) process.stdout.write(`vitest-tmpdir: kept ${dir}\n`);
+    else rmSync(dir, { recursive: true, force: true });
+    // Fixtures from runs before this setup existed sit directly in /tmp; sweep them by prefix and age.
+    if (original === undefined) delete process.env.TMPDIR;
+    else process.env.TMPDIR = original;
+    await sweepLegacy();
+  };
+}