okstra 0.186.7 → 0.188.0

package/runtime/python/okstra_ctl/report_finalize.py

@@ -42,11 +42,15 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Callable, Mapping, Sequence
 
-from .agent_activity import ActivityProjectionError, project_agent_activity
+from .agent.activity import ActivityProjectionError, project_agent_activity
 from .report_contract import apply_execution_roles
 from .report_assembly import ReportAssemblyError, assemble_report
 from .dispatch_state import DispatchError, link_agent_dispatch_result
-from .final_report_paths import final_report_data_path, final_report_markdown_path
+from .final_report_paths import (
+    final_report_data_path,
+    final_report_markdown_path,
+    sidecar_source_rel,
+)
 from .paths import task_dir, task_manifest_file
 from .release_gate import release_handoff_allowed
 from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
@@ -57,6 +61,16 @@ from .stage_targets import (
 )
 from .session import observe_lead_session
 
+# 포인터 값 타입만 쓴다. `okstra_project.phase_pointer` 는 okstra 안의
+# 어떤 것도 import 하지 않는 leaf 라 순환이 없다 — 그 모듈 도크스트링.
+from okstra_project.phase_pointer import (
+    STATUS_BLOCKED,
+    STATUS_PENDING,
+    STATUS_READY,
+    STATUS_TERMINAL,
+    promote as promote_next_phase,
+)
+
 
 STEP_PROJECT_ACTIVITY = "project-activity"
 STEP_CHECK_SOURCE = "check-source"
@@ -120,13 +134,6 @@ def resolve_optional_path(project_root: Path, value: Any) -> Path | None:
     return resolve_project_path(project_root, value)
 
 
-def project_relative_path(project_root: Path, path: Path) -> str:
-    try:
-        return path.relative_to(project_root).as_posix()
-    except ValueError:
-        return str(path)
-
-
 def task_group(manifest: Mapping[str, Any]) -> str:
     value = string_value(manifest.get("taskGroup"))
     if value:
@@ -337,8 +344,15 @@ def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
                 ctx.task_type,
                 "--seq",
                 ctx.seq,
+                # 사이드카가 되짚는 기준은 태스크 루트다. 프로젝트 루트
+                # 기준으로 넘기던 동안 HTML Export 가 만든 사이드카는
+                # 방향 선택 게이트를 통과할 수 없었다.
                 "--source-report",
-                project_relative_path(ctx.project_root, markdown_path),
+                sidecar_source_rel(markdown_path),
+                # 머리말 소요 시간의 출처. 보고서 seq 로 되짚으면 seq 가 갈린
+                # run 의 team-state 를 읽는다 — 여기서는 이미 알고 있다.
+                "--team-state",
+                str(ctx.team_state_path),
             ],
         ),
         (
@@ -491,9 +505,47 @@ def run_finalize(
         steps.append(step_payload(name, command, result))
         if result.returncode != 0 and not first_failure:
             first_failure = f"{name} failed with exit code {result.returncode}"
-    if first_failure:
-        return {"ok": False, "reason": first_failure, "steps": steps}
-    return {"ok": True, "reason": "", "steps": steps}
+    pointer, pointer_error = _recorded_next_phase(ctx)
+    payload: dict[str, Any] = {
+        "ok": not first_failure,
+        "reason": first_failure,
+        "steps": steps,
+        "nextRecommendedPhase": pointer,
+    }
+    if pointer_error:
+        payload["nextRecommendedPhaseError"] = pointer_error
+    # closeout 이 실제로 건넬 명령. 표를 리드의 기억에 맡기지 않는다.
+    payload["nextCommand"] = closeout_command(payload)
+    return payload
+
+
+def _recorded_next_phase(ctx: FinalizeContext) -> tuple[dict[str, str], str]:
+    """`validate-run` 이 방금 태스크 매니페스트에 쓴 다음 phase 포인터.
+
+    리드의 closeout 표는 이 포인터의 `status` / `rationale` 로 분기하는데,
+    포인터는 리드가 쓰는 필드가 아니고(`prompts/lead/report-writer.md`
+    "Nobody writes this pointer by hand"), 이 시퀀스의 결과에도 실리지
+    않았다. 값 없이 표만 받은 리드에게 남는 행동은 상태를 늘어놓고 턴을
+    끝내는 것뿐이다.
+
+    여기서 다시 계산하지 않는다 — 투영은 `validate-run` 의
+    `update_workflow_metadata` 가 하고, 이 함수는 그것이 파일에 남긴 값을
+    읽어 옮기기만 한다. `--only` 로 `validate-run` 을 건너뛴 호출에서는
+    이전 run 이 남긴 값이 그대로 읽히므로, 이번 시퀀스가 그 단계를 돌았는지는
+    `steps` 로 판단한다.
+
+    읽기가 실패하면 값을 지어내지 않고 사유를 함께 돌려준다.
+    """
+    try:
+        manifest = load_owned_object(
+            ctx.task_manifest_path, artifact="task-manifest"
+        )
+    except (JsonBoundaryError, OSError) as exc:
+        return promote_next_phase(None), f"{ctx.task_manifest_path}: {exc}"
+    workflow = manifest.get("workflow")
+    if not isinstance(workflow, Mapping):
+        return promote_next_phase(None), ""
+    return promote_next_phase(workflow.get("nextRecommendedPhase")), ""
 
 
 def _run_finalize_step(
@@ -529,6 +581,7 @@ def _run_project_activity(
     try:
         if ctx.report_contract_version == "3.0":
             assembled = assemble_report(ctx.project_root, ctx.manifest_path)
+            _point_task_manifest_at_report(ctx)
             count = len(assembled.get("agentActivity") or [])
         else:
             rows = project_agent_activity(
@@ -556,6 +609,34 @@ def write_execution_roles(ctx: FinalizeContext) -> None:
     write_owned_object_atomic(ctx.data_path, updated, artifact="final report record")
 
 
+def _point_task_manifest_at_report(ctx: FinalizeContext) -> None:
+    """게시한 data.json 을 latestReport 로 올린다.
+
+    render-only prepare 는 기존 포인터를 보존한다. 조립이 새 리포트를 썼는데도
+    task-manifest 가 예전 seq 를 가리키면 검사가 통과해도 상태가 004 에 남는다.
+    """
+    path = ctx.task_manifest_path
+    if not path.is_file() or not ctx.data_path.is_file():
+        return
+    try:
+        payload = load_owned_object(path, artifact="task manifest")
+    except (OSError, JsonBoundaryError):
+        return
+    if not isinstance(payload, Mapping):
+        return
+    try:
+        relative = ctx.data_path.resolve().relative_to(
+            ctx.project_root.resolve()
+        ).as_posix()
+    except ValueError:
+        relative = str(ctx.data_path)
+    if payload.get("latestReportRecordPath") == relative:
+        return
+    updated = dict(payload)
+    updated["latestReportRecordPath"] = relative
+    write_owned_object_atomic(path, updated, artifact="task manifest")
+
+
 def _link_lead_result_for_validation(ctx: FinalizeContext) -> None:
     """Link the lead-authored synthesis artifact before Phase 7 validation."""
     manifest = _load_manifest(ctx.manifest_path)
@@ -566,8 +647,11 @@ def _link_lead_result_for_validation(ctx: FinalizeContext) -> None:
     lead_dispatches = [
         row for row in (team_state.get("agentDispatches") or [])
         if isinstance(row, Mapping)
-        and row.get("audience") == "lead"
-        and row.get("workerId") == "lead"
+        and (
+            row.get("audience") == "lead"
+            or row.get("workerId") == "lead"
+            or str(row.get("assignmentRef") or "") in {"lead", "lead/lead"}
+        )
     ]
     if len(lead_dispatches) != 1:
         return
@@ -621,8 +705,41 @@ def _context_from_args(args: argparse.Namespace) -> FinalizeContext:
     )
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra report-finalize --project-root <dir> --run-manifest <path> \
+    --report <final-report-<task-type>-<seq>.md> [--team-state <path>]
+
+Runs the six Phase 7 steps in their contractual order against one final-report:
+
+  1. project-activity  project the run's activity events into the data.json
+  2. check-source      verify the data.json is the English SSOT
+  3. token-usage       substitute real token/cost numbers into the data.json
+  4. render-views      write the schema-v2 task-specific *.html sibling; v1
+                       keeps the legacy conditional interactive view
+  5. spawn-followups   turn section 4 rows into task stubs
+  6. validate-run      validate the finished run artifacts
+
+Every step is idempotent, so re-running after a fixed failure is safe. The
+sequence stops at the first non-zero exit and reports which step failed, except
+token-usage: its input is the lead session log, so a failure there does not
+take the html, follow-ups and validation after it down with it. Whenever a step
+exits non-zero the command prints the --only flags that resume the sequence
+from the earliest failing step — follow those rather than rerunning the failing
+step alone, which would leave the html rendered before the tokens landed.
+
+This is the same code path the Codex lead adapter runs automatically after its
+report-writer completes, so a Claude-led and a Codex-led run finalize
+identically.
+
+  --workspace-root is owned by this command.
+"""
+
+
 def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
+        prog="okstra report-finalize",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         description="Run the Phase 7 report post-processing sequence.",
     )
     parser.add_argument("--project-root", required=True)
@@ -632,7 +749,9 @@ def _parser() -> argparse.ArgumentParser:
         required=True,
         help="final-report record (.data.json); a leftover markdown path still locates the sibling record",
     )
-    parser.add_argument("--workspace-root", required=True)
+    # `okstra report-finalize` 래퍼(src/lib/python-command.mts)가 넣고, 사용자가
+    # 직접 주면 거절한다. usage 에 필수로 찍히면 그 거절과 모순되므로 감춘다.
+    parser.add_argument("--workspace-root", required=True, help=argparse.SUPPRESS)
     parser.add_argument(
         "--team-state",
         default="",
@@ -691,6 +810,80 @@ def _recovery_step_names(
     return []
 
 
+def closeout_command(result: Mapping[str, Any]) -> dict[str, str]:
+    """이 run 이 사용자에게 건네야 할 명령.
+
+    `prompts/launch.template.md` "User closeout (BLOCKING)" 의 표를 코드로
+    내린 것이다. 그 표는 문서에만 있었고, 표가 분기하는 포인터는 리드에게
+    도착하지도 않았다 — 규칙이 있고 집행이 없는 자리였다. 여기서 판정하면
+    리드가 표를 기억해 따라갈 필요가 없고, 리드가 침묵해도 명령은
+    `report-finalize` 출력에 남는다.
+
+    산문을 해석하지 않는다. `blocked` / `pending` 의 근거 문장은 이미 무엇을
+    실행할지 말하고 있으므로(`okstra_ctl.next_phase` 의 승인 차단 근거,
+    `validators/validate-run.py` 의 검증 실패 근거), 그 문장을 그대로 인용할
+    자리로 넘기고 명령 칸은 비운다. 근거에서 명령을 다시 뽑아내는 것은
+    기록된 값의 재구현이다.
+
+    돌려주는 것은 `command` 와 `note` 두 칸이다. `command` 가 비면 근거
+    문장이 그 자리를 대신한다.
+    """
+    failed_validate = any(
+        step.get("name") == STEP_VALIDATE_RUN and step.get("exitCode") != 0
+        for step in (result.get("steps") or [])
+        if isinstance(step, Mapping)
+    )
+    if failed_validate:
+        return {
+            "command": "/okstra-run",
+            "note": "validate-run failed — name the blocking cause in one line, "
+                    "then re-run this same phase",
+        }
+    pointer = result.get("nextRecommendedPhase")
+    if not isinstance(pointer, Mapping):
+        return {"command": "/okstra-inspect status", "note": "no pointer recorded"}
+    status = str(pointer.get("status") or "").strip()
+    phase = str(pointer.get("phase") or "").strip()
+    rationale = str(pointer.get("rationale") or "").strip()
+    if status == STATUS_READY and phase:
+        return {"command": f"/okstra-run → {phase}", "note": ""}
+    if status == STATUS_TERMINAL:
+        return {
+            "command": "",
+            "note": "the lifecycle ends here — say the task is finished, name any "
+                    "follow-up tasks this run registered, and do not send the user "
+                    "to /okstra-inspect",
+        }
+    if status in (STATUS_BLOCKED, STATUS_PENDING) and rationale:
+        return {
+            "command": "",
+            "note": "quote the rationale above and issue the command it names",
+        }
+    return {"command": "/okstra-inspect status", "note": ""}
+
+
+def _next_phase_summary_lines(result: Mapping[str, Any]) -> list[str]:
+    """다음 phase 포인터와 그것이 정하는 명령을 사람이 읽는 줄로."""
+    pointer = result.get("nextRecommendedPhase")
+    if not isinstance(pointer, Mapping):
+        return []
+    lines = [
+        f"next phase status: {pointer.get('status') or '-'}",
+        f"next phase: {pointer.get('phase') or '-'}",
+    ]
+    rationale = str(pointer.get("rationale") or "").strip()
+    if rationale:
+        lines.append(f"next phase rationale: {rationale}")
+    error = str(result.get("nextRecommendedPhaseError") or "").strip()
+    if error:
+        lines.append(f"next phase pointer unreadable: {error}")
+    closeout = closeout_command(result)
+    lines.append(f"next command: {closeout['command'] or '-'}")
+    if closeout["note"]:
+        lines.append(f"next command note: {closeout['note']}")
+    return lines
+
+
 def main(argv: Sequence[str] | None = None) -> int:
     args = _parser().parse_args(argv)
     try:
@@ -708,6 +901,10 @@ def main(argv: Sequence[str] | None = None) -> int:
     print("finalize steps:", file=sys.stderr)
     for line in _step_summary_lines(result, order):
         print(line, file=sys.stderr)
+    # closeout 이 분기하는 값. JSON 을 파싱하지 않고 훑는 리드에게도 보이도록
+    # 요약 줄로 한 번 더 낸다.
+    for line in _next_phase_summary_lines(result):
+        print(line, file=sys.stderr)
     if not result["ok"]:
         print(f"error: {result['reason']}", file=sys.stderr)
         recovery = _recovery_step_names(result, order)

package/runtime/python/okstra_ctl/report_html/common.py

@@ -68,8 +68,8 @@ def _own_section_ids(data: dict, omitted_fields: tuple[str, ...] = ()) -> set[st
 
     The ledger is the fallback home for a cited row, so it must not claim an id
     that has one — two elements with the same anchor send half the links to the
-    wrong place. `crossVerification.consensus` numbers its rows `C-001` in some
-    runs, exactly where a clarification lives.
+    wrong place. `crossVerification.consensus` numbers its rows `CV-001`, a
+    namespace of its own, so a `C-NNN` in the report has exactly one home.
 
     `omitted_fields` names task-block fields the HTML template does not render,
     so their ids do not count as anchored.

package/runtime/python/okstra_ctl/report_html/render.py

@@ -69,25 +69,21 @@ def _report_meta(data: dict, run_meta: HtmlRunMeta) -> dict[str, object]:
 
 
 def _localize(data: dict, data_path: Path) -> tuple[dict, str]:
-    """Apply the translation sidecar for this report's language, if there is one.
-
-    The data.json is the English SSOT and is never rewritten — the sidecar is
-    read here and overlaid onto an in-memory copy, so only this HTML document
-    speaks the reader's language. A pointer the sidecar left untranslated
-    renders in English; that keeps a half-finished translation readable, and
-    the counts are printed because a silently half-empty sidecar otherwise
-    ships looking finished.
+    """이 리포트 언어의 번역 사이드카를 메모리 복사본에 덮어쓴다.
+
+    data.json 은 영어 정본이고 고치지 않는다. 사람이 읽는 HTML 만 독자 언어다.
+    사이드카가 빠진 포인터는 영어로 남긴다. 사이드카 파일 자체가 없으면
+    크롬만 번역되고 본문은 영어로 나가므로 렌더를 거부한다.
     """
     lang = str((data.get("meta") or {}).get("reportLanguage") or "en")
     if lang == "en":
         return data, lang
     sidecar_file = translation_sidecar_path(data_path, lang)
     if not sidecar_file.is_file():
-        sys.stdout.write(
-            f"note: no {lang} translation sidecar at {sidecar_file.name}; "
-            "rendering the English source\n"
+        raise HtmlRenderError(
+            f"no {lang} translation sidecar at {sidecar_file.name}; "
+            "human HTML cannot fall back to the English source"
         )
-        return data, lang
     payload = load_owned_object(sidecar_file, artifact="translation sidecar")
     strings = payload.get("strings")
     if not isinstance(strings, dict):

package/runtime/python/okstra_ctl/report_language.py

@@ -1,8 +1,12 @@
-"""Report-language resolution for the report-writer prompt.
+"""Report-language resolution — the one place the precedence lives.
 
-Both dispatchers stamp `**Report Language:**` into the report-writer prompt, so
-the precedence (project config → global config → inferred from the task brief)
-lives here rather than in whichever dispatcher happened to need it first.
+Two surfaces need the answer and must agree: the `**Report Language:**` line
+both dispatchers stamp into the report-writer prompt, and `reportLanguage` in
+the run manifest, which report assembly copies into `meta.reportLanguage` and
+the HTML renderer reads. When only the prompt called this, a project could ask
+for `ko`, get a Korean-instructed writer, and still ship an English report.
+
+Precedence: project config → global config → inferred from the task brief.
 """
 from __future__ import annotations