okstra 0.225.0 → 0.226.0

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">

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

@@ -20,6 +20,8 @@ def validate_final_verification_content(data: dict, failures: list[str]) -> None
     if (data.get("header") or {}).get("taskType") != "final-verification":
         return
     _validate_added_surface_audit(data, failures)
+    _validate_defect_class_sweep(data, failures)
+    _validate_recurring_class_routing(data, failures)
     _validate_verdict_consistency(data, failures)
     _validate_verification_scope(data, failures)
 
@@ -97,6 +99,88 @@ def _added_surface_row_failures(
     return []
 
 
+def _acceptance_blockers(data: dict) -> list[Mapping]:
+    rows = (data.get("finalVerification") or {}).get("acceptanceBlockers") or []
+    return [row for row in rows if isinstance(row, Mapping)]
+
+
+def _validate_defect_class_sweep(data: dict, failures: list[str]) -> None:
+    """차단 사유마다 그것이 속한 결함 계열을 위치×경우 칸 단위로 훑었는지 본다.
+
+    위치 하나만 적은 차단 사유는 다음 run 이 같은 원리의 다른 위치나 다른 경우를
+    새로 찾게 만들었다. 실측: 한 계열이 final-verification 네 번에 걸쳐 하나씩
+    드러났다(dev-11562 stage 1, 001-004).
+    """
+    for row in _acceptance_blockers(data):
+        row_id = str(row.get("id") or "<id 없음>")
+        defect_class = row.get("defectClass")
+        if not isinstance(defect_class, Mapping):
+            failures.append(
+                f"final-verification: acceptance blocker {row_id} has no "
+                "`defectClass` — name the mechanism and sweep every location "
+                "and case that shares it before reporting the blocker."
+            )
+            continue
+        cells = [
+            cell for cell in defect_class.get("cells") or []
+            if isinstance(cell, Mapping)
+        ]
+        defective = [cell for cell in cells if cell.get("verdict") == "defective"]
+        if not defective:
+            failures.append(
+                f"final-verification: acceptance blocker {row_id} sweeps no "
+                "`defective` cell — the blocker itself is one, so record it."
+            )
+        untested = [
+            f"{cell.get('location')} / {cell.get('case')}"
+            for cell in defective
+            if not str(cell.get("regressionTest") or "").strip()
+        ]
+        if untested:
+            failures.append(
+                f"final-verification: acceptance blocker {row_id} has "
+                f"`defective` cells with no `regressionTest`: {untested} — the "
+                "fix covers the whole class, one regression test per cell."
+            )
+        if (
+            defect_class.get("recurrence") == "recurring"
+            and not defect_class.get("priorBlockers")
+        ):
+            failures.append(
+                f"final-verification: acceptance blocker {row_id} is "
+                "`recurring` but cites no `priorBlockers` "
+                "(`final-verification-NNN AB-NNN`)."
+            )
+
+
+_CLASS_REPLANNING_TARGETS = (
+    "error-analysis",
+    "implementation-option-selection",
+    "implementation-planning",
+)
+
+
+def _validate_recurring_class_routing(data: dict, failures: list[str]) -> None:
+    """이전 run 이 이미 막았던 계열은 한 지점 수정으로 다시 보내지 않고 재계획한다."""
+    recurring = [
+        str(row.get("id") or "<id 없음>")
+        for row in _acceptance_blockers(data)
+        if isinstance(row.get("defectClass"), Mapping)
+        and row["defectClass"].get("recurrence") == "recurring"
+    ]
+    if not recurring:
+        return
+    routing = (data.get("finalVerification") or {}).get("routingRecommendation")
+    target = str((routing or {}).get("target") or "") if isinstance(routing, Mapping) else ""
+    if target not in _CLASS_REPLANNING_TARGETS:
+        failures.append(
+            f"final-verification: acceptance blockers {recurring} are "
+            f"`recurring`, but routing targets `{target}`. A class a single-point "
+            "fix already failed to close routes to one of "
+            f"{list(_CLASS_REPLANNING_TARGETS)} so the whole class is re-planned."
+        )
+
+
 def _validate_verdict_consistency(data: dict, failures: list[str]) -> None:
     verdict = data.get("finalVerdict") or {}
     token = (verdict.get("verdictToken") or "").strip().lower()

package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md

@@ -52,7 +52,7 @@ template's check; that template is gone.
 - **External-source adapters — structure AND fixture both derive from a captured real sample; a self-authored fixture is NOT reality evidence:** when this run's diff builds or changes an `external-interface` or `transformation-mapping` surface (an HTTP / network client, or a parser / mapper of a third-party payload — HTML / JSON / XML / CSV originating outside this repo), the adapter's structural assumptions (selectors, field paths, expected response shape) AND the static fixture / golden that tests them MUST BOTH derive from a **captured real sample** of that payload — the capture cited in the stage's `external-interface` / `transformation-mapping` design-prep item, or one captured this run and recorded with its `source` + capture time. The captured sample is a static fixture (no live socket), so a parser test against it stays in source like any unit test — the Real-IO isolation rule below governs *live* calls, not the captured bytes. Do NOT hand-invent the shape and then hand-write a fixture that agrees with it: the passing test then only proves the code matches your assumption, never that the assumption matches reality (self-confirming oracle — the observed failure was a parser whose selectors existed in its synthetic fixture and in zero real pages: hundreds of green units over a fiction, and the whole structure built on the wrong shape). When no real sample is reachable (no network this run, or the brief supplied none), do NOT synthesize a stand-in and present its green tests as correctness: mark the adapter's shape `reality-unverified (no captured sample)` in `Validation evidence`, keep any placeholder fixture explicitly labelled an assumption (never validation evidence), and surface an explicit **user-owned** item in the routing recommendation to confirm against real data. Unlike the DB gate above this does NOT itself block acceptance — live external verification stays a user-owned item per `final-verification`'s External QA advisory policy — but a synthetic external fixture presented as reality-verified is exactly the mock-only external evidence the `final-verification` test-correctness pass is meant to reject.
 - **Real-IO test isolation (BLOCKING).** A test that exercises a **real** datastore, HTTP endpoint, external service, message queue, or filesystem — a live DB connection / DSN, a real `fetch` / `axios` / `http` request, an actual S3 / queue client, anything the project's normal CI test suite cannot run because that backend is absent — MUST be written under the task's qa scripts directory `<task_root>/qa/scripts/` (`<TASK_QA_PATH>/scripts`; the `qa/` root itself holds only data sidecars — the Tier 3 conformance manifest and `result-*.json`). It MUST NOT be written into the project source test tree — `src/**`, `test/**`, `tests/**`, `**/__test__/**`, `**/__tests__/**`, `*.spec.*`, `*.test.*`, or anywhere the project's lint/test globs collect. Two reasons: (a) the project's CI / normal suite has no real DB or network, so a real-IO test placed in source silently breaks the pipeline; (b) it is an okstra verification artifact, and the artifact-home rule confines okstra outputs to `.okstra/`. **The dividing line is the IO, not the intent:** a unit test that stubs/spies only *injected collaborators* (mock — no real socket, no real DB handle) is a TDD red-green artifact and stays in source; the moment a test opens a real connection or makes a real network call it belongs in qa. A stage's real-IO requirement check is a Tier 3 conformance script under `<task_root>/qa/scripts/` (declared via the implementation-planning conformance entry) — never smuggle real IO into a `*.spec.*` in source to make it run "as a unit test". The `db-test` real-execution gate above is satisfied by the conformance/db-test path against the replica, NOT by adding a live-DB `*.spec.*` to the project suite. **Author qa specs with the project's own test framework — never hand-roll `describe`/`it`/`expect`.** When the project ships a test runner as a devDependency (jest / vitest / pytest …), the qa spec uses it, invoked with the project config plus a discovery override pointing at the qa scripts dir (jest: `npx jest --config <project jest config> --roots <task_root>/qa/scripts --runInBand <spec-name>`) — the project config keeps module aliases resolving while the default sweep never collects the file; never widen the project's own test config to include qa paths. For TypeScript qa specs also write `<task_root>/qa/scripts/tsconfig.json` (`extends` the project tsconfig, adds the runner's `types` entry, `"include": ["**/*.ts"]`) so editors resolve path aliases and test globals — it is a qa artifact like the rest (untracked). **These qa artifacts stay untracked — never commit them.** `.okstra/**` is gitignored (the artifact-home rule); conformance scripts and their results are *executed* and recorded in the carry sidecar / verifier result, never written into git history. A committed `.okstra/qa` file is a stage-branch defect that leaks okstra internals into the eventual PR (see the `git add` rules below).
 - **Stage conformance script (BLOCKING when the approved plan declared `Conformance tests:`).** Planning only declared the path and `requires`. This run MUST write the script to that path under `<task_root>/qa/scripts/` and add the matching `<task_root>/qa/conformance-manifest.json` entry: `stageKey` (= `<task-id>-stage-<N>`), `script`, `runCommand`, `requirementIds`, `requires` (the set the plan declared, widened by any db/io/http/external surface this stage's diff touches that the plan left out — never narrowed; `validate-run.py` `_declared_conformance_errors` accepts a superset and rejects a subset), `passContract`, `exemption: null`, `waiver: null`. Do not skip this when the plan declared tests. If the plan declared `Conformance exemption:`, do not invent a script — with one exception: when this stage's diff touches a db/io/http/external surface the exemption promised it would not (the verifier's diff-surface cross-check names the surface), write the script and the manifest entry for this stage exactly as for a declared stage, with `requires` covering those surfaces. The approved plan is not rewritten; `validate-run.py` `_declared_conformance_errors` accepts an entry for a stage the plan exempted and still rejects one for a stage the plan does not have. The script's standard interface: a `main` that exits `0`=PASS / non-zero=FAIL, and whose stdout ends with `QA-RESULT: PASS|FAIL` followed by one `REQ <id>: PASS|FAIL: <reason>` line per requirement. The verifier runs `runCommand` from the **worktree cwd**, and that cwd is the tree under test. `runCommand` MUST NOT repoint it: a leading `cd <checkout> &&` sends the script at a tree without this stage's changes. Absolute paths are fine and usually necessary — the script and its `tsconfig` live under `<task_root>/qa/scripts/`, i.e. under `.okstra/`, and a worktree does not carry `.okstra/`. Point at those by absolute path; leave the cwd alone. **Enforced:** `scripts/okstra_ctl/conformance.py` `_check_entry` rejects a `runCommand` whose first word in any `&&` / `;` segment changes directory; `validators/validate-run.py` `_validate_conformance` fails the run if the inherited declaration has no script file.
-- read the approved plan at this prompt's `**Approved plan:**` anchor end-to-end and parse the `## 5.5 Stage Map`. Read this prompt's `**Stage for this implementation run:**` anchor: the single stage number this run owns. The runtime already selected and reserved this stage (one run = one stage) — do NOT recompute the start stage from `consumers.jsonl`. Both anchors are generated headers; when either is missing, stop and report `contract-violated` rather than inferring the value.
+- read the stage extract at this prompt's `**Approved plan stage extract:**` anchor end-to-end. It is the approved plan projected onto this run's stage: the whole Stage Map (`stageMap`), this stage's entry, the requirement-coverage, validation, rollback and risk rows that name this stage or name no stage, each with the `planItemId` (`P-Val-4`, `P-Rb-2`) directives cite it by, and the clarification items. Its `omitted` object names everything left out and why. The plan at the `**Approved plan:**` anchor stays the source of record: open it only for a targeted lookup of a key the extract omits, never end-to-end. When the prompt has no extract anchor (a Markdown plan, or a prompt published before the extract existed), read the approved plan end-to-end and parse its Stage Map instead. Read this prompt's `**Stage for this implementation run:**` anchor: the single stage number this run owns. The runtime already selected and reserved this stage (one run = one stage) — do NOT recompute the start stage from `consumers.jsonl`. Both anchors are generated headers; when either is missing, stop and report `contract-violated` rather than inferring the value.
   - load every `runs/<plan-key>/carry/stage-<i>.json` for `i ∈ depends-on(this stage)` and inject them into the executor's working context as "runtime carry-in". For a `depends-on (none)` stage, no sidecar load — task-brief only.
   - this stage's `depends-on` are all already `status:done`. Its file list, step order, Stage Validation commands, Stage Exit Contract, and rollback path are the authoritative scope.
 - **Clarification answers carried in (read before the first edit):** when the user answered the approved plan's `## 1. Clarification Items` rows, those answers arrive with this prompt under the heading `# Clarification answers carried in (authoritative)`, or as the `Clarification response` path under `## Inputs`. Treat each answer as an authoritative refinement of the plan's scope for the matching row; an answer that contradicts or expands the approved scope beyond the plan is a re-plan trigger (route to a new `implementation-planning` run), not a silent in-run change.