shapeup-sdlc 1.7.0 → 3.0.0

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

@@ -1,261 +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.
-
-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 — 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 |
-| 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
-  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.
-```
-
-  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, the previous attempt's AEGIS triples, and `trial_history` — the last 8 trials
-    for this scope (score, status, delta, top-3 digest), CROSSING the round boundary so a fix
-    round cannot re-propose a change the build round already reverted. The zero-memory
-    handoff, compiled from facts only. Dispatch a fresh Agent per attempt (the isolation
-    boundary):
-    Skill(shapeup-sdlc-plugin:task-executor) --order <path>
-  ingest-result — a WorkResult with status "escalated" leaves its artifact unwritten → see 3b below.
-
-Read back: ingest-result's summary line (tasks updated, ACs ticked, unblocked, discoveries) — not raw board
-files. SPIKE tasks close before the tasks they block can build (compile-order enforces the
-dependency order).
-```
-
-## 3b. A worker that cannot finish (scope contracts present, mid-attempt)
-```
-There is NO adjudication dispatch. A worker has no port for "I cannot decide this": WorkResult
-        carries no escalates field, so the question never reaches you as data.
-What you see: the phase produces no artifact. The workflow's post-condition
-        (resume-state.mjs --require <phase>) fails and the run ABORTS, naming the phase.
-Do: read the phase's result file to find what it could not complete, resolve it yourself —
-        by amending the spec, widening the scope contract, or answering the ambiguity in the
-        round-ledger "Decisions" table — then relaunch. The fast-forward re-dispatches only
-        what is still unfinished.
-Why it aborts rather than pauses: nothing persists an answer between launches, so a pause
-        would relaunch into the same order and hit the same wall. Aborting puts the question
-        in front of a human once instead of looping silently.
-```
-
-## 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:
-  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
-        T0-citation rule will require a citation to, appends one row to t0/trials.jsonl, and — this
-        is the ratchet — scores the attempt against the last kept trial and snapshots or
-        restores the working tree ITSELF. Zero LLM tokens — deterministic tooling, not a
-        judge (this is what keeps "T1 once per round" true even though verification runs
-        every attempt).
-Read back: the stdout JSON — {path, sha256, trial, overall, regression, score, status,
-        baseline_trial, delta, tree_ref}. `status` (kept|reverted|rebased|crash) is what
-        drives the attempt-loop branch in round-protocol.md "Isolated attempt loop"; by the
-        time you read it the tree action has already happened. Never branch on the process
-        exit code: it carries the T0 binary (0 green / 1 red / 2 bad argv, the oracles/*
-        convention), so a `kept` red-but-improved attempt, the ratchet's own signature case,
-        exits 1. 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) | tech lead (substrate/sequence), sandbox hook (write-whitelist), compile-order (inlined into orders) |
-| `t0/verdicts/r<N>-a<M>-t<T>.json` | `scripts/t0-verify.mjs` (skill-local, mechanical — not a worker) | spec-evaluator (required citation), tech lead (hill derivation), compile-order (digested errors) |
-| `t0/trials.jsonl` (the ratchet ledger, append-only, `baseline_trial` as the parent link) | `scripts/t0-verify.mjs` (one row per attempt: score, status, delta, tree_ref) | compile-order (`trial_history` into the next order), ship-report (T0 + Ratchet sections), `stats.mjs --ratchet` |
-| `round-ledger.md` | **tech lead (sole writer)** | compile-order (decisions into every order), PO (audit) |
-| `hill/<scope-id>.yml` + `hill-chart.md` | **tech lead (sole writer)** | PO ("status without asking"), scope-hammer (H0 census) |
-
-> The single-writer rule is closed mechanically: 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/hard-rules.md

@@ -1,34 +0,0 @@
-# Hard Rules (never override without explicit user instruction)
-
-Moved out of `SKILL.md` when the round loop became a launchable script:
-most of what this table used to guard against — a partial board reaching EVAL, a gate crossed
-on the model's own authority, an evaluator called mid-BUILD — is now a property of
-`skills/tech-lead/workflows/shapeup-run.js`'s code, not a rule a model has to remember to obey.
-The table stays as the readable rationale for WHY the code is shaped the way it is; the runtime
-guarantee lives in the script and, where noted, in a hook.
-
-| Rule | Rationale |
-|------|-----------|
-| Orchestrates Building only (steps 7–11); shaping/betting/kick-off are PO-personal, upstream | Intake is a kicked-off pitch, not a raw idea — the tech lead does no shaping/planning-authority work |
-| ORIENT (step 7) runs before MAP SCOPES (step 8) | Roadmap: no pre-divided tasks at kick-off; the team orients first so the board is reality-born |
-| Intake must be English before ORIENT; tech lead does NOT translate — it delegates to `translator` at GATE L0 | Translation is a separate single-purpose skill; the intake conversation only detects + sequences it, before RunArgs is ever compiled |
-| Every worker dispatch goes through the envelope port: compile-order → `--order` → ingest-result; shared state is written ONLY by ingest | The single-writer rule is mechanically true: a worker that writes boards/ledgers/run-state is a defect, and a malformed envelope is denied by the validate-envelope hook before it can corrupt run truth. `shapeup-run.js` uses this same shape for every operation in the central registry — orient, wire, analyze, map-scopes, evaluate, hunt, hammer alike |
-| Progress is reported by Hill position, never by counting tasks | The roadmap forbids task-counting; a 90%-done slice can still be stuck uphill on the one unknown that matters |
-| Evaluator runs once per round, only after GATE L2 (board 100% done) | The whole point: cheap end-of-round QA, never per task. `shapeup-run.js`'s round loop dispatches spec-evaluator exactly once per iteration, after the GATE L2 resolution — there is no code path that calls it from inside the scope attempt loop |
-| Evaluator never called inside the BUILD loop | Keeps the build coherent and the run cheap |
-| r>1 builds bugs only, never the whole board | Don't re-do passing work; minimize churn — see round-protocol.md's regression rule for what DOES re-run (touched UCs' full Test Surface) |
-| Stop at max_rounds; escalate honestly | No infinite fix loops; `shapeup-run.js` returns `{status: "gate_h", breaker: "outer"}` rather than looping past the budget |
-| Tech lead delegates, never reimplements a sub-skill | Stays thin; each skill keeps its own gates and authority |
-| Every delegation to a sub-skill (except the mechanical `t0-verify.mjs`/`compile-order.mjs`/`ingest-result.mjs`) is a fresh Agent on the L0.8-resolved model | Isolation the zero-memory-handoff design assumes; a direct inline call would silently drop the model matrix — see references/delegation.md "Invocation mechanism" |
-| Planner stays high-level on tech | Spec errors cascade into every build round |
-| Never auto-deploy; "shipped" never silently means "deployed" | Deploy is outward-facing, PO-gated; record "deploy pending (PO)" otherwise |
-| "Shipped" names the dims NOT evaluated | `RunReturn`'s `dims_not_evaluated` field carries this; the L4 sign-off block shows it, never silently drops it |
-| Every gate emits the canonical `⏸ GATE LN — Title` block before any narrative | Composed by the workflow (`gateBlock()`), emitted VERBATIM by the skill — conversational re-summary is not a gate |
-| In interactive/--auto: a `paused` return stops and waits for PO confirmation | Never auto-proceed past a gate; the PO must cross each threshold explicitly — see "The pause protocol" in SKILL.md |
-| At GATE L3 FAIL: name scope (task + failed criterion), never prescribe fix options | Root cause analysis and fix paths belong to the implementer, not the orchestrator |
-| SHIP harvest records facts only — copies existing structured output, never computes a new verdict/score | A self-computed score = a second judge behind spec-evaluator (breaks single-judge, invites Goodhart); the eval suite interprets, harvest records |
-| Three-level circuit breaker: attempt_budget (inner, per scope) nests inside round_budget (outer), with an opt-in wall_clock_budget_s deadline | An exhausted scope queues a GATE H hammer proposal, it never blocks the round; only round_budget hitting 0 stops the whole run; the deadline breaker (checked every round boundary in `shapeup-run.js`) routes to GATE H so a run out of clock still ships what is green instead of being killed from outside |
-| The tech lead never hand-edits a scope contract | scope-architect is its sole writer (single-writer-per-file) |
-| Substrate-disjointness + PA1/PA2 lints are re-asserted at GATE L1b (spec-lint.mjs) even when scope-architect already checked them | A human may have hand-approved past a 🔴 at the architect's checkpoint; `shapeup-run.js` runs spec-lint itself, in code, before resolving L1b |
-| Hill phase is read from mechanical facts (T0/T1/seesaw), never declared by a worker | Closes the self-reported-confidence risk outright — facts move dots, not authors |
-| GATE H is delegated to scope-hammer, never adjudicated inline by the tech lead | Keeps the orchestrator thin; census/baseline-comparison/cut-list logic has one owner |

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 |
-| `--exec-model / --eval-model / --qa-model <name>` | Override L0.8's resolved model matrix (`RunArgs.models`: exec/eval/qa) for this run only — highest precedence. The orchestrator itself runs in-session; it has no model knob here |
-| `--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, comma-separated (default `spec-conformance`). Passed straight through to `init-run.mjs --dimensions`, which records the set in the ledger's `eval_dimensions:` — that line is what every EVAL order is compiled from, so a dimension named anywhere else does not run. Ids the evaluator ships: `spec-conformance`, `tdd-surface`, `integration`, `completeness`, `test-surface-conformance`, `security`, `performance` (the last two are disabled stubs); a dimension you inject yourself is named here the same way |
-
----
-

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

@@ -1,213 +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.** 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]   # the set from GATE L0.5 (init-run --dimensions); every EVAL order is compiled from THIS line
-max_rounds: 3
-auto_level: interactive | auto | unattended
-status: orienting | mapping | building | evaluating | shipped | escalated
-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, 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. 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 the PO answers —
-never batched to round close. This is the file `task-executor`'s isolated briefs read back
-(the zero-memory handoff): 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; LOCAL (gitignored)
-```
-
-Path note: `metrics/` lives under the LOCAL root with the rest of the run trace — moved
-there by ADR-0001, because a committed shard keyed on `$HOSTNAME` only grows and puts a
-person's machine name in the repo. It outlives any single run (the per-slug run dirs are
-superseded run by run; the shard only appends), which is what makes it the durable signal
-feed. Sharded per machine so shards can be pooled deliberately without colliding on one
-filename; the read plane is `stats.mjs`, or `cat .shapeup/metrics/*.jsonl`.
-`schema_version` makes an old 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 the e2e pipeline measurement**. The per-skill functional
-fixtures run in isolation 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 (the run-trace is superseded run by run, so a LOCAL path dangles by the time anyone reads the row; SHARED paths resolve on any 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.