shapeup-sdlc 1.6.3 → 3.0.0

package/bin/init.mjs

@@ -11,22 +11,22 @@
 //
 // The bash installers remain the stable curl-able entrypoints for existing bookmarks;
 // this is the `npx` front door. Both produce the same layout, and drift between them is
-// a bug (tests/structural keeps the shared bits honest).
+// a bug (the structural suite keeps the shared bits honest).
 //
 // Usage:
-//   npx shapeup-sdlc init [-d <dir>] [-y] [-o] [--cli claude,antigravity,codex|all]
+//   npx shapeup-sdlc init [-d <dir>] [-y] [-o]
 //
 // What it configures (identical to install-harness.sh):
 //   AGENTS.md harness block · Claude Code plugin (CLI or settings.json merge) ·
-//   Antigravity .agents/skills + subagents · Codex .codex/skills · CLAUDE.md @AGENTS.md
-//   import · .gitignore rules · shapeup/metrics/ · Tier C templates
+//   CLAUDE.md @AGENTS.md import · .gitignore rules · shapeup/metrics/ · Tier C templates
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, cpSync, readdirSync, appendFileSync } from "node:fs";
-import { resolve, join, dirname, basename } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, cpSync, appendFileSync, realpathSync } from "node:fs";
+import { resolve, join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
-import { LOCAL, LEGACY, metricsDir } from "../skills/tech-lead/scripts/lib/paths.mjs";
+import { LOCAL, LEGACY, metricsDir } from "../kernel/lib/paths.mjs";
+import { mergePipelinePermissions as mergeGrant, isWorkspaceTrusted, WORKFLOW_RULE } from "./lib/grant.mjs";
 
 /** The root a project migrating off the pre-ADR-0001 layout may still be carrying. */
 const LEGACY_LOCAL = LEGACY.local;
@@ -35,31 +35,33 @@ const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const REPO = "nguyenvanphituoc/shapeup-sdlc-plugin";
 const MARKETPLACE_KEY = "nvptuoc-marketplace";
 const PLUGIN_KEY = "shapeup-sdlc-plugin@nvptuoc-marketplace";
-const ALL_CLIS = ["claude", "antigravity", "codex"];
 
 // ---- args -------------------------------------------------------------------
 const argv = process.argv.slice(2);
 const usage = `Usage: npx shapeup-sdlc init [options]
 Options:
   -d, --directory <path>   Target project directory (default: current directory)
-  --cli <list>             Comma-separated: claude,antigravity,codex or "all" (default: all)
   -o, --override           Overwrite existing files in target
   -y, --yes                Run unattended (answer yes to all prompts)
-  -h, --help               Print this help`;
+      --no-native-workflow Do not grant the unscoped "Workflow" permission (see below)
+  -h, --help               Print this help
 
-let targetDir = ".", yes = false, override = false, clis = [...ALL_CLIS];
+The grant this writes is two Bash rules for the harness kernel, plus — unless
+--no-native-workflow is given — the "Workflow" token that lets the tech-lead
+launch its run script without approving each launch. That token is UNSCOPED: it
+authorises every dynamic workflow script in the project, not only this plugin's.
+Declining it leaves the harness fully functional in an interactive session; only
+the unattended lane needs the pre-approval.`;
+
+let targetDir = ".", yes = false, override = false, nativeWorkflow = true;
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
   if (a === "-d" || a === "--directory") targetDir = argv[++i];
   else if (a === "-y" || a === "--yes") yes = true;
   else if (a === "-o" || a === "--override") override = true;
-  else if (a === "--cli") {
-    const v = argv[++i] || "";
-    clis = v === "all" ? [...ALL_CLIS] : v.split(",").map((s) => s.trim()).filter(Boolean);
-    const bad = clis.filter((c) => !ALL_CLIS.includes(c));
-    if (bad.length) { console.error(`Unknown CLI(s): ${bad.join(", ")}. Valid: ${ALL_CLIS.join(", ")}, all`); process.exit(1); }
-  } else if (a === "-h" || a === "--help") { console.log(usage); process.exit(0); }
+  else if (a === "--no-native-workflow") nativeWorkflow = false;
+  else if (a === "-h" || a === "--help") { console.log(usage); process.exit(0); }
   else if (a.startsWith("-")) { console.error(`Unknown option: ${a}\n${usage}`); process.exit(1); }
   else positional.push(a);
 }
@@ -71,7 +73,6 @@ if (positional.length && positional[0] !== "init") {
 const target = resolve(targetDir);
 if (!existsSync(target)) { console.error(`Target directory does not exist: ${target}`); process.exit(1); }
 console.log(`Installing Shape Up SDLC Harness into: ${target}`);
-console.log(`CLIs: ${clis.join(", ")}`);
 
 // ---- confirmation -----------------------------------------------------------
 if (!yes) {
@@ -116,21 +117,17 @@ if (!existsSync(agentsSrc)) {
   }
 }
 
-// ---- 1. per-CLI install -----------------------------------------------------
-for (const cli of clis) {
-  if (cli === "claude") installClaude();
-  else replaceSkills(cli);
-}
+// ---- 1. Claude Code install -------------------------------------------------
+installClaude();
+warnIfUntrusted(target);
 
-// ---- 2. wire each CLI to the root AGENTS.md ---------------------------------
-if (clis.includes("claude")) ensureAgentImport(join(target, "CLAUDE.md"), "CLAUDE.md", "claude");
-if (clis.includes("antigravity")) ensureAgentImport(join(target, ".agents", "AGENTS.md"), ".agents/AGENTS.md", "auto");
-if (clis.includes("codex")) ensureAgentImport(join(target, ".codex", "AGENTS.md"), ".codex/AGENTS.md", "auto");
+// ---- 2. wire Claude Code to the root AGENTS.md ------------------------------
+ensureAgentImport(join(target, "CLAUDE.md"), "CLAUDE.md");
 
 // ---- 3. .gitignore ----------------------------------------------------------
-// Both roots are listed, deliberately. A project may be mid-migration (0006 moves `.shapeup/`
-// to `.shapeup/`), and a run trace committed by accident during that window is exactly the mistake
-// the tier split exists to prevent. Ignoring a directory that does not exist costs nothing.
+// Both roots are listed, deliberately. A project may still be carrying the pre-ADR-0001 local root
+// alongside the current one, and a run trace committed by accident from either is exactly the
+// mistake the tier split exists to prevent. Ignoring a directory that does not exist costs nothing.
 const GITIGNORE_RULE = `# Shape Up SDLC run workspace
 ${LOCAL}/
 ${LEGACY_LOCAL}/
@@ -162,9 +159,23 @@ for (const [srcRel, note] of [
   const src = join(PKG_ROOT, srcRel);
   if (existsSync(src)) {
     const dst = join(target, srcRel);
-    mkdirSync(dirname(dst), { recursive: true });
-    cpSync(src, dst);
-    console.log(`Installed ${srcRel} (${note})`);
+    // Self-install (the target IS the plugin's own checkout — dogfooding, or a worktree loaded
+    // with --plugin-dir and initialized against itself) makes src and dst the same file. cpSync
+    // throws ERR_FS_CP_EINVAL on that rather than treating "already there" as done, which crashed
+    // the installer AFTER its one load-bearing step (the permission grant, step 2) had already
+    // succeeded — so the failure looked worse than it was, but it was still a crash. A plain
+    // string compare isn't enough: `target` can reach the same file through a symlinked temp root
+    // (macOS's `/tmp` -> `/private/tmp`, `/var/folders/...`) that `PKG_ROOT` — resolved from
+    // `import.meta.url`, which Node already canonicalizes — does not share textually. Comparing
+    // real paths is what makes the check hold under both forms.
+    const samePath = existsSync(dst) && realpathSync(src) === realpathSync(dst);
+    if (src === dst || samePath) {
+      console.log(`${srcRel} already present at the install target (self-install) — nothing to copy`);
+    } else {
+      mkdirSync(dirname(dst), { recursive: true });
+      cpSync(src, dst);
+      console.log(`Installed ${srcRel} (${note})`);
+    }
   }
 }
 
@@ -193,7 +204,7 @@ function installClaude() {
       : add;
     if (ins.status === 0) {
       // The CLI registers the marketplace and enables the plugin. It does NOT know about the
-      // pipeline permission grant, so this path has to add it — and until v1.6.1 it did not,
+      // kernel permission grant, so this path has to add it — and until v1.6.1 it did not,
       // while the comment below claimed both paths merged it. Measured on a fresh `npx
       // shapeup-sdlc init`: `permissions.allow` came out EMPTY on every machine with the claude
       // CLI installed, which is the common case and the one that prints success. That is FC-02
@@ -207,13 +218,13 @@ function installClaude() {
         try { written = JSON.parse(readFileSync(settingsFile, "utf8")); }
         catch (e) {
           console.error(`  [claude] plugin installed, but ${rel(settingsFile)} is not valid JSON (${e.message}) —`);
-          console.error("           the pipeline permission grant was NOT added. Copy it from .claude/settings.local.example.json.");
+          console.error("           the kernel permission grant was NOT added. Copy it from .claude/settings.local.example.json.");
           return;
         }
       }
       mergePipelinePermissions(written);
       writeFileSync(settingsFile, JSON.stringify(written, null, 2) + "\n");
-      console.log("  [claude] plugin installed at project scope + pipeline permissions granted — run /reload-plugins to activate in a live session");
+      console.log("  [claude] plugin installed at project scope + kernel permissions granted — run /reload-plugins to activate in a live session");
       return;
     }
     console.log("  [claude] Warning: claude CLI failed — falling back to writing settings.json directly");
@@ -237,93 +248,67 @@ function installClaude() {
   settings.enabledPlugins[PLUGIN_KEY] = true;
   mergePipelinePermissions(settings);
   writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + "\n");
-  console.log(`  [claude] merged marketplace + plugin + pipeline permissions into ${rel(settingsFile)}`);
+  console.log(`  [claude] merged marketplace + plugin + kernel permissions into ${rel(settingsFile)}`);
   console.log("  [claude] the plugin auto-enables on the next session opened in this directory");
 }
 
 /**
- * Pre-approve the harness's OWN pipeline scripts, and nothing else.
- *
- * WHY THIS EXISTS (measured, on this project's own benchmark).
- *
- * Every load-bearing step of a run is a Node script that ships with the plugin and therefore
- * lives OUTSIDE the project — `${CLAUDE_PLUGIN_ROOT}/skills/**\/scripts/*.mjs`. Under any
- * permission mode short of `bypassPermissions`, executing a script from outside the working
- * directory needs approval. In an interactive session you click once and forget it. In a headless
- * one there is nobody to click, and the run cannot take its first step.
+ * Pre-approve the harness's OWN kernel, and nothing else.
  *
- * That is not hypothetical. On `sdd-harness-bench`, the run receipt step (`init-run.mjs`) was
- * attempted six different ways in a single session — direct, via a heredoc, via two hand-written
- * wrapper scripts, via a sub-agent — and every one came back "This command requires approval".
- * The agent eventually gave up on the harness and built the feature by hand. It is the failure the
- * receipt was designed to make visible, arriving through the door the receipt itself opened.
+ * WHY THIS EXISTS. Every deterministic step of a run is a Node subcommand that ships with the
+ * plugin and therefore lives OUTSIDE the project. Under any permission mode short of
+ * `bypassPermissions`, executing a script from outside the working directory needs approval. In an
+ * interactive session you click once and forget it. In a headless one there is nobody to click,
+ * and the run cannot take its first step — measured, without a working grant, as the receipt step
+ * being attempted six different ways in one session and denied every time, after which the agent
+ * abandons the harness and builds the feature by hand.
  *
- * Scope is deliberately narrow: `node <plugin>/skills/.../scripts/*.mjs`, by prefix. This grants
- * the harness the right to run its own deterministic, dependency-free, network-free scripts. It
- * grants no general `Bash(node:*)`, which would be a much larger ask for a much smaller reason.
- *
- * BOTH SPELLINGS ARE GRANTED, and that is the point of v1.5's leg-2 fix. The skills now write
- * every invocation in the QUOTED literal form — `node "${CLAUDE_PLUGIN_ROOT}/skills/…"` — because
- * the unquoted form breaks the moment the plugin is installed under a path with a space in it
- * (`~/Library/Application Support/…`), which `lib/is-main.mjs` documents as a measured case, not a
- * hypothetical. A prefix rule is a literal string match, so the quote character would otherwise
- * put every call site back outside the grant — the exact mismatch this fix exists to remove. The
- * unquoted prefix stays for older prose and for anything a user has already typed.
- *
- * `tests/structural/14-invocation-paths.mjs` asserts that every documented call site is in a form
- * one of these prefixes actually matches, so the two can never drift apart again.
+ * The rule form and the measurements behind it live in `bin/lib/grant.mjs`. It is a separate module
+ * so the structural suite can IMPORT the generator instead of regex-parsing this file for the rule
+ * shape — the proxy that let a grant matching no command at all ship green for three releases.
  *
  * @param {object} settings - Parsed settings.json, mutated in place.
  * @returns {void}
  */
 function mergePipelinePermissions(settings) {
-  const OWNERS = ["tech-lead", "ba-pitch-analyzer", "spec-evaluator"];
-  const PREFIXES = OWNERS.flatMap((o) => [
-    `node \${CLAUDE_PLUGIN_ROOT}/skills/${o}/scripts/`,
-    `node "\${CLAUDE_PLUGIN_ROOT}/skills/${o}/scripts/`,
-  ]);
-  settings.permissions = settings.permissions || {};
-  const allow = new Set(settings.permissions.allow || []);
-  for (const p of PREFIXES) allow.add(`Bash(${p}:*)`);
-  settings.permissions.allow = [...allow];
-}
-
-function replaceSkills(cli) {
-  const src = join(PKG_ROOT, "skills");
-  const dest = join(target, cli === "antigravity" ? ".agents" : ".codex", "skills");
-  mkdirSync(dest, { recursive: true });
-  let n = 0;
-  for (const name of readdirSync(src)) {
-    const skillPath = join(src, name);
-    if (!existsSync(join(skillPath, "SKILL.md"))) continue; // skip empty stubs
-    rmSync(join(dest, name), { recursive: true, force: true });
-    cpSync(skillPath, join(dest, name), { recursive: true });
-    n++;
+  mergeGrant(settings, { nativeWorkflow });
+  if (!nativeWorkflow) {
+    console.log(`  [claude] --no-native-workflow: "${WORKFLOW_RULE}" not granted — launch the run`);
+    console.log("           script interactively and approve it, or re-run init without the flag.");
   }
-  console.log(`  [${cli}] ${n} skills replaced in ${rel(dest)}`);
+}
 
-  if (cli === "antigravity") {
-    const distSub = join(PKG_ROOT, "dist", "antigravity", "subagents");
-    if (existsSync(distSub)) {
-      const subDest = join(target, ".agents", "subagents");
-      mkdirSync(subDest, { recursive: true });
-      cpSync(distSub, subDest, { recursive: true });
-      const idx = join(PKG_ROOT, "dist", "antigravity", "subagents.json");
-      if (existsSync(idx)) cpSync(idx, join(target, ".agents", "subagents.json"));
-      console.log(`  [antigravity] subagent configs replaced in ${rel(subDest)}`);
-    }
-  }
+/**
+ * Say so when the grant we just wrote will be ignored anyway.
+ *
+ * Writing a correct rule into an untrusted workspace produces no error at install, no error at
+ * session start, and a denial at the first dispatch — the same invisible failure shape that let a
+ * grant matching no command at all ship for three releases. The one thing this project cannot
+ * afford is another enforcement point that is silent when it is not working, so this prints.
+ *
+ * It reports rather than repairs: trusting a directory authorises executing code from it, which is
+ * the user's call, not a decision for a package running under `npx`.
+ *
+ * @param {string} projectDir - The directory just installed into.
+ * @returns {void}
+ */
+function warnIfUntrusted(projectDir) {
+  const trusted = isWorkspaceTrusted(projectDir);
+  if (trusted === true || trusted === null) return;
+  console.log("");
+  console.log("  [claude] ⚠ This workspace is not trusted yet, so Claude Code will IGNORE the");
+  console.log("           permission grant just written and the harness will stop at its first");
+  console.log("           dispatch. Fix it in one of two ways:");
+  console.log("             • open Claude Code here interactively once and accept the trust prompt, or");
+  console.log(`             • set projects[${JSON.stringify(resolve(projectDir))}].hasTrustDialogAccepted`);
+  console.log("               to true in ~/.claude.json (this is what a CI image should bake in).");
 }
 
-function ensureAgentImport(file, label, mode) {
+function ensureAgentImport(file, label) {
   mkdirSync(dirname(file), { recursive: true });
   if (!existsSync(file)) writeFileSync(file, "");
-  if (mode === "claude") {
-    if (!readFileSync(file, "utf8").includes("@AGENTS.md")) {
-      appendFileSync(file, "\n@AGENTS.md\n");
-      console.log(`Appended @AGENTS.md import tag to ${label}`);
-    } else console.log(`@AGENTS.md import tag already present in ${label}`);
-  } else {
-    console.log(`${label} ready (root AGENTS.md auto-discovered)`);
-  }
+  if (!readFileSync(file, "utf8").includes("@AGENTS.md")) {
+    appendFileSync(file, "\n@AGENTS.md\n");
+    console.log(`Appended @AGENTS.md import tag to ${label}`);
+  } else console.log(`@AGENTS.md import tag already present in ${label}`);
 }

package/bin/lib/grant.mjs

@@ -0,0 +1,145 @@
+// grant — the permission rules that let the harness run its own kernel.
+//
+// WHY THIS IS ITS OWN MODULE. The installer writes these rules and the structural suite has to
+// check them. Checking them by regex-parsing `bin/init.mjs`'s source is how a grant that matched
+// no command at all once stayed green for three releases: the test re-derived what it expected
+// instead of asking the code what it emits. Exporting the generator is the fix — every caller gets
+// the same strings from the same function, or fails.
+//
+// HOW A BASH RULE ACTUALLY MATCHES (measured 2026-08-14 against Claude Code 2.1.232; every row was
+// a real session whose verdict was whether the target script's marker file landed on disk, never
+// what the model said about it). There are TWO rule syntaxes and they do not behave alike:
+//
+//   Bash(<prefix>:*)     PREFIX match. Compared literally; a `*` inside the prefix is an ordinary
+//                        asterisk. Matching is at COMPLETE ARGUMENT BOUNDARIES — the command must
+//                        equal the prefix or begin with `<prefix> `. A prefix ending mid-argument
+//                        (`…/scripts/:*`) therefore grants NOTHING.
+//   Bash(<pattern> *)    GLOB match, anchored end to end. Here `*` expands, and it crosses `/`.
+//
+// Two further facts shape what we emit:
+//   - A rule's `${CLAUDE_PLUGIN_ROOT}` is NOT expanded. Rules are read from the user's project
+//     settings, where that token has no meaning; measured DENIED against an expanded command.
+//   - A SKILL's `${CLAUDE_PLUGIN_ROOT}` IS expanded, at skill-load time, before the model reads it.
+//     So the command that reaches the matcher already carries an absolute, quoted path.
+//
+// WHAT WE EMIT — the whole grant, two lines:
+//
+//     Bash(node "*/kernel/harness.mjs" *)
+//     Bash(node "*/kernel/harness.mjs")
+//
+//   - GLOB syntax, not prefix, because the installer CANNOT know the path the rule must match.
+//     `npx shapeup-sdlc init` runs from an npm tarball; Claude Code loads the plugin from
+//     `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/`. A glob spans both, and the `*`
+//     is what makes the grant survive a plugin UPGRADE — an exact path would silently un-grant the
+//     harness on every version bump.
+//   - The QUOTED form is the one the skills emit, so an install path containing a space does not
+//     break the command. Closing the quote INSIDE the rule is what makes it match.
+//   - TWO rules, because the trailing ` *` requires at least one argument: a bare
+//     `node "<path>"` is DENIED by the ` *` form and needs the bare form as well.
+//   - The root is a bare `*`, NOT anchored on the plugin's directory name. Anchoring breaks every
+//     development and local install (a `--plugin-dir` checkout is named whatever the user cloned
+//     it to) and buys no security: anyone able to plant a script at `/tmp/x/kernel/harness.mjs`
+//     can equally plant one at `/tmp/x/shapeup-sdlc-plugin/9.9.9/kernel/harness.mjs`.
+//
+// WHY TWO LINES AND NOT FORTY. Through v1.8 the grant enumerated every pipeline script — two rules
+// each, regenerated whenever a script was added, renamed or removed, and silently wrong whenever
+// that regeneration was missed. v2.0 gives the deterministic half of the harness ONE executable
+// (`kernel/harness.mjs`, subcommands beneath it), so the grant is a constant a person can read and
+// verify by eye. Scope is unchanged in kind and narrower in fact: one dependency-free, network-free
+// script that ships with the plugin. It grants no general `Bash(node:*)`.
+//
+// THE WORKFLOW GRANT is separate and optional (see {@link workflowRule}). The `Workflow` permission
+// token is UNSCOPED — it authorises every dynamic workflow script in the project, not just this
+// plugin's — so the installer states that plainly and lets `--no-native-workflow` decline it. A
+// project that declines runs the harness interactively, approving the launch each time.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+
+/** The kernel's path inside the installed plugin — the one executable the grant has to cover. */
+export const KERNEL_ENTRY = "kernel/harness.mjs";
+
+/**
+ * The unscoped permission token that lets the tech-lead launch its Workflow script.
+ *
+ * Opt-in at install. Named here rather than spelled at each call site so the installer, the docs
+ * check and the structural suite all mean the same string.
+ */
+export const WORKFLOW_RULE = "Workflow";
+
+/**
+ * The `permissions.allow` rules for the harness kernel.
+ *
+ * Constant — deliberately not derived from the filesystem. A grant computed from a directory
+ * listing is a grant that changes silently when the listing does; with one entry point there is
+ * nothing left to enumerate.
+ *
+ * @returns {string[]} The two Bash rules, sorted.
+ */
+export function pipelineRules() {
+  const pattern = `node "*/${KERNEL_ENTRY}"`;
+  return [`Bash(${pattern} *)`, `Bash(${pattern})`].sort();
+}
+
+/**
+ * True for a rule this plugin has ever written and no longer wants in a user's settings.
+ *
+ * Two generations are purged: the v1.5–v1.8 prefix rules (which granted nothing), and the
+ * per-script glob rules v1.8 replaced them with (superseded by the single kernel entry point).
+ * Leaving either behind turns a user's settings into a museum of dead grants and hides which rules
+ * are live, so the installer purges rather than merging alongside.
+ *
+ * @param {string} rule - One entry from `permissions.allow`.
+ * @returns {boolean} Whether the installer should drop it.
+ */
+export function isSupersededRule(rule) {
+  return /^Bash\(node "?\$\{CLAUDE_PLUGIN_ROOT\}\/skills\/[a-z-]+\/scripts\/:\*\)$/.test(rule)
+    || /^Bash\(node "\*\/skills\/[a-z-]+\/scripts\/[\w.-]+\.mjs"( \*)?\)$/.test(rule);
+}
+
+/**
+ * Whether Claude Code will honour a PROJECT-scoped grant in this directory at all.
+ *
+ * A third failure layer, above the two in the banner, and the one that bites hardest in exactly the
+ * case the grant exists for. Measured 2026-08-14 (CC 2.1.232): in an untrusted workspace the CLI
+ * prints `Ignoring N permissions.allow entries from .claude/settings.json: this workspace has not
+ * been trusted.` and drops every one of them. A fresh clone in CI is untrusted by definition, so a
+ * perfectly correct rule set still grants nothing there. `-p` skips the trust *dialog*; it does not
+ * confer trust.
+ *
+ * This returns a fact, not a fix. The installer reports it; it deliberately does NOT write the
+ * trust flag, because trusting a directory is a decision about executing code from it and belongs
+ * to the person, not to a package running under `npx`.
+ *
+ * @param {string} projectDir - The project directory being installed into.
+ * @returns {(boolean|null)} True/false when `~/.claude.json` is readable, null when it is not.
+ */
+export function isWorkspaceTrusted(projectDir) {
+  const cfg = join(homedir(), ".claude.json");
+  if (!existsSync(cfg)) return null;
+  try {
+    const projects = JSON.parse(readFileSync(cfg, "utf8"))?.projects || {};
+    return projects[resolve(projectDir)]?.hasTrustDialogAccepted === true;
+  } catch { return null; }
+}
+
+/**
+ * Merge the harness grant into a parsed settings object, in place.
+ *
+ * @param {object} settings - Parsed settings.json.
+ * @param {object} [opts] - Options.
+ * @param {boolean} [opts.nativeWorkflow=true] - Also grant the unscoped `Workflow` token, which is
+ *   what lets the tech-lead launch its run script without a per-launch approval. `false` removes it
+ *   if a previous install added it, so `--no-native-workflow` is a real opt-out and not a no-op.
+ * @returns {void}
+ */
+export function mergePipelinePermissions(settings, { nativeWorkflow = true } = {}) {
+  settings.permissions = settings.permissions || {};
+  const allow = new Set(settings.permissions.allow || []);
+  for (const r of [...allow]) if (isSupersededRule(r)) allow.delete(r);
+  for (const r of pipelineRules()) allow.add(r);
+  if (nativeWorkflow) allow.add(WORKFLOW_RULE);
+  else allow.delete(WORKFLOW_RULE);
+  settings.permissions.allow = [...allow].sort();
+}

package/commands/build.md

@@ -12,3 +12,23 @@ If no task ID was given, read the board (`.shapeup/<slug>/tasks/_index.md`) and
 next `ready` task, stating which one you picked. Respect the substrate: if scope contracts
 exist, writes outside the active scope's whitelist will be denied by the sandbox hook — that is
 the harness working, not an error to route around.
+
+## Building a whole scoped feature is not this command
+
+This command builds **one task**. A full BUILD round — every scope, the per-scope attempt loop,
+T0 verification, the inner circuit breaker, then the single EVAL — is a workflow-script launch, and
+it belongs to the orchestrator:
+
+```
+Workflow({
+  scriptPath: "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/workflows/shapeup-run.js",
+  args: <the RunArgs object>
+})
+```
+
+Reach it through `/ship` (or the `tech-lead` skill), which opens the run properly — `harness init run`
+first, so the receipt exists. Do not hand-roll the round by calling this command once per task: the
+attempt loop, the T0 ratchet and the breakers are branches in that script, not steps a caller can
+be trusted to reproduce, and a session that rebuilds them by hand is the prose lane the cutover
+replaced. On a `--tiny` run or a spec with no committed `scopes/*.md`, the prose loop in
+`skills/tech-lead/references/protocol.md` still applies, unchanged and by design.

package/commands/eval.md

@@ -9,7 +9,8 @@ The single judge. Two modes, chosen by the arguments:
 - `--spec <folder> --feature <slug> --single-pass` — the once-per-round verdict on the whole
   board.
 
-Round mode is gated: a PreToolUse hook (GATE L2) will **deny** the dispatch while any task on
-the board is unfinished, naming the offenders. If that happens, the correct response is to
-route back to `/build` and finish them — do not retry the eval, do not argue with the hook, and
-do not use `--task` as a loophole to simulate a round verdict piecemeal.
+Round mode is watched: a PreToolUse hook (GATE L2) **warns** while any task on the board is
+unfinished, naming the offenders — advisory since ADR-0001, so the call proceeds, but a verdict
+taken now grades a partial board and the warning is recorded. The correct response is to route
+back to `/build` and finish them — do not shrug the warning off, and do not use `--task` as a
+loophole to simulate a round verdict piecemeal.

package/commands/scopes.md

@@ -5,10 +5,11 @@ This is step 8 (Map Scopes), which is two skills in sequence:
 
 1. Use the **ba-pitch-analyzer** skill on $ARGUMENTS — pitch → linked DDD spec tree (domain
    model → use cases → tasks) with BDD scenarios and the derived Test Surface. Pass through an
-   operation when the user names one: `analyze`, `generate-board`, `reconcile`,
-   `retrofit-surface`, or `coverage` (which writes the shared `requirements.md` registry).
-2. Then use the **scope-architect** skill to write the committed scope contracts
+   operation when the user names one: `analyze` (the default — spec tree + board), `reconcile`
+   (fold discovered-ledger items back into the board and UC invariants), `retrofit-surface`
+   (append a Test Surface to a spec written before there was one), or `coverage` (extract the
+   shared `requirements.md` registry that anchors covers-closure).
+2. Then use the **scope-architect** skill (`map-scopes`) to write the committed scope contracts
    (`scopes/*.md`) — import-graph slicing by flow, write-whitelist substrates, fixtures.
-   Operations: `map-scopes` (default), `remap`, `split-scope`.
 
 If the user asked for only one half ("just analyze", "just the contracts"), run only that half.

package/commands/shape.md

@@ -3,7 +3,7 @@ description: Shape a raw idea into a pitch (boundaries → breadboard → spike
 ---
 Use the **shapeup** skill on $ARGUMENTS.
 
-This is Phase 1 of the pipeline — it runs *before* any code and produces the `pitch.md` the
+This is Phase 1 of the pipeline — it runs *before* any code and produces the `shaping.md` and `breadboard.md` files (the pitch) that the
 Betting Table decides on. Default to the full sequence (`full`); when the user names a single
 step, pass it through as the sub-command: `shaping`, `breadboarding`, `spike`, `framing-doc`,
 `kickoff-doc`, or `breadboard-reflection`.

package/commands/ship.md

@@ -8,22 +8,59 @@ sign-off — especially the Ship gate (L4). The harness's safety depends on the
 loop; do not skip gates by default.
 
 **Before anything else, dispatch `tech-lead` and let it open the run** — its first action is
-`scripts/init-run.mjs`, which writes the run receipt. Do not summarise what the harness will do;
+`harness init run`, which writes the run receipt. Do not summarise what the harness will do;
 a session that dispatches the orchestrator and leaves no receipt is blocked at `Stop` by
 `hooks/gate-zerowork.mjs`.
 
+## How the run actually executes
+
+On a spec with committed `scopes/*.md` — the common case — `tech-lead` holds the L0 intake
+conversation, writes `project-profile.md`, then hands the whole pipeline to a single background
+launch and does not drive it turn by turn:
+
+```
+Workflow({
+  scriptPath: "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/workflows/shapeup-run.js",
+  args: <the RunArgs object>
+})
+```
+
+ORIENT → L1a → ANALYZE → WIRE → L1a.5 → MAP SCOPES → L1b → rounds of BUILD/L2/EVAL → QA → GATE H
+all run inside it. Three things follow, and they are the point of the cutover rather than trivia:
+
+- **A gate pause is a return value, not a stop.** The launch returns `{status: "paused", paused_at,
+  block}`; emit `block` **verbatim**, get the PO's decision, write it to
+  `.shapeup/<slug>/gate-answers.json`, and **relaunch the same call with the same args**. The
+  fast-forward re-derives position from disk and re-dispatches nothing already finished.
+- **A killed session loses nothing.** Resume state comes off disk, never from context, so a fresh
+  session picks the run up where it died — the property the whole launch shape exists to buy.
+- **The launch is the `Workflow` tool**, which is what gives the run resume-from-journal, worktree
+  isolation, and sub-agents that share the session's prompt cache instead of paying a cold start
+  each. `npx shapeup-sdlc init` writes the `"Workflow"` grant it needs. That grant is unscoped — it
+  authorises every dynamic workflow script in the project — so an install may decline it with
+  `--no-native-workflow`, in which case the launch asks for approval once per session and the
+  unattended lane is unavailable.
+
+`--tiny`, and any spec with no committed `scopes/*.md` yet, take the unchanged prose lane in
+`skills/tech-lead/references/protocol.md` instead — non-regression, by design.
+
 Only run headless/auto if the user explicitly asks for it in their message:
 - `--auto` → advance low-risk gates automatically, still pause at L4 (Ship sign-off).
   Implies `--gate-answers guarded` unless a set is named.
 - `--unattended` → fully headless, `max_rounds 3`. Intended for CI, not day-to-day local runs.
   Implies `--gate-answers ci` unless a set is named.
+  **In a `claude -p` invocation, set `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0` first.** Print mode
+  terminates a session's background tasks after 600 s, and the entire pipeline is one background
+  launch, so without it the run is killed roughly ten minutes in — mid-phase, with no error beyond
+  the CLI's own "background tasks still running; terminating". Resume state is on disk, so a
+  relaunch fast-forwards past whatever finished; the cost is a relaunch, not the run.
   **Typing the flag IS the confirmation — do not stop to ask for another one.** Emit the warning
   that no human will review the verdict before ship as the run's first line, then proceed straight
   into GATE L0 in the same turn.
 
   > Why this is spelled out: asking for confirmation here made `--unattended` unusable for the
-  > only job it has. In a non-interactive invocation (`claude -p …`, a CI step, a benchmark probe)
-  > there is no second turn in which to answer, so the run spent its turn requesting permission and
+  > only job it has. In a non-interactive invocation (`claude -p …`, a CI step) there is no second
+  > turn in which to answer, so the run spent its turn requesting permission and
   > exited having written nothing. A headless flag that cannot complete a headless run is a defect,
   > not a safety feature — and the warning, which is the part that carries the safety value, is
   > still printed. `--auto` remains the middle setting that pauses at L4.
@@ -37,14 +74,23 @@ Additional flags, pass through to `tech-lead` only when the user names them:
 - `--gate-answers <ci|guarded|interactive|path.json>` → the pre-recorded PO decisions this run
   crosses its gates with. Gates still emit their blocks and still record a decision; the
   decision's **source** becomes the answer set instead of a live human, and the ledger says so.
-  Generate one with `gate-answers.mjs --init --preset ci --by "<name>"`. This is what makes a
+  Generate one with `harness gate --init --preset ci --by "<name>"`. This is what makes a
   headless lane finish: without it an unattended run waits at the first ⏸ until the wall-clock
-  budget expires (measured: a benchmark DNF at 1800s on a feature the control finished in 51s).
+  budget expires, having built nothing.
 - `--wall-clock-budget <seconds>` → arm the deadline breaker. Off by default. Set it in any lane
-  with a hard clock (CI, a benchmark, an overnight run) and set it *below* the external kill, so
-  the harness trips its own breaker first: past the deadline `hooks/gate-deadline.mjs` denies new
+  with a hard clock (CI, an overnight run) and set it *below* the external kill, so
+  the harness trips its own breaker first: past the deadline `harness verify budget` denies new
   `task-executor` work and routes to GATE H, where scope-hammer ships whatever is green. A run
   killed from outside ships nothing — including the scopes that already passed T0.
+- `--parallel-scopes N` → how many scopes build at once (default 4). Concurrency is a cost
+  question before it is a speed one — every extra leg is another worker's full context — so this
+  is a dial rather than a constant. `1` builds scopes one at a time, which is the setting for a
+  project whose workers are not safe to run beside each other.
+- `--adversarial-verify` → before a FAIL finding costs a whole fix round, spend one independent
+  skeptic on it, prompted to refute and to default to "real" when it cannot. Off by default; it
+  does not touch the single-judge invariant, because a refutation retracts a finding rather than
+  issuing a verdict.
+- `--no-qa` → skip the QA Edge Hunt. QA is a level-up, not a gate.
 - `--rounds N` → override the outer circuit breaker (build+eval cycles, default 3).
 - `--attempts N` → override the inner circuit breaker (per-scope T0 attempts, default 5;
   no-op on specs without scope contracts).

package/commands/wire.md

@@ -5,7 +5,7 @@ Use the **solution-architect** skill (operation `wire`) on $ARGUMENTS.
 
 This is gate L1a.5 — it front-loads the integration seam so no engine ships orphaned. The skill
 is the sole writer of the committed `wiring-map.md`, resolved against `project-profile.md`'s
-`entry_point`; `trace-lint.mjs` later checks reachability against it.
+`entry_point`; `harness verify trace` later checks reachability against it.
 
 It needs the spec folder (for the use cases) and the project profile. If either is missing, say
 which one rather than inventing it.