shapeup-sdlc 1.6.2

package/skills/spec-evaluator/references/report-schema.md

@@ -0,0 +1,101 @@
+# Report Schema — `evaluation/EVAL-<task_id>.md`
+
+The handoff file. Communication between judge and doer is by file: the evaluator writes
+this, the generator (`task-executor`) reads the bug list as its next input. Keep it
+actionable enough that the generator never has to ask a follow-up question.
+
+## Frontmatter
+```yaml
+---
+type: eval-report
+feature: [slug]
+task: TASK-NNN(.variant)
+verdict: pass | fail
+dimensions_run: [spec-conformance]      # the active set this run
+dimensions_ignored: [security, performance]
+bug_count: [N]
+browser_mode: cli | mcp | none
+evaluator: spec-evaluator v0.1
+eval_at: [ISO date]
+linked_docs: ["[[usecases/UC-Name]]", "[[scope-summary]]"]  # + "[[tasks/TASK-NNN-slug]]" only when a local task file exists this run (V0.2b)
+t0_citation: ~ | { scope_id: cart-creation, artifact: t0/verdicts/r2-a3.json, sha256: 1a2b3c… }
+---
+```
+`t0_citation` is `~` (not applicable) only when the spec folder has no scope contracts
+(pre-v0.3.0 spec). On any scoped spec it is required — GATE V0.7/V2.5 in SKILL.md — an absent
+citation there means the report should not have been written yet.
+
+## Body sections (in order)
+
+### 1. Verdict line
+```
+OVERALL: FAIL — spec-conformance failed (1 AC, 1 non-go breach). 2 bugs. Ignored: security, performance.
+```
+
+### 2. Per-dimension criteria table
+One block per dimension run. N/A criteria shown as N/A, never PASS.
+```
+## spec-conformance — FAIL  (threshold: all-pass)
+| id | criterion | verdict | evidence |
+|----|-----------|---------|----------|
+| SC-AC | every UC Step/Error Case passes | ❌ FAIL | UC-Checkout Step 4 "Pay" click throws — apps/web/checkout/Pay.tsx:84 |
+| SC-DONE-WHEN | "User pays successfully" | ❌ FAIL | redirect to /success never fires (see AC2) |
+| SC-REQ | request matches contract | ✅ PASS | curl 200, fields match #Request |
+| SC-RES | response mapping | ✅ PASS | field-by-field match to #Response |
+| SC-ERR | error cases handled | ✅ PASS | 400/409/422 all returned as documented |
+| SC-NONGO | non-go respected | ❌ FAIL | modified packages/shared/auth — out of scope |
+| SC-LAYER | no layer leak | ✅ PASS | — |
+```
+
+### 2b. Verdict stability (verdict-ledger.md)
+After the dimension tables. Reports re-probe/confidence outcomes and any cross-run flips read from
+`.verdicts-<task_id>.jsonl`. On the first run, state there is no history yet (the ledger is still
+written, as the baseline).
+```
+## Verdict stability (run 3)
+- ⚠ AC4 — FLIP PASS→FAIL vs run 2, no code change to checkout → judge non-deterministic here; confidence low. Re-run before trusting.
+- AC2 — stable FAIL across runs 1–3 (confidence high).
+- Stability: 6/7 criteria stable this round.
+```
+The per-dimension tables (§2) carry a `confidence` column when this is active.
+
+### 3. Bug list
+One entry per FAIL, using the failing dimension's bug template. This is the generator's
+worklist.
+```
+## Bugs
+### BUG-1 — critical
+criterion: SC-AC / SC-DONE-WHEN
+location: apps/web/checkout/Pay.tsx:84
+repro: navigate /checkout → fill card → click "Pay"
+expected: POST /payments fires, redirect to /success (Done when: "User pays successfully")
+actual: console TypeError: onPay is not a function; no network call; stays on /checkout
+fix_hint: onPay prop not passed from CheckoutPage; wire handler → Pay button
+
+### BUG-2 — minor
+criterion: SC-NONGO
+location: apps/api/shared/auth.ts:12
+repro: git diff --stat
+expected: task touches apps/web only (## Non-go: do not change auth)
+actual: auth.ts modified (added a field); revert or move to a separate task
+```
+
+### 4. Next action
+A single explicit handoff line the orchestrator/generator acts on.
+```
+## Next action
+→ Generator: re-run `task-executor --spec <path> --task TASK-NNN` to fix BUG-1, BUG-2,
+  then re-run `spec-evaluator` on the same task. Do not close until verdict: pass.
+```
+For a PASS:
+```
+## Next action
+→ TASK-NNN is verified against [spec-conformance]. Safe for the orchestrator to close.
+  (Note: security, performance were NOT evaluated this run.)
+```
+
+## Rules
+- The report never sets `status: done` on the task — it sets `eval_verdict` only.
+- A PASS report still names the dimensions that were *not* run, so "verified" is never read
+  as "verified for everything."
+- Every bug is self-contained: location + repro + expected/actual, no external context needed.

package/skills/spec-evaluator/references/verdict-ledger.md

@@ -0,0 +1,92 @@
+# Verdict Ledger — re-probe, confidence, and flip detection
+
+Read this at GATE V2 (alongside `anti-leniency.md`) and act on it at Phase B. It exists because
+the judge is the harness's least verifiable component: a single non-deterministic snapshot per
+criterion, no second opinion, no record of whether last round's PASS would still pass. This turns
+that blind oracle into a **measurable** one — without adding a second judge (the single-judge
+invariant is untouched). Three mechanisms: **re-probe on FAIL**, **per-criterion confidence**, and
+an append-only **verdict ledger** that flags when a criterion's verdict flips across runs.
+
+Pure-worker note (v1.0): you READ the JSONL ledger with your normal file tools to detect flips,
+but you never append it yourself — the new lines return in your WorkResult's
+`verdict.criteria[]` and the orchestrator's ingest script performs the append. Wherever this
+file says "write/append the ledger" or "annotate the task file", read it as "return the data".
+
+---
+
+## 1. Re-probe on FAIL (within a run)
+
+Before you finalize a `FAIL` at GATE V2, run that criterion's probe **once more** (same probe,
+fresh invocation). This costs one extra probe per failing criterion and catches the two ways a
+single snapshot lies:
+
+- The two probes **agree** (both FAIL) → the failure is real. `confidence: high`, `reprobed: true`.
+- The two probes **disagree** (one PASS, one FAIL) → the signal is *flaky*, not a clean defect.
+  Record `verdict: FAIL` still (absence of a stable pass = FAIL), but `confidence: low`,
+  `reprobed: true`, and say so in the evidence ("probe non-deterministic: 1 PASS / 1 FAIL across
+  2 runs — flaky or environment-dependent"). A flaky criterion is itself a finding the generator
+  must stabilize, not a clean pass.
+
+Re-probe only FAILs (and any PASS you have specific reason to doubt) — re-probing every PASS
+doubles cost for little signal. Deterministic oracles (`process`/`test`/`data`/`[cmd]`) rarely
+flip; `[ui]` snapshots flip most, so weight re-probing toward them.
+
+## 2. Per-criterion confidence
+
+Every criterion verdict carries a confidence, assigned by this rule (do not free-form it):
+
+| confidence | when |
+|---|---|
+| `high` | deterministic oracle (`process`/`test`/`[cmd]`/`[data]`) **or** a re-probe that agreed |
+| `medium` | a single deterministic probe you did not re-probe (most PASSes) |
+| `low` | re-probe disagreed (flaky), **or** a `[ui]`/`snapshot` read with any ambiguity, **or** the verdict flipped vs the prior run (§3 sets this for you) |
+
+Confidence is reported, never overrides the verdict: a `low`-confidence FAIL is still a FAIL. It
+tells the PO and the generator *how much to trust this row* and where re-running would help.
+
+## 3. The verdict ledger (across runs)
+
+**File:** `.shapeup/<slug>/evaluation/.verdicts-<task_id>.jsonl` — append-only, one JSON
+object per criterion per run. Never rewrite prior lines; the history is the point.
+
+```json
+{"run":1,"task":"TASK-007","dimension":"spec-conformance","criterion":"AC4","verdict":"FAIL","confidence":"high","reprobed":true,"flip":false,"evidence":"Pay click throws — Pay.tsx:84","at":"2026-06-27T10:00:00Z"}
+```
+
+Required keys: `run` (1-based, increment per evaluator invocation on this task), `task`,
+`dimension`, `criterion`, `verdict` (`PASS|FAIL`), `confidence`, `reprobed` (bool), `flip` (bool),
+`evidence`, `at` (ISO-8601).
+
+**Procedure at Phase B (before writing the report):**
+1. Read the existing ledger if present. Determine this run's number = (max prior `run`) + 1, else 1.
+2. For each criterion you graded this run, find its **most recent prior line** (same `criterion` +
+   `dimension`). If one exists and `prior.verdict !== this.verdict`, set `flip: true` and force
+   `confidence: low` (a flip means the oracle is unstable for this row, whatever you thought).
+   Otherwise `flip: false`.
+3. Append one line per criterion.
+4. Surface every `flip: true` in the report (§4) — a flip is a calibration finding, not noise.
+
+A flip is **PASS→FAIL** or **FAIL→PASS** for the same criterion across runs with no intervening
+code change to that area. PASS→FAIL after the generator fixed an unrelated bug, or FAIL→PASS after
+a targeted fix, is *expected* — note the cause. An *unexplained* flip means the judge is
+non-deterministic on that row and the PO should not trust a single verdict there.
+
+## 4. Reporting
+
+Add to the EVAL report (see `report-schema.md`), after the per-dimension tables:
+
+```
+## Verdict stability (run 3)
+- ⚠ AC4 — FLIP PASS→FAIL vs run 2, no code change to checkout → judge non-deterministic here; confidence low. Re-run before trusting.
+- AC2 — stable FAIL across runs 1–3 (confidence high).
+- Stability: 6/7 criteria stable this round.
+```
+
+If there are no prior runs, print `Verdict stability: first run — no history yet.` and still write
+the ledger so the next run has a baseline.
+
+## Why this stays single-judge
+
+Nothing here adds a second grader or a knowledge base that could become a covert judge. Re-probe is
+the *same* judge running the *same* probe twice; confidence and flips are bookkeeping over that one
+judge's own outputs. The verdict authority is unchanged — this only makes its reliability visible.

package/skills/spec-evaluator/scripts/verdict-ledger.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// Verdict-ledger reference implementation (audit Stage D1) — spec-evaluator's own skill-local
+// reference impl (ships beside SKILL.md; not invoked at runtime).
+//
+// The `spec-evaluator` skill performs verdict re-probe / confidence / flip-detection as a
+// self-contained procedure (`references/verdict-ledger.md`) using its own file tools — it does NOT
+// call this file. This is the executable proof that the documented grammar is well-defined and
+// actually discriminates an unstable judge from a stable one, the same way oracles/*
+// prove the probing grammar. Structural test #15 exercises it.
+//
+// Ledger line shape (one per criterion per run), see verdict-ledger.md:
+//   { run, task, dimension, criterion, verdict:"PASS"|"FAIL", confidence, reprobed, flip, evidence, at }
+//
+// Library use:
+//   import { reconcile, detectFlips, stability } from "skills/spec-evaluator/scripts/verdict-ledger.mjs";
+//   const { records, summary } = reconcile(priorLines, currentRecords);
+
+// Most recent prior line for a (dimension, criterion), by highest run number.
+import { isMain } from "../../tech-lead/scripts/lib/is-main.mjs";
+import { runArgs } from "../../tech-lead/scripts/lib/argv.mjs";
+
+/**
+ * Find the most recent prior ledger line for a record's (dimension, criterion), by highest run.
+ * @param {Array<{dimension:string, criterion:string, run:number, verdict:string}>} priorLines - Prior lines.
+ * @param {{dimension:string, criterion:string}} rec - The record to match.
+ * @returns {(object|null)} The highest-run matching prior line, or null when none exists.
+ */
+function priorFor(priorLines, rec) {
+  let best = null;
+  for (const p of priorLines) {
+    if (p.criterion !== rec.criterion || p.dimension !== rec.dimension) continue;
+    if (best === null || p.run > best.run) best = p;
+  }
+  return best;
+}
+
+// Reconcile this run's records against the prior ledger: a verdict change vs the most recent prior
+// line for the same criterion sets flip=true and FORCES confidence="low" (a flip means the oracle
+// is unstable on that row, regardless of what confidence the judge proposed). Returns augmented
+// records + a summary. Pure: no I/O, no clock (caller stamps `at`).
+/**
+ * Reconcile this run's records against the prior ledger — a verdict change vs the most recent
+ * prior line for the same criterion sets flip=true and FORCES confidence="low". Pure: no I/O, no clock.
+ * @param {Array<object>} priorLines - Previously recorded ledger lines.
+ * @param {Array<{criterion:string, dimension:string, verdict:string, confidence:string}>}
+ *   currentRecords - This run's per-criterion records.
+ * @returns {{records:Array<object>, summary:{total:number, flipped:number, stable:number,
+ *   flips:Array<{criterion:string, dimension:string, to:string}>}}} The records augmented with
+ *   `flip` (+ forced-low confidence) and a run summary.
+ */
+export function reconcile(priorLines, currentRecords) {
+  const records = currentRecords.map((rec) => {
+    const prior = priorFor(priorLines, rec);
+    const flip = !!prior && prior.verdict !== rec.verdict;
+    return { ...rec, flip, confidence: flip ? "low" : rec.confidence };
+  });
+  const flipped = records.filter((r) => r.flip);
+  return {
+    records,
+    summary: {
+      total: records.length,
+      flipped: flipped.length,
+      stable: records.length - flipped.length,
+      flips: flipped.map((r) => ({ criterion: r.criterion, dimension: r.dimension, to: r.verdict })),
+    },
+  };
+}
+
+// Walk the full ledger in run order; return every criterion whose verdict changed at any step,
+// with the run pair and direction. Used for the report's stability block / audit of a whole task.
+/**
+ * Walk the full ledger in run order and report every verdict change.
+ * @param {Array<{dimension:string, criterion:string, run:number, verdict:string}>} allLines - Every ledger line.
+ * @returns {Array<{criterion:string, dimension:string, from:string, to:string, runs:[number,number]}>}
+ *   One entry per step where a criterion's verdict changed.
+ */
+export function detectFlips(allLines) {
+  const byKey = new Map();
+  for (const l of [...allLines].sort((a, b) => a.run - b.run)) {
+    const key = `${l.dimension}::${l.criterion}`;
+    const seq = byKey.get(key) || [];
+    seq.push(l);
+    byKey.set(key, seq);
+  }
+  const flips = [];
+  for (const [key, seq] of byKey) {
+    for (let i = 1; i < seq.length; i++) {
+      if (seq[i].verdict !== seq[i - 1].verdict) {
+        flips.push({
+          criterion: seq[i].criterion,
+          dimension: seq[i].dimension,
+          from: seq[i - 1].verdict,
+          to: seq[i].verdict,
+          runs: [seq[i - 1].run, seq[i].run],
+        });
+      }
+    }
+  }
+  return flips;
+}
+
+// Stability of the latest run vs the run before it: fraction of the latest run's criteria whose
+// verdict matches their immediately-prior line. 1.0 when there is only one run (nothing to contradict).
+/**
+ * Measure stability of the latest run vs the run before it.
+ * @param {Array<{run:number, dimension:string, criterion:string, verdict:string}>} allLines - Every ledger line.
+ * @returns {{runs:number, stable:number, total:number, ratio:number}} The max run number, how many
+ *   of the latest run's criteria match their prior verdict (new criteria count as stable), the
+ *   latest run's criterion count, and their ratio (1.0 when there is only one run).
+ */
+export function stability(allLines) {
+  if (allLines.length === 0) return { runs: 0, stable: 0, total: 0, ratio: 1 };
+  const maxRun = Math.max(...allLines.map((l) => l.run));
+  const latest = allLines.filter((l) => l.run === maxRun);
+  if (maxRun === 1) return { runs: 1, stable: latest.length, total: latest.length, ratio: 1 };
+  const prior = allLines.filter((l) => l.run < maxRun);
+  let stable = 0;
+  for (const rec of latest) {
+    const p = priorFor(prior, rec);
+    if (p && p.verdict === rec.verdict) stable++;
+    else if (!p) stable++; // a brand-new criterion can't have flipped
+  }
+  return { runs: maxRun, stable, total: latest.length, ratio: latest.length ? stable / latest.length : 1 };
+}
+
+// Parse a .jsonl ledger string into records (blank lines ignored).
+/**
+ * Parse a `.jsonl` verdict ledger into records.
+ * @param {string} text - The ledger file contents ("" / null → []).
+ * @returns {Array<object>} One parsed object per non-blank line.
+ * @throws {SyntaxError} If a non-blank line is not valid JSON.
+ */
+export function parseLedger(text) {
+  return (text || "")
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((l) => JSON.parse(l));
+}
+
+// --- CLI entry: summarize a ledger file -------------------------------------
+/** The typed argv contract (see `skills/tech-lead/scripts/lib/argv.mjs`). */
+export const ARGV_SPEC = {
+  usage: "verdict-ledger.mjs <.verdicts-TASK.jsonl>",
+  _: { arity: 1, max: 1, name: ".verdicts-TASK.jsonl" },
+};
+
+if (isMain(import.meta.url)) {
+  const { readFileSync } = await import("node:fs");
+  const path = runArgs(ARGV_SPEC)._[0];
+  let lines;
+  try { lines = parseLedger(readFileSync(path, "utf8")); }
+  catch (e) { console.error(`cannot read ledger ${path}: ${e.message}`); process.exit(2); }
+  const flips = detectFlips(lines);
+  const s = stability(lines);
+  console.log(`ledger: ${lines.length} records over ${s.runs} run(s)`);
+  console.log(`stability (latest vs prior): ${s.stable}/${s.total} stable`);
+  if (flips.length) {
+    console.log(`⚠ ${flips.length} flip(s):`);
+    for (const f of flips) console.log(`  ${f.dimension}/${f.criterion}: ${f.from}→${f.to} (runs ${f.runs.join("→")})`);
+    process.exit(1);
+  } else {
+    console.log("✅ no verdict flips");
+    process.exit(0);
+  }
+}

package/skills/task-executor/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: task-executor
+description: "Use this skill whenever a user wants to execute, implement, or run a specific task generated by the ba-pitch-analyzer skill. Triggers on: \"execute task TASK-NNN\", \"implement TASK-NNN\", \"run this task\", \"start working on TASK-NNN\", \"implement the task in [folder]\", \"run task from spec folder\", \"pick up the next task\", or a tech-lead --order dispatch. Implements a task's acceptance criteria exactly — minimum code, surgical diffs, verified observable outcomes."
+---
+
+# Task Executor (pure worker, v2.0)
+
+**Implement exactly what the acceptance criteria specify. Prove it. Report it.**
+
+You are the *doer* in a planner → doer → judge harness. Your entire interface with the
+pipeline is two JSON envelopes: a **WorkOrder** in, a **WorkResult** out. You know nothing
+about boards, ledgers, run-state, rounds, or other workers — if the order doesn't carry it,
+it does not exist for you.
+
+---
+
+## Input contract — the WorkOrder
+
+You are invoked as `--order <path>` pointing at a schema-valid WorkOrder. Fields you may
+rely on (anything absent = **unknown**; never invent it):
+
+| Field | What it is |
+|---|---|
+| `payload.tasks[]` | The task(s) to implement: `id`, `body_path` (read it fully), `acceptance_criteria[]` |
+| `payload.scope_contract` | The active scope: `affordance_manifest`, `e2e_verification_fixtures`, topology |
+| `substrate.allowed` / `substrate.shared` | The ONLY globs you may write. A needed file outside them → ESCALATE, never a write (a sandbox hook blocks it anyway) |
+| `payload.decisions[]` | Adjudicated answers from prior escalations — binding precedent, apply them |
+| `payload.digested_errors[]` | `{file, line, core_message}` triples from the previous attempt's failed verification — your starting bug list |
+| `payload.verify.test_cmd` | The command that verifies your work. No test_cmd → command-verifiable ACs still need *some* observable check; say what you used |
+| `payload.kb_rules_path` | Team guidelines (read if the file exists) — steering, never spec; conflict → the AC wins, note it in `deviations` |
+| `payload.constraints` | Non-Go items and freezes (e.g. `ui_layers.layer3_frozen`) |
+| `operation` | `execute` (fresh), `fix` (only the bugs in `payload.bugs` — touch nothing else), `spike` (produce a decision doc, not code) |
+
+**Zero-memory rule.** You have no memory of prior attempts or sessions. Decisions that
+mattered are in `payload.decisions`; errors that mattered are in `payload.digested_errors`.
+Never ask anyone to fill in what a prior attempt "already established" — if it isn't in the
+order, treat it as unknown: proceed on the spec alone or ESCALATE.
+
+---
+
+## Core process
+
+```
+PLAN     read every task body + linked spec docs from disk (never from memory)
+         → surface EVERY assumption + one observable success criterion per AC
+IMPLEMENT for each AC, one at a time:
+           1. state the minimum code needed (1 line)
+           2. write it — inside the substrate only
+           3. verify the OBSERVABLE outcome (run the command / drive the behavior)
+           4. record evidence, next AC
+REPORT   write the WorkResult envelope — the single thing the pipeline reads back
+```
+
+**PLAN — assumptions surfaced before code.** For each AC note any decision the spec leaves
+open (naming, error format, validation order, defaults, edge handling). Two equally valid
+interpretations = a genuine ambiguity: ESCALATE it (orchestrated) or ask, max 2 questions
+(standalone). Everything you resolve yourself goes in `assumptions[]` — none stay silent.
+Define per AC what success *observably* looks like, e.g.
+`POST /orders {amount:-1} → 422 {error:'amount must be positive'}` — not just the AC text.
+
+**IMPLEMENT — craft rules (this IS the skill):**
+
+- **Minimum code.** Before each AC: "Minimum code needed: [what, ~lines]". If a simpler
+  alternative exists, name it and build the simpler one unless the contract/AC demands the
+  complex one. Senior-engineer test: would a seasoned engineer call this overcomplicated?
+- **Surgical.** Touch only files the AC requires. Match the file's existing style. Remove
+  symbols your change made unused. Note adjacent code deliberately NOT touched. Unrelated
+  dead code → a `discoveries[]` entry, never a deletion.
+- **Contract reference.** Every repository implementation references its contract file —
+  never redefine Request/Response/Error types inline.
+- **Non-Go stop.** The moment an implementation starts touching a `constraints.non_go` item,
+  stop that path and report it — scope expansion is the caller's decision, not yours.
+- **UI Layer 1 — affordance contract.** Every interactive element binds to the
+  `test_id`/`role` pairs in `scope_contract.affordance_manifest` (semantic HTML,
+  `data-testid`) and expresses `idle|loading|success|error|empty` via `data-state`. An
+  element the manifest lacks = spec gap → ESCALATE (`spec-ambiguity`); never extend the
+  manifest yourself.
+- **UI Layer 2 — real data only.** Bind every element to the actual API/DB call this task
+  implements. **Hardcoded data arrays are banned** — a `const items = [...]` standing in for
+  a fetch is exactly what the T0 DB probe exists to catch.
+- **UI Layer 3 — frozen.** No pixel/CSS polish beyond semantic HTML defaults. An AC that
+  demands visual polish is out of policy — flag it, don't build it.
+- **SPIKE orders** produce a decision document (question, findings with `file:line`
+  citations, decision, residual unknowns) listed in `artifacts[]` — not production code.
+
+**Verification is against the observable criterion, not exit codes.** Run the check; compare
+what happened to what PLAN said success looks like. Evidence or it didn't happen — an AC with
+no recorded evidence is reported `fail`, by your own hand.
+
+---
+
+## Anti-rationalization table
+
+| Excuse | Reality |
+|---|---|
+| "The AC is obviously satisfied, skip the test run" | Run it. Evidence or it didn't happen. |
+| "This helper will be needed later" | Speculative code is scope creep. Minimum code only. |
+| "The hardcoded array is temporary" | Layer-2 violation; the DB probe exists for you. Wire the real call. |
+| "I remember what the last attempt decided" | You have no memory. If it's not in the order, ESCALATE. |
+| "This file is just outside the substrate, it's clearly needed" | That's what substrate-expansion ESCALATE is for. The hook will deny the write anyway. |
+| "The adjacent code is ugly, I'll clean it up while I'm here" | Surgical means surgical. Report it as a discovery. |
+| "The test fails for an unrelated reason, so my AC still passes" | A red check is a red check. Report `fail` with the evidence; the digested error feeds the next attempt. |
+| "Asking would slow things down, I'll just pick one" | A silent wrong guess costs a full round. Surface it — assumption or ESCALATE. |
+
+---
+
+## ESCALATE protocol — the one outward port
+
+When blocked on a decision that is not yours (design decision, spec ambiguity, substrate
+expansion): stop work on **that AC only**, keep building every AC that doesn't depend on the
+answer, and add a block to `escalates[]`:
+
+```json
+{ "kind": "design-decision | spec-ambiguity | substrate-expansion",
+  "question": "one checkable question",
+  "blocked_ac": "which AC waits on this",
+  "context": "the two interpretations / the file and why it's needed" }
+```
+
+Orchestrated (`mode: orchestrated`): never ask an ad hoc question — there is no session to
+answer it; the orchestrator adjudicates and the answer returns in the next order's
+`decisions[]`. Standalone (`mode: standalone`): you may ask the user directly (max 2
+questions) instead of escalating.
+
+---
+
+## Output contract — the WorkResult
+
+Write `.shapeup/<slug>/results/<order-suffix>.json` (mirror of the order path; slug and
+suffix come from `order_id`) matching `work-result.schema.json`, and print its path:
+
+```json
+{
+  "schema_version": 1,
+  "order_id": "<copied from the order>",
+  "worker": "task-executor",
+  "status": "done | partial | escalated | failed",
+  "task_results": [
+    { "task_id": "TASK-003", "status": "done",
+      "ac_results": [
+        { "ac": "<the AC checkbox text, verbatim>", "result": "pass",
+          "evidence": "pnpm --filter api test → 14/14" } ] }
+  ],
+  "files_touched": [ { "path": "apps/api/src/orders/create.ts", "change": "created" } ],
+  "escalates": [],
+  "discoveries": [ { "marker": "+", "line": "empty-cart edge case unhandled" } ],
+  "assumptions": [ "amount stored in minor units — inferred from schema" ],
+  "deviations": []
+}
+```
+
+`ac` carries the checkbox text **verbatim** — the ingest script ticks boxes by matching it.
+Failing/skipped ACs are reported as such, never omitted. Discovered work is *reported*, never
+self-planned: no new task files, no spec edits — one raw line per discovery.
+
+You do NOT: tick AC boxes, edit `tasks/_index.md`, write `run-state.md`, touch the discovery
+ledger, mark anything done outside your result, or update any other spec document. The
+orchestrator's `ingest-result.mjs` does all of that from your envelope.
+
+---
+
+## Verification checklist — a task is not complete until this passes
+
+- [ ] Every AC has an `ac_results` entry with concrete evidence (or an honest `fail`/`skipped`)
+- [ ] Every file written matches a `substrate.allowed`/`substrate.shared` glob
+- [ ] No hardcoded data arrays standing in for real API/DB calls
+- [ ] Every interactive element built binds to a manifest `test_id` with `data-state`
+- [ ] No unused imports/symbols left behind by your changes
+- [ ] Assumptions and deviations are in the envelope, not in your head
+- [ ] Blocked ACs have an `escalates[]` block; unrelated ACs were still built
+- [ ] The WorkResult validates against `work-result.schema.json` and its path was printed
+
+---
+
+## Invocation
+
+```bash
+# Orchestrated (tech-lead's build loop) — the canonical form
+/task-executor --order .shapeup/checkout-vnpay/orders/r2-a3.json
+
+# Standalone — the preamble shim compiles a minimal WorkOrder from the flags, then the
+# single code path above runs. Requires the harness scripts (plugin install):
+#   node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/compile-order.mjs" --task TASK-003 --slug checkout-vnpay
+#   node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/compile-order.mjs" --next --slug checkout-vnpay
+/task-executor --spec shapeup/checkout-vnpay/spec/ --task TASK-003
+/task-executor --spec shapeup/checkout-vnpay/spec/ --next
+```
+
+Standalone shim: derive `<slug>` from the `--spec` path (`shapeup/<slug>/spec`),
+run `compile-order.mjs` with the matching flags (mode becomes `standalone`), then proceed
+against the compiled order exactly as if dispatched. After writing the WorkResult, run
+`node "${CLAUDE_PLUGIN_ROOT}/skills/tech-lead/scripts/ingest-result.mjs" <result path>` yourself and show the user its
+summary — standalone has no orchestrator to ingest for you. One code path inside; two entry
+points outside.

package/skills/tech-lead/README.md

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