shapeup-sdlc 1.6.3 → 1.7.0

package/skills/tech-lead/schemas/domain.schema.json

@@ -3,7 +3,7 @@
   "title": "HarnessDomain",
   "description": "The CENTRAL domain registry of the pure-skill architecture. Every shared field that crosses a skill boundary is defined here exactly once, with its meaning, owner, and storage tier annotated — work-order.schema.json and work-result.schema.json $ref into $defs below instead of re-defining records inline, and no skill may introduce a cross-boundary field that is not registered here first. Annotation keys: x-tier = SHARED (committed under shapeup/, survives clone+crash) | LOCAL (gitignored under .shapeup/, regenerable run-trace) | EMBEDDED (a record type that only lives inside another entity); x-location = the canonical path; x-writer = the single component allowed to write it; x-readers = who consumes it. The x-erd block is the machine-readable entity-relationship map; x-payload-by-worker is the authoritative table of which WorkOrder payload fields each worker may rely on.",
   "x-erd": {
-    "description": "Relationship map. Cardinality reads left-to-right (WorkOrder 1:1 WorkResult = every order has exactly one result). Join keys: <slug> (the feature) is the aggregate root every path is keyed off; scope_id is the STABLE cross-machine key (boards regenerate; hill shards, T0 history and branches join on it); TASK-NNN ids are machine-local and must never be joined across machines (generate-board joins on scope, not task id).",
+    "description": "Relationship map. Cardinality reads left-to-right (WorkOrder 1:1 WorkResult = every order has exactly one result). Join keys: <slug> (the feature) is the aggregate root every path is keyed off; scope_id is the STABLE cross-machine key (boards regenerate; hill shards, T0 history and branches join on it); TASK-NNN ids are machine-local and must never be joined across machines (board regeneration joins on scope, not task id).",
     "relationships": [
       {
         "from": "WorkOrder",
@@ -101,20 +101,6 @@
         "via": "discoveries[]",
         "note": "ingest appends to discovery/ledger.md — three producers (executor +, QA ~, planner overflow), zero direct writers"
       },
-      {
-        "from": "WorkResult",
-        "to": "Escalate",
-        "cardinality": "1:N",
-        "via": "escalates[]",
-        "note": "ingest queues to escalates/<order>.json; advisor-protocol adjudicates into a Decision"
-      },
-      {
-        "from": "Escalate",
-        "to": "Decision",
-        "cardinality": "1:0..1",
-        "via": "advisor-protocol adjudication",
-        "note": "persisted to the committed round-ledger the instant it is answered (zero-memory handoff)"
-      },
       {
         "from": "WorkResult",
         "to": "Verdict",
@@ -181,7 +167,7 @@
         "to": "ScopeContract",
         "cardinality": "1:N",
         "via": "superseded_by[]",
-        "note": "set by split-scope — supersede-never-delete keeps branch and T0 history attributable"
+        "note": "set by map-scopes — supersede-never-delete keeps branch and T0 history attributable"
       },
       {
         "from": "T0Artifact",
@@ -254,15 +240,12 @@
       "spec_folder",
       "feature",
       "discovered_ledger",
-      "kb_rules_path",
-      "requirements"
+      "kb_rules_path"
     ],
     "scope-architect": [
       "feature",
       "spec_folder",
-      "tasks",
-      "discovered_ledger",
-      "scope_id"
+      "tasks"
     ],
     "solution-architect": [
       "feature",
@@ -304,12 +287,6 @@
     ],
     "coach": [
       "feedback"
-    ],
-    "advisor-protocol": [
-      "ledger",
-      "escalate",
-      "scope_id",
-      "round"
     ]
   },
   "x-result-by-worker": {
@@ -317,7 +294,6 @@
     "task-executor": [
       "task_results",
       "files_touched",
-      "escalates",
       "discoveries",
       "artifacts",
       "assumptions",
@@ -332,21 +308,18 @@
     ],
     "ba-pitch-analyzer": [
       "discoveries",
-      "escalates",
       "files_touched",
       "artifacts",
       "assumptions",
       "deviations"
     ],
     "scope-architect": [
-      "escalates",
       "files_touched",
       "artifacts",
       "assumptions",
       "deviations"
     ],
     "solution-architect": [
-      "escalates",
       "files_touched",
       "artifacts",
       "assumptions",
@@ -382,12 +355,6 @@
       "artifacts",
       "assumptions",
       "deviations"
-    ],
-    "advisor-protocol": [
-      "files_touched",
-      "artifacts",
-      "assumptions",
-      "deviations"
     ]
   },
   "$defs": {
@@ -404,34 +371,28 @@
         "qa-edge-hunter",
         "translator",
         "scope-hammer",
-        "coach",
-        "advisor-protocol"
+        "coach"
       ]
     },
     "Operation": {
-      "description": "The full operation vocabulary. Replaces lifecycle flags (--tasks-only, --from-discovered, --remap …): the caller knows the pipeline position; the worker never re-derives it. Ownership: execute/fix/spike = task-executor · analyze/generate-board/reconcile/retrofit-surface/coverage = ba-pitch-analyzer · map-scopes/remap/split-scope = scope-architect · wire = solution-architect · evaluate = spec-evaluator · orient = orient · hunt/recheck = qa-edge-hunter · translate = translator · hammer = scope-hammer · coach = coach · adjudicate = advisor-protocol.",
+      "description": "The full operation vocabulary. Replaces lifecycle flags (--tasks-only, --from-discovered, --map-scopes …): the caller knows the pipeline position; the worker never re-derives it. Ownership: execute/fix/spike = task-executor · analyze/reconcile/retrofit-surface/coverage = ba-pitch-analyzer · map-scopes = scope-architect · wire = solution-architect · evaluate = spec-evaluator · orient = orient · hunt = qa-edge-hunter · translate = translator · hammer = scope-hammer · coach = coach.",
       "type": "string",
       "enum": [
         "execute",
         "fix",
         "spike",
         "analyze",
-        "generate-board",
         "reconcile",
         "retrofit-surface",
         "coverage",
         "map-scopes",
-        "remap",
-        "split-scope",
         "wire",
         "evaluate",
         "orient",
         "hunt",
-        "recheck",
         "translate",
         "hammer",
-        "coach",
-        "adjudicate"
+        "coach"
       ]
     },
     "Substrate": {
@@ -477,7 +438,7 @@
       "properties": {
         "pause_gates": {
           "type": "boolean",
-          "description": "true (standalone default): pause at the worker's phase checkpoints. false: run straight through, surfacing questions as assumptions[]/escalates[]."
+          "description": "true (standalone default): pause at the worker's phase checkpoints. false: run straight through, surfacing questions as assumptions[] — or, when one genuinely blocks, deviations[] with status 'escalated'."
         },
         "max_questions": {
           "type": "integer",
@@ -549,7 +510,7 @@
           "items": {
             "type": "string"
           },
-          "description": "Explicit dependencies. The inverse (unlocks) is ALWAYS derived by board-derive.mjs, never hand-authored (KB-BA-001)."
+          "description": "Explicit dependencies. The inverse (unlocks) is ALWAYS derived by board-derive.mjs, never hand-authored — hand-authored inverses drift asymmetric, observed repeatedly."
         },
         "use_case_refs": {
           "type": "array",
@@ -564,7 +525,7 @@
       "description": "One adjudicated ESCALATE answer as carried inside a WorkOrder — binding precedent the worker must apply. Compiled from the committed round-ledger.md Decisions table (columns: Round | Scope | Kind | Question | Answer | Resolved by) filtered to this scope. The full row lives in the ledger; the envelope carries the minimal {id, answer} projection.",
       "x-tier": "EMBEDDED (projection of the SHARED round-ledger.md Decisions row)",
       "x-location": ".shapeup/<slug>/round-ledger.md",
-      "x-writer": "advisor-protocol (via tech-lead) — promoted the instant an answer is given",
+      "x-writer": "tech-lead — promoted the instant the PO gives an answer",
       "type": "object",
       "required": [
         "id",
@@ -732,14 +693,14 @@
             "DOWNHILL_EXECUTION",
             "FINISHED"
           ],
-          "description": "ALWAYS authored as UPHILL_UNKNOWN (DD-10). The live phase is DERIVED from T0/T1/seesaw facts into hill/<scope-id>.yml — facts move dots, not authors."
+          "description": "ALWAYS authored as UPHILL_UNKNOWN — self-reported confidence is the risk this closes. The live phase is DERIVED from T0/T1/seesaw facts into hill/<scope-id>.yml — facts move dots, not authors."
         },
         "superseded_by": {
           "type": "array",
           "items": {
             "type": "string"
           },
-          "description": "Set by split-scope: the replacing scope ids. Supersede-never-delete."
+          "description": "Set by map-scopes: the replacing scope ids. Supersede-never-delete."
         },
         "business_goal": {
           "type": "string",
@@ -831,87 +792,12 @@
         }
       }
     },
-    "Escalate": {
-      "description": "The worker's ONE outward port: a decision it cannot make alone. Ingest queues these to escalates/<order>.json; advisor-protocol adjudicates (budget ≤3/scope/round) and the answer returns as a Decision in the next order. The advisor-side grammar adds scope_id/round/attempt/options/default_if_silent (see EscalateBlock).",
-      "x-tier": "EMBEDDED",
-      "type": "object",
-      "required": [
-        "kind",
-        "question"
-      ],
-      "properties": {
-        "kind": {
-          "type": "string",
-          "enum": [
-            "design-decision",
-            "spec-ambiguity",
-            "substrate-expansion"
-          ],
-          "description": "Three kinds, three resolution paths: design/spec go to the PO (or default_if_silent unattended); substrate-expansion is NEVER silently approved — it routes to a scope-architect remap order."
-        },
-        "question": {
-          "type": "string",
-          "description": "One checkable question."
-        },
-        "blocked_ac": {
-          "type": "string",
-          "description": "Which AC waits on this — work on unrelated ACs continues."
-        },
-        "context": {
-          "type": "string",
-          "description": "The two interpretations / the file and why it's needed."
-        }
-      }
-    },
-    "EscalateBlock": {
-      "description": "The advisor-protocol adjudication grammar — an Escalate enriched with run coordinates and options, as passed to /advisor-protocol --escalate. The answer is persisted to the committed round-ledger.md Decisions table the instant it's given (zero-memory handoff: escalation memory lives in files, not chat).",
-      "x-tier": "EMBEDDED",
-      "x-readers": "advisor-protocol",
-      "type": "object",
-      "required": [
-        "kind",
-        "question"
-      ],
-      "properties": {
-        "scope_id": {
-          "type": "string"
-        },
-        "round": {
-          "type": "integer"
-        },
-        "attempt": {
-          "type": "integer"
-        },
-        "kind": {
-          "type": "string",
-          "enum": [
-            "design-decision",
-            "spec-ambiguity",
-            "substrate-expansion"
-          ]
-        },
-        "question": {
-          "type": "string"
-        },
-        "options": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Proposed answers, each with its rationale."
-        },
-        "default_if_silent": {
-          "type": "string",
-          "description": "Optional low-risk fallback — applied under --unattended (logged + flagged for GATE H); the advisor is never forced to accept it."
-        }
-      }
-    },
     "Discovery": {
       "description": "The universal currency of surprise: one raw discovered line. Producers: task-executor (marker +, P3.7), qa-edge-hunter (always ~, repro required), ba-pitch-analyzer (overflow reports). NO producer writes the ledger — ingest-result appends every entry to discovery/ledger.md (single-writer, mechanically). Promotion ~ → must-have is always a human act at SHIP S.0/GATE H.",
       "x-tier": "EMBEDDED (projection into the LOCAL discovery ledger)",
       "x-location": ".shapeup/<slug>/discovery/ledger.md",
       "x-writer": "ingest-result.mjs",
-      "x-readers": "ba-pitch-analyzer (reconcile), scope-architect (remap), scope-hammer (census), qa-edge-hunter (covered-territory context)",
+      "x-readers": "ba-pitch-analyzer (reconcile), scope-architect (map-scopes), scope-hammer (census), qa-edge-hunter (covered-territory context)",
       "type": "object",
       "required": [
         "marker",
@@ -961,7 +847,7 @@
       }
     },
     "T0Citation": {
-      "description": "The judge's pointer to a mechanical T0 artifact. The evaluator RECOMPUTES sha256 from disk — a handed hash is never trusted; a verdict on a scoped spec without a citation is structurally invalid (PA4/DD-7: T0 is a machine fact the generator cannot fabricate).",
+      "description": "The judge's pointer to a mechanical T0 artifact. The evaluator RECOMPUTES sha256 from disk — a handed hash is never trusted; a verdict on a scoped spec without a citation is structurally invalid: T0 is a machine fact the generator cannot fabricate.",
       "x-tier": "EMBEDDED",
       "type": "object",
       "required": [
@@ -1071,7 +957,7 @@
             "evidence": {
               "type": "string",
               "pattern": "[\\w./\\-]+:[0-9]+",
-              "description": "A FAIL must carry a file:line locator. Was stated 5x in spec-evaluator/SKILL.md prose and enforced 0x; a measured run returned a correct FAIL verdict with bugs[] null and no locator anywhere, so the finding could not be acted on without re-investigating. Now mechanical: validate-envelope rejects it before ingest."
+              "description": "A FAIL must carry a file:line locator. The rule used to live in prose and be enforced nowhere — a correct FAIL verdict with no locator anywhere is unactionable without re-investigating (observed, not theorized). Now mechanical: the ingest-side schema validation rejects it before any write."
             },
             "traces_to": {
               "type": "array",
@@ -1390,7 +1276,7 @@
       ]
     },
     "SeesawRegistry": {
-      "description": "The fixture registry of every FINISHED scope — what seesawCheck re-runs on each later attempt so a new scope cannot silently break a shipped one (PA5).",
+      "description": "The fixture registry of every FINISHED scope — what seesawCheck re-runs on each later attempt so a new scope cannot silently break a shipped one — a regression mistaken for progress is the pathology the seesaw exists for.",
       "x-tier": "LOCAL",
       "x-location": ".shapeup/<slug>/seesaw/registry.json",
       "x-writer": "tech-lead (when a scope reaches FINISHED)",
@@ -1460,10 +1346,10 @@
       }
     },
     "HillShard": {
-      "description": "One scope's hill position — DERIVED, never self-reported (DD-10): UPHILL_UNKNOWN (open unknowns > 0) → UPHILL_SOLVED (unknowns 0, no T0-green yet) → DOWNHILL_EXECUTION (≥1 T0-green; T1/seesaw pending) → FINISHED (T1 PASS ∧ seesaw green ∧ merged). Single-writer = whoever holds that scope's branch. Progress is reported by hill position, never task counts.",
+      "description": "One scope's hill position — DERIVED, never self-reported: UPHILL_UNKNOWN (open unknowns > 0) → UPHILL_SOLVED (unknowns 0, no T0-green yet) → DOWNHILL_EXECUTION (≥1 T0-green; T1/seesaw pending) → FINISHED (T1 PASS ∧ seesaw green ∧ merged). Single-writer = whoever holds that scope's branch. Progress is reported by hill position, never task counts.",
       "x-tier": "SHARED",
       "x-location": "shapeup/<slug>/hill/<scope-id>.yml",
-      "x-writer": "tech-lead (GATE L2.4 derivation)",
+      "x-writer": "tech-lead (GATE L2 derivation)",
       "x-readers": "tech-lead (GATE L3 hill report), scope-hammer (census), GATE L1b sequencing",
       "type": "object",
       "properties": {
@@ -1486,7 +1372,7 @@
       "x-tier": "SHARED",
       "x-location": ".shapeup/metrics/<machine-id>.jsonl",
       "x-writer": "tech-lead (SHIP S.6)",
-      "x-readers": "tier-3 e2e benchmark tooling, stats.mjs (read-only projection)",
+      "x-readers": "tier-3 e2e tooling, stats.mjs (read-only projection)",
       "type": "object",
       "properties": {
         "schema_version": {
@@ -1755,9 +1641,6 @@
             }
           }
         },
-        "open_escalates": {
-          "type": "integer"
-        },
         "pending_orders": {
           "type": "array",
           "items": {
@@ -1923,8 +1806,8 @@
       }
     },
     "Lane": {
-      "description": "v1.2 DESIGN DRAFT — reserves the name and makes the policy reviewable; no envelope references it yet and no runtime reads it. See docs/design/04-functional-design.md §4.7. When implemented, the lane is pipeline knowledge: the orchestrator compiles it away into existing registered knobs (payload.lens, payload.dimensions, interaction gate policy) — it NEVER rides in WorkOrderPayload, so workers stay pipeline-blind.",
-      "x-tier": "EMBEDDED (when implemented: recorded in harness-run.md frontmatter `lane:` — never a WorkOrderPayload field)",
+      "description": "The run's lane (full|tiny), computed by fit-check.mjs at GATE L0.3 and recorded in harness-run.md frontmatter `lane:` (with its evidence, and marked overridden when --lane/--tiny outranks the recommendation); RunArgs.lane carries it to the workflow launch. The lane is pipeline knowledge: the orchestrator compiles it away into existing registered knobs (lens, budgets, gate policy) — it NEVER rides in WorkOrderPayload, so workers stay pipeline-blind.",
+      "x-tier": "EMBEDDED (recorded in harness-run.md frontmatter `lane:` — never a WorkOrderPayload field)",
       "x-writer": "tech-lead (GATE L0 lane selection)",
       "x-readers": "tech-lead only",
       "x-lane-policy": {
@@ -1970,7 +1853,7 @@
       ]
     },
     "RequirementClause": {
-      "description": "One atomic customer requirement, frozen with a STABLE id — the covers-closure input truth (spine v1.3). Extracted from the REQ source (Open Decision A: pitch / customer-requirements doc / use-case bodies) by ba-pitch-analyzer's `coverage` operation; extraction is judgment (LLM), but ids are assigned ONCE and never renumber (they behave like scope_id, not TASK-NNN — every covers: link would rot otherwise). Supersede-never-delete: a dropped clause is marked CUT (PO-approved), never removed, so the registry stays auditable on a fresh clone. The original REQ source is never edited — the registry is a separate derived, committed file.",
+      "description": "One atomic customer requirement, frozen with a STABLE id — the covers-closure input truth (spine v1.3). Extracted from the REQ source (pitch / customer-requirements doc / use-case bodies) by the planner — extraction is judgment (LLM), but ids are assigned ONCE and never renumber (they behave like scope_id, not TASK-NNN — every covers: link would rot otherwise). Supersede-never-delete: a dropped clause is marked CUT (PO-approved), never removed, so the registry stays auditable on a fresh clone. The original REQ source is never edited — the registry is a separate derived, committed file.",
       "x-tier": "SHARED",
       "x-location": "shapeup/<slug>/requirements.md",
       "x-writer": "ba-pitch-analyzer (operation: coverage) — extraction only; CUT status is a PO governance edit (same class as a round-ledger Decision)",
@@ -2200,11 +2083,11 @@
         },
         "discovered_ledger": {
           "type": "string",
-          "description": "ba-pitch-analyzer (reconcile) / scope-architect (remap): the discovery ledger path whose raw [+]/~ lines get folded in."
+          "description": "ba-pitch-analyzer (reconcile) / scope-architect (map-scopes): the discovery ledger path whose raw [+]/~ lines get folded in."
         },
         "requirements": {
           "type": "string",
-          "description": "ba-pitch-analyzer (operation: coverage): the REQ source to extract atomic clauses from (Open Decision A — pitch / customer-requirements doc / use-case bodies). Absent → the planner defaults to the pitch and records the choice in assumptions[]. The written registry lands at shapeup/<slug>/requirements.md (RequirementClause rows)."
+          "description": "ba-pitch-analyzer: the REQ source to extract atomic clauses from (Open Decision A — pitch / customer-requirements doc / use-case bodies). Absent → the planner defaults to the pitch and records the choice in assumptions[]. The written registry lands at shapeup/<slug>/requirements.md (RequirementClause rows)."
         },
         "project_profile": {
           "type": "string",
@@ -2212,7 +2095,7 @@
         },
         "scope_id": {
           "type": "string",
-          "description": "scope-architect (split-scope): the stuck scope · scope-hammer (--breaker inner): the exhausted scope · advisor-protocol: budget scope."
+          "description": "scope-architect (map-scopes): the stuck scope · scope-hammer (--breaker inner): the exhausted scope."
         },
         "dimensions": {
           "type": "array",
@@ -2251,15 +2134,11 @@
         },
         "ledger": {
           "type": "string",
-          "description": "qa-edge-hunter: discovery ledger path (READ-ONLY context) · advisor-protocol: the committed round-ledger.md decisions persist to."
-        },
-        "escalate": {
-          "$ref": "#/$defs/EscalateBlock",
-          "description": "advisor-protocol: the worker's ESCALATE block to adjudicate."
+          "description": "qa-edge-hunter: discovery ledger path (READ-ONLY context)."
         },
         "round": {
           "type": "integer",
-          "description": "advisor-protocol: the round the budget/decision is counted against."
+          "description": "the round this order is counted against."
         },
         "baseline": {
           "type": "string",
@@ -2289,6 +2168,299 @@
           "description": "translator: existing glossary.md to reuse as the base term map."
         }
       }
+    },
+    "ResumeState": {
+      "description": "The fast-forward derivation: which phase a launch resumes at, derived from artifacts on disk and NEVER from stored state or conversation memory. Produced by skills/tech-lead/scripts/resume-state.mjs on stdout and consumed by shapeup-run.js's preamble on every launch, fresh or relaunch alike. Every phase predicate is an artifact test — `has_orient_artifacts` exists because the ORIENT branch was once gated on the ledger's stored `status` instead, which a silent courier failure left stale, and a completed ORIENT phase was re-dispatched on resume. `next_phase` is a convenience derived from the same booleans, which all travel too: a caller is never forced to trust a summary it cannot re-derive.",
+      "x-tier": "EMBEDDED",
+      "x-location": "stdout of resume-state.mjs — never written to disk (the run's state IS the artifacts this record reports on)",
+      "x-writer": "resume-state.mjs (deriving; the same script's --set-status / --set-active-scope operations write, and report their own outcome record instead)",
+      "x-readers": "shapeup-run.js (the fast-forward preamble, one call per launch)",
+      "type": "object",
+      "required": [
+        "intake_path",
+        "status",
+        "has_orient_artifacts",
+        "has_spec_tree",
+        "has_wiring_map",
+        "scope_files",
+        "pending_orders",
+        "eval_rounds_done",
+        "next_phase"
+      ],
+      "properties": {
+        "intake_path": {
+          "type": "string",
+          "description": "Resolved path to the run's intake — the pitch a fresh ORIENT dispatch is compiled against."
+        },
+        "spec_folder": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "From harness-run.md frontmatter; null before the ledger names one."
+        },
+        "status": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The ledger's stored status, reported for the readers that legitimately hold a MID_RUN set over it (run-snapshot.mjs, hooks/anti-rationalization.mjs). NOT a resume predicate: no phase decision in shapeup-run.js may branch on this field."
+        },
+        "has_orient_artifacts": {
+          "type": "boolean",
+          "description": "ORIENT finished: orient/ carries code-surface.md, discovered-seed.md, hill-signal.md and at least one spike-*.md (skills/orient/SKILL.md §Outputs). The ORIENT skip gates on THIS."
+        },
+        "has_spec_tree": {
+          "type": "boolean",
+          "description": "ANALYZE finished: the spec folder's usecases/ carries at least one use case that is not _index.md. WIRE reads these — one wiring-map entry per use case — which is why ANALYZE precedes WIRE in the phase chain: dispatched against an empty spec folder, WIRE escalates on every launch."
+        },
+        "has_wiring_map": {
+          "type": "boolean",
+          "description": "WIRE finished: shapeup/<slug>/wiring-map.md exists."
+        },
+        "project_profile_path": {
+          "type": "string"
+        },
+        "has_project_profile": {
+          "type": "boolean",
+          "description": "tech-lead writes project-profile.md at GATE L0, before the launch; trace-lint resolves reachability by its archetype."
+        },
+        "scope_files": {
+          "type": "array",
+          "description": "MAP SCOPES finished when non-empty. Each entry carries a RESOLVED path, never a bare filename — compile-order.mjs and t0-verify.mjs resolve --scope against cwd, and a bare id makes compile-order exit 2, which the attempt loop reads as the stagnation breaker.",
+          "items": {
+            "type": "object",
+            "required": [
+              "scope_id",
+              "path"
+            ],
+            "properties": {
+              "scope_id": {
+                "type": "string"
+              },
+              "path": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "pending_orders": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Order files with no result beside them. Diagnostic only — build orders carry no scope id, so this set is not an audit trail of build dispatches (see compile-order.mjs's order-id note)."
+        },
+        "eval_rounds_done": {
+          "type": "array",
+          "items": {
+            "type": "integer"
+          },
+          "description": "Round numbers with an evaluate-r<n>.json result — the resumed run's round counter starts one past the maximum."
+        },
+        "next_phase": {
+          "type": "string",
+          "enum": [
+            "orient",
+            "analyze",
+            "wire",
+            "map-scopes",
+            "build"
+          ],
+          "description": "The first phase whose artifacts are incomplete. Derived from the booleans above, in that order. The same table (resume-state.mjs PHASE_ARTIFACT) answers `--require <phase>`, the post-condition shapeup-run.js checks after every phase dispatch — resume and completion are ONE predicate by construction."
+        }
+      }
+    },
+    "RunArgs": {
+      "description": "C1 — the launch half of the workflow's only conversation. Compiled ONCE by tech-lead at GATE L0 from init-run.mjs output + the L0.8 model matrix + budgets, written to .shapeup/<slug>/run-args.json and handed to the run-workflow.mjs 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.",
+      "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-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",
+      "required": [
+        "slug",
+        "autoLevel",
+        "models",
+        "budgets",
+        "pluginRoot",
+        "startedAt"
+      ],
+      "properties": {
+        "slug": {
+          "type": "string",
+          "description": "The feature slug this run builds — the aggregate root every path is keyed off."
+        },
+        "autoLevel": {
+          "type": "string",
+          "enum": [
+            "interactive",
+            "auto",
+            "unattended"
+          ],
+          "description": "Resolved once at GATE L0; governs which gates pre-approve and what on_missing does (gate-answers.mjs)."
+        },
+        "answers": {
+          "type": "string",
+          "description": "A gate-answers preset name (ci|guarded|interactive) or a path to a gate-answers.json file — the ONLY thing that decides whether a gate crosses, pauses, or aborts."
+        },
+        "models": {
+          "type": "object",
+          "description": "The L0.8 role -> model matrix, resolved once. The model floor: sonnet or above on every role, including mechanical couriers — no exceptions.",
+          "properties": {
+            "exec": {
+              "type": "string"
+            },
+            "eval": {
+              "type": "string"
+            },
+            "qa": {
+              "type": "string"
+            }
+          }
+        },
+        "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.",
+          "properties": {
+            "maxRounds": {
+              "type": "integer"
+            },
+            "attemptBudget": {
+              "type": "integer"
+            },
+            "wallClockS": {
+              "type": "integer"
+            }
+          }
+        },
+        "pluginRoot": {
+          "type": "string",
+          "description": "${CLAUDE_PLUGIN_ROOT} — the only thing a workflow script may ever root a path in (a workflow has no filesystem of its own; every path it resolves is either rooted here or produced by a prior call's stdout)."
+        },
+        "startedAt": {
+          "type": "string",
+          "description": "ISO timestamp, passed in because Date.now() is unavailable inside a workflow script by design — the deadline breaker (budget-check.mjs) computes elapsed time itself, in Node, where the clock lives."
+        },
+        "lane": {
+          "$ref": "#/$defs/Lane",
+          "description": "The fit-check verdict (full|tiny) — compiles away into existing knobs; never rides in WorkOrderPayload."
+        },
+        "noEval": {
+          "type": "boolean",
+          "description": "If true, skips the EVAL phase completely. Rides here rather than in the ledger because there is no frontmatter line that carries it — contrast eval_dimensions, which does."
+        }
+      }
+    },
+    "RunReturn": {
+      "description": "C1 — the return half of the workflow's only conversation. The ONLY way the workflow speaks back to tech-lead, so it is a tagged union keyed on `status` — the skill branches on the tag, never on prose (the same exit-code discipline gate-answers.mjs already applies to gate sign-off, extended to the orchestrator's own return value). A gate resolved 'ask' (exit 4) always returns `paused`; a gate resolved 'abort' (exit 5) always returns `aborted`; any circuit breaker tripping (outer round_budget, inner attempt_budget, or the deadline breaker) returns `gate_h`; a full run whose final EVAL passes returns `shipped`. The union is written as a superset of what one inner round can itself produce (`paused`, `aborted`, `gate_h`, or a round-complete carrying a verdict) — `shipped` belongs only to a full run. It is deliberately NOT narrowed, because the round-scoped subset is what a `workflow()` child would return if the fan-out this design anticipates ever spends that nesting level.",
+      "x-tier": "EMBEDDED",
+      "x-location": "in-memory only — a Workflow return value, never written to disk",
+      "x-writer": "the workflow runtime (shapeup-run — the sole writer)",
+      "x-readers": "tech-lead (branches on `status`, emits `block` verbatim on a pause, never re-summarizes it)",
+      "type": "object",
+      "required": [
+        "status"
+      ],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "shipped",
+            "paused",
+            "aborted",
+            "gate_h",
+            "ok"
+          ],
+          "description": "shipped = the happy ending (outer run only) · paused = a gate resolved 'ask', relaunch after a recorded decision · aborted = a gate resolved 'abort', attributable stop · gate_h = a circuit breaker tripped, ship what is green · ok = one inner round completed (build+eval), not itself a ship — the outer loop decides whether to loop again."
+        },
+        "verdict": {
+          "type": "string",
+          "enum": [
+            "pass",
+            "fail"
+          ],
+          "description": "shipped | ok: the round or run's EVAL verdict, lowercased from spec-evaluator's PASS|FAIL."
+        },
+        "rounds_used": {
+          "type": "integer"
+        },
+        "dims_not_evaluated": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "qa_findings": {
+          "type": "integer"
+        },
+        "report": {
+          "type": "string",
+          "description": "shipped: shapeup/<slug>/REPORT.md path."
+        },
+        "state_warnings": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "shipped | gate_h: bookkeeping writes that did not take (a ledger status that read back wrong), carried on the ONE channel a headless launch preserves. The workflow's own log() goes to the progress narrator and `claude -p` stdout carries only the final message, so a run that returned `shipped` over a ledger still reading `evaluating` could not be told from one that warned about it. Absent when every state write took. Diagnostic, never a status: a lost bookkeeping write is a degraded digest, not a corrupted build."
+        },
+        "round": {
+          "type": "integer",
+          "description": "ok: which round this return describes."
+        },
+        "paused_at": {
+          "type": "string",
+          "description": "paused: the gate id that resolved 'ask' (e.g. L1b, L2, L3)."
+        },
+        "block": {
+          "type": "string",
+          "description": "paused: the ⏸ gate block, emitted VERBATIM by the skill — the block is the handoff contract; re-phrasing it is the paraphrase channel this design exists to close."
+        },
+        "valid_decisions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "paused: the decisions VALID_BY_GATE allows at this gate (gate-answers.mjs)."
+        },
+        "context": {
+          "type": "object",
+          "description": "paused: whatever facts the paused gate needs the PO to see (round, scope counts, spec_lint status, …)."
+        },
+        "aborted_at": {
+          "type": "string",
+          "description": "aborted: the gate id that resolved 'abort'."
+        },
+        "reason": {
+          "type": "string",
+          "description": "aborted: the attributable reason (gate-answers.mjs's own `reason` field, carried through verbatim)."
+        },
+        "breaker": {
+          "type": "string",
+          "enum": [
+            "outer",
+            "inner",
+            "deadline"
+          ],
+          "description": "gate_h: which of the three breakers fired (AGENTS.md's three-level circuit breaker)."
+        },
+        "hammer_proposals": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "gate_h | ok: scope ids queued for GATE H's census (scope-hammer) — an exhausted scope never blocks the round, it proposes."
+        },
+        "green_scopes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "gate_h | ok: scope ids that reached T0-green this round."
+        }
+      }
     }
   }
 }