okstra 0.225.1 → 0.226.0

package/runtime/python/okstra_ctl/initial_prompt_materialization.py

@@ -40,8 +40,10 @@ from .worker_prompt_body import (
 )
 from .worker_prompt_contract import PromptRecord, validate_initial_prompt_records
 from .worker_prompt_headers import source_worktree_headers, worker_prompt_headers
+from .approved_plan_stage_extract import StageExtractError, materialize_stage_extract
 from .worker_prompt_policy import (
     APPROVED_PLAN_HEADER,
+    APPROVED_PLAN_STAGE_EXTRACT_HEADER,
     IMPLEMENTATION_STAGE_HEADER,
     STAGE_QA_OWNER_HEADER,
     PromptPlan,
@@ -720,6 +722,11 @@ def _prompt_body(
         plan,
         _optional_approved_plan_path(context) if plan.include_approved_plan else "",
         _selected_direction_path(context) if plan.include_selected_direction else "",
+        (
+            _approved_plan_stage_extract(context)
+            if plan.audience == "implementation-executor"
+            else ""
+        ),
     )
 
 
@@ -1466,6 +1473,10 @@ def _implementation_anchor_lines(
     lines.append(
         f"{APPROVED_PLAN_HEADER} {_required_approved_plan_path(context)}"
     )
+    if plan.audience == "implementation-executor":
+        extract = _approved_plan_stage_extract(context)
+        if extract:
+            lines.append(f"{APPROVED_PLAN_STAGE_EXTRACT_HEADER} {extract}")
     lines.append(
         f"{IMPLEMENTATION_STAGE_HEADER} {_required_stage_number(context)}"
     )
@@ -1526,6 +1537,36 @@ def _required_approved_plan_path(context: _MaterializationContext) -> str:
     return str(_resolve_input_path(context.project_root, Path(value)))
 
 
+def _approved_plan_stage_extract(context: _MaterializationContext) -> str:
+    """Write this run's stage extract of the approved plan; its project path.
+
+    Empty when the plan is not a report record (see `materialize_stage_extract`),
+    and the executor then reads the plan itself.
+    """
+    stage = _required_stage_number(context)
+    if not stage.isdigit():
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            f"implementation stage is not a stage number: {stage}",
+        )
+    active_context_path = _resolve_input_path(
+        context.project_root,
+        Path(_required_string(context.manifest, "activeRunContextPath")),
+    )
+    suffix = active_context_path.name.removeprefix("active-run-context-")
+    output = active_context_path.with_name(f"approved-plan-stage-{stage}-{suffix}")
+    try:
+        written = materialize_stage_extract(
+            Path(_required_approved_plan_path(context)), int(stage), output
+        )
+    except (StageExtractError, JsonBoundaryError) as exc:
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            f"cannot project the approved plan onto stage {stage}: {exc}",
+        ) from exc
+    return _project_relative(context.project_root, output) if written else ""
+
+
 def _optional_approved_plan_path(context: _MaterializationContext) -> str:
     """The approved plan path when this run recorded one, otherwise empty.
 

package/runtime/python/okstra_ctl/manager_split.py

@@ -18,6 +18,7 @@ from types import ModuleType
 from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
 from okstra_ctl.jsonl import append_jsonl
 
+from .analysis_packet import BY_REFERENCE_FORMAT, _fence_mask
 from .ids import slugify_task_segment
 from .manager_paths import children_json_path, events_jsonl_path, split_plan_path, task_manifest_path
 from .manager_store import (
@@ -47,6 +48,7 @@ _LIST_FIELDS = (
     "constraints",
     "openQuestions",
     "outOfScope",
+    "localSources",
 )
 # 파일명·하위 task id 로 쓰이므로 경로 구분자나 공백을 받지 않는다.
 _TICKET_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
@@ -54,6 +56,9 @@ _TICKET_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
 _FILE_TITLE_DROP = re.compile(r"[^0-9A-Za-z가-힣ㄱ-ㅎㅏ-ㅣ ]+")
 _FILE_TITLE_MAX = 60
 _NONE = "_(none)_"
+_CREATED = re.compile(r"^created: (\d{4}-\d{2}-\d{2})$", re.M)
+# 다른 이슈나 같은 이슈의 다른 프로젝트가 늘 때 바뀌는 생성 절. 기존 브리프에서는 이 절의 바뀐 줄만 고친다.
+_REFRESHED_SECTIONS = ("### Out of scope", "## Related Artifacts", "## Related Task Graph")
 
 
 def brief_file_title(title: str) -> str:
@@ -246,6 +251,40 @@ def _source_block(index: int, ref: str, fetched_via: str, fetched_at: str, body:
     ]
 
 
+def _local_source_block(index: int, ref: str, fetched_at: str) -> list[str]:
+    return [
+        f"### Source {index} — file",
+        "",
+        f"- ref: {ref}",
+        "- fetched-via: okstra manager task split",
+        f"- fetched-at: {fetched_at}",
+        f"- format: {BY_REFERENCE_FORMAT}",
+        "",
+        "```",
+        "```",
+        "",
+    ]
+
+
+def _local_source_refs(assignment: dict, project_root: Path, where: str, errors: list[str]) -> list[str]:
+    """계획의 `localSources` 를 프로젝트 루트 기준 상대 경로로 바꾼다. 루트 밖이나 없는 파일은 거절한다."""
+    root = project_root.resolve()
+    refs: list[str] = []
+    for index, raw in enumerate(assignment["localSources"], 1):
+        candidate = Path(raw).expanduser()
+        path = (candidate if candidate.is_absolute() else root / candidate).resolve()
+        try:
+            relative = path.relative_to(root).as_posix()
+        except ValueError:
+            errors.append(f"{where}.localSources[{index}] {raw!r} is outside project root {str(root)!r}")
+            continue
+        if not path.is_file():
+            errors.append(f"{where}.localSources[{index}] {raw!r} is not a file under {str(root)!r}")
+            continue
+        refs.append(relative)
+    return list(dict.fromkeys(refs))
+
+
 def _source_is_issue(source: dict, issue: dict) -> bool:
     return source["ref"] in {issue["ticketId"], issue["url"]}
 
@@ -284,6 +323,7 @@ def _render_brief(
     project_root: str,
     siblings: list[tuple[str, dict, Path]],
     graph: list[tuple[str, ...]],
+    local_sources: list[str],
 ) -> str:
     ticket = issue["ticketId"]
     project_id = assignment["projectId"]
@@ -322,6 +362,10 @@ def _render_brief(
     ]
     if not _source_is_issue(source, issue):
         lines.extend(_source_block(2, source["ref"], source["fetchedVia"], source["fetchedAt"], source["body"]))
+    first_local = 2 if _source_is_issue(source, issue) else 3
+    for index, ref in enumerate(local_sources, first_local):
+        # 같은 계획을 다시 돌려도 브리프가 같도록 날짜만 쓴다.
+        lines.extend(_local_source_block(index, ref, created))
     lines.extend(
         [
             "## Context",
@@ -385,10 +429,125 @@ def _validate_rendered(items: list[dict], validator: ModuleType, group_segment:
             path = briefs_root / group_segment / item["briefPath"].name
             path.parent.mkdir(parents=True)
             path.write_text(item["text"], encoding="utf-8")
-            errors.extend(f"{item['taskKey']}: {error}" for error in validator.validate_brief(path, briefs_root))
+            # discussion follow-up 도 이 함수를 쓰며 projectRoot 를 넘기지 않는다. 그 브리프는 prepare 가 다시 검사한다.
+            project_root = Path(item["projectRoot"]) if item.get("projectRoot") else None
+            errors.extend(
+                f"{item['taskKey']}: {error}"
+                for error in validator.validate_brief(path, briefs_root, project_root)
+            )
     return errors
 
 
+def _plan_items(
+    projects: dict, task_group: str, group_segment: str, source: dict, issues: list[dict], validator: ModuleType,
+) -> tuple[list[dict], list[str]]:
+    """(이슈, 프로젝트) 쌍마다 렌더링 입력을 만든다. 본문은 `created` 가 정해진 뒤 `_render_item` 이 쓴다."""
+    keys: dict[tuple[str, str], str] = {}
+    items: list[dict] = []
+    for issue in issues:
+        ticket = issue["ticketId"]
+        stem = "-".join(part for part in (ticket, brief_file_title(issue["title"])) if part)
+        for assignment in issue["assignments"]:
+            project_id = assignment["projectId"]
+            child_task_id = slugify_task_segment(ticket)
+            key = f"{project_id}:{task_group}:{child_task_id}"
+            keys[(ticket, project_id)] = key
+            root = Path(str(projects[project_id].get("projectRoot") or ""))
+            items.append({"issue": issue, "assignment": assignment, "stem": stem, "taskKey": key,
+                          "projectId": project_id, "childTaskId": child_task_id, "projectRoot": str(root),
+                          "briefPath": root / ".okstra" / "briefs" / group_segment / f"{stem}.md"})
+    errors: list[str] = []
+    for item in items:
+        item["localSources"] = _local_source_refs(item["assignment"], Path(item["projectRoot"]),
+                                                  item["taskKey"], errors)
+    graph = _graph_rows(source, issues, keys, set(validator.DIRECTED_TASK_RELATIONS))
+    for item in items:
+        item["graph"] = graph
+        item["siblings"] = [(other["taskKey"], other["assignment"], other["briefPath"]) for other in items
+                            if other["issue"] is item["issue"] and other is not item]
+    return items, errors
+
+
+def _render_item(item: dict, source: dict, task_group: str, manager_task: str, created: str) -> str:
+    return _render_brief(source=source, issue=item["issue"], assignment=item["assignment"],
+                         task_group=task_group, manager_task=manager_task,
+                         child_task_id=item["childTaskId"], stem=item["stem"],
+                         created=created, key=item["taskKey"], project_root=item["projectRoot"],
+                         siblings=item["siblings"], graph=item["graph"], local_sources=item["localSources"])
+
+
+def _previous_items(
+    home: Path, manager_id: str, task_group: str, task_id: str, projects: dict, group_segment: str,
+    validator: ModuleType,
+) -> tuple[dict, dict]:
+    """지난 분할이 남긴 계획의 렌더링 입력을 브리프 경로별로 돌려준다. 지금 프로젝트 목록으로 검증되지 않으면 비운다."""
+    path = split_plan_path(home, manager_id, task_group, task_id)
+    if not path.is_file():
+        return {}, {}
+    source, issues, errors = normalize_plan(_load_plan(path), set(projects), set(validator.TASK_RELATIONS))
+    if errors:
+        return {}, {}
+    items, errors = _plan_items(projects, task_group, group_segment, source, issues, validator)
+    if errors:
+        return {}, {}
+    return {item["briefPath"]: item for item in items}, source
+
+
+def _existing_created(text: str) -> str:
+    match = _CREATED.search(text)
+    return match.group(1) if match else ""
+
+
+def _section_spans(lines: list[str]) -> dict[str, tuple[int, int]]:
+    """펜스 밖 제목 줄마다 본문 범위 (시작, 끝). Source Material 본문 속 `#` 줄은 제목이 아니다."""
+    headings = [index for index, (line, fenced) in enumerate(zip(lines, _fence_mask(lines)))
+                if not fenced and line.startswith("#")]
+    spans: dict[str, tuple[int, int]] = {}
+    for position, start in enumerate(headings):
+        end = headings[position + 1] if position + 1 < len(headings) else len(lines)
+        spans.setdefault(lines[start], (start + 1, end))
+    return spans
+
+
+def _outside_refreshed(lines: list[str], spans: dict[str, tuple[int, int]]) -> list[str]:
+    kept = list(lines)
+    for start, end in sorted((spans[heading] for heading in _REFRESHED_SECTIONS), reverse=True):
+        del kept[start:end]
+    return kept
+
+
+def _merge_section(ours: list[str], base: list[str], new: list[str]) -> list[str]:
+    """지난 렌더링에서 이번 렌더링으로 바뀐 줄만 기존 절에 반영한다. 손으로 더한 줄은 남는다."""
+    removed = set(base) - set(new)
+    added = [line for line in new if line.strip() and line not in base]
+    merged = [line for line in ours if not (line.strip() and line in removed)]
+    if any(line != _NONE for line in added):
+        merged = [line for line in merged if line != _NONE]
+        added = [line for line in added if line != _NONE]
+    elif any(line.strip() and line != _NONE for line in merged):
+        added = []
+    content = [index for index, line in enumerate(merged) if line.strip()]
+    at = content[-1] + 1 if content else min(1, len(merged))
+    merged[at:at] = added
+    return merged
+
+
+def _refresh(current: str, base: str, new: str) -> str | None:
+    """`base` 와 `new` 가 생성 갱신 절에서만 다르면 그 차이를 `current` 에 반영한 본문, 아니면 None."""
+    ours, old, fresh = current.split("\n"), base.split("\n"), new.split("\n")
+    ours_spans, old_spans, fresh_spans = _section_spans(ours), _section_spans(old), _section_spans(fresh)
+    if any(heading not in spans for spans in (ours_spans, old_spans, fresh_spans) for heading in _REFRESHED_SECTIONS):
+        return None
+    if _outside_refreshed(old, old_spans) != _outside_refreshed(fresh, fresh_spans):
+        return None
+    result = list(ours)
+    for heading in sorted(_REFRESHED_SECTIONS, key=lambda heading: ours_spans[heading][0], reverse=True):
+        start, end = ours_spans[heading]
+        result[start:end] = _merge_section(ours[start:end], old[slice(*old_spans[heading])],
+                                           fresh[slice(*fresh_spans[heading])])
+    return "\n".join(result)
+
+
 def split_task(
     home: Path,
     manager_id: str,
@@ -412,46 +571,45 @@ def split_task(
         raise ManagerError("split plan rejected:\n- " + "\n- ".join(errors))
     when = now or _now_iso()
     manager_task = f"{manager_id}/{task_group}/{task_id}"
-    keys: dict[tuple[str, str], str] = {}
-    items: list[dict] = []
-    for issue in issues:
-        ticket = issue["ticketId"]
-        stem = "-".join(part for part in (ticket, brief_file_title(issue["title"])) if part)
-        for assignment in issue["assignments"]:
-            project_id = assignment["projectId"]
-            child_task_id = slugify_task_segment(ticket)
-            key = f"{project_id}:{task_group}:{child_task_id}"
-            keys[(ticket, project_id)] = key
-            root = Path(str(projects[project_id].get("projectRoot") or ""))
-            items.append({"issue": issue, "assignment": assignment, "stem": stem, "taskKey": key,
-                          "projectId": project_id, "childTaskId": child_task_id, "projectRoot": str(root),
-                          "briefPath": root / ".okstra" / "briefs" / group_segment / f"{stem}.md"})
-    graph = _graph_rows(source, issues, keys, set(validator.DIRECTED_TASK_RELATIONS))
+    items, errors = _plan_items(projects, task_group, group_segment, source, issues, validator)
+    if errors:
+        raise ManagerError("split plan rejected:\n- " + "\n- ".join(errors))
+    previous, previous_source = _previous_items(home, manager_id, task_group, task_id, projects, group_segment,
+                                                validator)
     for item in items:
-        siblings = [(other["taskKey"], other["assignment"], other["briefPath"]) for other in items
-                    if other["issue"] is item["issue"] and other is not item]
-        item["text"] = _render_brief(source=source, issue=item["issue"], assignment=item["assignment"],
-                                     task_group=task_group, manager_task=manager_task,
-                                     child_task_id=item["childTaskId"], stem=item["stem"],
-                                     created=when[:10], key=item["taskKey"], project_root=item["projectRoot"],
-                                     siblings=siblings, graph=graph)
+        path = item["briefPath"]
+        item["current"] = path.read_text(encoding="utf-8") if path.is_file() else None
+        # 다시 분할해도 브리프가 처음 쓰인 날짜를 유지한다. 실행 날짜를 쓰면 계획이 같아도 모든 브리프가 바뀐다.
+        created = _existing_created(item["current"] or "") or when[:10]
+        item["text"] = _render_item(item, source, task_group, manager_task, created)
+        before = previous.get(path)
+        item["base"] = _render_item(before, previous_source, task_group, manager_task, created) if before else None
     errors = _validate_rendered(items, validator, group_segment)
     if errors:
         raise ManagerError("rendered briefs failed validate-brief:\n- " + "\n- ".join(errors))
     for item in items:
-        path = item["briefPath"]
-        if not path.is_file():
+        current, base = item["current"], item["base"]
+        refreshed = _refresh(current, base, item["text"]) if current is not None and base is not None else None
+        if current is None:
             item["briefStatus"] = "created"
-        elif path.read_text(encoding="utf-8") == item["text"]:
+        elif current == item["text"] or base == item["text"] or refreshed == current:
             item["briefStatus"] = "unchanged"
+        elif refreshed is not None:
+            item["briefStatus"] = "refreshed"
+            item["text"] = refreshed
         else:
             item["briefStatus"] = "overwritten"
     conflicts = [str(item["briefPath"]) for item in items if item["briefStatus"] == "overwritten"]
     if conflicts and not overwrite:
         raise ManagerError(
-            "briefs already exist with different content; pass --overwrite to replace them:\n- "
+            "briefs already exist with content this plan would change outside the Related Task Graph, "
+            "Out of scope and Related Artifacts sections; pass --overwrite to replace them:\n- "
             + "\n- ".join(conflicts)
         )
+    errors = _validate_rendered([item for item in items if item["briefStatus"] == "refreshed"], validator,
+                                group_segment)
+    if errors:
+        raise ManagerError("refreshed briefs failed validate-brief:\n- " + "\n- ".join(errors))
     for item in items:
         if item["briefStatus"] != "unchanged":
             item["briefPath"].parent.mkdir(parents=True, exist_ok=True)

package/runtime/python/okstra_ctl/next_phase.py

@@ -270,7 +270,9 @@ def _from_option_selection(report_data: Mapping[str, Any]) -> dict[str, str]:
         return make(status=_OPTION_SELECTION_NON_PHASE[routing])
     if not routing:
         return make(status=STATUS_PENDING)
-    return make(phase=routing, status=STATUS_READY)
+    # 이 phase 의 routing 은 enum 이라 이유 칸이 없다. technical-verification 과
+    # 검증된 preselected 방향의 근거도 차단 분기와 같은 selectionGuidance 에서 온다.
+    return make(phase=routing, status=STATUS_READY, rationale=_selection_guidance(selection))
 
 
 def _direction_selection_reason(selection: Mapping[str, Any]) -> str:

package/runtime/python/okstra_ctl/phases/final_verification/prior_blockers.py

@@ -0,0 +1,128 @@
+"""같은 검증 대상의 이전 final-verification run 이 남긴 차단 사유를 packet 용으로 좁힌다.
+
+final-verification run 은 직전 run 의 판정을 하나도 받지 못했다. 그래서 각 run 이
+결함 하나를 새로 찾고, 같은 계열의 다음 칸은 다음 run 이 찾았다. 이 블록은 같은
+reports 디렉터리(단일 stage 면 stage 별, whole-task 면 task 별)의 이전 리포트에서
+차단 사유 전부와 가장 최근 run 의 잔여 위험만 싣는다. 리포트 전문은 싣지 않는다.
+
+재발 판단은 소유하지 않는다. 워커가 원리를 비교해 `defectClass.recurrence` 를
+적고, 검증기는 그 표기의 형식과 라우팅만 본다(`validation.py`).
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from pathlib import Path
+
+from okstra_ctl.final_report_paths import final_report_data_path
+from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
+
+_REPORT_RE = re.compile(r"^final-report-final-verification-(\d{3,})\.data\.json$")
+_SUMMARY_LIMIT = 300
+_WHITESPACE_RE = re.compile(r"\s+")
+
+
+def prior_blockers_packet_block(final_report_path: Path) -> str:
+    """이번 run 리포트보다 앞선 순번의 리포트 요약. 차단 사유가 없으면 빈 문자열."""
+    current = _REPORT_RE.match(final_report_data_path(Path(final_report_path)).name)
+    current_seq = int(current.group(1)) if current else None
+    reports_dir = Path(final_report_path).parent
+    priors = []
+    for path in sorted(reports_dir.glob("final-report-final-verification-*.data.json")):
+        match = _REPORT_RE.match(path.name)
+        if match is None:
+            continue
+        seq = int(match.group(1))
+        if current_seq is not None and seq >= current_seq:
+            continue
+        data = _load(path)
+        if data:
+            priors.append((match.group(1), data))
+    if not priors:
+        return ""
+    run_lines: list[str] = []
+    for seq, data in priors:
+        run_lines.extend(_run_lines(seq, data))
+    latest_seq, latest = priors[-1]
+    risk_lines = _risk_lines(latest)
+    if not any(line.startswith("  - AB-") for line in run_lines) and not risk_lines:
+        return ""
+    parts = [
+        "## Prior Final-Verification Blockers",
+        "",
+        "Earlier final-verification runs of this same target blocked on the",
+        "rows below. Before judging anything new, re-check each carried",
+        "blocker's whole class — every location and case its mechanism reaches —",
+        "on the current head. When a blocker you raise shares a carried",
+        "blocker's mechanism, set `defectClass.recurrence` to `recurring`, cite",
+        "the carried row in `defectClass.priorBlockers` as",
+        "`final-verification-NNN AB-NNN`, and route to a phase that re-plans",
+        "the class, never to `implementation`.",
+        "",
+        *run_lines,
+    ]
+    if risk_lines:
+        parts.extend([
+            "",
+            f"Residual risks `final-verification-{latest_seq}` left open:",
+            *risk_lines,
+        ])
+    return "\n".join(parts)
+
+
+def _run_lines(seq: str, data: Mapping) -> list[str]:
+    fv = data.get("finalVerification")
+    fv = fv if isinstance(fv, Mapping) else {}
+    verdict = _one_line((data.get("finalVerdict") or {}).get("verdictToken")) or "unrecorded"
+    routing = fv.get("routingRecommendation")
+    target = _one_line(routing.get("target")) if isinstance(routing, Mapping) else ""
+    lines = [
+        f"- `final-verification-{seq}`: verdict `{verdict}`, routed "
+        f"`{target or 'unrecorded'}`"
+    ]
+    for row in fv.get("acceptanceBlockers") or []:
+        if not isinstance(row, Mapping):
+            continue
+        defect_class = row.get("defectClass")
+        mechanism = (
+            _one_line(defect_class.get("mechanism"))
+            if isinstance(defect_class, Mapping) else ""
+        )
+        line = (
+            f"  - {_one_line(row.get('id')) or '<no id>'} "
+            f"({_one_line(row.get('severity')) or 'unrated'}): "
+            f"{_one_line(row.get('statement'))}"
+        )
+        if mechanism:
+            line += f" — mechanism: {mechanism}"
+        lines.append(line)
+    return lines
+
+
+def _risk_lines(data: Mapping) -> list[str]:
+    fv = data.get("finalVerification")
+    rows = fv.get("residualRisk") if isinstance(fv, Mapping) else None
+    return [
+        f"- {_one_line(row.get('id')) or '<no id>'}: {_one_line(row.get('item'))}"
+        for row in rows or []
+        if isinstance(row, Mapping)
+    ]
+
+
+def _load(path: Path) -> Mapping:
+    try:
+        data = load_owned_object(path, artifact="prior final-verification report")
+    except (JsonBoundaryError, OSError):
+        # expected-miss: 이전 run 이 깨뜨린 리포트. 맥락 블록일 뿐이라 그 run 을
+        # 건너뛰고, 이번 검증 준비는 막지 않는다.
+        return {}
+    return data if isinstance(data, Mapping) else {}
+
+
+def _one_line(value: object) -> str:
+    if not isinstance(value, str):
+        return ""
+    collapsed = _WHITESPACE_RE.sub(" ", value).strip()
+    if len(collapsed) <= _SUMMARY_LIMIT:
+        return collapsed
+    return collapsed[: _SUMMARY_LIMIT - 1].rstrip() + "…"

package/runtime/python/okstra_ctl/phases/final_verification/profile.md

@@ -30,6 +30,8 @@
 - Worker verification procedure:
   - **Target confirmation:** analyse the injected target and nothing else. Read `verification-target.md` for the stage/report mapping and the complete diff stat. Prepare fixed that target and `phases/final_verification/validation.py` `validate_verification_target_match` (called by `validators/validate-run.py`) re-checks the report against its digest, so the procedure to follow here is simply: if the worktree you can see does not match the injected target, record a `tool-failure` — never reselect a target.
   - **Evidence:** attach file:line, exact command + exit code, log excerpt, or MCP SELECT evidence to every finding. Mark a requirement as covered only when the cited artifact demonstrates it.
+  - **Defect-class sweep:** a confirmed defect is one instance of a class, and finding it does not end the search. Name its mechanism in one sentence (for example "after a recovery the editor keeps a copy of server data taken before the recovery"). Enumerate every location in the verified diff and its direct callers where that mechanism can occur, and the cases that change its outcome (for example same version, version changed, two recoveries overlapping, cancelled request). Judge every location × case cell `defective`, `sound`, `unverified`, or `not-applicable` with evidence, and report every defective cell in this run. Each blocker records the sweep as `defectClass` (`mechanism`, `cells[]`, `recurrence`). Its fix is the whole class: every `defective` cell names the `regressionTest` that must fail before the fix and pass after it. Sweep a Residual Risk's class the same way before writing it; a residual row has no `defectClass` field, so the sweep goes into its `item` text. **Enforced:** `phases/final_verification/validation.py` `_validate_defect_class_sweep` refuses a blocker without `defectClass`, without a `defective` cell, or with a `defective` cell that names no `regressionTest`. Whether the enumeration is complete is a judgement no validator can make.
+  - **Prior-run carry-in:** when an earlier final-verification run of the same target exists, the analysis packet carries its blockers under `## Prior Final-Verification Blockers` (`phases/final_verification/prior_blockers.py`). Re-check each carried blocker's whole class on the current head. A blocker whose mechanism matches a carried one is `recurrence: recurring` and cites it in `priorBlockers` as `final-verification-NNN AB-NNN`; a class a single-point fix already failed to close is re-planned, so a report with a `recurring` blocker routes to `error-analysis`, `implementation-option-selection`, or `implementation-planning`, never to `implementation`. **Enforced:** `validation.py` `_validate_defect_class_sweep` refuses a `recurring` blocker with no `priorBlockers`, and `_validate_recurring_class_routing` refuses any other routing target. Marking a matching class `new` is a judgement the validator cannot see.
   - **Tier 1 and Tier 2 read-only validation:** Tier 1 is the originating brief/approved plan `validation` set. Tier 2 is the `Project QA Commands` section from `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <TASK_KEY>` (the full `Task key` your dispatch prompt names). Do not auto-detect commands from package manifests. A missing tier is `qa-command not configured: <category>`. Before execution, reject commands containing source/lockfile mutation tokens such as `--fix`, `--write`, ` -w`, ` -u`, `--snapshot-update`, `INSTA_UPDATE=<not-no>`, `cargo update`, or `npm install` without `ci`; record the exact denied token. Tier 2 is already screened by prepare, so this check catches a Tier 1 command the brief or plan named.
   - **External QA outcome policy:** continue to attempt every in-scope Tier 3
     command. For an entry requiring `db`, `http`, or `external`, record non-PASS
@@ -56,7 +58,7 @@
   - **Source Implementation Report(s)** (**Enforced:** `phases/final_verification/validation.py` `validate_verification_target_match` (called by `validators/validate-run.py`) compares `verificationScope`, `worktreePath`, `implementationBaseRef`, `capturedHeadSha`, and the `stageReports` stage set against the digest-verified `instruction-set/verification-target.md`; a snapshot whose digest no longer checks out is ignored rather than trusted. `verificationScope` in particular gates both stage-group eligibility and release-handoff routing, so it is not the report's to restate): the `VERIFICATION_TARGET` snapshot verbatim — verification scope, worktree path, base/head refs, the list of stages under verification, and one row per stage citing its originating implementation final-report (`report_path` from `consumers.jsonl`; render `(report_path unrecorded)` when absent). Every analyser prompt carries the same compact target identity (`**Verification scope:** / **Worktree:** / **Verification base ref:** / **Verification head ref:** / **Verification target path:** / **Verification target digest:**`) and reads the sidecar on demand for the complete diff stat. A worker that cannot confirm its analysis ran against that worktree's delivered diff MUST record a `tool-failure`.
   - **Verdict vocabulary**: Section 7 (`Final Verdict`) MUST include a `Verdict Token` field whose value is exactly one of `accepted`, `conditional-accept`, or `blocked`. `conditional-accept` requires an explicit, exhaustive list of conditions; ambiguous verdicts ("looks good", "mostly ready") are not allowed. Each condition MUST be recorded as a row in the **Conditional Acceptance Conditions** deliverable (`id` `CA-NNN`, `condition`, `evidenceRequired`, `blocksReleaseHandoff`). `blocksReleaseHandoff` is a gate, not a note: `false` means this condition alone would not stop the release, and a `conditional-accept` whose conditions are all `false` may route to `release-handoff` (the conditions travel into the PR body as unresolved items). Declare `true` for anything that must be settled before release. The validator enforces verdict↔deliverable consistency: `accepted` ⇒ zero acceptance blockers, `blocked` ⇒ at least one, `conditional-accept` ⇒ at least one condition, and a `release-handoff` routing recommendation is allowed only when the verdict is release-ready by `okstra_ctl.release_gate.release_handoff_allowed`. **Any Acceptance Blocker therefore forces the verdict off `accepted` (to `conditional-accept` or `blocked`); the gates below cite this rule instead of restating the arithmetic.**
   - **Added-surface audit** (`finalVerification.addedSurfaceAudit`): the reverse of requirement coverage — one row per surface the merged diff added (`id` `AS-NNN`, `surface` as `path:line` + the added name, `callers`, `requirement`, `disposition`, `note`). Requirement coverage proves every requirement reached the diff; this table proves every addition answers a requirement. An empty array is a claim that the diff added no identifier, module, or configuration entry, not permission to skip the enumeration. Single-stage scope audits its own stage's diff; whole-task audits the merged diff, which is the only place a surface added by one stage and orphaned by another is visible.
-  - **Acceptance Blockers block** (under section 4): one row per blocker with `id`, `severity` (`critical` / `major`), evidence (file path, log excerpt, or test output), and the recommended follow-up phase: `error-analysis` for a cause problem, `implementation-option-selection` for a direction problem, or `implementation-planning` for a detailed-plan problem. Empty block is acceptable and preferred — render the single line `- No acceptance blockers found.`
+  - **Acceptance Blockers block** (under section 4): one row per defect class with `id`, `severity` (`critical` / `major`), evidence (file path, log excerpt, or test output), the recommended follow-up phase: `error-analysis` for a cause problem, `implementation-option-selection` for a direction problem, or `implementation-planning` for a detailed-plan problem, and the `defectClass` sweep from the worker procedure above. The `statement` names the fix for the whole class, not for the first cell found. Empty block is acceptable and preferred — render the single line `- No acceptance blockers found.`
   - **Residual Risk block** (under section 4): risks that are not blockers but should be tracked, each with mitigation owner and a trigger that would escalate them to a blocker.
   - **Validation Evidence**: for every requirement in the originating plan or task brief, cite the artifact (commit SHA, test output, log line, MCP SELECT result) that demonstrates coverage. Paraphrased "verified" claims without an artifact are rejected.
   - **Read-only command log**: any pre-existing test/validation command touched during this run MUST be listed with its exact command line and one honest status — `executed` (ran; carries its exit code) / `advisory` (external Tier 3 did not PASS; carries observed/expected results and remains user-owned) / `env-unavailable` (should run but cannot in this environment — missing replica DB, container, or service; carries the reason, never a faked pass) / `not-configured` (no such qa-command tier) / `rejected` (a mutating/denied token — skipped, carries the denied token). A check that could not run locally is recorded as `env-unavailable` or `advisory` according to the external QA policy — never silently dropped and never reported as `executed` with an invented exit code. Mutating-command prohibition is the shared read-only boundary (see Non-goals); it is not restated per row.
@@ -68,11 +70,12 @@
 - Self-review pass before finalising the report (the Okstra lead runs this; do not delegate it):
   1. **Verdict precision** — section 7 (`Final Verdict`) includes `Verdict Token` with one of the three allowed verdict tokens; `conditional-accept` lists every condition as an actionable item.
   2. **Blocker traceability** — every blocker cites a concrete artifact (file:line, log excerpt, test exit code, MCP SELECT). Blockers without evidence are demoted to residual risk or removed.
-  3. **Coverage check** — every requirement in the originating plan/task brief is either marked covered (with artifact) or listed as a blocker. A user-owned external advisory gap is the sole outcome exception: keep it as a Residual Risk with the exact rerun Recommended Next Step instead of promoting it to a blocker. No silent omissions.
-  4. **Verifier dissent preserved** — if workers reach different verdicts, the disagreement is visible in section 1.2; synthesis hides nothing.
-  5. **No source-mutation audit** — scan the run's session transcripts for Edit / Write or state-mutating Bash commands that touch paths OUTSIDE `<PROJECT_ROOT>/.okstra/**` and outside the assigned run-artifact paths. Writes to worker prompts, audit sidecars, team-state, the final-report `data.json`, and rendered reports under the run directory are allowed okstra artifacts. Any source/schema/deployment mutation means the run has crossed into implementation and MUST be re-routed; do NOT silently strip the evidence.
+  3. **Class completeness** — the first confirmed blocker is not the whole list. Before the verdict, check each blocker's `defectClass` against the verified diff: a location or case the workers did not judge is swept now (re-dispatch the verifiers on that class when the lead cannot judge it from the cited evidence), and blockers sharing one mechanism merge into one row. Carried prior blockers are re-checked the same way.
+  4. **Coverage check** — every requirement in the originating plan/task brief is either marked covered (with artifact) or listed as a blocker. A user-owned external advisory gap is the sole outcome exception: keep it as a Residual Risk with the exact rerun Recommended Next Step instead of promoting it to a blocker. No silent omissions.
+  5. **Verifier dissent preserved** — if workers reach different verdicts, the disagreement is visible in section 1.2; synthesis hides nothing.
+  6. **No source-mutation audit** — scan the run's session transcripts for Edit / Write or state-mutating Bash commands that touch paths OUTSIDE `<PROJECT_ROOT>/.okstra/**` and outside the assigned run-artifact paths. Writes to worker prompts, audit sidecars, team-state, the final-report `data.json`, and rendered reports under the run directory are allowed okstra artifacts. Any source/schema/deployment mutation means the run has crossed into implementation and MUST be re-routed; do NOT silently strip the evidence.
 - Cross-verification mode:
-  - **Acceptance critic (opt-in, one slot — recommended 1)**: the user chooses whether to add the slot at launch and, when they add it, picks its model. With no critic slot this pass does not run. A reused-worker **acceptance devil's-advocate** pass is dispatched concurrently with the first convergence reverify round to surface candidate acceptance blockers the verifiers may have missed; candidates are verified only after convergence completes. Each candidate is verified **confirm-or-downgrade**: confirmed → an `Acceptance Blockers` row; unconfirmed → a `Residual Risk` row (never dropped). See `prompts/lead/convergence.md` "Acceptance critic pass (final-verification)".
+  - **Acceptance critic (opt-in, one slot — recommended 1)**: the user chooses whether to add the slot at launch and, when they add it, picks its model. With no critic slot this pass does not run. A reused-worker **acceptance devil's-advocate** pass is dispatched concurrently with the first convergence reverify round to surface candidate acceptance blockers the verifiers may have missed; candidates are verified only after convergence completes. Each candidate is verified **confirm-or-downgrade**: confirmed → an `Acceptance Blockers` row; unconfirmed → a `Residual Risk` row (never dropped). The critic also sweeps the classes the verifiers raised: a location or case of an existing blocker's mechanism that the verifiers did not judge is a new candidate, not a restatement. Reverify rounds stay confirm-or-refute only; the sweep belongs to the workers that raise a finding and to the critic. See `prompts/lead/convergence.md` "Acceptance critic pass (final-verification)".
 - Non-goals:
   - proposing unrelated refactors beyond the delivered scope
   - **source code edits, follow-up bug fixes, or scope expansion** — this run renders a verdict only; defects detected here become inputs to a new `error-analysis`, `implementation-option-selection`, or `implementation-planning` run according to whether the cause, direction, or detailed plan is invalid

package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification.template.html

@@ -34,7 +34,7 @@
 <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") }}
-  <div class="summary-grid">{% for row in final.acceptanceBlockers %}<article class="summary-card tone-important" id="id-{{ row.id }}"><p class="eyebrow">{{ row.id | inline_code }} · {{ row.severity }}</p><h3>{{ row.statement | inline_code }}</h3><p class="evidence-refs">{{ t('macros.layout.evidence') }} {{ row.evidence | inline_code }}</p><p>{{ t('tasks.final-verification.follow-up') }} {{ row.followUpPhase | inline_code }}</p></article>{% else %}<p>{{ t('tasks.final-verification.nothing-is-holding-acceptance') }}</p>{% endfor %}</div>
+  <div class="summary-grid">{% for row in final.acceptanceBlockers %}<article class="summary-card tone-important" id="id-{{ row.id }}"><p class="eyebrow">{{ row.id | inline_code }} · {{ row.severity }}</p><h3>{{ row.statement | inline_code }}</h3><p class="evidence-refs">{{ t('macros.layout.evidence') }} {{ row.evidence | inline_code }}</p><p>{{ t('tasks.final-verification.follow-up') }} {{ row.followUpPhase | inline_code }}</p>{% if row.get("defectClass") %}{% set dc = row.defectClass %}<p><strong>{{ t('tasks.final-verification.defect-mechanism') }}</strong> {{ dc.mechanism | inline_code }}</p>{% if dc.recurrence == "recurring" %}<p><strong>{{ t('tasks.final-verification.recurring-class') }}</strong> {{ (dc.get("priorBlockers") or []) | join(", ") }}</p>{% endif %}<table data-report-field="finalVerification.acceptanceBlockers.defectClass.cells"><thead><tr><th>{{ t('tasks.final-verification.location') }}</th><th>{{ t('tasks.final-verification.case') }}</th><th>{{ t('tasks.final-verification.verdict') }}</th><th>{{ t('tasks.final-verification.evidence') }}</th><th>{{ t('tasks.final-verification.regression-test') }}</th></tr></thead><tbody>{% for cell in dc.cells %}<tr><td>{{ cell.location | inline_code }}</td><td>{{ cell.case | inline_code }}</td><td>{{ cell.verdict }}</td><td>{{ cell.evidence | inline_code }}</td><td>{{ (cell.get("regressionTest") or "") | inline_code }}</td></tr>{% endfor %}</tbody></table>{% endif %}</article>{% else %}<p>{{ t('tasks.final-verification.nothing-is-holding-acceptance') }}</p>{% endfor %}</div>
 </section>
 
 <section data-report-section="residual-risk" data-report-field="finalVerification.residualRisk">