okstra 0.202.0 → 0.205.0

package/runtime/python/okstra_ctl/role_requirements.py

@@ -1,10 +1,17 @@
-"""Parse canonical role requirements declared in phase profiles."""
+"""Load the role structure a phase profile declares.
+
+The structure lives in `prompts/profiles/<task-type>.json` beside the profile's
+Markdown task instructions. The Markdown owns procedure and per-task inputs and
+outputs; it declares no machine-readable roster. See ADR-0017.
+"""
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
+from typing import Union
 
 from .domain.role import RoleCatalogError, normalize_role, role_for_duty
+from .json_boundary import JsonBoundaryError, load_owned_object
 
 
 class RoleProfileError(ValueError):
@@ -12,13 +19,16 @@ class RoleProfileError(ValueError):
 
 
 @dataclass(frozen=True)
-class RoleRequirement:
+class StaticRoleRequirement:
+    """A role slot whose count the run fixes before dispatch."""
+
     role: str
     min_count: int
     recommended_count: int
     max_count: int
     duty: str
-    dynamic: bool = False
+
+    dynamic: bool = field(default=False, init=False)
 
     def signature(self) -> tuple[str, int, int, int, str, bool]:
         return (
@@ -27,138 +37,129 @@ class RoleRequirement:
             self.recommended_count,
             self.max_count,
             self.duty,
-            self.dynamic,
+            False,
         )
 
 
+@dataclass(frozen=True)
+class DynamicRoleRequirement:
+    """A role slot the runtime adds once per activated source slot.
+
+    It carries no counts. Expressing it as 0/0/0 made a dynamic role look like a
+    static role nobody selected, which is a different thing: the upper bound is
+    the number of activated source slots, not zero.
+    """
+
+    role: str
+    duty: str
+    source_role_ids: tuple[str, ...]
+    activation: str
+
+    dynamic: bool = field(default=True, init=False)
+
+    def signature(self) -> tuple[str, str, tuple[str, ...], str, bool]:
+        return (self.role, self.duty, self.source_role_ids, self.activation, True)
+
+
+RoleRequirement = Union[StaticRoleRequirement, DynamicRoleRequirement]
+
+
 @dataclass(frozen=True)
 class RoleProfile:
     roles: tuple[RoleRequirement, ...]
 
-    def role_signature(self) -> tuple[tuple[str, int, int, int, str, bool], ...]:
+    def role_signature(self) -> tuple[tuple[object, ...], ...]:
         return tuple(requirement.signature() for requirement in self.roles)
 
 
-_REQUIRED_FIELDS = frozenset({"role", "min", "recommended", "max", "duty"})
-_ALLOWED_FIELDS = _REQUIRED_FIELDS | {"dynamic"}
-
-
 def load_role_profile(path: Path) -> RoleProfile:
-    """Load and validate the one fenced YAML ``roles:`` declaration in a profile."""
-    profile_path = Path(path)
+    """Load the structure contract for the profile at *path*.
+
+    Callers hold the profile's Markdown path because that is what the rest of
+    the prepare step reads, so this resolves the `.json` sibling itself. Passing
+    the `.json` path directly is the same call.
+    """
+    profile_path = Path(path).with_suffix(".json")
     try:
-        text = profile_path.read_text(encoding="utf-8")
+        payload = load_owned_object(profile_path, artifact="role profile")
+    except JsonBoundaryError as exc:
+        raise RoleProfileError(f"invalid role profile: {profile_path}: {exc}") from exc
     except OSError as exc:
         raise RoleProfileError(f"cannot read role profile: {profile_path}") from exc
-    raw_roles, errors = _parse_roles_block(text)
+
+    errors: list[str] = []
+    if payload.get("schemaVersion") != "1.0":
+        errors.append("role profile schemaVersion must be 1.0")
+    raw_roles = payload.get("roles")
+    if not isinstance(raw_roles, list):
+        raise RoleProfileError("invalid role profile:\n- roles must be a list")
+
     requirements = tuple(
-        _validate_requirement(raw, index, errors)
+        _requirement(raw, index, errors)
         for index, raw in enumerate(raw_roles, 1)
     )
     _validate_static_role_duplicates(requirements, errors)
+    _validate_dynamic_sources(requirements, errors)
     if errors:
         raise RoleProfileError("invalid role profile:\n- " + "\n- ".join(errors))
     return RoleProfile(requirements)
 
 
-def _parse_roles_block(text: str) -> tuple[list[dict[str, str]], list[str]]:
-    blocks = _yaml_blocks_with_roles(text)
-    if len(blocks) != 1:
-        return [], ["profile must declare exactly one fenced YAML roles block"]
-    lines = blocks[0]
-    if lines == ["roles: []"]:
-        return [], []
-    if not lines or lines[0] != "roles:":
-        return [], ["roles block must start with roles:"]
-    roles: list[dict[str, str]] = []
-    errors: list[str] = []
-    current: dict[str, str] | None = None
-    for line_number, line in enumerate(lines[1:], 2):
-        if not line.strip():
-            continue
-        if line.startswith("  - "):
-            if current is not None:
-                roles.append(current)
-            current = {}
-            _add_yaml_field(current, line[4:], line_number, errors)
-            continue
-        if line.startswith("    ") and current is not None:
-            _add_yaml_field(current, line[4:], line_number, errors)
-            continue
-        errors.append(f"roles block line {line_number} is not a role field")
-    if current is not None:
-        roles.append(current)
-    elif not errors:
-        errors.append("roles block must contain a role or use roles: []")
-    return roles, errors
-
-
-def _yaml_blocks_with_roles(text: str) -> list[list[str]]:
-    blocks: list[list[str]] = []
-    current: list[str] | None = None
-    for line in text.splitlines():
-        if line.strip() == "```yaml":
-            current = []
-            continue
-        if line.strip() == "```" and current is not None:
-            if any(item.strip().startswith("roles:") for item in current):
-                blocks.append(current)
-            current = None
-            continue
-        if current is not None:
-            current.append(line)
-    return blocks
-
-
-def _add_yaml_field(
-    fields: dict[str, str], line: str, line_number: int, errors: list[str],
-) -> None:
-    if ":" not in line:
-        errors.append(f"roles block line {line_number} must contain key: value")
-        return
-    key, value = (part.strip() for part in line.split(":", 1))
-    if not key or not value:
-        errors.append(f"roles block line {line_number} must contain key: value")
-        return
-    if key in fields:
-        errors.append(f"roles block line {line_number} repeats {key}")
-        return
-    fields[key] = value
-
-
-def _validate_requirement(
-    raw: dict[str, str], index: int, errors: list[str],
-) -> RoleRequirement:
+def _requirement(raw: object, index: int, errors: list[str]) -> RoleRequirement:
     prefix = f"role requirement {index}"
-    for field in sorted(_REQUIRED_FIELDS - raw.keys()):
-        errors.append(f"{prefix} is missing {field}")
-    for field in sorted(raw.keys() - _ALLOWED_FIELDS):
-        errors.append(f"{prefix} has unknown field {field}")
-
-    role = _validate_role(raw.get("role", ""), prefix, errors)
-    min_count = _validate_non_negative_integer(
-        raw.get("min", ""), "min", prefix, errors,
+    if not isinstance(raw, dict):
+        errors.append(f"{prefix} must be an object")
+        return StaticRoleRequirement("", 0, 0, 0, "")
+    mode = raw.get("mode")
+    if mode == "dynamic":
+        return _dynamic_requirement(raw, prefix, errors)
+    if mode == "static":
+        return _static_requirement(raw, prefix, errors)
+    errors.append(f"{prefix} mode must be static or dynamic")
+    return StaticRoleRequirement("", 0, 0, 0, "")
+
+
+def _static_requirement(
+    raw: dict[str, object], prefix: str, errors: list[str]
+) -> StaticRoleRequirement:
+    role = _validate_role(raw.get("roleId"), prefix, errors)
+    duty = _validate_duty(raw.get("dutyId"), role, prefix, errors)
+    counts = tuple(
+        _validate_count(raw.get(key), key, prefix, errors)
+        for key in ("min", "recommended", "max")
     )
-    recommended_count = _validate_non_negative_integer(
-        raw.get("recommended", ""), "recommended", prefix, errors,
-    )
-    max_count = _validate_non_negative_integer(
-        raw.get("max", ""), "max", prefix, errors,
-    )
-    duty = _validate_duty(raw.get("duty", ""), role, prefix, errors)
-    dynamic = _validate_dynamic(raw.get("dynamic", "false"), prefix, errors)
-    if not (min_count <= recommended_count <= max_count):
+    if not (counts[0] <= counts[1] <= counts[2]):
         errors.append(f"{prefix} min must be <= recommended <= max")
-    if dynamic and (min_count != 0 or recommended_count != 0 or max_count != 0):
-        errors.append(
-            f"{prefix} dynamic roles must have min, recommended, and max of zero"
-        )
-    return RoleRequirement(
-        role, min_count, recommended_count, max_count, duty, dynamic,
-    )
-
-
-def _validate_role(raw: str, prefix: str, errors: list[str]) -> str:
+    return StaticRoleRequirement(role, counts[0], counts[1], counts[2], duty)
+
+
+def _dynamic_requirement(
+    raw: dict[str, object], prefix: str, errors: list[str]
+) -> DynamicRoleRequirement:
+    role = _validate_role(raw.get("roleId"), prefix, errors)
+    duty = _validate_duty(raw.get("dutyId"), role, prefix, errors)
+    sources = raw.get("sourceRoleIds")
+    if (
+        not isinstance(sources, list)
+        or not sources
+        or not all(isinstance(item, str) and item for item in sources)
+    ):
+        errors.append(f"{prefix} sourceRoleIds must be a non-empty list of role ids")
+        sources = []
+    activation = raw.get("activation")
+    if activation != "per-selected-source":
+        errors.append(f"{prefix} activation must be per-selected-source")
+        activation = "per-selected-source"
+    for key in ("min", "recommended", "max"):
+        if key in raw:
+            errors.append(f"{prefix} dynamic roles declare no {key}")
+    return DynamicRoleRequirement(role, duty, tuple(sources), str(activation))
+
+
+def _validate_role(raw: object, prefix: str, errors: list[str]) -> str:
+    if not isinstance(raw, str) or not raw:
+        errors.append(f"{prefix} roleId must be a role id")
+        return ""
     try:
         return normalize_role(raw)
     except RoleCatalogError as exc:
@@ -166,7 +167,10 @@ def _validate_role(raw: str, prefix: str, errors: list[str]) -> str:
         return raw
 
 
-def _validate_duty(raw: str, role: str, prefix: str, errors: list[str]) -> str:
+def _validate_duty(raw: object, role: str, prefix: str, errors: list[str]) -> str:
+    if not isinstance(raw, str) or not raw:
+        errors.append(f"{prefix} dutyId must be a duty id")
+        return ""
     try:
         duty_role = role_for_duty(raw)
     except RoleCatalogError as exc:
@@ -177,25 +181,11 @@ def _validate_duty(raw: str, role: str, prefix: str, errors: list[str]) -> str:
     return raw
 
 
-def _validate_non_negative_integer(raw: str, field: str, prefix: str, errors: list[str]) -> int:
-    try:
-        value = int(raw)
-    except ValueError:
-        errors.append(f"{prefix} {field} must be a non-negative integer")
-        return 0
-    if value < 0 or str(value) != raw:
-        errors.append(f"{prefix} {field} must be a non-negative integer")
+def _validate_count(raw: object, field_name: str, prefix: str, errors: list[str]) -> int:
+    if not isinstance(raw, int) or isinstance(raw, bool) or raw < 0:
+        errors.append(f"{prefix} {field_name} must be a non-negative integer")
         return 0
-    return value
-
-
-def _validate_dynamic(raw: str, prefix: str, errors: list[str]) -> bool:
-    if raw == "true":
-        return True
-    if raw == "false":
-        return False
-    errors.append(f"{prefix} dynamic must be true or false")
-    return False
+    return raw
 
 
 def _validate_static_role_duplicates(
@@ -208,3 +198,26 @@ def _validate_static_role_duplicates(
         if requirement.role in static_roles:
             errors.append(f"duplicate static role: {requirement.role}")
         static_roles.add(requirement.role)
+
+
+def _validate_dynamic_sources(
+    requirements: tuple[RoleRequirement, ...], errors: list[str],
+) -> None:
+    """A dynamic slot activates per source slot, so its sources must be declared.
+
+    A source the profile never declares can never activate, which makes the row
+    unreachable rather than invalid at dispatch time — the failure would surface
+    as a round that silently opens no verifier.
+    """
+    static_roles = {
+        requirement.role for requirement in requirements if not requirement.dynamic
+    }
+    for requirement in requirements:
+        if not requirement.dynamic:
+            continue
+        unknown = sorted(set(requirement.source_role_ids) - static_roles)
+        if unknown:
+            errors.append(
+                f"dynamic role {requirement.role} has unknown sourceRoleIds: "
+                + ", ".join(unknown)
+            )

package/runtime/python/okstra_ctl/rollup.py

@@ -142,9 +142,11 @@ def build_rollup(project_root: Path, task_group: str | None) -> dict:
 _CLI_EPILOG = r"""Usage:
   okstra rollup [--task-group <group>] [--project-root <dir>] [--cwd <dir>]
 
-Read-only. Prints a JSON roll-up of every catalog task (optionally scoped to one
+Prints a JSON roll-up of every catalog task (optionally scoped to one
 task-group): per-task run count, elapsed time (raw ms), error count, and the
 latest report path, plus group-level totals and status/category/phase tallies.
+Resolving a task may record a finished implementation outcome in its task
+manifest, the task catalog, and consumers.jsonl; nothing else is written.
 With no --task-group it covers the whole project catalog. Time is raw ms; the
 caller formats HH:MM:SS and synthesizes the prose digest from the report files.
 """

package/runtime/python/okstra_ctl/run.py

@@ -1827,10 +1827,9 @@ def _materialize_release_handoff_input(
     brief 는 entry phase 의 입력물이라 release-handoff 에는 없다 — 이 run 의
     `--task-brief` 자리는 여기서 생성된 input 문서가 채운다. stage 자격은
     okstra_ctl.handoff 의 SSOT 판정을 prepare 에서도 그대로 강제한다.
-    반환: ctx 에 올릴 {"HANDOFF_MODE": ..., "HANDOFF_STAGES": ...}."""
+    반환: ctx 에 올릴 {"HANDOFF_STAGES": ...}."""
     from .consumers import read_consumers
-    from .handoff import (HandoffError, _require_eligible,
-                          latest_whole_task_fv_release_ready)
+    from .handoff import HandoffError, _require_eligible, compute_eligibility
     from .paths import task_dir
     from .render import render_template_with_ctx
     from .run_context import _now_task_date
@@ -1840,8 +1839,8 @@ def _materialize_release_handoff_input(
         raise PrepareError(
             "--task-brief is not accepted for --task-type release-handoff — "
             "the input document is generated from the cited final-verification "
-            "reports (pick stages via --stages, or leave it empty for "
-            "whole-task)"
+            "reports (pick stages via --stages, or leave it empty to take "
+            "every eligible stage)"
         )
     if not inp.approved_plan_path:
         raise PrepareError(
@@ -1868,21 +1867,20 @@ def _materialize_release_handoff_input(
             _require_eligible(stage_map, rows, nums)
         except HandoffError as exc:
             raise PrepareError(str(exc)) from exc
-        mode = "stage-group"
-        stages_csv = ",".join(str(n) for n in nums)
-        report_rows = _collect_handoff_source_report_rows(rows, nums)
     else:
-        report = latest_whole_task_fv_release_ready(
-            project_root, inp.project_id, inp.task_group, inp.task_id)
-        if not report:
+        eligibility = compute_eligibility(stage_map, rows)
+        nums = [e["stage"] for e in eligibility if e["eligible"]]
+        if not nums:
+            blocked = "; ".join(
+                f"stage {e['stage']}: {', '.join(e['reasons'])}"
+                for e in eligibility) or "(no stage in the Stage Map)"
             raise PrepareError(
-                "whole-task release-handoff requires the latest completed, release-ready whole-task "
-                "final-verification report with matching target evidence — re-run final-verification, "
-                "or pass --stages <csv> for a stage-group PR"
+                "release-handoff has no eligible stage — every stage must "
+                "carry a release-ready single-stage final-verification of its "
+                f"recorded implementation commit. {blocked}"
             )
-        mode = "whole-task"
-        stages_csv = ""
-        report_rows = [("(all)", Path(report))]
+    stages_csv = ",".join(str(n) for n in nums)
+    report_rows = _collect_handoff_source_report_rows(rows, nums)
 
     source_rows, source_conditions = _render_handoff_sources(report_rows, project_root)
 
@@ -1902,13 +1900,12 @@ def _materialize_release_handoff_input(
         "PROJECT_ID": inp.project_id,
         "TASK_TYPE": inp.task_type,
         "TASK_DATE": _now_task_date(),
-        "HANDOFF_MODE": mode,
-        "HANDOFF_STAGES": stages_csv or "(all)",
+        "HANDOFF_STAGES": stages_csv,
         "HANDOFF_SOURCE_REPORTS": source_rows,
         "HANDOFF_CONDITIONS": source_conditions,
     })
     inp.brief_path = out
-    return {"HANDOFF_MODE": mode, "HANDOFF_STAGES": stages_csv}
+    return {"HANDOFF_STAGES": stages_csv}
 
 
 QA_COMMAND_EXECUTING_TASK_TYPES = ("implementation", "final-verification")
@@ -2768,7 +2765,7 @@ def recommended_role_models(
     codex 이고 다른 provider 요청은 거부된다(`resolve_lead_provider`). 그래서
     `lead_provider` 를 받아 그 provider 의 기본값으로 해소한다. 받지 않으면
     role 별 레거시 기본값(claude 계열)으로 떨어지는데, 그 값을 codex 호스트
-    화면에 그대로 쓰면 안내는 `opus` 인데 prepare 는 `gpt-5.6-sol` 을 배정한다.
+    화면에 그대로 쓰면 안내는 `opus` 인데 prepare 는 `gpt-6-sol` 을 배정한다.
     """
     lead_provider_id = lead_provider or "claude"
     report_writer_provider_id = report_writer_provider or "claude"
@@ -4250,6 +4247,9 @@ def _write_bundle_artifacts(
     ctx["FIX_CYCLE_ID"] = _record_fix_cycle_events(inp, ctx)
 
 
+CONTRACT_FORMAT_VERSION = 2
+
+
 def _prepare_agent_contract(
     inp: PrepareInputs,
     ctx: dict,
@@ -4258,11 +4258,14 @@ def _prepare_agent_contract(
 ) -> None:
     source = _duty_catalog_source(workspace_root)
     destination = Path(ctx["DUTY_CONTRACT_ROOT"])
-    _snapshot_duty_catalog(source, destination)
+    _snapshot_duty_catalog(source, destination, _common_contract_source(workspace_root))
     digest = digest_duty_catalog(destination)
     allowed_audiences = _allowed_agent_audiences(inp, models)
     contract = {
         "schemaVersion": 1,
+        # 이 run 이 동결한 계약의 형식. 2 = JSON 계약(공통·역할·직무). 1 이거나
+        # 없는 run 은 Markdown 직무를 동결했고, 그 파서는 더 이상 없다.
+        "contractFormatVersion": CONTRACT_FORMAT_VERSION,
         "dutyRootPath": ctx["DUTY_CONTRACT_ROOT_RELATIVE_PATH"],
         "catalogDigest": digest,
         "invocationReservationRootPath": (
@@ -4295,14 +4298,35 @@ def _duty_catalog_source(workspace_root: Path) -> Path:
         okstra_home() / "prompts" / "duties",
     )
     for candidate in candidates:
-        if (candidate / "common.md").is_file():
+        if (candidate / "lead.json").is_file():
             return candidate
     raise PrepareError("agent duty catalog is missing from the runtime")
 
 
-def _snapshot_duty_catalog(source: Path, destination: Path) -> None:
+def _common_contract_source(workspace_root: Path) -> Path:
+    """공통 계약의 정본 위치. 직무가 아니므로 `agents/` 가 소유한다(ADR-0017)."""
+    for candidate in (
+        workspace_root / "agents" / "common.json",
+        okstra_home() / "agents" / "common.json",
+    ):
+        if candidate.is_file():
+            return candidate
+    raise PrepareError("agent common contract is missing from the runtime")
+
+
+def _snapshot_duty_catalog(
+    source: Path, destination: Path, common_source: Path,
+) -> None:
+    """이 run 이 쓸 계약을 한 폴더로 동결한다.
+
+    공통 계약은 `agents/` 가 소유하지만 동결본은 한 뿌리여야 한다 — 두 곳에서
+    읽으면 run 이 시작된 뒤 둘 중 하나만 바뀌어도 그 run 의 다이제스트가
+    자기 입력과 맞지 않게 된다.
+    """
     if destination.exists():
-        if digest_duty_catalog(destination) != digest_duty_catalog(source):
+        if digest_duty_catalog(destination) != _runtime_catalog_digest(
+            source, common_source
+        ):
             raise PrepareError("existing run duty snapshot conflicts with runtime catalog")
         return
     destination.parent.mkdir(parents=True, exist_ok=True)
@@ -4313,15 +4337,38 @@ def _snapshot_duty_catalog(source: Path, destination: Path) -> None:
     ))
     try:
         shutil.copytree(source, temp_dir, dirs_exist_ok=True)
+        shutil.copyfile(common_source, temp_dir / "common.json")
+        shutil.copytree(
+            common_source.parent / "roles", temp_dir / "roles", dirs_exist_ok=True
+        )
         os.rename(temp_dir, destination)
     except FileExistsError as exc:
-        if digest_duty_catalog(destination) != digest_duty_catalog(source):
+        if digest_duty_catalog(destination) != _runtime_catalog_digest(
+            source, common_source
+        ):
             raise PrepareError("run duty snapshot publication conflict") from exc
     finally:
         if temp_dir.exists():
             shutil.rmtree(temp_dir)
 
 
+def _runtime_catalog_digest(source: Path, common_source: Path) -> str:
+    """동결본과 비교할 런타임 카탈로그의 다이제스트.
+
+    동결본은 `common.json` 을 포함하므로 런타임 쪽도 같은 구성으로 세어야 한다.
+    """
+    staged = Path(tempfile.mkdtemp(prefix=".okstra-catalog-digest."))
+    try:
+        shutil.copytree(source, staged, dirs_exist_ok=True)
+        shutil.copyfile(common_source, staged / "common.json")
+        shutil.copytree(
+            common_source.parent / "roles", staged / "roles", dirs_exist_ok=True
+        )
+        return digest_duty_catalog(staged)
+    finally:
+        shutil.rmtree(staged, ignore_errors=True)
+
+
 def _allowed_agent_audiences(
     inp: PrepareInputs,
     models: _ModelBindings,
@@ -4792,7 +4839,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
 
     # release-handoff: 검증 보고서 인용 input 문서를 생성해 brief 자리에 채운다.
     # 이후의 모든 brief 소비 경로(material/instruction-set 복사)는 그대로 동작한다.
-    handoff_tokens = {"HANDOFF_MODE": "", "HANDOFF_STAGES": ""}
+    handoff_tokens = {"HANDOFF_STAGES": ""}
     if inp.task_type == "release-handoff":
         handoff_tokens = _materialize_release_handoff_input(
             workspace_root, project_root, inp)
@@ -5250,8 +5297,8 @@ def build_prepare_argument_parser():
     p.add_argument(
         "--stages", default="", dest="stages",
         help=(
-            "release-handoff only. Comma-separated stage numbers to bundle "
-            "into one PR (stage-group mode); empty = whole-task mode. "
+            "release-handoff only. Comma-separated stage numbers to open a "
+            "PR for, one PR per stage; empty = every eligible stage. "
             "Distinct from --stage (implementation/final-verification "
             "Stage Map selection)."
         ),

package/runtime/python/okstra_ctl/schedule_semantics.py

@@ -33,9 +33,20 @@ _WORK_BREAKDOWN_SEPARATOR = ["---:", "---", "---:", "---", "---:"]
 # No `Task ID` and no `taskType`: the schedule is shared with people who do not
 # run okstra, so a task is named by its work and a row binds to the selection by
 # its `#` position — the same rule the `### <n>.` blocks follow.
-_AT_A_GLANCE_HEADER = [
-    "#", "작업", "Category", "Priority", "Effort", "Days", "Risk",
-]
+# 두 번째 열은 작업 이름 열이고 그 제목은 문서 언어를 따른다(`작업` / `Travail`).
+# 언어별 제목은 형식 게이트(`validate-schedule.py` 의 `glance_work_column`)가
+# 검사한다. 여기서 한국어로 고정하면 번역본이 이 게이트를 통과할 수 없다.
+_AT_A_GLANCE_FIXED_COLUMNS = ["Category", "Priority", "Effort", "Days", "Risk"]
+_AT_A_GLANCE_WIDTH = 2 + len(_AT_A_GLANCE_FIXED_COLUMNS)
+
+
+def _is_at_a_glance_header(cells: list[str]) -> bool:
+    return (
+        len(cells) == _AT_A_GLANCE_WIDTH
+        and cells[0] == "#"
+        and bool(cells[1])
+        and cells[2:] == _AT_A_GLANCE_FIXED_COLUMNS
+    )
 _EFFORT_HEADER = ["Size", "Criteria", "Day(s)"]
 _EFFORT_SIZES = {"S", "M", "L", "XL", "XXL"}
 _DAY_NUMBER = r"\d+(?:\.\d+)?"
@@ -594,9 +605,9 @@ def _parse_at_a_glance_table(
         if not line.strip().startswith("|"):
             break
         cells = split_pipe_row(line)
-        if cells == _AT_A_GLANCE_HEADER:
+        if _is_at_a_glance_header(cells):
             break
-        if len(cells) != len(_AT_A_GLANCE_HEADER):
+        if len(cells) != _AT_A_GLANCE_WIDTH:
             task_id = cells[1] if len(cells) > 1 else "<unknown>"
             violations.append(
                 f"At a Glance: noncanonical row for task {task_id} "
@@ -621,7 +632,7 @@ def _parse_at_a_glance_rows(
     lines = section.splitlines()
     header_indexes = [
         index for index, line in enumerate(lines)
-        if split_pipe_row(line) == _AT_A_GLANCE_HEADER
+        if _is_at_a_glance_header(split_pipe_row(line))
     ]
     if not header_indexes:
         return [], ["At a Glance: missing canonical 7-column table"]

package/runtime/python/okstra_ctl/stage_fix_carry.py

@@ -82,14 +82,33 @@ def derive_stage_fix_carry(
         prev_report_seq=_REPORT_RE.search(report.name).group(1),
         prev_head_commit=head,
         failed_verifiers=[str(row.get("verifier", "")) for row in failed],
-        blocking_findings=[
-            str(row.get("discrepancy") or row.get("verifier") or "")
-            for row in failed
-        ],
+        blocking_findings=_blocking_findings(data, failed),
         routing_recommendation=_routing_line(impl.get("routingRecommendation")),
     )
 
 
+def _blocking_findings(data: dict, failed: list[dict]) -> list[str]:
+    """이전 run 을 FAIL 로 만든 finding 목록.
+
+    정본은 리포트의 `humanSummary.blockers` 다 — 스키마가 요구하는 배열이고,
+    FAIL 사유가 정적 검토 finding(F-NNN)이든 Discrepancy 규칙이든 그 문장이 여기
+    있다. 검증자 행의 `discrepancy` 는 재실행 결과 차이를 적는 칸이라 FAIL 사유가
+    아닐 수 있다. 실측(2026-09-22, jobs dev-10860 stage 1): Codex 의 FAIL 사유는
+    F-001~003 이었는데 캐리는 그 행의 VC-001 종료 코드 메모를 실었다.
+    blockers 가 비어 있는 옛 리포트만 검증자 행으로 대신한다.
+    """
+    summary = data.get("humanSummary")
+    blockers = summary.get("blockers") if isinstance(summary, dict) else None
+    if isinstance(blockers, list):
+        rows = [row.strip() for row in blockers if isinstance(row, str) and row.strip()]
+        if rows:
+            return rows
+    return [
+        str(row.get("discrepancy") or row.get("verifier") or "")
+        for row in failed
+    ]
+
+
 def _routing_line(value: object) -> str:
     """구조체 라우팅을 캐리 프롬프트에 실을 한 줄로 편다.