okstra 0.176.1 → 0.177.1

package/runtime/python/okstra_ctl/pane_reclaim.py

@@ -1,12 +1,15 @@
-"""활성 run 스코프 조회 — pane 정리 의무를 어느 run 에 걸지 고르는 데 쓴다.
+"""진행 중 run 조회 — pane 회수 의무를 어느 run 에 걸지 고르는 데 쓴다.
 
 호출자는 `SessionStart(compact)` 훅(`okstra-compact-reminder.sh`) 하나다. 압축
-직후 리드에게 "이 run 의 완료 teammate pane 을 라운드 경계마다 회수하라"는 의무를
+직후 리드에게 "이 run 의 끝난 워커 pane 을 라운드 경계마다 회수하라"는 의무를
 재주입할 때, 그 대상이 되는 이 프로젝트의 진행 중 run 을 여기서 찾는다.
 
-완료 판정(`is_completed_status`)과 프로젝트 무관 전체 조회(`active_run_dirs`)도
-여기 있었으나, 그것을 쓰던 `okstra-trace-cleanup.sh --reclaim-completed` 와
-`okstra-subagent-reclaim.sh` 가 제거되면서 함께 사라졌다.
+정본은 run 디렉터리다(ADR-0011). 신호는 그 run 의 가장 최근 team-state 에
+비종결 배치가 남아 있는지다. 이전 구현은 `~/.okstra/active.jsonl` 을 읽었는데,
+그 원장은 `initial_status="running"` 으로 기록된 run 만 담고 in-session 경로는
+`--render-only` 강제로 항상 `prepared` 가 되어 종결로 라우팅된다 — 실측에서 그
+파일은 0행이었고 이 훅은 한 번도 발화하지 않았다. `state/lead-pane.id` 도 신호가
+못 된다: 한 번 기록된 뒤 지워지지 않아 끝난 run 을 영구히 진행 중으로 읽는다.
 """
 from __future__ import annotations
 
@@ -14,54 +17,57 @@ import json
 import sys
 from pathlib import Path
 
-from .paths import resolve_under_root
-from .reconcile import NON_TERMINAL_RECENT_STATUSES
+from .dispatch_state import NON_TERMINAL_WORKER_STATUSES
 
 
-def _iter_active_run_dirs(home: Path):
-    """active.jsonl 의 진행 중 run 마다 (projectRoot_str, 절대 run_dir) 를 yield.
-    runDirRel 의 base 는 projectRoot(paths.compute_run_paths 의 _rel 기준)."""
-    path = home / "active.jsonl"
-    if not path.is_file():
-        return
-    for line in path.read_text(encoding="utf-8").splitlines():
-        line = line.strip()
-        if not line:
-            continue
-        try:
-            row = json.loads(line)
-        except json.JSONDecodeError:
-            continue
-        # 대상(진행 중) 집합은 reconcile 의 NON_TERMINAL_RECENT_STATUSES 가
-        # SSOT. reserving 은 아직 run-dir 산출물이 없어 이 집합에 들어있지
-        # 않으므로 자연히 제외된다(allowlist).
-        if row.get("status") not in NON_TERMINAL_RECENT_STATUSES:
-            continue
-        run_dir = resolve_under_root(row.get("projectRoot"), row.get("runDirRel"))
-        if run_dir is not None:
-            yield row.get("projectRoot"), run_dir
+def _newest_team_state(state_dir: Path) -> Path | None:
+    """한 run 디렉터리의 최신 team-state.
+
+    seq 는 3자리 zero-pad 라 이름 정렬이 곧 순서다. run 하나에 seq 가 누적되고
+    이전 라운드의 `in-progress` 행이 그 파일에 남으므로, 최신이 아닌 파일을 읽으면
+    몇 시간 전에 끝난 run 을 진행 중으로 보고한다.
+    """
+    files = sorted(state_dir.glob("team-state-*.json"))
+    return files[-1] if files else None
 
 
-def active_run_dirs_for_project(home: Path, cwd: Path) -> list[Path]:
-    """진행 중 run 중 projectRoot 이 cwd(또는 그 상위)인 것의 절대 run-dir 목록.
-    SessionStart(compact) 훅이 이 프로젝트의 run 에만 리마인더를 걸도록 스코프한다."""
-    cwd_r = Path(cwd).resolve()
+def _has_live_dispatch(team_state_path: Path) -> bool:
+    try:
+        payload = json.loads(team_state_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    if not isinstance(payload, dict):
+        return False
+    return any(
+        isinstance(record, dict)
+        and record.get("status") in NON_TERMINAL_WORKER_STATUSES
+        for record in payload.get("workerDispatches", [])
+    )
+
+
+def in_flight_run_dirs(project_root: Path) -> list[Path]:
+    """비종결 배치를 아직 들고 있는 이 프로젝트의 run 디렉터리 목록.
+
+    `runs/<task-type>/` 와 stage 격리 run 의 `runs/<task-type>/stage-<N>/` 을 모두
+    훑는다. 후자를 빼면 `implementation` 과 단일 stage `final-verification` 이
+    통째로 누락된다.
+    """
+    tasks_root = Path(project_root) / ".okstra" / "tasks"
+    if not tasks_root.is_dir():
+        return []
     out: list[Path] = []
-    for project_root, run_dir in _iter_active_run_dirs(home):
-        if not project_root:
-            continue
-        try:
-            project_root_r = Path(project_root).resolve()
-        except OSError:
+    for state_dir in sorted(tasks_root.glob("*/*/runs/**/state")):
+        if not state_dir.is_dir():
             continue
-        if cwd_r == project_root_r or cwd_r.is_relative_to(project_root_r):
-            out.append(run_dir)
+        newest = _newest_team_state(state_dir)
+        if newest is not None and _has_live_dispatch(newest):
+            out.append(state_dir.parent)
     return out
 
 
 def main(argv: list[str]) -> int:
-    if len(argv) == 3 and argv[0] == "--active-dirs-for":
-        for run_dir in active_run_dirs_for_project(Path(argv[1]), Path(argv[2])):
+    if len(argv) == 2 and argv[0] == "--in-flight-run-dirs-for":
+        for run_dir in in_flight_run_dirs(Path(argv[1])):
             print(run_dir)
         return 0
     return 1

package/runtime/python/okstra_ctl/release_gate.py

@@ -0,0 +1,56 @@
+"""final-verification 판정이 release-handoff 진입을 허용하는지 판정한다.
+
+검증기(`validators/validate-run.py`)와 핸드오프(`handoff.py`), 그리고 HTML 리포트가
+모두 같은 답을 내야 하므로 규칙은 여기 한 번만 산다.
+
+`accepted` 는 그대로 통과한다. `conditional-accept` 는 모든 조건이 스스로
+`blocksReleaseHandoff: false` 라고 선언했을 때만 통과한다 — 릴리스를 막는다고 적힌
+조건이 하나라도 있으면 막힌다. 조건 목록이 비어 있는 `conditional-accept` 는
+그 자체가 계약 위반이므로(조건을 빠짐없이 적어야 한다) 여기서도 막는다.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+RELEASE_HANDOFF_TARGETS = frozenset({"release-handoff", "release-handoff(stage-group)"})
+
+
+def verdict_token(data: Mapping[str, Any]) -> str:
+    """리포트의 유일한 판정 토큰 자리에서 읽은 값(소문자, 공백 제거)."""
+    final_verdict = data.get("finalVerdict")
+    if not isinstance(final_verdict, Mapping):
+        return ""
+    return str(final_verdict.get("verdictToken") or "").strip().lower()
+
+
+def _conditions(data: Mapping[str, Any]) -> list[Mapping[str, Any]]:
+    final_verdict = data.get("finalVerdict")
+    if not isinstance(final_verdict, Mapping):
+        return []
+    rows = final_verdict.get("conditionalAcceptanceConditions")
+    if not isinstance(rows, list):
+        return []
+    return [row for row in rows if isinstance(row, Mapping)]
+
+
+def blocking_condition_ids(data: Mapping[str, Any]) -> list[str]:
+    """릴리스를 막는다고 선언된 조건의 id. 선언이 없거나 참이면 막는 것으로 읽는다."""
+    return [
+        str(row.get("id") or "<id 없음>")
+        for row in _conditions(data)
+        if row.get("blocksReleaseHandoff") is not False
+    ]
+
+
+def release_handoff_allowed(data: Mapping[str, Any]) -> bool:
+    """이 final-verification 리포트가 release-handoff 로 넘어가도 되는가."""
+    token = verdict_token(data)
+    if token == "accepted":
+        return True
+    if token != "conditional-accept":
+        return False
+    conditions = _conditions(data)
+    if not conditions:
+        return False
+    return not blocking_condition_ids(data)

package/runtime/python/okstra_ctl/render.py

@@ -735,6 +735,15 @@ def render_team_state(team_state_path: str, ctx: dict) -> None:
     catalog = _worker_catalog(ctx)
     worker_dispatch_plan = _worker_dispatch_plan(ctx)
     workers = []
+    for row in _optional_worker_roles(ctx):
+        workers.append({
+            **{key: row[key] for key in (
+                "workerId", "role", "agent", "provider", "runner",
+                "model", "modelExecutionValue", "resultPath", "promptPath",
+            )},
+            "status": "not-run",
+            "reason": "",
+        })
     for w in selected:
         m = catalog[w]
         workers.append(
@@ -1133,6 +1142,44 @@ def _required_worker_roles(ctx: dict, reviewers: list[str]) -> list[dict]:
     ]
 
 
+def _optional_worker_roles(ctx: dict) -> list[dict]:
+    """Roles this run may dispatch but does not require — today, the critics.
+
+    A critic is opt-in, so it never belonged in `requiredWorkerRoles`. But it
+    was absent from the roster entirely, and both `okstra team dispatch` and
+    the liveness reader locate a worker by its team-state row: dispatching a
+    critic failed with `team-state has no workerId=acceptance`, while adding
+    the row by hand failed validation as an `unexpected worker role`. Declaring
+    it here makes the roster say what the run may run, so both sides agree.
+
+    Keyed off `invocationAssignments`, which is where the run records the
+    critic it actually resolved — an absent `critic/*` entry means no critic.
+    """
+    assignments = _invocation_assignments(ctx)
+    roles: list[dict] = []
+    for assignment_ref, assignment in sorted(assignments.items()):
+        if not assignment_ref.startswith("critic/"):
+            continue
+        provider = str(assignment.get("provider", ""))
+        roles.append({
+            # `okstra team dispatch` projects a v2 worker's state key off the
+            # assignment ref's last segment; the row it looks up must use it.
+            "workerId": assignment_ref.rsplit("/", 1)[-1],
+            "role": f"{provider_spec(provider).display_label} critic",
+            "agent": provider,
+            "provider": provider,
+            "runner": str(assignment.get("runner", "")),
+            "model": str(assignment.get("model", "")),
+            "modelExecutionValue": str(assignment.get("modelExecutionValue", "")),
+            # The lead names these when it materializes the invocation; a
+            # critic has no prompt or result until it is dispatched.
+            "resultPath": "",
+            "promptPath": "",
+            "attemptRequired": False,
+        })
+    return roles
+
+
 def _reporter_confirmation_status(brief_bytes: bytes) -> str:
     try:
         lines = brief_bytes.decode("utf-8").splitlines()
@@ -1448,6 +1495,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
             "minimumPreferredWorkerResults": len(reviewers),
             "requiredWorkerAttempts": reviewers,
             "requiredWorkerRoles": required_worker_roles,
+            "optionalWorkerRoles": _optional_worker_roles(ctx),
             "requiredAgentStatusEntries": required_agent_status_entries,
             "requireDistinctLeadFromWorkerSession": True,
             "requireAllRequiredWorkerAttempts": True,
@@ -1644,6 +1692,10 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "taskId": ctx.get("TASK_ID", ""),
         "taskKey": ctx.get("TASK_KEY", ""),
         "taskType": ctx.get("TASK_TYPE", ""),
+        # Every other path in this manifest is project-relative; this is the
+        # anchor they resolve against. Convergence reads it to place run
+        # artifacts, so a manifest without it cannot seed a round.
+        "projectRoot": ctx.get("PROJECT_ROOT", ""),
         "hostRuntime": ctx.get("HOST_RUNTIME", "") or _lead_runtime(ctx),
         "leadRuntime": _lead_runtime(ctx),
         "leadRuntimeRequest": ctx.get("LEAD_RUNTIME_REQUEST", "") or _lead_runtime(ctx),
@@ -1765,6 +1817,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
             "finalSynthesisOwner": lead_role,
             "requiredWorkerAttempts": reviewers,
             "requiredWorkerRoles": required_worker_roles,
+            "optionalWorkerRoles": _optional_worker_roles(ctx),
             "requiredAgentStatusEntries": [lead_role]
             + [catalog[item]["role"] for item in reviewers],
             "requireDistinctLeadFromWorkerSession": True,

package/runtime/python/okstra_ctl/report_contract.py

@@ -111,6 +111,7 @@ TASK_TYPE_REQUIRED_HUMAN_FIELDS = {
     ),
     "final-verification": (
         "finalVerification.validationEvidence",
+        "finalVerification.addedSurfaceAudit",
         "finalVerification.acceptanceBlockers",
         "finalVerification.residualRisk",
         "finalVerification.manualUserTest",

package/runtime/python/okstra_ctl/report_finalize.py

@@ -42,6 +42,12 @@ from .report_contract import apply_execution_roles
 from .dispatch_state import DispatchError, link_agent_dispatch_result
 from .final_report_paths import final_report_data_path, final_report_markdown_path
 from .paths import task_dir, task_manifest_file
+from .release_gate import release_handoff_allowed
+from .stage_integrate import IntegrateError
+from .stage_targets import (
+    StageTargetError,
+    integrate_and_teardown_whole_task,
+)
 from .session import observe_lead_session
 
 
@@ -51,6 +57,7 @@ STEP_TOKEN_USAGE = "token-usage"
 STEP_RENDER_VIEWS = "render-views"
 STEP_SPAWN_FOLLOWUPS = "spawn-followups"
 STEP_VALIDATE_RUN = "validate-run"
+STEP_TEARDOWN_STAGES = "teardown-stages"
 
 STEP_ORDER = (
     STEP_PROJECT_ACTIVITY,
@@ -62,6 +69,9 @@ STEP_ORDER = (
     STEP_RENDER_VIEWS,
     STEP_SPAWN_FOLLOWUPS,
     STEP_VALIDATE_RUN,
+    # Last, and only after the run validated: it removes the stage worktrees a
+    # blocked verdict would send the user straight back to.
+    STEP_TEARDOWN_STAGES,
 )
 
 
@@ -213,6 +223,7 @@ class FinalizeContext:
     task_key: str
     task_type: str
     task_group: str
+    task_id: str
     seq: str
     final_status_path: Path | None
 
@@ -241,6 +252,7 @@ class FinalizeContext:
             task_key=require_string(manifest, "taskKey"),
             task_type=require_string(manifest, "taskType"),
             task_group=task_group(manifest),
+            task_id=task_id(manifest),
             seq=report_seq(manifest),
             final_status_path=resolve_optional_path(
                 project_root, manifest.get("finalStatusPath")
@@ -327,9 +339,49 @@ def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
             ],
         ),
         (STEP_VALIDATE_RUN, _validate_run_command(ctx, markdown_path)),
+        (
+            STEP_TEARDOWN_STAGES,
+            ["<in-process>", "teardown-stages", str(ctx.data_path)],
+        ),
     ]
 
 
+def _teardown_stage_worktrees(
+    ctx: FinalizeContext,
+    command: list[str],
+) -> subprocess.CompletedProcess:
+    """판정이 릴리스로 향할 때만 stage worktree 와 registry 키를 정리한다.
+
+    whole-task 진입이 통합만 하고 정리를 남겨두므로(`stage_targets`), 정리는 판정이
+    나온 뒤인 여기서 한다. `blocked` 이거나 릴리스를 막는 조건이 남은 판정에서는
+    stage 작업물을 그대로 둬서 재작업이 바로 이어지게 한다. 이미 정리된 뒤 재실행돼도
+    같은 결과를 낸다 — 병합은 `already_merged` 로, 없는 worktree 는 건너뛴다.
+    """
+    def _done(payload: Mapping[str, Any]) -> subprocess.CompletedProcess:
+        return subprocess.CompletedProcess(command, 0, json.dumps(payload), "")
+
+    if ctx.task_type != "final-verification":
+        return _done({"skipped": "not a final-verification run"})
+    try:
+        data = json.loads(Path(ctx.data_path).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return subprocess.CompletedProcess(
+            command, 1, "", f"cannot read final-report data.json: {exc}")
+    if data.get("verificationScope") != "whole-task":
+        return _done({"skipped": "single-stage verification owns no teardown"})
+    if not release_handoff_allowed(data):
+        return _done({"skipped": "verdict does not clear the work for release"})
+    try:
+        result = integrate_and_teardown_whole_task(
+            project_root=ctx.project_root,
+            task_group=ctx.task_group,
+            task_id=ctx.task_id,
+        )
+    except (IntegrateError, StageTargetError, OSError) as exc:
+        return subprocess.CompletedProcess(command, 1, "", str(exc))
+    return _done(result)
+
+
 def _validate_run_command(ctx: FinalizeContext, markdown_path: Path) -> list[str]:
     command = [
         sys.executable,
@@ -431,6 +483,8 @@ def run_finalize(
                 )
         else:
             result = None
+        if name == STEP_TEARDOWN_STAGES:
+            result = _teardown_stage_worktrees(ctx, command)
         if name == STEP_VALIDATE_RUN:
             try:
                 _link_lead_result_for_validation(ctx)

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

@@ -109,17 +109,21 @@ def _html_path(data_path: Path) -> Path:
 
 def render_v2_html_view(
     data_path: Path,
-    markdown_path: Path,
     *,
     run_meta: HtmlRunMeta,
     templates_root: Path | None = None,
 ) -> Path:
+    """Render the human HTML from the data.json alone.
+
+    The AI-handoff markdown sibling is a second rendering of this same record,
+    never an input here: it used to be read for a `source-md-sha256` stamp that
+    no reader ever compared, which made a derived artifact a precondition for
+    another derived artifact.
+    """
     data = json.loads(data_path.read_text(encoding="utf-8"))
     errors = validate(data, load_schema_for_data(data))
     if errors:
         raise HtmlRenderError("invalid v2 final-report data: " + "; ".join(errors[:5]))
-    if not markdown_path.is_file():
-        raise HtmlRenderError(f"v2 markdown sibling not found: {markdown_path}")
     # Validate the SSOT, then localize — the sidecar carries presentation and
     # has no say in whether the report is well-formed.
     data, lang = _localize(data, data_path)
@@ -150,7 +154,6 @@ def render_v2_html_view(
         "taskType": view.task_type,
         "sourceData": source_data,
         "dataSha256": _sha256(data_path),
-        "markdownSha256": _sha256(markdown_path),
         "clarificationItems": data.get("clarificationItems", []),
         # Every task type ends with the same run-cost section, so it is bound
         # here rather than in ten view models that would each rebuild it.

package/runtime/python/okstra_ctl/report_html/view_models/final_verification.py

@@ -1,6 +1,7 @@
 """Human-first final-verification view model."""
 from __future__ import annotations
 
+from ...release_gate import release_handoff_allowed
 from ..common import evidence_index
 from ..models import HumanReportView, VisualNode
 from ..visualizations import coverage_figure
@@ -25,13 +26,15 @@ def build_final_verification_view(data: dict) -> HumanReportView:
     figure = coverage_figure(
         rows=_coverage_nodes(final), title="Requirement verification coverage"
     )
+    verdict_token = data["finalVerdict"]["verdictToken"]
     context = {
         "humanSummary": data["humanSummary"],
         "verdict": data["verdictCard"],
+        "verdictToken": verdict_token,
         "final": final,
         "narrative": final["userNarrative"],
         "coverageFigure": figure,
-        "releaseAllowed": data["verdictCard"]["verdictToken"] == "accepted",
+        "releaseAllowed": release_handoff_allowed(data),
         "evidenceIndex": evidence_index(data),
     }
     return HumanReportView(