okstra 0.176.0 → 0.177.0

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -107,7 +107,11 @@ from .worker_prompt_headers import (
     resolve_errors_log_path,
 )
 from .worker_artifact_paths import audit_sidecar_rel
-from .wrapper_status import read_wrapper_status, status_path_for_prompt
+from .wrapper_status import (
+    log_path_for_prompt,
+    read_wrapper_status,
+    status_path_for_prompt,
+)
 from .worker_request import verifier_extra_dirs
 from .write_policy import (
     WriteEnforcement,
@@ -394,11 +398,38 @@ def dispatch_plan(plan: DispatchPlan, *, wait: bool = True) -> int:
             if result != 0:
                 return result
         return 0
-    handles = [_spawn_job(plan, job, 1) for job in plan.jobs]
+    round_artifact_paths = _round_artifact_paths(plan)
+    handles = [
+        _spawn_job(plan, job, 1, batch_artifact_paths=round_artifact_paths)
+        for job in plan.jobs
+    ]
     _record_dispatch_facts(plan.team_state_path, _mode_from_handles(handles))
     return 0
 
 
+def _round_artifact_paths(plan: DispatchPlan) -> tuple[Path, ...]:
+    """Every artifact this round's workers are entitled to write.
+
+    These jobs run concurrently into one shared artifact root, so each worker's
+    own result, audit sidecar, status sidecar and live log land inside every
+    sibling's audit window. Judged against one worker's policy alone, the
+    siblings' writes read as unauthorized artifact-root changes and failed a
+    whole round of otherwise clean verifiers.
+
+    They travel as orchestrator paths rather than as a widened policy union
+    because the snapshot carries orchestrator paths and the audit excuses them
+    without consulting a policy — while `_validate_snapshot_authority` compares
+    the recorded policy digests exactly, so a snapshot taken under a union can
+    no longer be closed by the per-job policy the awaiting process rebuilds.
+    Same effect on the verdict; no coupling between two processes' plans.
+    """
+    return tuple(
+        path
+        for job in plan.jobs
+        for path in _worker_artifact_paths(plan, job)
+    )
+
+
 def dispatch_cli_wrapper_plan(plan: DispatchPlan) -> int:
     """Start one dependency-free CLI batch before collecting any worker."""
     if any(job.backend != BACKEND_CLI_WRAPPER for job in plan.jobs):
@@ -1263,7 +1294,13 @@ def _jobs_from_file(
     )
 
 
-def _spawn_job(plan: DispatchPlan, job: WorkerJob, attempt: int) -> WorkerHandle:
+def _spawn_job(
+    plan: DispatchPlan,
+    job: WorkerJob,
+    attempt: int,
+    *,
+    batch_artifact_paths: Sequence[Path] = (),
+) -> WorkerHandle:
     job = _prepare_job_attempt(plan, job, attempt)
     contract = _persisted_write_contract(plan, job)
     policies = (contract[0],) if contract else ()
@@ -1275,7 +1312,12 @@ def _spawn_job(plan: DispatchPlan, job: WorkerJob, attempt: int) -> WorkerHandle
                 _load_json_object(snapshot_path, "mutation audit snapshot")
             )
         else:
-            snapshot = _mutation_snapshot(plan, policies, (job,))
+            snapshot = _mutation_snapshot(
+                plan,
+                policies,
+                (job,),
+                round_artifact_paths=batch_artifact_paths,
+            )
     handle = replace(
         _start_job(plan, job),
         mutation_snapshot=snapshot,
@@ -1373,11 +1415,13 @@ def _mutation_snapshot(
     plan: DispatchPlan,
     policies: Sequence[WritePolicy],
     jobs: Sequence[WorkerJob],
+    round_artifact_paths: Sequence[Path] = (),
 ) -> MutationSnapshot:
     sidecars = tuple(_mutation_snapshot_path(job) for job in jobs)
     snapshot = ExecutionMutationAudit().snapshot(
         policies,
         orchestrator_paths=(
+            *round_artifact_paths,
             plan.manifest_path,
             plan.team_state_path,
             Path(f"{plan.team_state_path}.lock"),
@@ -1478,7 +1522,7 @@ def _worker_artifact_paths(plan: DispatchPlan, job: WorkerJob) -> tuple[Path, ..
         *job.completion_paths,
         Path(audit_sidecar_rel(str(job.worker_result_path))),
         status_path_for_prompt(job.prompt_path),
-        job.prompt_path.with_suffix(job.prompt_path.suffix + ".log"),
+        log_path_for_prompt(job.prompt_path),
     }
     error_logs = active_context.get("errorLogs")
     if isinstance(error_logs, Mapping):
@@ -2171,7 +2215,7 @@ def _wrapper_log_tail(job: WorkerJob) -> str | None:
     some process exited 1. Capped well under the writer's own excerpt limit
     because a whole record must stay inside one atomic `PIPE_BUF` append.
     """
-    log_path = job.prompt_path.with_suffix(job.prompt_path.suffix + ".log")
+    log_path = log_path_for_prompt(job.prompt_path)
     try:
         with log_path.open("rb") as handle:
             handle.seek(0, 2)

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -57,7 +57,7 @@ from .worker_prompt_contract import (
 from .worker_runner import LIVE, QUIET
 from .worker_request import verifier_extra_dirs
 from .worker_artifact_paths import audit_sidecar_rel
-from .wrapper_status import status_path_for_prompt
+from .wrapper_status import log_path_for_prompt, status_path_for_prompt
 from .write_policy import (
     build_invocation_write_contract,
     planned_paths_from_run_manifest,
@@ -176,7 +176,7 @@ class WorkerJob:
             self.model_execution_value,
             str(self.prompt_path),
             self.worktree_path,
-            self.role,
+            self.wrapper_role,
             str(self.idle_timeout_seconds),
             "--presentation",
             self._presentation(),
@@ -190,6 +190,30 @@ class WorkerJob:
             argv += ["--session-id", self.session_id]
         return argv
 
+    @property
+    def wrapper_role(self) -> str:
+        """The canonical role the entrypoint's role positional is read as.
+
+        `self.role` is the roster label team-state carries (`Antigravity
+        worker`) so the report's execution-status row can quote it. The
+        entrypoint reads that same position through `normalize_role`, which
+        knows only the eleven canonical ids, and compares it against
+        `role_for_duty(dutyId)` from the invocation metadata. Handing it the
+        label failed that check before the status sidecar was written, so a
+        pane worker exited 64 leaving no `.log` and no `.status.json` while
+        team-state still read `in-progress`. It also silently denied the
+        verifier the toolchain dirs `verifier_extra_dirs` grants by role.
+
+        A legacy v1 job carries no duty id; the entrypoint skips the metadata
+        role check for it, so its existing value is preserved.
+        """
+        if not self.duty_id:
+            return self.role
+        try:
+            return role_for_duty(self.duty_id)
+        except RoleCatalogError:
+            return self.role
+
     def _presentation(self) -> str:
         # A pane is a screen a person watches; a cli-wrapper dispatch's stdout is
         # a subagent's context window. Progress belongs in the first and not the
@@ -790,7 +814,7 @@ def _manifest_worker_write_paths(
         result,
         Path(audit_sidecar_rel(str(result))),
         status_path_for_prompt(prompt_path),
-        prompt_path.with_suffix(prompt_path.suffix + ".log"),
+        log_path_for_prompt(prompt_path),
     }
     active_value = authority.get("activeRunContextPath")
     active = (
@@ -847,7 +871,7 @@ def _prompt_write_paths(
         _project_or_absolute(project_root, value) for value in artifact_values
     }
     artifacts.add(status_path_for_prompt(prompt_path))
-    artifacts.add(prompt_path.with_suffix(prompt_path.suffix + ".log"))
+    artifacts.add(log_path_for_prompt(prompt_path))
     worktree_value = values.get("Worktree")
     worktree = (
         _project_or_absolute(project_root, worktree_value)

package/runtime/python/okstra_ctl/execution_mutation_audit.py

@@ -171,7 +171,10 @@ class ExecutionMutationAudit:
             before.scratch_digests, after.scratch_digests
         )
         source_changes = _source_changes(changed, rows, before)
-        git_changed = before.git_projection != after.git_projection
+        # Reported and, through `_retry_allowed`, load-bearing: a stat-cache
+        # refresh must not read as "this worker touched Git" and must not
+        # withhold the retry a worker that failed for another reason is owed.
+        git_changed = _stable_git_projection(before) != _stable_git_projection(after)
         violations = _policy_violations(
             before,
             after,
@@ -250,6 +253,22 @@ def _maximum_precision(policy: WritePolicy) -> str:
     return policy.maximum_boundary_precision
 
 
+_INSTALLED_DEPENDENCY_DIRS = frozenset({"node_modules"})
+"""Trees a package manager installs, which no worker authored and no policy can
+enumerate.
+
+Excluded for the same reason `.git` is: the audit asks whether the worker
+changed *source*, and these hold neither source nor run artifacts. What forced
+the entry is that the tools inside them write to themselves — a `final-verification`
+verifier running the Tier 1 / Tier 2 suites its own profile mandates had Vitest
+persist `node_modules/.vite/vitest/<hash>/results.json`, and that single cache
+file failed both acceptance verifiers of an otherwise clean stage.
+
+One ecosystem, because one is what has been observed. A second name belongs here
+when a run produces the same evidence for it, not before.
+"""
+
+
 def _content_snapshot(root: Path, generated: frozenset[str]) -> dict[str, str]:
     rows: dict[str, str] = {}
     for current, directories, filenames in os.walk(root, followlinks=False):
@@ -258,7 +277,11 @@ def _content_snapshot(root: Path, generated: frozenset[str]) -> dict[str, str]:
         for name in sorted(directories):
             path = current_path / name
             relative_path = path.relative_to(root)
-            if name == ".git" or _excluded(relative_path, generated):
+            if (
+                name == ".git"
+                or name in _INSTALLED_DEPENDENCY_DIRS
+                or _excluded(relative_path, generated)
+            ):
                 continue
             if path.is_symlink():
                 rows[relative_path.as_posix()] = _path_digest(path)
@@ -473,7 +496,7 @@ def _policy_violations(
 ) -> list[str]:
     if all(policy.source_mode == "source-readonly" for policy in policies):
         failures = ["readonly source changed"] if source_changes else []
-        if before.git_projection != after.git_projection:
+        if _stable_git_projection(before) != _stable_git_projection(after):
             failures.append("gitPolicy disabled but Git projection changed")
         return failures
     policy = next(row for row in policies if row.source_mode == "project-mutation")
@@ -482,6 +505,29 @@ def _policy_violations(
     return failures
 
 
+def _stable_git_projection(snapshot: MutationSnapshot) -> dict[str, Any]:
+    """The projection minus the one field a read-only reader moves on its own.
+
+    `indexDigest` is Git's stat cache, and Git rewrites it whenever a plain
+    read refreshes a stale entry — `git status --short`, which the
+    `final-verification` profile requires of every verifier, is enough. Nothing
+    about the worktree's content changed when it moves, so comparing it made a
+    read-only worker fail for doing what its own phase told it to do (observed:
+    both stage-1 acceptance verifiers, where `indexDigest` was the only key that
+    differed and `stagedPaths` was empty on both sides).
+
+    Every field that does witness a mutation stays compared: `head` and
+    `branchCommit` for a moved ref, `stagedPaths` for content added to the
+    index, `worktreeRegistration` for a re-registered worktree, `reflogDigest`
+    for a ref rewrite, and both Git directories for a redirected repository.
+    """
+    return {
+        key: value
+        for key, value in snapshot.git_projection.items()
+        if key != "indexDigest"
+    }
+
+
 def _source_policy_failures(
     policy: WritePolicy,
     changed: set[str],

package/runtime/python/okstra_ctl/handoff.py

@@ -15,6 +15,11 @@ from typing import Any, Callable, Dict, List, Optional, Tuple
 from . import consumers, stage_targets, worktree_registry
 from .final_report_paths import final_report_markdown_path
 from .paths import RunRef
+from .release_gate import (
+    blocking_condition_ids,
+    release_handoff_allowed,
+    verdict_token,
+)
 from .stage_map import StageMapError, parse_stage_map_file, stage_map_records
 from .worktree import (compute_branch_name, compute_worktree_path,
                        main_worktree_path, is_dirty_excluding_okstra,
@@ -52,12 +57,14 @@ def compute_eligibility(stage_map: List[Dict[str, Any]],
     ).handoff_eligibility()
 
 
-def latest_whole_task_fv_accepted(project_root, project_id: str,
-                                  task_group: str, task_id: str) -> str:
-    """accepted whole-task final-verification 보고서 경로. 없으면 ''.
+def latest_whole_task_fv_release_ready(project_root, project_id: str,
+                                       task_group: str, task_id: str) -> str:
+    """release-handoff 로 넘어가도 되는 whole-task 검증 보고서 경로. 없으면 ''.
 
     판정의 SSOT 는 final-report 의 data.json 이다 (record_verified 와 동일
-    필드: header.taskType / verificationScope / finalVerdict.verdictToken).
+    필드: header.taskType / verificationScope / finalVerdict). 통과 조건은
+    `release_gate.release_handoff_allowed` 한 곳이 소유한다 — `accepted`,
+    또는 모든 조건이 릴리스를 막지 않는다고 선언한 `conditional-accept`.
     whole-task run 산출물만 평면 reports/ 에 남으므로 stage-* 는 걸리지 않는다."""
     from okstra_project.state import find_task_root
     root = find_task_root(Path(project_root),
@@ -71,11 +78,9 @@ def latest_whole_task_fv_accepted(project_root, project_id: str,
             data = json.loads(dj.read_text(encoding="utf-8"))
         except (OSError, json.JSONDecodeError):
             continue
-        token = ((data.get("finalVerdict") or {}).get("verdictToken")
-                 or "").strip().lower()
         if ((data.get("header") or {}).get("taskType") == "final-verification"
                 and data.get("verificationScope") == "whole-task"
-                and token == "accepted"):
+                and release_handoff_allowed(data)):
             md = final_report_markdown_path(dj)
             return str(md if md.is_file() else dj)
     return ""
@@ -363,8 +368,10 @@ def _impl_task_key_for_any(rows: List[Dict[str, Any]], stages: List[int]) -> str
 
 def record_verified(*, plan_run_root, stage: int, report_path: str,
                     data_json) -> Dict[str, Any]:
-    """단독-stage accepted 만 기록. data.json 의 taskType/scope/verdict 를 검증해
-    lead 가 임의 보고서를 verified 로 올리는 것을 막는다."""
+    """릴리스로 넘어갈 수 있는 단독-stage 판정만 기록. data.json 의
+    taskType/scope/verdict 를 검증해 lead 가 임의 보고서를 verified 로 올리는 것을
+    막는다. 통과 조건은 whole-task 와 같고(`release_gate`), 기록되는 verdict 는
+    보고서가 실제로 실은 토큰이다."""
     try:
         data = json.loads(Path(data_json).read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError) as exc:
@@ -376,14 +383,20 @@ def record_verified(*, plan_run_root, stage: int, report_path: str,
         raise HandoffError(
             f"record-verified requires verificationScope single-stage, "
             f"got {scope!r}")
-    token = ((data.get("finalVerdict") or {}).get("verdictToken")
-             or "").strip().lower()
-    if token != "accepted":
-        raise HandoffError(f"verdict token must be `accepted`, got {token!r}")
+    token = verdict_token(data)
+    if not release_handoff_allowed(data):
+        blocking = blocking_condition_ids(data)
+        detail = (
+            f"condition(s) {blocking} declare `blocksReleaseHandoff: true`"
+            if blocking else f"got {token!r}"
+        )
+        raise HandoffError(
+            "verdict must be `accepted`, or `conditional-accept` whose every "
+            f"condition declares `blocksReleaseHandoff: false` — {detail}")
     rows = consumers.read_consumers(Path(plan_run_root))
     key = _impl_task_key_for(rows, stage)
     consumers.append_verified(Path(plan_run_root), impl_task_key=key,
-                              stage=stage, verdict="accepted",
+                              stage=stage, verdict=token,
                               report_path=report_path)
     return {"ok": True, "stage": stage, "report_path": report_path}
 

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/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/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(

package/runtime/python/okstra_ctl/run.py

@@ -1580,7 +1580,7 @@ def _materialize_release_handoff_input(
     반환: ctx 에 올릴 {"HANDOFF_MODE": ..., "HANDOFF_STAGES": ...}."""
     from .consumers import read_consumers
     from .handoff import (HandoffError, _require_eligible,
-                          latest_whole_task_fv_accepted)
+                          latest_whole_task_fv_release_ready)
     from .paths import task_dir
     from .render import render_template_with_ctx
     from .run_context import _now_task_date
@@ -1622,7 +1622,7 @@ def _materialize_release_handoff_input(
         stages_csv = ",".join(str(n) for n in nums)
         report_rows = _collect_handoff_source_report_rows(rows, nums)
     else:
-        report = latest_whole_task_fv_accepted(
+        report = latest_whole_task_fv_release_ready(
             project_root, inp.project_id, inp.task_group, inp.task_id)
         if not report:
             raise PrepareError(
@@ -1659,6 +1659,33 @@ def _materialize_release_handoff_input(
     return {"HANDOFF_MODE": mode, "HANDOFF_STAGES": stages_csv}
 
 
+QA_COMMAND_EXECUTING_TASK_TYPES = ("implementation", "final-verification")
+
+
+def validate_project_qa_commands(task_type: str, project_root: Path) -> None:
+    """`qaCommands` 를 실행하는 phase 진입에서 변경성 토큰 선언을 막는다.
+
+    `implementation` 은 verifier 의 QA gate baseline 으로, `final-verification` 은
+    프로파일이 정의한 Tier 2 재실행 집합으로 같은 선언을 읽는다. 실행 직전에 리드가
+    스스로 걸러내게 두면 그 자기검사가 유일한 방어선이 되므로 진입에서 막는다.
+    나머지 task-type 은 이 선언을 읽지 않아 잘못된 값이 있어도 동작에 닿지 않는다.
+    """
+    if task_type not in QA_COMMAND_EXECUTING_TASK_TYPES:
+        return
+    project_json = project_json_path(project_root)
+    if not project_json.is_file():
+        return
+    try:
+        project_meta = json.loads(project_json.read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        raise PrepareError(
+            f"project.json read failed at {project_json}: {exc}"
+        ) from exc
+    qa_errors = validate_qa_commands(project_meta.get("qaCommands"))
+    if qa_errors:
+        raise PrepareError(_format_qa_errors(qa_errors))
+
+
 def _apply_qa_waiver_if_requested(inp: "PrepareInputs", project_root: Path) -> None:
     """`--qa-waiver` 가 있으면 task-level 매니페스트 entry 의 waiver 를 채운다.
 
@@ -1745,21 +1772,9 @@ def _register_and_check_project(project_root: Path, inp: PrepareInputs) -> None:
         # is preserved by the `: {exc}` suffix and the `raise ... from exc`.
         raise PrepareError(f"project.json upsert failed for {project_root}: {exc}") from exc
 
-    # `qaCommands` 는 implementation phase verifier 의 QA gate baseline 으로만
-    # 쓰이므로 검증도 implementation 진입 시에만 수행한다. 다른 task-type 에서는
-    # 잘못된 선언이 있어도 동작에 영향이 없어 fail-fast 할 이유가 없다.
+    validate_project_qa_commands(inp.task_type, project_root)
+    # waiver 는 stage 단위 Tier 3 면제라 implementation 진입에서만 적용한다.
     if inp.task_type == "implementation":
-        project_json = project_json_path(project_root)
-        if project_json.is_file():
-            try:
-                project_meta = json.loads(project_json.read_text())
-            except (OSError, json.JSONDecodeError) as exc:
-                raise PrepareError(
-                    f"project.json read failed at {project_json}: {exc}"
-                ) from exc
-            qa_errors = validate_qa_commands(project_meta.get("qaCommands"))
-            if qa_errors:
-                raise PrepareError(_format_qa_errors(qa_errors))
         _apply_qa_waiver_if_requested(inp, project_root)