okstra 0.176.0 → 0.177.0

package/runtime/python/okstra_ctl/stage_targets.py

@@ -767,7 +767,10 @@ def _acquire_whole_task_target(
             )
             or ""
         ),
-        teardown=True,
+        # 정리는 판정 뒤로 미룬다(Phase 7 `teardown-stages`). 되돌릴 수 없는 정리를
+        # 판정 앞에 두면, 재작업이 가장 필요한 blocked 판정에서 stage 작업물이 이미
+        # 사라져 있다. 여기서는 통합만 하고 worktree/registry 키는 남긴다.
+        teardown=False,
     )
     return FinalVerificationTargetAcquisition(
         target=whole["target"],
@@ -776,6 +779,75 @@ def _acquire_whole_task_target(
     )
 
 
+def integrate_and_teardown_whole_task(
+    *, project_root: Path, task_group: str, task_id: str,
+) -> dict[str, Any]:
+    """판정이 끝난 whole-task 검증의 stage worktree 와 registry 키를 회수한다.
+
+    진입은 통합만 하고 정리를 남겨 두므로(`_resolve_whole_task_acquisition`), 정리는
+    판정 뒤인 Phase 7 에서 여기로 들어온다. 통합은 이미 끝나 있어 Phase A 는 전부
+    `already_merged` 로 지나가고 Phase B 만 실제 일을 한다. 두 번 불려도 결과는 같다 —
+    사라진 worktree 는 건너뛰고, 미커밋 변경이 남은 stage 트리는 보존한다.
+
+    stage_map 은 done 행에서 만든다. 정리 대상은 완료된 stage 뿐이고, 계획에만 있고
+    완료되지 않은 stage 는 Phase A 가 어차피 건너뛰기 때문이다.
+    """
+    from json import loads as _loads
+
+    from okstra_project.dirs import okstra_home, project_json_path
+
+    from . import consumers, worktree_registry
+    from .locks import worktree_provision_mutex
+    from .paths import task_runs_dir
+    from .stage_integrate import integrate_stages
+
+    try:
+        project_id = _loads(
+            project_json_path(project_root).read_text(encoding="utf-8")
+        ).get("projectId", "")
+    except (OSError, ValueError):
+        project_id = ""
+    if not project_id:
+        return {"skipped": "project.json declares no projectId"}
+
+    plan_run_root = task_runs_dir(
+        project_root, task_group, task_id
+    ) / "implementation-planning"
+    done_rows = [
+        row for row in consumers.read_consumers(plan_run_root)
+        if row.get("status") == "done"
+    ]
+    if not done_rows:
+        return {"skipped": "no done stage rows to reclaim"}
+    stage_map = [
+        {"stage_number": stage}
+        for stage in sorted(consumers.latest_done_by_stage(done_rows))
+    ]
+
+    entry = worktree_registry.lookup(project_id, task_group, task_id)
+    if entry is None:
+        return {"skipped": "task worktree is no longer registered"}
+
+    with worktree_provision_mutex(okstra_home(), project_id, task_group, task_id):
+        result = integrate_stages(
+            project_id=project_id,
+            task_group=task_group,
+            task_id=task_id,
+            task_worktree_path=entry.worktree_path,
+            stage_map=stage_map,
+            done_rows=done_rows,
+            teardown=True,
+        )
+    return {
+        "tornDown": result.torn_down,
+        "teardownSkipped": [
+            {"stage": stage, "reason": reason}
+            for stage, reason in result.teardown_skipped
+        ],
+        "warnings": result.warnings,
+    }
+
+
 def acquire_final_verification_target(
     request: FinalVerificationTargetRequest,
 ) -> FinalVerificationTargetAcquisition:

package/runtime/python/okstra_ctl/wizard.py

@@ -1406,26 +1406,35 @@ def _role_add_prompt(
     state: WizardState,
     requirement: RoleRequirement,
 ) -> Prompt:
-    """min=0 선택 역할: 기본은 추가 안 함, 추가 시 1..max 수량을 이 스텝에서 고른다."""
+    """min=0 선택 역할: 프로필의 적정 수량이 기본이고, 1..max 를 이 스텝에서 고른다.
+
+    적정이 0 이면 기본은 추가 안 함이다. 0 보다 큰 적정을 선언한 역할만 기본이 열린
+    상태로 뜬다 — 어느 쪽이든 사용자는 이 화면에서 바꿀 수 있다.
+    """
     prompt = _p(
         state.workspace_root,
         "role_add",
         role=requirement.role,
         maximum=str(requirement.max_count),
     )
+    suffix = prompt["options"].get("default_suffix", "")
+
+    def _default_suffix(count: int) -> str:
+        return suffix if count == requirement.recommended_count else ""
+
     options = [
         _opt(
             "0",
-            prompt["options"]["skip"].format(
-                default_suffix=prompt["options"].get("default_suffix", ""),
-            ),
+            prompt["options"]["skip"].format(default_suffix=_default_suffix(0)),
         ),
     ]
     for count in range(1, requirement.max_count + 1):
         options.append(
             _opt(
                 str(count),
-                prompt["options"]["add"].format(count=count),
+                prompt["options"]["add"].format(
+                    count=count, default_suffix=_default_suffix(count),
+                ),
             )
         )
     return Prompt(
@@ -3865,10 +3874,10 @@ def _handoff_eligibility(state: WizardState) -> list:
     return compute_eligibility(stage_map, rows)
 
 
-def _latest_whole_task_fv_accepted(state: WizardState) -> str:
+def _latest_whole_task_fv_release_ready(state: WizardState) -> str:
     """accepted whole-task final-verification 보고서 경로 — handoff 모듈 SSOT 위임."""
-    from okstra_ctl.handoff import latest_whole_task_fv_accepted
-    return latest_whole_task_fv_accepted(
+    from okstra_ctl.handoff import latest_whole_task_fv_release_ready
+    return latest_whole_task_fv_release_ready(
         state.project_root, state.project_id, state.task_group, state.task_id)
 
 
@@ -3876,7 +3885,7 @@ def _build_handoff_stage_pick(state: WizardState) -> Prompt:
     elig = _handoff_eligibility(state)
     eligible = [e for e in elig if e["eligible"]]
     blocked = [e for e in elig if not e["eligible"]]
-    whole_task_report = _latest_whole_task_fv_accepted(state)
+    whole_task_report = _latest_whole_task_fv_release_ready(state)
     msgs = _handoff_msgs(state)
     blocked_summary = ("; ".join(
         f"stage {e['stage']} ({', '.join(e['reasons'])})" for e in blocked)
@@ -3908,7 +3917,7 @@ def _submit_handoff_stage_pick(state: WizardState, value: str) -> Optional[str]:
     if WHOLE_TASK_STAGE in picks:
         if len(picks) > 1:
             raise WizardError(t["errors"]["whole_task_exclusive"])
-        if not _latest_whole_task_fv_accepted(state):
+        if not _latest_whole_task_fv_release_ready(state):
             raise WizardError(t["errors"]["whole_task_missing"])
         state.handoff_mode = "whole-task"
         state.handoff_stages = ""

package/runtime/python/okstra_ctl/worker_liveness.py

@@ -37,6 +37,8 @@ from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
 
+from .wrapper_status import log_path_for_prompt
+
 from okstra_ctl.dispatch_state import (
     DispatchError,
     LIVENESS_AUDIT_HEARTBEAT,
@@ -69,7 +71,7 @@ def _utc_now() -> datetime:
 
 def _log_path(prompt: Path) -> Path:
     """The wrapper's live log, named as okstra-*-exec.sh names it."""
-    return prompt.with_suffix(".log") if prompt.suffix == ".md" else Path(f"{prompt}.log")
+    return log_path_for_prompt(prompt)
 
 
 def probe_heartbeat(

package/runtime/python/okstra_ctl/wrapper_status.py

@@ -25,6 +25,21 @@ def status_path_for_prompt(prompt_path: Path) -> Path:
     return prompt_path.with_suffix(prompt_path.suffix + ".status.json")
 
 
+def log_path_for_prompt(prompt_path: Path) -> Path:
+    """Where the wrapper writes its live log for this prompt.
+
+    A `.md` prompt drops that suffix rather than stacking on it, so the log of
+    `…-009.md` is `…-009.log` and not `…-009.md.log`. Both spellings existed:
+    the entrypoint wrote the first while the dispatcher listed the second among
+    the write policy's allowed artifacts, so every CLI worker's own log read as
+    an unauthorized change to the artifact root. One function now, because the
+    disagreement stays invisible until an audit compares the two.
+    """
+    if prompt_path.name.endswith(".md"):
+        return prompt_path.with_name(f"{prompt_path.name[:-3]}.log")
+    return Path(f"{prompt_path}.log")
+
+
 def read_wrapper_status(path: Path) -> WrapperStatus | None:
     try:
         raw = json.loads(path.read_text(encoding="utf-8"))

package/runtime/schemas/final-report-v2.0.schema.json

@@ -230,10 +230,9 @@
     },
     "verdictCard": {
       "type": "object",
-      "description": "Top-of-report at-a-glance card. Values MUST byte-match finalVerdict and recommendedNextSteps[0]; renderer fills both from this data structure so divergence is impossible.",
+      "description": "Top-of-report at-a-glance card. It carries no verdict token — the token lives once, in finalVerdict. `direction` and `nextStep` MUST byte-match finalVerdict and recommendedNextSteps[0].",
       "required": [
         "finalConclusion",
-        "verdictToken",
         "direction",
         "approvalRequired",
         "nextStep"
@@ -245,9 +244,6 @@
           "minLength": 1,
           "description": "Conclusion SSOT for the whole report: at most 3 sentences. Other prose blocks reference this instead of restating it."
         },
-        "verdictToken": {
-          "$ref": "#/$defs/VerdictToken"
-        },
         "direction": {
           "$ref": "#/$defs/Direction"
         },
@@ -1406,6 +1402,7 @@
       "description": "RENDER_IF taskType == final-verification. §5.8 deliverables.",
       "required": [
         "sourceImplementationReport",
+        "addedSurfaceAudit",
         "acceptanceBlockers",
         "residualRisk",
         "validationEvidence",
@@ -1475,6 +1472,13 @@
             }
           }
         },
+        "addedSurfaceAudit": {
+          "type": "array",
+          "description": "Over-delivery axis. One row per identifier / module / configuration entry the merged diff ADDS, each traced to the brief requirement it serves. An empty array states the diff added no such surface; it is not a licence to skip the enumeration.",
+          "items": {
+            "$ref": "#/$defs/AddedSurfaceRow"
+          }
+        },
         "acceptanceBlockers": {
           "type": "array",
           "items": {
@@ -2049,17 +2053,6 @@
       },
       "then": {
         "properties": {
-          "verdictCard": {
-            "properties": {
-              "verdictToken": {
-                "enum": [
-                  "analysis-complete",
-                  "analysis-partial",
-                  "blocked"
-                ]
-              }
-            }
-          },
           "finalVerdict": {
             "not": {
               "required": [
@@ -9576,6 +9569,51 @@
         }
       }
     },
+    "AddedSurfaceRow": {
+      "type": "object",
+      "description": "One surface the merged diff added, and what requirement it serves.",
+      "required": [
+        "id",
+        "surface",
+        "callers",
+        "requirement",
+        "disposition",
+        "note"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^AS-\\d{3,}$"
+        },
+        "surface": {
+          "type": "string",
+          "minLength": 1,
+          "description": "path:line plus the added identifier / module / configuration key."
+        },
+        "callers": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The caller found by searching the whole repository, or `none`. A declaration, its own test, or a commented-out line is not a caller."
+        },
+        "requirement": {
+          "type": "string",
+          "description": "The brief requirement this surface serves. Empty unless disposition is `traced`."
+        },
+        "disposition": {
+          "enum": [
+            "traced",
+            "exempt",
+            "over-delivery"
+          ]
+        },
+        "note": {
+          "type": "string",
+          "minLength": 1,
+          "description": "`traced`: how the surface serves the requirement. `exempt`: which exit applies and its cited evidence. `over-delivery`: the `AB-NNN` or `CA-NNN` row this became."
+        }
+      }
+    },
     "AcceptanceBlockerRow": {
       "type": "object",
       "required": [
@@ -9594,8 +9632,7 @@
         "severity": {
           "enum": [
             "critical",
-            "major",
-            "minor"
+            "major"
           ]
         },
         "statement": {

package/runtime/templates/reports/html/i18n/en.json

@@ -239,6 +239,10 @@
     "final-verification": {
       "verification-verdict": "Verification verdict",
       "result-per-requirement": "Result per requirement",
+      "what-the-change-added": "What the change added",
+      "traced-to": "Serves",
+      "callers": "Callers",
+      "the-change-added-no-new-surface": "The change added no new identifier, module, or configuration entry.",
       "what-blocks-acceptance": "What blocks acceptance",
       "nothing-is-holding-acceptance": "Nothing is holding acceptance.",
       "residual-risk": "Residual risk",

package/runtime/templates/reports/html/i18n/ko.json

@@ -239,6 +239,10 @@
     "final-verification": {
       "verification-verdict": "검증 판정",
       "result-per-requirement": "요구사항별 결과",
+      "what-the-change-added": "이 변경이 추가한 것",
+      "traced-to": "봉사하는 요구사항",
+      "callers": "호출자",
+      "the-change-added-no-new-surface": "이 변경이 새로 추가한 식별자·모듈·설정 항목은 없습니다.",
       "what-blocks-acceptance": "수용을 막는 것",
       "nothing-is-holding-acceptance": "수용을 막는 것이 없습니다.",
       "residual-risk": "남은 위험",

package/runtime/templates/reports/html/tasks/final-verification.template.html

@@ -5,7 +5,7 @@
 {% block human_content %}
 <section data-report-section="verification-verdict">
   <h2>{{ t('tasks.final-verification.verification-verdict') }}</h2>
-  <p><span class="status status-{{ verdict.verdictToken }}">{{ verdict.verdictToken }}</span></p>
+  <p><span class="status status-{{ verdictToken }}">{{ verdictToken }}</span></p>
   {{ render_narrative(narrative.verdictExplanation, "finalVerification.userNarrative.verdictExplanation") }}
 </section>
 
@@ -15,6 +15,12 @@
   {{ figure(coverageFigure, anchor_nodes=true) }}
 </section>
 
+<section data-report-section="added-surface" data-report-field="finalVerification.addedSurfaceAudit">
+  <h2>{{ t('tasks.final-verification.what-the-change-added') }}</h2>
+  <div class="table-scroll"><table><thead><tr><th>ID</th><th>{{ t('tasks.final-verification.what-the-change-added') }}</th><th>{{ t('tasks.final-verification.callers') }}</th><th>{{ t('tasks.final-verification.traced-to') }}</th><th>{{ t('tasks.final-verification.result-per-requirement') }}</th></tr></thead>
+  <tbody>{% for row in final.addedSurfaceAudit %}<tr id="id-{{ row.id }}"><td>{{ row.id }}</td><td>{{ row.surface | inline_code }}</td><td>{{ row.callers | inline_code }}</td><td>{{ row.requirement | inline_code }}</td><td><span class="status status-{{ row.disposition }}">{{ row.disposition }}</span> {{ row.note | inline_code }}</td></tr>{% else %}<tr><td colspan="5">{{ t('tasks.final-verification.the-change-added-no-new-surface') }}</td></tr>{% endfor %}</tbody></table></div>
+</section>
+
 <section data-report-section="blockers" data-report-field="finalVerification.acceptanceBlockers">
   <h2>{{ t('tasks.final-verification.what-blocks-acceptance') }}</h2>
   {{ render_narrative(narrative.blockerExplanation, "finalVerification.userNarrative.blockerExplanation") }}

package/runtime/validators/validate-run.py

@@ -53,6 +53,11 @@ from okstra_ctl.conformance import (  # noqa: E402
 )
 from okstra_ctl.paths import RunRef  # noqa: E402
 from okstra_ctl.report_contract import CURRENT_REPORT_SCHEMA_VERSION  # noqa: E402
+from okstra_ctl.release_gate import (  # noqa: E402
+    RELEASE_HANDOFF_TARGETS,
+    blocking_condition_ids,
+    release_handoff_allowed,
+)
 from okstra_ctl.domain.host import HostNotRegistered  # noqa: E402
 from okstra_ctl.registry.host_registry import default_host_registry  # noqa: E402
 from okstra_ctl.build_tools import (  # noqa: E402
@@ -6247,7 +6252,7 @@ def _validate_verified_row_recorded(
     report_path: Path,
     failures: list[str],
 ) -> None:
-    """An accepted single-stage verification must leave its `verified` row.
+    """A release-ready single-stage verification must leave its `verified` row.
 
     `okstra handoff record-verified` validates its own inputs, but nothing
     checked that it ever ran. Skipping it leaves the report saying `accepted`
@@ -6258,8 +6263,7 @@ def _validate_verified_row_recorded(
     """
     if str(data.get("verificationScope") or "") != "single-stage":
         return
-    token = str((data.get("finalVerdict") or {}).get("verdictToken") or "").strip()
-    if token.lower() != "accepted":
+    if not release_handoff_allowed(data):
         return
     stages = {
         row.get("stage")
@@ -6279,7 +6283,7 @@ def _validate_verified_row_recorded(
     missing = sorted(s for s in stages if s not in verified)
     if missing:
         failures.append(
-            f"final-verification accepted stage(s) {missing} but "
+            f"final-verification cleared stage(s) {missing} for release but "
             "`runs/implementation-planning/consumers.jsonl` carries no "
             "`verified` row for them. Run `okstra handoff record-verified` "
             "before finishing — without that row the report says accepted "
@@ -6308,11 +6312,11 @@ def _validate_verifier_fail_blocks_verdict(data: dict, failures: list[str]) -> N
     })
     if not failed:
         return
-    token = str((data.get("verdictCard") or {}).get("verdictToken") or "").strip()
+    token = str((data.get("finalVerdict") or {}).get("verdictToken") or "").strip()
     if token in _PASSING_VERDICT_TOKENS:
         failures.append(
             f"final-report data.json: verifier(s) {failed} recorded "
-            f"`verdict: FAIL` but `verdictCard.verdictToken` is `{token}`. A "
+            f"`verdict: FAIL` but `finalVerdict.verdictToken` is `{token}`. A "
             "verifier rejection MUST survive into the published verdict — "
             "dropping it during synthesis is how rejected work reaches "
             "`release-handoff`. Either carry the FAIL into a blocking verdict "
@@ -7914,6 +7918,82 @@ def _validate_stage_has_requirement(data: dict, failures: list[str]) -> None:
         )
 
 
+_ADDED_SURFACE_NO_CALLER_RE = re.compile(r"^\s*none\b", re.IGNORECASE)
+
+
+def _validate_added_surface_audit(data: dict, failures: list[str]) -> None:
+    """Every surface the diff added is traced to a requirement, exempted, or paid for.
+
+    The coverage table proves each requirement reached the diff. Nothing proved
+    the reverse — that each thing the diff added answers a requirement — so work
+    nobody asked for passed every gate. This check reads the reverse table and
+    refuses a row that calls itself over-delivery without the blocker or
+    condition it became: a caller-less surface is an acceptance blocker, and a
+    surface with callers but no requirement is a conditional-acceptance
+    condition (ADR-0009 grades the two differently on purpose).
+    """
+    fv = data.get("finalVerification")
+    if not isinstance(fv, Mapping):
+        return
+    rows = fv.get("addedSurfaceAudit")
+    if not isinstance(rows, list):
+        return
+    blocker_ids = {
+        str(row.get("id"))
+        for row in (fv.get("acceptanceBlockers") or [])
+        if isinstance(row, Mapping)
+    }
+    condition_ids = {
+        str(row.get("id"))
+        for row in ((data.get("finalVerdict") or {}).get(
+            "conditionalAcceptanceConditions") or [])
+        if isinstance(row, Mapping)
+    }
+    for row in rows:
+        if not isinstance(row, Mapping):
+            continue
+        row_id = str(row.get("id") or "<id 없음>")
+        disposition = str(row.get("disposition") or "")
+        note = str(row.get("note") or "")
+        if disposition == "traced" and not str(row.get("requirement") or "").strip():
+            failures.append(
+                f"final-verification: addedSurfaceAudit {row_id} is `traced` but "
+                "names no requirement — a surface is traced to something the "
+                "brief asked for, or it is not traced."
+            )
+            continue
+        if disposition != "over-delivery":
+            continue
+        caller_less = bool(
+            _ADDED_SURFACE_NO_CALLER_RE.match(str(row.get("callers") or ""))
+        )
+        expected, known = (
+            ("AB", blocker_ids) if caller_less else ("CA", condition_ids)
+        )
+        cited = set(re.findall(rf"\b{expected}-\d{{3,}}\b", note))
+        if not cited:
+            failures.append(
+                f"final-verification: addedSurfaceAudit {row_id} is "
+                f"`over-delivery` with callers "
+                f"{'none' if caller_less else 'recorded'}, so its note MUST cite "
+                f"the `{expected}-NNN` row it became — "
+                + (
+                    "a caller-less surface is an acceptance blocker"
+                    if caller_less
+                    else "a surface with callers but no requirement is a "
+                         "conditional-acceptance condition"
+                )
+                + "."
+            )
+            continue
+        missing = sorted(cited - known)
+        if missing:
+            failures.append(
+                f"final-verification: addedSurfaceAudit {row_id} cites "
+                f"{missing}, which the report does not carry."
+            )
+
+
 def _validate_final_verification_consistency(data: dict, failures: list[str]) -> None:
     """Enforce verdict ↔ blocker/condition/routing consistency on the
     final-verification data.json (SSOT). The schema guarantees field SHAPE;
@@ -7923,6 +8003,7 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
     """
     if (data.get("header") or {}).get("taskType") != "final-verification":
         return
+    _validate_added_surface_audit(data, failures)
     verdict = data.get("finalVerdict") or {}
     token = (verdict.get("verdictToken") or "").strip().lower()
     fv = data.get("finalVerification") or {}
@@ -7954,14 +8035,19 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
             "final-verification: verdict `conditional-accept` but "
             "conditionalAcceptanceConditions is empty — list every condition."
         )
-    if (
-        routing_token in {"release-handoff", "release-handoff(stage-group)"}
-        and token != "accepted"
-    ):
+    if routing_token in RELEASE_HANDOFF_TARGETS and not release_handoff_allowed(data):
+        blocking = blocking_condition_ids(data)
+        reason = (
+            f"condition(s) {blocking} declare `blocksReleaseHandoff: true` "
+            "(a condition with no declaration counts as blocking)"
+            if blocking
+            else f"verdict is `{token}`"
+        )
         failures.append(
             f"final-verification: routingRecommendation cites `release-handoff` "
-            f"but verdict is `{token}` — release-handoff routing is allowed only "
-            "when the verdict is `accepted`."
+            f"but {reason} — release-handoff routing needs an `accepted` verdict, "
+            "or a `conditional-accept` whose every condition declares "
+            "`blocksReleaseHandoff: false`."
         )
 
     scope = data.get("verificationScope", "whole-task")

package/runtime/validators/validate_analysis_report.py

@@ -422,11 +422,8 @@ def _validate_analysis_verdict(
     expected = "blocked" if worker_blocked or scope_blocked else (
         "analysis-partial" if partial else "analysis-complete"
     )
-    actual = {
-        str((data.get("verdictCard") or {}).get("verdictToken") or ""),
-        str((data.get("finalVerdict") or {}).get("verdictToken") or ""),
-    }
-    if actual == {expected}:
+    actual = str((data.get("finalVerdict") or {}).get("verdictToken") or "")
+    if actual == expected:
         return
     reasons = []
     if worker_blocked: