okstra 0.49.0 → 0.51.0

package/runtime/python/okstra_ctl/paths.py

@@ -31,9 +31,25 @@ __all__ = [
     "DISCOVERY_RELATIVE",
     "compute_run_paths",
     "next_run_seq",
+    "task_dir",
+    "task_runs_dir",
 ]
 
 
+def task_dir(project_root: Path, task_group: str, task_id: str) -> Path:
+    """task root 경로: ``<project>/.okstra/tasks/<group-seg>/<id-seg>``.
+
+    raw group/id 를 받아 내부에서 slugify 한다 — compute_run_paths 가 쓰는 것과
+    동일한 segment 규칙이다. 과거 sequence/wizard 가 이 구조를 손으로 재유도해
+    silent drift 위험이 있던 것을 이 SSOT 로 모은다."""
+    return Path(project_root) / TASKS_RELATIVE / slugify(task_group) / slugify(task_id)
+
+
+def task_runs_dir(project_root: Path, task_group: str, task_id: str) -> Path:
+    """task 의 runs 디렉터리: ``task_dir/runs``."""
+    return task_dir(project_root, task_group, task_id) / "runs"
+
+
 def next_run_seq(run_seq_dir: Path, task_type_segment: str) -> int:
     """run_seq_dir 안에서 `*-<task-type>-NNN.<ext>` 파일을 스캔해 다음 seq 번호를
     돌려준다. 디렉터리 부재 시 1.
@@ -100,6 +116,7 @@ def compute_run_paths(
     task_manifest = task_root / "task-manifest.json"
     task_index = task_root / "task-index.md"
     instruction_set = task_root / "instruction-set"
+    analysis_packet = instruction_set / "analysis-packet.md"
     runs_dir = task_root / "runs"
     history_dir = task_root / "history"
     timeline_file = history_dir / "timeline.json"
@@ -143,6 +160,7 @@ def compute_run_paths(
     final_report = run_reports / f"final-report{suffixes['reports']}.md"
     final_status = run_status / f"final{suffixes['status']}.status"
     team_state = run_state / f"team-state{suffixes['state']}.json"
+    active_run_context = run_state / f"active-run-context{suffixes['state']}.json"
     final_report_template = instruction_set / "final-report-template.md"
     final_report_schema = instruction_set / "final-report-schema.json"
     reference_expectations = instruction_set / "reference-expectations.md"
@@ -183,6 +201,7 @@ def compute_run_paths(
         "TASK_MANIFEST_PATH": str(task_manifest),
         "TASK_INDEX_PATH": str(task_index),
         "INSTRUCTION_SET_PATH": str(instruction_set),
+        "ANALYSIS_PACKET_PATH": str(analysis_packet),
         "RUNS_DIR": str(runs_dir),
         "HISTORY_DIR": str(history_dir),
         "TIMELINE_PATH": str(timeline_file),
@@ -205,6 +224,7 @@ def compute_run_paths(
         "FINAL_REPORT_PATH": str(final_report),
         "FINAL_STATUS_PATH": str(final_status),
         "TEAM_STATE_PATH": str(team_state),
+        "ACTIVE_RUN_CONTEXT_PATH": str(active_run_context),
         "FINAL_REPORT_TEMPLATE_PATH": str(final_report_template),
         "FINAL_REPORT_SCHEMA_PATH": str(final_report_schema),
         "REFERENCE_EXPECTATIONS_FILE": str(reference_expectations),
@@ -244,6 +264,7 @@ def compute_run_paths(
         ("TASK_MANIFEST_RELATIVE_PATH", task_manifest),
         ("TASK_INDEX_RELATIVE_PATH", task_index),
         ("INSTRUCTION_SET_RELATIVE_PATH", instruction_set),
+        ("ANALYSIS_PACKET_RELATIVE_PATH", analysis_packet),
         ("RUNS_RELATIVE_PATH", runs_dir),
         ("HISTORY_RELATIVE_PATH", history_dir),
         ("TIMELINE_RELATIVE_PATH", timeline_file),
@@ -263,6 +284,7 @@ def compute_run_paths(
         ("FINAL_REPORT_RELATIVE_PATH", final_report),
         ("FINAL_STATUS_RELATIVE_PATH", final_status),
         ("TEAM_STATE_RELATIVE_PATH", team_state),
+        ("ACTIVE_RUN_CONTEXT_RELATIVE_PATH", active_run_context),
         ("WORKER_RESULTS_RELATIVE_PATH", worker_results),
         ("RUN_CARRY_RELATIVE_PATH", run_carry),
         ("FINAL_REPORT_TEMPLATE_RELATIVE_PATH", final_report_template),

package/runtime/python/okstra_ctl/render.py

@@ -24,6 +24,11 @@ from pathlib import Path
 
 from okstra_project.dirs import OKSTRA_DIR_NAME, project_json_path
 
+# phase 시퀀스 / 기본 next-phase 매핑의 SSOT 는 workflow 모듈이다. 과거
+# render_task_manifest 가 동일한 리스트/딕셔너리를 로컬에 중복 정의했는데,
+# 이는 silent drift 위험이 있어 SSOT import 로 통합한다.
+from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
+
 
 class TokenRenderError(Exception):
     """Raised when a template references a `{{TOKEN}}` not present in ctx.
@@ -75,7 +80,7 @@ def _strip_phase_blocks(text: str, current_phase: str) -> str:
     entirely. When *current_phase* is empty or not one of the four
     block-targetable phases (e.g. `requirements-discovery`,
     `error-analysis`), every block is dropped — correct because none of
-    the `## 4.5` / `4.6` / `4.7` / `4.8` deliverable sections apply
+    the `## 5.5` / `5.6` / `5.7` / `5.8` deliverable sections apply
     there.
 
     Observed (fontsninja-classifier-v2 RD run): the raw final-report
@@ -238,11 +243,154 @@ def _worker_catalog(ctx: dict) -> dict:
     }
 
 
+def _active_workers(ctx: dict) -> list[dict]:
+    catalog = _worker_catalog(ctx)
+    workers = []
+    for worker_id in _resolve_workers(ctx):
+        item = catalog[worker_id]
+        workers.append({
+            "workerId": item["workerId"],
+            "role": item["role"],
+            "agent": item["agent"],
+            "agentLabel": item["agentLabel"],
+            "model": item["model"],
+            "modelExecutionValue": item["modelExecutionValue"],
+            "promptPath": item["promptPath"],
+            "resultPath": item["resultPath"],
+            "attemptRequired": True,
+        })
+    return workers
+
+
+def _active_task(ctx: dict) -> dict:
+    return {
+        "projectId": ctx.get("PROJECT_ID", ""),
+        "taskGroup": ctx.get("TASK_GROUP", ""),
+        "taskId": ctx.get("TASK_ID", ""),
+        "taskKey": ctx.get("TASK_KEY", ""),
+        "taskType": ctx.get("TASK_TYPE", ""),
+        "workCategory": ctx.get("WORKFLOW_WORK_CATEGORY", "unknown"),
+        "projectRoot": ctx.get("PROJECT_ROOT", ""),
+        "taskRootPath": ctx.get("TASK_ROOT_RELATIVE_PATH", ""),
+    }
+
+
+def _active_workflow(ctx: dict) -> dict:
+    return {
+        "currentPhase": ctx.get("WORKFLOW_CURRENT_PHASE", ""),
+        "currentPhaseState": ctx.get("WORKFLOW_CURRENT_PHASE_STATE", ""),
+        "lastCompletedPhase": ctx.get("WORKFLOW_LAST_COMPLETED_PHASE", ""),
+        "nextRecommendedPhase": ctx.get("WORKFLOW_NEXT_RECOMMENDED_PHASE", ""),
+        "awaitingApproval": ctx.get("WORKFLOW_AWAITING_APPROVAL", "false") == "true",
+        "routingStatus": ctx.get("WORKFLOW_ROUTING_STATUS", ""),
+        "allowedOutputs": ctx.get("PHASE_ALLOWED_OUTPUTS", ""),
+        "forbiddenActions": ctx.get("PHASE_FORBIDDEN_ACTIONS", ""),
+    }
+
+
+def _active_run(ctx: dict) -> dict:
+    return {
+        "runDirectoryPath": ctx.get("RUN_DIR_RELATIVE_PATH", ""),
+        "runManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
+        "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
+        "promptSnapshotPath": ctx.get("RUN_PROMPT_SNAPSHOT_RELATIVE_PATH", ""),
+        "finalReportPath": ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
+        "finalStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
+        "validatorScriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),
+        "resumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
+        "workerPromptsDirectoryPath": ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
+        "workerResultsDirectoryPath": ctx.get("WORKER_RESULTS_RELATIVE_PATH", ""),
+    }
+
+
+def _active_instruction_set(ctx: dict) -> dict:
+    instruction_set = ctx.get("INSTRUCTION_SET_RELATIVE_PATH", "")
+    clarification = (
+        instruction_set + "/clarification-response.md"
+        if ctx.get("CLARIFICATION_RESPONSE_RELATIVE_PATH", "") else ""
+    )
+    return {
+        "path": instruction_set,
+        "analysisPacketPath": ctx.get("ANALYSIS_PACKET_RELATIVE_PATH", ""),
+        "taskBriefPath": instruction_set + "/task-brief.md",
+        "analysisProfilePath": instruction_set + "/analysis-profile.md",
+        "analysisMaterialPath": instruction_set + "/analysis-material.md",
+        "referenceExpectationsPath": ctx.get("REFERENCE_EXPECTATIONS_RELATIVE_PATH", ""),
+        "clarificationResponsePath": clarification,
+        "finalReportTemplatePath": ctx.get("FINAL_REPORT_TEMPLATE_RELATIVE_PATH", ""),
+        "finalReportSchemaPath": ctx.get("FINAL_REPORT_SCHEMA_RELATIVE_PATH", ""),
+    }
+
+
+def _active_error_logs(ctx: dict) -> dict:
+    return {
+        "runErrorsLogPath": ctx.get("RUN_ERRORS_LOG_RELATIVE_PATH", ""),
+        "sidecarsByWorkerId": {
+            "claude": ctx.get("CLAUDE_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", ""),
+            "codex": ctx.get("CODEX_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", ""),
+            "gemini": ctx.get("GEMINI_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", ""),
+            "report-writer": ctx.get("REPORT_WRITER_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", ""),
+        },
+    }
+
+
+def _active_executor_worktree(ctx: dict) -> dict:
+    return {
+        "status": ctx.get("EXECUTOR_WORKTREE_STATUS", ""),
+        "path": ctx.get("EXECUTOR_WORKTREE_PATH", ""),
+        "branch": ctx.get("EXECUTOR_WORKTREE_BRANCH", ""),
+        "baseRef": ctx.get("EXECUTOR_WORKTREE_BASE_REF", ""),
+        "note": ctx.get("EXECUTOR_WORKTREE_NOTE", ""),
+    }
+
+
+def _active_source_artifacts(ctx: dict) -> dict:
+    return {
+        "taskManifestPath": ctx.get("TASK_MANIFEST_RELATIVE_PATH", ""),
+        "runContextPath": ctx.get("RUN_CONTEXT_RELATIVE_PATH", ""),
+        "runInputsPath": ctx.get("RUN_INPUTS_RELATIVE_PATH", ""),
+        "historyTimelinePath": ctx.get("TIMELINE_RELATIVE_PATH", ""),
+    }
+
+
+def _active_lazy_read_plan() -> dict:
+    return {
+        "leadPhase1Primary": True,
+        "readTaskIndexOnlyForHumanSummary": True,
+        "readHistoryTimelineOnlyForHistoryOrCarryInDisambiguation": True,
+        "readFinalReportTemplateOnlyForReportWriter": True,
+    }
+
+
 # --------------------------------------------------------------------------- #
 # team-state
 # --------------------------------------------------------------------------- #
 
 
+def render_active_run_context(active_context_path: str, ctx: dict) -> None:
+    """Write the compact lead intake surface for the current run.
+
+    This is an interface file, not a replacement for task/run manifests. The
+    source manifests remain the audit/replay authority; this file concentrates
+    the fields the lead needs at Phase 1 so it does not have to recompose the
+    current run from several shallow artifacts.
+    """
+    payload = {
+        "schemaVersion": "1.0",
+        "kind": "active-run-context",
+        "task": _active_task(ctx),
+        "workflow": _active_workflow(ctx),
+        "run": _active_run(ctx),
+        "instructionSet": _active_instruction_set(ctx),
+        "workers": _active_workers(ctx),
+        "errorLogs": _active_error_logs(ctx),
+        "executorWorktree": _active_executor_worktree(ctx),
+        "sourceArtifacts": _active_source_artifacts(ctx),
+        "lazyReadPlan": _active_lazy_read_plan(),
+    }
+    _write_json(Path(active_context_path), payload)
+
+
 def render_team_state(team_state_path: str, ctx: dict) -> None:
     selected = _resolve_workers(ctx)
     catalog = _worker_catalog(ctx)
@@ -598,6 +746,121 @@ def _required_worker_roles(ctx: dict, reviewers: list[str]) -> list[dict]:
     ]
 
 
+def _derive_phase_states(existing_workflow: dict, ctx: dict) -> tuple[dict, str, str]:
+    """phaseStates dict + (current_phase, current_phase_state) 를 도출한다.
+
+    기존 manifest 의 phaseStates 를 보존하면서 PHASE_SEQUENCE 의 모든 phase 를
+    not-started 로 채우고 current_phase 만 현재 상태로 덮어쓴다."""
+    phase_states = (
+        existing_workflow.get("phaseStates", {})
+        if isinstance(existing_workflow.get("phaseStates"), dict)
+        else {}
+    )
+    current_phase = ctx.get("WORKFLOW_CURRENT_PHASE", ctx.get("TASK_TYPE", ""))
+    current_phase_state = ctx.get("WORKFLOW_CURRENT_PHASE_STATE", "not-started")
+    for phase in PHASE_SEQUENCE:
+        phase_states.setdefault(phase, "not-started")
+    if current_phase:
+        phase_states[current_phase] = current_phase_state
+    return phase_states, current_phase, current_phase_state
+
+
+def _derive_next_recommended_phase(
+    current_phase: str, current_phase_state: str, existing_workflow: dict, ctx: dict
+) -> str:
+    """canonical next phase 를 deterministic 하게 결정한다.
+
+    `current_phase` 가 terminal-success(`completed`) 가 아니면 그 자리에 머무르도록
+    recommend 한다. `prepared` / `in-progress` / `blocked` / `error` /
+    `contract-violated` 상태에서 다음 phase 로 미리 advance 하면 wizard(와 사람)
+    가 현재 phase 를 끝난 것으로 오인한다. (Historical bug: implementation 이
+    `prepared` 상태로 provision 됐을 때 wizard 가 `final-verification` 을 기본
+    task_type 으로 추천했다.)"""
+    canonical_next = DEFAULT_NEXT_PHASE.get(current_phase) or ctx.get(
+        "WORKFLOW_NEXT_RECOMMENDED_PHASE", "unknown"
+    )
+    existing_next = existing_workflow.get("nextRecommendedPhase") or ""
+    if current_phase_state not in {"completed"}:
+        # 아직 끝나지 않음 — 같은 phase 를 추천한다. sequence 상 더 앞을 가리키는
+        # stale existing_next 는 무시하고, 같은 current_phase 를 가리키는 값만 존중.
+        return current_phase
+    if existing_next and existing_next != current_phase:
+        return existing_next
+    return canonical_next
+
+
+def _derive_latest_pointers(existing: dict, ctx: dict, current_report_relative: str) -> dict:
+    """latest run/report/team 포인터 + lastSafeCheckpoint 를 도출한다.
+
+    render-only 경로는 기존 manifest 의 포인터를 보존(checkpoint 가 진행 중인
+    실제 run 을 덮어쓰지 않도록)하고, 일반 경로는 이번 run 의 ctx 값으로 갱신한다."""
+    render_only = ctx.get("RENDER_ONLY", "") == "true"
+    existing_workflow = (
+        existing.get("workflow", {}) if isinstance(existing.get("workflow"), dict) else {}
+    )
+    existing_checkpoint = existing_workflow.get("lastSafeCheckpoint", {})
+    if not isinstance(existing_checkpoint, dict):
+        existing_checkpoint = {}
+    if render_only:
+        return {
+            "lastSafeCheckpoint": {
+                "label": existing_checkpoint.get("label", ""),
+                "taskManifestPath": existing_checkpoint.get(
+                    "taskManifestPath", ctx.get("TASK_MANIFEST_RELATIVE_PATH", "")
+                ),
+                "taskIndexPath": existing_checkpoint.get(
+                    "taskIndexPath", ctx.get("TASK_INDEX_RELATIVE_PATH", "")
+                ),
+                "latestRunPath": existing_checkpoint.get(
+                    "latestRunPath", existing.get("latestRunPath", "")
+                ),
+                "latestRunManifestPath": existing_checkpoint.get(
+                    "latestRunManifestPath", ""
+                ),
+                "latestTeamStatePath": existing_checkpoint.get(
+                    "latestTeamStatePath", existing.get("teamStatePath", "")
+                ),
+                "latestReportPath": existing_checkpoint.get(
+                    "latestReportPath", existing.get("latestReportPath", "")
+                ),
+                "latestResumeCommandPath": existing_checkpoint.get(
+                    "latestResumeCommandPath", existing.get("latestResumeCommandPath", "")
+                ),
+            },
+            "latestRunPath": existing.get("latestRunPath", "")
+            or ctx.get("LATEST_RUN_RELATIVE_PATH", ""),
+            "latestRunStatus": existing.get("latestRunStatus", "")
+            or ctx.get("CURRENT_RUN_STATUS", ""),
+            "latestRunPromptsPath": existing.get("latestRunPromptsPath", "")
+            or ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
+            "latestReportPath": existing.get("latestReportPath", "")
+            or current_report_relative,
+            "latestTeamStatePath": existing.get("teamStatePath", "")
+            or ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
+            "latestResumeCommandPath": existing.get("latestResumeCommandPath", ""),
+        }
+    return {
+        "lastSafeCheckpoint": {
+            "label": ctx.get("WORKFLOW_LAST_SAFE_CHECKPOINT_LABEL", ""),
+            "taskManifestPath": ctx.get("TASK_MANIFEST_RELATIVE_PATH", ""),
+            "taskIndexPath": ctx.get("TASK_INDEX_RELATIVE_PATH", ""),
+            "latestRunPath": ctx.get("LATEST_RUN_RELATIVE_PATH", ""),
+            "latestRunManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
+            "latestTeamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
+            "latestReportPath": current_report_relative,
+            "latestResumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
+        },
+        "latestRunPath": ctx.get("LATEST_RUN_RELATIVE_PATH", ""),
+        "latestRunStatus": ctx.get("CURRENT_RUN_STATUS", ""),
+        "latestRunPromptsPath": ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
+        "latestReportPath": current_report_relative
+        or existing.get("latestReportPath", ""),
+        "latestTeamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
+        "latestResumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", "")
+        or existing.get("latestResumeCommandPath", ""),
+    }
+
+
 def render_task_manifest(manifest_path: str, ctx: dict) -> None:
     path = Path(manifest_path)
     existing = {}
@@ -608,22 +871,6 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
             existing = {}
     reviewers = _resolve_workers(ctx)
     catalog = _worker_catalog(ctx)
-    phase_sequence = [
-        "requirements-discovery",
-        "error-analysis",
-        "implementation-planning",
-        "implementation",
-        "final-verification",
-        "release-handoff",
-    ]
-    default_next_phase = {
-        "requirements-discovery": "pending-routing-decision",
-        "error-analysis": "implementation-planning",
-        "implementation-planning": "implementation",
-        "implementation": "final-verification",
-        "final-verification": "pending-release-handoff",
-        "release-handoff": "done-or-follow-up",
-    }
     required_worker_roles = _required_worker_roles(ctx, reviewers)
     worker_prompt_paths = {item: catalog[item]["promptPath"] for item in reviewers}
     required_agent_status_entries = ["Claude lead"] + [
@@ -633,129 +880,37 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
     current_report_relative = ctx.get("LATEST_REPORT_RELATIVE_PATH") or ctx.get(
         "FINAL_REPORT_RELATIVE_PATH", ""
     )
-    workflow = (
+    existing_workflow = (
         existing.get("workflow", {})
         if isinstance(existing.get("workflow"), dict)
         else {}
     )
-    phase_states = (
-        workflow.get("phaseStates", {})
-        if isinstance(workflow.get("phaseStates"), dict)
-        else {}
+    phase_states, current_phase, current_phase_state = _derive_phase_states(
+        existing_workflow, ctx
     )
-    current_phase = ctx.get("WORKFLOW_CURRENT_PHASE", ctx.get("TASK_TYPE", ""))
-    current_phase_state = ctx.get("WORKFLOW_CURRENT_PHASE_STATE", "not-started")
-    for phase in phase_sequence:
-        phase_states.setdefault(phase, "not-started")
-    if current_phase:
-        phase_states[current_phase] = current_phase_state
     work_category = existing.get("workCategory") or ctx.get(
         "WORKFLOW_WORK_CATEGORY", "unknown"
     )
-    # Compute the canonical next phase from current_phase deterministically.
-    # Only advance past `current_phase` when its state is terminal-success
-    # (`completed`). For `prepared` / `in-progress` / `blocked` / `error` /
-    # `contract-violated` states the recommendation MUST stay on
-    # `current_phase` — advancing prematurely makes wizards (and humans)
-    # think the current phase is done when it has merely been provisioned.
-    # Historical bug: implementation provisioned in `prepared` state caused
-    # the wizard to recommend `final-verification` as the default task_type.
-    canonical_next = default_next_phase.get(
-        current_phase, ctx.get("WORKFLOW_NEXT_RECOMMENDED_PHASE", "unknown")
+    next_recommended_phase = _derive_next_recommended_phase(
+        current_phase, current_phase_state, existing_workflow, ctx
     )
-    existing_next = workflow.get("nextRecommendedPhase") or ""
-    terminal_success_states = {"completed"}
-    if current_phase_state not in terminal_success_states:
-        # Current phase has not finished — recommend staying on it. Suppress
-        # any stale `existing_next` that points further forward in the
-        # sequence; only honour a stale value if it points to the SAME
-        # current_phase (i.e. encodes "re-enter current phase").
-        next_recommended_phase = current_phase
-    elif existing_next and existing_next != current_phase:
-        next_recommended_phase = existing_next
-    else:
-        next_recommended_phase = canonical_next
-    last_completed_phase = workflow.get("lastCompletedPhase") or ctx.get(
+    last_completed_phase = existing_workflow.get("lastCompletedPhase") or ctx.get(
         "WORKFLOW_LAST_COMPLETED_PHASE", ""
     )
-    routing_status = workflow.get("routingStatus") or ctx.get(
+    routing_status = existing_workflow.get("routingStatus") or ctx.get(
         "WORKFLOW_ROUTING_STATUS", "not-applicable"
     )
-    awaiting_approval = workflow.get("awaitingApproval")
+    awaiting_approval = existing_workflow.get("awaitingApproval")
     if not isinstance(awaiting_approval, bool):
         awaiting_approval = ctx.get("WORKFLOW_AWAITING_APPROVAL", "false") == "true"
-    render_only = ctx.get("RENDER_ONLY", "") == "true"
-    existing_checkpoint = (
-        existing.get("workflow", {}).get("lastSafeCheckpoint", {})
-        if isinstance(existing.get("workflow"), dict)
-        else {}
-    )
-    if not isinstance(existing_checkpoint, dict):
-        existing_checkpoint = {}
-    if render_only:
-        last_safe_checkpoint = {
-            "label": existing_checkpoint.get("label", ""),
-            "taskManifestPath": existing_checkpoint.get(
-                "taskManifestPath", ctx.get("TASK_MANIFEST_RELATIVE_PATH", "")
-            ),
-            "taskIndexPath": existing_checkpoint.get(
-                "taskIndexPath", ctx.get("TASK_INDEX_RELATIVE_PATH", "")
-            ),
-            "latestRunPath": existing_checkpoint.get(
-                "latestRunPath", existing.get("latestRunPath", "")
-            ),
-            "latestRunManifestPath": existing_checkpoint.get(
-                "latestRunManifestPath", ""
-            ),
-            "latestTeamStatePath": existing_checkpoint.get(
-                "latestTeamStatePath", existing.get("teamStatePath", "")
-            ),
-            "latestReportPath": existing_checkpoint.get(
-                "latestReportPath", existing.get("latestReportPath", "")
-            ),
-            "latestResumeCommandPath": existing_checkpoint.get(
-                "latestResumeCommandPath", existing.get("latestResumeCommandPath", "")
-            ),
-        }
-        latest_run_relative = existing.get("latestRunPath", "") or ctx.get(
-            "LATEST_RUN_RELATIVE_PATH", ""
-        )
-        latest_run_status = existing.get("latestRunStatus", "") or ctx.get(
-            "CURRENT_RUN_STATUS", ""
-        )
-        latest_run_prompts_relative = existing.get(
-            "latestRunPromptsPath", ""
-        ) or ctx.get("RUN_PROMPTS_RELATIVE_PATH", "")
-        latest_report_relative = (
-            existing.get("latestReportPath", "") or current_report_relative
-        )
-        latest_team_state_relative = existing.get("teamStatePath", "") or ctx.get(
-            "TEAM_STATE_RELATIVE_PATH", ""
-        )
-        latest_resume_command_relative = existing.get("latestResumeCommandPath", "")
-    else:
-        last_safe_checkpoint = {
-            "label": ctx.get("WORKFLOW_LAST_SAFE_CHECKPOINT_LABEL", ""),
-            "taskManifestPath": ctx.get("TASK_MANIFEST_RELATIVE_PATH", ""),
-            "taskIndexPath": ctx.get("TASK_INDEX_RELATIVE_PATH", ""),
-            "latestRunPath": ctx.get("LATEST_RUN_RELATIVE_PATH", ""),
-            "latestRunManifestPath": ctx.get("RUN_MANIFEST_RELATIVE_PATH", ""),
-            "latestTeamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
-            "latestReportPath": current_report_relative,
-            "latestResumeCommandPath": ctx.get(
-                "CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""
-            ),
-        }
-        latest_run_relative = ctx.get("LATEST_RUN_RELATIVE_PATH", "")
-        latest_run_status = ctx.get("CURRENT_RUN_STATUS", "")
-        latest_run_prompts_relative = ctx.get("RUN_PROMPTS_RELATIVE_PATH", "")
-        latest_report_relative = current_report_relative or existing.get(
-            "latestReportPath", ""
-        )
-        latest_team_state_relative = ctx.get("TEAM_STATE_RELATIVE_PATH", "")
-        latest_resume_command_relative = ctx.get(
-            "CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""
-        ) or existing.get("latestResumeCommandPath", "")
+    pointers = _derive_latest_pointers(existing, ctx, current_report_relative)
+    last_safe_checkpoint = pointers["lastSafeCheckpoint"]
+    latest_run_relative = pointers["latestRunPath"]
+    latest_run_status = pointers["latestRunStatus"]
+    latest_run_prompts_relative = pointers["latestRunPromptsPath"]
+    latest_report_relative = pointers["latestReportPath"]
+    latest_team_state_relative = pointers["latestTeamStatePath"]
+    latest_resume_command_relative = pointers["latestResumeCommandPath"]
     convergence_block = _build_convergence_block(ctx)
     payload = {
         "schemaVersion": "1.0",
@@ -791,7 +946,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
         "latestResumeCommandPath": latest_resume_command_relative,
         "teamStatePath": latest_team_state_relative,
         "workflow": {
-            "phaseSequence": phase_sequence,
+            "phaseSequence": PHASE_SEQUENCE,
             "currentPhase": current_phase,
             "currentPhaseState": phase_states.get(current_phase, current_phase_state),
             "phaseStates": phase_states,
@@ -806,6 +961,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
             + "/analysis-profile.md",
             "analysisMaterialPath": ctx.get("INSTRUCTION_SET_RELATIVE_PATH", "")
             + "/analysis-material.md",
+            "analysisPacketPath": ctx.get("ANALYSIS_PACKET_RELATIVE_PATH", ""),
             "taskBriefCopyPath": ctx.get("INSTRUCTION_SET_RELATIVE_PATH", "")
             + "/task-brief.md",
             "referenceExpectationsPath": ctx.get(
@@ -821,6 +977,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
             ),
             "resumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
             "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
+            "activeRunContextPath": ctx.get("ACTIVE_RUN_CONTEXT_RELATIVE_PATH", ""),
             "workerResultsDirectoryPath": ctx.get("WORKER_RESULTS_RELATIVE_PATH", ""),
             "validatorScriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),
         },
@@ -1009,6 +1166,8 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "expectedReportPath": ctx.get("FINAL_REPORT_RELATIVE_PATH", ""),
         "expectedStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
+        "activeRunContextPath": ctx.get("ACTIVE_RUN_CONTEXT_RELATIVE_PATH", ""),
+        "analysisPacketPath": ctx.get("ANALYSIS_PACKET_RELATIVE_PATH", ""),
         "workerResultsDirectoryPath": ctx.get("WORKER_RESULTS_RELATIVE_PATH", ""),
         "reportTemplatePath": ctx.get("FINAL_REPORT_TEMPLATE_RELATIVE_PATH", ""),
         "validatorScriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),

package/runtime/python/okstra_ctl/render_final_report.py

@@ -9,7 +9,7 @@ the canonical user-facing markdown.
 
 Why this exists: prior to v0.32, report-writer-worker wrote the markdown
 directly. Free-form authoring led to silent contract violations — missing
-columns in the Execution Status table, omitted §7 phase-continuation
+columns in the Execution Status table, omitted §4 phase-continuation
 rows, invented ``## Index`` sections. Routing everything through one
 template + schema cuts those failure modes to zero.
 
@@ -17,6 +17,11 @@ Phase 7 mutation flow: ``okstra-token-usage.py --substitute-data`` fills
 the ``tokenUsage`` and ``executionStatus[].totalTokens`` etc. cells in
 data.json, then re-invokes this renderer so the markdown stays in sync.
 The markdown is never hand-edited.
+
+As of v0.33+, the renderer itself is the schema-enforcement seam: data.json
+is validated against ``schemas/final-report-v1.0.schema.json`` before any
+Jinja2 rendering begins, so schema violations are caught at write-time
+rather than only by the post-hoc ``validators/validate-run.py``.
 """
 from __future__ import annotations
 
@@ -34,6 +39,7 @@ from typing import Any
 import okstra_vendor  # noqa: F401 — side effect: sys.modules aliases
 from jinja2 import ChainableUndefined, Environment, FileSystemLoader
 
+from okstra_ctl.final_report_schema import SchemaError, load_schema, validate as schema_validate
 from okstra_ctl.i18n import I18nError, SUPPORTED_LANGS, load_dictionary, make_jinja_global
 
 
@@ -104,6 +110,29 @@ def _yaml_inline_list(values: list[str]) -> str:
     return "[" + ", ".join(_yaml_scalar(v) for v in values) + "]"
 
 
+def _enforce_schema(data: dict) -> None:
+    """렌더 전에 data.json 을 스키마에 대해 검증하는 seam.
+
+    스키마 파일을 찾지 못하는 경우(손상된 설치 환경)는 경고만 출력하고 계속
+    진행한다 — validate-run 과 install 경고가 이미 해당 상황을 표면화하므로
+    Phase 7 재렌더를 hard-fail 시키는 것은 과도하다.
+    """
+    try:
+        schema = load_schema()
+    except SchemaError as exc:
+        print(
+            f"render-final-report: schema not locatable; skipping schema enforcement ({exc})",
+            file=sys.stderr,
+        )
+        return
+    errors = schema_validate(data, schema)
+    if errors:
+        raise FinalReportRenderError(
+            f"final-report data.json fails schema validation ({len(errors)} error(s)): "
+            + "; ".join(errors[:5])
+        )
+
+
 def _build_environment(template_dir: Path) -> Environment:
     # ChainableUndefined lets optional fields (e.g.
     # ``clarificationCarryIn``, ``ticketCoverage.omit``) silently evaluate
@@ -161,6 +190,8 @@ def render(
     if not template_path.is_file():
         raise FinalReportRenderError(f"template not found: {template_path}")
 
+    _enforce_schema(data)
+
     lang = resolve_report_language(data, override=report_language)
     try:
         dictionary = load_dictionary(lang)