shapeup-sdlc 1.6.3 → 3.0.0

package/skills/tech-lead/README.md

@@ -1,71 +0,0 @@
-# tech-lead
-
-The orchestrator over the harness. Acts as the tech lead that runs a feature end-to-end
-across three skills, makes round decisions, and reports to the PO at gates. It is **thin** —
-it sequences and decides, it does not plan, build, or judge itself.
-
-```
-ba-pitch-analyzer (planner)  →  task-executor (generator)  →  spec-evaluator (judge)
-        PLAN                         BUILD (loop all tasks)        EVALUATE (once / round)
-                                          ▲                              │
-                                          └──── bugs, round r+1 ◄────────┘  on FAIL
-```
-
-**Core rule:** the evaluator runs exactly once per build round, only after the task board
-is 100% done — never per task. That single end-of-round QA pass is the long-running harness
-V2 lesson, and enforcing its timing is the reason this skill exists.
-
-## Resource map
-```
-tech-lead/
-├── SKILL.md                       # entry — GATE L0–L4, the round loop, flags, hard rules
-├── README.md                      # this file
-└── references/
-    ├── round-protocol.md          # ★ the loop: r=1 vs r>1, stop conditions, eval timing rule
-    ├── delegation.md              # how each of the 3 sub-skills is invoked + handoff files
-    └── ledger-schema.md           # harness-run.md — the round table / decisions / escalation
-```
-
-| Resource | Loaded at | Purpose |
-|----------|-----------|---------|
-| `SKILL.md` | always | L-gates, phase sequence, invocation, authority rules |
-| `references/round-protocol.md` | BUILD/EVAL | the loop semantics + the "eval once at end" rule |
-| `references/delegation.md` | each phase | exact sub-skill commands + which handoff files to read |
-| `references/ledger-schema.md` | throughout | the run ledger that carries state across rounds/sessions |
-
-## Install
-```bash
-cp -r tech-lead <repo>/.claude/skills/      # or ~/.claude/skills/
-```
-Requires the harness skills installed: `ba-pitch-analyzer`, `task-executor`,
-`spec-evaluator`, plus `translator` (the GATE L0 language gate for non-English intake).
-The EVAL phase uses spec-evaluator's feature-level pass
-(`--feature <slug>`) — see the dependency note in `references/delegation.md`.
-
-## Invoke
-```bash
-/tech-lead --pitch shapeup/checkout/shaping/shaping.md --spec shapeup/checkout/spec/ --lens standard
-/tech-lead --pitch ... --spec ... --auto                 # sub-skills unattended; pause at L1/L3/L4
-/tech-lead --pitch ... --spec ... --unattended --max-rounds 3   # headless / CI (Agent SDK)
-/tech-lead --spec shapeup/checkout/spec/ --from build   # resume an existing run
-/tech-lead --pitch ... --spec ... --no-eval              # skip eval for a trivial feature
-```
-
-## Gate map
-| Gate | When | Decision |
-|------|------|----------|
-| L0 | intake | language gate (`/translator --check`, translate if non-English) + run config: spec folder, lens, dims, max_rounds, auto level |
-| L1a | after ORIENT | PO reviews the spiked area + 🗻 Hill unknowns before mapping scopes |
-| L1b | after MAP SCOPES | PO accepts the task board (appetite guard) before any code |
-| L2 | after BUILD round | board 100% done? → the single EVAL pass (hook warns if not; advisory) |
-| L3 | after EVAL | PASS → /qa-edge-hunter pass → ship; FAIL → bug-only round r+1; max_rounds → escalate |
-| L4 | after SHIP | PO sign-off, close the ledger, harvest metrics to metrics.jsonl |
-
-## Auto levels
-- **interactive** (default): pause at every L-gate; sub-skills keep their own gates.
-- **--auto**: sub-skills run unattended; tech lead still pauses at L1a / L1b / L3 / L4.
-- **--unattended**: auto-confirm all L-gates; stop only on PASS, max_rounds, or hard error.
-  This is the headless mode for an Agent SDK / CI driver.
-
-## Version
-0.10 — Two-root workspace split (`shapeup/` vs `.shapeup/`), automated discovered-task reconciliation (`/ba-pitch-analyzer --tasks-only --from-discovered`), regression rule (touched UCs re-run), QA edge-hunter wiring (exploratory findings, triage at SHIP S.0), metrics harvest, and split L1a/L1b gates.

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

@@ -1,254 +0,0 @@
-# Delegation
-
-The tech lead invokes the build-phase skills and reads their handoff files. It never
-reimplements their logic. Each sub-skill keeps its own gates; pass `--auto` to a sub-skill
-only when the run's auto level is `--auto` or `--unattended`.
-
-## Invocation mechanism — Agent, not Skill
-
-Every "Invoke:" line below means: call the **Agent** tool — a real subagent, on its own
-context and (where a role is named) its own model — whose prompt tells it to run
-`Skill(shapeup-sdlc-plugin:<name>)` with the given args and report back the artifacts. It does
-**not** mean the tech lead calls the `Skill` tool itself. A direct `Skill` call executes
-inline, in the tech lead's own turn, on the tech lead's own model — that silently drops GATE
-L0.8's model matrix (there is no per-role model left to route once the call is inline) and
-breaks the isolation the zero-memory-handoff design (`round-protocol.md`, the compiled
-WorkOrder in `orders/r<N>-a<M>.json`) already assumes every worker below has.
-
-Standard shape (pure-skill architecture v1.0 — the envelope port):
-```
-1. node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/compile-order.mjs" <mode flags>      # → orders/<id>.json
-2. Agent({
-     description: "<short task description>",
-     subagent_type: "general-purpose",
-     model: "<role model resolved at GATE L0.8>",
-     prompt: "Call Skill(shapeup-sdlc-plugin:<skill>) --order <orders/<id>.json>.
-              Report back: the WorkResult path (.shapeup/<slug>/results/<id>.json)."
-   })
-3. node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/ingest-result.mjs" .shapeup/<slug>/results/<id>.json
-```
-The WorkOrder carries everything the worker may rely on (payload, decisions, digested errors,
-substrate write-contract); the WorkResult carries everything the worker used to write into
-shared files. `validate-envelope.mjs` runs as a PreToolUse hook on Skill|Agent and DENIES a
-dispatch whose `--order` file is missing or schema-invalid. Workers write only their own
-domain artifacts inside their substrate — never boards, ledgers, or run-state (D6, closed).
-
-Role → model, resolved once at GATE L0.8 from the `orch`/`exec`/`eval`/`qa` matrix
-(`t0-verify.mjs` is mechanical tooling run directly via Bash, never an Agent — DD-7, zero LLM
-tokens):
-
-| Skill | L0.8 role | Why this tier |
-|-------|-----------|---------------|
-| translator | exec | one-shot text transform — builder tier |
-| orient (Scout) | exec | reads/spikes code — builder tier, not judgment |
-| ba-pitch-analyzer | exec | planner — builder tier, not judgment |
-| scope-architect | exec | scope-contract author (sole writer of scopes/*.md) — builder tier |
-| task-executor | exec | the builder itself |
-| advisor-protocol | exec | adjudicates ESCALATE by precedent/default, budget-capped — not the single judge |
-| spec-evaluator | eval | the single judge (judge ≠ doer) — keep its own matrix key even if a PO points it at the same model as `exec`, so it can be split later without a harness change |
-| qa-edge-hunter | qa | cheapest tier by design — exploratory breadth over depth |
-| scope-hammer | exec | census + baseline comparison, proposes only — not a verdict |
-| coach | exec | categorization gate, not a verdict |
-
-The tech lead itself is `orch` — this conversation, never delegated to.
-
-The order is **Orient (7) → Map Scopes (8) → Build (9) → Eval**, faithful to Shape Up: the
-team orients before any board exists, so the planner's board is reality-born. The tech lead
-is the **sole writer of run-state** (`harness-run.md`) — it passes each worker the run
-metadata it needs (`feature`, `spec`, `stack`, `discovered_rounds`, `--auto`) as **args**;
-workers keep only their own product-idempotency key and emit domain artifacts.
-
-## 0. LANGUAGE GATE → translator (GATE L0, only if non-English)
-```
-Invoke via Agent (model: exec): Skill(shapeup-sdlc-plugin:translator) --check "<intake path>"
-                 # detect-only, writes nothing
-  English      → skip; ORIENT against the original.
-  non-English  → Agent (model: exec): Skill(shapeup-sdlc-plugin:translator) "<intake path>" [--auto]
-                 # full pass
-                 Writes: <name>.en.md (English copy; original untouched) + glossary.md
-                         + translation-report.md.
-                 ORIENT against the <name>.en.md copy.
-Read back: the detect table (--check) / the .en.md path + residual scan result (full pass).
-Authority: translator normalizes language only — it does not orient/plan/build/judge. The tech
-lead never translates itself; it only detects and sequences this step before ORIENT.
-```
-
-## 1. ORIENT → orient (the Scout, step 7) — runs BEFORE planning
-```
-Invoke via Agent (model: exec): Skill(shapeup-sdlc-plugin:orient)
-        --pitch "<kicked-off pitch path>" --spec <path> --stack "<hint>" [--auto]
-Owns:   its own GATE O-A/O-B (or runs straight through under --auto)
-Writes: .shapeup/<slug>/orient/ → code-surface.md, spike-<area>.md, discovered-seed.md, hill-signal.md (LOCAL run-trace)
-Read back: hill-signal.md (render the area-level Hill at GATE L1a) + the spiked area/result.
-Why first: at Orient time NO board exists; the Scout's map + discovered seed make the planner's
-        board reality-born instead of imagined. The four artifacts are the orient→ba contract.
-Authority: pure worker — no code, no board, no run-state, no reporting.
-```
-
-## 2. MAP SCOPES → ba-pitch-analyzer + scope-architect (step 8, orient-informed)
-```
-Order A (the spec tree + board):
-  compile-order --operation analyze --slug <slug> --worker ba-pitch-analyzer
-    --payload '{"pitch": "<path>", "lens": "<lens>", "orient_dir": ".shapeup/<slug>/orient/"}'
-  Agent (model: exec): Skill(shapeup-sdlc-plugin:ba-pitch-analyzer) --order <path>
-  The order hands it code-surface.md (Phase-1 ingest, no re-scan), discovered-seed.md (task
-  gen from reality), spike-<area>.md (feasibility/contracts).
-  Writes (its substrate): spec_folder → _index.md, domain-model.md, ux-behavior.md, usecases/*,
-    contracts/*.contract.md, scope-summary.md (+ api-feasibility.md if third-party) and the
-    LOCAL board .shapeup/<slug>/tasks/ (v3.2; regenerable via a generate-board order).
-  Returns: WorkResult (artifacts list + discoveries) → ingest-result.
-Order B (the scope contracts):
-  compile-order --operation map-scopes --slug <slug> --worker scope-architect
-  Agent (model: exec): Skill(shapeup-sdlc-plugin:scope-architect) --order <path>
-  Writes (its substrate): shapeup/<slug>/scopes/*.md + scope-board.md — sole
-    writer. Lint mechanically: node "${CLAUDE_PLUGIN_ROOT}/skills/ba-pitch-analyzer/scripts/spec-lint.mjs" <slug> (PA1/PA2 +
-    substrate disjointness) before GATE L1b.
-Read back: .shapeup/<slug>/tasks/_index.md (the board) + scope-summary.md (Done-when)
-  + the spec-lint verdict.
-Pass-through rule: do not coach the planner to over-specify implementation — keep tech high-level.
-```
-
-## 2b. RECONCILE → ba-pitch-analyzer (discovered task reconciliation, operation: reconcile)
-```
-compile-order --operation reconcile --slug <slug> --worker ba-pitch-analyzer
-  --payload '{"discovered_ledger": ".shapeup/<slug>/discovery/ledger.md"}'
-Agent (model: exec): Skill(shapeup-sdlc-plugin:ba-pitch-analyzer) --order <path>
-Effect: reconciles raw ledger discoveries into board tasks + appended UC invariants/TS rows,
-        inside the reconcile write-contract (frozen zone enforced by the sandbox hook, not
-        prose). Appetite Guard runs mechanically: node "${CLAUDE_PLUGIN_ROOT}/skills/ba-pitch-analyzer/scripts/board-derive.mjs".
-Returns: WorkResult → ingest-result (which updates the board and bumps discovered_rounds in
-        harness-run.md — the worker holds no counter).
-Read back: updated tasks/_index.md + scope-summary.md before routing back to GATE L1b.
-```
-
-## 2c. BOOTSTRAP LOCAL BOARD → ba-pitch-analyzer (operation: generate-board, v3.2)
-```
-Only when GATE L1b's bootstrap check fires (LOCAL .shapeup/<slug>/tasks/_index.md missing
-AND SHARED shapeup/<slug>/spec/usecases/ present):
-  compile-order --operation generate-board --slug <slug> --worker ba-pitch-analyzer
-  Agent (model: exec): Skill(shapeup-sdlc-plugin:ba-pitch-analyzer) --order <path>
-Effect: regenerates the LOCAL task board fresh from the committed usecases/domain-model/scopes
-        — no ledger, no reconciliation. Status bootstraps from committed T0/hill facts at
-        SCOPE granularity; unlocks recomputed by node "${CLAUDE_PLUGIN_ROOT}/skills/ba-pitch-analyzer/scripts/board-derive.mjs" --write.
-Read back: the freshly regenerated tasks/_index.md before entering BUILD.
-```
-
-## 3. BUILD → task-executor (always through the envelope port)
-```
-r=1 loop:
-  compile-order --next --slug <slug> [--test-cmd "<cmd>"]        # exit 2 = no ready task
-  Agent (model: exec), one fresh subagent per order:
-    Skill(shapeup-sdlc-plugin:task-executor) --order <path>
-  ingest-result <results/<id>.json>   # ticks ACs, marks done, updates board, propagates unblocks
-  Repeat until compile-order --next reports no ready task (board all ✅).
-
-r>1 (fix) per bug:
-  compile-order --task <id> --slug <slug> --operation fix --payload '{"bugs": [<entries>]}'
-  → dispatch + ingest as above. Scope the change to the bug only.
-
-Scope contracts present (isolated attempt loop, per scope, per attempt):
-  compile-order --scope shapeup/<slug>/scopes/<id>.md --round <N> --attempt <M>
-  → orders/r<N>-a<M>.json inlines the scope contract, this scope's tasks, promoted ledger
-    decisions, and the previous attempt's AEGIS triples — the zero-memory handoff, compiled
-    from facts only. Dispatch a fresh Agent per attempt (this IS the isolation boundary):
-    Skill(shapeup-sdlc-plugin:task-executor) --order <path>
-  ingest-result — any escalates[] in the WorkResult are queued → dispatch 3b below.
-
-Read back: ingest-result's summary line (tasks updated, unblocked, escalates) — not raw board
-files. SPIKE tasks close before the tasks they block can build (compile-order enforces the
-dependency order).
-```
-
-## 3b. ESCALATE adjudication → advisor-protocol (scope contracts present, mid-attempt)
-```
-Invoke via Agent (model: exec): Skill(shapeup-sdlc-plugin:advisor-protocol)
-        --ledger shapeup/<slug>/round-ledger.md --escalate <block> [--unattended]
-Effect: adjudicates via precedent / substrate-expansion (→ a scope-architect remap order) / PO ask / conservative
-        default; appends one row to round-ledger.md "Decisions" the instant it resolves.
-Read back: the answer, to fold into the SAME attempt if still in progress, or the next
-        attempt's isolated brief otherwise.
-Authority: advises; never designs, builds, or judges. Budget ≤3/scope/round — the 4th+
-        ESCALATE this scope/round auto-resolves conservatively and flags a GATE H proposal.
-```
-
-## 3c. T0 verify → scripts/t0-verify.mjs (skill-local; scope contracts present, every attempt)
-```
-Invoke via Bash directly — NOT an Agent, this is deterministic tooling, not a worker (DD-7):
-  node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/t0-verify.mjs" shapeup/<slug>/scopes/<scope-id>.md
-        --round <N> --attempt <M> --seesaw-registry .shapeup/<slug>/seesaw/registry.json
-Effect: runs the scope's e2e fixtures + DB probe, then (on green) the seesaw regression check
-        over every FINISHED scope's fixtures. Writes the verdict artifact spec-evaluator's
-        GATE V0.7 will require a citation to. Zero LLM tokens — deterministic tooling, not a
-        judge (this is what keeps "T1 once per round" true even though verification runs
-        every attempt, DD-7).
-Read back: overall (green|red) + regression (bool) — drives the attempt-loop branch in
-        round-protocol.md "Isolated attempt loop". On red, its `discovered_tasks` field is
-        the AEGIS digest to fold into the next brief — no separate digester dispatch needed
-        (t0-verify.mjs calls its sibling aegis-digest.mjs internally on failure).
-```
-
-## 4. EVAL → spec-evaluator (once per round)
-```
-compile-order --operation evaluate --slug <slug> --worker spec-evaluator --round <r>
-  --payload '{"dimensions": ["spec-conformance"], "run_cmd": "<cmd>", "t0_artifacts": [...]}'
-Invoke via Agent (model: eval), ONCE, after GATE L2:
-  Skill(shapeup-sdlc-plugin:spec-evaluator) --order <path>
-Effect: one feature-level pass over the running app against all AC + Done-when; writes
-        evaluation/EVAL-FEATURE-<slug>.md (verdict + bug list) + its WorkResult (criteria
-        verdicts, refuted boxes, T0 citations). It touches NO task file and NO board.
-ingest-result <results/evaluate-r<r>.json>: appends the .verdicts JSONL ledger, un-ticks the
-        refuted AC boxes, sets eval_verdict frontmatter — the judge returns data, ingest writes.
-Read back: EVAL-FEATURE-<slug>.md → verdict (pass|fail) + the bug list (each bug has
-        task ref, severity, file:line, expected vs actual).
-```
-
-> Dependency note: this uses spec-evaluator's **feature-level** pass (`--feature <slug>`),
-> which evaluates the whole board in one session rather than one task at a time. If your
-> installed spec-evaluator is the per-task v0.1, add the `--feature` mode (a small v0.2
-> patch: iterate the board's AC/Done-when in one probe+grade session, emit one
-> EVAL-FEATURE report) before wiring the tech lead to it. The per-task invocation still
-> works for ad-hoc checks, but the round loop expects one feature pass.
-
-## 5. SHIP / GATE H → scope-hammer
-```
-Invoke via Agent (model: exec): Skill(shapeup-sdlc-plugin:scope-hammer)
-        --slug <slug> [--baseline <path>] [--breaker outer|inner --scope <id>]
-Effect: GATE H0 census (scopes + QA findings + discovered ledger + advisor-overflow flags) →
-        H1 baseline comparison (never vs. a perfect ideal) → H2 cut list + verdict.
-Read back: the proposed cut list + verdict (SHIP now | SHIP after fixing ship-blocking items |
-        CANNOT SHIP). The tech lead records the PO's decision in round-ledger.md and performs
-        the actual close (SHIP S.1 onward) — scope-hammer proposes, it never ships.
-```
-
-## Authority boundaries (do not cross)
-- The Scout orients; it never plans, builds, or judges — it hands raw material to the planner.
-- The planner decides scope; the tech lead confirms it with the PO at GATE L1b.
-- The generator reports task outcomes in its WorkResult; `ingest-result.mjs` flips `status:
-  done` from that report. The tech lead confirms the feature-level close at GATE L4.
-- The evaluator issues verdicts only; it never closes tasks. Judge ≠ doer.
-- The tech lead decides *when* and *whether* each skill runs and how rounds proceed, owns
-  run-state + the Hill report — it does not decide *what* a task contains or *whether* a
-  single AC passes.
-
-## Handoff files (the shared state)
-| File | Written by | Read by |
-|------|-----------|---------|
-| `<name>.en.md` + `glossary.md` | translator (L0, if non-English) | tech lead (ORIENT input), Scout, planner |
-| `orient/code-surface.md` | Scout (step 7) | planner Phase 1 (ingest, no re-scan) |
-| `orient/spike-<area>.md` | Scout (step 7) | planner Phase 1b/contracts; tech lead (L1a) |
-| `orient/discovered-seed.md` | Scout (step 7) | planner Phase 6 (task gen) |
-| `orient/hill-signal.md` | Scout (step 7) | tech lead (renders L1a Hill) |
-| `orders/<id>.json` (WorkOrder) | **compile-order.mjs (mechanical)** | every worker (its ONLY pipeline input), validate-envelope hook |
-| `results/<id>.json` (WorkResult) | the dispatched worker (its ONLY pipeline output) | ingest-result.mjs (the single writer of everything below it) |
-| `.shapeup/<slug>/tasks/*` (LOCAL board, v3.2) | **ingest-result.mjs** (status, AC ticks, unblocks) + planner orders (task bodies) | tech lead (board status), compile-order (next task, ACs) |
-| `discovery/ledger.md` | **ingest-result.mjs** (from workers' `discoveries[]`) | reconcile orders (ba), scope-hammer (H0 census) |
-| `scope-summary.md` | planner (analyze/reconcile orders) | tech lead (Done-when), evaluator (Done-when criteria) |
-| `evaluation/EVAL-FEATURE-<slug>.md` + `.verdicts-*.jsonl` | evaluator (report) / **ingest-result.mjs** (verdict ledger, un-ticks) | tech lead (verdict), next fix order (bug list) |
-| `harness-run.md` | **tech lead (sole writer)** | tech lead (round ledger + Hill + run-state), PO (audit) |
-| `scopes/<scope-id>.md` | `scope-architect` (sole writer, incl. remap/split orders) | tech lead (substrate/sequence), sandbox hook (write-whitelist), compile-order (inlined into orders) |
-| `t0/verdicts/r<N>-a<M>.json` | `scripts/t0-verify.mjs` (skill-local, mechanical — not a worker) | spec-evaluator (required citation), tech lead (hill derivation), compile-order (digested errors) |
-| `round-ledger.md` | **tech lead (sole writer)** | compile-order (decisions into every order), advisor-protocol (appends), PO (audit) |
-| `hill/<scope-id>.yml` + `hill-chart.md` | **tech lead (sole writer)** | PO ("status without asking"), scope-hammer (H0 census) |
-
-> D6 is closed (v1.0): no worker writes `run-state.md`, the board, or the ledger. A worker
-> performing a shared-state write is a defect — route it back through its WorkResult.

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

@@ -1,45 +0,0 @@
-# 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

@@ -1,214 +0,0 @@
-# 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.