okstra 0.136.0 → 0.137.0

package/runtime/python/okstra_ctl/stage_targets.py

@@ -49,6 +49,23 @@ class StageLifecycle:
     pr_covered: bool
     head_commit: str
     report_path: str
+    step_count: int
+    deps_satisfied: bool
+    blocked_by: list[int]
+
+    @property
+    def status(self) -> str:
+        """Lifecycle state, in precedence order: done > active > ready > blocked.
+
+        ``started`` and ``reserved`` collapse into ``active`` because every
+        caller that distinguishes them already words the two the same way (see
+        the numeric-request error in ``resolve_effective_stages``).
+        """
+        if self.done:
+            return "done"
+        if self.started or self.reserved:
+            return "active"
+        return "ready" if self.deps_satisfied else "blocked"
 
     def handoff_eligibility_record(self) -> dict[str, Any]:
         reasons: list[str] = []
@@ -92,14 +109,67 @@ class StageLifecycleSnapshot:
         requested: str,
         budget: int = RUN_STEP_BUDGET,
     ) -> list[int]:
-        return resolve_effective_stages(
-            self.stage_map,
-            self.done_stages,
-            requested,
-            budget=budget,
-            started_stages=self.started_stages,
-            reserved_stages=self.reserved_stages,
+        """Return ordered stage numbers this run should execute.
+
+        ``requested`` is ``"auto"`` or a decimal string. Auto selection returns
+        every stage reporting ``ready`` within the step budget; numeric
+        selection returns one forced stage. Readiness itself is not decided
+        here — ``StageLifecycle.status`` is the single judgment point.
+        """
+        if requested != "auto":
+            return [self._forced_stage(requested)]
+
+        ready = [lc for lc in self.lifecycles if lc.status == "ready"]
+        if not ready:
+            raise StageTargetError(self._no_ready_stage_reason())
+
+        batch: list[int] = []
+        total = 0
+        for lifecycle in ready:
+            if batch and total + lifecycle.step_count > budget:
+                break
+            batch.append(lifecycle.stage)
+            total += lifecycle.step_count
+        return batch
+
+    def _forced_stage(self, requested: str) -> int:
+        try:
+            n = int(requested)
+        except ValueError as exc:
+            raise StageTargetError(
+                f"--stage must be 'auto' or an integer, got {requested!r}"
+            ) from exc
+        by_number = {lc.stage: lc for lc in self.lifecycles}
+        lifecycle = by_number.get(n)
+        if lifecycle is None:
+            raise StageTargetError(
+                f"--stage {n} not in Stage Map (have {list(by_number)})"
+            )
+        if lifecycle.status == "done":
+            raise StageTargetError(
+                f"--stage {n} already completed (consumers.jsonl status:done exists)"
+            )
+        if lifecycle.status == "active":
+            # Wording is load-bearing: okstra-run's unattended chain matches it
+            # to terminate normally instead of raising an exception gate.
+            raise StageTargetError(
+                f"--stage {n} already in progress or reserved by another run"
+            )
+        return n
+
+    def _no_ready_stage_reason(self) -> str:
+        blocked = [lc for lc in self.lifecycles if lc.status == "blocked"]
+        if not blocked:
+            return (
+                "no stage is ready: every stage is done or occupied by "
+                "another run"
+            )
+        detail = "; ".join(
+            f"stage {lc.stage} blocked by "
+            + ", ".join(str(d) for d in lc.blocked_by)
+            for lc in blocked
         )
+        return f"no stage is ready: {detail}"
 
     def resolve_implementation_stage(self, requested: str) -> int:
         return self.resolve_effective_stages(requested)[0]
@@ -131,9 +201,16 @@ def stage_lifecycle_snapshot_from_state(
     for stage in stage_map:
         stage_number = stage["stage_number"]
         done_row = consumer_state.done_by_stage.get(stage_number) or {}
+        depends_on = list(stage.get("depends_on") or [])
+        blocked_by = [
+            d for d in depends_on if d not in consumer_state.done_stages
+        ]
         lifecycles.append(StageLifecycle(
             stage=stage_number,
-            depends_on=list(stage.get("depends_on") or []),
+            depends_on=depends_on,
+            step_count=int(stage.get("step_count") or 0),
+            deps_satisfied=not blocked_by,
+            blocked_by=blocked_by,
             done=stage_number in consumer_state.done_stages,
             started=stage_number in consumer_state.started_stages,
             reserved=stage_number in reserved,
@@ -198,56 +275,22 @@ def resolve_effective_stages(
     started_stages: set[int] | None = None,
     reserved_stages: set[int] | None = None,
 ) -> list[int]:
-    """Return ordered stage numbers this run should execute.
+    """Adapter over ``StageLifecycleSnapshot.resolve_effective_stages``.
 
-    ``requested`` is ``"auto"`` or a decimal string. Auto selection returns all
-    ready stages within the step budget, excluding done/started/reserved stages.
-    Numeric selection returns one forced stage.
+    Entry point for callers holding raw stage-map and consumer sets rather than
+    a snapshot. It only assembles the snapshot; the readiness judgment lives on
+    ``StageLifecycle.status``.
     """
-    started_stages = started_stages or set()
-    reserved_stages = reserved_stages or set()
-    occupied = done_stages | started_stages | reserved_stages
-    if requested != "auto":
-        try:
-            n = int(requested)
-        except ValueError as exc:
-            raise StageTargetError(
-                f"--stage must be 'auto' or an integer, got {requested!r}"
-            ) from exc
-        target = next((s for s in stages if s["stage_number"] == n), None)
-        if target is None:
-            raise StageTargetError(
-                f"--stage {n} not in Stage Map "
-                f"(have {[s['stage_number'] for s in stages]})"
-            )
-        if n in done_stages:
-            raise StageTargetError(
-                f"--stage {n} already completed (consumers.jsonl status:done exists)"
-            )
-        if n in started_stages or n in reserved_stages:
-            raise StageTargetError(
-                f"--stage {n} already in progress or reserved by another run"
-            )
-        return [n]
-
-    ready = [
-        s for s in stages
-        if s["stage_number"] not in occupied
-        and all(d in done_stages for d in s["depends_on"])
+    rows: list[dict[str, Any]] = [
+        {"stage": n, "status": "done"} for n in sorted(done_stages)
     ]
-    if not ready:
-        raise StageTargetError(
-            "no stage is ready: every remaining stage has unsatisfied depends-on"
-        )
-    batch: list[int] = []
-    total = 0
-    for stage in ready:
-        step_count = stage.get("step_count", 0) or 0
-        if batch and total + step_count > budget:
-            break
-        batch.append(stage["stage_number"])
-        total += step_count
-    return batch
+    rows += [
+        {"stage": n, "status": "started"} for n in sorted(started_stages or set())
+    ]
+    snapshot = stage_lifecycle_snapshot_from_rows(
+        stages, rows, reserved_stages=reserved_stages,
+    )
+    return snapshot.resolve_effective_stages(requested, budget=budget)
 
 
 def resolve_implementation_stage(

package/runtime/python/okstra_ctl/time_report.py

@@ -14,12 +14,13 @@ import json
 import sys
 from pathlib import Path
 
-from okstra_ctl.paths import resolve_under_root
+from okstra_ctl.paths import resolve_under_root, task_timeline_file
+from okstra_project import read_task_key
 from okstra_ctl.task_target import resolve_task_root
 
 
 def load_runs(task_root: Path) -> tuple[list[dict], bool]:
-    path = task_root / "history" / "timeline.json"
+    path = task_timeline_file(task_root)
     try:
         data = json.loads(path.read_text(encoding="utf-8"))
     except (OSError, ValueError):
@@ -30,12 +31,6 @@ def load_runs(task_root: Path) -> tuple[list[dict], bool]:
     return runs, False
 
 
-def _task_key(task_root: Path) -> str:
-    try:
-        return json.loads((task_root / "task-manifest.json").read_text(encoding="utf-8")).get("taskKey", "")
-    except (OSError, ValueError):
-        return ""
-
 
 def _duration_ms(block) -> int:
     """usage / leadUsage block 의 durationMs — na_block·missing·None 은 0."""
@@ -194,7 +189,7 @@ def main(argv: list[str] | None = None) -> int:
 
     task_root, project_root = resolve_task_root(args.target, args.project_root, args.cwd)
     runs, _ = load_runs(task_root)
-    result = {"ok": True, "taskKey": _task_key(task_root)}
+    result = {"ok": True, "taskKey": read_task_key(task_root)}
     result.update(aggregate_time(runs, project_root))
     print(json.dumps(result, ensure_ascii=False, indent=2))
     return 0

package/runtime/python/okstra_ctl/wizard.py

@@ -972,14 +972,7 @@ def _fix_cycle_confirm_required(state: WizardState) -> bool:
         return False
     task_root = task_dir(Path(state.project_root),
                          state.task_group, state.task_id)
-    manifest = task_root / "task-manifest.json"
-    if not manifest.is_file():
-        return False
-    try:
-        data = json.loads(manifest.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return False
-    workflow = data.get("workflow") or {}
+    workflow = (read_task_manifest(task_root) or {}).get("workflow") or {}
     if workflow.get("lastCompletedPhase") != "release-handoff":
         return False
     return fix_cycles.open_cycle(fix_cycles.read_rows(task_root)) is None
@@ -1009,33 +1002,29 @@ def _parse_stage_objects(state: WizardState) -> list:
     return stages
 
 
-def _done_stage_numbers(state: WizardState) -> set:
-    """approved plan 을 소비한 implementation run 들의 consumers.jsonl 에서
-    done 처리된 stage 번호 집합. 순수 읽기 — carry backfill 은 하지 않는다.
+def _stage_lifecycle_snapshot(
+    state: WizardState, stages: list, *, reserved_stages: Optional[set] = None,
+):
+    """picker 가 보는 Stage Lifecycle Snapshot. 순수 읽기 — carry backfill 금지.
 
     backfill_done_from_carry 는 consumers.jsonl 에 done 행을 append 하고
-    그 부수효과로 worktree-registry stage 점유를 해제한다. 이 함수는 stage
+    그 부수효과로 worktree-registry stage 점유를 해제한다. 이 스냅샷은 stage
     picker 표시와 progress 추정(_remaining_screens 가 매 step 반복 호출)에서만
     쓰이므로, 화면을 그리는 것만으로 동시 실행 중인 run 의 점유를 풀면 안 된다.
-    carry 기반 done 보정은 prepare 게이트(run.py)가 단일 진입점으로 수행한다."""
-    if not state.approved_plan_path:
-        return set()
-    from .consumers import read_consumers, latest_done_by_stage
-    plan_run_root = Path(state.approved_plan_path).resolve().parents[1]
-    rows = read_consumers(plan_run_root)
-    return set(latest_done_by_stage(rows).keys())
+    carry 기반 done 보정은 prepare 게이트(run.py)가 단일 진입점으로 수행한다.
 
-
-def _started_stage_numbers(state: WizardState) -> set:
-    """approved plan 을 소비한 run 들의 consumers.jsonl 에서 status:started 인
-    stage 번호 집합. _done_stage_numbers 와 같은 순수 읽기 — carry backfill 금지."""
-    if not state.approved_plan_path:
-        return set()
-    from .consumers import read_consumers
-    plan_run_root = Path(state.approved_plan_path).resolve().parents[1]
-    rows = read_consumers(plan_run_root)
-    return {r["stage"] for r in rows
-            if r.get("status") == "started" and isinstance(r.get("stage"), int)}
+    One snapshot per call site: the two ledger reads this replaced ran once per
+    helper, and `_build_stage_pick` sits inside `_remaining_screens`' simulation.
+    """
+    from .stage_targets import read_stage_lifecycle_snapshot
+    return read_stage_lifecycle_snapshot(
+        [{"stage_number": s.stage_number,
+          "depends_on": list(s.depends_on),
+          "step_count": s.step_count} for s in stages],
+        Path(state.approved_plan_path).resolve().parents[1],
+        recover_from_carry=False,
+        reserved_stages=reserved_stages,
+    )
 
 
 def _reserved_stage_numbers(state: WizardState) -> set:
@@ -1068,7 +1057,7 @@ def _whole_task_allowed(
     if not stages:
         return False
     if done is None:
-        done = _done_stage_numbers(state)
+        done = _stage_lifecycle_snapshot(state, stages).done_stages
     return all(s.stage_number in done for s in stages)
 
 
@@ -2192,9 +2181,11 @@ def _build_stage_pick(state: WizardState) -> Prompt:
     is_fv = state.task_type == "final-verification"
     is_impl = state.task_type == "implementation"
     label = (t["label_final_verification"] or t["label"]) if is_fv else t["label"]
-    done = _done_stage_numbers(state)
-    started = _started_stage_numbers(state) if is_impl else set()
-    reserved = _reserved_stage_numbers(state) if is_impl else set()
+    snapshot = _stage_lifecycle_snapshot(
+        state, stages,
+        reserved_stages=_reserved_stage_numbers(state) if is_impl else None,
+    )
+    done = snapshot.done_stages
     options = []
     if _whole_task_allowed(state, stages=stages, done=done):
         options.append(_opt(WHOLE_TASK_STAGE, t["options"]["whole_task"]))
@@ -2208,7 +2199,8 @@ def _build_stage_pick(state: WizardState) -> Prompt:
                              if s.stage_number in done
                              else t["options"]["undone_mark"])
         elif is_impl:
-            suffix = "  " + _impl_stage_marker(t, s, done, started, reserved)
+            suffix = "  " + _impl_stage_marker(
+                t, snapshot.lifecycle_for(s.stage_number))
         options.append(_opt(
             str(s.stage_number),
             f"{s.stage_number}: {s.title}  "
@@ -2222,15 +2214,19 @@ def _build_stage_pick(state: WizardState) -> Prompt:
     )
 
 
-def _impl_stage_marker(t, stage, done, started, reserved) -> str:
-    n = stage.stage_number
-    if n in done:
-        return t["options"]["mark_done"]
-    if n in started or n in reserved:
-        return t["options"]["mark_active"]
-    if all(d in done for d in stage.depends_on):
-        return t["options"]["mark_ready"]
-    return t["options"]["mark_blocked"]
+# Presentation keys are mapped explicitly rather than interpolated from the
+# status, so renaming a Stage Lifecycle status is a compile-time-visible edit
+# here instead of a KeyError raised while drawing the picker.
+_STAGE_MARKER_KEYS = {
+    "done": "mark_done",
+    "active": "mark_active",
+    "ready": "mark_ready",
+    "blocked": "mark_blocked",
+}
+
+
+def _impl_stage_marker(t, lifecycle) -> str:
+    return t["options"][_STAGE_MARKER_KEYS[lifecycle.status]]
 
 
 def _submit_stage_pick(state: WizardState, answer: str) -> Optional[str]:
@@ -2264,9 +2260,11 @@ def _submit_impl_stage_pick(state: WizardState, answer: str) -> Optional[str]:
         raise WizardError(t["errors"]["whole_task_impl"])
     stages = _parse_stage_objects(state)
     all_nums = {s.stage_number for s in stages}
-    done = _done_stage_numbers(state)
-    occupied = (done | _started_stage_numbers(state)
-                | _reserved_stage_numbers(state))
+    snapshot = _stage_lifecycle_snapshot(
+        state, stages, reserved_stages=_reserved_stage_numbers(state))
+    done = snapshot.done_stages
+    occupied = {lc.stage for lc in snapshot.lifecycles
+                if lc.status in ("done", "active")}
     chosen = _impl_chosen_stages(t, picks, answer, all_nums, occupied)
     ordered = order_stage_closure(
         [(s.stage_number, s.depends_on) for s in stages], chosen, done)

package/runtime/python/okstra_ctl/work_categories.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 import json
 from pathlib import Path
 
-from .paths import task_dir
+from .paths import task_dir, task_manifest_file
 
 WORK_CATEGORIES: tuple[str, ...] = (
     "bugfix",
@@ -30,7 +30,7 @@ def is_valid_category(value: str) -> bool:
 
 def recorded_work_category(project_root: Path, task_group: str, task_id: str) -> str:
     """task-manifest.json 에 이미 기록된 work-category. 없거나 enum 밖이면 ""."""
-    manifest = task_dir(project_root, task_group, task_id) / "task-manifest.json"
+    manifest = task_manifest_file(task_dir(project_root, task_group, task_id))
     try:
         data = json.loads(manifest.read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError):

package/runtime/python/okstra_ctl/worker_prompt_body.py

@@ -71,6 +71,88 @@ def analysis_input_lines(
     return existing_input_lines(inputs)
 
 
+REPORT_WRITER_WORKER_ID = "report-writer"
+
+
+def report_writer_prompt_body(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+    model: str,
+    report_language: str,
+) -> list[str]:
+    """Render the provider-neutral body for the report-writer audience."""
+    return [
+        f"**Model:** Report writer worker, {model}",
+        f"**Report Language:** {report_language}",
+        "",
+        "# Report Writer Worker Dispatch",
+        "",
+        "## Role",
+        (
+            "You are the Report writer worker. Author the final-report data.json "
+            "and the worker-results audit file."
+        ),
+        "",
+        "## Task",
+        f"- Task key: `{_require_string(manifest, 'taskKey')}`",
+        f"- Task type: `{_require_string(manifest, 'taskType')}`",
+        "",
+        "## Inputs",
+        *report_writer_input_lines(manifest, active_context, team_state),
+        "",
+        mcp_pointer_line(),
+        "",
+        "## Output Contract",
+        "You are the author of TWO files:",
+        "- The final-report data.json at Result Path.",
+        "- The worker-results audit file at Audit sidecar path.",
+        (
+            'After writing the data.json, invoke "okstra render-final-report '
+            '<Result Path>" so the markdown sibling is rendered before you return.'
+        ),
+        "Do not return the report inline.",
+        "Copy Report Language verbatim into data.json.meta.reportLanguage.",
+    ]
+
+
+def report_writer_input_lines(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+) -> list[str]:
+    inputs = [
+        ("Task brief", instruction_path(manifest, active_context, "taskBriefPath")),
+        ("Analysis profile", instruction_path(manifest, active_context, "analysisProfilePath")),
+        ("Analysis material", instruction_path(manifest, active_context, "analysisMaterialPath")),
+        ("Reference expectations", instruction_path(manifest, active_context, "referenceExpectationsPath")),
+        ("Clarification response", instruction_path(manifest, active_context, "clarificationResponsePath")),
+        ("Final report template", instruction_path(manifest, active_context, "finalReportTemplatePath")),
+        ("Final report schema", instruction_path(manifest, active_context, "finalReportSchemaPath")),
+        ("Worker results directory", _string_value(manifest.get("workerResultsDirectoryPath"))),
+    ]
+    lines = existing_input_lines(inputs)
+    lines.extend(analysis_worker_result_lines(team_state))
+    return lines or ["- No report-writer inputs were recorded in active-run-context."]
+
+
+def analysis_worker_result_lines(team_state: Mapping[str, Any]) -> list[str]:
+    lines = []
+    workers = team_state.get("workers")
+    if not isinstance(workers, list):
+        return lines
+    for worker in workers:
+        if not isinstance(worker, Mapping):
+            continue
+        worker_id = worker.get("workerId")
+        if worker_id == REPORT_WRITER_WORKER_ID:
+            continue
+        result_path = _string_value(worker.get("resultPath"))
+        if result_path:
+            lines.append(f"- Analysis result ({worker_id}): `{result_path}`")
+    return lines
+
+
 def existing_input_lines(inputs: Sequence[tuple[str, str]]) -> list[str]:
     lines = [f"- {label}: `{path}`" for label, path in inputs if path]
     return lines or ["- No input paths were recorded in active-run-context."]

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -170,19 +170,6 @@ def validate_analysis_prompt_set(prompts: Mapping[str, str]) -> list[str]:
     return [f"normalized initial analysis prompts differ across workers: {workers}"]
 
 
-def validate_final_verification_prompt_paths(
-    prompt_paths: Mapping[str, Path],
-) -> list[str]:
-    """Validate persisted initial prompts and their normalized equality."""
-    records = [
-        PromptRecord(worker_id, "initial", path)
-        for worker_id, path in sorted(prompt_paths.items())
-    ]
-    return validate_initial_prompt_records(
-        manifest={"taskType": "final-verification"},
-        records=records,
-    )
-
 
 def validate_initial_prompt_records(
     *,

package/runtime/python/okstra_ctl/worker_prompt_headers.py

@@ -85,6 +85,13 @@ def worker_prompt_headers(
         f"**Project Root:** {project_root}",
         f"**Prompt History Path:** {prompt_rel}",
         f"**Result Path:** {result_rel}",
+    ]
+    if audit_source_rel and audit_source_rel != result_rel:
+        # The audit path is derived from this file, not from Result Path, so the
+        # worker has to be told which one it is (report-writer, whose Result Path
+        # is the report data.json rather than its own worker result).
+        headers.append(f"**Worker Result Path:** {audit_source_rel}")
+    headers += [
         f"**Audit sidecar path:** {audit_sidecar_path}",
         f"Assigned worker prompt history path: {prompt_path}",
         f"**Worker Preamble Path:** {_worker_preamble_path(plan, active_context)}",

package/runtime/python/okstra_project/__init__.py

@@ -33,11 +33,13 @@ from .state import (
     parse_task_key,
     read_latest_task,
     read_task_catalog,
+    read_task_key,
     read_task_manifest,
     resolve_task_id,
     resolve_task_identity,
     resolve_task_reference,
     slugify,
+    stage_map_read_side_snapshot,
     task_read_side_snapshot,
 )
 
@@ -59,12 +61,14 @@ __all__ = [
     "project_json_path",
     "read_latest_task",
     "read_task_catalog",
+    "read_task_key",
     "read_task_manifest",
     "resolve_project_root",
     "resolve_task_id",
     "resolve_task_identity",
     "resolve_task_reference",
     "slugify",
+    "stage_map_read_side_snapshot",
     "task_read_side_snapshot",
     "tasks_root",
     "upsert_project_json",

package/runtime/python/okstra_project/dirs.py

@@ -37,6 +37,13 @@ OKSTRA_RELATIVE = Path(OKSTRA_DIR_NAME)
 LEGACY_OKSTRA_RELATIVE = Path(LEGACY_OKSTRA_DIR_NAME)
 PROJECT_JSON_RELATIVE = OKSTRA_RELATIVE / "project.json"
 TASKS_RELATIVE = OKSTRA_RELATIVE / "tasks"
+
+TASK_MANIFEST_FILENAME = "task-manifest.json"
+"""task root 안의 lifecycle manifest 파일명.
+
+`okstra_ctl.paths.task_manifest_path` 와 `okstra_project.state.read_task_manifest`
+양쪽이 이 상수를 쓴다 — paths 가 state 를 import 하므로 역방향 import 는 순환이고,
+두 계층이 공유할 수 있는 자리는 여기뿐이다."""
 DISCOVERY_RELATIVE = OKSTRA_RELATIVE / "discovery"
 TASK_CATALOG_RELATIVE = DISCOVERY_RELATIVE / "task-catalog.json"
 LATEST_TASK_RELATIVE = DISCOVERY_RELATIVE / "latest-task.json"