shapeup-sdlc 1.6.2

package/SECURITY.md

@@ -0,0 +1,72 @@
+# Security
+
+This plugin installs **eight hook entries (seven Node scripts + one `echo`)**, four of them in
+a `PreToolUse` position where they can deny tool calls. That is the product — and it is also
+exactly the kind of surface a careful reviewer should want spelled out before installing.
+This page is that spelling-out.
+
+## Reporting a vulnerability
+
+Use [GitHub private vulnerability reporting](https://github.com/nguyenvanphituoc/shapeup-sdlc-plugin/security/advisories/new)
+for anything exploitable — especially anything that would let a run **escape a deny** (talk
+past GATE L2, write outside a substrate, widen its own safety overrides) or exfiltrate data.
+For non-sensitive hardening ideas, an ordinary issue is fine.
+
+In scope: the hooks, the pipeline scripts (`compile-order` / `ingest-result` /
+`validate-envelope` / `t0-verify`), the installer/migration shell scripts, and any prompt-
+injection path through skill files. Please do not test against machines you don't own.
+
+## The claims, stated so they can be falsified
+
+1. **No hook or pipeline script makes a network request.** There is no `fetch`, no
+   `node:http(s)`, no `node:net`, no shelling out to `curl`/`wget` anywhere in `hooks/` or
+   `skills/*/scripts/`. Verify: `grep -rnE "fetch|node:http|node:net|curl|wget" hooks/ skills/*/scripts/`.
+2. **No hook has dependencies.** Plain `.mjs`, Node standard library only, no `node_modules`,
+   no install-time scripts. What you read is what runs.
+3. **Every hook is fail-open by design.** Unparseable input, missing state files, or an
+   unrecognized invocation shape → the hook defers and the normal permission flow proceeds. A
+   hook denies only when it can positively prove its condition (a non-green board, a matched
+   destructive command, a path outside a declared substrate, an invalid order file).
+4. **The model cannot widen its own safety envelope.** The escape hatch
+   (`.shapeup/safety-overrides.json`) is human-authored; `safety-spine` itself denies any
+   write/move/delete touching that file, a malformed overrides file is treated as absent
+   (override channel fails closed), and every exercised override is logged.
+5. **Stop hooks never block.** The two Stop-position hooks are advisory: they emit at most a
+   `systemMessage` and always exit 0.
+
+If you find any of these to be false, that is a vulnerability — report it as claim #ⁿ.
+
+## What each hook does
+
+Wired in [`hooks/hooks.json`](hooks/hooks.json); every script is short enough to read in one
+sitting, and reading them is the recommended review.
+
+| Hook | Event (matcher) | Reads | Can deny | Never does |
+|---|---|---|---|---|
+| [`safety-spine.mjs`](hooks/safety-spine.mjs) | PreToolUse (`Bash\|Read\|Write\|Edit\|MultiEdit`) | The proposed command/path; `.shapeup/safety-overrides.json` | Yes — provably destructive ops only: `rm -rf` on unrecoverable targets, `git push --force` / push to main, `git reset --hard`, `git clean -fdx`, `DROP TABLE`/`TRUNCATE`, reads of `.env`/keys/cloud credentials, and any write to its own overrides file | Never blocks an unmatched command; `--force-with-lease` stays allowed |
+| [`gate-l2.mjs`](hooks/gate-l2.mjs) | PreToolUse (`Skill`) | The round's task board (`.shapeup/<slug>/tasks/`) | Yes — the once-per-round EVAL dispatch while any task is unfinished | Never gates a single-task eval (`--task`); no board → defers |
+| [`validate-envelope.mjs`](skills/tech-lead/scripts/validate-envelope.mjs) | PreToolUse (`Skill\|Agent`) | The `--order` file named in the dispatch; the JSON schemas | Yes — a worker dispatch whose order file is missing or schema-invalid | Never gates a dispatch that carries no `--order` (standalone skill use stays free) |
+| [`sandbox-guard.mjs`](hooks/sandbox-guard.mjs) | PreToolUse (`Edit\|Write\|MultiEdit`) | The target path; the active scope contract | Yes — writes outside the active scope's substrate whitelist | No-op unless a scope is active; the active feature's own `.shapeup/<slug>/` run-trace is always writable. Appends denials to the local pathology log |
+| [`anti-rationalization.mjs`](hooks/anti-rationalization.mjs) | Stop | Board/T0 facts vs. the reply's completion claims | **No** — advisory `systemMessage` only | Never `decision:"block"`, never exit 2 |
+| [`slop-cleaner.mjs`](hooks/slop-cleaner.mjs) | Stop | The session's git diff (local `git diff`, via `spawnSync`) | **No** — advisory `systemMessage` flagging TODO / `console.log` / commented-out leftovers | Same — never blocks |
+| [`compact-snapshot.mjs`](hooks/compact-snapshot.mjs) | PreCompact | Run state | No — writes `.shapeup/<slug>/run-snapshot.json` before compaction | Touches nothing outside `.shapeup/` |
+| [`session-rehydrate.mjs`](hooks/session-rehydrate.mjs) | SessionStart (`compact\|resume`) | The saved run snapshot | No — injects the "trust the files, not the summary" hint when a run is in flight | Silent when no run is in flight |
+
+(The eighth `hooks.json` entry is a plain `echo` on SessionStart confirming the plugin loaded.)
+
+## Data handling
+
+- **Nothing leaves the machine.** Run state lives in the gitignored `.shapeup/`; telemetry
+  is a per-machine JSONL shard under `shapeup/metrics/` that travels only if you
+  commit it. There is no phone-home of any kind.
+- **The safety-spine actively blocks secret reads** (`.env`, `*.pem`, `*.key`, ssh/cloud
+  credentials) rather than merely not making them.
+- The installer (`scripts/install-harness.sh`) writes only into the target project
+  (`.claude/`, `.agents/`, `.codex/`, `shapeup/`, `.gitignore`) and tells you what it
+  is going to do first; the `curl | bash` form requires an explicit `--yes` for exactly that
+  reason.
+
+## Supported versions
+
+Pre-1.0-ecosystem project, solo-maintained: fixes land on `main` and ship in the next tag.
+Report against the latest release.

package/bin/init.mjs

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+// npx shapeup-sdlc init — cross-platform scaffolding installer (P1-1).
+//
+// A faithful Node port of scripts/install-harness.sh + lib-harness.sh, with the two
+// differences that were the point of porting it:
+//   • no bash, no jq, no python3 — Node parses JSON natively, so the settings.json merge
+//     that needed a jq→python3→give-up fallback chain is just JSON.parse. Works on Windows.
+//   • no Playwright prerequisite — the browser is a lazy dependency, checked by the eval
+//     skill at the moment a [ui] criterion is actually probed (see
+//     skills/spec-evaluator/references/probing.md), never at install time.
+//
+// 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).
+//
+// Usage:
+//   npx shapeup-sdlc init [-d <dir>] [-y] [-o] [--cli claude,antigravity,codex|all]
+//
+// 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
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, cpSync, readdirSync, appendFileSync } from "node:fs";
+import { resolve, join, dirname, basename } 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";
+
+/** The root a project migrating off the pre-ADR-0001 layout may still be carrying. */
+const LEGACY_LOCAL = LEGACY.local;
+
+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`;
+
+let targetDir = ".", yes = false, override = false, clis = [...ALL_CLIS];
+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.startsWith("-")) { console.error(`Unknown option: ${a}\n${usage}`); process.exit(1); }
+  else positional.push(a);
+}
+if (positional.length && positional[0] !== "init") {
+  console.error(`Unknown command: ${positional[0]} (only "init" is supported)\n${usage}`);
+  process.exit(1);
+}
+
+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) {
+  if (!process.stdin.isTTY) {
+    console.error("Non-interactive environment and no --yes given. Re-run with -y.");
+    process.exit(1);
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise((res) => rl.question(`Proceed with installation in ${target}? [y/N] `, res));
+  rl.close();
+  if (!/^y$/i.test(answer.trim())) { console.log("Installation cancelled."); process.exit(1); }
+}
+
+// ---- 0. AGENTS.md harness block ---------------------------------------------
+const agentsSrc = join(PKG_ROOT, "AGENTS.md");
+const agentsDst = join(target, "AGENTS.md");
+if (!existsSync(agentsSrc)) {
+  console.warn("Warning: AGENTS.md not found in package — skipping root AGENTS.md setup.");
+} else {
+  const block = readFileSync(agentsSrc, "utf8");
+  if (!existsSync(agentsDst)) {
+    writeFileSync(agentsDst, block);
+    console.log(`Created ${rel(agentsDst)} from harness template`);
+  } else {
+    const existing = readFileSync(agentsDst, "utf8");
+    if (existing.includes("<!-- HARNESS_START -->")) {
+      // Replace the old block in place (block goes at the top, mirroring the bash awk).
+      const stripped = existing
+        .split(/\r?\n/)
+        .reduce((acc, line) => {
+          if (line.includes("<!-- HARNESS_START -->")) acc.skip = true;
+          else if (line.includes("<!-- HARNESS_END -->")) acc.skip = false;
+          else if (!acc.skip) acc.out.push(line);
+          return acc;
+        }, { out: [], skip: false }).out.join("\n");
+      writeFileSync(agentsDst, block + stripped);
+      console.log(`Updated harness block in ${rel(agentsDst)}`);
+    } else {
+      appendFileSync(agentsDst, "\n" + block);
+      console.log(`Appended harness block to existing ${rel(agentsDst)}`);
+    }
+  }
+}
+
+// ---- 1. per-CLI install -----------------------------------------------------
+for (const cli of clis) {
+  if (cli === "claude") installClaude();
+  else replaceSkills(cli);
+}
+
+// ---- 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");
+
+// ---- 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.
+const GITIGNORE_RULE = `# Shape Up SDLC run workspace
+${LOCAL}/
+${LEGACY_LOCAL}/
+
+# Shape Up SDLC Tier C — per-member local config (templates *.example stay committed).
+# The env file is SHAPEUP_-namespaced (filename + keys) so it never collides with, or gets
+# confused with, this project's own .env / .env.local.
+.claude/settings.local.json
+.env.shapeup.local
+!.env.shapeup.example
+!.claude/settings.local.example.json`;
+const gitignore = join(target, ".gitignore");
+if (existsSync(gitignore)) {
+  if (!readFileSync(gitignore, "utf8").includes(`${LOCAL}/`)) {
+    appendFileSync(gitignore, "\n" + GITIGNORE_RULE + "\n");
+    console.log("Added Shape Up SDLC ignore rules to .gitignore");
+  } else console.log(`${LOCAL}/ already ignored in .gitignore`);
+} else {
+  writeFileSync(gitignore, GITIGNORE_RULE + "\n");
+  console.log("Created .gitignore and added ignore rules");
+}
+
+// ---- 4. telemetry shard dir + Tier C templates ------------------------------
+mkdirSync(metricsDir(target), { recursive: true });
+for (const [srcRel, note] of [
+  [".claude/settings.local.example.json", "copy to settings.local.json and edit"],
+  [".env.shapeup.example", "copy to .env.shapeup.local and edit"],
+]) {
+  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})`);
+  }
+}
+
+console.log("\n✅ Harness installation and scaffolding completed.");
+console.log("   Next: open a Claude Code session in this directory and run /ship \"<your idea>\".");
+console.log("   ([ui] evaluation needs a browser — `npx playwright install chromium` — but only");
+console.log("   when a run actually reaches a [ui] criterion; nothing else requires it.)");
+
+// ---- helpers ----------------------------------------------------------------
+function rel(p) { return p.startsWith(target) ? p.slice(target.length + 1) || "." : p; }
+
+function installClaude() {
+  const settingsFile = join(target, ".claude", "settings.json");
+  mkdirSync(join(target, ".claude"), { recursive: true });
+
+  // Primary path: the claude CLI registers the marketplace in the live session AND writes
+  // project-scoped settings. Single command strings + shell so Windows resolves claude.cmd;
+  // every argument is a static constant, nothing user-controlled is interpolated.
+  const sh = (cmd, opts = {}) => spawnSync(cmd, { shell: true, ...opts });
+  const have = sh("claude --version", { stdio: "ignore" });
+  if (have.status === 0) {
+    console.log("  [claude] registering marketplace + installing plugin via claude CLI…");
+    const add = sh(`claude plugin marketplace add --scope project ${REPO}`, { cwd: target, stdio: "inherit" });
+    const ins = add.status === 0
+      ? sh(`claude plugin install --scope project ${PLUGIN_KEY}`, { cwd: target, stdio: "inherit" })
+      : 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,
+      // 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
+      // exactly — an enforcement point inert on the path people actually take — and the grant it
+      // skipped is the one that exists because a headless run without it was denied approval 26
+      // times in a single session.
+      //
+      // Merged, never overwritten: re-read what the CLI just wrote and add only the allow list.
+      let written = {};
+      if (existsSync(settingsFile)) {
+        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.");
+          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");
+      return;
+    }
+    console.log("  [claude] Warning: claude CLI failed — falling back to writing settings.json directly");
+  }
+
+  // Fallback: merge settings.json natively (the whole reason this file is Node).
+  //
+  // (See mergePipelinePermissions below — it runs on both paths.)
+  let settings = {};
+  if (existsSync(settingsFile)) {
+    try { settings = JSON.parse(readFileSync(settingsFile, "utf8")); }
+    catch (e) {
+      console.error(`  [claude] ${rel(settingsFile)} is not valid JSON (${e.message}) — refusing to overwrite it.`);
+      console.error(`           Fix the file, or add manually: extraKnownMarketplaces.${MARKETPLACE_KEY} + enabledPlugins["${PLUGIN_KEY}"]`);
+      return;
+    }
+  }
+  settings.extraKnownMarketplaces = settings.extraKnownMarketplaces || {};
+  settings.extraKnownMarketplaces[MARKETPLACE_KEY] = { source: { source: "github", repo: REPO } };
+  settings.enabledPlugins = settings.enabledPlugins || {};
+  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] 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @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++;
+  }
+  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)}`);
+    }
+  }
+}
+
+function ensureAgentImport(file, label, mode) {
+  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)`);
+  }
+}

package/commands/build.md

@@ -0,0 +1,14 @@
+---
+description: Implement a task's acceptance criteria exactly (minimum code, surgical diffs)
+---
+Use the **task-executor** skill on $ARGUMENTS.
+
+Standalone build: implements one task (`TASK-NNN`) from a spec folder — assumption scan first,
+minimum code, surgical diffs, verified observable outcomes. Inside an orchestrated run the
+tech-lead dispatches this skill through the envelope port instead; this command is for picking
+up a single task directly.
+
+If no task ID was given, read the board (`.shapeup/<slug>/tasks/_index.md`) and take the
+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.

package/commands/eval.md

@@ -0,0 +1,15 @@
+---
+description: Judge the build against the committed spec (skeptical; absence of evidence = FAIL)
+---
+Use the **spec-evaluator** skill on $ARGUMENTS.
+
+The single judge. Two modes, chosen by the arguments:
+
+- `--task TASK-NNN` — grade one task against its acceptance criteria.
+- `--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.

package/commands/hammer.md

@@ -0,0 +1,12 @@
+---
+description: GATE H — must-have census, baseline comparison, cut list + ship verdict
+---
+Use the **scope-hammer** skill on $ARGUMENTS.
+
+The stop decision. Censuses the open items (QA findings, discovered-ledger rows, attempt-budget
+hammer proposals), compares the product to the **pitch's baseline — what customers live with
+today, never the ideal** — and returns a cut list plus a ship verdict for the TL/PO to confirm.
+
+Handles all three arrival paths: the normal stop (all scopes finished), an exhausted round
+budget, and an exhausted per-scope attempt budget. The verdict is a proposal — promotion of cut
+items is the human's call at the gate, not the skill's.

package/commands/orient.md

@@ -0,0 +1,11 @@
+---
+description: Builder-led recon — read the code, spike the riskiest area, surface unknowns
+---
+Use the **orient** skill on $ARGUMENTS.
+
+This is step 7 — after kick-off, before any task board exists. It reads the code, spikes the
+single riskiest area, and emits a code-surface map, spike findings, a discovered-task seed, and
+a hill signal. It writes **no production code**.
+
+If the user has not named a pitch or spec folder, ask which feature to orient on rather than
+guessing from the working tree.

package/commands/qa.md

@@ -0,0 +1,12 @@
+---
+description: Exploratory edge hunt on the running app (post-PASS; findings never block ship)
+---
+Use the **qa-edge-hunter** skill on $ARGUMENTS.
+
+Runs after the evaluator's PASS, outside the build↔eval loop. It charters edges *outside* what
+the evaluator probed and hunts them through six fixed lenses against the running app. Findings
+are filed to the discovery ledger as `~` — QA has **no verdict and no score**, and a finding
+never blocks ship.
+
+It needs a spec folder, a PASS eval report, and a running app. If there is no PASS verdict yet,
+say so and stop — QA before PASS is the evaluator's job done out of order.

package/commands/retro.md

@@ -0,0 +1,13 @@
+---
+description: File ship-gate feedback into the team-shared, per-skill knowledge base
+---
+Use the **coach** skill on $ARGUMENTS.
+
+Turns raw PO/TL feedback (usually from the L4 Ship gate) into per-skill guideline files under
+committed `shapeup/knowledge-base/<skill>.md`, which the coachable skills read back at
+the top of their next run.
+
+Two rules the skill enforces and this command must not soften: GATE COACH-1 **asks** the PO
+which skill owns each rule — it never assumes; and feedback whose root cause is the mechanism
+itself (a gate, hook, or contract defect) is categorized `harness-defect` and filed to the
+defect register as a raw idea for the Betting Table, never as worker steering.

package/commands/scopes.md

@@ -0,0 +1,14 @@
+---
+description: Decompose the pitch into a spec tree + board, then map the scope contracts
+---
+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
+   (`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

@@ -0,0 +1,12 @@
+---
+description: Shape a raw idea into a pitch (boundaries → breadboard → spike → pitch)
+---
+Use the **shapeup** skill on $ARGUMENTS.
+
+This is Phase 1 of the pipeline — it runs *before* any code and produces the `pitch.md` 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`.
+
+Do not start building from here — a pitch that has not been bet on goes to the PO, not to
+`/build`.

package/commands/ship.md

@@ -0,0 +1,53 @@
+---
+description: Run the full Shape Up harness on a pitch, with human sign-off at gates
+---
+Use the **tech-lead** skill to run the full harness on $ARGUMENTS.
+
+Default to **interactive** (`auto_level = interactive`): pause at every ⏸ gate and require PO
+sign-off — especially the Ship gate (L4). The harness's safety depends on the human being in 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;
+a session that dispatches the orchestrator and leaves no receipt is blocked at `Stop` by
+`hooks/gate-zerowork.mjs`.
+
+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.
+  **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
+  > 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.
+
+- `--tiny` → the small-change lane: orient (light) → single-task board → build → T0 → done.
+  Skips wiring, scope contracts, EVAL, and QA; only gates L0 and L4 pause. The tech-lead's L0
+  fit-check applies (≤ ~2 files, no new domain concept/dependency/flow) — if the change isn't
+  tiny, it will say so and recommend the full lane.
+
+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
+  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).
+- `--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
+  `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.
+- `--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).
+- `--orch-model / --exec-model / --eval-model / --qa-model <name>` → override GATE L0.8's
+  resolved model matrix for this run only (highest precedence over `.claude/settings.local.json`
+  / `.claude/settings.json` / skill defaults).

package/commands/wire.md

@@ -0,0 +1,11 @@
+---
+description: Write the wiring map — engine → seam → entry-point call site, per use case
+---
+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.
+
+It needs the spec folder (for the use cases) and the project profile. If either is missing, say
+which one rather than inventing it.