shapeup-sdlc 1.7.0 → 3.0.1

package/bin/init.mjs

@@ -20,12 +20,13 @@
 //   AGENTS.md harness block · Claude Code plugin (CLI or settings.json merge) ·
 //   CLAUDE.md @AGENTS.md import · .gitignore rules · shapeup/metrics/ · Tier C templates
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, cpSync, appendFileSync } from "node:fs";
+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;
@@ -42,15 +43,24 @@ Options:
   -d, --directory <path>   Target project directory (default: current directory)
   -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;
+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 === "--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);
@@ -109,6 +119,7 @@ if (!existsSync(agentsSrc)) {
 
 // ---- 1. Claude Code install -------------------------------------------------
 installClaude();
+warnIfUntrusted(target);
 
 // ---- 2. wire Claude Code to the root AGENTS.md ------------------------------
 ensureAgentImport(join(target, "CLAUDE.md"), "CLAUDE.md");
@@ -148,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})`);
+    }
   }
 }
 
@@ -179,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
@@ -193,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");
@@ -223,55 +248,60 @@ 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 (observed, not theorized).
+ * Pre-approve the harness's OWN kernel, and nothing else.
  *
- * 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.
+ * 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.
  *
- * That is not hypothetical. Without the grant, the run receipt step (`init-run.mjs`) gets
- * 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 comes back "This command requires approval".
- * The agent then gives up on the harness and builds the feature by hand. It is the failure the
- * receipt was designed to make visible, arriving through the door the receipt itself opened.
+ * 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.
  *
- * 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.
+ * @param {object} settings - Parsed settings.json, mutated in place.
+ * @returns {void}
+ */
+function mergePipelinePermissions(settings) {
+  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.");
+  }
+}
+
+/**
+ * Say so when the grant we just wrote will be ignored anyway.
  *
- * 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.
+ * 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.
  *
- * The structural suite asserts that every documented call site is in a form
- * one of these prefixes actually matches, so the two can never drift apart again.
+ * 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 {object} settings - Parsed settings.json, mutated in place.
+ * @param {string} projectDir - The directory just installed into.
  * @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 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) {

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

@@ -19,15 +19,16 @@ This command builds **one task**. A full BUILD round — every scope, the per-sc
 T0 verification, the inner circuit breaker, then the single EVAL — is a workflow-script launch, and
 it belongs to the orchestrator:
 
-```bash
-node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/run-workflow.mjs" \
-  "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/workflows/shapeup-run.js" \
-  --args-file .shapeup/<slug>/run-args.json --run-dir .shapeup/<slug>/workflow-run
+```
+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 — `init-run.mjs`
+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/round-protocol.md` still applies, unchanged and by design.
+`skills/tech-lead/references/protocol.md` still applies, unchanged and by design.

package/commands/ship.md

@@ -8,7 +8,7 @@ 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`.
 
@@ -18,10 +18,11 @@ On a spec with committed `scopes/*.md` — the common case — `tech-lead` holds
 conversation, writes `project-profile.md`, then hands the whole pipeline to a single background
 launch and does not drive it turn by turn:
 
-```bash
-node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/run-workflow.mjs" \
-  "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/workflows/shapeup-run.js" \
-  --args-file .shapeup/<slug>/run-args.json --run-dir .shapeup/<slug>/workflow-run
+```
+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
@@ -33,23 +34,26 @@ all run inside it. Three things follow, and they are the point of the cutover ra
   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.
-- **Headless runs need `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0` in the environment.** Without it
-  `claude -p` cuts the background wait at 600 s and **exits 0**, reporting a truncated run as a
-  clean one. Set it for any `--unattended` or CI invocation.
-- **Never launch this with the `Workflow` tool.** That call needs an interactive confirmation, so it
-  is denied in every headless session, and the only grant that unblocks it is unscoped. Left to it,
-  the script executes **zero** times and the agent improvises instead — a session can reach GATE L4
-  with a valid receipt while the pipeline never started. `run-workflow.mjs` runs the same script
-  under the path-scoped grant `npx shapeup-sdlc init` already writes.
+- **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/round-protocol.md` instead — non-regression, by design.
+`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.
@@ -70,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, having built nothing.
 - `--wall-clock-budget <seconds>` → arm the deadline breaker. Off by default. Set it in any lane
   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 `hooks/gate-deadline.mjs` denies new
+  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.