okstra 0.139.0 → 0.141.0

package/runtime/validators/validate-run.py

@@ -44,6 +44,11 @@ from okstra_ctl.conformance import (  # noqa: E402
     validate_conformance_manifest,
 )
 from okstra_ctl.paths import RunRef  # noqa: E402
+from okstra_ctl.build_tools import (  # noqa: E402
+    command_invokes_build_tool,
+    resolve_build_tool_tokens,
+)
+from okstra_ctl.stage_citations import cited_stage_numbers  # noqa: E402
 from okstra_ctl.workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE  # noqa: E402
 from okstra_ctl.md_table import (  # noqa: E402
     is_separator_row as _is_markdown_separator,
@@ -55,8 +60,9 @@ from okstra_ctl.improvement_assignment import (  # noqa: E402
 )
 from okstra_ctl.worker_prompt_policy import GRILLING_LOG_HEADER  # noqa: E402
 from okstra_ctl.scope_provenance import (  # noqa: E402
+    brief_citation_problem,
+    brief_end_state_ids,
     brief_headings,
-    normalize_heading,
     parse_source,
     resolve_chain,
 )
@@ -2317,6 +2323,18 @@ def validate_final_report_data(
         _validate_implementation_planning_decision_drafts(data, failures)
         _validate_plan_body_gate_recompute(data, failures)
         _validate_gate_blocked_by(data, failures)
+        _validate_participating_analysers(data, failures)
+        _validate_self_fix_rewrite_scope(data, failures)
+        for warning in _detect_self_fix_recurrence(
+            (data.get("implementationPlanning") or {}).get("planBodyVerification") or {}
+        ):
+            print(f"validate-run: warning: {warning}", file=sys.stderr)
+        for warning in _detect_unmapped_incremental_fallback(data, report_path):
+            print(f"validate-run: warning: {warning}", file=sys.stderr)
+        for warning in _detect_missing_dependency_precondition(
+            data, _project_root_from_report(report_path)
+        ):
+            print(f"validate-run: warning: {warning}", file=sys.stderr)
         _validate_supersession_ledger(data, failures)
         _validate_self_fix_grouping(data, failures)
         _validate_clarification_evidence_note(data, failures)
@@ -2737,6 +2755,296 @@ def _gate_blocking_causes(pbv: dict, coverage_blockers: list[str]) -> set[str]:
     return causes
 
 
+_CHECKLIST_REF_RE = re.compile(r"VC-\d+")
+
+
+def _project_root_from_report(report_path: Path) -> Path:
+    """Walk out of `<project>/.okstra/tasks/.../reports/` to the project root."""
+    for parent in report_path.parents:
+        if parent.name == ".okstra":
+            return parent.parent
+    return report_path.parent
+
+
+def _detect_missing_dependency_precondition(
+    data: dict, project_root: Path
+) -> list[str]:
+    """A stage that runs the toolchain must point at a declared precondition.
+
+    The planning worktree installs no dependencies, so `yarn … test` cannot run
+    there. A plan that says nothing about it produces steps whose commands die
+    on `exit 127`, and the verification round then spends itself on a defect the
+    planner cannot fix by editing the plan.
+
+    The shape checked is the one an observed self-fix loop arrived at after two
+    rounds: one `phase: pre` checklist item declaring the install, referenced by
+    every stage that needs it. Only the reference is machine-checked — whether
+    the cited item genuinely covers dependencies is a semantic judgement left to
+    the §5.5.9 round, the same boundary the scope-provenance gate draws.
+    """
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        return []
+    tokens = resolve_build_tool_tokens(project_root)
+    if not tokens:
+        return []
+
+    checklist = {
+        str(row.get("id")): str(row.get("phase") or "")
+        for row in (planning.get("validationChecklist") or [])
+        if isinstance(row, dict) and row.get("id")
+    }
+
+    warnings: list[str] = []
+    for stage in planning.get("stages") or []:
+        if not isinstance(stage, dict):
+            continue
+        commands = [
+            str(step.get("command") or "")
+            for step in (stage.get("stepwiseExecution") or [])
+            if isinstance(step, dict)
+        ]
+        if not any(command_invokes_build_tool(c, tokens=tokens) for c in commands):
+            continue
+        refs = _CHECKLIST_REF_RE.findall(str(stage.get("stageValidation") or ""))
+        if not refs:
+            warnings.append(
+                f"Stage {stage.get('stage')} runs the project toolchain but its "
+                "Stage Validation cites no `VC-NNN` precondition. The planning "
+                "worktree has no dependencies installed, so declare the install "
+                "once as a `phase: pre` Validation Checklist item and reference "
+                "it here."
+            )
+            continue
+        if not any(checklist.get(ref) == "pre" for ref in refs):
+            cited = ", ".join(sorted(set(refs)))
+            warnings.append(
+                f"Stage {stage.get('stage')} runs the project toolchain and cites "
+                f"{cited}, but none of those is a `phase: pre` Validation "
+                "Checklist item — a precondition verified after the fact is not a "
+                "precondition."
+            )
+    return warnings
+
+
+_UNMAPPED_FALLBACK_REASON = "no impacted stages resolved"
+
+
+def _prior_planning_data(report_path: Path) -> dict | None:
+    """The newest implementation-planning data.json preceding *report_path*."""
+    match = re.search(r"-(\d+)\.md$", report_path.name)
+    if not match:
+        return None
+    current_seq = int(match.group(1))
+    candidates = sorted(
+        (
+            path
+            for path in report_path.parent.glob(
+                "final-report-implementation-planning-*.data.json"
+            )
+            if (m := re.search(r"-(\d+)\.data\.json$", path.name))
+            and int(m.group(1)) < current_seq
+        ),
+        key=lambda p: p.name,
+    )
+    for path in reversed(candidates):
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        if isinstance(payload, dict):
+            return payload
+    return None
+
+
+def _detect_unmapped_incremental_fallback(
+    data: dict, report_path: Path
+) -> list[str]:
+    """A re-run that fell back to full while the prior report could have mapped it.
+
+    Both "the answer restructures the plan" and "no stage could be resolved"
+    return `mode: full`, and only the second is a missed narrowing. The lead
+    declares the first through `--full-reason`, so the reason prefix separates
+    them; this reports the second only when the trace would have succeeded.
+
+    Advisory: a lead that never passed `--full-reason` produces the fallback
+    reason for both cases, so failing here would punish runs written before the
+    flag existed.
+    """
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        return []
+    decision = planning.get("incrementalDecision")
+    if not isinstance(decision, dict) or decision.get("mode") != "full":
+        return []
+    if _UNMAPPED_FALLBACK_REASON not in str(decision.get("reason") or ""):
+        return []
+
+    answered = _answered_clarification_ids(data)
+    if not answered:
+        return []
+    prior = _prior_planning_data(report_path)
+    if prior is None:
+        return []
+
+    try:
+        from okstra_ctl.incremental_scope import clarification_impacted_stages
+
+        stages = clarification_impacted_stages(prior, set(answered))
+    except (ImportError, ValueError):
+        return []
+    if not stages:
+        return []
+    return [
+        "incrementalDecision fell back to full for lack of a resolved stage, but "
+        f"the prior report maps {', '.join(sorted(answered))} to stage(s) "
+        f"{', '.join(str(s) for s in sorted(stages))}. Pass the answered ids "
+        "through `--answered-clarifications` so the re-run narrows, or declare "
+        "the structural change with `--full-reason` when full is the judgement."
+    ]
+
+
+_SELF_FIX_NOTE_ROUND_RE = re.compile(r"self-fixed in round\s*(\d+)", re.IGNORECASE)
+
+
+def _items_resolved_in_round(plan_items: object, round_number: int) -> set[str]:
+    resolved: set[str] = set()
+    for item in plan_items if isinstance(plan_items, list) else []:
+        if not isinstance(item, dict):
+            continue
+        match = _SELF_FIX_NOTE_ROUND_RE.search(str(item.get("selfFixNote") or ""))
+        if match and int(match.group(1)) == round_number:
+            resolved.add(str(item.get("id")))
+    return resolved
+
+
+def _detect_self_fix_recurrence(pbv: dict) -> list[str]:
+    """Rounds that re-target ground the previous round already worked, unresolved.
+
+    `no-progress` counts resolutions, which a round can claim while its
+    correction introduces the next round's defect — the observed shape was two
+    rounds spent on one identical seven-item set. Repeating the previous
+    round's *unresolved* remainder is the earlier signal.
+
+    Advisory only. Narrowing onto what the last round genuinely left open is
+    legitimate progress, and the rule separating that from re-digging the same
+    hole is not settled (design D-1), so this reports rather than fails.
+    """
+    groups = pbv.get("selfFixGroups") if isinstance(pbv, dict) else None
+    if not isinstance(groups, list):
+        return []
+    by_round: dict[int, set[str]] = {}
+    for group in groups:
+        if not isinstance(group, dict) or not isinstance(group.get("round"), int):
+            continue
+        ids = {str(i) for i in group.get("itemIds") or []}
+        by_round.setdefault(group["round"], set()).update(ids)
+
+    warnings: list[str] = []
+    plan_items = pbv.get("planItems")
+    for round_number in sorted(by_round)[1:]:
+        previous = by_round.get(round_number - 1)
+        if not previous:
+            continue
+        unresolved = previous - _items_resolved_in_round(plan_items, round_number - 1)
+        current = by_round[round_number]
+        if current and current <= unresolved:
+            warnings.append(
+                f"self-fix round {round_number} re-targets only items round "
+                f"{round_number - 1} left unresolved ({', '.join(sorted(current))}) "
+                "— the previous round's correction did not move this cause. "
+                "Consider exiting with `cause-group-recurrence` instead of "
+                "spending the remaining budget on the same ground."
+            )
+    return warnings
+
+
+def _validate_self_fix_rewrite_scope(data: dict, failures: list[str]) -> None:
+    """Keep the rewrite-reach measurement internally consistent.
+
+    No threshold is applied: the contract calls a self-fix round a targeted
+    correction rather than a full regeneration, but how far a correct one
+    reaches is not yet known from enough runs to name a number. What is
+    checkable now is that the narrower figure sits inside the wider one — an
+    outside-scope path missing from the rewritten set makes the reach read
+    smaller than it was.
+    """
+    groups = (
+        (data.get("implementationPlanning") or {})
+        .get("planBodyVerification") or {}
+    ).get("selfFixGroups")
+    for group in groups if isinstance(groups, list) else []:
+        if not isinstance(group, dict):
+            continue
+        outside = group.get("outsideScopePaths")
+        if not isinstance(outside, list) or not outside:
+            continue
+        rewritten = group.get("rewrittenPaths")
+        if not isinstance(rewritten, list):
+            failures.append(
+                "final-report data.json: selfFixGroups round "
+                f"{group.get('round')} lists outsideScopePaths without "
+                "rewrittenPaths — the wider set is what the narrower one is a "
+                "subset of, so it cannot be omitted."
+            )
+            continue
+        for path in outside:
+            if path not in rewritten:
+                failures.append(
+                    "final-report data.json: selfFixGroups round "
+                    f"{group.get('round')} lists `{path}` as outside-scope but "
+                    "not among rewrittenPaths — a path the round touched belongs "
+                    "in both."
+                )
+
+
+def _validate_participating_analysers(data: dict, failures: list[str]) -> None:
+    """The gate's own arithmetic base, checked against the votes it ran on.
+
+    A majority over two votes and a majority over three are different claims,
+    and a shrunken roster loosens the gate silently: with two analysers,
+    1-AGREE/1-DISAGREE is a tie, so it never reaches `majority-disagree`. The
+    field only reports; the arithmetic is unchanged. It is recomputable from
+    the recorded verdicts, so a figure the table denies is a defect.
+    """
+    pbv = ((data.get("implementationPlanning") or {}).get("planBodyVerification") or {})
+    declared = pbv.get("participatingAnalysers")
+    if not isinstance(declared, dict):
+        return
+
+    rostered = declared.get("rostered")
+    voting = declared.get("voting")
+    if not isinstance(rostered, int) or not isinstance(voting, int):
+        failures.append(
+            "final-report data.json: planBodyVerification.participatingAnalysers "
+            "needs integer `rostered` and `voting`."
+        )
+        return
+    if voting > rostered:
+        failures.append(
+            "final-report data.json: planBodyVerification.participatingAnalysers "
+            f"claims {voting} voting of {rostered} rostered — more workers voted "
+            "than were on the roster."
+        )
+        return
+
+    observed = {
+        str(v.get("worker"))
+        for item in (pbv.get("planItems") or [])
+        if isinstance(item, dict)
+        for v in (item.get("verdicts") or [])
+        if isinstance(v, dict) and str(v.get("verdict") or "") != "verification-error"
+    }
+    if observed and voting != len(observed):
+        failures.append(
+            "final-report data.json: planBodyVerification.participatingAnalysers "
+            f"declares {voting} voting analyser(s) but the recorded verdicts carry "
+            f"{len(observed)} ({', '.join(sorted(observed))}). A worker whose "
+            "dispatch returned no result is excluded from the gate arithmetic and "
+            "must not be counted here either."
+        )
+
+
 def _validate_gate_blocked_by(data: dict, failures: list[str]) -> None:
     """The gate value names an *outcome*; `gateBlockedBy` names the *cause*.
 
@@ -4456,6 +4764,89 @@ def _validate_requirement_coverage_covered_by(data: dict, failures: list[str]) -
             )
 
 
+# The phases that read the run's brief. Resolving the brief outside this set
+# would fire the missing-brief warning on runs (implementation,
+# final-verification, release-handoff) that never consult one.
+_BRIEF_DERIVED_PHASES = frozenset(
+    {
+        "requirements-discovery",
+        "error-analysis",
+        "implementation-planning",
+        "improvement-discovery",
+    }
+)
+# The subset that maps the brief's end state. improvement-discovery is absent
+# on purpose: its report is free-form markdown outside the data.json schema, so
+# it has nowhere to carry endStateCoverage.
+_END_STATE_PHASES = frozenset(
+    {"requirements-discovery", "error-analysis", "implementation-planning"}
+)
+
+
+def _validate_end_state_coverage(
+    data: dict, brief_path: Path, failures: list[str]
+) -> None:
+    """Every end-state id the brief pinned is accounted for exactly once.
+
+    This is the lower bound the phase contracts previously lacked: a phase could
+    quietly drop a reporter requirement and still produce a clean report. The
+    gate does not judge whether the mapping is true — that is the Phase 5.5
+    round's job — but it makes an omission an explicit, attributable statement
+    rather than a silence.
+
+    Legacy briefs declare no ids, so the gate self-disables for them instead of
+    wedging runs authored before the contract existed.
+    """
+    declared = brief_end_state_ids(brief_path)
+    if not declared:
+        return
+
+    rows = [r for r in (data.get("endStateCoverage") or []) if isinstance(r, dict)]
+    seen: dict[str, int] = {}
+    for row in rows:
+        row_id = str(row.get("id") or "").strip()
+
+        # Counting only declared ids keeps one mistake to one failure: an
+        # undeclared id repeated twice is one "not declared" per row, not that
+        # plus a duplicate report about an id the brief never had.
+        if row_id not in declared:
+            failures.append(
+                f"final-report data.json: endStateCoverage cites {row_id!r}, which "
+                "is not declared by this run's brief. Map only ids the reporter "
+                "pinned."
+            )
+            continue
+        seen[row_id] = seen.get(row_id, 0) + 1
+
+        disposition = str(row.get("disposition") or "").strip()
+        if disposition == "addressed" and not str(row.get("coveredBy") or "").strip():
+            failures.append(
+                f"final-report data.json: endStateCoverage `{row_id}` is `addressed` "
+                "but names no `coveredBy` anchor. State which deliverable of this "
+                "phase accounts for it."
+            )
+        if disposition != "addressed" and not str(row.get("rationale") or "").strip():
+            failures.append(
+                f"final-report data.json: endStateCoverage `{row_id}` is "
+                f"`{disposition or '(empty)'}` but records no `rationale`. Dropping a "
+                "reporter requirement is allowed; dropping it silently is not."
+            )
+
+    for row_id, count in seen.items():
+        if count > 1:
+            failures.append(
+                f"final-report data.json: endStateCoverage maps `{row_id}` more than "
+                f"once ({count} rows). One id, one disposition."
+            )
+
+    for missing in sorted(declared - seen.keys()):
+        failures.append(
+            f"final-report data.json: brief end-state `{missing}` has no "
+            "endStateCoverage row. Every pinned id needs a disposition, including "
+            "`not-applicable` with a rationale."
+        )
+
+
 def _validate_requirement_provenance(
     data: dict, brief_path: Path, failures: list[str]
 ) -> None:
@@ -4478,15 +4869,15 @@ def _validate_requirement_provenance(
         for r in rows
     }
     headings = brief_headings(brief_path)
+    end_state = brief_end_state_ids(brief_path)
 
     for rid, ref in refs.items():
-        if ref.kind == "brief" and headings:
-            if normalize_heading(ref.value) not in headings:
-                failures.append(
-                    f"final-report data.json: requirementCoverage `{rid}` cites brief "
-                    f"heading `{ref.value}` which does not exist in the brief. A "
-                    "requirement must trace to a line the reporter actually wrote."
-                )
+        problem = brief_citation_problem(ref, headings, end_state)
+        if problem:
+            failures.append(
+                f"final-report data.json: requirementCoverage `{rid}` {problem}. A "
+                "requirement must trace to a line the reporter actually wrote."
+            )
 
     for rid, verdict in resolve_chain(refs).items():
         if verdict != "ok":
@@ -4497,47 +4888,13 @@ def _validate_requirement_provenance(
             )
 
 
-_CITED_STAGE_RANGE = r"(?:[-–]|\bto\b|\bthrough\b)"
-_CITED_STAGE_ITEM = rf"\d+(?:\s*{_CITED_STAGE_RANGE}\s*\d+)?"
-# `, and` / `, &` is one separator, not a separator followed by a stray word:
-# `Stages 1, 2, and 3` is the idiomatic plural and must not orphan stage 3.
-_CITED_STAGE_SEP = r"(?:,\s*(?:and|&)?|and|&)"
-_CITED_STAGE_LIST_RE = re.compile(
-    rf"\bstages?[ \t]*({_CITED_STAGE_ITEM}(?:\s*{_CITED_STAGE_SEP}\s*{_CITED_STAGE_ITEM})*)",
-    re.IGNORECASE,
-)
-_CITED_STAGE_ITEM_RE = re.compile(
-    rf"(\d+)(?:\s*{_CITED_STAGE_RANGE}\s*(\d+))?", re.IGNORECASE
-)
-_CITED_STAGE_RANGE_MAX_SPAN = 64
-
-
-def _cited_stage_numbers(covered_by: str) -> set[int]:
-    """Stage numbers a `coveredBy` cell cites, in every prose form a planner writes.
-
-    Deliberately not `_COVERED_BY_STAGE_REF_RE`: the two directions disagree on
-    what "no match" means — forward treats it as nothing to verify and passes,
-    reverse treats it as nothing cited and orphans every stage — so the reverse
-    reader must cover `Stages 1, 2`, `Stages 1-3` and `Stage 1 and 2` too.
-    Numbers stay anchored to a word-initial `stage`/`stages` token on the same
-    line; harvesting bare numbers — or letting the anchor reach across a line
-    break, or match the tail of `Substage`/`Backstage` — would let any prose,
-    including a row disclaiming every stage, justify any stage.
-    """
-    cited: set[int] = set()
-    for span in _CITED_STAGE_LIST_RE.finditer(covered_by):
-        for item in _CITED_STAGE_ITEM_RE.finditer(span.group(1)):
-            start = int(item.group(1))
-            cited.add(start)
-            if item.group(2) is None:
-                continue
-            end = int(item.group(2))
-            cited.add(end)
-            # A reversed or absurdly wide range is a typo, not a citation of
-            # everything between its endpoints.
-            if 0 <= end - start <= _CITED_STAGE_RANGE_MAX_SPAN:
-                cited.update(range(start, end))
-    return cited
+# Deliberately not `_COVERED_BY_STAGE_REF_RE`: the two directions disagree on
+# what "no match" means — forward treats it as nothing to verify and passes,
+# reverse treats it as nothing cited and orphans every stage — so the reverse
+# reader must cover `Stages 1, 2`, `Stages 1-3` and `Stage 1 and 2` too. The
+# grammar is shared with the incremental-scope back-trace, which resolves the
+# same citations in the opposite direction.
+_cited_stage_numbers = cited_stage_numbers
 
 
 # Statuses under which a row asserts the plan does work for the requirement.
@@ -4843,6 +5200,34 @@ def validate_phase_boundary(
         _append_stage_structure_failures(content, failures)
 
 
+def _brief_path_from_manifest(task_manifest: dict, project_root: Path) -> Path:
+    """This run's brief, or a non-existent path when the manifest names none.
+
+    Readers of the returned path all degrade to "no brief information" on a
+    missing file, so an absent brief disables brief-derived gates rather than
+    failing the run.
+
+    That degrade is why a named-but-missing brief warns: it is indistinguishable
+    from a legacy brief at every reader (both yield an empty id set), so a
+    new-format run whose brief path rotted would pass every brief-derived gate
+    without anyone seeing it happen. Warning rather than failing keeps the
+    existing contract — an absent brief is not by itself a run failure.
+    """
+    relative = str(task_manifest.get("taskBriefPath") or "").strip()
+    if not relative:
+        return project_root / "__no-brief__"
+    resolved = (project_root / relative).resolve()
+    if not resolved.is_file():
+        print(
+            f"validate-run: warning: task manifest names taskBriefPath "
+            f"{relative!r} but no file exists there — every brief-derived check "
+            "(end-state coverage, requirement provenance, fan-out provenance) "
+            "is skipped for this run",
+            file=sys.stderr,
+        )
+    return resolved
+
+
 def _parse_brief_frontmatter(brief_path: Path) -> dict:
     """Parse YAML frontmatter from a brief file into a flat dict.
 
@@ -5810,35 +6195,22 @@ def main() -> int:
         )
         for warning in conformance_warnings:
             print(f"validate-run: warning: {warning}", file=sys.stderr)
-    if task_type == "implementation-planning":
-        _validate_planning_conformance_declared(report_path, failures)
-        brief_relative = str(task_manifest.get("taskBriefPath") or "").strip()
-        planning_brief = (
-            (project_root / brief_relative).resolve()
-            if brief_relative
-            else project_root / "__no-brief__"  # absent path → brief_headings returns set()
-        )
-        planning_data = _load_final_report_data(report_path)
-        _validate_requirement_provenance(planning_data, planning_brief, failures)
-        _validate_stage_has_requirement(planning_data, failures)
-    if task_type == "improvement-discovery":
-        brief_relative = str(task_manifest.get("taskBriefPath") or "").strip()
-        brief_path = (
-            (project_root / brief_relative).resolve()
-            if brief_relative
-            else project_root / "__no-brief__"  # absent path → _parse_brief_frontmatter returns {}
-        )
-        run_dir = report_path.parent.parent
-        _validate_improvement_discovery(report_path, run_dir, brief_path, failures)
-    if task_type == "requirements-discovery":
-        brief_relative = str(task_manifest.get("taskBriefPath") or "").strip()
-        brief_path = (
-            (project_root / brief_relative).resolve()
-            if brief_relative
-            else project_root / "__no-brief__"  # absent path → brief_headings returns set()
-        )
-        run_dir = report_path.parent.parent
-        _validate_requirements_discovery_fanout(run_dir, failures, brief_path)
+    if task_type in _BRIEF_DERIVED_PHASES:
+        brief_path = _brief_path_from_manifest(task_manifest, project_root)
+        if task_type in _END_STATE_PHASES:
+            if task_type == "implementation-planning":
+                _validate_planning_conformance_declared(report_path, failures)
+            report_data = _load_final_report_data(report_path)
+            _validate_end_state_coverage(report_data, brief_path, failures)
+            if task_type == "implementation-planning":
+                _validate_requirement_provenance(report_data, brief_path, failures)
+                _validate_stage_has_requirement(report_data, failures)
+        if task_type == "improvement-discovery":
+            run_dir = report_path.parent.parent
+            _validate_improvement_discovery(report_path, run_dir, brief_path, failures)
+        if task_type == "requirements-discovery":
+            run_dir = report_path.parent.parent
+            _validate_requirements_discovery_fanout(run_dir, failures, brief_path)
     # Phase-agnostic: convergence runs in every finding-producing phase.
     _validate_convergence_states(report_path.parent.parent, failures)
     _validate_convergence_rounds_match_manifest(

package/runtime/validators/validate_fanout.py

@@ -18,8 +18,9 @@ for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "
 from okstra_ctl.work_categories import WORK_CATEGORIES  # noqa: E402
 from okstra_ctl.fanout import topological_order, CycleError  # noqa: E402
 from okstra_ctl.scope_provenance import (  # noqa: E402
+    brief_citation_problem,
+    brief_end_state_ids,
     brief_headings,
-    normalize_heading,
     parse_source,
 )
 
@@ -37,7 +38,11 @@ _PROVENANCE_BULLET_RE = re.compile(r"^\s*[-*]\s+(?P<src>.+?)\s*$", re.MULTILINE)
 
 
 def _check_provenance(
-    pkt_name: str, text: str, errors: list[str], headings: set[str]
+    pkt_name: str,
+    text: str,
+    errors: list[str],
+    headings: set[str],
+    end_state: set[str],
 ) -> None:
     """A fan-out unit must cite the brief line that demanded it.
 
@@ -47,6 +52,8 @@ def _check_provenance(
 
     `headings` empty means the brief was unavailable — the grammar still
     applies, only the heading-existence half degrades to unverifiable.
+    `end_state` empty means the brief predates the end-state sections, so the
+    older heading form is still the admissible one.
     """
     section = _PROVENANCE_SECTION_RE.search(text)
     if not section:
@@ -61,7 +68,7 @@ def _check_provenance(
     if not bullets:
         errors.append(
             f"{pkt_name}: `## Requirement Provenance` is empty — cite at least one "
-            "`brief:<heading>` or `contract:<rule>`"
+            "`brief:EB-001` (or the legacy `brief:<heading>`) or `contract:<rule>`"
         )
         return
     for raw in bullets:
@@ -69,14 +76,15 @@ def _check_provenance(
         if ref.kind not in ("brief", "contract"):
             errors.append(
                 f"{pkt_name}: unrecognized provenance `{raw}` — a fan-out unit's "
-                "source must be `brief:<heading>` or `contract:<rule>`"
+                "source must be `brief:EB-001` (or the legacy `brief:<heading>`) "
+                "or `contract:<rule>`"
             )
-        elif ref.kind == "brief" and headings:
-            if normalize_heading(ref.value) not in headings:
+        elif ref.kind == "brief":
+            problem = brief_citation_problem(ref, headings, end_state)
+            if problem:
                 errors.append(
-                    f"{pkt_name}: cites brief heading `{ref.value}` which does not "
-                    "exist in the brief. A fan-out unit becomes the brief for a whole "
-                    "downstream task — it must trace to a line the reporter wrote."
+                    f"{pkt_name}: {problem}. A fan-out unit becomes the brief for a "
+                    "whole downstream task — it must trace to a line the reporter wrote."
                 )
 
 
@@ -117,13 +125,14 @@ def validate_fanout(run_dir: Path, brief_path: Path | None = None) -> Validation
         return ValidationResult(ok=True)
 
     headings = brief_headings(brief_path) if brief_path is not None else set()
+    end_state = brief_end_state_ids(brief_path) if brief_path is not None else set()
 
     errors: list[str] = []
     units: dict[str, list[str]] = {}
     for pkt in sorted(fo.glob("unit-*.md")):
         text = pkt.read_text(encoding="utf-8")
         fm = _frontmatter(text)
-        _check_provenance(pkt.name, text, errors, headings)
+        _check_provenance(pkt.name, text, errors, headings, end_state)
         uid = fm.get("unit-id", "")
         if uid != pkt.stem:
             errors.append(f"{pkt.name}: unit-id {uid!r} != filename stem {pkt.stem!r}")