okstra 0.63.0 → 0.64.0

package/runtime/agents/SKILL.md

@@ -91,6 +91,7 @@ Required checkpoints:
 - `PROGRESS: phase-2-prompts preparing <N> worker prompts` — at the start of Phase 2, before any `Write` to the assigned prompt paths.
 - `PROGRESS: phase-3-team-create attempting TeamCreate` — immediately before the `TeamCreate` call.
 - `PROGRESS: phase-4-dispatch worker=<role> model=<model>` — once per worker, immediately before the `Agent` / wrapper call.
+- `PROGRESS: phase-5-poll pending=<n> done=<m>` — emitted on each wakeup while the pending set is non-empty.
 - `PROGRESS: phase-5-collect worker=<role> status=<terminal-status>` — once per worker, immediately after the result file is verified.
 - `PROGRESS: phase-5.5-convergence round=<N> queue=<count>` — at the start of each convergence round (Phase 5.5).
 - `PROGRESS: phase-5.6-critic provider=<provider> gaps=<n>` — when the coverage critic pass runs (Phase 5.6, opt-in). Omitted when `convergence.critic.enabled == false`.
@@ -226,6 +227,8 @@ Spawn **analysis workers only** in the same turn (Phase 4 in Teams mode; Phase 5
 
 The no-`team_name` fallback (Phase 5) is only legal when team-state's `teamCreate.status` is `"error"` for this run. If `teamCreate` is missing or `attempted: false`, the correct action when an Agent dispatch is rejected for a missing team is to GO BACK to Phase 3 and call `TeamCreate` — never to strip `team_name` and continue.
 
+**Completion detection after dispatch (BLOCKING).** The `Agent(... team_name ...)` call returns `Spawned successfully` immediately; that ack is NOT completion. After dispatching the analysis workers (async), Lead MUST detect their completion via the self-scheduled polling protocol in [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) "Worker-completion detection (self-scheduled polling)" — do NOT restate the algorithm here. Lead MUST NOT end its turn with a prose "waiting for workers" statement; that path stalls the run until the user manually nudges it.
+
 ### Errors log path wiring (BLOCKING)
 
 The launch prompt's `## Run Logs (error-log wiring)` section gives Lead the resolved absolute paths for the run-level errors log and every per-worker sidecar. When Lead constructs each worker's dispatch prompt body, Lead MUST inject the matching two header lines verbatim:
@@ -314,7 +317,7 @@ Distinct from Phase 5.5 finding convergence:
 
 Lead's responsibilities in this sub-step (in order):
 
-1. Extract `P-*` plan items from the draft report's `## 5.5 Implementation Plan Deliverables` per the prefix → source-section mapping in the convergence skill.
+1. Extract `P-*` plan items from the draft report's `## 5.4 Implementation Plan Deliverables` per the prefix → source-section mapping in the convergence skill.
 2. Dispatch a single plan-body reverify round to every analyser worker in the roster (`claude`, `codex`, and `gemini` when opted in). `Report writer worker` is NOT a participant in this round.
 3. Aggregate verdicts and resolve the gate result to one of `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`.
 4. Write `runs/<task-type>/state/plan-body-verification.json` (schema in the convergence skill).
@@ -378,7 +381,7 @@ After persistence, reply briefly in the resolved Report Language with: completio
 | Letting `convergence.maxRounds` default to 2 for `requirements-discovery` | Resolve effective default to `1` for discovery and record in convergence state artifact |
 | Issuing serial Read calls in Phase 1 | The intake files are independent — issue all Read calls in a single message (parallel) |
 | Flagging the claude-worker dispatch prompt as "incomplete" because it lacks `[Required reading]` / `[Error reporting]` blocks | Intentional asymmetry — see [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) "Asymmetry between claude-worker and codex/gemini-worker prompts" |
-| Waiting silently while the dispatched `claude-worker` Agent call returns nothing for many minutes (the dev-9495 pattern: two 28+25-minute hangs before lead manually `tmux kill-pane`d) | The claude-worker MUST append a `- PROGRESS: <stage> <ISO-UTC>` line to its audit sidecar (`runs/<task-type>/worker-results/claude-worker-audit-<task-type>-<seq>.md`) at least every 5 minutes (see `agents/workers/claude-worker.md` "Heartbeat" rule). If the sidecar is absent or its mtime is >5 minutes stale, treat the dispatch as `timeout` and redispatch once with a byte-identical prompt; after a second silent hang, record terminal status `timeout` with the missing-sidecar reason in team-state. Lead cannot poll mid-Agent-call but MUST inspect the audit sidecar immediately when the Agent call finally returns — a missing sidecar after `completed` is itself a contract violation per the heartbeat rule |
+| Waiting silently while the dispatched `claude-worker` Agent call returns nothing for many minutes (the dev-9495 pattern: two 28+25-minute hangs before lead manually `tmux kill-pane`d) | The claude-worker MUST append a `- PROGRESS: <stage> <ISO-UTC>` line to its audit sidecar (`runs/<task-type>/worker-results/claude-worker-audit-<task-type>-<seq>.md`) at least every 5 minutes (see `agents/workers/claude-worker.md` "Heartbeat" rule). If the sidecar is absent or its mtime is >5 minutes stale, treat the dispatch as `timeout` and redispatch once with a byte-identical prompt; after a second silent hang, record terminal status `timeout` with the missing-sidecar reason in team-state. The authoritative completion signal is the **result file's appearance**, detected via self-scheduled polling (see [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) "Worker-completion detection (self-scheduled polling)") — NOT the Agent-call return, which under `team_name` dispatch is just an immediate `Spawned successfully` ack. The heartbeat sidecar is an auxiliary liveness signal layered on top: a missing sidecar after the result file appears is itself a contract violation per the heartbeat rule |
 | Re-sending confirmed findings (`full-consensus`/`partial-consensus`/`worker-unique`) to a worker in Round 2 | Queue pruning rule — see [okstra-convergence](./skills/okstra-convergence/SKILL.md) "Round 1-N: Re-verification Loop (queue-pruned)" |
 | Aggregating a `timeout`/`error` reverify dispatch as `DISAGREE` | Worker failure handling — record as `verification-error` and add to `skippedWorkers[]`. See [okstra-convergence](./skills/okstra-convergence/SKILL.md) "Worker failure handling in reverify" |
 | Skipping `--substitute-data` in the Phase 7 collector run | Always pass the flag — see [okstra-report-writer](./skills/okstra-report-writer/SKILL.md) "Phase 7 token-usage collector" |

package/runtime/agents/TODO.md

@@ -96,7 +96,11 @@ Lead가 implementation.md 프로필을 따라 Phase 4 dispatch를 시도할 때:
 
 ---
 
-## 수정 B — Leader-side 워커 soft timeout 도입
+## 수정 B — Leader-side 워커 soft timeout 도입 [해결됨, 2026-06-10]
+
+### 해결 메모 (2026-06-10)
+
+본 항목이 요구한 per-worker soft-timeout 안전장치는 self-scheduled polling 작업으로 구현됐다. lead 가 백그라운드 폴링 루프를 띄울 때 거는 `deadline=$((SECONDS + <per-worker-deadline-seconds>))` 가드([skills/okstra-team-contract/SKILL.md:134](../skills/okstra-team-contract/SKILL.md:134))가 워커별 마감을 강제하고, 초과 시 폴링이 `POLL_TIMEOUT` 으로 종료된다([skills/okstra-team-contract/SKILL.md:136](../skills/okstra-team-contract/SKILL.md:136)). 규약은 "Worker-completion detection (self-scheduled polling)" 섹션([skills/okstra-team-contract/SKILL.md:124](../skills/okstra-team-contract/SKILL.md:124))에 정본으로 명세돼 있다. 설계 근거는 [docs/superpowers/specs/2026-06-10-lead-worker-completion-polling-design.md](../docs/superpowers/specs/2026-06-10-lead-worker-completion-polling-design.md) 참고. 아래 배경/초안 분석은 당시 기록으로 보존한다.
 
 ### 배경
 
@@ -166,10 +170,12 @@ fabricate a `timeout` status against a missing artifact.
 
 - 수정 A (Claude worker Stop Condition) 가 먼저 머지되어 일정 기간 사용 데이터를 수집해야, 위 표의 expected duration 값을 실측 기반으로 조정할 수 있다. 초안 값은 보수적으로 잡았으므로 1~2주 사용 후 조정 권장.
 
-### 참고 — 적용 범위 밖 (수정 C 후보)
+### 참고 — 적용 범위 밖 (수정 C 후보) [해결됨, 2026-06-10]
 
 다음은 수정 B와 별개의 더 큰 설계 변경이며, 별도 브랜치에서 다룬다.
 
+> 해결 메모 (2026-06-10): 아래 첫 두 항목(background 전환 + worker-results 파일 폴링 루프)은 동일한 self-scheduled polling 프로토콜로 구현됐다 — "Worker-completion detection (self-scheduled polling)" 섹션([skills/okstra-team-contract/SKILL.md:124](../skills/okstra-team-contract/SKILL.md:124)), 설계는 [docs/superpowers/specs/2026-06-10-lead-worker-completion-polling-design.md](../docs/superpowers/specs/2026-06-10-lead-worker-completion-polling-design.md). 진짜 cancellation 통합은 여전히 미해결.
+
 - Phase 4를 foreground multi-Agent에서 `run_in_background: true` + leader polling 방식으로 전환
 - Lead 가 worker-results 파일 존재 + 헤더 검증으로 완료를 판단하는 폴링 루프 추가
 - 진짜 cancellation (Agent 강제 종료) 가 가능해지면 그 시점에 통합
@@ -179,3 +185,4 @@ fabricate a `timeout` status against a missing artifact.
 ## 변경 이력
 
 - 2026-05-03 — 작성. 수정 A(Claude worker Stop Condition) 동시 머지에 따른 후속 항목 기록.
+- 2026-06-10 — 수정 B(Leader-side 워커 soft timeout) 및 수정 C 후보(Phase 4 background polling / worker-results 파일 폴링 루프)를 self-scheduled polling 작업으로 해소 표기. 정본: okstra-team-contract "Worker-completion detection (self-scheduled polling)" 섹션, 설계: docs/superpowers/specs/2026-06-10-lead-worker-completion-polling-design.md.

package/runtime/agents/workers/claude-worker.md

@@ -86,7 +86,7 @@ This contract mirrors the `okstra-team-contract` skill's Worker Output Contract
 
 ## Stop Condition (BLOCKING)
 
-You are an in-process Claude subagent — Lead's `Agent()` call blocks until you return your final assistant message. Lingering after your worker-results file is on disk extends Phase 4 wall-clock time for the entire run and delays convergence. Be deliberate about stopping.
+When Lead dispatches you with `team_name` (Teams mode), its `Agent()` call returns `Spawned successfully` **immediately** and does NOT block on your completion — Lead detects your completion by self-scheduled polling of your worker-results file (see `okstra-team-contract` "Worker-completion detection (self-scheduled polling)"). Therefore you MUST write your worker-results file at the canonical Result Path before returning: that file's appearance is the ONLY completion signal Lead uses. Lingering after your worker-results file is on disk extends Phase 4 wall-clock time for the entire run and delays convergence. Be deliberate about stopping.
 
 After your `Write` to the assigned worker-results file (path provided by Lead as `**Result Path:**` — the canonical anchor header defined in `okstra-team-contract` "Worker Prompt Composition" — or derived under `runs/<task-type>/worker-results/claude-worker-<task-type>-<seq>.md`) succeeds:
 

package/runtime/bin/lib/okstra-ctl/cmd-rerun.sh

@@ -143,13 +143,32 @@ def _brief_path_from_argv(argv, cwd, project_root):
 
 batch_id = make_batch_id()
 items = []
-spawned = skipped = 0
+spawned = skipped = rejected = 0
 # 같은 (project, group, task_id, task_type) 에 속한 다중 rerun 이 같은 batch 내에서
 # 같은 seq 를 받지 않도록 메모리상 reservation 추적. tmux spawn 후 detached okstra 가
 # 디스크에 manifest/report 를 쓰기 전에 락이 풀리므로 filesystem-only 예측은 충돌한다.
 batch_reserved = {}
 for original in targets:
     row = find_row_by_run_id(home, original)
+    # implementation 은 stage 격리 task-type 이다. 한 run = 런타임에 live
+    # registry/consumers 상태로 auto-resolve 되는 단일 stage(_resolve_effective_stages)
+    # 이므로, cmd-rerun 은 spawn 전에 어느 stage-<N> 가 선택될지 알 수 없어
+    # runs/implementation/stage-<N> 경로도 per-stage run_seq 도 예측할 수 없다.
+    # OKSTRA_RUN_SEQ_OVERRIDE(run 전체에 단일 seq) 는 per-stage seq 카운터와
+    # 구조적으로 양립 불가하고, 원본 invocation 재생은 진짜 rerun 이 아니다
+    # (forced --stage N 은 이미 done 이라 거부되고, --stage auto 는 다른 ready
+    # stage 로 조용히 전진한다). 따라서 선예약/spawn 이전에 거부하고 신규
+    # implementation run 으로 안내한다.
+    if row and slugify_task_segment(row.get("taskType", "")) == "implementation":
+        items.append({"originalRunId": original, "newRunId": None,
+                      "newRunSeq": None, "sessionName": None,
+                      "status": "rejected", "spawnedAt": None,
+                      "skipReason": "implementation 은 stage 격리되어 okstra-ctl rerun 으로 "
+                                    "재실행할 수 없습니다. 다음 ready stage 를 실행하려면 "
+                                    "새 implementation run 을 시작하십시오 "
+                                    "(okstra.sh --task-type implementation --stage auto)."})
+        rejected += 1
+        continue
     inv = (load_invocation(home, row["projectId"], row["taskGroup"],
                            row["taskId"], row["taskType"], row["runSeq"])
            if row else None)
@@ -296,14 +315,14 @@ write_batch_meta(home, batch_id, {
     "selectorRaw": selector_raw, "maxSpawn": max_spawn,
     "items": items,
     "summary": {"total": len(targets), "spawned": spawned,
-                "skipped": skipped, "rejected": 0},
+                "skipped": skipped, "rejected": rejected},
 })
 
 dry_run_count = sum(1 for it in items if it["status"] == "dry-run")
 if dry_run_count:
-    print(f"batch  {batch_id}   dry-run: {dry_run_count}   skipped: {skipped}   rejected: 0")
+    print(f"batch  {batch_id}   dry-run: {dry_run_count}   skipped: {skipped}   rejected: {rejected}")
 else:
-    print(f"batch  {batch_id}   spawned: {spawned}   skipped: {skipped}   rejected: 0")
+    print(f"batch  {batch_id}   spawned: {spawned}   skipped: {skipped}   rejected: {rejected}")
 print()
 header = ("RUN-ID", "SESSION-NAME", "ATTACH")
 rows = []

package/runtime/prompts/profiles/implementation-planning.md

@@ -55,7 +55,7 @@
 - Section heading contract (BLOCKING — validator scans for these literal English substrings):
   - 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`, `Requirement Coverage`. (Approval is no longer a body section — it is the YAML frontmatter `approved` field.)
   - Korean translations are allowed in parentheses (e.g. `### Recommended Option (권장 옵션)`), but the English keyword must be present verbatim in the heading line.
-  - The shape and ordering follow `final-report-template.md` section 5.5 (`Implementation Plan Deliverables` + `Stage Map`). Do NOT translate the heading keywords — `validators/validate-run.py` does substring matching on the raw report text and missing English strings are a real, repeatedly observed failure mode (root cause: writer translated the headings to Korean).
+  - The shape and ordering follow `final-report-template.md` sections 5.4 (`Implementation Plan Deliverables`) + 5.5 (`Stage Map`). Do NOT translate the heading keywords — `validators/validate-run.py` does substring matching on the raw report text and missing English strings are a real, repeatedly observed failure mode (root cause: writer translated the headings to Korean).
   - Beyond substring matching, when the Plan Body Verification gate result is `passed` / `passed-with-dissent`, `validators/validate-run.py` runs the **structural** Stage Map validator (`validators/validate-implementation-plan-stages.py`) at the planning boundary — the exact `## 5.5 Stage Map` heading, each `## 5.5.<i> Stage <i>:` section with its four required subsections, the per-stage effective step count (≤6), the `depends-on` DAG, and the per-stage vertical-slice contract (S10) are all enforced here, not deferred to the `implementation` entry gate. S10 scans for the literal in-section strings `Slice value:`, `Acceptance:`, and the Stepwise `action`-cell prefixes `RED:` / `GREEN:` (or a `TDD exemption:` line) — keep these tokens verbatim for the same reason as the heading keywords above.
 - Required deliverable shape (final report, in addition to the standard sections):
   - at least two implementation options. **Each option must include**:

package/runtime/prompts/wizard/prompts.ko.json

@@ -157,6 +157,22 @@
       "label": "approved final-report.md 의 경로를 알려주세요 (APPROVED 마커 필수)",
       "echo_template": "approved-plan: {value}"
     },
+    "approve_plan_confirm": {
+      "label": "이 플랜으로 implementation 을 진행할까요?\n  {path}\n· 예 — 진행합니다. 플랜이 아직 승인 전이면 지금 data.json(정본) + 리포트를 함께 approved 로 처리한 뒤 진행합니다. (markdown 만 손으로 고치면 일관성 검증에서 거부되므로 이 경로로 승인하세요.)\n· 아니오 — 진행하지 않습니다.",
+      "echo_template": "approve-plan: {value}",
+      "options": {
+        "yes": "예 — 승인하고 진행",
+        "no": "아니오 — 진행하지 않음"
+      },
+      "echo_variants": {
+        "selected": "plan 선택: {path} — 다음 단계에서 승인·진행 여부를 확인합니다",
+        "approved": "approved-plan: {path} (승인·진행 확인됨)"
+      },
+      "errors": {
+        "declined": "진행을 선택하지 않으면 implementation 을 시작할 수 없습니다. 진행(예)하거나 위저드를 종료하세요.",
+        "still_unapproved": "approve-plan: 승인 처리 후에도 승인 상태가 아닙니다 (data.json/markdown 불일치): {path}"
+      }
+    },
     "stage_pick": {
       "label": "stage 범위를 선택하세요. auto 는 전체 task(모든 stage)를, 특정 번호는 해당 stage 만 대상으로 합니다.",
       "echo_template": "stage: {value}",
@@ -260,7 +276,7 @@
       }
     },
     "defaults_or_custom": {
-      "label": "역할별로 어떤 모델을 쓸지 정하는 단계입니다 (참여 워커 구성을 바꾸는 게 아닙니다).\n· 기본값으로 진행 — lead·실행자/워커·report-writer 를 모두 추천 모델로 두고 바로 진행합니다.\n· 커스터마이즈 — 역할별 모델을 직접 고르고, 추가 directive·관련 task 도 지정합니다.",
+      "label": "역할별 모델·실행 옵션 단계입니다 (참여 워커 구성을 바꾸는 게 아닙니다).\n이번 run 의 워커: {workers}\n· 기본값으로 진행 — 모든 역할을 추천 모델로 둡니다. 추천 기본값: lead·report-writer=opus, claude=opus, codex=gpt-5.5, gemini=auto (실제 값은 runtime 기본값으로 해소). directive·관련 task 없이 바로 진행.\n· 커스터마이즈 — 역할별 모델을 직접 고르고, 추가 directive·관련 task 도 지정합니다.",
       "echo_template": "customize: {value}",
       "options": {
         "defaults": "기본값으로 진행 (역할별 추천 모델 그대로)",

package/runtime/python/okstra_ctl/backfill.py

@@ -15,6 +15,28 @@ from .jsonl import append_jsonl, read_jsonl, rotate_recent_if_needed
 from .project_meta import _project_meta_path
 from .reconcile import _now_iso, normalize_central_status
 
+_STAGE_DIR_RE = _re.compile(r"^stage-\d+$")
+
+
+def _iter_manifest_dirs(runs: Path):
+    """`runs/` 아래에서 실제 run-manifest 가 사는 manifests 디렉터리를 모두 yield.
+
+    대부분 task-type 은 `runs/<task_type>/manifests/`. implementation 은 stage
+    격리로 산출물이 `runs/implementation/stage-<N>/manifests/` 에 사므로, 직접
+    하위 `manifests` 뿐 아니라 `stage-<N>/manifests` 까지 내려가 스캔해야
+    backfill/reindex 가 implementation run 을 누락하지 않는다.
+    """
+    for type_dir in sorted(p for p in runs.iterdir() if p.is_dir()):
+        direct = type_dir / "manifests"
+        if direct.is_dir():
+            yield direct
+        for stage_dir in sorted(p for p in type_dir.iterdir() if p.is_dir()):
+            if not _STAGE_DIR_RE.match(stage_dir.name):
+                continue
+            stage_manifests = stage_dir / "manifests"
+            if stage_manifests.is_dir():
+                yield stage_manifests
+
 
 def discover_project_roots(home: Path) -> List[tuple]:
     """`~/.okstra/projects/<projectId>/meta.json` 을 권위 소스로 (project_id,
@@ -110,10 +132,7 @@ def backfill_project(home: Path, project_id: str, project_root: Path) -> int:
             runs = task_dir / "runs"
             if not runs.is_dir():
                 continue
-            for type_dir in sorted(p for p in runs.iterdir() if p.is_dir()):
-                manifests = type_dir / "manifests"
-                if not manifests.is_dir():
-                    continue
+            for manifests in _iter_manifest_dirs(runs):
                 for mf in sorted(manifests.iterdir()):
                     m = manifest_re.match(mf.name)
                     if not m:

package/runtime/python/okstra_ctl/consumers.py

@@ -7,8 +7,9 @@ so the same (started / done) record is never duplicated."""
 from __future__ import annotations
 
 import json
+import re
 from pathlib import Path
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional
 
 from .run_context import consumers_mutex
 
@@ -51,3 +52,119 @@ def append_consumer(plan_run_root: Path, *, impl_task_key: str, stage: int,
         }
         with _path(plan_run_root).open("a", encoding="utf-8") as f:
             f.write(json.dumps(record, ensure_ascii=False) + "\n")
+
+
+# --- carry-as-SSOT done recovery ---------------------------------------------
+#
+# A stage's completion evidence is the verifier-authored sidecar at
+# `runs/implementation/carry/stage-<N>.json`. The `done` row in consumers.jsonl
+# is a derived index that the lead appends by hand (per the implementation
+# profile) — so it can be missing even when the stage actually finished. The
+# dependency gate (`_resolve_stage_base_commit`) reads `done.head_commit`, so a
+# missing `done` row wrongly blocks downstream stages. We treat the carry file
+# as the source of truth and backfill the missing `done` rows from it before
+# the gate runs. A stage with no carry, or an unfinished carry, is left blocked
+# on purpose.
+
+
+def _carry_stage_number(carry: Dict[str, Any], filename: str) -> Optional[int]:
+    for key in ("stage", "stageNumber"):
+        v = carry.get(key)
+        if isinstance(v, int):
+            return v
+    m = re.search(r"stage-(\d+)", filename)
+    return int(m.group(1)) if m else None
+
+
+_FAILED_CARRY_STATUSES = ("fail", "failed", "blocked", "error", "aborted")
+
+
+def _carry_is_complete(carry: Dict[str, Any]) -> bool:
+    # A carry sidecar is written only after the stage's steps + Stage Validation
+    # post commands all pass (spec §3.2), so its mere presence marks completion.
+    # Treat it as complete unless it explicitly records a failure status. The
+    # real backfill guard is whether a head commit can be extracted.
+    status = carry.get("status")
+    if status is not None and str(status).lower() in _FAILED_CARRY_STATUSES:
+        return False
+    return True
+
+
+def _carry_head_commit(carry: Dict[str, Any]) -> str:
+    rng = carry.get("stageCommitRange")
+    if isinstance(rng, dict) and rng.get("head"):
+        return str(rng["head"])
+    for key in ("head_sha", "head_commit", "head"):
+        v = carry.get(key)
+        if v:
+            return str(v)
+    commits = carry.get("commits")
+    if isinstance(commits, list) and commits:
+        last = commits[-1]
+        if isinstance(last, dict) and last.get("sha"):
+            return str(last["sha"])
+    return ""
+
+
+def _carry_dir(plan_run_root: Path) -> Path:
+    # consumers.jsonl lives at runs/implementation-planning/; the carry sidecars
+    # live at the sibling runs/implementation/carry/.
+    return plan_run_root.parent / "implementation" / "carry"
+
+
+def backfill_done_from_carry(plan_run_root: Path) -> int:
+    """Recover missing `done` rows from carry sidecars (carry is SSOT).
+
+    For every `runs/implementation/carry/stage-<N>.json` that is complete and
+    not already recorded as `done` in consumers.jsonl, append a `done` row with
+    the head commit read from the carry. Returns the number of rows recovered.
+    Stages with no carry or an unfinished carry are skipped, so the dependency
+    gate still legitimately blocks genuinely-unstarted stages."""
+    carry_dir = _carry_dir(plan_run_root)
+    if not carry_dir.is_dir():
+        return 0
+    existing = read_consumers(plan_run_root)
+    done_stages = {r.get("stage") for r in existing if r.get("status") == "done"}
+    key_by_stage: Dict[Any, str] = {}
+    fallback_key = ""
+    for r in existing:
+        k = r.get("impl_task_key")
+        if k:
+            fallback_key = k
+            key_by_stage.setdefault(r.get("stage"), k)
+    task_root = plan_run_root.parents[1]
+    recovered = 0
+    for cf in sorted(carry_dir.glob("stage-*.json")):
+        try:
+            carry = json.loads(cf.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            continue
+        if not isinstance(carry, dict):
+            continue
+        stage = _carry_stage_number(carry, cf.name)
+        if stage is None or stage in done_stages:
+            continue
+        if not _carry_is_complete(carry):
+            continue
+        head = _carry_head_commit(carry)
+        if not head:
+            continue
+        impl_key = key_by_stage.get(stage) or carry.get("impl_task_key") or fallback_key
+        if not impl_key:
+            continue
+        try:
+            carry_path = str(cf.relative_to(task_root))
+        except ValueError:
+            carry_path = str(cf)
+        append_consumer(
+            plan_run_root,
+            impl_task_key=impl_key,
+            stage=stage,
+            status="done",
+            head_commit=head,
+            carry_path=carry_path,
+            source="carry-backfill",
+        )
+        done_stages.add(stage)
+        recovered += 1
+    return recovered

package/runtime/python/okstra_ctl/paths.py

@@ -87,6 +87,7 @@ def compute_run_paths(
     task_id: str,
     task_type: str,
     run_seq_override: Optional[int] = None,
+    stage: Optional[int] = None,
 ) -> dict:
     """주어진 identity 와 task-type 에 대해 모든 path/segment 값을 계산해
     dict 로 돌려준다. 부수효과 없음.
@@ -123,6 +124,15 @@ def compute_run_paths(
     timeline_file = history_dir / "timeline.json"
 
     run_dir = runs_dir / task_type_segment
+    # implementation stage isolation: each stage's run artifacts live in a
+    # dedicated `stage-<N>` subtree (mirrors the per-stage worktree) so two
+    # concurrent `implementation` runs never share reports/state/worker-results.
+    # consumers.jsonl + the worktree registry stay at the task-type level (the
+    # shared stage ledger / occupancy SSOT); they are computed OUTSIDE this
+    # function and are intentionally NOT stage-scoped. Other task-types have no
+    # stage concept, so their run_dir is unchanged.
+    if task_type_segment == "implementation" and stage is not None:
+        run_dir = run_dir / f"stage-{int(stage)}"
     run_manifests = run_dir / "manifests"
     run_state = run_dir / "state"
     run_prompts = run_dir / "prompts"
@@ -208,6 +218,7 @@ def compute_run_paths(
         "HISTORY_DIR": str(history_dir),
         "TIMELINE_PATH": str(timeline_file),
         "RUN_DIR": str(run_dir),
+        "RUN_STAGE": "" if stage is None else str(int(stage)),
         "RUN_MANIFESTS_DIR": str(run_manifests),
         "RUN_STATE_DIR": str(run_state),
         "RUN_PROMPTS_DIR": str(run_prompts),