okstra 0.136.0 → 0.138.0

package/runtime/python/okstra_ctl/wizard.py

@@ -81,8 +81,8 @@ from okstra_ctl.worktree import (
     compute_worktree_path,
     is_git_work_tree,
     main_worktree_path,
-    preview_stage_worktree_decision,
     preview_worktree_decision,
+    resolve_stage_worktree_decision,
 )
 from okstra_ctl.paths import RunRef, task_dir, task_runs_dir
 from okstra_ctl.work_categories import resolve_work_category
@@ -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)
@@ -3177,7 +3175,7 @@ def _worktree_preview_line_impl(state: WizardState) -> str:
         )
         return _msg(state.workspace_root, "confirmation", "worktree_impl_auto",
                     path=str(parent_dir))
-    decision = preview_stage_worktree_decision(
+    decision = resolve_stage_worktree_decision(
         project_id=state.project_id, task_group_segment=state.task_group,
         task_id_segment=state.task_id,
         work_category=_preview_work_category(state),

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

@@ -16,6 +16,10 @@ from .worker_prompt_policy import (
 MAX_FINAL_VERIFICATION_DIRECTIVE_LINES = 40
 MAX_FINAL_VERIFICATION_BODY_LINES = 96
 
+PROMPT_DELIVERY_MODE_HEADER = "**Prompt Delivery Mode:**"
+PROMPT_DELIVERY_MODES = frozenset({"eager-include", "lazy-path-reference"})
+MODEL_HEADER = "**Model:**"
+
 _DIRECTIVE_HEADING = "## Run-specific directive"
 _WORKER_ERROR_CONTRACT_HEADER = "**Worker Error Contract Path:**"
 _PRIMARY_PACKET_RE = re.compile(
@@ -48,6 +52,7 @@ _NON_BODY_PREFIXES = (
     "**Verification head ref:**",
     "**Verification target path:**",
     "**Verification target digest:**",
+    PROMPT_DELIVERY_MODE_HEADER,
 )
 _REQUIRED_TARGET_PREFIXES = (
     "**Worktree:**",
@@ -81,6 +86,8 @@ class PromptRecord:
     worker_id: str
     dispatch_kind: str
     path: Path
+    expected_model: str | None = None
+    expected_delivery_mode: str | None = None
 
 
 def validate_final_verification_initial_prompt(text: str) -> list[str]:
@@ -170,19 +177,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(
     *,
@@ -207,6 +201,10 @@ def validate_initial_prompt_records(
             f"{record.worker_id}: {error}"
             for error in _validate_prompt_for_plan(text, plan, manifest)
         )
+        errors.extend(
+            f"{record.worker_id}: {error}"
+            for error in _validate_record_metadata(text, record)
+        )
         if plan.equality_group:
             group = equality_groups.setdefault(plan.equality_group, {})
             group[record.worker_id] = text
@@ -215,6 +213,68 @@ def validate_initial_prompt_records(
     return errors
 
 
+def _validate_record_metadata(text: str, record: PromptRecord) -> list[str]:
+    errors = _validate_delivery_mode(
+        _header_values(text, PROMPT_DELIVERY_MODE_HEADER),
+        record.expected_delivery_mode,
+    )
+    if record.expected_model is None:
+        return errors
+    model = _model_value(_header_values(text, MODEL_HEADER))
+    if model is None:
+        errors.append(
+            "exactly one non-empty **Model:** <label>, <model> header is required"
+        )
+    elif model != record.expected_model:
+        errors.append(
+            f"prompt model does not match requested model: {record.expected_model}"
+        )
+    return errors
+
+
+def _validate_delivery_mode(
+    values: list[str],
+    expected: str | None,
+) -> list[str]:
+    errors = []
+    if len(values) != 1 or not values[0]:
+        errors.append(
+            "exactly one non-empty **Prompt Delivery Mode:** header is required"
+        )
+    errors.extend(
+        f"unsupported Prompt Delivery Mode: {value}"
+        for value in values
+        if value and value not in PROMPT_DELIVERY_MODES
+    )
+    if (
+        expected is not None
+        and len(values) == 1
+        and values[0]
+        and values[0] != expected
+    ):
+        errors.append(
+            f"Prompt Delivery Mode does not match requested mode: {expected}"
+        )
+    return errors
+
+
+def _header_values(text: str, prefix: str) -> list[str]:
+    return [
+        line.strip()[len(prefix):].strip()
+        for line in text.splitlines()
+        if line.strip().startswith(prefix)
+    ]
+
+
+def _model_value(values: list[str]) -> str | None:
+    if len(values) != 1:
+        return None
+    parts = [part.strip() for part in values[0].rsplit(",", 1)]
+    if len(parts) != 2 or not all(parts):
+        return None
+    return parts[1]
+
+
 def _resolve_record_plan(
     manifest: Mapping[str, Any],
     record: PromptRecord,

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_ctl/worktree.py

@@ -194,31 +194,38 @@ def preview_worktree_decision(
     )
 
 
-def preview_stage_worktree_decision(
+@dataclass
+class StageWorktreeDecision:
+    """Side-effect-free decision for one concrete implementation stage."""
+
+    status: str
+    path: str
+    branch: str = ""
+    base_ref: str = ""
+
+
+def resolve_stage_worktree_decision(
     *,
     project_id: str,
     task_group_segment: str,
     task_id_segment: str,
     work_category: str,
     stage_number: int,
-) -> "WorktreeDecision":
-    """Side-effect-free: what provision_stage_worktree WOULD do (reuse vs new).
-
-    Mirrors provision_stage_worktree's registry-reuse branch exactly. A "new"
-    decision carries no base_ref — the stage base commit is resolved later by
-    the prepare flow from the stage's dependency anchors.
-    """
+) -> StageWorktreeDecision:
+    """Resolve whether one concrete stage worktree is new or reusable."""
     safe_project = _safe_segment(project_id)
     safe_group = _safe_segment(task_group_segment)
     safe_task = _safe_segment(task_id_segment)
     existing = worktree_registry.lookup(
         safe_project, safe_group, safe_task, stage_number=stage_number)
     if existing is not None and existing.status == "active":
-        return WorktreeDecision(
-            status="reused", path=existing.worktree_path,
-            branch=existing.branch, base_ref=existing.base_ref,
+        return StageWorktreeDecision(
+            status="reused",
+            path=existing.worktree_path,
+            branch=existing.branch,
+            base_ref=existing.base_ref,
         )
-    return WorktreeDecision(
+    return StageWorktreeDecision(
         status="new",
         path=str(compute_worktree_path(
             project_id=safe_project, task_group_segment=safe_group,
@@ -923,31 +930,32 @@ def provision_stage_worktree(
     if not base_commit:
         raise RuntimeError("provision_stage_worktree requires a base_commit")
 
-    safe_project = _safe_segment(project_id)
-    safe_group = _safe_segment(task_group_segment)
-    safe_task = _safe_segment(task_id_segment)
-    worktree_path = compute_worktree_path(
-        project_id=safe_project, task_group_segment=safe_group,
-        task_id_segment=safe_task, stage_number=stage_number,
-    )
-    branch = compute_branch_name(
-        work_category=work_category, task_id_segment=safe_task,
+    decision = resolve_stage_worktree_decision(
+        project_id=project_id,
+        task_group_segment=task_group_segment,
+        task_id_segment=task_id_segment,
+        work_category=work_category,
         stage_number=stage_number,
     )
-
-    existing = worktree_registry.lookup(
-        safe_project, safe_group, safe_task, stage_number=stage_number)
-    if existing is not None and existing.status == "active":
+    if decision.status == "reused":
         return WorktreeProvision(
-            status="reused", path=existing.worktree_path,
-            branch=existing.branch, base_ref=existing.base_ref,
+            status="reused",
+            path=decision.path,
+            branch=decision.branch,
+            base_ref=decision.base_ref,
             note=(
                 f"stage {stage_number} worktree reused at "
-                f"{existing.worktree_path} on branch {existing.branch} "
-                f"(base {existing.base_ref[:12]})"
+                f"{decision.path} on branch {decision.branch} "
+                f"(base {decision.base_ref[:12]})"
             ),
         )
 
+    safe_project = _safe_segment(project_id)
+    safe_group = _safe_segment(task_group_segment)
+    safe_task = _safe_segment(task_id_segment)
+    worktree_path = Path(decision.path)
+    branch = decision.branch
+
     if worktree_path.exists():
         raise RuntimeError(
             f"stage worktree path already exists but is not in the registry: "

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"