shapeup-sdlc 1.6.2

package/oracles/snapshot-oracle.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// `snapshot` oracle for the evaluation contract (Stage G, step 4b of the audit).
+//
+// Deliverable: a generator or a pure refactor — something whose acceptance is "produces exactly
+// this output". The oracle runs the deliverable, captures its stdout, and diffs it against a
+// committed *golden* file. An empty diff is PASS; any difference is FAIL with the unified diff as
+// evidence. This is the natural oracle for "the refactor changed nothing observable" and for
+// code/text generators.
+//
+// Invariants (carried from the evaluator's design):
+//   • Probe behavior, not code presence — the verdict cites the diff of observed output.
+//   • Absence of evidence = FAIL — a probe that cannot run, or a missing golden, FAILs.
+//   • One verdict per criterion.
+//
+// Contract shape:
+//   { "oracle": "snapshot", "criteria": [
+//       { "id": "S1", "desc": "greets by name",
+//         "probe": { "argv": ["Ada"], "stdin": "" },
+//         "golden": "greet.Ada.golden.txt" } ] }
+//   `golden` is resolved relative to the contract file (baseDir). Trailing whitespace on each
+//   line and a single trailing newline are normalized so a benign EOL diff is not a false FAIL.
+//
+// Library use:  import { runContract } from ".../snapshot-oracle.mjs"
+// CLI use:      node snapshot-oracle.mjs <contract.json> "<command to run the deliverable>"
+//               exit 0 = all PASS, 1 = ≥1 FAIL, 2 = usage/contract error.
+
+import { spawnSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { CRASH_RE, formatReport } from "./_shared.mjs";
+import { isMain } from "../skills/tech-lead/scripts/lib/is-main.mjs";
+
+// Normalize so trailing spaces and final-newline differences never cause a spurious FAIL.
+function normalize(s) {
+  return s.replace(/\r\n/g, "\n").split("\n").map((l) => l.replace(/[ \t]+$/, "")).join("\n").replace(/\n+$/, "\n");
+}
+
+// Minimal line-level unified diff (no deps). Returns "" when identical.
+function unifiedDiff(expected, actual) {
+  const a = normalize(expected).split("\n");
+  const b = normalize(actual).split("\n");
+  if (a.join("\n") === b.join("\n")) return "";
+  const lines = ["--- golden", "+++ actual"];
+  const max = Math.max(a.length, b.length);
+  for (let i = 0; i < max; i++) {
+    if (a[i] === b[i]) { if (a[i] !== undefined) lines.push(`  ${a[i]}`); }
+    else {
+      if (a[i] !== undefined) lines.push(`- ${a[i]}`);
+      if (b[i] !== undefined) lines.push(`+ ${b[i]}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function spawnProbe(cmd, probe) {
+  const [bin, ...baseArgs] = String(cmd).split(/\s+/).filter(Boolean);
+  const res = spawnSync(bin, [...baseArgs, ...(probe.argv || [])], {
+    encoding: "utf8",
+    cwd: probe.cwd,
+    timeout: probe.timeout_ms || 10_000,
+    input: probe.stdin,
+  });
+  return {
+    code: res.status,
+    stdout: res.stdout || "",
+    combined: (res.stdout || "") + (res.stderr || ""),
+    spawnError: res.error?.message,
+  };
+}
+
+export function runContract({ cmd, criteria, baseDir = "." }) {
+  const results = [];
+  let fails = 0;
+  for (const c of criteria) {
+    let g;
+    try {
+      if (!c.golden) throw new Error("criterion has no `golden` file");
+      const goldenPath = isAbsolute(c.golden) ? c.golden : join(baseDir, c.golden);
+      if (!existsSync(goldenPath)) throw new Error(`golden file not found: ${c.golden}`);
+      const golden = readFileSync(goldenPath, "utf8");
+      const r = spawnProbe(cmd, c.probe || {});
+      if (r.spawnError) throw new Error(`could not run deliverable: ${r.spawnError}`);
+      if (CRASH_RE.test(r.combined)) {
+        g = { pass: false, evidence: `deliverable crashed (stack trace / panic in output): ${JSON.stringify(r.combined.trim().slice(0, 120))}` };
+      } else {
+        const diff = unifiedDiff(golden, r.stdout);
+        g = diff
+          ? { pass: false, evidence: `output differs from golden (exit ${r.code}):\n${diff}` }
+          : { pass: true, evidence: `identical to golden (${normalize(golden).split("\n").filter(Boolean).length} lines, exit ${r.code})` };
+      }
+    } catch (e) {
+      g = { pass: false, evidence: `probe threw: ${e.message}` }; // absence of evidence = FAIL
+    }
+    if (!g.pass) fails++;
+    results.push({ id: c.id, desc: c.desc, ...g });
+  }
+  return { fails, results };
+}
+
+export { formatReport };
+
+// --- CLI entry ---------------------------------------------------------------
+if (isMain(import.meta.url)) {
+  const contractPath = process.argv[2];
+  const cmd = process.argv[3];
+  if (!contractPath || !cmd) {
+    console.error('usage: node snapshot-oracle.mjs <contract.json> "<command to run the deliverable>"');
+    process.exit(2);
+  }
+  let contract;
+  try { contract = JSON.parse(readFileSync(contractPath, "utf8")); }
+  catch (e) { console.error(`cannot read contract ${contractPath}: ${e.message}`); process.exit(2); }
+  if (!Array.isArray(contract.criteria) || contract.criteria.length === 0) {
+    console.error(`contract ${contractPath} has no criteria[]`); process.exit(2);
+  }
+  const summary = runContract({ cmd, criteria: contract.criteria, baseDir: dirname(contractPath) });
+  console.log(formatReport(`snapshot oracle: ${contractPath}`, summary));
+  process.exit(summary.fails === 0 ? 0 : 1);
+}

package/oracles/test-oracle.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// `test` oracle for the evaluation contract (Stage G, step 4a of the audit).
+//
+// Deliverable: a library / module whose acceptance is "its own test suite is green".
+// The oracle runs the project's test command and grades the OBSERVED suite result —
+// exit code, executed-test count, and failing-test names — never the source.
+//
+// Why this oracle exists: a CLI is judged by `process`, a web app by `ui`, but a *library*
+// has no runtime surface to drive — its contract is its tests. (probing.md "TDD-1": a suite
+// that runs zero tests is NOT green, so `min_tests` defaults to 1.)
+//
+// Invariants (carried from the evaluator's design):
+//   • Probe behavior, not code presence — the verdict cites the suite's own output.
+//   • Absence of evidence = FAIL — a suite that cannot run, or runs nothing, FAILs.
+//   • One verdict per criterion.
+//
+// Contract shape:
+//   { "oracle": "test", "criteria": [
+//       { "id": "T1", "desc": "suite green",
+//         "probe": { "cmd": "node --test ./mathx.test.mjs", "cwd": "." },
+//         "expect": { "exit": "==0", "min_tests": 1, "no_failures": true } } ] }
+//
+// `cmd` resolution: criterion.probe.cmd overrides the contract/CLI default. The parser
+// understands node:test TAP (`# pass/# fail/# tests`, `ok`/`not ok`) and mocha-style
+// "N passing / M failing"; falls back to counting TAP `ok`/`not ok` lines.
+//
+// Library use:  import { runContract } from ".../test-oracle.mjs"
+// CLI use:      node test-oracle.mjs <contract.json> ["default test command"]
+//               exit 0 = all PASS, 1 = ≥1 FAIL, 2 = usage/contract error.
+
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { matchNum, toRegExp, formatReport } from "./_shared.mjs";
+import { isMain } from "../skills/tech-lead/scripts/lib/is-main.mjs";
+
+// Parse common test-runner output into { total, pass, fail, failing[] }.
+function parseSuite(out) {
+  const r = { total: null, pass: null, fail: null, failing: [] };
+
+  // node:test summary lines — TAP reporter prefixes with `#`, the default spec reporter with `ℹ`.
+  const mt = out.match(/^[#ℹ]\s*tests\s+(\d+)/m);
+  const mp = out.match(/^[#ℹ]\s*pass\s+(\d+)/m);
+  const mf = out.match(/^[#ℹ]\s*fail\s+(\d+)/m);
+  if (mt) r.total = Number(mt[1]);
+  if (mp) r.pass = Number(mp[1]);
+  if (mf) r.fail = Number(mf[1]);
+
+  // mocha / jest-ish summary
+  if (r.pass === null) { const m = out.match(/(\d+)\s+passing/); if (m) r.pass = Number(m[1]); }
+  if (r.fail === null) { const m = out.match(/(\d+)\s+failing/); if (m) r.fail = Number(m[1]); }
+
+  // failing test names from TAP `not ok N - name`
+  for (const m of out.matchAll(/^not ok\s+\d+\s+-\s+(.+)$/gm)) r.failing.push(m[1].trim());
+
+  // Fallback: count raw TAP result lines if no summary was emitted.
+  if (r.total === null) {
+    const oks = (out.match(/^ok\s+\d+/gm) || []).length;
+    const noks = (out.match(/^not ok\s+\d+/gm) || []).length;
+    if (oks + noks > 0) { r.total = oks + noks; r.pass = oks; r.fail = noks; }
+  }
+  return r;
+}
+
+function runSuite(cmd, probe) {
+  const [bin, ...baseArgs] = String(cmd).split(/\s+/).filter(Boolean);
+  const res = spawnSync(bin, [...baseArgs, ...(probe.argv || [])], {
+    encoding: "utf8",
+    cwd: probe.cwd,
+    timeout: probe.timeout_ms || 60_000,
+  });
+  const out = (res.stdout || "") + (res.stderr || "");
+  return { code: res.status, out, spawnError: res.error?.message, parsed: parseSuite(out) };
+}
+
+function grade(expect, r) {
+  const reasons = [];
+  let pass = true;
+  const p = r.parsed;
+
+  if (r.spawnError) { pass = false; reasons.push(`suite did not run: ${r.spawnError}`); }
+  if (!matchNum(expect.exit ?? "==0", r.code)) { pass = false; reasons.push(`suite exit ${r.code} ≠ expected ${expect.exit ?? "==0"}`); }
+
+  const minTests = expect.min_tests ?? 1;
+  if (p.total === null) { pass = false; reasons.push("no test results parsed (suite produced no recognizable output)"); }
+  else if (p.total < minTests) { pass = false; reasons.push(`only ${p.total} test(s) ran, need ≥${minTests}`); }
+
+  if ((expect.no_failures ?? true) && (p.fail ?? 0) > 0) {
+    pass = false; reasons.push(`${p.fail} failing: ${p.failing.join(", ") || "(names unparsed)"}`);
+  }
+  if (expect.stdout !== undefined && !toRegExp(expect.stdout).test(r.out)) {
+    pass = false; reasons.push(`output does not match ${expect.stdout}`);
+  }
+
+  const evidence =
+    `suite exit ${r.code}; tests=${p.total ?? "?"} pass=${p.pass ?? "?"} fail=${p.fail ?? "?"}` +
+    (p.failing.length ? `; failing=[${p.failing.join("; ")}]` : "") +
+    (reasons.length ? `  [${reasons.join("; ")}]` : "");
+  return { pass, evidence };
+}
+
+export function runContract({ cmd, criteria }) {
+  const results = [];
+  let fails = 0;
+  for (const c of criteria) {
+    let g;
+    try {
+      const useCmd = (c.probe && c.probe.cmd) || cmd;
+      if (!useCmd) throw new Error("no test command (criterion.probe.cmd or contract default)");
+      g = grade(c.expect || {}, runSuite(useCmd, c.probe || {}));
+    } catch (e) {
+      g = { pass: false, evidence: `probe threw: ${e.message}` }; // absence of evidence = FAIL
+    }
+    if (!g.pass) fails++;
+    results.push({ id: c.id, desc: c.desc, ...g });
+  }
+  return { fails, results };
+}
+
+export { formatReport };
+
+// --- CLI entry ---------------------------------------------------------------
+if (isMain(import.meta.url)) {
+  const contractPath = process.argv[2];
+  const defaultCmd = process.argv[3];
+  if (!contractPath) {
+    console.error('usage: node test-oracle.mjs <contract.json> ["default test command"]');
+    process.exit(2);
+  }
+  let contract;
+  try { contract = JSON.parse(readFileSync(contractPath, "utf8")); }
+  catch (e) { console.error(`cannot read contract ${contractPath}: ${e.message}`); process.exit(2); }
+  if (!Array.isArray(contract.criteria) || contract.criteria.length === 0) {
+    console.error(`contract ${contractPath} has no criteria[]`); process.exit(2);
+  }
+  const summary = runContract({ cmd: defaultCmd || contract.cmd, criteria: contract.criteria });
+  console.log(formatReport(`test oracle: ${contractPath}`, summary));
+  process.exit(summary.fails === 0 ? 0 : 1);
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "shapeup-sdlc",
+  "version": "1.6.2",
+  "description": "Shape Up for coding agents — with gates the agent can't talk its way past. Harness for Claude Code, compiled to Cursor, Antigravity and Codex.",
+  "bin": {
+    "shapeup-sdlc": "bin/init.mjs"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "!skills/**/evals/**",
+    "hooks/",
+    "commands/",
+    "oracles/",
+    ".claude-plugin/",
+    "AGENTS.md",
+    ".env.shapeup.example",
+    ".claude/settings.local.example.json",
+    "SECURITY.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nguyenvanphituoc/shapeup-sdlc-plugin.git"
+  },
+  "homepage": "https://github.com/nguyenvanphituoc/shapeup-sdlc-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/nguyenvanphituoc/shapeup-sdlc-plugin/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node tests/structural.mjs",
+    "demo": "node tools/demo/record-demo.mjs",
+    "distribute": "node tools/distribute.js"
+  },
+  "keywords": [
+    "shapeup",
+    "sdlc",
+    "cursor",
+    "antigravity",
+    "claude-code"
+  ],
+  "author": "Liberty Nguyen",
+  "license": "MIT"
+}

package/skills/advisor-protocol/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: advisor-protocol
+description: "Use this skill whenever a harness worker (task-executor, scope-architect) hits a decision it cannot make alone during Build Vertically — a design decision, a spec ambiguity, or a request to write outside its scope's substrate — and needs it adjudicated under a budget instead of guessed or asked ad hoc. Trigger on: \"escalate this decision\", \"ESCALATE\", \"adjudicate this ambiguity\", \"ask the advisor\", \"substrate expansion request\", \"resolve this design decision within budget\", \"how many escalations does this scope have left\". Also triggers when tech-lead needs to answer a worker's structured ESCALATE return during a build round."
+---
+
+# Advisor Protocol (ESCALATE grammar + budgets)
+
+The mechanism behind Shape Up's "advisor, not micromanager" posture (design spec v1.1 DD-1,
+DD-8). A worker mid-attempt hits something it genuinely cannot decide alone — not "what should
+I name this variable" (that's Principle A, resolved silently or at the worker's own gate), but
+a decision whose wrong guess is expensive: a design trade-off the spec left open, a spec
+ambiguity that changes behavior, or a file the worker needs to touch outside its scope's
+`allowed_file_substrate`. Instead of guessing or opening an unbounded chat with the PO, the
+worker emits one structured `ESCALATE` return and this skill adjudicates it.
+
+**Why this exists as its own skill, not inline PO chat.** Zero-memory handoff (design spec
+§3.6) means every attempt gets a *fresh* context — no chat history. An answer given once must
+survive every future reset for that scope. This skill is what turns a transient Q&A into a
+persisted decision: it writes the answer to the round-ledger (committed, Tier A) the moment
+it's made, and every future brief for that scope reads it back. Escalation memory lives in
+files, not in chat (DD-8).
+
+---
+
+## The ESCALATE grammar
+
+A worker never asks a free-form question mid-attempt. It returns a structured block and stops
+work on the blocked AC/file until an answer comes back:
+
+```yaml
+ESCALATE:
+  scope_id: cart-creation
+  round: 2
+  attempt: 3
+  kind: design-decision | spec-ambiguity | substrate-expansion
+  question: "Contract leaves cart-total rounding unspecified — round half-up or banker's rounding?"
+  options: ["round half-up (matches existing order-total code)", "banker's rounding (matches contract's other money fields)"]
+  default_if_silent: "round half-up"     # optional — see --unattended below
+```
+
+Three kinds, three different resolution paths (below). `default_if_silent` is optional — a
+worker proposes it when it has a reasonable, low-risk fallback; the advisor is never forced to
+accept it.
+
+---
+
+## Budget
+
+**≤3 ESCALATEs per scope per round** (design spec §3.3). Counted per `scope_id` + `round`, reset
+each new round. The budget exists so a struggling scope surfaces as *stuck* (routed to the
+hill's stuck-split rule, ≥3 rounds at the same position → forced scope-architect split order) rather than
+draining PO attention one question at a time.
+
+```
+1st–3rd ESCALATE this scope/round → adjudicate normally (below).
+4th+                              → do NOT ask again. Apply the most conservative resolution
+                                     (narrowest scope, no substrate expansion, closest precedent)
+                                     and flag it as a GATE-H hammer proposal: "scope exceeded its
+                                     escalation budget — question N unresolved, applied [X]".
+                                     The worker's attempt continues with that resolution.
+```
+
+Exceeding budget is never a hard stop — Build Vertically must keep moving; it's a signal that
+this scope needs GATE H's attention, not a excuse to freeze the round.
+
+---
+
+## Adjudication (in order — cheapest resolution wins)
+
+```
+1. Precedent check (free, no PO time):
+   Search this run's round-ledger.md "Decisions" section (this scope AND sibling scopes) and
+   shapeup/knowledge-base/*.md for an already-answered question that is the same or a
+   clear superset of this one. Found → reuse verbatim, log "resolved by precedent: [ref]",
+   do NOT count against budget (a repeat question is a zero-memory artifact, not a new decision).
+
+2. kind: substrate-expansion:
+   Never silently approved. Present the requested path(s) + why the worker says it needs them.
+   PO/TL approves → dispatch a scope-architect remap order to add the path to the scope contract's
+   `shared_substrate` (never hand-edit the contract — `ba` is its sole writer, F.5). PO/TL
+   declines → worker re-plans within its existing substrate; log the decline as a decision too
+   (prevents re-asking).
+
+3. kind: design-decision | spec-ambiguity, interactive/--auto:
+   Print the ESCALATE block verbatim + budget remaining for this scope/round. Ask (max 1):
+   pick an option / provide a different answer / defer to default_if_silent if offered.
+   Never answer on the PO's behalf — a wrong silent guess here is exactly what zero-memory
+   handoff makes expensive to unwind later.
+
+4. --unattended (no PO available):
+   default_if_silent present → apply it, log "auto-resolved (default, unattended)".
+   No default offered → apply the most conservative option (narrowest scope / least
+   irreversible) and flag it as a GATE-H hammer proposal for PO review before ship — the
+   run must not block, but an unattended guess is never allowed to hide from the PO forever.
+```
+
+---
+
+## Persistence — the decision must survive a reset
+
+The instant an ESCALATE is answered (any path above), append one row to the run's committed
+`round-ledger.md` "Decisions" section — never batch it for later, never keep it only in the
+current session (a crash before the next promotion point would lose it):
+
+```
+| Round | Scope | Kind | Question | Answer | Resolved by |
+|-------|-------|------|----------|--------|-------------|
+| 2 | cart-creation | design-decision | cart-total rounding | round half-up | PO (interactive) |
+```
+
+Every subsequent isolated brief for that scope (task-executor's zero-memory handoff, design
+spec §3.6) includes the full decisions table for its `scope_id` — this is how an answer given
+once in round 2 is still known in round 5's fresh-context attempt without replaying any chat
+history.
+
+---
+
+## Envelope contract — the domain layer
+
+Orchestrated, this skill is dispatched like every worker: a **WorkOrder** in (`--order <path>`,
+operation `adjudicate`), a **WorkResult** out. The standalone flags below map 1:1 onto the
+payload fields registered for this worker in the central domain registry
+(`skills/tech-lead/schemas/domain.schema.json`, `x-payload-by-worker`):
+
+| Payload field | Standalone flag | Meaning |
+|---|---|---|
+| `payload.ledger` | `--ledger` | The run's committed `round-ledger.md` — every answer persists here |
+| `payload.escalate` | `--escalate` | The worker's ESCALATE block to adjudicate (the `EscalateBlock` grammar above) |
+| `payload.scope_id` | `--scope` | The scope the budget is counted against |
+| `payload.round` | `--round` | The round the budget/decision is counted against |
+
+The WorkResult may carry only `files_touched`, `artifacts`, `assumptions`, `deviations`
+(`x-result-by-worker`): the adjudicated Decision itself persists to the committed round-ledger,
+never to the envelope, so it survives every zero-memory reset.
+
+---
+
+## Invocation
+
+```bash
+# Adjudicate one ESCALATE return from a worker (typical: tech-lead calls this mid-round)
+/advisor-protocol --ledger shapeup/checkout-vnpay/round-ledger.md --escalate '<ESCALATE yaml>'
+
+# Check remaining budget for a scope this round (worker or tech-lead, before emitting ESCALATE)
+/advisor-protocol --budget --scope cart-creation --round 2 --ledger shapeup/checkout-vnpay/round-ledger.md
+
+# Headless run — no PO available; apply defaults / conservative fallback, flag the rest for GATE H
+/advisor-protocol --unattended --ledger ... --escalate '<ESCALATE yaml>'
+```
+
+### Flags
+| Flag | Effect |
+|------|--------|
+| `--ledger <path>` | The run's committed `round-ledger.md` (decisions persist here) |
+| `--escalate <yaml\|path>` | The worker's ESCALATE block to adjudicate |
+| `--budget --scope <id> --round <N>` | Report remaining ESCALATE budget for a scope this round, no adjudication |
+| `--unattended` | No PO available — apply defaults/conservative fallback per rule 4 above |
+
+---
+
+## Hard Rules (never override without explicit user instruction)
+
+| Rule | Rationale |
+|------|-----------|
+| A worker never guesses a design decision or spec ambiguity silently | The whole point of ESCALATE — wrong silent guesses are the expensive failure mode zero-memory handoff amplifies |
+| Substrate-expansion is never auto-approved | PA3 (cross-scope contamination) exists precisely because agents self-justify "just this once" writes |
+| Budget is ≤3/scope/round; exceeding it never blocks the round | Signals a stuck scope to GATE L2's stuck-split rule instead of freezing Build Vertically |
+| Every answer is persisted to the committed round-ledger the instant it's given | Zero-memory handoff means the *only* place a decision survives is a file, not a session |
+| Precedent reuse never counts against budget | A repeat question is a zero-memory artifact, not a new decision — don't penalize the worker for context loss |
+| An unattended conservative resolution is always flagged for GATE H | An automated guess must stay visible to the PO before ship, never silently absorbed |
+| This skill never designs, builds, or judges | Advisor, not a fifth worker — it adjudicates, it does not decide scope or verify code |

package/skills/ba-pitch-analyzer/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: ba-pitch-analyzer
+description: "Use this skill whenever a user provides a product requirement, pitch, or feature description and wants it broken down into structured, executable development tasks. Triggers on: \"analyze this pitch\", \"break this into tasks\", \"generate tasks from requirement\", \"act as BA\", \"create spec from PRD\", \"turn this into dev tasks\", or any request to decompose a feature into DDD-structured documents and tasks; also on Shape Up, bounded context, domain model, or use cases, and on a tech-lead --order dispatch. Produces a linked pitch → domain model → use cases → tasks document tree with BDD scenarios and a derived Test Surface."
+---
+
+# BA Pitch Analyzer (spec-analyzer, pure worker v4.0)
+
+**Decompose the pitch into a spec a machine can build and a judge can grade — invent nothing.**
+
+Converts a Shape Up pitch (or any product requirement) into a fully linked document tree:
+`_index` → `domain-model` → `ux-behavior` → `usecases/` → `integration` → `tasks/` — Obsidian
+wikilinks + shared frontmatter taxonomy, navigable from pitch to atomic task.
+
+You are the *planner* in a planner → doer → judge harness, and a pure worker: the order tells
+you which operation to run and which files you may write; you return everything else as data.
+You keep **no state** — no run-state.md, no pitch-hash cache, no counters. Same order in →
+same artifacts out.
+
+---
+
+## Input contract — the WorkOrder
+
+Invoked as `--order <path>`. Fields you may rely on (absent = unknown; surface it, never guess):
+
+| Field | What it is |
+|---|---|
+| `operation` | `analyze` (pitch → full spec tree + board) · `generate-board` (regenerate the LOCAL board from the committed spec) · `reconcile` (fold discovered-ledger items into the board + UC invariants) · `retrofit-surface` (append `## Test Surface` to a pre-surface spec) · `coverage` (extract atomic requirement clauses → the SHARED `requirements.md` registry) |
+| `payload.pitch` | The pitch/PRD path (analyze) |
+| `payload.requirements` | (coverage) the REQ source to extract atomic clauses from — pitch / a customer-requirements doc / the use-case bodies. Absent → default to the pitch and record the choice in `assumptions[]` |
+| `payload.lens` | `lite` \| `standard` \| `cross-context`. Absent → judge it: LITE for ≤2-week appetite, no third-party, ≤3 user-facing actions; STANDARD for multi-team, third-party, or bigger appetite; genuinely unclear → one binary question / one `escalates[]` entry |
+| `payload.orient_dir` | The Scout's artifacts — `code-surface.md` IS your codebase map (do not re-scan), `discovered-seed.md` seeds task gen, `spike-*.md` feeds feasibility |
+| `payload.spec_folder` / `payload.feature` | Where the committed tree lives / the slug |
+| `payload.discovered_ledger` | (reconcile) the ledger whose raw `[+]`/`~` lines you fold in |
+| `payload.kb_rules_path` | Team guidelines (read if present) — steering, never spec |
+| `substrate.allowed / append_only / frozen` | Your write contract for THIS operation. The old frozen-zone prose is now data the sandbox hook enforces: respect it, and when an operation genuinely needs a file outside it, ESCALATE — never widen |
+| `interaction.pause_gates` | Caller policy. `true` (standalone default): pause at the phase checkpoints below, max 2 questions each. `false`: run straight through, surfacing questions as `assumptions[]`/`escalates[]` instead |
+
+---
+
+## Core craft — the analysis pipeline (operation: analyze)
+
+Phases, each with a checkpoint (pause only per `interaction`). Read the reference file before
+its phase; templates live in `assets/templates/`.
+
+```
+1  INGEST      pitch + orient artifacts + KB. Extract slug, appetite, in/out boundaries,
+               rabbit holes, third-party mentions. No files written yet.
+1b FEASIBILITY (third-party/API/SDK/webhook mentioned) verification questions + fallback
+               scope per API-NN → api-feasibility.md
+2  DDD         bounded contexts, aggregates (new vs extended), value objects, domain events,
+               repository interfaces → domain-model.md          [references/ddd-patterns.md]
+2b CONTRACTS   (standard lens) typed Request/Response/Error per repository; two-pass rule:
+               unresolvable at spec time → `⏳ TBD — verify in TASK-NNN-spike-…`, resolved
+               post-SPIKE with citation → contracts/            [references/contract-patterns.md]
+3  UX          per screen: state table (idle→loading→error→success), error cases with
+               message+action, ASCII flows → ux-behavior.md     [references/ux-behavior-patterns.md]
+4  USE CASES   one file per actor+action: typed Input/Output, numbered Steps, all error
+               cases with codes, ## System Flow (UI→API→UC→Repo→DB), ## Test Surface
+               (DERIVED ONLY from D1 Invariants · D2 Error Cases · D3 Contract shape ·
+               D4 No-gos — a sourceless test idea is a spec gap to raise, never a row to
+               invent) → usecases/                              [references/test-surface.md]
+5  INTEGRATION (standard lens) cross-system data flows, events, silent-failure risks
+               → integration.md                                 [references/integration-analysis.md]
+6  TASKS       atomic, ordered, executable → tasks/ (LOCAL root; the one uncommitted branch
+               of the tree — regenerable, machine-local)        [references/task-generation.md]
+7  DERIVE+LINT mechanical, not yours to grade:
+               node "${CLAUDE_PLUGIN_ROOT}/skills/ba-pitch-analyzer/scripts/board-derive.mjs" --slug <slug> --write
+                 (unlocks = depends_on inverse; Σ hours; critical path; appetite arithmetic —
+                  overflow is a fact you REPORT for the caller's HAMMER gate, never resolve)
+               node "${CLAUDE_PLUGIN_ROOT}/skills/ba-pitch-analyzer/scripts/spec-lint.mjs" --slug <slug>
+                 (structure, wikilinks, edge symmetry — fix reds, then re-run; you never
+                  self-grade with a hand-walked checklist)
+               → scope-summary.md + synthesis.md (traceability matrix, risk register,
+                 dependency graph — the JUDGMENT layers over board-derive's numbers)
+8  INDEX       _index.md (pitch digest + document map) + feedback.md template
+```
+
+**Task generation rules (the craft that makes tasks executable):**
+- One task = one verifiable change (one package, one concern); AC checkable by running commands.
+- `depends_on` explicit; `unlocks` NEVER hand-authored — board-derive recomputes it.
+- Contract-first: an implementation task touching a repository requires its contract file
+  (else generate the contract-stub task first); third-party + `⏳ TBD` → the SPIKE task
+  precedes and blocks it (`time_box_hours` hard cap, `api_ref`, `blocks[]`).
+- AC Trigger Matrix (full rules in references/task-generation.md): conditional rendering →
+  🔁 Inverse Conditions; data fetching → 📭 Empty & Null States; numeric limits → 🔢 Boundary
+  Values; FEAT + user actor or cross-layer → 🧪 BDD Scenarios; ≥1 service boundary →
+  🔗 Integration Flow; not triggered → remove the section entirely.
+- After all implementation tasks: one integration-test task (DB round-trip, auth rejection,
+  cross-service BDD).
+
+**Coverage trust = UC.** Every task carries `use_case_refs`; a task with none is an orphan
+(red). An invariant-backed regression task still anchors to its owning UC — there is no
+second path to green.
+
+---
+
+## The other four operations — same craft, different payload + whitelist
+
+| Operation | Essence | Never |
+|---|---|---|
+| `generate-board` | Re-derive the full task set fresh from the committed `usecases/` + `domain-model.md` (+ scope contracts if present — tasks respect their substrates). Numbering restarts at TASK-001. Initialize `status` from committed mechanical truth at SCOPE granularity (a scope with hill shard FINISHED → its tasks start `done`) — never join on task id; ids renumber per machine, the scope is the stable key. Then board-derive `--write` + regenerate scope-summary.md | touch the committed spec docs (frozen in your substrate) |
+| `reconcile` | Verify `ledger.feature == payload.feature` (mismatch → STOP). Map each `[+]` Keep item → its owning UC; new task continues numbering (never renumber); `~`/Cut → synthesis "Hammered Out" row, no file. A Keep item asserting a new invariant → APPEND `[INV-NN]` + TS-INV row to that UC (append-only sections in your substrate). A new actor/action with no UC → `escalates[]` (spec-ambiguity): spawning a UC mid-cycle is silent re-shaping, the PO decides. Finish with board-derive (appetite overflow → report) + spec-lint | re-run phases 1–5; edit UC Steps; resolve the appetite HAMMER yourself |
+| `retrofit-surface` | Append `## Test Surface` (derived rows only, after Error Cases) to each UC of a pre-surface spec; an all-sources-empty UC gets the explicit empty-sources line | touch anything else — append-only substrate |
+| `coverage` | Extract **atomic** customer requirement clauses from `payload.requirements` (default: the pitch) and write the SHARED `shapeup/<slug>/requirements.md` registry: one `\| REQ-id \| clause (verbatim) \| source \| status \| note \|` row per clause. Split compound sentences into one testable clause each — the audit's dropped clauses ("side-step OR lure enemies into traps", "low-res world textures") were *lost inside* a bigger sentence. **Assign REQ-ids ONCE and freeze them** (they behave like scope_id, never TASK-NNN — every `covers:` link rots otherwise): re-running, append new clauses with fresh ids, mark a removed clause `CUT (PO-approved)`, never renumber or delete. Status starts `covered` (a live requirement); only the PO sets `CUT`. The REQ source itself is frozen — the registry is a separate derived file | edit the REQ source; renumber existing REQ-ids; delete a dropped clause instead of marking it CUT; invent a requirement not in the source |
+
+---
+
+## Anti-rationalization table
+
+| Excuse | Reality |
+|---|---|
+| "This test idea is obviously worth a row" | No D1–D4 source = no row. Raise it as a spec gap; inventing rows is how the judge ends up grading fiction. |
+| "The discovered item obviously fits UC-03" | Run the actor/action match. 'Obviously' is how UCs silently widen — no match → ESCALATE. |
+| "I'll fix the UC steps while reconciling" | Steps are frozen in your substrate. A step change is re-shaping — the PO's call, not yours. |
+| "My output looks complete, score it 92" | You don't grade yourself. spec-lint reports facts; the judge judges. |
+| "The appetite overflow is small, drop a nice-to-have myself" | Overflow is a HAMMER gate for the caller. You report the fact and the candidate cuts. |
+| "Re-scanning the codebase is safer than trusting orient" | code-surface.md IS the map. Re-scanning burns tokens and forks the truth. |
+| "unlocks is quick to fill in by hand" | Hand-authored unlocks produced 10 asymmetric edges (KB-BA-001). board-derive computes it. |
+
+---
+
+## Output contract — the WorkResult
+
+Domain artifacts land inside your substrate (the committed spec tree + the LOCAL board). Then
+write `.shapeup/<slug>/results/<order-suffix>.json`:
+
+```json
+{
+  "schema_version": 1, "order_id": "<copied>", "worker": "ba-pitch-analyzer",
+  "status": "done | partial | escalated",
+  "artifacts": ["shapeup/<slug>/spec/domain-model.md", "…"],
+  "escalates": [ { "kind": "spec-ambiguity", "question": "New actor 'auditor' has no UC — add UC-07 or cut?" } ],
+  "assumptions": ["lens=standard — third-party PSP present"],
+  "deviations": [],
+  "discoveries": [ { "marker": "+", "line": "appetite overflow 12h — candidate cuts: TASK-014, TASK-017" } ]
+}
+```
+
+You do NOT write: `run-state.md` (dead — the orchestrator owns run truth), `tasks/_index.md`
+status flips for built work (ingest's job), scope contracts (scope-architect's), or any
+`discovered_rounds` counter (the orchestrator counts rounds).
+
+---
+
+## Verification checklist
+
+- [ ] Every file written matches the operation's substrate (allowed/append_only respected)
+- [ ] Every task has `use_case_refs`, explicit `depends_on`, command-verifiable AC
+- [ ] No hand-authored `unlocks`; board-derive ran `--write` after the last board change
+- [ ] spec-lint reports 0 red (or each remaining red is explained in `deviations[]`)
+- [ ] Test Surface rows all cite a D1–D4 source; gaps raised, not filled
+- [ ] Appetite overflow (if any) reported as a discovery, not self-resolved
+- [ ] The WorkResult validates against `work-result.schema.json`
+
+---
+
+## Invocation
+
+```bash
+# Orchestrated (tech-lead MAP SCOPES / round boundaries) — the canonical form
+/ba-pitch-analyzer --order .shapeup/checkout-vnpay/orders/analyze.json
+
+# Standalone — the preamble shim compiles the order (mode: standalone, pause_gates: true):
+#   node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/compile-order.mjs" --operation analyze --slug <slug> \
+#        --worker ba-pitch-analyzer --payload '{"pitch": "docs/pitch.md", "lens": "standard"}'
+/ba-pitch-analyzer docs/pitch.md                      # operation: analyze, lens judged
+/ba-pitch-analyzer --lens standard docs/pitch.md      # lens pinned
+```
+
+Standalone keeps exactly two flags: the pitch input and `--lens`. Every retired flag is now
+caller context: `--tasks-only` → a generate-board order, `--from-discovered` → a reconcile
+order, `--surface-only` → a retrofit-surface order, `--remap`/`--split` → scope-architect
+orders, `--status` → read `spec-lint.mjs`/`board-derive.mjs` output (zero LLM tokens),
+`--auto`/`--skip-gate*` → `interaction.pause_gates`, `--upgrade` → an analyze order with the
+standard lens over an existing lite tree (reconciliation pass: extend, never overwrite Steps).