okstra 0.189.2 → 0.189.4

package/runtime/validators/validate-run.py

@@ -3084,6 +3084,9 @@ def validate_final_report_data(
     failures.extend(f"{task_type}: {error}" for error in analysis_result.errors)
 
     _validate_no_opaque_id_references(data, failures)
+    _validate_no_null_literals_in_prose(data, failures)
+    for warning in _unbridged_worker_finding_refs(data):
+        print(f"validate-run: warning: {warning}", file=sys.stderr)
     # Phase-agnostic: the coverage critic runs in every finding-producing phase.
     _validate_unverified_critic_gaps_recorded(data, failures)
     # Called here rather than from a task-type branch: four profiles raise
@@ -3093,6 +3096,9 @@ def validate_final_report_data(
 
     task_type = (data.get("header") or {}).get("taskType")
     _validate_verifier_fail_blocks_verdict(data, failures)
+    _validate_verifier_discrepancy_names_checklist_phase(
+        data, report_path, project_root, failures
+    )
     if task_type == "implementation-option-selection":
         selection = data.get("implementationOptionSelection") or {}
         validation_root = project_root or report_path.parent
@@ -3159,7 +3165,9 @@ def validate_final_report_data(
         carried = _carried_decision_map(
             manifest, project_root=project_root, report_path=report_path
         )
-        _validate_supersession_ledger(data, failures, carried=carried)
+        _validate_supersession_ledger(
+            data, failures, carried=carried, new_plan=selected_direction_contract
+        )
         _validate_approval_clarification_backtrace(data, failures)
         _validate_rerun_guidance(data, failures)
         _validate_approval_guidance(data, failures)
@@ -3239,6 +3247,97 @@ def _validate_no_opaque_id_references(data: dict, failures: list[str]) -> None:
             )
 
 
+# A stringified null is not prose. Lowercase `none` is a token the clarification
+# option contract uses on purpose ("reverses nothing"), so only the capitalised
+# and language-native spellings count — 2026-09-05 audit: `"None"` in 16
+# trade-off cells and 2 option fields across the shipped reports.
+_NULL_LITERALS = frozenset({"None", "null", "undefined", "NaN"})
+_FINDING_REF_RE = re.compile(r"^F-\d{3,}$")
+# Citation lists the human page renders as links or plain text.
+_CITATION_LIST_KEYS = ("evidenceRefs", "supportingEvidence", "falsifyingEvidenceChecked")
+
+
+def _prose_pointers(node: object, key: str = "", pointer: str = "") -> list[tuple[str, str]]:
+    """(JSON pointer, value) for every string under a reader-facing prose key."""
+    from okstra_ctl.report_translation import PROSE_KEYS
+
+    out: list[tuple[str, str]] = []
+    if isinstance(node, dict):
+        for child_key, value in node.items():
+            out.extend(_prose_pointers(value, str(child_key), f"{pointer}/{child_key}"))
+    elif isinstance(node, list):
+        for index, value in enumerate(node):
+            out.extend(_prose_pointers(value, key, f"{pointer}/{index}"))
+    elif isinstance(node, str) and key in PROSE_KEYS:
+        out.append((pointer, node))
+    return out
+
+
+def _validate_no_null_literals_in_prose(data: dict, failures: list[str]) -> None:
+    """A prose cell holding `None`/`null`/`undefined` is a serialisation
+    artefact the page prints verbatim — nlpvibe planning-009…014 showed
+    `None` under Test cost and Rollout cost. An empty value is spelled by
+    omitting the field or leaving it empty, never by naming the language's
+    null."""
+    offenders = [
+        f"{pointer} = {value.strip()!r}"
+        for pointer, value in _prose_pointers(data)
+        if value.strip() in _NULL_LITERALS
+    ]
+    if offenders:
+        failures.append(
+            "final-report data.json: prose field(s) hold a null literal — "
+            + ", ".join(offenders[:8])
+            + (f" (+{len(offenders) - 8} more)" if len(offenders) > 8 else "")
+            + ". Leave the field empty or omit it; the page prints the literal as text."
+        )
+
+
+def _unbridged_worker_finding_refs(data: dict) -> list[str]:
+    """Advisory: citation lists naming a worker's own finding number (`F-NNN`)
+    that no `evidence.primary[].sourceItems` entry carries.
+
+    The page links a bare `F-NNN` only when exactly one promoted evidence row
+    cites it as `<worker>:F-NNN` (`report_html/common.py`
+    `worker_finding_links`); every other one is dead text. The 2026-09-05
+    audit found 22 to 156 such citations per shipped report, so this stays a
+    warning until the writer contracts have caught up — cite the promoted
+    `E-` row, or add the finding to that row's `sourceItems`.
+    """
+    bridged: set[str] = set()
+    for row in ((data.get("evidence") or {}).get("primary") or []):
+        if not isinstance(row, dict):
+            continue
+        for item in row.get("sourceItems") or []:
+            for token in re.findall(r"\b(F-\d{3,})\b", str(item)):
+                bridged.add(token)
+    unbridged: dict[str, list[str]] = {}
+
+    def walk(node: object, key: str = "", pointer: str = "") -> None:
+        if isinstance(node, dict):
+            for child_key, value in node.items():
+                walk(value, str(child_key), f"{pointer}/{child_key}")
+        elif isinstance(node, list):
+            if key in _CITATION_LIST_KEYS:
+                for value in node:
+                    if isinstance(value, str) and _FINDING_REF_RE.match(value.strip()) and value.strip() not in bridged:
+                        unbridged.setdefault(value.strip(), []).append(pointer)
+            else:
+                for index, value in enumerate(node):
+                    walk(value, key, f"{pointer}/{index}")
+
+    walk(data)
+    if not unbridged:
+        return []
+    listed = ", ".join(f"{ref} ({len(where)}×)" for ref, where in sorted(unbridged.items())[:10])
+    return [
+        f"citation lists name worker finding number(s) no evidence.primary "
+        f"sourceItems entry carries — {listed}"
+        + (f" (+{len(unbridged) - 10} more)" if len(unbridged) > 10 else "")
+        + "; cite the promoted E- row or add `<worker>:F-NNN` to its sourceItems"
+    ]
+
+
 def _validate_implementation_planning_cross_project(data: dict, failures: list[str]) -> None:
     """타 프로젝트 의존을 DM 행(`kind == 'cross-project'`)으로 선언했다면
     `crossProjectDependencies` 에 `direction == 'upstream-precondition'` 행이
@@ -4791,11 +4890,22 @@ def _answered_clarification_ids(data: dict) -> list[str]:
 
 
 def _validate_supersession_ledger(
-    data: dict, failures: list[str], *, carried: dict | None = None,
+    data: dict,
+    failures: list[str],
+    *,
+    carried: dict | None = None,
+    new_plan: bool = False,
 ) -> None:
     """Incorporating an answer means retiring what it invalidates, not only
     adding what it decides.
 
+    `new_plan` marks a plan built from a selected direction. Prepare seeds
+    that run's ledger with every answer the option-selection record carried
+    (2026-09-05), and a first plan has no earlier statement those answers
+    could retire — an entry per carried row would be `no-dependent-statement`
+    by construction. Those ids are exempt; answers the plan itself raised and
+    settled still need their entry.
+
     A re-run reconciles each `C-*` row's `Status` and writes the new decision
     into the plan, but nothing required it to remove the sentences the answer
     made false. The result is one plan carrying two opposite instructions for
@@ -4809,7 +4919,10 @@ def _validate_supersession_ledger(
     if not isinstance(ip, dict):
         return
     answered = set(_answered_clarification_ids(data))
-    answered.update((carried or {}).keys())
+    if new_plan:
+        answered.difference_update((carried or {}).keys())
+    else:
+        answered.update((carried or {}).keys())
     if not answered:
         return
     ledger = [e for e in (ip.get("supersessionLedger") or []) if isinstance(e, dict)]
@@ -5149,6 +5262,110 @@ def _validate_verifier_discrepancy_is_not_passed(
             )
 
 
+_CHECKLIST_ID_RE = re.compile(r"\bVC-\d{3,}\b")
+_CHECKLIST_PHASE_RE = re.compile(r"\bphase\W{0,3}(pre|mid|post)\b", re.IGNORECASE)
+
+
+def _approved_plan_record(
+    data: dict, report_path: Path, project_root: Path | None
+) -> dict | None:
+    """이 구현 리포트가 가리키는 승인 계획 레코드(data.json). 못 찾으면 None.
+
+    `approvedPlanReference.planFile` 은 실물에서 프로젝트 상대(`.okstra/tasks/...`)로,
+    fixture 에서 태스크 상대(`runs/implementation-planning/...`)로 나오고 확장자는
+    `.md` 와 `.data.json` 둘 다 쓰인다. 어느 형태든 레코드로 되짚고, 없으면 None 을
+    돌려 호출자가 판정을 건너뛰게 한다 — 계획 부재는 다른 검사의 몫이고, 없는
+    파일을 여기서 위반으로 세지 않는다.
+    """
+    implementation = data.get("implementation")
+    if not isinstance(implementation, dict):
+        return None
+    reference = implementation.get("approvedPlanReference")
+    plan_file = reference.get("planFile") if isinstance(reference, dict) else None
+    if not isinstance(plan_file, str) or not plan_file.strip():
+        return None
+    from okstra_ctl.final_report_paths import final_report_data_path
+
+    candidate = Path(plan_file.strip())
+    if candidate.name.endswith(".md"):
+        candidate = final_report_data_path(candidate)
+    task_root = next(
+        (parent.parent for parent in report_path.parents if parent.name == "runs"),
+        None,
+    )
+    roots: list[Path | None] = (
+        [None] if candidate.is_absolute()
+        else [root for root in (project_root, task_root) if root is not None]
+    )
+    for root in roots:
+        path = candidate if root is None else root / candidate
+        if not path.is_file():
+            continue
+        try:
+            loaded = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return None
+        return loaded if isinstance(loaded, dict) else None
+    return None
+
+
+def _validate_verifier_discrepancy_names_checklist_phase(
+    data: dict,
+    report_path: Path,
+    project_root: Path | None,
+    failures: list[str],
+) -> None:
+    """계획 `validationChecklist` 행을 근거로 적은 divergence 는 그 행의 `phase` 를 인용한다.
+
+    2026-09-05 실측(fontsninja-v3-site dev-10626 stage-1): codex 검증자가 `VC-003` 의
+    `git diff --name-only` 가 커밋 뒤 빈 출력이라며 FAIL 을 냈다. 그 행은 계획 레코드에
+    `phase: mid` — 편집과 커밋 사이의 체크포인트 — 로 선언돼 있어, 커밋 뒤의 빈 출력은
+    계획의 단계 순서 그 자체였다. 수렴에서 제기자 본인이 반대 읽기에 AGREE 했지만 FAIL
+    행은 남아 stage 가 `failed` 로 갔고, 리드도 그 주장을 열어 보지 않고 라우팅에 옮겼다.
+    `pre`/`mid`/`post` 는 행이 언제 성립하는지를 정하므로, 행을 인용하는 문장이 그 값을
+    함께 적어야 한다 — 읽지 않은 행을 근거로 쓰는 문장은 그러면 쓸 수 없다.
+
+    행에 `phase` 가 없거나 계획 레코드를 못 찾으면 판정하지 않는다.
+    """
+    plan = _approved_plan_record(data, report_path, project_root)
+    if plan is None:
+        return
+    planning = plan.get("implementationPlanning")
+    rows = planning.get("validationChecklist") if isinstance(planning, dict) else None
+    phases = {
+        str(row["id"]): str(row["phase"]).strip().lower()
+        for row in (rows if isinstance(rows, list) else [])
+        if isinstance(row, dict)
+        and isinstance(row.get("id"), str)
+        and isinstance(row.get("phase"), str)
+    }
+    if not phases:
+        return
+    for who, row in _verifier_rows(data):
+        discrepancy = row.get("discrepancy")
+        if not isinstance(discrepancy, str) or not discrepancy.strip():
+            continue
+        cited = sorted(set(_CHECKLIST_ID_RE.findall(discrepancy)) & set(phases))
+        if not cited:
+            continue
+        named = {
+            match.group(1).lower()
+            for match in _CHECKLIST_PHASE_RE.finditer(discrepancy)
+        }
+        missing = [
+            f"{row_id} (phase: {phases[row_id]})"
+            for row_id in cited
+            if phases[row_id] not in named
+        ]
+        if missing:
+            failures.append(
+                f"verifier-discrepancy: {who} 가 계획 체크리스트 행을 근거로 divergence 를 "
+                f"적었지만 그 행의 phase 를 인용하지 않았다 — {', '.join(missing)}. "
+                "`pre`/`mid`/`post` 는 행이 언제 성립하는지를 정하므로 인용 문장에 "
+                "`VC-NNN (phase: <값>)` 으로 적는다 (`_implementation-verifier.md` § Tier 1)."
+            )
+
+
 def _verifier_rows(data: dict):
     """(표시 이름, verifierResults 행) 쌍."""
     implementation = data.get("implementation")