okstra 0.191.2 → 0.193.0

package/runtime/python/okstra_ctl/conformance.py

@@ -152,6 +152,80 @@ def malformed_conformance_stages(data: object) -> list[int]:
     return bad
 
 
+def exempt_stage_surface_conflicts(
+    data: object, patterns: object = None,
+) -> list[dict[str, object]]:
+    """`Conformance exemption:` 을 선언했는데 계획된 경로가 capability 표면을 건드리는 stage.
+
+    면제 규칙(prompts/profiles/implementation-planning.md "Per-stage conformance
+    declaration")은 "db/io/http/external 표면을 건드리지 않는 stage" 에만 허용하고,
+    구현 diff 가 그 표면을 건드리면 validate-run 의 diff-surface 대조가 막는다고
+    적는다. 그 대조는 구현이 끝난 뒤에만 돌았고, 승인된 계획은 불변이라 그때는
+    고칠 수 없었다(실측 2026-09-09, dev-10784 Stage 2: plannedPaths 에 ORM
+    repository 를 넣고 면제 선언 → 구현 완료 후 `contract-violated`). 같은 모순은
+    계획의 `stepwiseExecution[].plannedPaths` 로 승인 전에 판별된다 — 이 함수가
+    그 판별이고, 구현 게이트와 같은 `detect_surfaces` 를 쓴다.
+
+    반환 행: `{"stage": <int>, "surfaces": [..], "paths": [..]}`. `plannedPaths`
+    가 없는 step 은 `files` 문자열(쉼표 구분)을 대신 읽는다.
+    """
+    planning = data.get("implementationPlanning") if isinstance(data, dict) else None
+    stages = planning.get("stages") if isinstance(planning, dict) else None
+    conflicts: list[dict[str, object]] = []
+    for stage in stages if isinstance(stages, list) else []:
+        if not isinstance(stage, dict):
+            continue
+        exemption = stage.get("conformanceExemption")
+        if not isinstance(exemption, str) or not exemption.strip():
+            continue
+        number = stage.get("stage")
+        if not isinstance(number, int) or isinstance(number, bool) or number < 1:
+            continue
+        paths = _stage_planned_paths(stage)
+        touching = sorted(
+            path for path in paths if detect_surfaces([path], patterns)
+        )
+        surfaces = detect_surfaces(touching, patterns)
+        if surfaces:
+            conflicts.append(
+                {"stage": number, "surfaces": sorted(surfaces), "paths": touching}
+            )
+    return conflicts
+
+
+def _stage_planned_paths(stage: dict) -> list[str]:
+    """stage 의 step 들이 계획한 경로 — 경로 모양인 문자열만.
+
+    plannedPaths 에는 `(none — read-only repository command)` 같은 산문
+    자리표시자도 들어온다(실측 2026-09-09 dev-10627). 공백이 든 문자열을 표면
+    패턴에 대면 `*repository*` 가 그 산문에 걸려 거짓 양성이 된다. 실제 경로는
+    공백이 없고 `/` 나 `.` 을 품는다."""
+    paths: list[str] = []
+    for step in stage.get("stepwiseExecution") or []:
+        if not isinstance(step, dict):
+            continue
+        planned = step.get("plannedPaths")
+        candidates: list[str] = []
+        if isinstance(planned, list):
+            candidates = [p for p in planned if isinstance(p, str)]
+        elif isinstance(step.get("files"), str):
+            candidates = step["files"].split(",")
+        paths.extend(c.strip() for c in candidates if _looks_like_path(c.strip()))
+    return paths
+
+
+def _looks_like_path(value: str) -> bool:
+    if not value or any(ch.isspace() for ch in value):
+        return False
+    if value.startswith(".okstra/"):
+        # task 산출물(qa 스크립트·fixture·decision 기록)은 코드 표면이 아니다 —
+        # 구현 diff 는 워크트리에서 나오므로 그 경로는 구현 게이트에도 닿지 않는다.
+        # 실측(84개 계획 sweep): `.okstra/**` 를 세면 `*migration*` 이 decision
+        # 파일명에 걸려 거짓 양성이 14건 늘었다.
+        return False
+    return "/" in value or "." in value
+
+
 def is_advisory_conformance_entry(entry: object) -> bool:
     """Return whether one entry depends on user-owned external QA."""
     if not isinstance(entry, dict):

package/runtime/python/okstra_ctl/convergence.py

@@ -22,6 +22,11 @@ from .convergence_engine import (
     validate_final_state,
     validate_working_state,
 )
+from .convergence_reverify_prompt import (
+    ReverifyPromptError,
+    reverify_findings,
+    reverify_prompt_body,
+)
 from .convergence_critic_prompt import (
     analyser_results,
     covered_index,
@@ -285,6 +290,8 @@ _CLI_EPILOG = r"""Usage:
   okstra convergence apply-round --work-state <path> --plan <path> \
     --results <path>
   okstra convergence critic-prompt --run-manifest <path>
+  okstra convergence reverify-prompt --run-manifest <path> --plan <path> \
+    --worker <worker-id>
   okstra convergence apply-critic-gaps --work-state <path> --results <path>
   okstra convergence finalize --work-state <path> --output <path>
   okstra convergence validate --state <path> --kind <working|final>
@@ -388,6 +395,25 @@ def _parser() -> argparse.ArgumentParser:
     )
     critic_prompt.add_argument("--run-manifest", type=Path, required=True)
 
+    reverify_prompt = subparsers.add_parser(
+        "reverify-prompt",
+        help="render one worker's reverify task instructions to stdout",
+        description=(
+            "Print the reverify instruction body for one `dispatches[]` row of "
+            "a round plan. The lead writes it verbatim to the file the prompt "
+            "materializer's `--instruction` takes. It carries the round's "
+            "mandate (adversarial or collaborative, from the grouping's "
+            "config), every planned finding with its summary, origin worker, "
+            "cited-evidence line, the origin worker's result file and item id, "
+            "and the origin audit sidecar the verifier may open, plus the "
+            "response format the collector parses. Nothing here is hand-written."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    reverify_prompt.add_argument("--run-manifest", type=Path, required=True)
+    reverify_prompt.add_argument("--plan", type=Path, required=True)
+    reverify_prompt.add_argument("--worker", required=True)
+
     apply_critic = subparsers.add_parser(
         "apply-critic-gaps",
         help="apply one coverage-critic verification batch",
@@ -1403,6 +1429,39 @@ def _prepare_groups(args: argparse.Namespace) -> tuple[str, Path]:
     return "prepared", output
 
 
+def _reverify_prompt(args: argparse.Namespace) -> str:
+    """한 워커의 reverify 지시문 본문. 입력은 매니페스트·라운드 계획·워커 id."""
+    authority = validated_run_authority(args.run_manifest)
+    groups_path = authority.run_dir / "state" / _canonical_run_artifact_name(
+        "convergence-groups", authority.task_type, authority.state_sequence
+    )
+    if not groups_path.is_file():
+        raise ConvergenceContractError(
+            "the reverify prompt needs the Round 0 grouping; run "
+            f"`okstra convergence prepare-groups` first: {groups_path}"
+        )
+    groups = load_owned_json_object(groups_path)
+    plan = load_owned_json_object(args.plan)
+    config = groups.get("config") if isinstance(groups.get("config"), Mapping) else {}
+    round_number = plan.get("round")
+    if not isinstance(round_number, int) or round_number < 1:
+        raise ConvergenceContractError("round plan has no positive `round`")
+    if plan.get("action") != "dispatch":
+        raise ConvergenceContractError(
+            f"round plan action is {plan.get('action')!r}, not `dispatch`; "
+            "there is nothing to verify this round"
+        )
+    return reverify_prompt_body(
+        task_key=_manifest_authority_string(authority.payload, "taskKey"),
+        round_number=round_number,
+        adversarial=bool(config.get("adversarial", False)),
+        findings=reverify_findings(
+            groups, plan, args.worker,
+            project_root=authority.project_root, run_dir=authority.run_dir,
+        ),
+    )
+
+
 def _execute(args: argparse.Namespace) -> tuple[str, Path]:
     operations: dict[str, Any] = {
         "prepare-groups": _prepare_groups,
@@ -1433,8 +1492,11 @@ def main(argv: list[str] | None = None) -> int:
         if args.operation == "critic-prompt":
             print(_critic_prompt(args), end="")
             return 0
+        if args.operation == "reverify-prompt":
+            print(_reverify_prompt(args), end="")
+            return 0
         action, path = _execute(args)
-    except (ConvergenceContractError, VerdictBlockError,
+    except (ConvergenceContractError, VerdictBlockError, ReverifyPromptError,
             json.JSONDecodeError, ValueError) as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 2

package/runtime/python/okstra_ctl/convergence_reverify_prompt.py

@@ -0,0 +1,238 @@
+"""Reverify 지시문을 수렴 상태와 라운드 계획에서 결정적으로 렌더한다.
+
+Phase 5.5 의 재검증 워커는 리드가 손으로 쓴 지시문을 받아 왔다. 그 손에서 두
+가지가 반복해서 어긋났다(실측 2026-09-09, 다른 세션의 첫 reverify 보고).
+
+- 응답 형식 — 리드가 `- Verdict:` 불릿을 적었고 워커는 시킨 대로 썼다. 파서는
+  이제 그 모양도 읽지만(`verdict_blocks._field_match`), 형식 블록을 리드가 매
+  라운드 다시 쓰는 구조 자체가 결함이다.
+- 근거 축약 — 리드가 `**Cited evidence**` 줄에 원 워커가 인용한 근거의 일부만
+  옮겨 적었다. 검증자는 계약대로 그 줄만 열었고, `burden-not-met` 5건은 주장을
+  검증한 것이 아니라 리드의 전사(轉寫)를 검증한 것이었다.
+
+이 모듈은 그 지시문을 코드로 만든다. finding 마다 그룹의 요약·원 워커·인용
+근거 줄에 더해, **원 워커의 결과 파일과 그 안의 항목 id, 그리고 원 워커의 감사
+사이드카**(실행한 읽기 전용 명령과 출력이 기록된 파일)를 싣고, 그 둘을 열어도
+된다고 명시한다. 검증자는 리드의 요약이 아니라 원 워커가 실제로 인용한 것을
+판단한다. 응답 형식은 `verdict_blocks` 가 읽는 정본 모양 그대로다.
+
+산출물은 프롬프트 materializer 의 `--instruction` 이 받는 본문이다. `## Instructions`
+로 시작하므로 `complete_reverify_instruction` 이 모델·task type·금지 목록을 그
+앞에 붙이고, 출력 계약(`templates/reverify-output-contract.md`)을 뒤에 덧붙인다.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from .convergence_critic_prompt import analyser_results
+from .worker_artifact_paths import WorkerArtifactPathError, audit_sidecar_rel
+
+
+class ReverifyPromptError(ValueError):
+    """지시문을 결정적으로 만들 수 없다."""
+
+
+# 렌더된 지시문의 서명. 리드가 손으로 쓴 지시문은 이 줄이 없어 materialize 의
+# `validate_reverify_prompt` 에서 거절된다 — 저작(convergence.md "write its output
+# verbatim")만 있고 집행이 없으면 리드는 다시 손으로 쓴다.
+RENDERED_BY_LINE = "**Rendered by:** okstra convergence reverify-prompt"
+
+
+@dataclass(frozen=True)
+class ReverifyFinding:
+    """검증 큐의 finding 하나와, 그 원 워커의 실물 인용 위치."""
+
+    finding_id: str
+    summary: str
+    origin_worker: str
+    origin_item_id: str
+    origin_evidence: str
+    origin_result_path: str
+    origin_audit_path: str
+
+
+_ADVERSARIAL_MANDATE = """Your job is to BREAK each finding below, not to confirm it. For EACH finding,
+open the cited evidence directly and actively search for evidence that the claim
+is wrong, overstated, or unproven. Then respond with exactly one verdict:
+
+- **REFUTED**: You broke the claim. State the basis:
+  - counter-evidence — you found contradicting evidence (give file:line or log line), OR
+  - burden-not-met — you re-inspected the cited evidence and could neither confirm
+    nor refute it (the claim has not proven itself).
+- **SURVIVES**: You actively tried to refute it and failed — the claim withstood the attack.
+- **SURVIVES-WITH-CAVEAT**: It holds, but a scope limit / extra condition / missing
+  precondition exists (state it).
+- **UNVERIFIABLE**: Capability, credential, network, or service state prevents you
+  from opening or reproducing the cited evidence. Do not use REFUTED as a substitute.
+
+The burden of proof is on the claim. If after inspecting the cited evidence you remain
+uncertain, your verdict is REFUTED with basis = burden-not-met.
+
+Inspect ONLY the evidence each finding cites and its immediate surroundings. Do NOT
+re-read the task brief, instruction-set, or report template."""
+
+_COLLABORATIVE_MANDATE = """Review the following findings discovered by other workers.
+For EACH finding, respond with exactly one verdict:
+
+- **AGREE**: The finding is valid based on the evidence presented
+- **DISAGREE**: The finding is incorrect or unsupported (explain briefly why)
+- **SUPPLEMENT**: The finding is valid AND you have additional supporting evidence or context
+- **UNVERIFIABLE**: Capability, credential, network, or service state prevents you
+  from checking this finding. Explain the unavailable capability; do not substitute DISAGREE.
+
+Do NOT re-analyze the original source materials. Judge based on the evidence provided."""
+
+# 근거 접근 규칙. `**Cited evidence**` 는 리드의 요약이고, 완전한 인용은 원 워커의
+# 결과 항목이다. 검증자가 요약만 열고 "이 근거로는 입증되지 않는다" 고 답하던
+# 자리를 막는다.
+_EVIDENCE_ACCESS = """The `**Cited evidence**` line is the lead's summary of what the origin worker cited.
+The complete citation is the origin worker's own item: before judging, open the
+`**Origin item**` file at the named `### <item-id>` section and read every path, line,
+command, and quote it cites. The `**Origin audit sidecar**` records the read-only
+commands that worker ran and their output; it counts as cited evidence and you may
+open it. Judge the claim against what the origin worker actually cited, never against
+the summary line alone."""
+
+_ADVERSARIAL_RESPONSE = """### <finding-id>
+**Verdict**: REFUTED | SURVIVES | SURVIVES-WITH-CAVEAT | UNVERIFIABLE
+**Basis** (only if REFUTED): counter-evidence | burden-not-met
+**Explanation**: <2-3 sentences; for counter-evidence include the file:line you found>"""
+
+_COLLABORATIVE_RESPONSE = """### <finding-id>
+**Verdict**: AGREE | DISAGREE | SUPPLEMENT | UNVERIFIABLE
+**Explanation**: <2-3 sentences>"""
+
+
+def _nonempty_string(value: Any) -> str:
+    return value if isinstance(value, str) and value.strip() else ""
+
+
+def plan_row_for_worker(plan: Mapping[str, Any], worker_id: str) -> Mapping[str, Any]:
+    """계획의 `dispatches[]` 에서 이 워커의 행 하나. 검증기와 같은 규칙으로 맞춘다.
+
+    `validators/validate-run.py` `_plan_dispatch_finding_ids` 처럼 `worker` 가
+    그대로 같거나 `<worker>-worker` 가 같으면 그 행이다.
+    """
+    dispatches = plan.get("dispatches")
+    if not isinstance(dispatches, list):
+        raise ReverifyPromptError("round plan has no dispatches array")
+    matched = [
+        row for row in dispatches
+        if isinstance(row, Mapping)
+        and (row.get("worker") == worker_id or f"{row.get('worker')}-worker" == worker_id)
+    ]
+    if len(matched) != 1:
+        planned = ", ".join(
+            _nonempty_string(row.get("worker")) or "?" for row in dispatches
+            if isinstance(row, Mapping)
+        )
+        raise ReverifyPromptError(
+            f"round plan dispatches nothing to `{worker_id}`; planned workers: "
+            f"{planned or 'none'}"
+        )
+    finding_ids = matched[0].get("findingIds")
+    if not isinstance(finding_ids, list) or not finding_ids:
+        raise ReverifyPromptError(f"round plan row for `{worker_id}` has no findingIds")
+    return matched[0]
+
+
+def reverify_findings(
+    groups: Mapping[str, Any],
+    plan: Mapping[str, Any],
+    worker_id: str,
+    *,
+    project_root: Path,
+    run_dir: Path,
+) -> list[ReverifyFinding]:
+    """계획 행의 finding 을 계획 순서대로, 원 워커의 실물 인용 위치와 함께."""
+    row = plan_row_for_worker(plan, worker_id)
+    by_id = {
+        _nonempty_string(group.get("findingId")): group
+        for group in groups.get("groups") or []
+        if isinstance(group, Mapping) and _nonempty_string(group.get("findingId"))
+    }
+    result_paths = {
+        result.worker_id: result.result_path
+        for result in analyser_results(groups, project_root=project_root, run_dir=run_dir)
+    }
+    findings: list[ReverifyFinding] = []
+    for finding_id in row["findingIds"]:
+        group = by_id.get(str(finding_id))
+        if group is None:
+            raise ReverifyPromptError(
+                f"round plan names `{finding_id}`, which the grouping does not carry"
+            )
+        origin = _nonempty_string(group.get("originWorker"))
+        discovered = group.get("discoveredBy")
+        origin_item = (
+            _nonempty_string((discovered.get(origin) or {}).get("itemId"))
+            if isinstance(discovered, Mapping) and isinstance(discovered.get(origin), Mapping)
+            else ""
+        )
+        result_path = result_paths.get(origin, "")
+        if not origin or not origin_item or not result_path:
+            raise ReverifyPromptError(
+                f"finding `{finding_id}` has no resolvable origin item "
+                f"(origin worker `{origin or '?'}`, item `{origin_item or '?'}`)"
+            )
+        try:
+            audit_path = audit_sidecar_rel(result_path)
+        except WorkerArtifactPathError as exc:
+            raise ReverifyPromptError(str(exc)) from exc
+        findings.append(ReverifyFinding(
+            finding_id=str(finding_id),
+            summary=_nonempty_string(group.get("summary")),
+            origin_worker=origin,
+            origin_item_id=origin_item,
+            origin_evidence=_nonempty_string(group.get("originEvidence")),
+            origin_result_path=result_path,
+            origin_audit_path=audit_path,
+        ))
+    return findings
+
+
+def reverify_prompt_body(
+    *,
+    task_key: str,
+    round_number: int,
+    adversarial: bool,
+    findings: Sequence[ReverifyFinding],
+) -> str:
+    """reverify 지시문 파일 본문. 같은 입력이면 같은 바이트를 낸다."""
+    if not _nonempty_string(task_key):
+        raise ReverifyPromptError("convergence groups carry no taskKey")
+    if not findings:
+        raise ReverifyPromptError("no findings to verify")
+    mode = "ADVERSARIAL re-verification" if adversarial else "re-verification"
+    mandate = _ADVERSARIAL_MANDATE if adversarial else _COLLABORATIVE_MANDATE
+    response = _ADVERSARIAL_RESPONSE if adversarial else _COLLABORATIVE_RESPONSE
+    rows = [
+        "## Instructions\n\n",
+        f"{RENDERED_BY_LINE}\n\n",
+        f"Perform {mode} for {task_key} (round {round_number}).\n\n",
+        mandate, "\n\n",
+        _EVIDENCE_ACCESS, "\n\n",
+        "## Findings to verify\n",
+    ]
+    for finding in findings:
+        rows.append(f"\n### {finding.finding_id}: {finding.summary or '(no summary)'}\n")
+        rows.append(f"**Origin**: {finding.origin_worker}\n")
+        rows.append(f"**Cited evidence**: {finding.origin_evidence or '(none recorded)'}\n")
+        rows.append(
+            f"**Origin item**: `{finding.origin_result_path}` — section "
+            f"`### {finding.origin_item_id}`\n"
+        )
+        rows.append(f"**Origin audit sidecar**: `{finding.origin_audit_path}`\n")
+    rows.append("\n## Response format\n\n")
+    rows.append(
+        "One block per finding, headed by the finding id at exactly three hashes. "
+        "Field labels are bold with the colon outside (`**Verdict**: …`); the "
+        "collector also reads `**Verdict:** …` and `- Verdict: …` as the same field.\n\n"
+    )
+    rows.append(response.replace("<finding-id>", findings[0].finding_id))
+    rows.append("\n")
+    if len(findings) > 1:
+        rows.append(f"\n### {findings[1].finding_id}\n**Verdict**: ...\n")
+    return "".join(rows)

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -1032,29 +1032,8 @@ def _translator_job_from_reservation(
         raise DispatchError(
             "translator dispatch requires a canonical translator role execution"
         )
-    contract = manifest.get("agentContract")
-    if not isinstance(contract, Mapping):
-        raise DispatchError("translator dispatch requires an agent contract")
-    reservation_root = _resolve_required_path(
-        project_root, contract, "invocationReservationRootPath"
-    )
-    dispatched_ids = {
-        str(row.get("dispatchId") or "")
-        for collection in (
-            team_state.get("workerDispatches") or [],
-            team_state.get("agentDispatches") or [],
-        )
-        for row in collection
-        if isinstance(row, Mapping)
-    }
+    candidates, seen = translator_reservations(project_root, manifest, team_state)
     run_manifest_rel = _string_value(manifest.get("runManifestPath"))
-    candidates, seen = _translator_reservation_candidates(
-        project_root,
-        reservation_root,
-        execution=execution,
-        dispatched_ids=dispatched_ids,
-        run_manifest_rel=run_manifest_rel,
-    )
     if len(candidates) != 1:
         run_label = run_manifest_rel or "run manifest path unknown"
         raise DispatchError(
@@ -1120,6 +1099,47 @@ def _translator_job_from_reservation(
     )
 
 
+def translator_reservations(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+) -> tuple[list[Mapping[str, Any]], list[str]]:
+    """이 run 이 지금 디스패치할 수 있는 translator 예약과, 본 예약 전부의 요약.
+
+    두 소비자가 같은 답을 읽는다: `_translator_job_from_reservation` 은 그 하나를
+    골라 띄우고, `report-finalize` 의 `translate` 단계
+    (`okstra_ctl.report_translation_dispatch`) 는 0건이면 예약을 만든다. 후보를
+    세는 규칙이 두 곳이면 한쪽만 고쳐져 "만들었는데 못 고른다" 가 나온다.
+    """
+    execution = _canonical_translator_execution(manifest)
+    if execution is None:
+        raise DispatchError(
+            "translator dispatch requires a canonical translator role execution"
+        )
+    contract = manifest.get("agentContract")
+    if not isinstance(contract, Mapping):
+        raise DispatchError("translator dispatch requires an agent contract")
+    reservation_root = _resolve_required_path(
+        project_root, contract, "invocationReservationRootPath"
+    )
+    dispatched_ids = {
+        str(row.get("dispatchId") or "")
+        for collection in (
+            team_state.get("workerDispatches") or [],
+            team_state.get("agentDispatches") or [],
+        )
+        for row in collection
+        if isinstance(row, Mapping)
+    }
+    return _translator_reservation_candidates(
+        project_root,
+        reservation_root,
+        execution=execution,
+        dispatched_ids=dispatched_ids,
+        run_manifest_rel=_string_value(manifest.get("runManifestPath")),
+    )
+
+
 def _translator_reservation_candidates(
     project_root: Path,
     reservation_root: Path,

package/runtime/python/okstra_ctl/execution_mutation_audit.py

@@ -38,6 +38,12 @@ class MutationSnapshot:
     # 때문이다(다른 라운드의 재시도 프롬프트, 로그, 상태 사이드카가 그 창에
     # 들어온다).
     orchestrator_paths: tuple[str, ...] = ()
+    # artifact root(프로젝트 루트)의 HEAD. 소스 root 가 워크트리라 `git_projection`
+    # 은 워크트리를 보고, 프로젝트 루트에서 사람이 브랜치를 바꾸면 그 사실이 어디에도
+    # 남지 않았다. 다이제스트에는 넣지 않는다 — 이 필드가 없던 시절의 `before`
+    # 스냅샷이 아직 실행 중인 디스패치에 남아 있고, 그것을 못 읽으면 그 워커가
+    # 통째로 error 가 된다. 두 루트가 같으면 None.
+    artifact_git_head: str | None = None
 
     def to_payload(self) -> dict[str, Any]:
         return {
@@ -50,6 +56,7 @@ class MutationSnapshot:
             "gitProjection": dict(self.git_projection),
             "digest": self.digest,
             "orchestratorPaths": list(self.orchestrator_paths),
+            "artifactGitHead": self.artifact_git_head,
         }
 
     @classmethod
@@ -64,6 +71,10 @@ class MutationSnapshot:
             git_projection=dict(payload["gitProjection"]),
             digest=str(payload["digest"]),
             orchestrator_paths=tuple(payload.get("orchestratorPaths", ())),
+            artifact_git_head=(
+                str(payload["artifactGitHead"])
+                if payload.get("artifactGitHead") else None
+            ),
         )
         expected = _snapshot_digest(
             snapshot.root,
@@ -168,6 +179,9 @@ class ExecutionMutationAudit:
             git_projection=git_projection,
             digest=digest,
             orchestrator_paths=orchestrator,
+            artifact_git_head=(
+                None if artifact_root == root else _git_head(artifact_root)
+            ),
         )
 
     def compare(
@@ -206,8 +220,8 @@ class ExecutionMutationAudit:
             source_changes,
             out_of_plan_edits,
         )
-        artifact_failures, untracked_artifact_changes = _artifact_policy_failures(
-            before, rows, artifact_changed
+        artifact_failures, untracked_artifact_changes, switched = (
+            _artifact_policy_failures(before, rows, artifact_changed, after=after)
         )
         violations.extend(artifact_failures)
         status = _terminal_status(
@@ -234,7 +248,8 @@ class ExecutionMutationAudit:
             after_digest=after.digest,
             git_projection=after.git_projection,
             untracked_artifact_paths=tuple(sorted(untracked_artifact_changes)),
-            warnings=_audit_warnings(untracked_artifact_changes),
+            warnings=_audit_warnings(untracked_artifact_changes)
+            + _branch_switch_warnings(before, after, switched),
         )
 
 
@@ -250,6 +265,24 @@ def _audit_warnings(untracked_artifact_changes: set[str]) -> tuple[str, ...]:
     )
 
 
+def _branch_switch_warnings(
+    before: MutationSnapshot, after: MutationSnapshot, switched: set[str],
+) -> tuple[str, ...]:
+    if not switched:
+        return ()
+    shown = sorted(switched)[:5]
+    more = len(switched) - len(shown)
+    tail = f" (+{more} more)" if more else ""
+    return (
+        "artifact root HEAD moved "
+        f"{(before.artifact_git_head or '?')[:12]} → "
+        f"{(after.artifact_git_head or '?')[:12]} during the dispatch; "
+        f"{len(switched)} tracked path(s) that differ between those commits are "
+        "attributed to that switch, not to the worker: "
+        + ", ".join(shown) + tail,
+    )
+
+
 def _validate_batch(policies: tuple[WritePolicy, ...]) -> tuple[Path, Path]:
     if not policies:
         raise MutationAuditError("mutation audit requires at least one policy")
@@ -611,14 +644,24 @@ def _artifact_policy_failures(
     snapshot: MutationSnapshot,
     policies: Sequence[WritePolicy],
     changed: set[str],
-) -> tuple[list[str], set[str]]:
-    """``(위반 목록, 위반이 아닌 비추적 신규 경로)``.
+    *,
+    after: MutationSnapshot | None = None,
+) -> tuple[list[str], set[str], set[str]]:
+    """``(위반 목록, 위반이 아닌 비추적 신규 경로, 브랜치 전환으로 설명되는 경로)``.
 
     artifact root 의 변경 중 위반으로 남는 것은 두 부류다 — okstra 산출물
     서브트리(`.okstra/`) 안의 허용 밖 쓰기와, git 이 추적하는 파일의 변경.
     그 밖의 비추적 신규 파일은 워커의 도구가 남긴 로그·캐시이므로 소스 root 의
     `_split_tracked` 와 같은 이유로 기록만 한다. artifact root 가 git 레포가
     아니면 추적 여부를 알 수 없으므로 종전대로 전부 위반으로 본다.
+
+    추적 파일의 변경 중 **artifact root 의 HEAD 가 실행 창 안에서 옮겨졌고 그
+    두 커밋 사이에서 실제로 달라지는 경로**는 워커의 쓰기가 아니라 사람의 브랜치
+    전환이다. 실측(2026-09-09, `fontsninja-v3-site` dev-10627 reverify r1b): 워커가
+    워크트리에서 읽기만 하는 8분 동안 프로젝트 루트에서 `checkout preprod →
+    rebase` 가 있었고, run 브랜치에만 있는 `CardHero.{tsx,styled.ts}` 가 사라져
+    완주한 결과가 `contract-failed-unattributed` 로 폐기됐다. 그 경로는 위반에서
+    빼고 경고로 남긴다. 전환으로 설명되지 않는 추적 파일 변경은 그대로 위반이다.
     """
     allowed = _allowed_artifact_paths(policies)
     orchestrator = {
@@ -632,7 +675,7 @@ def _artifact_policy_failures(
         and not any(_is_within(path, item) for item in orchestrator)
     }
     if snapshot.artifact_root == snapshot.root:
-        return [], set()
+        return [], set(), set()
     tracked = _tracked_paths(snapshot.artifact_root)
     if tracked is None:
         untracked_outside: set[str] = set()
@@ -642,9 +685,54 @@ def _artifact_policy_failures(
             if path not in tracked
             and not _is_within(path, _OKSTRA_ARTIFACT_SUBTREE)
         }
-    violating = unauthorized - untracked_outside
+    # 전환으로 설명되는 경로는 사라진 쪽(after 에서 비추적)과 나타난 쪽(after 에서
+    # 추적) 양쪽에 걸친다 — 둘 다 워커의 흔적이 아니므로 두 집합에서 함께 뺀다.
+    switched = {
+        path for path in _branch_switch_paths(snapshot, after)
+        if path in unauthorized and not _is_within(path, _OKSTRA_ARTIFACT_SUBTREE)
+    }
+    untracked_outside -= switched
+    violating = unauthorized - untracked_outside - switched
     failures = ["artifact-root change exceeds batch policy union"] if violating else []
-    return failures, untracked_outside
+    return failures, untracked_outside, switched
+
+
+def _branch_switch_paths(
+    before: MutationSnapshot, after: MutationSnapshot | None,
+) -> set[str]:
+    """artifact root 의 HEAD 가 before→after 사이에 옮겨졌을 때 두 커밋 간 달라지는 경로."""
+    if after is None:
+        return set()
+    old_head, new_head = before.artifact_git_head, after.artifact_git_head
+    if not old_head or not new_head or old_head == new_head:
+        return set()
+    listing = subprocess.run(
+        ["git", "-C", str(before.artifact_root), "diff", "--name-only", old_head, new_head],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if listing.returncode != 0:
+        return set()
+    return {line.strip() for line in listing.stdout.splitlines() if line.strip()}
+
+
+def _git_head(root: Path) -> str | None:
+    probe = subprocess.run(
+        ["git", "-C", str(root), "rev-parse", "--is-inside-work-tree"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if probe.returncode != 0:
+        return None
+    head = subprocess.run(
+        ["git", "-C", str(root), "rev-parse", "HEAD"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return head.stdout.strip() or None if head.returncode == 0 else None
 
 
 def _allowed_artifact_paths(policies: Sequence[WritePolicy]) -> set[str]: