okstra 0.102.2 → 0.102.4

package/runtime/prompts/lead/okstra-lead-contract.md

@@ -49,7 +49,7 @@ This document is the operating contract and phase index. Detailed procedures liv
 | 5.5 Convergence | Cross-verify findings across workers | `convergence` |
 | 5.6 Critic pass | (opt-in) reused-worker critic pass: coverage gaps (discovery/error-analysis/impl-planning) or acceptance devil's-advocate (final-verification). The critic dispatch fires concurrently with the first 5.5 reverify round (its input is fixed at Round 0); gap/blocker verification (one round) completes here | `convergence` "Coverage critic pass" / "Acceptance critic pass" |
 | 6. Synthesis | Dispatch Report writer worker, review draft. **For `implementation-planning`: then run the Phase 6 plan-body verification sub-step (see Phase 6 section below).** | `report-writer` + `convergence` (sub-step) |
-| 7. Persist | Run token-usage collector, update manifests, ask about residual tmux panes, then ask whether to dismiss the worker teammates (reconcile stale members + `SendMessage` shutdown_request only on approval) | `report-writer` + `_common-contract.md` "Phase wrap-up" / "Run-end teammate teardown" |
+| 7. Persist | Run token-usage collector, update manifests, ask once about residual tmux panes plus worker teammates, then close panes and dismiss teammates together on approval (reconcile stale members + `SendMessage` shutdown_request) | `report-writer` + `_common-contract.md` "Phase wrap-up" / "Run-end teammate teardown" |
 
 ## Core operating contract
 
@@ -103,7 +103,7 @@ Required checkpoints:
 - `PROGRESS: phase-batch-cleanup panes=<n> teammates=<m>` — 이전 배치 pane·완료 teammate 를 정리한 직후, 각 배치 경계에서(① 첫 `phase-5.5-convergence` round 직전 ② `phase-6-synthesis` report-writer dispatch 직전). 카운트만 노출하고 `%NNN`/lead-pane.id/raw Agent name 은 절대 노출하지 않는다. 첫 배치(분석 워커 dispatch) 직전엔 치울 게 없어 no-op 이며 마커도 생략.
 - `PROGRESS: phase-6-synthesis dispatching report-writer-worker` — at the start of Phase 6.
 - `PROGRESS: phase-7-persist updating manifests` — at the start of Phase 7.
-- `PROGRESS: phase-7-teardown dismissing teammates` — after token-usage collection and after the pane-disposition prompt, only when the user approved worker teammate cleanup, immediately before reconciling stale members + dismissing them via `SendMessage` shutdown_request (Teams mode only; see `_common-contract.md` "Run-end teammate teardown"). Skipped when split-pane is off (no roster) or when the user keeps the teammates.
+- `PROGRESS: phase-7-teardown dismissing teammates` — after token-usage collection and after the pane-disposition prompt, only when the user approved combined pane/team cleanup, immediately before reconciling stale members + dismissing them via `SendMessage` shutdown_request (Teams mode only; see `_common-contract.md` "Run-end teammate teardown"). Skipped when split-pane is off (no roster) or when the user keeps the panes/teammates.
 - `PROGRESS: complete final-report=<relative-path>` — final summary line, after all persistence.
 
 These lines are the only structured signal the user has during a long run. Do NOT replace them with prose ("Now I'm starting Phase 2..."), do NOT skip a checkpoint because "the previous message already said that", and do NOT batch multiple checkpoints into one. Each line stands alone so the user (or any operator scraping stdout) can timestamp it externally.

package/runtime/prompts/lead/report-writer.md

@@ -130,7 +130,7 @@ The four steps below MUST execute in this exact order. Reordering them is the re
 
 The status file is written after step 3 completes.
 
-**Run-end teammate teardown follows this whole sequence.** Token-usage collection (step 1) reads the worker session jsonls, so the lead MUST NOT disband the team until every step above is done. Only then — after the pane-disposition prompt and only when the user approves teammate cleanup — does the lead dismiss the worker teammates via `SendMessage` shutdown_request per `_common-contract.md` "Run-end teammate teardown" (split-pane runs only; silent-skip when split-pane is off; if the user keeps the teammates, leave them intact and surface the manual Teams/FleetView cleanup path).
+**Run-end teammate teardown follows this whole sequence.** Token-usage collection (step 1) reads the worker session jsonls, so the lead MUST NOT disband the team until every step above is done. Only then — after the combined pane/team disposition prompt and only when the user approves cleanup — does the lead dismiss the worker teammates via `SendMessage` shutdown_request per `_common-contract.md` "Run-end teammate teardown" (split-pane runs only; silent-skip when split-pane is off; if the user keeps panes/teammates, leave them intact and surface the manual Teams/FleetView cleanup path).
 
 ## Final Report Structure
 

package/runtime/prompts/profiles/_common-contract.md

@@ -44,25 +44,23 @@ profile document.
 - Phase wrap-up — okstra pane disposition (shared, runs AFTER Phase 7 persistence/token collection and BEFORE teammate teardown):
   - At run end the only residual okstra panes are the LAST phase's (e.g. the `report-writer-worker` agent pane and any codex/antigravity trace pane). `okstra-trace-cleanup.sh --list --run-dir "<RUN_DIR>"` returns one tab-separated `<pane_id>\t<pane_title>` line per residual okstra pane (worker-agent + trace) for this run.
   - After the final-report file has been written and the routing recommendation has been issued, the lead MUST ALWAYS run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list --run-dir "<RUN_DIR>"` exactly once — NEVER gating this call on its own reading of `lead-pane.id`. The output lists every residual okstra pane (worker-agent + trace) for this run, never the lead's own pane; outside tmux it is a safe no-op (empty output).
-  - If the list is empty, skip the question — there is nothing to ask about (the phase-start resets above usually already cleared prior phases).
-  - Otherwise the lead MUST present the user with a strict binary choice **before** declaring the phase complete. Use one prompt of this shape (Korean preferred, English acceptable if the rest of the run is in English):
-    > 현재 phase 종료 시점입니다. 다음 okstra pane 이 열려 있습니다 — 닫을까요?
+  - If the list is empty and no matching on-disk team config exists (see Run-end teammate teardown below), skip the question — there is nothing to ask about (the phase-start resets above usually already cleared prior phases).
+  - Otherwise the lead MUST present the user with a strict binary choice **before** declaring the phase complete. This single choice controls BOTH residual pane cleanup and worker teammate dismissal; do not ask a second teammate-cleanup question. Use one prompt of this shape (Korean preferred, English acceptable if the rest of the run is in English):
+    > 현재 phase 종료 시점입니다. 다음 okstra pane 및 worker teammate 가 남아 있습니다 — 닫고 정리할까요?
     > <인용된 `--list` 출력>
-    > (예) 모두 닫기 / (아니오) 그대로 두기
-  - On `예` / `y` / `close` → run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<RUN_DIR>"` and report the kill count back in one sentence.
-  - On `아니오` / `n` / `keep` → leave the panes intact; remind the user that they will be cleaned up automatically when Claude `/exit` fires the `SessionEnd` hook (`--reap`).
-  - The question MUST be a clean yes/no — do NOT offer "close some / keep some" partial answers, do NOT propose alternatives like "close only codex panes". The whole-set decision keeps the wrap-up predictable.
+    > (예) 모두 닫고 팀원 정리 / (아니오) 그대로 두기
+  - On `예` / `y` / `close` → run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<RUN_DIR>"`, then run the Run-end teammate teardown sequence below without asking a second question. Report the pane kill count and teammate cleanup outcome back in one sentence.
+  - On `아니오` / `n` / `keep` → leave panes and teammates intact; remind the user that tagged trace panes will be cleaned up automatically when Claude `/exit` fires the `SessionEnd` hook (`--reap`), while FleetView/Teams teammates remain visible until session end or manual Teams UI cleanup.
+  - The question MUST be a clean yes/no — do NOT offer "close some / keep some" partial answers, do NOT propose alternatives like "close only codex panes". The whole-set decision keeps the wrap-up predictable: lead pane excluded, every okstra worker/tail pane and worker teammate cleaned together on approval.
   - This step is mandatory for every phase (`requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff`). Whether there is anything to ask about is decided by the `--list` output, NOT by the lead's reading of `lead-pane.id`: an empty list → skip the question (above); the lead MUST NOT fabricate a synthetic pane list.
 - Run-end teammate teardown (shared — MUST run AFTER the pane disposition question and BEFORE `PROGRESS: complete`):
   - CC v2.1.178 removed `TeamCreate` / `TeamDelete`: this run rode the session's **implicit team** (Phase 3 recorded `teamCreate.status: "implicit"` plus the `teamName` audit label). There is no tool to delete a team — the implicit team ends when the session ends. What teardown CAN do is gracefully dismiss the worker teammates the lead spawned, so they stop showing as live members in the FleetView roster.
   - **Whether to run this step is decided by on-disk fact.** The harness names the team directory `session-<leadSessionId-prefix>` (the `teamName` label never becomes a directory name). Resolve existence from disk: find the `~/.claude/teams/session-*/config.json` whose `leadSessionId` equals team-state `lead.sessionId`.
     - **Matching on-disk config found, with members beyond the lead** → teammates exist; run the dismissal sequence below.
     - **No matching on-disk config, or split-pane was off** → nothing to dismiss → silent-skip.
-  - After the pane disposition step above, the lead MUST ask the user whether to dismiss the worker teammates. This is a strict binary choice:
-    > worker teammate (`<teamName>`) 들을 정리할까요?
-    > (예) 팀원 정리 / (아니오) 그대로 두기
+  - The pane disposition prompt above is the only user prompt for this cleanup decision. Do NOT ask a second teammate-only question.
   - On `아니오` / `n` / `keep` → dismiss nothing. Tell the user the teammates remain visible in FleetView/Teams until the session ends, and can be removed earlier from the Teams UI.
-  - On `예` / `y` / `cleanup` → emit `PROGRESS: phase-7-teardown dismissing teammates`, then run the sequence below. Token-usage collection MUST already be complete — it reads `~/.claude/projects/` jsonls, which dismissal never touches, but the read MUST precede teardown.
+  - On `예` / `y` / `close` → emit `PROGRESS: phase-7-teardown dismissing teammates`, then run the sequence below. Token-usage collection MUST already be complete — it reads `~/.claude/projects/` jsonls, which dismissal never touches, but the read MUST precede teardown.
     1. Run `$HOME/.okstra/bin/okstra-team-reconcile.sh "<resolved-config-path>"` — the on-disk `~/.claude/teams/session-<…>/config.json` resolved in the existence check above — exactly once. It flips dead-pane stale-active members to inactive, and no-ops when tmux is unavailable or nothing is stale. Do NOT loop it.
     2. Send each confirmed-complete member a structured `SendMessage(to: <name>, message: { type: "shutdown_request" })` — the `message` MUST be the object literal shown, NEVER a JSON string stuffed into a text field. NEVER target the lead's own session, and never use `TaskStop` (teammates are not background tasks — `TaskStop` 404s on a member address).
   - Claude Code exposes no tool to delete the team or surgically remove a roster entry, so a dismissed teammate may still show as an idle pill until the session ends. Do not pretend the team was deleted. If the user wants the roster gone entirely, surface the manual action: `Teams/FleetView 에서 team <teamName> 삭제`, and if tmux panes were kept earlier also show `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<RUN_DIR>"`.

package/runtime/python/okstra_ctl/codex_dispatch.py

@@ -18,7 +18,12 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Mapping, Sequence
 
+from .final_report_paths import (
+    final_report_data_path as _final_report_data_path,
+    final_report_markdown_path as _final_report_markdown_path,
+)
 from .lead_events import LeadEvent, append_lead_event
+from .path_hints import hydrate_active_run_context
 from .wrapper_status import status_path_for_prompt
 from .paths import task_dir
 from .worker_prompt_headers import WorkerPromptHeaderError, worker_prompt_headers
@@ -1398,7 +1403,7 @@ def _load_json_object(path: Path, label: str) -> dict[str, Any]:
 def _load_optional_json_object(path: Path | None) -> dict[str, Any]:
     if path is None or not path.is_file():
         return {}
-    return _load_json_object(path, "active-run-context")
+    return hydrate_active_run_context(_load_json_object(path, "active-run-context"))
 
 
 def _resolve_required_path(
@@ -1450,18 +1455,6 @@ def _failure_reason(exit_code: int, missing_paths: Sequence[Path]) -> str:
     return "worker dispatch failed"
 
 
-def _final_report_data_path(markdown_path: Path) -> Path:
-    if markdown_path.name.endswith(".md"):
-        return markdown_path.with_name(markdown_path.name[:-3] + ".data.json")
-    return markdown_path.with_suffix(".data.json")
-
-
-def _final_report_markdown_path(data_json_path: Path) -> Path:
-    if data_json_path.name.endswith(".data.json"):
-        return data_json_path.with_name(data_json_path.name[:-10] + ".md")
-    return data_json_path.with_suffix(".md")
-
-
 def _replace_report_writer_model_line(
     prompt_path: Path,
     model_execution_value: str,

package/runtime/python/okstra_ctl/consumers.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import json
 import re
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
@@ -17,6 +18,17 @@ from .run_context import consumers_mutex
 CONSUMERS_FILENAME = "consumers.jsonl"
 
 
+@dataclass(frozen=True)
+class StageConsumerState:
+    rows: List[Dict[str, Any]]
+    done_rows: List[Dict[str, Any]]
+    done_by_stage: Dict[int, Dict[str, Any]]
+    done_stages: set[int]
+    started_stages: set[int]
+    verified_accepted_stages: set[int]
+    pr_covered_stages: set[int]
+
+
 def _path(plan_run_root: Path) -> Path:
     return plan_run_root / CONSUMERS_FILENAME
 
@@ -50,6 +62,29 @@ def latest_done_by_stage(rows: List[Dict[str, Any]]) -> Dict[int, Dict[str, Any]
     return out
 
 
+def read_stage_consumer_state(
+    plan_run_root: Path, *, recover_from_carry: bool = False,
+) -> StageConsumerState:
+    if recover_from_carry:
+        backfill_done_from_carry(plan_run_root)
+    rows = read_consumers(plan_run_root)
+    done_rows = [r for r in rows if r.get("status") == "done"]
+    done_by_stage = latest_done_by_stage(rows)
+    started = {
+        r["stage"] for r in rows
+        if r.get("status") == "started" and isinstance(r.get("stage"), int)
+    }
+    return StageConsumerState(
+        rows=rows,
+        done_rows=done_rows,
+        done_by_stage=done_by_stage,
+        done_stages=set(done_by_stage.keys()),
+        started_stages=started,
+        verified_accepted_stages=verified_accepted_stages(rows),
+        pr_covered_stages=pr_covered_stages(rows),
+    )
+
+
 def append_consumer(plan_run_root: Path, *, impl_task_key: str, stage: int,
                     status: str, force_reappend: bool = False,
                     **fields: Any) -> None:

package/runtime/python/okstra_ctl/container.py

@@ -506,7 +506,7 @@ def _split_task_key(task_key: str) -> tuple[str, str, str]:
 def _resolve_up_inputs(project_root: Path, task_key: str) -> dict:
     """task-key 로 up 에 필요한 입력(worktree/stage_map/done_rows/anchor)을 모은다."""
     from . import worktree_registry as _reg
-    from .consumers import read_consumers, backfill_done_from_carry
+    from .consumers import read_stage_consumer_state
     from .plan_run_root import resolve_plan_run_root_by_task_key
 
     project_id, group, task_id = _split_task_key(task_key)
@@ -517,11 +517,9 @@ def _resolve_up_inputs(project_root: Path, task_key: str) -> dict:
             "없습니다. 먼저 해당 task 의 phase 를 한 번 실행해 worktree 를 만드세요.")
     plan = resolve_plan_run_root_by_task_key(
         project_root=project_root, task_group=group, task_id=task_id)
-    # carry sidecar 가 stage 완료의 SSOT 다 — final-verification 과 동일하게 누락된
-    # done 행을 carry 에서 복구한 뒤 읽어, 두 경로가 같은 디스크 상태에서 갈라지지
-    # 않게 한다(crash/부분쓰기로 consumers.jsonl done 행만 유실된 경우 대비).
-    backfill_done_from_carry(plan.run_root)
-    done_rows = [r for r in read_consumers(plan.run_root) if r.get("status") == "done"]
+    done_rows = read_stage_consumer_state(
+        plan.run_root, recover_from_carry=True,
+    ).done_rows
     stage_map = _plan_stage_map(plan.approved_plan_path)
     anchor = _reg.get_implementation_base(project_id, group, task_id) or ""
     return {

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -11,7 +11,12 @@ from pathlib import Path
 from typing import Any, Mapping, Sequence
 
 from . import tmux
+from .final_report_paths import (
+    final_report_data_path as _final_report_data_path,
+    final_report_markdown_path as _final_report_markdown_path,
+)
 from .lead_events import LeadEvent, append_lead_event
+from .path_hints import hydrate_active_run_context
 from .worker_prompt_headers import WorkerPromptHeaderError, worker_prompt_headers
 from .wrapper_status import read_wrapper_status, status_path_for_prompt
 
@@ -823,18 +828,6 @@ def _completion_paths(worker_id: str, result_path: Path, manifest: Mapping[str,
     return (data_json, _final_report_markdown_path(data_json), result_path)
 
 
-def _final_report_data_path(markdown_path: Path) -> Path:
-    if markdown_path.name.endswith(".md"):
-        return markdown_path.with_name(markdown_path.name[:-3] + ".data.json")
-    return markdown_path.with_suffix(".data.json")
-
-
-def _final_report_markdown_path(data_json_path: Path) -> Path:
-    if data_json_path.name.endswith(".data.json"):
-        return data_json_path.with_name(data_json_path.name[:-10] + ".md")
-    return data_json_path.with_suffix(".md")
-
-
 def _run_dir(plan: DispatchPlan) -> Path:
     value = _string_value(plan.manifest.get("runDirectoryPath"))
     return _resolve_project_path(plan.project_root, value) if value else plan.team_state_path.parent.parent
@@ -876,7 +869,9 @@ def _load_optional_json(project_root: Path, value: Any) -> dict[str, Any]:
     if not isinstance(value, str) or not value.strip():
         return {}
     path = _resolve_project_path(project_root, value)
-    return _load_json_object(path, "active-run-context") if path.is_file() else {}
+    if not path.is_file():
+        return {}
+    return hydrate_active_run_context(_load_json_object(path, "active-run-context"))
 
 
 def _resolve_required_path(project_root: Path, manifest: Mapping[str, Any], key: str) -> Path:

package/runtime/python/okstra_ctl/final_report_paths.py

@@ -0,0 +1,24 @@
+"""Path helpers for the final-report markdown/data.json pair."""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+DATA_JSON_SUFFIX = ".data.json"
+MARKDOWN_SUFFIX = ".md"
+
+
+def final_report_data_path(report_path: Path) -> Path:
+    """Return the data.json sibling for a final-report markdown path."""
+    name = report_path.name
+    if name.endswith(MARKDOWN_SUFFIX):
+        return report_path.with_name(name[: -len(MARKDOWN_SUFFIX)] + DATA_JSON_SUFFIX)
+    return report_path.with_suffix(DATA_JSON_SUFFIX)
+
+
+def final_report_markdown_path(data_path: Path) -> Path:
+    """Return the markdown sibling for a final-report data.json path."""
+    name = data_path.name
+    if name.endswith(DATA_JSON_SUFFIX):
+        return data_path.with_name(name[: -len(DATA_JSON_SUFFIX)] + MARKDOWN_SUFFIX)
+    return data_path.with_suffix(MARKDOWN_SUFFIX)

package/runtime/python/okstra_ctl/handoff.py

@@ -13,6 +13,7 @@ from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Tuple
 
 from . import consumers, worktree_registry
+from .final_report_paths import final_report_markdown_path
 from .worktree import (compute_branch_name, compute_worktree_path,
                        main_worktree_path, is_dirty_excluding_okstra,
                        nested_worktree_excludes, is_ancestor, merge_branch,
@@ -91,7 +92,7 @@ def latest_whole_task_fv_accepted(project_root, project_id: str,
         if ((data.get("header") or {}).get("taskType") == "final-verification"
                 and data.get("verificationScope") == "whole-task"
                 and token == "accepted"):
-            md = dj.with_name(dj.name[:-len(".data.json")] + ".md")
+            md = final_report_markdown_path(dj)
             return str(md if md.is_file() else dj)
     return ""
 

package/runtime/python/okstra_ctl/implementation_outcome.py

@@ -0,0 +1,271 @@
+"""Artifact-derived implementation phase outcome reconciliation."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .consumers import read_stage_consumer_state
+from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
+
+
+@dataclass(frozen=True)
+class ImplementationOutcome:
+    completed: bool
+    stages: list[int] = field(default_factory=list)
+    head_commit: str = ""
+    report_path: str = ""
+    next_recommended_phase: str = ""
+    reason: str = ""
+
+
+def derive_implementation_outcome(task_root: Path) -> ImplementationOutcome:
+    task_root = Path(task_root)
+    manifest = _load_json(task_root / "task-manifest.json")
+    workflow = manifest.get("workflow") if isinstance(manifest.get("workflow"), dict) else {}
+    if workflow.get("currentPhase") != "implementation":
+        return ImplementationOutcome(completed=False, reason="current phase is not implementation")
+
+    plan_run_root = task_root / "runs" / "implementation-planning"
+    if not plan_run_root.is_dir():
+        return ImplementationOutcome(completed=False, reason="implementation-planning run root missing")
+
+    stage_map = _load_stage_map(task_root, manifest)
+    if not stage_map:
+        return ImplementationOutcome(completed=False, reason="stage map unavailable")
+
+    consumers = read_stage_consumer_state(plan_run_root, recover_from_carry=True)
+    required_stages = {stage["stage_number"] for stage in stage_map}
+    if not required_stages or not required_stages.issubset(consumers.done_stages):
+        return ImplementationOutcome(completed=False, reason="not all stages are done")
+
+    carries = [_load_carry(task_root, stage) for stage in sorted(required_stages)]
+    if any(carry is None for carry in carries):
+        return ImplementationOutcome(completed=False, reason="carry sidecar missing")
+    if any(not _carry_passed(carry) for carry in carries if carry is not None):
+        return ImplementationOutcome(completed=False, reason="carry sidecar is not pass-grade")
+
+    latest_stage = max(required_stages)
+    latest_done = consumers.done_by_stage.get(latest_stage) or {}
+    latest_carry = carries[-1] or {}
+    return ImplementationOutcome(
+        completed=True,
+        stages=sorted(required_stages),
+        head_commit=str(latest_done.get("head_commit") or "") or _carry_head_commit(latest_carry),
+        report_path=_latest_implementation_report(task_root),
+        next_recommended_phase=DEFAULT_NEXT_PHASE["implementation"],
+        reason="all implementation stages have pass-grade carry and done rows",
+    )
+
+
+def reconcile_implementation_outcome(project_root: Path, task_root: Path) -> bool:
+    project_root = Path(project_root)
+    task_root = Path(task_root)
+    outcome = derive_implementation_outcome(task_root)
+    if not outcome.completed:
+        return False
+
+    manifest_path = task_root / "task-manifest.json"
+    manifest = _load_json(manifest_path)
+    workflow = manifest.get("workflow")
+    if not isinstance(workflow, dict):
+        workflow = {}
+        manifest["workflow"] = workflow
+
+    changed = _promote_workflow(workflow, outcome)
+    phase_outcome = manifest.get("phaseOutcome")
+    if not isinstance(phase_outcome, dict):
+        phase_outcome = {}
+        manifest["phaseOutcome"] = phase_outcome
+
+    contract = manifest.get("contractValidation")
+    contract_status = contract.get("status", "") if isinstance(contract, dict) else ""
+    implementation = {
+        "state": "completed",
+        "source": "implementation-carry",
+        "stages": outcome.stages,
+        "headCommit": outcome.head_commit,
+        "reportPath": outcome.report_path,
+        "contractValidationStatus": contract_status,
+        "reason": outcome.reason,
+    }
+    if phase_outcome.get("implementation") != implementation:
+        phase_outcome["implementation"] = implementation
+        changed = True
+
+    if changed:
+        _write_json(manifest_path, manifest)
+    return changed or _update_task_catalog(project_root, manifest)
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _load_stage_map(task_root: Path, manifest: dict[str, Any]) -> list[dict[str, Any]]:
+    plan_path = _source_plan_path(task_root, manifest)
+    if not plan_path.is_file():
+        return []
+    from .run import PrepareError, _load_parsed_stage_map, _stage_map_reject_detail
+
+    try:
+        stages, errs = _load_parsed_stage_map(plan_path.read_text(encoding="utf-8"))
+    except PrepareError:
+        return []
+    if _stage_map_reject_detail(stages, errs) is not None:
+        return []
+    return [
+        {
+            "stage_number": stage.stage_number,
+            "title": stage.title,
+            "depends_on": list(stage.depends_on),
+            "step_count": stage.step_count,
+        }
+        for stage in stages
+    ]
+
+
+def _source_plan_path(task_root: Path, manifest: dict[str, Any]) -> Path:
+    carry_dir = task_root / "runs" / "implementation" / "carry"
+    for carry_path in sorted(carry_dir.glob("stage-*.json")):
+        value = _load_json(carry_path).get("sourcePlanPath")
+        if isinstance(value, str) and value:
+            return _resolve_relative(task_root, value)
+
+    latest = manifest.get("latestReportPath")
+    if isinstance(latest, str) and "implementation-planning" in latest:
+        return _resolve_relative(task_root, latest)
+
+    reports = task_root / "runs" / "implementation-planning" / "reports"
+    candidates = sorted(reports.glob("final-report-implementation-planning-*.md"))
+    return candidates[-1] if candidates else Path()
+
+
+def _resolve_relative(task_root: Path, value: str) -> Path:
+    path = Path(value)
+    if path.is_absolute():
+        return path
+    project_root = _project_root_from_task_root(task_root)
+    project_relative = project_root / path
+    if project_relative.exists():
+        return project_relative
+    task_relative = task_root / path
+    if task_relative.exists():
+        return task_relative
+    return project_relative
+
+
+def _project_root_from_task_root(task_root: Path) -> Path:
+    parts = task_root.resolve().parts
+    if ".okstra" not in parts:
+        return task_root.resolve()
+    return Path(*parts[: parts.index(".okstra")])
+
+
+def _load_carry(task_root: Path, stage: int) -> dict[str, Any] | None:
+    data = _load_json(task_root / "runs" / "implementation" / "carry" / f"stage-{stage}.json")
+    return data or None
+
+
+def _carry_passed(carry: dict[str, Any]) -> bool:
+    status = str(carry.get("status") or "").lower()
+    if status in {"fail", "failed", "blocked", "error", "aborted"}:
+        return False
+    conformance = carry.get("conformance")
+    if isinstance(conformance, dict):
+        overall = str(conformance.get("overall") or "").upper()
+        if overall and overall != "PASS":
+            return False
+    unverified = carry.get("unverified")
+    return not (isinstance(unverified, list) and unverified)
+
+
+def _carry_head_commit(carry: dict[str, Any]) -> str:
+    stage_range = carry.get("stageCommitRange")
+    if isinstance(stage_range, dict) and stage_range.get("head"):
+        return str(stage_range["head"])
+    for key in ("head_sha", "head_commit", "head"):
+        value = carry.get(key)
+        if value:
+            return str(value)
+    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 _latest_implementation_report(task_root: Path) -> str:
+    reports = sorted(
+        (task_root / "runs" / "implementation").glob(
+            "stage-*/reports/final-report-implementation-*.md"
+        )
+    )
+    if not reports:
+        return ""
+    project_root = _project_root_from_task_root(task_root)
+    try:
+        return str(reports[-1].relative_to(project_root))
+    except ValueError:
+        return str(reports[-1])
+
+
+def _promote_workflow(workflow: dict[str, Any], outcome: ImplementationOutcome) -> bool:
+    before = json.dumps(workflow, sort_keys=True, ensure_ascii=False)
+    phase_states = workflow.get("phaseStates")
+    if not isinstance(phase_states, dict):
+        phase_states = {}
+        workflow["phaseStates"] = phase_states
+    for phase in PHASE_SEQUENCE:
+        phase_states.setdefault(phase, "not-started")
+    workflow["currentPhase"] = "implementation"
+    workflow["currentPhaseState"] = "completed"
+    phase_states["implementation"] = "completed"
+    workflow["lastCompletedPhase"] = "implementation"
+    workflow["nextRecommendedPhase"] = outcome.next_recommended_phase
+    after = json.dumps(workflow, sort_keys=True, ensure_ascii=False)
+    return before != after
+
+
+def _update_task_catalog(project_root: Path, manifest: dict[str, Any]) -> bool:
+    catalog_path = project_root / ".okstra" / "discovery" / "task-catalog.json"
+    catalog = _load_json(catalog_path)
+    tasks = catalog.get("tasks")
+    if not isinstance(tasks, list):
+        return False
+    task_key = manifest.get("taskKey")
+    workflow = manifest.get("workflow") if isinstance(manifest.get("workflow"), dict) else {}
+    outcome = manifest.get("phaseOutcome") if isinstance(manifest.get("phaseOutcome"), dict) else {}
+    for entry in tasks:
+        if not isinstance(entry, dict) or entry.get("taskKey") != task_key:
+            continue
+        before = json.dumps(entry, sort_keys=True, ensure_ascii=False)
+        entry["currentPhase"] = workflow.get("currentPhase", "")
+        entry["currentPhaseState"] = workflow.get("currentPhaseState", "")
+        entry["lastCompletedPhase"] = workflow.get("lastCompletedPhase", "")
+        entry["nextRecommendedPhase"] = workflow.get("nextRecommendedPhase", "")
+        entry["latestReportPath"] = manifest.get("latestReportPath", "")
+        entry["latestRunStatus"] = manifest.get("latestRunStatus", entry.get("latestRunStatus", ""))
+        entry["currentStatus"] = manifest.get("currentStatus", entry.get("currentStatus", ""))
+        entry["phaseOutcome"] = outcome
+        if before == json.dumps(entry, sort_keys=True, ensure_ascii=False):
+            return False
+        _write_json(catalog_path, catalog)
+        return True
+    return False
+
+
+def _write_json(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
+        encoding="utf-8",
+    )

package/runtime/python/okstra_ctl/implementation_stage.py

@@ -66,16 +66,14 @@ def select_and_provision_implementation_stage(
     """
     del task_key  # The registry uses the split identity fields.
 
-    from .consumers import read_consumers, backfill_done_from_carry
+    from .consumers import backfill_done_from_carry, read_stage_consumer_state
     from . import worktree as _worktree
     from . import worktree_registry as _reg
 
     plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
     backfill_done_from_carry(plan_run_root)
     auto_reconcile_best_effort(inp, plan_run_root)
-    consumed = read_consumers(plan_run_root)
-    done_stages = {r["stage"] for r in consumed if r.get("status") == "done"}
-    started_stages = {r["stage"] for r in consumed if r.get("status") == "started"}
+    consumers = read_stage_consumer_state(plan_run_root)
     reserved_stages = _reg.list_active_stage_numbers(
         inp.project_id,
         inp.task_group,
@@ -83,18 +81,17 @@ def select_and_provision_implementation_stage(
     )
 
     try:
-        batch = stage_targets.resolve_effective_stages(
+        selected = stage_targets.resolve_implementation_stage(
             ctx_stage_map,
-            done_stages,
+            consumers.done_stages,
             inp.stage,
-            started_stages=started_stages,
+            started_stages=consumers.started_stages,
             reserved_stages=reserved_stages,
         )
     except stage_targets.StageTargetError as exc:
         raise _as_implementation_stage_error(exc) from exc
 
-    selected = batch[0]
-    concurrent_stages = sorted(reserved_stages - done_stages - {selected})
+    concurrent_stages = sorted(reserved_stages - consumers.done_stages - {selected})
 
     if executor_worktree_status.startswith("skipped"):
         head = _git_out(inp.project_root, "rev-parse", "HEAD")
@@ -133,11 +130,10 @@ def select_and_provision_implementation_stage(
     selected_stage = next(
         s for s in ctx_stage_map if s["stage_number"] == selected
     )
-    consumer_done_rows = [r for r in consumed if r.get("status") == "done"]
     try:
         stage_base = stage_targets.resolve_stage_base_commit(
             selected_stage,
-            consumer_done_rows,
+            consumers.done_rows,
             anchor_base_commit=anchor,
             candidate_base=head_sha,
             project_root=Path(task_worktree_path),