shapeup-sdlc 1.6.2

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

@@ -0,0 +1,45 @@
+# Tech-Lead Invocation
+
+Invocation examples and the complete flag table, extracted from `SKILL.md` (progressive
+disclosure). Read this when you need the exact CLI shape or a flag's effect.
+
+---
+
+## Invocation
+
+```bash
+# Full build run from a kicked-off pitch, interactive (pause at every L-gate)
+/tech-lead --pitch shapeup/checkout-vnpay/shaping/shaping.md --spec shapeup/checkout-vnpay/spec/ --lens standard
+
+# Sub-skills unattended, tech lead pauses only at orient / plan / verdict / ship
+/tech-lead --pitch ... --spec ... --auto
+
+# Headless for CI (Agent SDK): auto-confirm all gates, stop on PASS / max_rounds / error
+/tech-lead --pitch ... --spec ... --unattended --max-rounds 3
+
+# Resume an existing run — start from a build-phase step
+/tech-lead --spec shapeup/checkout-vnpay/spec/ --from build
+
+# Skip evaluation for a trivial feature (tech-lead judgment / PO override)
+/tech-lead --pitch ... --spec ... --no-eval
+```
+
+### Flags
+| Flag | Effect |
+|------|--------|
+| `--pitch <path>` | Kicked-off pitch (shaped + bet by PO) — input to ORIENT then MAP SCOPES |
+| `--spec <path>` | Spec folder (orient/ + planner output + ledger location) |
+| `--lens lite\|standard\|cross-context` | Passed to ba-pitch-analyzer at step 8 |
+| `--auto` | Sub-skills run unattended; tech lead pauses at L1a/L1b/L3/L4 |
+| `--unattended` | Auto-confirm all L-gates (headless / CI) |
+| `--max-rounds N` | BUILD→EVAL cycles before escalating (default 3) — the OUTER breaker |
+| `--attempts N` | Per-scope T0 attempts before queuing a GATE H hammer proposal (default 5) — the INNER breaker; no-op on specs without scope contracts |
+| `--orch-model / --exec-model / --eval-model / --qa-model <name>` | Override L0.8's resolved model matrix for this run only (highest precedence) |
+| `--from orient\|plan\|build\|eval` | Resume an in-progress run at a build-phase step |
+| `--no-eval` | Skip the evaluation pass this run (trivial feature) |
+| `--no-qa` | Skip the post-PASS /qa-edge-hunter pass (ledger records `qa: skipped`) |
+| `--tiny` | The small-change lane: orient (light) → single-task board → build → T0 → done. Implies `--no-eval --no-qa`, skips WIRE and scope contracts, collapses the gates to L0 + L4. See "The tiny lane" in SKILL.md — the L0 fit-check is mandatory and the ledger records `lane: tiny` |
+| `--dimensions <list>` | Eval dimensions (default spec-conformance) |
+
+---
+

package/skills/tech-lead/references/ledger-schema.md

@@ -0,0 +1,214 @@
+# Ledger Schema — `harness-run.md`
+
+The tech lead's run record. One per feature, lives in the LOCAL run-trace root
+`.shapeup/<slug>/harness-run.md` (hidden, gitignorable — it is ephemeral run-state,
+not a shared deliverable). It is the structured
+artifact that carries state across rounds and across sessions (so `--from` can resume), and
+the PO's audit of how the feature was built.
+
+**The tech lead is the sole writer of this file** (redesign doc D6). It is the authoritative
+run-state for the whole build phase — rounds, gate decisions, Hill positions, verdicts,
+`discovered_rounds`, config, language record. Workers never write here; the tech lead passes
+them what they need (`feature`, `spec`, `stack`, `discovered_rounds`) as args. The board
+(`tasks/_index.md`) remains the planner/generator's execution truth that the tech lead reads.
+
+## Frontmatter
+```yaml
+---
+type: harness-run
+feature: [slug]
+spec_folder: [path to SHARED spec deliverable, e.g. shapeup/<slug>/spec/]
+lens: lite | standard | cross-context
+eval_dimensions: [spec-conformance]
+max_rounds: 3
+auto_level: interactive | auto | unattended
+status: orienting | mapping | building | evaluating | shipped | escalated
+final_verdict: ~ | pass | fail | not-evaluated
+rounds_used: [N]
+discovered_rounds: [N]
+deploy: ~ | deployed | pending-po
+started_at: [ISO]
+closed_at: ~ | [ISO]
+---
+```
+
+## Round table (the spine)
+Mirrors the long-running harness cost table — one row per phase, so you can see where time
+and tokens go and that EVAL is cheap relative to BUILD.
+
+```
+## Rounds
+| Phase            | Round | Result            | Duration | Notes |
+|------------------|-------|-------------------|----------|-------|
+| Orient           | —     | spiked VNPay seam | 18 min   | spike resolved; 9 discovered tasks seeded |
+| Map Scopes       | —     | 14 tasks, 5 layers| 5 min    | orient-informed; 1 SPIKE (VNPay) |
+| Build            | 1     | 14/14 ✅          | 2 h 10 m | all tasks closed |
+| Eval             | 1     | FAIL — 3 bugs     | 9 min    | EVAL-FEATURE-checkout-vnpay.md |
+| Build            | 2     | 3 bugs fixed      | 22 min   | bug-only re-build |
+| Eval             | 2     | PASS              | 8 min    | verdict pass |
+| Ship             | —     | built & verified  | —        | dims: spec-conformance; deploy pending (PO) |
+```
+
+## Hill report (the progress narrative — NOT task counts)
+The roadmap forbids reporting progress by counting tasks: a 90%-done slice can still be stuck
+uphill on the one unknown that matters. So the tech lead reports each slice's **position on
+the hill**, derived mechanically from open unknowns. Render it at every round boundary
+(area-level at GATE L1a — before slices exist; slice-level from GATE L1b onward).
+
+```
+## Hill — round 1
+| Slice        | Position    | Derived from |
+|--------------|-------------|--------------|
+| S1-spine     | 🔽 downhill | spike closed + spine render-AC passed (crest crossed); 2 known tasks left |
+| S2-filters   | 🔼 uphill   | SPIKE-003 open: pagination approach unproven |
+| S3-export    | 🔼 uphill   | contract ⏳ TBD: file-format field |
+```
+
+Position triggers:
+- 🔼 **Uphill** — open SPIKE / `⏳ TBD` contract / unresolved discovered task / approach unproven.
+- ⛰️ **Crest** — all unknowns resolved AND a concrete board fact (the spine slice's render-AC passes).
+- 🔽 **Downhill** — only known work remains, no open unknowns.
+- ✅ **Done** — slice clickable-done.
+
+Source: `orient/hill-signal.md` (area-level, at L1a) then the board + open SPIKE/contract state
+(slice-level, L1b onward). If slice IDs aren't on the board yet (D3 deferred), report at
+task-group level and note the fallback here.
+
+## Decisions log
+Every L-gate decision, for traceability.
+```
+## Decisions
+- GATE L1a: Orient accepted; spiked VNPay seam (resolved); S2-filters flagged uphill.
+- GATE L1b: PO accepted board; cut "guest checkout" task to phase 2.
+- GATE L2 (r1): board green; ran eval (feature not trivial).
+- GATE L3 (r1): FAIL → approved bug-only round 2.
+- GATE L3 (r2): PASS → ship.
+- GATE L4: built & verified; deploy pending (PO); closed.
+```
+
+## Bug carry-over (when FAIL)
+Links the current round's bug list so the next BUILD round has its worklist.
+```
+## Open bugs (round 1 → fix in round 2)
+→ see evaluation/EVAL-FEATURE-checkout-vnpay.md
+- BUG-1 critical SC-DONE-WHEN apps/web/checkout/Pay.tsx:84
+- BUG-2 major   SC-ERR     apps/api/payments/handler.ts:51
+- BUG-3 minor   SC-NONGO   apps/api/shared/auth.ts:12
+```
+
+## Escalation block (only if max_rounds hit without PASS)
+```
+## Escalation
+Rounds used: 3/3 — still FAIL. Residual bugs: [N].
+Recommendation: [cut scope of feature X | accept minor bugs | extend max_rounds with PO approval].
+Decision owner: PO.
+```
+
+## Rules
+- The ledger is append-mostly: each round adds rows, never rewrites history.
+- `status` + `final_verdict` are the resume anchors for `--from`.
+- A `not-evaluated` final verdict (from `--no-eval`) is recorded plainly — never silently
+  upgraded to `pass`.
+
+---
+
+## `round-ledger.md` (committed, Tier A — scope contracts only)
+
+Lives at `shapeup/<slug>/round-ledger.md` (SHARED root, tracked). Not a replacement
+for `harness-run.md` — a small, committed **subset** of it: the two things that must survive
+a `.shapeup/` wipe or a crash (design spec addendum §F.3). Absent on specs with no scope
+contracts; `harness-run.md`'s existing Decisions log stays the only ledger there.
+
+```yaml
+---
+type: round-ledger
+feature: [slug]
+models:                          # L0.8 resolved matrix, recorded once, source noted
+  orch: [model] (source: flags|settings.local|settings.json|default)
+  exec: [model] (source: ...)
+  eval: [model] (source: ...)
+  qa:   [model] (source: ...)
+  digester: script | sonnet
+budgets:
+  round_budget: [N]              # outer breaker
+  attempt_budget: [N]            # inner breaker, per scope
+---
+```
+
+```
+## Decisions
+| Round | Scope | Kind | Question | Answer | Resolved by |
+|-------|-------|------|----------|--------|-------------|
+| 2 | cart-creation | design-decision | cart-total rounding | round half-up | PO (interactive) |
+| 2 | cart-creation | substrate-expansion | needs packages/shared/http.ts | approved → shared_substrate | PO (interactive) |
+```
+**Promotion timing:** a row is appended the INSTANT `advisor-protocol` resolves an ESCALATE —
+never batched to round close. This is the file `task-executor`'s isolated briefs read back
+(zero-memory handoff, DD-8): an answer given once in round 2 must still be known in round 5's
+fresh-context attempt without replaying any chat history.
+
+---
+
+## Harvest row — `metrics/<machine-id>.jsonl` (written at SHIP)
+
+`harness-run.md` is ephemeral run-state — needed live for `--from` resume, the
+FAIL-loop, and QA reconcile; worthless after ship. At SHIP the tech-lead **harvests**
+the durable-mineable *signals* out of it into one append-only row:
+
+```
+shapeup/metrics/<machine-id>.jsonl   # one row = one e2e run; COMMITTED (tracked)
+```
+
+Path note: the per-slug local run dirs `.shapeup/[slug]/` are gitignored wholesale
+(`.shapeup/`), but `metrics/` lives under the **shared** workspace
+`shapeup/` and stays **tracked** — it is the committed report surface, the
+durable signal feed that survives the gitignored run-trace. Sharded per machine (addendum
+Δ3) so concurrent runs append without merge-conflicting on one file; an aggregate view is
+`cat shapeup/metrics/*.jsonl`. `schema_version` makes a v2.1 row readable by later
+skill versions.
+
+### Two hard rules (same discipline as the Test Surface: *derived, never invented*)
+1. **Harvest only fields that already exist as structured output at ship time.** If a
+   field forces the tech-lead to *evaluate something new* → reject (judgment in disguise).
+2. **Harvest records facts, never computes a new verdict.** A self-computed
+   `run_quality_score` would be a second judge behind `spec-evaluator` → breaks the
+   single-judge rule and invites Goodhart. The eval suite *interprets* downstream;
+   harvest *records*.
+
+Scope: the harvest feeds **only tier-3 (e2e pipeline benchmark)**. Tier-1
+(trigger-evals) and tier-2 (per-skill functional, golden fixtures) run on isolated
+fixtures and do not consume it.
+
+### Row schema (one JSON object per line)
+| Field | Existing source (copied, never re-graded) | Signal |
+|---|---|---|
+| `schema_version` | constant `1` | forward-compat |
+| `feature_slug` | run-state frontmatter | identity |
+| `terminal_state` | run-state final: `shipped` / `circuit_broken` / `abandoned` | circuit-breaker outcome |
+| `round_count` | round table | effort-to-PASS |
+| `final_audit_score` | final EVAL report (copied, not re-graded) | conformance |
+| `surprise_count` | `.shapeup/<slug>/discovery/ledger.md` | shaping quality — scope drift |
+| `spike_unresolved_count` | `SPIKE-UNRESOLVED` markers at bet | shaping quality — open risk into bet |
+| `scope_cut_count` | `~` items cut at SHIP S.0 | appetite pressure / scope hammer |
+| `qa_findings` | `.shapeup/<slug>/qa/hunt-report.md` + triage → `{total, promoted, held}` | edge quality |
+| `slice_count` | breadboard B5 (≤9) | **normalizer / denominator** |
+| `sources` | path to each **SHARED** source artifact — never a LOCAL `.shapeup/` path (this row is committed; the run-trace is gitignored/wiped, so a LOCAL path dangles on every clone — tier-direction rule) | auditability |
+
+- `slice_count` is the **denominator**: `round_count=4` on a 2-slice feature is alarming,
+  on a 9-slice feature is normal. Without it, e2e comparisons are apples-to-oranges.
+  Enables `round-per-slice`, `surprise-per-slice`.
+- `spike_unresolved_count` + `surprise_count` measure two of the three downhill
+  conditions (open-risk-remaining, scope-drift-from-breadboard). A good shaping run
+  drives both toward 0 — measured from the build trace, no manual grading.
+- **Rejected fields:** `time_spent` / velocity (no clock; Shape Up forbids counting hours
+  — `round_count` is the legitimate effort proxy) and `run_quality_score` (second judge).
+
+### Row template
+```json
+{"schema_version":1,"feature_slug":"checkout-vnpay","terminal_state":"shipped","round_count":2,"final_audit_score":"PASS","surprise_count":3,"spike_unresolved_count":0,"scope_cut_count":1,"qa_findings":{"total":5,"promoted":1,"held":4},"slice_count":4,"sources":["shapeup/checkout-vnpay/shaping/shaping.md","shapeup/checkout-vnpay/shaping/breadboard.md"]}
+```
+
+LOCAL artifacts (the EVAL report, discovery ledger, QA hunt report) are *harvest-time reads*:
+their **values** are copied into the row's fields (`final_audit_score`, `surprise_count`,
+`qa_findings`) but their paths are never recorded in `sources` — they are gitignored and
+wiped, so a committed pointer to them is dead on arrival.

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

@@ -0,0 +1,184 @@
+# Round Protocol
+
+The orchestration loop in detail. A "round" is one BUILD phase followed by exactly one
+EVAL phase. The feature is done when an EVAL round returns PASS.
+
+> `tasks/_index.md` referenced throughout this file lives in the LOCAL gitignored root
+> (`.shapeup/<slug>/tasks/`, v3.2), not the
+> SHARED spec dir. See tech-lead SKILL.md GATE L1b for the bootstrap step that regenerates it
+> when missing.
+
+```
+round r = 1
+loop:
+    BUILD(r)                          # see r=1 vs r>1 below
+    assert board 100% done            # GATE L2 — advisory: the hook warns, you decide
+    verdict, bugs = EVAL(r)           # ONE spec-evaluator --feature pass
+    if verdict == PASS:
+        SHIP; break
+    if r >= max_rounds:
+        ESCALATE(bugs); break         # honest stop — no infinite loop
+    r = r + 1                         # next round builds bugs only
+```
+
+## BUILD(r) semantics
+
+| | r = 1 (initial build) | r > 1 (fix build) |
+|--|----------------------|-------------------|
+| Input | the whole task board | the bug list from EVAL(r-1) |
+| Scope | every ready task, dependency/layer order, until board all ✅ | only the tasks/areas named by bugs |
+| Command | compile-order `--next` → task-executor `--order` → ingest, looped | compile-order `--task <id> --operation fix` → dispatch → ingest, per bug |
+| Passing areas | n/a | never touched |
+| SPIKEs | resolved first (they block) | only if a bug is a SPIKE finding |
+
+Re-opening tasks in r>1: the fix order's WorkResult reports the task `partial` while failing
+and `done` when re-verified; ingest-result flips the board accordingly. The board reflects the
+churn so the next EVAL sees a green board again.
+
+Discovered Tasks:
+If WorkResults carry `discoveries[]` during BUILD, ingest-result appends them to the discovery
+ledger (`.shapeup/<slug>/discovery/ledger.md`) and the build loop pauses after the current
+tasks are done. Compile + dispatch a reconcile order (ba-pitch-analyzer, operation: reconcile).
+This reconciles them into new tasks and invariants and updates the board; the tech lead bumps
+`discovered_rounds` in harness-run.md, then routes back to GATE L1b (Board Review) for PO
+approval of the new tasks and estimates before resuming the BUILD loop.
+
+## The EVAL timing rule (the core constraint)
+
+EVAL fires **once** per round and **only** when GATE L2 has confirmed the board is 100% done.
+It is never:
+- called per task,
+- called inside the BUILD loop,
+- called on a partial board.
+
+## Regression rule (r > 1) — QA-meeting Bước 1c
+
+A fix round changes code; a fix can break what passed. Therefore EVAL(r>1) scope is **not**
+just the fixed bugs:
+
+```
+EVAL(r) for r > 1:
+  touched_UCs = every UC referenced (use_case_refs) by a task re-opened in BUILD(r)
+  scope = fixed bugs' criteria
+        + FULL re-run of `## Test Surface` rows for every touched UC
+          (test-surface-conformance dimension, when active)
+        + completeness re-check (cheap, static)
+  untouched UCs' surfaces: NOT re-run (their code didn't change; re-probing everything
+  every round would turn cheap end-of-round QA into a full-suite tax)
+```
+
+Pre-v2.9 specs (no Test Surface anywhere): the rule degrades to bug-criteria-only, as
+before — and the verdict report notes `regression coverage: none (no test surface)`.
+Honest reporting over silent coverage claims.
+
+## QA edge hunt (post-PASS, pre-ship)
+
+When EVAL(r) returns PASS for the **first** time in a run, the orchestrator delegates one
+`/qa-edge-hunter` pass before SHIP (skippable via `--no-qa`, same spirit as `--no-eval`).
+QA is a pure worker: no verdict, no score, no gate — it writes `~` findings to
+`discovery/ledger.md` and a `qa/hunt-report.md`. Triage happens at SHIP/GATE L4:
+- all findings stay `~` → SHIP; findings carry over as raw ideas (debt-free).
+- PO/TL promote any to must-have → a fix round r+1 (those items only) → EVAL
+  `--single-pass` on them → `/qa-edge-hunter --recheck` (re-probe ONLY the promoted items;
+  never a second full hunt) → back to L4.
+- Circuit breaker applies: out of rounds/appetite → ship with `~` findings recorded.
+QA never runs on a FAIL round — a build that hasn't passed conformance isn't worth
+edge-hunting yet.
+
+Rationale (from the long-running harness work): a single end-of-round QA pass over the
+running feature is cheap relative to the build (minutes vs hours) and catches the
+last-mile defects, whereas grading every task multiplies evaluator cost for little gain
+once the generator is competent. If the build round didn't finish, there is nothing
+coherent to evaluate yet.
+
+## Stop conditions
+1. **PASS** — EVAL(r) verdict is PASS → SHIP.
+2. **max_rounds (OUTER breaker)** — r would exceed `--max-rounds` (default 3) without PASS →
+   ESCALATE: print the residual bug list, the rounds used, and hand the decision to the PO
+   (scope contracts present: also `/scope-hammer --breaker outer`). Do not start another
+   build round automatically.
+3. **attempt_budget (INNER breaker, scope contracts only)** — a single scope's T0 attempt
+   loop exhausts `--attempts` (default 5) without a green result → does NOT stop the round;
+   queues a hammer PROPOSAL for GATE H and moves to the next scope in sequence. See
+   "Three-level circuit breaker" below.
+4. **wall_clock_budget (DEADLINE breaker, opt-in)** — elapsed seconds since the run receipt
+   exceed `--wall-clock-budget` → do NOT start another build round or another scope; go
+   straight to GATE H (`/scope-hammer --breaker deadline`). Checked with
+   `scripts/budget-check.mjs` at every round boundary and enforced by `hooks/gate-deadline.mjs`,
+   which denies a `task-executor` dispatch past the deadline while leaving `spec-evaluator`,
+   `scope-hammer`, `qa-edge-hunter` and `advisor-protocol` reachable — a run past its deadline
+   must still be able to judge, hammer, and close. Off unless configured.
+5. **Hard error** — a sub-skill fails irrecoverably (e.g. spec folder gone, app won't
+   build at all) → stop and report; do not retry blindly.
+6. **User halt** — at any L-gate the user can stop the run; the ledger preserves state for
+   `--from` resume.
+
+## Three-level circuit breaker
+
+```
+OUTER    round_budget (max_rounds)  — the six-week-timebox analog. Decremented once per
+                                       round at GATE L2, regardless of how many scopes it
+                                       covered. Hitting 0 → GATE H immediately (§ above).
+INNER    attempt_budget (per scope) — decremented once per T0 attempt inside BUILD round r.
+                                       Hitting its cap WITHOUT a T0-green result trips the
+                                       inner breaker for that scope only: the scope is queued
+                                       as a hammer PROPOSAL (not a hard stop) and the round
+                                       moves on to the next scope in the L1b sequence.
+DEADLINE wall_clock_budget_s        — elapsed seconds since the run receipt. Opt-in; off
+                                       unless set at L0. Tripping routes to GATE H with
+                                       --breaker deadline. Enforced by hooks/gate-deadline.mjs.
+```
+
+**Why the third one exists — it was measured, and it corrected an earlier diagnosis.** On the
+SDD harness benchmark (F3, Sonnet 5) this harness was killed at the declared 1800 s cap and
+published as a DNF. The natural reading was that it had stalled at a gate. Re-reading the
+retained transcript says otherwise: **327 turns, 262 tool calls, 37 file writes, 19 gate markers,
+last gate L3, and zero stall signals** — the least talkative shapeup run in the whole matrix. It
+was working when the clock ran out.
+
+Both existing breakers count *events*, not time: `round_budget` moves once per round,
+`attempt_budget` once per T0 attempt. Neither can observe that round 1 has been running for
+twenty-nine minutes, so a run can burn its entire wall clock with both breakers untouched. The
+cost is not the DNF row — it is that a run killed from *outside* ships nothing, not even the
+scopes that were already green. A breaker that trips from the inside routes to GATE H, where
+scope-hammer compares the shippable subset against the baseline and ships what works. Same clock,
+different ending.
+Nesting rationale (DD-9): a struggling scope should not freeze every other scope's progress
+in the same round — only running out of *rounds* (the real six-week analog) stops the whole
+run. A scope that trips its inner breaker still gets judged fairly at GATE H: scope-hammer
+compares "ship without this scope" against the baseline, same as any other cut candidate — it
+is never silently dropped, and it is never allowed to block scopes that ARE working.
+
+## Isolated attempt loop — one T0 attempt, in detail (scope contracts only)
+
+```
+compile-order --scope … --round N --attempt M
+                                   → zero-memory WorkOrder (scope contract + this scope's
+                                      tasks + digested errors + ledger decisions — compiled
+                                      facts, no chat history by construction)
+dispatch task-executor --order …   → code within substrate; WorkResult in results/
+ingest-result <result>             → board/ledger writes; escalates[] queued
+handle_escalations(≤3/scope/round) → /advisor-protocol; answer promoted to round-ledger.md
+                                      immediately (must survive the NEXT attempt's fresh
+                                      context — this is what "zero-memory" is compatible with
+                                      escalation memory means, DD-8)
+t0-verify.mjs                      → fixtures + DB probe + (on green) seesaw
+  green            → attempt loop breaks; scope reaches DOWNHILL_EXECUTION
+  red, regression  → git stash (never a hard discard) + retry; a FINISHED scope's fixture
+                      broke (PA5) — the whole point of running seesaw before declaring green
+  red, own fixture  → AEGIS-digest the failure into {file, line, core_message} triples,
+                      feed them into the NEXT attempt's brief; loop
+```
+This replaces the old flat per-task loop for any scope that has a contract;
+scopes/specs without one keep the v0.2.6 behavior verbatim (see BUILD(r) table above).
+
+## --no-eval (skip evaluation)
+A tech-lead judgment, surfaced at GATE L2: if the feature is clearly within what the model
+builds reliably solo, the evaluator is optional overhead. With `--no-eval`, after GATE L2
+the run goes straight to SHIP with verdict `not-evaluated` recorded in the ledger and a
+clear note that nothing was verified beyond the build's own task-executor GATE D checks.
+
+## Round-cost intuition
+Build dominates; eval is cheap. Expect each EVAL round to cost a small fraction of a BUILD
+round. This is why running eval once per round (not per task) is the right trade: you pay a
+little QA at the end of each build and keep the expensive build coherent in between.

package/skills/tech-lead/references/state-model.md

@@ -0,0 +1,66 @@
+# State Model — who writes what
+
+Reference for the orchestrator. Moved out of `SKILL.md` so the front door stays a runbook: the
+first screen a model reads decides whether it acts or describes, and every line of architecture
+prose ahead of the first tool call is a line it can summarise instead of execute.
+
+---
+
+## State ownership (D6, mechanically closed in v1.0)
+
+Workers are stateless; the orchestrator layer is the **sole writer of ALL run-state**. Every
+worker receives a structured **WorkOrder** envelope (`.shapeup/<slug>/orders/`, compiled by
+`compile-order.mjs`) and returns a **WorkResult** envelope (`results/`); the deterministic
+`ingest-result.mjs` performs every shared-state write — board status, AC ticks, unblock
+propagation, discovery-ledger appends, verdict bookkeeping.
+
+No worker writes `run-state.md`, `tasks/_index.md`, or the ledger. Everything a worker used to
+write into shared files, it now returns as data.
+
+The tech lead owns `harness-run.md` — rounds, gate decisions, Hill positions, verdicts,
+`discovered_rounds`, config, language record. The board (`tasks/_index.md`, LOCAL root — v3.2) is
+**execution truth**, maintained exclusively through ingest.
+
+**The run receipt (v1.4).** `scripts/init-run.mjs` opens the run and writes
+`.shapeup/<slug>/receipt.json` plus `.shapeup/active-scope` before any gate. The
+receipt is the mechanical fact that a run *started* — distinct from every other artifact here,
+which records what a run *did*. That distinction is load-bearing: the guards that check a run's
+progress (`anti-rationalization.mjs`) are all scoped to an active run, so before the receipt
+existed, a run that never started was invisible to every one of them. `hooks/gate-zerowork.mjs`
+reads only the receipt's presence, which is why it can see a total failure that leaves no other
+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`,
+`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`).
+
+A new cross-boundary field is added THERE first (structural test #24 enforces the map's
+consistency); a skill inventing its own undeclared field is a defect — the orchestrator, not the
+worker, owns the vocabulary.
+
+## Two ledgers, split by promotion timing
+
+(Addendum §F.3 — only when scope contracts exist.)
+
+`harness-run.md` stays the LOCAL (`.shapeup/<slug>/`, gitignored) full run trace: it can be
+rebuilt or lost without consequence.
+
+A second, committed `round-ledger.md` (`shapeup/<slug>/round-ledger.md`, SHARED,
+Tier A) holds only what must survive a crash or a `.shapeup/` wipe:
+
+- the resolved model/budget matrix (L0.8/L0.9),
+- the **Decisions** table — every gate crossing and every advisor-protocol ESCALATE answer,
+  promoted the instant it is given, never batched to round close.
+
+Gate crossings resolved from a **gate answer set** (`scripts/gate-answers.mjs`) are written here
+with their source — `preset:ci`, `file:.shapeup/gate-answers.json` — and the set's
+`authorized_by`. A headless run that ships must always be able to name the human behind its
+sign-off; that name lives here and nowhere else.
+
+The tech lead is the sole writer of both. `round-ledger.md` is simply the subset that must never
+live only in a session or a gitignored file. No scope contracts → `round-ledger.md` is not
+written, and `harness-run.md`'s "Decisions log" is the only ledger, exactly as in v0.2.6.

package/skills/tech-lead/references/tiny-lane.md

@@ -0,0 +1,52 @@
+# The tiny lane (`--tiny`) — lane contract
+
+An 8-gate pipeline for a one-file fix is indefensible, and pretending otherwise teaches users
+to bypass the harness entirely. `--tiny` is the honest right-sizing: the full lane's ceremony
+scales down, its *verification floor* does not.
+
+```
+⏸ L0 (fit-check) → ▶ orient (light) → ▶ build (1–2 tasks) → T0 verify → ⏸ L4 (sign-off)
+```
+
+## What changes vs. the full lane
+
+| | Full lane | Tiny lane |
+|---|---|---|
+| WIRE / wiring map | gate L1a.5 | **skipped** |
+| Scope contracts | scope-architect | **skipped** |
+| Spec tree | full DDD tree + board | **single-task board**, compiled directly |
+| EVAL | once per round | **skipped** (`--no-eval` implied) |
+| QA | post-PASS hunt | **skipped** (`--no-qa` implied) |
+| Coach retro | post-L4 | **skipped** |
+| Interactive gates | L0 L1a L1a.5 L1b L2 L3 L4 | **L0 + L4 only** |
+
+## What is kept, non-negotiable
+
+- **The envelope port.** The build is still a compile-order → task-executor(`--order`) →
+  ingest-result dispatch. Tiny never means "just edit the file inline".
+- **T0 verification.** A tiny change still proves itself by running — never by claim. If there
+  is no runnable check at all, that is a fit-check failure, not a reason to skip T0.
+- **The safety-spine and sandbox hooks.** Machine guards do not scale down.
+- **The discovery ledger.** `lane: tiny` is recorded, so a later reader knows exactly what was
+  NOT checked (no EVAL verdict, no QA charter, no wiring assertion).
+
+## The L0 fit-check (mandatory — this is the lane's own gate)
+
+Tiny fits when **all** of these hold:
+
+- the change touches ≤ ~2 files;
+- no new domain concept;
+- no new dependency;
+- no new user-facing flow (changed copy/behavior inside an existing flow is fine).
+
+If the pitch fails any of those, SAY SO and recommend the full lane. Proceed tiny anyway only
+on the PO's explicit confirmation, and record the override in the ledger. The tiny lane must
+never become the way around the gates — it is for changes where the gates would have nothing
+to say.
+
+## Mid-build escalation
+
+If the change turns out not to be tiny while building — a discovery lands that needs a new
+task, a substrate expansion is requested, T0 needs a fixture that doesn't exist — STOP and
+escalate to the PO with a recommendation to restart in the full lane, carrying the orient
+output and the ledger forward. Do not grow the tiny lane in place.