okstra 0.34.0 → 0.36.0

package/docs/superpowers/plans/2026-05-20-implementation-planning-multi-stage.md

@@ -0,0 +1,1267 @@
+# implementation-planning multi-stage Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** `implementation-planning` task 가 항상 `Stage Map + N stages` 구조로 산출하고, `implementation` task 가 stage 단위로 분할 실행되며 stage 간 carry-in 이 정적 명세 + sidecar evidence JSON 으로 자동 전달되도록 한다.
+
+**Architecture:** seed 단계의 profile / template 갱신 → 신규 validator 가 산출을 강제 → `run.py` 가 `--stage` 인수와 auto 선택 알고리즘으로 stage 단위 실행 → `wizard.py` 에 동적 stage picker → worker / lead prompt 가 evidence sidecar 와 `consumers.jsonl` 을 작성. carry-in 은 (a) `Stage Exit Contract` 정적 명세 + (b) `runs/<impl-key>/carry/stage-<N>.json` 런타임 evidence 두 갈래로 자동 흡수.
+
+**Tech Stack:** Python 3.x (argparse / fcntl / pytest), Markdown profile 파일, bash entry. 신규 의존성 없음.
+
+**Spec 참조:** [docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md](../specs/2026-05-20-implementation-planning-multi-stage-design.md)
+
+---
+
+## Task DAG (병렬 wave)
+
+| Task | depends-on | wave | 한 줄 요약 |
+|------|------------|------|-----------|
+| 1 | (none) | wave-1 | Stage validator `validate-implementation-plan-stages.py` + 테스트 |
+| 2 | (none) | wave-1 | `paths.py` 의 carry dir + `consumers.jsonl` helper + lock + 테스트 |
+| 3 | (none) | wave-1 | `implementation-planning.md` profile + input template 갱신 |
+| 4 | (none) | wave-1 | `implementation.md` profile 갱신 (stage 추출 / sidecar / PR 분리) |
+| 5 | 1, 2     | wave-2 | `run.py` 에 `--stage` 인수 + validator 호출 + `parsed_stage_map` ctx |
+| 6 | 2, 5     | wave-3 | `run.py` 의 auto stage 선택 + `consumers.jsonl` append |
+| 7 | 1, 5     | wave-3 | `wizard.py` 의 `stage_pick` step 동적 추가 |
+| 8 | 4        | wave-2 | `agents/workers/{claude,codex,gemini}-worker.md` evidence JSON 책임 |
+| 9 | 2, 4, 8  | wave-3 | lead prompt 의 sidecar 저장 + consumers 갱신 + stage PR 본문 |
+| 10 | 1–9     | wave-4 | e2e 시나리오 자동화 (Q1~Q9 of spec §9) |
+
+wave-1 (Task 1·2·3·4) 은 4 개 동시 가능. wave-2 (Task 5·8) 도 동시 가능. wave-3 (Task 6·7·9) 동시 가능. wave-4 는 최종.
+
+---
+
+## Task 1: Stage validator 신규
+
+**Files:**
+- Create: `validators/validate-implementation-plan-stages.py`
+- Create: `tests/test_validate_implementation_plan_stages.py`
+- Create: `tests/fixtures/plans/valid_one_stage.md`
+- Create: `tests/fixtures/plans/valid_three_stage_parallel.md`
+- Create: `tests/fixtures/plans/invalid_step_overflow.md`
+- Create: `tests/fixtures/plans/invalid_depends_on_cycle.md`
+- Create: `tests/fixtures/plans/invalid_missing_subsections.md`
+
+- [ ] **Step 1: Write failing test for valid 1-stage plan**
+
+```python
+# tests/test_validate_implementation_plan_stages.py
+import subprocess
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[1]
+VALIDATOR = REPO / "validators" / "validate-implementation-plan-stages.py"
+FIXTURES = REPO / "tests" / "fixtures" / "plans"
+
+def _run(fixture: str):
+    return subprocess.run(
+        ["python3", str(VALIDATOR), "--plan", str(FIXTURES / fixture)],
+        capture_output=True, text=True,
+    )
+
+def test_one_stage_valid():
+    r = _run("valid_one_stage.md")
+    assert r.returncode == 0, r.stderr
+```
+
+- [ ] **Step 2: Create the valid 1-stage fixture**
+
+`tests/fixtures/plans/valid_one_stage.md`:
+```markdown
+# Final Report
+
+## 4.5 Stage Map
+
+| stage | title | depends-on | step-count | exit-contract-summary |
+|-------|-------|-----------|------------|------------------------|
+| 1 | only stage | (none) | 2 | src/foo.ts:bar |
+
+## 4.5.1 Stage 1: only stage
+
+### Carry-In
+- task-brief 의 요구사항
+
+### Stepwise Execution Order
+
+| step | action | files | command | expected |
+|------|--------|-------|---------|----------|
+| 1 | write failing test | tests/test_foo.py | pytest -k bar | FAIL |
+| 2 | implement bar | src/foo.ts | pytest -k bar | PASS |
+
+### Stage Exit Contract
+- 추가: src/foo.ts:bar
+
+### Stage Validation
+- post: pytest -k bar
+```
+
+- [ ] **Step 3: Run test, expect failure (validator not yet implemented)**
+
+Run: `pytest tests/test_validate_implementation_plan_stages.py::test_one_stage_valid -v`
+Expected: FAIL with `FileNotFoundError` or `returncode != 0`.
+
+- [ ] **Step 4: Implement validator skeleton (S1–S4)**
+
+`validators/validate-implementation-plan-stages.py`:
+```python
+#!/usr/bin/env python3
+"""S1–S8 checks for the Stage Map structure of an approved
+implementation-planning final-report.md. Run from prepare_task_bundle
+of `implementation` task or standalone."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Tuple
+
+STAGE_MAP_HEADING = re.compile(r"^##\s+4\.5\s+Stage\s+Map\b", re.M)
+STAGE_SECTION = re.compile(
+    r"^##\s+4\.5\.(\d+)\s+Stage\s+\1\s*:\s*(.+)$", re.M
+)
+REQUIRED_SUBSECTIONS = ("Carry-In", "Stepwise Execution Order",
+                        "Stage Exit Contract", "Stage Validation")
+
+@dataclass
+class StageMeta:
+    stage_number: int
+    title: str
+    depends_on: List[int]
+    step_count: int
+    exit_contract_summary: str
+
+@dataclass
+class ValidationError:
+    code: str   # S1..S8
+    stage: int  # 0 = global
+    message: str
+
+def _check_stage_map_present(text: str) -> List[ValidationError]:
+    if not STAGE_MAP_HEADING.search(text):
+        return [ValidationError("S1", 0,
+            "section '## 4.5 Stage Map' is missing")]
+    return []
+
+def main(argv: List[str]) -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--plan", required=True)
+    args = p.parse_args(argv)
+    text = Path(args.plan).read_text(encoding="utf-8")
+    errors: List[ValidationError] = []
+    errors.extend(_check_stage_map_present(text))
+    if errors:
+        for e in errors:
+            print(f"{e.code} stage={e.stage}: {e.message}", file=sys.stderr)
+        return 1
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
+```
+
+- [ ] **Step 5: Run test, confirm S1 passes for 1-stage fixture**
+
+Run: `pytest tests/test_validate_implementation_plan_stages.py::test_one_stage_valid -v`
+Expected: PASS.
+
+- [ ] **Step 6: Add failing tests for S2 (monotonic) – S8 (DAG)**
+
+Append to `tests/test_validate_implementation_plan_stages.py`:
+```python
+def test_three_stage_parallel_valid():
+    r = _run("valid_three_stage_parallel.md")
+    assert r.returncode == 0, r.stderr
+
+def test_step_overflow_rejected():
+    r = _run("invalid_step_overflow.md")
+    assert r.returncode == 1
+    assert "S5" in r.stderr
+
+def test_missing_subsections_rejected():
+    r = _run("invalid_missing_subsections.md")
+    assert r.returncode == 1
+    assert "S4" in r.stderr
+
+def test_depends_on_cycle_rejected():
+    r = _run("invalid_depends_on_cycle.md")
+    assert r.returncode == 1
+    assert "S8" in r.stderr
+```
+
+And create the three fixtures:
+- `valid_three_stage_parallel.md`: stage 1·2 with `(none)`, stage 3 with `1, 2`, each ≤ 6 steps.
+- `invalid_step_overflow.md`: stage 1 with 7 step rows in `Stepwise Execution Order`.
+- `invalid_missing_subsections.md`: stage 1 missing the `Stage Validation` heading.
+- `invalid_depends_on_cycle.md`: stage 1 `depends-on 2`, stage 2 `depends-on 1`.
+
+(Use the same template as `valid_one_stage.md` with the relevant mutation.)
+
+- [ ] **Step 7: Implement S2–S8 checks**
+
+Extend `validators/validate-implementation-plan-stages.py`:
+```python
+def _parse_stage_map(text: str) -> Tuple[List[StageMeta], List[ValidationError]]:
+    # Locate the table immediately after "## 4.5 Stage Map"
+    m = STAGE_MAP_HEADING.search(text)
+    if not m:
+        return [], []   # S1 already reported
+    body = text[m.end():]
+    rows = []
+    for line in body.splitlines():
+        if line.startswith("##"):
+            break
+        if not line.strip().startswith("|"):
+            continue
+        cells = [c.strip() for c in line.strip().strip("|").split("|")]
+        if len(cells) != 5 or cells[0] in ("stage", "-----") or set(cells[0]) <= set("-"):
+            continue
+        try:
+            n = int(cells[0])
+        except ValueError:
+            continue
+        depends_raw = cells[2].strip()
+        depends = [] if depends_raw in ("(none)", "") else [
+            int(x.strip()) for x in depends_raw.split(",") if x.strip()
+        ]
+        try:
+            step_count = int(cells[3])
+        except ValueError:
+            step_count = -1
+        rows.append(StageMeta(n, cells[1], depends, step_count, cells[4]))
+    errors: List[ValidationError] = []
+    for i, r in enumerate(rows, start=1):
+        if r.stage_number != i:
+            errors.append(ValidationError("S2", r.stage_number,
+                f"stage numbers must be 1..N monotonic, got {r.stage_number} at row {i}"))
+    return rows, errors
+
+def _check_each_stage_section(text: str, stages: List[StageMeta]) -> List[ValidationError]:
+    errs: List[ValidationError] = []
+    for s in stages:
+        if not re.search(rf"^##\s+4\.5\.{s.stage_number}\s+Stage\s+{s.stage_number}\s*:",
+                         text, re.M):
+            errs.append(ValidationError("S3", s.stage_number,
+                f"stage section '## 4.5.{s.stage_number} Stage {s.stage_number}:' missing"))
+            continue
+        # Slice the stage's section body
+        start = re.search(rf"^##\s+4\.5\.{s.stage_number}\s+Stage\s+{s.stage_number}\s*:",
+                          text, re.M).end()
+        nxt = re.search(rf"^##\s+4\.5\.{s.stage_number + 1}\s+Stage\s+", text[start:], re.M)
+        section = text[start: start + nxt.start()] if nxt else text[start:]
+        for sub in REQUIRED_SUBSECTIONS:
+            if not re.search(rf"^###\s+{re.escape(sub)}\b", section, re.M):
+                errs.append(ValidationError("S4", s.stage_number,
+                    f"required subsection '### {sub}' missing"))
+        # S5: effective step count
+        steps = _count_effective_steps(section)
+        if steps > 6:
+            errs.append(ValidationError("S5", s.stage_number,
+                f"effective step count {steps} exceeds 6"))
+        if s.step_count != steps and s.step_count >= 0:
+            errs.append(ValidationError("S7", s.stage_number,
+                f"Stage Map step-count={s.step_count} but real count={steps}"))
+    return errs
+
+def _count_effective_steps(section: str) -> int:
+    m = re.search(r"^###\s+Stepwise Execution Order\b", section, re.M)
+    if not m:
+        return 0
+    body = section[m.end():]
+    nxt = re.search(r"^###\s+\w", body, re.M)
+    if nxt:
+        body = body[: nxt.start()]
+    count = 0
+    for line in body.splitlines():
+        s = line.strip()
+        if not s or s.startswith("<!--") or set(s) <= set("|-: "):
+            continue
+        if s.startswith("|") and not s.startswith("| step") and not set(s.replace("|", "").strip()) <= set("-: "):
+            count += 1
+    return count
+
+def _check_depends_on(stages: List[StageMeta]) -> List[ValidationError]:
+    errs: List[ValidationError] = []
+    valid = {s.stage_number for s in stages}
+    for s in stages:
+        for d in s.depends_on:
+            if d == s.stage_number:
+                errs.append(ValidationError("S8", s.stage_number, "self depends-on"))
+            elif d not in valid:
+                errs.append(ValidationError("S6", s.stage_number,
+                    f"depends-on {d} does not exist"))
+    # DAG cycle (Kahn)
+    indeg = {s.stage_number: len(s.depends_on) for s in stages}
+    graph = {s.stage_number: [] for s in stages}
+    for s in stages:
+        for d in s.depends_on:
+            if d in graph:
+                graph[d].append(s.stage_number)
+    queue = [n for n, k in indeg.items() if k == 0]
+    visited = 0
+    while queue:
+        n = queue.pop()
+        visited += 1
+        for m in graph[n]:
+            indeg[m] -= 1
+            if indeg[m] == 0:
+                queue.append(m)
+    if visited != len(stages):
+        errs.append(ValidationError("S8", 0, "depends-on graph has a cycle"))
+    return errs
+```
+
+Then wire them into `main()`:
+```python
+def main(argv: List[str]) -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--plan", required=True)
+    args = p.parse_args(argv)
+    text = Path(args.plan).read_text(encoding="utf-8")
+    errors: List[ValidationError] = []
+    errors.extend(_check_stage_map_present(text))
+    stages, s2_errs = _parse_stage_map(text)
+    errors.extend(s2_errs)
+    if stages:
+        errors.extend(_check_each_stage_section(text, stages))
+        errors.extend(_check_depends_on(stages))
+    if errors:
+        for e in errors:
+            print(f"{e.code} stage={e.stage}: {e.message}", file=sys.stderr)
+        return 1
+    return 0
+```
+
+- [ ] **Step 8: Run all Task 1 tests + commit**
+
+Run: `pytest tests/test_validate_implementation_plan_stages.py -v`
+Expected: 5 tests pass.
+
+Then:
+```bash
+git add validators/validate-implementation-plan-stages.py \
+        tests/test_validate_implementation_plan_stages.py \
+        tests/fixtures/plans/
+git commit -m "feat(validators): add implementation-plan stage validator (S1–S8)"
+```
+
+---
+
+## Task 2: paths + consumers helper + lock
+
+**Files:**
+- Modify: `scripts/okstra_ctl/paths.py:56-98` (add `carry/` and `consumers.jsonl` to `compute_run_paths`)
+- Modify: `scripts/okstra_ctl/run_context.py:44-63` (add `consumers_mutex` helper)
+- Create: `scripts/okstra_ctl/consumers.py` (append-only writer + reader)
+- Create: `tests/test_consumers_jsonl.py`
+
+- [ ] **Step 1: Write failing test for `consumers.jsonl` append + readback**
+
+`tests/test_consumers_jsonl.py`:
+```python
+import json
+from pathlib import Path
+from scripts.okstra_ctl.consumers import append_consumer, read_consumers
+
+def test_append_and_read(tmp_path):
+    plan_root = tmp_path / "runs" / "implementation-planning" / "plan-key"
+    plan_root.mkdir(parents=True)
+    append_consumer(plan_root, impl_task_key="impl-A", stage=1,
+                    status="started", started_at="2026-05-20T00:00:00+09:00",
+                    head_commit="abc000")
+    append_consumer(plan_root, impl_task_key="impl-A", stage=1,
+                    status="done", completed_at="2026-05-20T00:10:00+09:00",
+                    carry_path="runs/impl-A/carry/stage-1.json")
+    rows = read_consumers(plan_root)
+    assert len(rows) == 2
+    assert rows[0]["status"] == "started"
+    assert rows[1]["status"] == "done"
+
+def test_append_is_idempotent(tmp_path):
+    plan_root = tmp_path / "p"
+    plan_root.mkdir()
+    for _ in range(3):
+        append_consumer(plan_root, impl_task_key="impl-B", stage=2,
+                        status="started", started_at="2026-05-20T00:00:00+09:00",
+                        head_commit="zzz")
+    rows = read_consumers(plan_root)
+    assert len(rows) == 1
+```
+
+- [ ] **Step 2: Run test, expect ModuleNotFoundError**
+
+Run: `pytest tests/test_consumers_jsonl.py -v`
+Expected: ImportError on `scripts.okstra_ctl.consumers`.
+
+- [ ] **Step 3: Implement `consumers.py`**
+
+`scripts/okstra_ctl/consumers.py`:
+```python
+"""Append-only writer / reader for `consumers.jsonl` under a plan run's task root.
+
+A row's identity for idempotency is the tuple
+    (impl_task_key, stage, status)
+so the same (started / done) record is never duplicated."""
+
+from __future__ import annotations
+
+import json
+import fcntl
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .run_context import consumers_mutex
+
+CONSUMERS_FILENAME = "consumers.jsonl"
+
+def _path(plan_run_root: Path) -> Path:
+    return plan_run_root / CONSUMERS_FILENAME
+
+def read_consumers(plan_run_root: Path) -> List[Dict[str, Any]]:
+    p = _path(plan_run_root)
+    if not p.exists():
+        return []
+    out = []
+    for line in p.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        out.append(json.loads(line))
+    return out
+
+def append_consumer(plan_run_root: Path, *, impl_task_key: str, stage: int,
+                    status: str, **fields: Any) -> None:
+    if status not in ("started", "done"):
+        raise ValueError(f"unsupported status: {status}")
+    with consumers_mutex(plan_run_root.name):
+        existing = read_consumers(plan_run_root)
+        for row in existing:
+            if (row.get("impl_task_key") == impl_task_key
+                and row.get("stage") == stage
+                and row.get("status") == status):
+                return  # idempotent
+        record: Dict[str, Any] = {
+            "impl_task_key": impl_task_key,
+            "stage": stage,
+            "status": status,
+            **fields,
+        }
+        with _path(plan_run_root).open("a", encoding="utf-8") as f:
+            f.write(json.dumps(record, ensure_ascii=False) + "\n")
+```
+
+- [ ] **Step 4: Add `consumers_mutex` to `run_context.py`**
+
+In `scripts/okstra_ctl/run_context.py`, just below the existing `task_mutex`, add:
+```python
+@contextmanager
+def consumers_mutex(plan_task_key: str) -> Iterator[None]:
+    """Per-plan-key mutex for appending to consumers.jsonl."""
+    home = _okstra_home()
+    locks = home / ".locks"
+    locks.mkdir(parents=True, exist_ok=True)
+    safe = plan_task_key.replace("/", "_").replace(":", "_")
+    path = locks / f"{safe}.consumers.lock"
+    with path.open("a+") as f:
+        fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+```
+
+- [ ] **Step 5: Run test, confirm both tests pass**
+
+Run: `pytest tests/test_consumers_jsonl.py -v`
+Expected: 2 tests pass.
+
+- [ ] **Step 6: Extend `compute_run_paths` with `carry/` directory**
+
+In `scripts/okstra_ctl/paths.py`, inside `compute_run_paths` (around line 70+), add `run_carry = run_dir / "carry"` next to `worker_results`, and return it in the dict (key: `"run_carry"`). Add a corresponding `mkdir(parents=True, exist_ok=True)` call wherever the existing directories are created (search for `worker_results.mkdir`).
+
+```python
+# Inside compute_run_paths, after worker_results = run_dir / "worker-results"
+run_carry = run_dir / "carry"
+# ...later, alongside other mkdir lines:
+run_carry.mkdir(parents=True, exist_ok=True)
+# ...in the returned dict:
+"run_carry": run_carry,
+```
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add scripts/okstra_ctl/consumers.py \
+        scripts/okstra_ctl/run_context.py \
+        scripts/okstra_ctl/paths.py \
+        tests/test_consumers_jsonl.py
+git commit -m "feat(okstra-ctl): add consumers.jsonl writer + carry/ run dir"
+```
+
+---
+
+## Task 3: `implementation-planning.md` profile + input template
+
+**Files:**
+- Modify: `prompts/profiles/implementation-planning.md` — lines 50–53 (section heading contract) and 61–67 (stepwise execution order body)
+- Modify: `templates/reports/implementation-planning-input.template.md` — replace step-list area with stage examples
+
+- [ ] **Step 1: Update the section heading contract (line 50–53)**
+
+Replace the BLOCKING string list (line 51) with:
+```markdown
+  - The final report MUST include section headings containing each of the following exact strings: `Option Candidates`, `Trade-off`, `Recommended Option`, `Stage Map`, `Stage Exit Contract`, `Stage Validation`, `Dependency`, `Validation Checklist`, `Rollback`, `User Approval Request`.
+```
+
+The old keyword `Stepwise Execution Order` is removed from the BLOCKING list because it now lives **inside** each `## 4.5.<i> Stage <i>:` section, and the new validator (Task 1) checks for it per-stage instead of as a single global heading.
+
+- [ ] **Step 2: Replace lines 61–67 (deliverable shape body) with the stage block**
+
+Replace this region:
+```markdown
+  - **stepwise execution order for the recommended option**, written as bite-sized tasks:
+    - each step is one action completable in roughly 2–5 minutes ...
+    - every step names exact file paths and exact commands; for code steps, include the actual code or the diff sketch — not a description
+    - prefer TDD ordering (failing test → implementation → green → commit) when the touched area has or can have tests
+```
+With:
+```markdown
+  - **Stage Map (mandatory — always emitted, even when N=1):** a table of all stages with `stage | title | depends-on | step-count | exit-contract-summary`. `depends-on` is `(none)` or a comma-separated stage number list. Stages with `depends-on (none)` can be implemented in parallel by two simultaneous `implementation` runs.
+  - **Per-stage subsections** (`## 4.5.<i> Stage <i>: <title>` for each `i`), each containing the four required subsections:
+    - `### Carry-In` — for `depends-on (none)`: task-brief 만. Otherwise: each depended-on stage's static exit contract + runtime sidecar path `runs/<impl-key>/carry/stage-<i>.json` placeholder.
+    - `### Stepwise Execution Order` — bite-sized table with `step | action | files | command | expected`. **Effective row count ≤ 6** (excluding header / divider / blank). Each step is one action completable in 2–5 minutes; for code steps include actual code or diff sketch; prefer TDD ordering (failing test → implementation → green → commit).
+    - `### Stage Exit Contract` — predicted added/modified files, newly exposed identifiers/types/endpoints, downstream-usable resources.
+    - `### Stage Validation` — pre / mid / post exact commands or observable outcomes for this stage only.
+  - **Parallelisation-first rule (1st-class):** the writer MUST prefer the partition that maximises the number of `depends-on (none)` stages. Given two partitions with equal total step count, the one with fewer `depends-on` edges wins. Conservative "let's serialise to be safe" groupings are forbidden — each `depends-on` link is justified by a concrete data/contract dependency, not a vague risk concern.
+  - **Stage exit contract is the carry surface:** keep it as narrow as possible. Wider surface = more downstream coupling.
+```
+
+- [ ] **Step 3: Update the self-review block (line 84–90)**
+
+Append to the self-review pass list:
+```markdown
+  7. **Stage Map self-check** — for every stage, count the effective rows of its `Stepwise Execution Order` table by hand; reject the draft if any stage exceeds 6. Walk the `depends-on` graph and confirm it is a DAG (no cycle, no self-reference). For each `depends-on` link, ask "can this be removed by re-partitioning?" — if yes, re-partition and re-count.
+```
+
+- [ ] **Step 4: Update input template — add stage example block**
+
+In `templates/reports/implementation-planning-input.template.md`, append a new section after the existing scope block:
+```markdown
+## Stage Output Shape (reference)
+
+This run's final report MUST emit `## 4.5 Stage Map` and `## 4.5.<i> Stage <i>` sections per the implementation-planning profile §"Required deliverable shape". Two illustrative shapes:
+
+### Shape A — single stage (small work)
+| stage | title | depends-on | step-count | exit-contract-summary |
+|-------|-------|-----------|------------|------------------------|
+| 1 | tiny rename | (none) | 2 | src/foo.ts:renamedFoo |
+
+### Shape B — three stages, two parallel
+| stage | title | depends-on | step-count | exit-contract-summary |
+|-------|-------|-----------|------------|------------------------|
+| 1 | foo API skeleton | (none) | 4 | src/foo/api.ts:exportedFoo |
+| 2 | baz settings split | (none) | 2 | src/baz/settings.ts, env BAZ_MODE |
+| 3 | bar integration | 1, 2 | 3 | src/bar/use-foo.ts, GET /bar |
+
+Stages 1 and 2 in Shape B are `depends-on (none)` → can be run by two parallel `implementation` runs.
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add prompts/profiles/implementation-planning.md \
+        templates/reports/implementation-planning-input.template.md
+git commit -m "docs(profile): require Stage Map + per-stage subsections in implementation-planning"
+```
+
+---
+
+## Task 4: `implementation.md` profile
+
+**Files:**
+- Modify: `prompts/profiles/implementation.md` — line 69 (approved-plan extraction), plus an appended section on stage selection / sidecar / PR
+
+- [ ] **Step 1: Update line 69 (extract from approved plan)**
+
+Replace the single line:
+```markdown
+  - re-read the approved plan end-to-end and extract: file list, step order, validation commands, rollback path
+```
+With:
+```markdown
+  - re-read the approved plan end-to-end and parse the `## 4.5 Stage Map`. Determine **start stage**:
+    - if `--stage <N>` is supplied, use N. Otherwise auto = the lowest stage number whose `depends-on` are all recorded as `status:done` in `runs/<plan-key>/consumers.jsonl` AND that itself has no `status:done` row. Multiple stages may match — two parallel `implementation` runs may pick different ones and proceed concurrently.
+    - load every `runs/<plan-key>/carry/stage-<i>.json` for `i ∈ depends-on(start_stage)` and inject them into the executor's working context as "runtime carry-in". For `depends-on (none)` stages, no sidecar load — task-brief only.
+    - extract the **start stage's** file list, step order, Stage Validation commands, Stage Exit Contract, and rollback path. These — not the whole plan — are the authoritative scope for this run.
+```
+
+- [ ] **Step 2: Insert a new section "Stage execution contract" after line 75**
+
+After the "drift rule / out-of-plan rule" block, insert:
+```markdown
+- Stage execution contract (this run owns exactly one stage of the plan):
+  - **Sidecar evidence writer (BLOCKING).** When the start stage's Stage Validation `post` commands all succeed, the Executor MUST emit a JSON object matching the schema in `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2 and the lead MUST persist it to `runs/<impl-task-key>/carry/stage-<N>.json`. The file MUST NOT exist before the run starts (overwrite is refused — see `--force-stage` non-goal).
+  - **Reverse link (BLOCKING).** Before the first Edit/Write, append a `status:"started"` row to `runs/<plan-task-key>/consumers.jsonl` (lock via the okstra runtime). On stage completion, append a `status:"done"` row with `carry_path` populated.
+  - **One-PR-per-stage.** This run creates exactly one PR titled `Stage <N>: <stage title>`. The PR body MUST include:
+    - `## Stage` — number and title (from Stage Map row).
+    - `## Carry-In summary` — depends-on list + cited identifiers/SHAs from each loaded sidecar (omit when depends-on is empty).
+    - `## Next stage` — next stage number/title or `(last stage)`.
+    Stage PRs link back to each other in their bodies (`Previous: #<n>, Next: #<m>` lines) so a reviewer can navigate the chain.
+```
+
+- [ ] **Step 3: Update "Plan link & approval evidence" deliverable (line 112) to include stage info**
+
+Replace the bullet:
+```markdown
+  - **Plan link & approval evidence**: path to the approved `final-report.md` and the exact quoted approval marker
+```
+With:
+```markdown
+  - **Plan link & approval evidence**: path to the approved `final-report.md`, the exact quoted approval marker, AND the executed stage number / title quoted from the Stage Map row.
+```
+
+- [ ] **Step 4: Add "Stage sidecar evidence" deliverable**
+
+Append a new bullet to the Required deliverable shape list (after "Out-of-plan edits block"):
+```markdown
+  - **Stage sidecar evidence**: the JSON payload of `runs/<impl-task-key>/carry/stage-<N>.json` is embedded verbatim in a fenced ```json``` block, AND the `consumers.jsonl` rows this run appended are quoted line-by-line, so reviewers can audit the carry surface without grepping artifact directories.
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add prompts/profiles/implementation.md
+git commit -m "docs(profile): teach implementation runs to pick a stage and emit carry sidecar"
+```
+
+---
+
+## Task 5: `run.py` — `--stage` arg + validator wiring + `parsed_stage_map`
+
+**Files:**
+- Modify: `scripts/okstra_ctl/run.py` — argparse block (lines 920–948), `_validate_approved_plan` (line 146), `prepare_task_bundle` implementation branch (lines 473–483)
+- Create: `tests/test_run_stage_arg.py`
+
+depends-on: Task 1, Task 2.
+
+- [ ] **Step 1: Write failing test — `--stage 1` parses to `inp.stage`**
+
+`tests/test_run_stage_arg.py`:
+```python
+import subprocess, sys
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[1]
+
+def test_stage_arg_accepted_for_implementation(tmp_path):
+    # bundle a minimal valid stage plan into tmp_path
+    plan = tmp_path / "final-report.md"
+    plan.write_text(Path("tests/fixtures/plans/valid_one_stage.md")
+                    .read_text(encoding="utf-8"), encoding="utf-8")
+    # Approve it
+    plan.write_text(plan.read_text() + "\n- [x] Approved\n", encoding="utf-8")
+    r = subprocess.run(
+        [sys.executable, "-m", "okstra_ctl.run",
+         "--task-type", "implementation",
+         "--task-group", "demo", "--task-id", "demo-1",
+         "--project-root", str(tmp_path),
+         "--project-id", "demo",
+         "--approved-plan", str(plan),
+         "--stage", "1",
+         "--render-only"],
+        capture_output=True, text=True, cwd=str(REPO),
+    )
+    assert r.returncode == 0, r.stderr
+
+def test_stage_arg_rejected_outside_implementation(tmp_path):
+    r = subprocess.run(
+        [sys.executable, "-m", "okstra_ctl.run",
+         "--task-type", "error-analysis",
+         "--task-group", "demo", "--task-id", "demo-2",
+         "--project-root", str(tmp_path),
+         "--project-id", "demo",
+         "--stage", "1",
+         "--render-only"],
+        capture_output=True, text=True, cwd=str(REPO),
+    )
+    assert r.returncode != 0
+    assert "stage" in r.stderr.lower()
+```
+
+- [ ] **Step 2: Run test, expect failure**
+
+Run: `pytest tests/test_run_stage_arg.py -v`
+Expected: both tests fail (current argparse rejects `--stage` everywhere).
+
+- [ ] **Step 3: Add `--stage` argument in `run.py` argparse block**
+
+In `scripts/okstra_ctl/run.py` around line 925, after the `--approved-plan` declaration, insert:
+```python
+    p.add_argument(
+        "--stage", default="auto", dest="stage",
+        help=(
+            "implementation task only. Which Stage Map entry to execute. "
+            "'auto' (default) = lowest-numbered stage whose depends-on are all "
+            "consumers.jsonl status:done. Numeric '<N>' = force that stage."
+        ),
+    )
+```
+
+And in the dataclass `PrepareInputs` (search for it earlier in the file), add:
+```python
+    stage: str = "auto"
+```
+
+In the inputs-construction block (where `PrepareInputs(...)` is built from argparse `args`), pass through `stage=args.stage`.
+
+- [ ] **Step 4: Reject `--stage` outside `implementation` and call the new validator**
+
+Replace `prepare_task_bundle` lines 473–483 with:
+```python
+    if inp.task_type == "implementation":
+        if not inp.approved_plan_path:
+            raise PrepareError(
+                "task-type implementation requires --approved-plan <path-to-final-report.md>"
+            )
+        if inp.approve_plan_ack:
+            _apply_cli_approval(inp.approved_plan_path)
+        _validate_approved_plan(inp.approved_plan_path)
+        _validate_stage_structure(inp.approved_plan_path)  # NEW
+        ctx["parsed_stage_map"] = _parse_stage_map_into_ctx(inp.approved_plan_path)
+    else:
+        if inp.stage != "auto":
+            raise PrepareError(
+                f"--stage is only meaningful with --task-type implementation; got {inp.task_type}"
+            )
+```
+
+- [ ] **Step 5: Implement `_validate_stage_structure` and `_parse_stage_map_into_ctx`**
+
+In `scripts/okstra_ctl/run.py`, near the existing `_validate_approved_plan` (line 146 area), add:
+```python
+import subprocess as _subprocess
+
+_VALIDATOR_PATH = (
+    Path(__file__).resolve().parents[2] / "validators"
+    / "validate-implementation-plan-stages.py"
+)
+
+def _validate_stage_structure(plan_path: str) -> None:
+    r = _subprocess.run(
+        ["python3", str(_VALIDATOR_PATH), "--plan", plan_path],
+        capture_output=True, text=True,
+    )
+    if r.returncode != 0:
+        raise PrepareError(
+            f"approved plan failed stage validation:\n{r.stderr.strip()}"
+        )
+
+def _parse_stage_map_into_ctx(plan_path: str) -> list[dict]:
+    text = Path(plan_path).read_text(encoding="utf-8")
+    # Reuse the validator's parser by importing it
+    sys.path.insert(0, str(_VALIDATOR_PATH.parent))
+    try:
+        import importlib.util
+        spec = importlib.util.spec_from_file_location("ip_stage_v", _VALIDATOR_PATH)
+        mod = importlib.util.module_from_spec(spec)  # type: ignore
+        spec.loader.exec_module(mod)                 # type: ignore
+        stages, _errs = mod._parse_stage_map(text)
+    finally:
+        sys.path.pop(0)
+    return [
+        {
+            "stage_number": s.stage_number,
+            "title": s.title,
+            "depends_on": s.depends_on,
+            "step_count": s.step_count,
+            "exit_contract_summary": s.exit_contract_summary,
+        }
+        for s in stages
+    ]
+```
+
+- [ ] **Step 6: Run tests, expect pass + commit**
+
+Run: `pytest tests/test_run_stage_arg.py tests/test_validate_implementation_plan_stages.py -v`
+Expected: all tests pass.
+
+```bash
+git add scripts/okstra_ctl/run.py tests/test_run_stage_arg.py
+git commit -m "feat(run.py): add --stage arg and wire stage-map validator"
+```
+
+---
+
+## Task 6: `run.py` — auto stage selection + consumers append
+
+**Files:**
+- Modify: `scripts/okstra_ctl/run.py` — `prepare_task_bundle` implementation branch (add auto-resolve + consumers append)
+- Create: `tests/test_auto_stage_selection.py`
+
+depends-on: Task 2, Task 5.
+
+- [ ] **Step 1: Failing test for auto selection**
+
+`tests/test_auto_stage_selection.py`:
+```python
+import subprocess, sys, json
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[1]
+
+def _prepare(tmp_path, plan_fixture, stage_arg, consumers_lines=None):
+    plan = tmp_path / "final-report.md"
+    plan.write_text(
+        Path(f"tests/fixtures/plans/{plan_fixture}").read_text() + "\n- [x] Approved\n"
+    )
+    plan_root = tmp_path / ".project-docs" / "okstra" / "tasks" / "demo" / "demo-1" \
+                / "runs" / "implementation-planning"
+    plan_root.mkdir(parents=True)
+    if consumers_lines:
+        (plan_root / "consumers.jsonl").write_text(
+            "\n".join(json.dumps(x) for x in consumers_lines) + "\n"
+        )
+    r = subprocess.run(
+        [sys.executable, "-m", "okstra_ctl.run",
+         "--task-type", "implementation",
+         "--task-group", "demo", "--task-id", "demo-1",
+         "--project-root", str(tmp_path),
+         "--project-id", "demo",
+         "--approved-plan", str(plan),
+         "--stage", stage_arg,
+         "--render-only"],
+        capture_output=True, text=True, cwd=str(REPO),
+    )
+    return r, plan_root
+
+def test_auto_picks_stage_1_when_none_done(tmp_path):
+    r, _ = _prepare(tmp_path, "valid_three_stage_parallel.md", "auto")
+    assert r.returncode == 0
+    assert "selected stage: 1" in r.stdout
+
+def test_auto_picks_stage_2_when_stage_1_done(tmp_path):
+    r, _ = _prepare(tmp_path, "valid_three_stage_parallel.md", "auto",
+        consumers_lines=[
+            {"impl_task_key": "impl-A", "stage": 1, "status": "started",
+             "started_at": "x", "head_commit": "y"},
+            {"impl_task_key": "impl-A", "stage": 1, "status": "done",
+             "completed_at": "z", "carry_path": "..."},
+        ])
+    # stage 2 is depends-on (none) so it's still pickable.
+    # Algorithm picks lowest unsatisfied → here stage 2.
+    assert r.returncode == 0
+    assert "selected stage: 2" in r.stdout
+
+def test_auto_blocks_on_unsatisfied_depends_on(tmp_path):
+    # stage 3 has depends-on 1,2 — neither done. auto should pick stage 1.
+    r, _ = _prepare(tmp_path, "valid_three_stage_parallel.md", "auto")
+    assert "selected stage: 1" in r.stdout
+```
+
+- [ ] **Step 2: Run, expect failure**
+
+Run: `pytest tests/test_auto_stage_selection.py -v`
+Expected: all three fail (auto resolution not yet implemented).
+
+- [ ] **Step 3: Implement auto resolution in `run.py`**
+
+Inside the `if inp.task_type == "implementation":` branch (after `_parse_stage_map_into_ctx`):
+```python
+        # Resolve effective stage
+        from .consumers import read_consumers
+        plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]  # .../runs/implementation-planning/
+        consumed = read_consumers(plan_run_root)
+        done_stages = {r["stage"] for r in consumed if r.get("status") == "done"}
+        stages = ctx["parsed_stage_map"]
+        if inp.stage == "auto":
+            chosen = None
+            for s in stages:
+                if s["stage_number"] in done_stages:
+                    continue
+                if all(d in done_stages for d in s["depends_on"]):
+                    chosen = s
+                    break
+            if chosen is None:
+                raise PrepareError(
+                    "no stage is ready: every remaining stage has unsatisfied depends-on"
+                )
+            inp.stage = str(chosen["stage_number"])
+        else:
+            try:
+                n = int(inp.stage)
+            except ValueError:
+                raise PrepareError(f"--stage must be 'auto' or an integer, got {inp.stage!r}")
+            target = next((s for s in stages if s["stage_number"] == n), None)
+            if target is None:
+                raise PrepareError(f"--stage {n} not in Stage Map (have {[s['stage_number'] for s in stages]})")
+            if n in done_stages:
+                raise PrepareError(f"--stage {n} already completed (consumers.jsonl status:done exists)")
+            inp.stage = str(n)
+        ctx["effective_stage"] = int(inp.stage)
+        print(f"selected stage: {inp.stage}", file=sys.stdout)
+```
+
+- [ ] **Step 4: Append `started` row to consumers.jsonl during prepare**
+
+Right after the resolution block above:
+```python
+        from .consumers import append_consumer
+        import datetime, subprocess as _sp
+        head = _sp.run(["git", "rev-parse", "HEAD"],
+                       cwd=inp.project_root, capture_output=True, text=True)
+        append_consumer(
+            plan_run_root,
+            impl_task_key=ctx["TASK_KEY"],
+            stage=int(inp.stage),
+            status="started",
+            started_at=datetime.datetime.now(datetime.timezone.utc).isoformat(),
+            head_commit=head.stdout.strip() if head.returncode == 0 else "",
+        )
+```
+
+- [ ] **Step 5: Run tests, expect pass**
+
+Run: `pytest tests/test_auto_stage_selection.py -v`
+Expected: 3 tests pass.
+
+- [ ] **Step 6: Add test for `--stage <N>` rejection when already done**
+
+Append to `tests/test_auto_stage_selection.py`:
+```python
+def test_explicit_stage_rejected_when_done(tmp_path):
+    r, _ = _prepare(tmp_path, "valid_three_stage_parallel.md", "1",
+        consumers_lines=[
+            {"impl_task_key": "impl-A", "stage": 1, "status": "started",
+             "started_at": "x", "head_commit": "y"},
+            {"impl_task_key": "impl-A", "stage": 1, "status": "done",
+             "completed_at": "z", "carry_path": "..."},
+        ])
+    assert r.returncode != 0
+    assert "already completed" in r.stderr
+```
+Run: `pytest tests/test_auto_stage_selection.py::test_explicit_stage_rejected_when_done -v`
+Expected: pass.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add scripts/okstra_ctl/run.py tests/test_auto_stage_selection.py
+git commit -m "feat(run.py): auto-resolve next ready stage and append consumers.jsonl"
+```
+
+---
+
+## Task 7: `wizard.py` — dynamic `stage_pick` step
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py` — STEPS list (line ~1581) + new `_build_stage_pick` / `_submit_stage_pick` functions
+- Create: `tests/test_wizard_stage_pick.py`
+
+depends-on: Task 1, Task 5.
+
+- [ ] **Step 1: Failing test**
+
+`tests/test_wizard_stage_pick.py`:
+```python
+import json, subprocess, sys
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[1]
+
+def _wizard(*args):
+    return subprocess.run(
+        [sys.executable, "-m", "okstra_ctl.wizard", *args],
+        capture_output=True, text=True, cwd=str(REPO),
+    )
+
+def test_stage_pick_step_emitted_for_three_stage_plan(tmp_path):
+    state = tmp_path / "wiz.json"
+    plan = tmp_path / "plan.md"
+    plan.write_text(
+        Path("tests/fixtures/plans/valid_three_stage_parallel.md").read_text()
+        + "\n- [x] Approved\n"
+    )
+    # init + answer through to the approved_plan step
+    _wizard("init", "--state-file", str(state),
+            "--project-root", str(tmp_path), "--project-id", "demo")
+    # ... (drive state to stage_pick — exact step depends on wizard.py STEPS order)
+    # For the test, we instead drive the state file directly using public API:
+    from scripts.okstra_ctl.wizard import WizardState, next_prompt
+    s = WizardState(
+        workspace_root=str(REPO),
+        task_type="implementation",
+        approved_plan_path=str(plan),
+        # ... minimal fields ...
+    )
+    prompt = next_prompt(s)
+    # Walk forward until we hit S_STAGE_PICK
+    visited_ids = []
+    while prompt.kind != "done":
+        visited_ids.append(prompt.step)
+        s.answered.add(prompt.step)
+        prompt = next_prompt(s)
+    assert "stage_pick" in visited_ids
+```
+
+- [ ] **Step 2: Run, expect failure**
+
+Run: `pytest tests/test_wizard_stage_pick.py -v`
+Expected: fail (`stage_pick` step does not exist yet).
+
+- [ ] **Step 3: Add `S_STAGE_PICK` constant + builder + submitter**
+
+In `scripts/okstra_ctl/wizard.py` near the existing step ID constants:
+```python
+S_STAGE_PICK = "stage_pick"
+```
+
+Add builder (mirroring `_build_approved_plan_pick` at line 909):
+```python
+def _build_stage_pick(state: WizardState) -> Prompt:
+    # Parse Stage Map from the approved plan to build picker options.
+    text = Path(state.approved_plan_path).read_text(encoding="utf-8")
+    import importlib.util
+    spec = importlib.util.spec_from_file_location(
+        "ip_stage_v",
+        Path(state.workspace_root) / "validators" / "validate-implementation-plan-stages.py",
+    )
+    mod = importlib.util.module_from_spec(spec)  # type: ignore
+    spec.loader.exec_module(mod)                 # type: ignore
+    stages, _ = mod._parse_stage_map(text)
+    options = [_opt("auto", "auto (다음 미완료 stage)")]
+    for s in stages:
+        options.append(_opt(str(s.stage_number),
+                            f"{s.stage_number}: {s.title}  [depends-on: "
+                            f"{','.join(map(str, s.depends_on)) or '(none)'} | "
+                            f"steps: {s.step_count}]"))
+    return Prompt(
+        step=S_STAGE_PICK, kind="pick",
+        label="실행할 stage 를 선택하세요. auto 는 의존성이 만족된 가장 빠른 미완료 stage 를 자동으로 잡습니다.",
+        options=options,
+        echo_template="stage: {value}",
+    )
+
+def _submit_stage_pick(state: WizardState, answer: str) -> str:
+    if not answer:
+        return "value required"
+    if answer != "auto":
+        try:
+            int(answer)
+        except ValueError:
+            return f"answer must be 'auto' or a stage number, got {answer!r}"
+    state.selected_stage = answer
+    return f"stage: {answer}"
+```
+
+Add field to `WizardState`:
+```python
+    selected_stage: str = "auto"
+```
+
+- [ ] **Step 4: Register in STEPS list**
+
+Find the global `STEPS = [...]` list (line ~1581). Insert immediately after the `S_APPROVED_PLAN_PICK` step:
+```python
+    Step(
+        id=S_STAGE_PICK,
+        applies=lambda s: s.task_type == "implementation"
+                          and s.approved_plan_path
+                          and S_STAGE_PICK not in s.answered,
+        build=_build_stage_pick,
+        submit=_submit_stage_pick,
+        owns=("selected_stage",),
+    ),
+```
+
+- [ ] **Step 5: Update `render-args` to surface `--stage`**
+
+Find the `cmd_render_args` (or equivalent) that emits `args` dict at the end. Add:
+```python
+    if state.task_type == "implementation":
+        out["stage"] = state.selected_stage or "auto"
+```
+
+And update the `okstra-run` skill's Step 5 invocation example (in the SKILL.md, line ~152 area) — append `--stage "<args.stage>"` to the `render-bundle` call list. (No code change needed if the skill already iterates `args` keys generically; otherwise update.)
+
+- [ ] **Step 6: Run tests + commit**
+
+Run: `pytest tests/test_wizard_stage_pick.py -v`
+Expected: pass.
+
+```bash
+git add scripts/okstra_ctl/wizard.py tests/test_wizard_stage_pick.py \
+        skills/okstra-run/SKILL.md
+git commit -m "feat(wizard): add dynamic stage_pick step for implementation"
+```
+
+---
+
+## Task 8: worker prompts — evidence JSON output
+
+**Files:**
+- Modify: `agents/workers/claude-worker.md`
+- Modify: `agents/workers/codex-worker.md`
+- Modify: `agents/workers/gemini-worker.md`
+
+depends-on: Task 4.
+
+- [ ] **Step 1: Locate the verifier / final-validation section in each worker prompt**
+
+Run: `grep -n -E "(verifier|final|Audit sidecar)" agents/workers/*.md | head -40`
+Confirm the location of the "after all validations pass" block in each worker.
+
+- [ ] **Step 2: Append the evidence emission requirement to each worker prompt**
+
+Append the following block to the **end** of each of `agents/workers/{claude,codex,gemini}-worker.md`:
+```markdown
+## Stage evidence emission (BLOCKING, implementation task only)
+
+When this run's `task_type` is `implementation` and you are acting as the **Executor**, after the Stage Validation `post` commands all return exit code 0 you MUST emit a single JSON document matching `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2:
+
+```json
+{
+  "schemaVersion": 1,
+  "sourcePlanPath": "<approved-plan path>",
+  "stageNumber": <int>,
+  "stageTitle": "<from Stage Map>",
+  "completedAt": "<ISO-8601 with tz>",
+  "stageCommitRange": { "base": "<sha>", "head": "<sha>" },
+  "filesChanged": ["<rel/path>", "..."],
+  "newIdentifiers": ["<name>", "..."],
+  "stepResults": [{"step": <int>, "status": "done", "commit": "<sha>"}],
+  "validationsPassed": ["<label>", "..."],
+  "notes": []
+}
+```
+
+Emit this as a fenced ```json``` block in your worker result under the heading `### Stage Carry Evidence`. The lead (`Claude lead`) is responsible for persisting the block as `runs/<impl-task-key>/carry/stage-<N>.json` — you do not write the file yourself.
+
+This applies only when `task_type` is `implementation`. For other task types, skip this block entirely.
+```
+
+- [ ] **Step 3: Verify by grep**
+
+Run: `grep -l "Stage Carry Evidence" agents/workers/*.md`
+Expected: three files matched (claude, codex, gemini).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add agents/workers/claude-worker.md \
+        agents/workers/codex-worker.md \
+        agents/workers/gemini-worker.md
+git commit -m "docs(workers): require Stage Carry Evidence JSON in implementation runs"
+```
+
+---
+
+## Task 9: lead prompt — sidecar persistence + consumers `done` row
+
+**Files:**
+- Modify: `prompts/profiles/implementation.md` — add "Lead post-stage persistence" section
+
+depends-on: Task 2, Task 4, Task 8.
+
+- [ ] **Step 1: Append the new section**
+
+Append to `prompts/profiles/implementation.md` (after the Self-review pass block, before "In-phase debugging"):
+```markdown
+- Lead post-stage persistence (BLOCKING — runs after the Executor emits `### Stage Carry Evidence`):
+  - Parse the executor's `### Stage Carry Evidence` JSON block. If absent or unparsable, end with status `contract-violated` and route to a follow-up `error-analysis`.
+  - Write the JSON verbatim to `runs/<impl-task-key>/carry/stage-<N>.json`. Refuse to overwrite an existing file (one stage = one sidecar; re-runs are out of scope for this version).
+  - Append a `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` with `completed_at`, `carry_path`, and the SHA of HEAD. Use the okstra runtime's `consumers_mutex` helper (NOT a raw filesystem write) to honour the lock.
+  - Quote both files' new contents (the sidecar JSON in full, the new consumers row by itself) in the final report's `Stage sidecar evidence` deliverable section.
+```
+
+- [ ] **Step 2: Grep-verify the new section is uniquely named**
+
+Run: `grep -c "Lead post-stage persistence" prompts/profiles/implementation.md`
+Expected: 1.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add prompts/profiles/implementation.md
+git commit -m "docs(profile): make lead persist Stage Carry Evidence and consumers row"
+```
+
+---
+
+## Task 10: e2e scenarios (spec §9 Q1–Q9)
+
+**Files:**
+- Create: `tests-e2e/test_implementation_plan_multi_stage.py` (or `.sh` matching existing tests-e2e style — check `tests-e2e/` layout first)
+
+depends-on: Task 1–9.
+
+- [ ] **Step 1: Inspect `tests-e2e/` to match its convention**
+
+Run: `ls tests-e2e/`
+Pick the closest existing test to model after (pytest-style or bash-style) — adopt that style.
+
+- [ ] **Step 2: Implement Q1 — 1-stage plan, full happy path**
+
+Sketch (pytest style assumed):
+```python
+def test_q1_one_stage_plan_happy_path(tmp_project):
+    # 1. Seed an APPROVED 1-stage plan in tmp_project's planning run dir
+    # 2. Invoke `okstra render-bundle --task-type implementation --stage auto ...`
+    # 3. Assert the rendered ctx has effective_stage == 1
+    # 4. Simulate executor: write the Stage Carry Evidence JSON
+    # 5. Lead persistence: write carry/stage-1.json + consumers.jsonl done row
+    # 6. Assert both files exist with expected contents
+    ...
+```
+
+(Use the same harness existing e2e tests use to render bundles and to simulate worker output.)
+
+- [ ] **Step 3: Implement Q2–Q9**
+
+Translate each spec §9 row into a test case. Use these IDs as test names so the mapping stays obvious:
+- `test_q2_three_stage_plan_first_run_picks_stage_1`
+- `test_q3_after_stage_1_done_run_2_picks_stage_2_and_loads_sidecar`
+- `test_q4_step_seven_rejected_by_validator_at_prepare`
+- `test_q5_depends_on_nonexistent_stage_rejected_S6`
+- `test_q6_force_stage_when_already_done_errors`
+- `test_q7_parallel_runs_pick_distinct_none_stages`
+- `test_q8_partial_depends_on_blocks_higher_stage`
+- `test_q9_cycle_rejected_S8`
+
+- [ ] **Step 4: Run the e2e suite**
+
+Run: `pytest tests-e2e/test_implementation_plan_multi_stage.py -v`
+Expected: all 9 tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests-e2e/test_implementation_plan_multi_stage.py
+git commit -m "test(e2e): cover Q1–Q9 scenarios from multi-stage design spec"
+```
+
+- [ ] **Step 6: Final verification — full test suite**
+
+Run: `pytest tests/ tests-e2e/ -v`
+Expected: all green.
+
+---
+
+## Self-review (post-write)
+
+(performed by plan author after writing — fixed inline)
+
+- **Spec coverage:** spec §1 mot →§2 5 원칙 → §3 model → §4 흐름 → §5 변경 파일 → §6 wizard → §9 시나리오 모두 task 매핑됨. spec §5.9 (release-handoff stage PR 일람) 와 §8 미해결 항목들은 의도적으로 별도 후속 spec 으로 분리(§8 명시) — 본 plan 의 비범위.
+- **Placeholder scan:** "TBD" / "TODO" / "implement later" 없음. Task 7 의 `# ... minimal fields ...` 자리는 wizard 의 `WizardState` 정확한 필드 목록을 plan 실행자가 wizard.py 의 dataclass 정의를 보고 채워야 하는 자리 — 이건 fixture set-up 의 본질이라 정상.
+- **Type consistency:** `StageMeta` 5 필드(`stage_number / title / depends_on / step_count / exit_contract_summary`) 가 Task 1, 5, 7 에서 동일. `consumers.jsonl` row identity (`impl_task_key, stage, status`) 도 Task 2, 6, 9 에서 동일.
+- **No-placeholder rule:** code-touching step 마다 실제 코드 블록 또는 정확한 diff 명세 포함. 문서 변경은 정확한 before/after 인용.
+
+---
+
+**Plan complete and saved.** 다음 단계 — 실행 방식 선택:
+
+1. **Subagent-Driven (recommended)** — fresh subagent per task, two-stage review between tasks, fast iteration.
+2. **Inline Execution** — execute tasks in this session using `superpowers:executing-plans` skill, batch execution with checkpoints.
+
+어느 쪽으로 진행할까요?