shapeup-sdlc 3.5.0 → 3.6.0

package/kernel/report/export.mjs

@@ -47,10 +47,11 @@ import { runArgs } from "../lib/argv.mjs";
 import { splitFrontmatter } from "../lib/contract.mjs";
 import { runIdFromReceipt, readReceipt } from "../lib/paths.mjs";
 import { TABLES, runRow, dispatchFacts } from "./facts.mjs";
+import { deriveRounds } from "../probe/rounds.mjs";
 import {
   localDir, activeScope, receipt as receiptPath, harnessRun, ordersDir, resultsDir,
   trials as trialsPath, verdictsDir, evaluationDir, decisions as decisionsPath,
-  exportsDir, exportRunDir,
+  gates as gatesPath, roundBuildDir, exportsDir, exportRunDir,
 } from "../lib/paths.mjs";
 
 export const EXPORT_SCHEMA_VERSION = 1;
@@ -164,6 +165,51 @@ function criterionRows(dir, runId, t) {
   return out;
 }
 
+/**
+ * Flatten one gate-crossing ledger row (`gates.jsonl`, `kernel/gate.mjs`'s sole writer) into a
+ * flat `gate_decision` fact row. The row on disk already carries exactly these fields
+ * (see `appendGateLedger`), so this is a pass-through with a stamped `run_id` fallback rather than
+ * a re-derivation: two readers of "what did this gate decide" must not compute the answer twice.
+ * @param {object} g - One parsed line of `gates.jsonl`.
+ * @param {(string|null)} runId - Run key for a row written before it carried its own.
+ * @returns {object} A flat `gate_decision` row.
+ */
+function gateDecisionRow(g, runId) {
+  return {
+    run_id: g?.run_id ?? runId ?? null,
+    gate: g?.gate ?? null,
+    decision: g?.decision ?? null,
+    status: g?.status ?? null,
+    source: g?.source ?? null,
+    round: g?.round ?? null,
+    has_note: !!(g?.note && String(g.note).trim()),
+  };
+}
+
+/**
+ * Flatten one round build-gate artifact (`kernel/verify/build.mjs`'s `writeRoundBuild`) into a flat
+ * `build_gate` fact row. The gate ends a round exactly as EVAL does (AGENTS.md's round
+ * build gate ⚙), and until now had no fact table at all.
+ * @param {object} a - A parsed round-build artifact.
+ * @param {(string|null)} runId - Run key for an artifact written before it carried its own.
+ * @returns {object} A flat `build_gate` row.
+ */
+function buildGateRow(a, runId) {
+  const steps = Array.isArray(a?.steps) ? a.steps : [];
+  return {
+    run_id: a?.run_id ?? runId ?? null,
+    round: a?.round ?? null,
+    trial: a?.trial ?? null,
+    at: a?.at ?? null,
+    overall: a?.overall ?? null,
+    archetype: a?.archetype ?? null,
+    steps_total: steps.length,
+    steps_failed: steps.filter((s) => !s?.skipped && s?.pass === false).length,
+    warnings: Array.isArray(a?.warnings) ? a.warnings.length : 0,
+    discovered_tasks: Array.isArray(a?.discovered_tasks) ? a.discovered_tasks.length : 0,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // The export itself
 // ---------------------------------------------------------------------------
@@ -190,7 +236,10 @@ export function collectRun(cwd, slug) {
   const results = readJsonDir(resultsDir(cwd, slug), t);
 
   const { dispatch, ac_result, discovery, file_touched } = dispatchFacts({ orders, results, runId });
-  const run = runRow({ receipt: rec, ledger, runId });
+  // Computed here, once, from the same trace this whole function reads, and handed to
+  // runRow rather than re-derived by it: runRow stays pure (no I/O), this function already has cwd.
+  const rounds = deriveRounds(cwd, slug, ledger.rounds_used);
+  const run = runRow({ receipt: rec, ledger, runId, rounds });
 
   // Hook decisions are checkout-wide, so they are FILTERED to this run rather than read from a
   // per-run file. Rows with a null key belong to no run (a hook that fired outside one) and are
@@ -208,6 +257,9 @@ export function collectRun(cwd, slug) {
       t0_verdict: readJsonDir(verdictsDir(cwd, slug), t).map((a) => t0Row(a, runId)),
       criterion_verdict: criterionRows(evaluationDir(cwd, slug), runId, t),
       hook_decision,
+      // The decision that crossed each gate, and the round build gate's own artifact.
+      gate_decision: readJsonl(gatesPath(cwd, slug), t).map((g) => gateDecisionRow(g, runId)),
+      build_gate: readJsonDir(roundBuildDir(cwd, slug), t).map((a) => buildGateRow(a, runId)),
     },
     defects: { records_skipped: t.skipped },
   };

package/kernel/report/facts.mjs

@@ -27,6 +27,11 @@
 export const TABLES = [
   "run", "dispatch", "ac_result", "discovery", "file_touched",
   "trial", "t0_verdict", "criterion_verdict", "hook_decision",
+  // The decision that shipped a run (or any other gate) had a ledger row (`gates.jsonl`)
+  // and no table — a reader had to open the LOCAL trace itself, which the export exists so nobody
+  // has to. `build_gate` is the round build gate's own artifact (kernel/verify/build.mjs), on the
+  // same terms: it ends a round exactly as EVAL does, and had no table either.
+  "gate_decision", "build_gate",
 ];
 
 /** Coerce anything to a finite number, or null. Keeps `0` and rejects `NaN`/`""`/undefined. */
@@ -76,9 +81,14 @@ export function parseOrderStem(orderId) {
  * @param {(object|null)} o.receipt - Parsed `receipt.json`.
  * @param {(object|null)} [o.ledger] - Parsed `harness-run.md` frontmatter (a flat scalar map).
  * @param {(string|null)} [o.runId] - The run key, when already resolved.
+ * @param {({rounds_used:*, rounds_judged:(number|null)}|null)} [o.rounds] - The two-number
+ *   derivation (`probe/rounds.mjs`'s `deriveRounds`), computed by the caller because it needs the
+ *   filesystem and this function stays pure. Falls back to the ledger's own (unreliable — see
+ *   `deriveRounds`) `rounds_used` line when the caller has not derived one, so an existing caller
+ *   is unaffected rather than broken.
  * @returns {(object|null)} The run row, or null when there is no receipt to describe.
  */
-export function runRow({ receipt, ledger = null, runId = null }) {
+export function runRow({ receipt, ledger = null, runId = null, rounds = null }) {
   if (!receipt) return null;
   const c = receipt.config || {};
   const fm = ledger || {};
@@ -87,6 +97,9 @@ export function runRow({ receipt, ledger = null, runId = null }) {
     slug: receipt.slug ?? null,
     started_at: receipt.started_at ?? null,
     closed_at: fm.closed_at && fm.closed_at !== "~" ? fm.closed_at : null,
+    // Why the run ended at a terminal status, written by `probe resume --close` alongside
+    // `closed_at` — the two facts a trace needs to tell a live run from a dead one apart.
+    close_cause: fm.close_cause && fm.close_cause !== "~" ? fm.close_cause : null,
     intake_sha256: receipt.intake_sha256 ?? null,
     intake_chars: num(receipt.intake_chars),
     intake_lines: num(receipt.intake_lines),
@@ -101,8 +114,17 @@ export function runRow({ receipt, ledger = null, runId = null }) {
     // Copied from the ledger, never re-derived: the run's own status line is the harness's answer,
     // and a read plane that recomputed it would be asserting a second one.
     status: fm.status ?? null,
+    // The terminal status `closeRun` alone writes, carried BESIDE `status` rather than instead of
+    // it. `status:` is ordinary phase traffic and a later phase may move it, so an export that
+    // carried only that line could show a run wearing another close's cause. These two disagreeing
+    // is itself the fact worth exporting: it says the ledger was written after the close.
+    closed_status: fm.closed_status && fm.closed_status !== "~" ? fm.closed_status : null,
     final_verdict: fm.final_verdict && fm.final_verdict !== "~" ? fm.final_verdict : null,
-    rounds_used: num(Number(fm.rounds_used)),
+    // Two fields, not one: `rounds_used` is the highest round carrying ANY build evidence,
+    // `rounds_judged` the highest round EVAL actually returned a verdict for. A caller that has not
+    // derived `rounds` falls back to the ledger's own (pre-fix, unreliable) line, non-regression.
+    rounds_used: rounds ? num(Number(rounds.rounds_used)) : num(Number(fm.rounds_used)),
+    rounds_judged: rounds ? num(rounds.rounds_judged) : null,
   };
 }
 

package/{skills/tech-lead → kernel}/schemas/domain.schema.json

@@ -668,14 +668,14 @@
             "string",
             "null"
           ],
-          "description": "Source file of the failure; null/absent when the log line carried no location (raw triple — never invented)."
+          "description": "Source file of the failure; null/absent when the log line named no file at all (raw triple — never invented)."
         },
         "line": {
           "type": [
             "integer",
             "null"
           ],
-          "description": "Line of the failure; null/absent when the log line carried no location. Paired with `file` — a triple has both or neither, and neither is ever invented to satisfy a shape."
+          "description": "Line of the failure; null/absent when the diagnostic carried no line number — independently of `file`, since a diagnostic can name a file with no line (a resource-compiler error, for example). Never invented to satisfy a shape."
         },
         "core_message": {
           "type": "string",
@@ -1891,9 +1891,10 @@
             "building",
             "evaluating",
             "shipped",
-            "escalated"
+            "escalated",
+            "aborted"
           ],
-          "description": "Mirrors harness-run.md frontmatter status."
+          "description": "Mirrors harness-run.md frontmatter status — kernel/probe/resume.mjs's RUN_STATUSES is the source enum this one must not drift from."
         },
         "round": {
           "type": "integer",
@@ -1904,7 +1905,12 @@
           "description": "From the latest t0/verdicts/r<N>-a<M>.json filename."
         },
         "rounds_used": {
-          "type": "integer"
+          "type": "integer",
+          "description": "Highest round carrying any build evidence (an order, a T0 verdict, a round build-gate artifact, or an EVAL result) — kernel/probe/rounds.mjs's deriveRounds(), the same derivation the ship report and the export use. Falls back to harness-run.md's literal frontmatter value only when no such evidence exists on disk."
+        },
+        "rounds_judged": {
+          "type": "integer",
+          "description": "Highest round EVAL actually returned a verdict for (an evaluate-r<N>.json result on disk) — its own field, never folded into rounds_used: a round built is not a round judged. Omitted when no round has been judged yet."
         },
         "max_rounds": {
           "type": "integer"
@@ -2704,10 +2710,10 @@
       }
     },
     "RunArgs": {
-      "description": "C1 — the launch half of the workflow's only conversation. Compiled ONCE by tech-lead at GATE L0 from harness init run output + the L0.8 model matrix + budgets, written to .shapeup/<slug>/run-args.json and handed to the harness run launch as one JSON literal — the workflow cannot ask follow-ups and cannot read config files itself, so everything a run will ever need travels in this one record. A workflow script validates its own subset of this shape in code (no runtime schema check at the C1 boundary itself); this entry is the central-registry definition the workflow script and the tech-lead skill both read as the one true shape.",
+      "description": "C1 — the launch half of the workflow's only conversation. Resolved ONCE at GATE L0 from harness init run output + the L0.8 model matrix + budgets, then built by `harness init run-args`, which writes it to .shapeup/<slug>/run-args.json AND prints it — tech-lead passes that printed value to the harness run launch as one JSON literal, never a second, hand-typed copy of it. The workflow cannot ask follow-ups and cannot read config files itself, so everything a run will ever need travels in this one record. A workflow script validates its own subset of this shape in code (no runtime schema check at the C1 boundary itself); this entry is the central-registry definition the workflow script, `harness init run-args` and the tech-lead skill all read as the one true shape.",
       "x-tier": "EMBEDDED",
-      "x-location": ".shapeup/<slug>/run-args.json — written fresh by tech-lead on every launch and relaunch; the workflow receives it as its args and never reads other config",
-      "x-writer": "tech-lead (GATE L0, on every launch AND every relaunch after a paused gate)",
+      "x-location": ".shapeup/<slug>/run-args.json — written fresh on every launch and relaunch by `harness init run-args`; the workflow receives it as its args and never reads other config",
+      "x-writer": "harness init run-args (kernel), invoked by tech-lead at GATE L0 on every launch AND every relaunch after a paused gate",
       "x-readers": "the Workflow runtime (shapeup-run, and shapeup-run's own inner round dispatch)",
       "x-not-here": "Run config the LEDGER already carries does NOT get a second home in RunArgs — eval_dimensions, lens, spec_folder, stack, run_cmd, app_url are read off harness-run.md frontmatter by resume-state on every launch AND every relaunch, so a copy here would be a second source that can disagree with the first. RunArgs carries what a workflow cannot derive from disk (identity, budgets, the model matrix, pluginRoot, startedAt) plus noEval, which no frontmatter line holds.",
       "type": "object",
@@ -2759,16 +2765,13 @@
         },
         "budgets": {
           "type": "object",
-          "description": "The three-level circuit breaker's own limits (AGENTS.md) — outer round_budget, inner attempt_budget, and the opt-in wall-clock breaker.",
+          "description": "The two RunArgs-level circuit breakers (AGENTS.md) — outer round_budget, inner attempt_budget. The third, opt-in DEADLINE breaker (the wall-clock budget) is NOT a RunArgs field: it is typed once, at `harness init run --wall-clock-budget`, and lands in the run receipt's `wall_clock_budget_s` — `harness verify budget` reads that receipt field directly and never sees this launch's RunArgs at all, so it has no member here to declare.",
           "properties": {
             "maxRounds": {
               "type": "integer"
             },
             "attemptBudget": {
               "type": "integer"
-            },
-            "wallClockS": {
-              "type": "integer"
             }
           }
         },

package/kernel/verify/envelope.mjs

@@ -12,7 +12,7 @@
 //   #/$defs/Name                       — a definition in the SAME schema document
 //   domain.schema.json#/$defs/Name     — a definition in a SIBLING file (the central domain
 //                                        registry; resolved against the schema's own dir,
-//                                        falling back to skills/tech-lead/schemas/)
+//                                        falling back to kernel/schemas/)
 //
 // Usage (CLI):    node kernel/harness.mjs verify envelope <envelope.json> <schema.json>
 //                 exit 0 = valid, 1 = invalid (errors printed one per line)
@@ -28,7 +28,7 @@ import { runArgs } from "../lib/argv.mjs";
 import { runHook, readStdin, settle } from "../../hooks/lib/decision.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
-export const SCHEMAS_DIR = resolve(HERE, "../../skills/tech-lead/schemas");
+export const SCHEMAS_DIR = resolve(HERE, "../schemas");
 
 /**
  * Validate a value against the JSON-Schema subset the envelope schemas use (type, required,

package/kernel/verify/skills.mjs

@@ -45,7 +45,7 @@ export const PLUGIN_ROOT = resolve(HERE, "../..");
  *   its own domain registry has a broken installation, which is the very thing being checked.
  */
 export function roster(root = PLUGIN_ROOT) {
-  const schemaPath = join(root, "skills/tech-lead/schemas/domain.schema.json");
+  const schemaPath = join(root, "kernel/schemas/domain.schema.json");
   const schema = JSON.parse(readFileSync(schemaPath, "utf8"));
   const names = schema?.$defs?.WorkerName?.enum;
   if (!Array.isArray(names) || !names.length) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shapeup-sdlc",
-  "version": "3.5.0",
+  "version": "3.6.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"

package/skills/coach/SKILL.md

@@ -93,7 +93,7 @@ never lands in any worker's KB.
 Orchestrated, this skill is dispatched like every worker: a **WorkOrder** in (`--order <path>`,
 operation `coach` or `scan`), a **WorkResult** out. Standalone, the raw feedback is passed
 directly; it maps onto the one payload field registered for this worker in the central domain
-registry (`skills/tech-lead/schemas/domain.schema.json`, `x-payload-by-worker`):
+registry (`kernel/schemas/domain.schema.json`, `x-payload-by-worker`):
 
 | Payload field | Standalone form | Meaning |
 |---|---|---|
@@ -117,7 +117,13 @@ fields nobody used" → "Prefer the minimum DTO that satisfies the AC; don't add
 fields"). Keep the originating why — a rule without its reason gets ignored or misapplied.
 
 ### Step 2 — ⏸ GATE COACH-1: Categorize (ASK, never assume)
-This is the load-bearing gate. **Do not infer which skill a rule belongs to** — a
+This is the load-bearing gate. **Resolve it first** — `node
+"${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" gate --resolve COACH-1 --slug <slug>
+[--file <path>|--preset <name>]` — so the ledger carries a row for the decision this gate makes,
+same as every other gate in the run. Exit 0 (`decision=skip`) — an unattended lane with no live PO;
+record nothing and stop here, the same outcome the CI preset's own note already documents. Exit 4
+(`ask`) — proceed with the categorization below, which IS the PO conversation this decision opens.
+**Do not infer which skill a rule belongs to** — a
 miscategorized rule lands in a file the wrong worker reads (or no worker reads). Present every
 candidate rule and ask the PO to assign each one. Emit this block, then stop and wait:
 

package/skills/hill-chart/SKILL.md

@@ -10,7 +10,7 @@ re-runs a computation that would erase true history.**
 
 You are not a worker: no WorkOrder, no WorkResult, invoked directly by the user (or by `/hill`)
 exactly like `shapeup` is. There is nothing to declare in
-`skills/tech-lead/schemas/domain.schema.json` and nothing to teach `harness compile` or
+`kernel/schemas/domain.schema.json` and nothing to teach `harness compile` or
 `harness reduce ingest` — those steps exist only for dispatched workers.
 
 ## What you read
@@ -71,9 +71,8 @@ Build one `{ scope_id, phase }` object per file.
 ## Rendering — the injection contract
 
 The engine ships at `assets/dashboard.template.html` — a complete, self-contained HTML page
-(inline CSS/JS, no external fetch beyond Google Fonts, no build step — the same convention as
-this repo's own `docs/visualize/*.html`). Do not rewrite it from a text description; read it,
-fill in real data, and write the result.
+(inline CSS/JS, no external fetch beyond Google Fonts, no build step). Do not rewrite it from a
+text description; read it, fill in real data, and write the result.
 
 1. For each discovered slug, build one entry:
 

package/skills/scope-hammer/SKILL.md

@@ -150,7 +150,7 @@ the harness (this is neither the generator nor the evaluator).
 Orchestrated, this skill is dispatched like every worker: a **WorkOrder** in (`--order <path>`,
 operation `hammer`), 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`):
+(`kernel/schemas/domain.schema.json`, `x-payload-by-worker`):
 
 | Payload field | Standalone flag | Meaning |
 |---|---|---|

package/skills/tech-lead/SKILL.md

@@ -60,15 +60,15 @@ check the lane:
   legacy loop instead — `references/protocol.md` (BUILD(r)/EVAL) + `references/protocol.md`
   carry the full step-by-step for both the tiny lane and a scope-less BUILD loop, verbatim, non-
   regression. Stop reading this file here for that run.
-- **Otherwise** (the common case — a scoped spec, any auto level): build `RunArgs`
-  (`domain.schema.json` `$defs/RunArgs` — `{slug, runId, autoLevel, answers, lane,
-  models:{exec,eval,qa}, budgets:{maxRounds,attemptBudget,wallClockS}, pluginRoot, startedAt}`,
-  plus every switch the operator typed — `references/gates.md` GATE L0.9 has the flag→field table,
-  and a flag that stops here is a flag that was accepted and ignored). **Write that exact object to
-  `.shapeup/<slug>/run-args.json` before launching**, fresh on every launch and relaunch: the flags
-  reach the workflow as a value in memory, so it is the run's only evidence of what it was launched
-  with, and a run that cannot state its own configuration cannot have a claim about it checked.
-  Then launch with the **`Workflow` tool** — naming `init run`'s staged copy, never the install path:
+- **Otherwise** (the common case — a scoped spec, any auto level): resolve every switch the
+  operator typed (`references/gates.md` GATE L0.9b has the flag→field table) and run the kernel's
+  sole `RunArgs` writer: `node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" init run-args --slug
+  <slug> --auto-level <level> --exec-model <n> [--eval-model <n>] [--qa-model <n>] --max-rounds <N>
+  --attempts <N> --plugin-root "${CLAUDE_PLUGIN_ROOT}" [--answers <a>] [--lane <l>] [--no-eval]
+  [--no-qa] [--adversarial-verify] [--parallel-scopes <N>]`. It writes `.shapeup/<slug>/run-args.json`
+  fresh on every launch/relaunch and prints that identical object — **pass it to `Workflow`
+  verbatim, never re-type it**. Then launch with the **`Workflow` tool** — naming `init run`'s
+  staged copy, never the install path:
 
 ```
 Workflow({
@@ -114,7 +114,7 @@ did not actually receive from the PO — an unattended lane with no answer for a
 
 FIRST freeze the evidence — run state is gitignored, so `shapeup/<slug>/REPORT.md` (already
 written by `shapeup-run.js` via `harness reduce ship`, or write it now on a `gate_h` close) is all a
-teammate sees. Then emit:
+teammate sees. Then RESOLVE the gate — `references/gates.md` GATE L4 has the call — and emit:
 
 ```
 ⏸ GATE L4 — Ship Sign-Off

package/skills/tech-lead/references/gates.md

@@ -113,11 +113,13 @@ Collect (explicit — never inferred):
         gate to be its first execution.
 ```
 
-**L0.9b — the launch record.** Every switch the operator typed becomes a `RunArgs` field, or it
-does nothing at all: the workflow cannot read a config file and cannot ask a follow-up, so a flag
-that stops at the skill boundary was accepted and ignored. That is not hypothetical — `--no-qa` was
-documented in seven places across the shipped set and inert in all of them, because no line of this
-protocol ever put `noQa` into the record.
+**L0.9b — the launch record.** Every switch the operator typed to *this launch* becomes a `RunArgs`
+field, or it does nothing at all: the workflow cannot read a config file and cannot ask a follow-up,
+so a flag that stops at the skill boundary was accepted and ignored. That is not hypothetical —
+`--no-qa` was documented in seven places across the shipped set and inert in all of them, because no
+line of this protocol ever put `noQa` into the record. `--wall-clock-budget` is the one flag below
+that is not a `RunArgs` field at all — it is consumed earlier, at `init run` itself, and never
+needed to reach this launch; see its row for where it actually lands.
 
 | Flag | `RunArgs` field |
 |---|---|
@@ -125,14 +127,19 @@ protocol ever put `noQa` into the record.
 | `--no-qa` | `noQa: true` |
 | `--parallel-scopes N` | `maxParallelScopes: N` — how many scopes build at once (default 4; `1` = sequential) |
 | `--adversarial-verify` | `adversarialVerify: true` |
-| `--rounds N` / `--attempts N` / `--wall-clock-budget S` | `budgets.{maxRounds,attemptBudget,wallClockS}` |
+| `--rounds N` / `--attempts N` | `budgets.{maxRounds,attemptBudget}` |
 | `--gate-answers <set>` | `answers` |
+| `--wall-clock-budget S` | *(not a `RunArgs` field)* — typed once, on the `harness init run` command line itself, not on this launch; it lands straight in the run receipt as `wall_clock_budget_s`, and the deadline breaker reads that receipt field directly — consumed by `kernel/verify/budget.mjs` as `wall_clock_budget_s`. `budgets` declares only `maxRounds`/`attemptBudget` — the schema, `SKILL.md`'s own RunArgs contract line and this script's own header comment all agree there is no third member |
 | `--orch-model/--exec-model/--eval-model/--qa-model` | `models.{…}` (L0.8) |
 
-The assembled object is written to `.shapeup/<slug>/run-args.json` before the launch, fresh on every
-launch and relaunch. It is the only artifact that records what a run was configured with; the ship
-report, a resumed session and any later measurement all read it, and none of them can recover a
-value that only ever existed as an argument.
+`harness init run-args` (invoked at Step 2 of `SKILL.md`) is the sole writer of the assembled
+object: it takes the resolved values above, writes `.shapeup/<slug>/run-args.json` fresh on every
+launch and relaunch, and prints the same object back so the launch never re-assembles it by hand. It
+is the only artifact that records what a run was configured with; the ship report, a resumed session
+and any later measurement all read it, and none of them can recover a value that only ever existed
+as an argument. Step 2 is not merely advisory: `shapeup-run.js`'s own Preflight refuses to dispatch
+ORIENT (or anything past it) when this file is missing at the run's local root — a launch that
+skipped this step aborts there rather than proceeding on a silent default.
 
 **L0.0 — intake precondition (before any other L0 collection):**
 ```
@@ -161,7 +168,14 @@ Model matrix : orch=[model] exec=[model] eval=[model] qa=[model] digester=[scrip
 Budgets      : round_budget=[N] (outer)   attempt_budget=[N] (inner, per scope)
 Knowledge    : [tech-lead.md — N workflow rules, M suggested values (confirmed above) | none — `/retro --scan` or `/retro --research <stack>` seeds it (optional)]
 ```
-Do NOT start ORIENT until confirmed (interactive/auto). Under --unattended, proceed.
+**Resolve it** — this gate is this skill's own (the workflow never sees it), so it is this skill
+that runs the same tool every other gate resolves through, not a paragraph read as a stand-in for
+one: `node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" gate --resolve L0 --slug <slug>
+[--file <path>|--preset <name>]`. Exit 4 (`ask`) is the confirmation this block already asks for —
+put it to the PO and wait, same as the paragraph above always meant. Exit 0 (`decision=proceed`) —
+continue straight to ORIENT, which is what `--unattended`'s pre-answered set resolves to. Exit 5
+(`abort`) — stop; do not launch. Either way, the gate's own ledger row is what lets a later reader
+see the decision that opened the run, not only the decisions that closed it.
 
 ---
 
@@ -541,5 +555,28 @@ On confirm:
 - If the PO provides substantive feedback (not just 'y' or empty) → automatically delegate via Agent (model: exec — see references/protocol.md "Invocation mechanism"): Skill(shapeup-sdlc-plugin:coach) with the provided feedback for RLHF. The coach runs its own GATE COACH-1 to have the PO categorize each rule, then files it under the responsible skill in `shapeup/knowledge-base/<skill>.md` (committed → team-shared). Coachable: `task-executor`, `ba-pitch-analyzer`, `qa-edge-hunter`, `orient`, `scope-architect`, `solution-architect` (each reads its own file at the top of its next run) and `tech-lead` (workflow guidance, read at the next GATE L0). Guidance never decides a gate: a filed rule may add a question or a check to a gate block, never an answer. The tech lead does not categorize the feedback itself — that is the coach's gate, by design (no assumptions).
 - Then output → `✅ [slug] [shipped & deployed | built & verified, deploy pending] — [r] rounds, verdict PASS.`
 
+**Resolve the gate itself before any of the above** — this is the decision that shipped the run,
+and without it the trace holds no record of that decision at all: `node
+"${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" gate --resolve L4 --slug <slug>
+[--file <path>|--preset <name>]`. Exit 0 (`decision=ship|hold`) — render the block above and close
+the run: `node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" probe resume --slug <slug> --close shipped
+--cause "verdict=<verdict> rounds=<r> decision=<ship|hold>"`. Always issue this call — a `gate_h`
+close is the ordinary case where `shapeup-run.js` handed off without closing the run, and the
+GATE H → L4 path (scope-hammer's census, then this gate) is the one this instruction exists for.
+The close itself is a once-only fact IN THE KERNEL (`closeRun`'s own guard reads a `closed_status:`
+line that only `closeRun` ever writes — never the mutable `status:` line every phase rewrites, this
+call included), not a conditional this instruction has to get right: if this run_id was NOT already
+closed, this call performs the close, fresh. If it was already closed `shipped` (or `aborted`) and
+the cause text is byte-identical to what is already on the ledger, this call is a true idempotent
+no-op. If it was already closed with the SAME status but a genuinely different cause — a run closed
+more than once across relaunches, the ordinary shape a `gate_h` hand-off after an earlier abort takes
+— this call SUPERSEDES it: the new cause is written, the prior one is folded into the same
+`close_cause` line rather than lost, and the kernel call itself still exits 0 (only the RunReturn a
+launch's own `withWarnings` wraps carries the resulting `state_warning` — a prose-driven close like
+this one has no RunReturn to attach it to, so read `close_cause` by hand if this branch matters to
+you). If it was already closed with a DIFFERENT status altogether, this call is refused outright —
+cause intact, never silently flipped. Exit 4 (`ask`) — the block above IS that stop; put it to the
+PO and wait, same as always. L4's answer set carries no `abort`.
+
 ---
 

package/skills/tech-lead/references/protocol.md

@@ -630,7 +630,7 @@ trace. See `references/gates.md` — GATE L0.1.
 ## Central domain registry
 
 Every record type and payload field that crosses a skill boundary is defined exactly once in
-`skills/tech-lead/schemas/domain.schema.json` — the envelope schemas (`work-order.schema.json`,
+`kernel/schemas/domain.schema.json` — the envelope schemas (`work-order.schema.json`,
 `work-result.schema.json`) only `$ref` it. The registry annotates each entity's tier
 (SHARED/LOCAL), location, sole writer, and readers, carries the machine-readable ERD (`x-erd`),
 and maps which payload fields each worker may rely on (`x-payload-by-worker`).
@@ -686,13 +686,15 @@ lens: lite | standard | cross-context
 eval_dimensions: [spec-conformance]   # the set from GATE L0.5 (init-run --dimensions); every EVAL order is compiled from THIS line
 max_rounds: 3
 auto_level: interactive | auto | unattended
-status: orienting | mapping | building | evaluating | shipped | escalated
+status: orienting | mapping | building | evaluating | shipped | escalated | aborted
 final_verdict: ~ | pass | fail | not-evaluated
 rounds_used: [N]
 discovered_rounds: [N]
 deploy: ~ | deployed | pending-po
 started_at: [ISO]
 closed_at: ~ | [ISO]
+close_cause: ~ | [why the run ended at that terminal status — `probe resume --close` writes this and closed_at together]
+closed_status: ~ | [the terminal status actually closed — written ONLY by `probe resume --close`, never by `--set-status`, so it is immune to `status:` above being rewritten by ordinary phase traffic after the close]
 ---
 ```