shapeup-sdlc 3.18.2 → 4.0.0

package/kernel/schemas/work-order.schema.json

@@ -1,7 +1,7 @@
 {
   "$id": "work-order.schema.json",
   "title": "WorkOrder",
-  "description": "The orchestrator \u2192 worker envelope (pure-skill architecture v1.0). Compiled by kernel/compile.mjs, validated by harness verify envelope before any worker dispatch. A worker depends only on this envelope \u2014 never on filesystem topology, run-state format, board schema, or another worker. Path: .shapeup/<slug>/orders/r<N>-a<M>.json (or <slug>/orders/<operation>.json for non-attempt work). Every record type and payload field is DEFINED CENTRALLY in domain.schema.json ($defs + x-payload-by-worker) \u2014 this file only shapes the envelope; it never re-defines a domain entity.",
+  "description": "The orchestrator \u2192 worker envelope (pure-skill architecture v1.0). Written by the loop, validated by harness verify envelope before any worker dispatch. A worker depends only on this envelope \u2014 never on filesystem topology, run-state format, board schema, or another worker. Path: .shapeup/<slug>/orders/r<N>-a<M>.json (or <slug>/orders/<operation>.json for non-attempt work). Every record type and payload field is DEFINED CENTRALLY in domain.schema.json ($defs + x-payload-by-worker) \u2014 this file only shapes the envelope; it never re-defines a domain entity.",
   "type": "object",
   "required": [
     "schema_version",
@@ -24,11 +24,11 @@
     },
     "kernel": {
       "type": "string",
-      "description": "OPTIONAL \u2014 the absolute path of the kernel entry point (harness.mjs) of the plugin copy that compiled this order. A worker runs every kernel command as node \"<kernel>\" \u2026: a command naming a variable instead (${CLAUDE_PLUGIN_ROOT}) is refused in a headless session before any permission rule is consulted."
+      "description": "OPTIONAL \u2014 the absolute path of the kernel entry point (harness.mjs) of the plugin copy that wrote this order. A worker runs every kernel command as node \"<kernel>\" \u2026: a command naming a variable instead (${CLAUDE_PLUGIN_ROOT}) is refused in a headless session before any permission rule is consulted."
     },
     "run_id": {
       "type": "string",
-      "description": "OPTIONAL (v1.8) \u2014 the run this dispatch belongs to, stamped by harness compile from the receipt (kernel/lib/paths.mjs). The join key the analysis plane groups on: order_id alone collides across runs of the same slug, so without this no record the pipeline writes can be attributed to a run. Absent when no readable receipt exists (a standalone dispatch in a workspace with no open run) \u2014 never invented, and never required, because an analytic field must not be able to block a build.",
+      "description": "OPTIONAL (v1.8) \u2014 the run this dispatch belongs to, stamped by the loop from the receipt (kernel/lib/paths.mjs). The join key the analysis plane groups on: order_id alone collides across runs of the same slug, so without this no record the pipeline writes can be attributed to a run. Absent when no readable receipt exists (a standalone dispatch in a workspace with no open run) \u2014 never invented, and never required, because an analytic field must not be able to block a build.",
       "pattern": "^[a-z0-9][a-z0-9-]*-[0-9]{8}T[0-9]{6}Z-[0-9a-f]{8}$"
     },
     "compiled_at": {
@@ -36,7 +36,11 @@
       "description": "OPTIONAL (v1.8) \u2014 ISO timestamp of compilation. The dispatch record's own time dimension: WorkResult carries none, and the journal's timings exist only on the workflow lane, so without this a dispatch on the prose lane is timeless."
     },
     "worker": {
-      "$ref": "domain.schema.json#/$defs/WorkerName"
+      "description": "The skill the order is addressed to — a member of the worker roster — or `building`, the loop itself, for a `plan` order: a fence-only order no sub-agent answers. `building` is deliberately not in the roster: the roster is what a dispatch can be addressed to, and nothing is ever dispatched to the loop.",
+      "anyOf": [
+        { "$ref": "domain.schema.json#/$defs/WorkerName" },
+        { "type": "string", "enum": ["building"] }
+      ]
     },
     "mode": {
       "type": "string",

package/kernel/schemas/work-result.schema.json

@@ -1,7 +1,7 @@
 {
   "$id": "work-result.schema.json",
   "title": "WorkResult",
-  "description": "The worker → orchestrator envelope (pure-skill architecture v1.0). Everything a worker used to write into shared files it now RETURNS as data; kernel/reduce/ingest.mjs performs the writes (tick AC boxes, flip board status, append execution log, propagate unblocks, append discoveries) deterministically, in one place. Path: .shapeup/<slug>/results/r<N>-a<M>.json. Every record type is DEFINED CENTRALLY in domain.schema.json — this file only shapes the envelope.",
+  "description": "The worker → orchestrator envelope (pure-skill architecture v1.0). Everything a worker used to write into shared files it now RETURNS as data; the loop performs the writes (tick AC boxes, flip board status, append execution log, propagate unblocks, append discoveries) deterministically, in one place. Path: .shapeup/<slug>/results/r<N>-a<M>.json. Every record type is DEFINED CENTRALLY in domain.schema.json — this file only shapes the envelope.",
   "type": "object",
   "required": [
     "schema_version",

package/kernel/verify/envelope.mjs

@@ -4,7 +4,7 @@
 // The lesson already in the repo: structured artifacts + deterministic tooling beat prose
 // conventions (harness verify t0 is the most reliable component in the harness). This script makes
 // the WorkOrder/WorkResult ports mechanically checkable: a malformed order never reaches a
-// worker, a malformed result never reaches ingest.
+// worker, a malformed result is sent back before the loop applies it.
 //
 // Zero dependencies, zero network — same discipline as the oracles and the GATE L2 block. Implements
 // the JSON-Schema subset the shipped schemas use (type, required, properties, items, enum,
@@ -271,7 +271,7 @@ export async function cli(rawArgv) {
         },
       });
       if (!existsSync(orderPath)) {
-        deny(`WorkOrder gate — order file not found: ${orderPath}. Compile it first (harness compile) — a worker must never be dispatched against a dangling order.`, "order-missing");
+        deny(`WorkOrder gate — order file not found: ${orderPath}. Write the order first (resources/orders.md in the building skill) — a worker must never be dispatched against a dangling order.`, "order-missing");
       }
       try {
         const { valid, errors } = validateFile(orderPath, join(SCHEMAS_DIR, "work-order.schema.json"));

package/kernel/verify/skills.mjs

@@ -4,7 +4,7 @@
 // WHAT IT CATCHES. A dispatch against a plugin that is absent, disabled or a different version
 // returns `<tool_use_error>Unknown skill</tool_use_error>`, and the sub-agent then does the craft
 // itself from the prose already in its own prompt. `hooks/dispatch-receipt.mjs` makes that visible
-// at ingest; this makes it visible at `init run`, before a single sub-agent has been paid for.
+// in the receipts; this makes it visible at `init run`, before a single sub-agent has been paid for.
 //
 // WHAT IT HONESTLY CANNOT DO, stated here because a check that overclaims is worse than no check.
 // It proves *these files exist at this root at this version*. It cannot prove the SESSION will
@@ -15,9 +15,9 @@
 //
 // THE ROSTER IS DERIVED, NEVER SPELLED. It comes from `domain.schema.json#/$defs/WorkerName` — the
 // same enum that decides which workers a WorkOrder may be addressed to. A hand-written list beside
-// a schema enum is the drift this project exists to prevent: eight names beside a ten-member enum
-// reads perfectly and is wrong, and the two it would omit (`translator`, `coach`) are exactly the
-// ones a short run never reaches, so the omission would surface months later on the one run that did.
+// a schema enum is the drift this project exists to prevent: a list that drops one member of the enum
+// reads perfectly and is wrong, and the member it omits is exactly the one a short run never reaches,
+// so the omission would surface months later on the one run that did.
 //
 // THE ROOT IS DERIVED FROM THIS MODULE'S OWN LOCATION, not from `CLAUDE_PLUGIN_ROOT`: the env var is
 // not reliably exported into a sub-agent's shell, and the kernel that is executing is already inside
@@ -54,11 +54,26 @@ export function roster(root = PLUGIN_ROOT) {
   return names;
 }
 
+/**
+ * The skills an agent definition preloads, read from its `skills:` frontmatter list.
+ *
+ * @param {string} path - The `agents/<worker>.md` file.
+ * @returns {string[]} The listed skill names; [] when the file or the list is absent.
+ */
+export function preloadedSkills(path) {
+  let text;
+  try { text = readFileSync(path, "utf8"); } catch { return []; }
+  const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1] ?? "";
+  const block = /^skills:[ \t]*\r?\n((?:[ \t]+-[ \t]*\S+[ \t]*\r?\n?)+)/m.exec(fm + "\n")?.[1] ?? "";
+  return [...block.matchAll(/-[ \t]*(\S+)/g)].map((m) => m[1]);
+}
+
 /**
  * Resolve every worker in the roster against a plugin root.
  *
- * A worker is present when its `SKILL.md` is readable. That is the file the host loads to answer a
- * `Skill(...)` call, so its absence is the closest on-disk fact to "this dispatch will fail".
+ * A worker is present when its `SKILL.md` is readable AND its agent definition (`agents/<worker>.md`)
+ * is readable and preloads that skill. The agent is what a dispatch names, the skill is its craft, and
+ * either one missing is the closest on-disk fact to "this dispatch will fail".
  *
  * @param {string} [root=PLUGIN_ROOT] - Plugin root to check.
  * @returns {{root:string, version:(string|null), name:(string|null), workers:Array<{worker:string,
@@ -74,7 +89,9 @@ export function resolveWorkers(root = PLUGIN_ROOT) {
   } catch { /* an unreadable manifest is reported as null, never as a failure of its own */ }
   const workers = roster(root).map((worker) => {
     const path = join(root, "skills", worker, "SKILL.md");
-    return { worker, path, present: existsSync(path) };
+    const agent = join(root, "agents", `${worker}.md`);
+    const preloads = preloadedSkills(agent).includes(worker);
+    return { worker, path, agent, present: existsSync(path) && preloads, skill: existsSync(path), agent_preloads_skill: preloads };
   });
   return { root, version, name, workers, missing: workers.filter((w) => !w.present).map((w) => w.worker) };
 }
@@ -116,7 +133,9 @@ export function cli(rawArgv) {
   }
   if (report.missing.length) {
     console.error(`  ✗ verify skills: ${report.missing.length} worker skill(s) missing under ${report.root}:`);
-    for (const w of report.workers.filter((x) => !x.present)) console.error(`      ${w.worker} — no SKILL.md at ${w.path}`);
+    for (const w of report.workers.filter((x) => !x.present)) {
+      console.error(`      ${w.worker} — ${w.skill ? `${w.agent} does not preload the \`${w.worker}\` skill` : `no SKILL.md at ${w.path}`}`);
+    }
     console.error(`    This plugin copy cannot run the pipeline. Load the working copy with`);
     console.error(`    \`claude --plugin-dir <repo>\`, or install/enable the plugin, then retry.`);
     process.exit(1);

package/kernel/verify/t0.mjs

@@ -574,7 +574,7 @@ export const ARGV_SPEC = {
 export async function cli(rawArgv) {
   const args = runArgs(ARGV_SPEC, rawArgv);
   const contractPath = args._[0];
-  // Markdown first, legacy JSON second (ADR-0001, lib/contract.mjs).
+  // Markdown first, legacy JSON second (lib/contract.mjs).
   const found = readContract(contractPath, SCOPE_CONTRACT);
   if (!found) { console.error(`t0-verify: no scope contract at ${contractPath} (.md or .json)`); process.exit(2); }
   const contract = found.contract;
@@ -583,7 +583,7 @@ export async function cli(rawArgv) {
   // contract's own location.
   //
   // This used to be `dirname(dirname(contractPath))` — "the parent of scopes/" — which was correct
-  // while scope contracts and the run trace shared a root. ADR-0001 split the tiers and moved scope
+  // while scope contracts and the run trace shared a root. The tier split moved scope
   // contracts to COMMITTED `shapeup/<slug>/scopes/`, so the default silently followed them: every
   // T0 verdict and trial row was written to `shapeup/<slug>/t0/` while `probe t0` — the ONLY reader,
   // and the one the build round's confirm stage asks — resolves `verdictsDir()` to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shapeup-sdlc",
-  "version": "3.18.2",
+  "version": "4.0.0",
   "description": "Shape Up for coding agents \u2014 with gates the agent can't talk its way past. Harness for Claude Code.",
   "bin": {
     "shapeup-sdlc": "bin/init.mjs"
@@ -11,6 +11,7 @@
     ".env.shapeup.example",
     "AGENTS.md",
     "SECURITY.md",
+    "agents/",
     "bin/",
     "commands/",
     "hooks/",
@@ -35,7 +36,8 @@
   "scripts": {
     "test": "node tests/structural.mjs",
     "demo": "node tools/demo/record-demo.mjs",
-    "test:grant": "node tests/grant/executing-grant.mjs"
+    "test:grant": "node tests/grant/executing-grant.mjs",
+    "verify:cross-dir": "node tools/verify-cross-dir.mjs"
   },
   "keywords": [
     "shapeup",

package/skills/building/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: building
+description: "Use this skill whenever the user wants to ship a kicked-off Shape Up pitch end to end — orient, plan, build, evaluate, hunt, cut, ship — as the tech lead who drives the run in this session and sits at every gate with the PO. Trigger on: \"ship this feature\", \"run the harness\", \"build from this pitch\", \"from pitch to ship\", \"run the full harness\", \"orchestrate the build\", \"resume the run\". Also covers its sub-commands: translate a non-English pitch to English (intake), decide when to stop with the census and cut list (the Cut-List Review gate, \"hammer this down to must-haves\"), and file ship feedback or seed the knowledge base from the project or the platform docs (the retro, \"coach this feedback\", \"scan the project for guidelines\"). DEFAULT: /ship <pitch>. Use it even when the user describes a multi-step build flow without naming the skills."
+---
+
+# Building — the loop that drives a run
+
+## ▶ RUN THIS FIRST — do not summarise this file
+
+**Your first output is a tool call, not a plan.** Narrating the pipeline reads like a clean run and
+leaves defects behind it. A run that left no receipt did not happen; loading these instructions is not
+running them.
+
+You drive the run, in this session. What stands between you and a claim of "done" is five mechanisms and
+nothing else: the **receipt** `init run` writes, the **gate resolver**, the **T0 witness** that runs a
+scope's fixtures and re-hashes what it cites, the **write fence** that refuses a worker's write outside
+its order's substrate, and the **dispatch receipts** that name which agent ran. Everything else in this
+file is your own discipline, and no script checks it for you — so after every action, read the files
+again instead of remembering them.
+
+Every kernel command below is run exactly as written, on ONE line (a grant matches a single-line
+command; a `\`-continued one comes back "requires approval"). If a kernel command comes back "requires
+approval", stop and say so — the scripts need a one-time grant (`npx shapeup-sdlc init`); never route
+around it or hand-build the feature.
+
+## Rules
+
+1. **ASK, DON'T ASSUME.** Collect the intake explicitly (`resources/intake.md`); put every gate to the PO with a recommendation first.
+2. **SIMPLEST FIRST.** The smallest change that satisfies the pitch.
+3. **NON-REGRESSION.** Never touch what already works.
+4. **A CLAIM NAMES ITS FILE.** Every "done", "green" or "shipped" you write cites the file or kernel output it came from.
+
+## Step 0 — open the run
+
+Resolve the intake and open it as `resources/intake.md` says: language check (a non-English pitch is made
+English by you, right there: `<name>.en.md` and the glossary, and the run opens on the copy), the L0 collect-list,
+`init run` — with every switch the operator typed, because it writes the launch record in the same act
+as the receipt and refuses a model below the floor (exit 3 = a run is already open, or the worker roster is
+missing: the record is kept and the loop continues from the files), the shared `project-profile.md`, and the
+L0 gate.
+
+## Where the facts are
+
+`K` is `node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs"`. `<run>` is `.shapeup/<slug>/`, `<spec>` is `shapeup/<slug>/`.
+
+| Fact | File |
+|---|---|
+| the launch record: models, `budgets.maxRounds`, `budgets.attemptBudget`, the answer set (`answers`), `noEval`, `noQa`, `maxParallelScopes` | `<run>/run-args.json` |
+| the intake, and which plugin copy opened the run | `<run>/intake.md`, `<run>/receipt.json` |
+| a gate is crossed when a row with that `gate` and `"status":"ok"` exists (matching `round` where it has one) | `<run>/gates.jsonl` |
+| orders and results — a dispatch is answered when `results/<stem>.json` exists | `<run>/orders/<stem>.json`, `<run>/results/<stem>.json` |
+| the scorer's verdict per attempt; the latest row per scope is its state | `<run>/t0/trials.jsonl`, `<run>/t0/verdicts/r<R>-a<A>-t<T>.json` |
+| committed plan: requirements, spec tree, wiring map, scope contracts | `<spec>requirements.md`, `<spec>spec/`, `<spec>wiring-map.md`, `<spec>scopes/<id>.md` |
+| the board: one `TASK-NNN.md` per task, `status:` in its frontmatter | `<run>/tasks/` |
+| the census GATE L4 reads | `<run>/reports/hammer-census.json` |
+
+## The phases — do the first one whose condition holds, then read the files again
+
+A gate is crossed with `K gate --resolve <GATE> --slug <slug> [--round R] [--verdict V] --preset <set>` (exit 0 = crossed; 4 = ask the PO and
+re-run with `--answer <decision>`; 5 = the set aborts: close the run as aborted and stop). `<set>` is the launch record's `answers`.
+
+| # | Condition | Do |
+|---|---|---|
+| 0 | `<run>/close.json` exists | the run has ended: report its `status` and `cause`, and stop. Reopening it is the PO's decision (`init run --force`) |
+| 1 | no `results/orient.json` | **dispatch** `orient` (below) |
+| 2 | GATE L1a not crossed | `K gate --resolve L1a --slug <slug> --preset <set>` |
+| 3 | no `<spec>requirements.md` | plan substep `requirements` |
+| 4 | no spec tree or no board | plan substep `spec`; then read the board back against `resources/plan-spec.md`'s checklist |
+| 5 | no `<spec>wiring-map.md` | plan substep `wire`; then GATE L1a.5 |
+| 6 | no `<spec>scopes/*.md` | plan substep `scopes`; then GATE L1b |
+| 7 | a scope has no green latest trial for round R (R starts at 1) | **build** it (below) |
+| 8 | every scope green or out of attempts, GATE L2 not crossed for R | `K gate --resolve L2 --slug <slug> --round R --preset <set>` |
+| 9 | no `results/evaluate-rR.json` (skipped under `noEval`) | **dispatch** `spec-evaluator` |
+| 10 | GATE L3 not crossed for R | `K gate --resolve L3 --slug <slug> --round R --verdict <pass\|fail\|not-evaluated>`. On fail and `R < maxRounds`, round R+1 repeats 7 to 10 for the scopes the verdict's bugs name; otherwise go to 13 |
+| 11 | GATE QA not crossed | `K gate --resolve QA --slug <slug> --round R --verdict pass --preset <set>` |
+| 12 | QA answered `run` and no `results/hunt.json` (skipped under `noQa`) | **dispatch** `qa-edge-hunter`. Do not move on without it: GATE L4 refuses `ship` over a hunt the run owed and never ran, and the only recorded way out is `K gate --resolve QA … --answer skip` |
+| 13 | no census file | do the census (`resources/stop.md`) and write `<run>/reports/hammer-census.json`; then GATE H |
+| 14 | GATE H crossed, no `<spec>REPORT.md` | write the ship report (`resources/stop.md`); then GATE L4 |
+| 15 | GATE L4 crossed | `K order close --slug <slug> --status <shipped\|escalated\|aborted> --cause "<verdict, rounds>"`; `shipped` is refused (exit 1) unless this run's L4 row says `ship`, so a refusal here means the gate was not crossed — go back to phase 14; then GATE COACH-1 |
+
+**A plan substep** is done here, in this session, with no sub-agent: write the substep's order (`resources/orders.md`, operation `plan`,
+`worker: "building"`), open it with `K order open`, write only what the substep produces (`resources/plan.md` and its `plan-*.md`
+siblings say what and how), then write `results/plan-<step>.json` yourself (the order's `own` path, so it is writable though results are frozen) and read the artifact back, before you write the next order. The order's substrate is the
+fence: while it is open, the staged pitch, the receipt and the other orders are frozen.
+
+## A dispatch
+
+The same five moves for every worker. `resources/orders.md` has the order for each operation.
+
+1. **Write the order** to `<run>/orders/<stem>.json` from the template for the operation. It carries the substrate (the globs the worker may write,
+   copied from the scope contract for a build) and the payload the worker needs, as paths where a path will do.
+2. **Open it**: `K order open --slug <slug> --order "<run>/orders/<stem>.json"`. This stamps the order's time and names the live order to the fence; without it the fence allows every write.
+3. **Spawn** the agent `shapeup-sdlc-plugin:<worker>` with the prompt `--order "<run>/orders/<stem>.json"` and one line of note, and pass the
+   **model** the launch record names for the role: `models.exec` for `orient` and `task-executor`, `models.eval` for `spec-evaluator`, `models.qa`
+   for `qa-edge-hunter`. The agent definitions say `inherit`, so a dispatch that carries no model runs on *your* session's model, whatever the
+   record asked for. The dispatch is checked against the order schema before it leaves, and leaves a receipt naming the agent that ran, the model
+   the call asked for and the model the host says ran. GATE L4 reads those receipts: an `exec` or `eval` worker that ran below the floor refuses
+   `ship`, and a model other than the record's is written into the gate's row — say so in the ship report.
+4. **Read the result** at `<run>/results/<stem>.json`: `K verify envelope "<run>/results/<stem>.json" "${CLAUDE_PLUGIN_ROOT}/kernel/schemas/work-result.schema.json"`.
+   Invalid, or absent, goes back **once** with the reason; a second failure is a phase that did not complete — name it and stop at that phase.
+5. **Apply it yourself**: update the board's `status:` for the tasks the result closed, append each discovery to `<run>/discovery/ledger.md`, append the
+   evaluator's verdict-ledger lines to `<run>/evaluation/.verdicts-<target>.jsonl`, and state what the result changed. Nobody else writes these.
+
+## Build a scope
+
+For scope `S` in round `R`, attempt `A` (start at 1): dispatch `task-executor` with operation `execute` (round 1, or `fix` with the verdict's bugs on later rounds),
+whose substrate is the scope contract's `allowed_file_substrate` and `shared_substrate`. The worker runs `K verify t0 "<spec>scopes/S.md" --round R --attempt A`
+itself. After its result lands, **run the same command yourself** and read `status` from the JSON on stdout, never from the exit code (a `kept` red-but-improved attempt exits 1):
+
+| `status` | You |
+|---|---|
+| `kept`, overall green | the scope is green for round R |
+| `kept`, red | attempt A+1 builds on this tree; fold the digested errors into the next order |
+| `reverted` or `crash` | attempt A+1; the tree was restored |
+
+A scope that reaches `attemptBudget` attempts without a green is **out of attempts**: stop building it, record it as a proposal for GATE H, and go on. It never stops the round.
+Build a scope only after the scopes in its contract's `depends_on` are green. Two scopes build at once only when no path is writable by both (read the contracts' substrates); otherwise one at a time.
+Count an attempt from the dispatch receipts in `<run>/receipts/dispatch.jsonl`, not from your memory: a dispatch with no receipt did not run the shipped worker.
+
+## The breakers
+
+`maxRounds` ends the run: after a failed round R = `maxRounds`, go to the census. `attemptBudget` ends one scope. Neither ends the run from outside — both route to GATE H, where the
+census compares what is green against the baseline and ships what works. A run killed from outside ships nothing.
+
+## Sub-commands
+
+`/ship` with none runs the whole loop. A sub-command does one activity of it:
+`plan` (`/scopes`, `/wire`) — the planning substeps; `stop` (`/hammer`) — the census over the run in hand;
+`retro` (`/retro`, `/retro --scan`, `/retro --research <stack>`) — `resources/retro.md`, `retro-scan.md`, `retro-research.md`;
+`intake <path>…` (`--check` writes nothing) — the language gate alone, `resources/intake.md` §2.
+
+## Resume
+
+`/ship` again over an open run is the resume (over a closed one, phase 0 reports the ending and stops): `init run` refuses and prints what is on disk, and you continue from the phase table, reading files and nothing else.
+A run closed without shipping is reopened by `init run --force`, which resolves every order nobody answered as abandoned before it writes.
+
+> **Intake, language check and translation, profile, the launch record** → `resources/intake.md`
+> **The order for each operation: substrate, payload, where each field comes from** → `resources/orders.md`
+> **Planning: how a substep runs, requirements; the spec, wiring and scope formats** → `resources/plan.md` and its `plan-*.md` siblings
+> **Which knowledge-base file is read where, and under what name a rule is filed** → `resources/guidance.md`
+> **How to put a gate to the PO, and what to have read first** → `resources/gates.md`
+> **What a round is; the attempt loop; why the loop stops where it does** → `resources/rounds.md`
+> **The census, the baseline comparison, the cut list, the ship report (GATE H)** → `resources/stop.md`
+> **After a ship: feedback, the retro gate, `--scan`, `--research`** → `resources/retro.md`, `retro-scan.md`, `retro-research.md`

package/skills/building/resources/gates.md

@@ -0,0 +1,76 @@
+# Putting a gate to the PO
+
+A gate resolves through the kernel, never through a paragraph of yours. When `gate --resolve` exits 4
+it is your job to ask well: print the `block` verbatim, then **one question, the valid decisions, your
+recommendation first**. The recommendation is yours; the answer is the PO's.
+
+| Gate | What the PO is deciding | Recommend |
+|---|---|---|
+| `L1a` Orient Review | the Scout's code-surface map and the spike result, before any board exists | `proceed` unless the spike found the shape does not fit the code; `abort` when it did |
+| `L1a.5` Wiring Review | every use case traced to its seam and entry point | `proceed` when each has one; name any that does not |
+| `L1b` Board Review | the scope board and its disjointness — where scope is actually decided | read the REQ → AC table in the block's neighbourhood first: a requirement no acceptance criterion grades and no scope claims is **red**. The ways out are an AC carrying `(covers: REQ-…)` or the PO marking the clause `CUT (PO-approved)`. `proceed` only when none is red. |
+| `L2` Build Round Complete | whether the round's work goes to evaluation | `proceed`; over unfinished tasks it is a warning, not a block. A board with no tasks at all forces a stop however it is answered |
+| `L3` Verdict & Loop | the judge's verdict for the round | on FAIL `loop` while rounds remain, `stop` to cut; on PASS the answer only matters for the next phase |
+| `QA` QA Edge Hunt | whether to hunt past what the judge probed | `run` unless the PO is out of time; a hunt discovers and never blocks |
+| `H` Decide When to Stop | the census: what ships and what is cut, against the baseline and never the ideal | `accept-cut-list` for `ship-now` or `ship-after-fixes`; `cannot-ship` never reaches this question |
+| `L4` Ship Sign-Off | final go/no-go; `ship` is only offered when a census cleared the run, any QA hunt the run owed ran (or GATE QA was answered `skip`), and no `exec` or `eval` worker ran below the model floor by its receipt; a model other than the launch record's is written into the row, not refused | `ship` only after reading the status line the block carries |
+
+An unattended run puts none of these to anyone: its answer set resolves them and the ledger names the
+set as the source. A gate with no answer and no human is a fast, attributable abort, not a silent wait.
+
+## What to have read, and printed, before you ask
+
+The `block` is the kernel's facts; the PO decides on more than those, so read what the gate is about first and
+print the headline from the artifact — never composed from memory. Guidance may add a question to any of these;
+it never answers one.
+
+**L1a — Orient Review.** Read `.shapeup/<slug>/orient/`. Render the area-level Hill from `hill-signal.md` (each
+suspected area uphill — open unknowns · crest — approach proven by the spike · downhill). Print the breadboard
+source (flag, sibling, shaping dir, shared root, embedded, or none), the code-surface headline, the spiked area
+and its result, and the riskiest open unknowns going into mapping. Ask at most two: is the riskiest area the one
+that was spiked, and is there an unknown that needs another spike before scopes are mapped?
+
+**L1a.5 — Wiring Review.** Every use case has one declared engine → seam → entry-point call site → affordance in
+`wiring-map.md`. Name any that does not.
+
+**L1b — Board Review.** The PO reviews the committed plan — `usecases/_index.md`, `scopes/*.md`,
+`scope-summary.md`'s Done-when headlines — never the per-machine task board; task-level detail stays hidden here
+by design. Print: use-case count and actors; the scope board (scope id, topology, substrate file count); any spike
+blockers; the Done-when headlines; the **Deferred Places** from `ux-behavior.md` — breadboard Places the shape will
+not build, each needing the PO's yes, a rejected deferral going back to planning as a screen; and the
+`REQ → AC` table, one row per registered requirement (`REQ-12 ← shaping.md R12`, the criterion that grades it,
+or the scope that claims it, or `CUT (PO-approved)`), omitted when the run has no registry. The table is printed,
+never asked: it decides nothing at this gate.
+Read the plan back here yourself, whatever the planning step already checked, because a human may have approved past a
+problem and no script lints it for you. A problem is a hard stop: a file in two scopes' substrate without both declaring it
+shared, a scope aligned with a directory (PA1), a scope whose use case does not resolve, a `depends_on` naming a scope that is
+not there, a requirement no criterion grades and no scope claims, a Place with UI affordances folded into another screen. A scope over
+~15 files is a warning. The breadboard problems are planning's to fix — add the screen or defer the Place, never fold it into another
+screen. Scopes are released in dependency order: a scope opens the moment the scopes it declares in `depends_on` have settled, up to
+`maxParallelScopes`, and contracts declaring none are one wave, every scope eligible at once. Ask at most two: scope cuts? any spike to resolve before build? Frame cuts against
+the pitch's appetite, and surface the pitch's rabbit holes — a cut here is cheap, after round 1 it is expensive.
+
+**L2 — Round Close.** The block carries `green_scopes`, `hammer_proposals` and the build gate (`green`, `red —
+<failing step>`, or `undeclared`). `red` means the judge is not dispatched this round and the failing step
+becomes round r + 1's bugs; `undeclared` means the round goes to evaluation over an unproven build, and the
+block says so. Over unfinished tasks it is a warning, not a block.
+
+**L3 — Verdict.** Report progress by hill position per scope (from the committed hill shards), never by "N of M
+tasks done" — a 90%-done slice can be stuck uphill on the one unknown that matters. On FAIL, print the bug list
+grouped by scope: the failed Done-when criterion and its repro, and **nothing about causes or fixes** — the
+orchestrator names the scope; the implementer diagnoses. A round whose build gate was red never reached the
+judge: the "bug list" is the gate's failing step. Ask at most one: fix these in round r + 1, cut scope, or waive a
+bug? Past the round budget the answer is the census, with the residual bug list.
+
+**QA.** A hunt discovers; the run's verdict stays the judge's PASS. Triage happens at H and L4.
+
+**H — Cut List.** See `resources/stop.md`: the census against the baseline, never the ideal.
+
+**L4 — Ship Sign-Off.** Print the feature as `SHIPPED (deployed)` or `BUILT & VERIFIED — deploy pending (PO)`;
+rounds; the verdict with the dimensions evaluated **and** not evaluated, so "shipped" never reads as "verified
+for all"; QA findings (all held as `~`) or skipped; and the `Requirements:` line **transcribed** from
+the report's Requirements table, which you read off the verdict and `requirements.md`, never composed from memory (it decides nothing: a clause with no PASS
+evidence is a fact the census weighs, not a veto). Deploy is outward-facing and the PO's: the loop stops at built and verified, records
+`deploy pending (PO)` unless the PO says to run the project's own deploy, and never deploys itself. Ask at most
+one: anything to record before closing? Substantive feedback goes to the retro (`resources/retro.md`), which
+asks the PO which rule belongs where; the loop never categorises feedback itself.

package/skills/building/resources/guidance.md

@@ -0,0 +1,23 @@
+# The knowledge base — which file is read where
+
+`shapeup/knowledge-base/<name>.md` holds the rules the team has filed. Guidance steers craft: **a rule may
+add a question or a check to a gate block, never an answer, a skip, a reorder or a wider substrate.** A rule
+that disagrees with the spec, a contract, a gate or a kernel check loses, and the conflict is told to the PO.
+
+Files are named after the skill a rule was first filed under, and a consumer's existing files keep working.
+New rules are written under the **activity** name. The loop reads, in order:
+
+| Read at | Files | Why those names |
+|---|---|---|
+| L0, before the intake questions | `building.md`, then `tech-lead.md` | `tech-lead.md` is what the loop's guidance was filed as before it had its own name; it is read as `building` guidance |
+| every `plan` step (its `guidance` field lists the ones that exist; the order's `payload.kb_rules_paths` names all four) | `plan.md`, `ba-pitch-analyzer.md`, `scope-architect.md`, `solution-architect.md` | the planning activity was three skills; each file's rules still apply to the substep that skill's craft became (analysis, scope contracts, wiring) |
+| a dispatched worker's order | `task-executor.md`, `orient.md`, `qa-edge-hunter.md` — the worker reads its own, from `payload.kb_rules_path` | unchanged |
+
+Never read: a file for `spec-evaluator` (the judge is not coachable — a coached judge is a second grader) or
+for the stop step's census (its ownership, exhaustion and requirement claims come from files, not
+from guidance). A file left behind under the name of a retired skill — `scope-hammer.md`, `coach.md`,
+`translator.md` — is read by nobody; its rules are filed again under a category at the next retro.
+
+A rule filed against `ba-pitch-analyzer`, `scope-architect` or `solution-architect` is read by the plan
+step and is rewritten under `plan` the next time the retro touches it; the old file is never deleted by the
+loop.

package/skills/{translator/references/preservation-rules.md → building/resources/intake-preservation.md}

@@ -1,6 +1,6 @@
 # Preservation Rules
 
-What the translator touches, what it must never touch, and how it proves the result.
+What the intake translation touches, what it must never touch, and how it proves the result.
 Read this before translating any file. The governing principle: **translate meaning,
 preserve everything that machines parse.** A `.en.md` that reads well but breaks the spec
 tree's wikilinks or drops a table row is a failed translation.

package/skills/building/resources/intake.md

@@ -0,0 +1,157 @@
+# Intake — opening a run
+
+Everything the run needs is pinned once, here, so the loop never has to guess. The intake is a
+**kicked-off pitch**: shaping, betting and kick-off are the PO's own and happen upstream. A raw idea is
+not an intake.
+
+## 1. Resolve the pitch
+
+In order: `--pitch <path>` (a shaping or pitch file), `--spec <folder>`, requirement text passed to the
+skill. **None resolvable → stop.** Print "✋ NO INTAKE — name a kicked-off pitch (`--pitch <path>`)" and
+nothing else: do not emit the L0 block, list downstream gates, or describe the pipeline that "will" run.
+A run with no spec has nothing to drive, and narrating one reads exactly like a run that worked.
+
+A pitch is `shaping.md` plus its `breadboard.md`. You find the breadboard beside the pitch, in
+`shapeup/<slug>/shaping/`, one the PO names, or inline in a single `pitch.md`, and you copy it to
+`.shapeup/<slug>/breadboard.md` once the run is open: that is the path every planning order freezes and every worker reads.
+
+## 2. Language check — the harness is English end to end
+
+The planner, the doers and the judge all assume English and fail hard on anything else, so this is the one
+place a non-English intake is made English: **faithfully, once, by you, in this context** — no sub-agent. It
+normalises language and nothing else: it never plans, builds or judges, never summarises, adds or drops a
+requirement, and never translates harness *output* back into the PO's language. `/ship intake <path>…` (the
+`intake` sub-command) runs just this step over named files, and with `--check` stops after the detection and
+writes nothing.
+
+**Detect.** For the pitch **and** its breadboard, sample headings and body prose (ignore code, identifiers and
+URLs): `English` → used as it is, no `.en.md` written (idempotent, so a re-run and `--check` are safe and
+cheap); `non-English` → queue; `mixed` → queue, and leave the English spans exactly as written.
+
+**Glossary.** One English term per source term, across every document and every run — two spellings read as two
+concepts to the planner's domain pass. Load the feature's `shapeup/<slug>/shaping/glossary.md` when it exists as
+the base map; extract domain nouns, actor names, status/enum values, screen names and feature jargon with a
+proposed English term each; mark the do-not-translate tokens (proper nouns, brand and product names, code
+identifiers, API names, env vars, file paths), which pass through verbatim. **An ambiguous term (one source
+word, several valid English terms) is asked of the PO and never guessed** — a wrong canonical term cascades
+into every document and every round. `auto` and `unattended` runs go on when nothing is ambiguous, and still
+stop when something is.
+
+**Translate.** Write `<name>.en.md` beside its source — under `shapeup/<slug>/shaping/` when the source lives
+there; the **original is never overwritten**. This is the committed tier, and the loop is its writer. Prose
+becomes English with the glossary applied to every domain term; everything a machine parses stays byte
+identical, and structure stays 1:1 — same headings, table rows, list items, order. What is kept and what is
+translated, the glossary protocol and the verification scan are in `resources/intake-preservation.md`; read it
+before translating any file.
+
+**Verify, then sign off.** A residual-language scan of every `.en.md` outside code and do-not-translate tokens
+(any hit lists `file:line` and the file does not pass), a structural diff against the source (heading, table-row,
+list-item, wikilink and code-block counts must match — a mismatch is a requirement dropped or added), and a
+glossary with no unresolved term. A dirty scan stops the run in every lane: a half-translated intake makes the
+planner fail mid-run, which is worse than stopping here. Clean →
+
+```
+Translated   : <k> files → <name>.en.md
+Glossary     : shapeup/<slug>/shaping/glossary.md (<t> terms, <a> resolved ambiguities)
+Residual scan: clean | <n> non-English spans → [file:line …]
+Structure    : matches source | <diff>
+```
+
+The run **opens on the `.en.md` files** (`--intake-file <name>.en.md`, and the `<breadboard>.en.md` copied to `.shapeup/<slug>/breadboard.md`):
+the intake is what every planning step reads, so a translation made after the run opened reaches nobody. A run
+already open on the original is reopened with `init run --force` — nothing has been planned yet. Once the run
+is open, write the audit trail (what was detected, skipped or flagged, the glossary diff, the scan result) to
+`.shapeup/<slug>/translation-report.md`.
+
+## 3. Collect, explicitly
+
+Never inferred; ask for what the pitch does not say.
+
+| | |
+|---|---|
+| Appetite | the pitch frontmatter's `appetite`. Missing or uncapped is a risk: say so at L0 and again at the board gate. It sizes the round budget: 1 week → 2 rounds, 2 weeks → 3, 6 weeks → 4. |
+| Lens | `lite` \| `standard` \| `cross-context` (default `standard`) — carried as `lens` in every `plan` order's payload |
+| Stack hint | aims the Scout's sweeps and the run commands (e.g. "pnpm, Next 16 web :3000") |
+| Eval dimensions | default `auto`: the order resolves the set from the spec. Name a set only on request; it must reach every `evaluate` order's `dimensions`, or it grades nothing. What is left out is reported at the ship gate as not evaluated. |
+| Rounds, attempts | default 3 rounds, 5 attempts per scope per round. `resources/rounds.md` says why there are two breakers |
+| Auto level | `interactive` (default): pause at every gate · `auto`: low-risk gates pre-answered, still pause at the judgment gates and ship · `unattended`: headless, needs an answer set |
+| Models | resolve once: flags, then `.claude/settings.local.json`, then `.claude/settings.json`, then defaults, and pass the result as `--exec-model` / `--eval-model` / `--qa-model`. Exec and eval must be sonnet or above — `init run` refuses a cheaper tier. A model the member's plan does not offer degrades one tier down, and the degrade is said at the L0 gate, never silent. |
+| Run commands | the build command (`run_cmd`), and the profile's `build_probe` and `launch_probe`. A `mobile` profile with no launch probe has nobody owning the install and launch risk: say so. |
+| Knowledge base | read `shapeup/knowledge-base/building.md` and then `tech-lead.md` (the same guidance under its old name; `resources/guidance.md`) if they exist. It may add a question or a check to a gate block and may propose run values (confirm each with the PO and note `(source: knowledge-base)`). It never answers, skips or reorders a gate. With no file at all, offer `/retro --scan` once and go on whether or not the PO takes it. |
+
+## 4. Open the run
+
+Write the requirement to a file first and pass the path; a multi-line requirement inlined into a shell
+argument is where this step goes wrong. **Every switch the operator typed goes on this one command**: `init
+run` writes the launch record (§7) in the same act as the receipt, so a switch left off it does nothing.
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" init run --slug <slug> --intake-file <path> --auto-level <interactive|auto|unattended> [--gate-answers <ci|guarded|path.json>] [--max-rounds 3] [--attempts 5] [--exec-model <m>] [--eval-model <m>] [--qa-model <m>] [--no-eval] [--no-qa] [--parallel-scopes <N>]
+```
+
+Ask for every value in §3 *before* this command, so the record is right the first time; a change the PO asks
+for at the L0 gate (§6) re-opens the run with `--force` — nothing has been planned yet.
+
+**Exit 2 naming a role** means a model is below the floor (`exec` and `eval` must be sonnet or above; `qa` and,
+under `--no-eval`, `eval` are not checked): say which, and ask for another. An unknown switch exits 2 too, naming it.
+
+**Exit 3 means a run is already open, or the worker roster is missing.** For an open run the refusal prints the
+launch record it keeps — the switches typed to *this* call were not applied — and the loop continues from the phase
+table in `SKILL.md`. `--force` reopens deliberately: it answers every order nobody answered as abandoned, retires the
+fence's pointer and writes a fresh record; only the PO asks for it.
+
+## 5. The shared profile
+
+Write `shapeup/<slug>/project-profile.md`: frontmatter `{schema_version: 1, archetype, entry_point}` plus,
+when the project has them, `build_probe` and `launch_probe`. Nothing downstream can be
+wired without it, and a typo in the `archetype` enum must fail rather than silently disable a check.
+
+| Field | Meaning |
+|---|---|
+| `archetype` | `client-only-game` · `web-service` · `mobile` · `library` · `data-pipeline` |
+| `entry_point` | the composition root the wiring map names its call sites against. Where some module composes the app, name that one rather than the file the platform happens to start |
+| `build_probe` | asserts the BUILT ARTIFACT covers what the run wrote — a green exit code is not proof the feature compiled when the toolchain compiles only what an entry point reaches |
+| `launch_probe` | installs, starts and asserts the first screen. A `mobile` profile without one is worth saying at L0, because nothing else launches the app |
+
+The loop runs them itself, once per round before it dispatches the evaluator: a scope's fixture can be green while its
+code never compiles, on any toolchain that compiles only what the entry point reaches, so `build_probe` asserts the
+built artifact. A red step ends the round with no verdict, and its failure is the next round's bug.
+
+## 6. The L0 gate
+
+Emit the block, then resolve it like every other gate:
+
+```
+⏸ GATE L0 — Intake & Run Config
+Feature      : <slug>   (kicked-off pitch: <path>)
+Intake lang  : English | translated → <name>.en.md
+Appetite     : ~1 week | ~2 weeks | ~6 weeks | ⚠ missing — scope uncapped
+Eval dims    : auto | the named set        Rounds: <N>     Auto: <level>
+Run commands : <run_cmd> · build_probe <set|—> · launch_probe <set|— ⚠ mobile>
+Model matrix : exec=<m> eval=<m> qa=<m>   (source: flags | settings.local | settings.json | default)
+Budgets      : round_budget=<N> (outer)   attempt_budget=<N> (inner, per scope)
+Knowledge    : building.md — <N> rules | none
+```
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" gate --resolve L0 --slug <slug> [--file <path>|--preset <name>]
+```
+
+Exit 4: put the block to the PO and wait. Exit 0 `proceed`: continue. Exit 5: stop; do not launch.
+
+## 7. The launch record
+
+`.shapeup/<slug>/run-args.json` is what this run was launched with, written by `init run` and read by the loop;
+it is the only place a typed switch survives. The loop reads nothing but the record and the artifacts.
+
+| Switch on `init run` | Field |
+|---|---|
+| `--auto-level` | `autoLevel` |
+| `--gate-answers <set>` | `answers` — the answer set the gates resolve through |
+| `--exec-model` `--eval-model` `--qa-model` | `models.{exec,eval,qa}` — a flag, else `SHAPEUP_EXEC_MODEL` / `SHAPEUP_EVAL_MODEL` / `SHAPEUP_QA_MODEL`, else `sonnet`; `qa` follows `exec` |
+| `--max-rounds` `--attempts` | `budgets.{maxRounds,attemptBudget}` |
+| `--no-eval` | `noEval` — skips the evaluation; the ship report says so in its first line and never reads as verified; you do not write PASS over a run launched with it |
+| `--no-qa` | `noQa` — skips the QA hunt |
+| `--parallel-scopes N` | `maxParallelScopes` — how many scopes build at once (default 4; `1` = sequential) |
+
+Then go to the loop.