okstra 0.140.0 → 0.141.1

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

package/runtime/validators/validate_improvement_report.py

@@ -181,10 +181,13 @@ def _check_candidate_row(
     errors: list[str],
 ) -> None:
     """Items 2, 3, 4, 6, 7 — validate a single candidate row."""
-    if len(row) != 10:
-        errors.append(f"row {idx} has {len(row)} columns, expected 10")
+    if len(row) != 11:
+        errors.append(f"row {idx} has {len(row)} columns, expected 11")
         return
-    cand_id, lens_cell, _title, scope, _sev, _eff, consensus, source_workers, next_phase, _evidence = row
+    (
+        cand_id, lens_cell, _title, scope, _sev, _eff,
+        consensus, source_workers, next_phase, expected_after, _evidence,
+    ) = row
 
     if not _CAND_ID_RE.match(cand_id):
         errors.append(f"row {idx}: Cand ID '{cand_id}' must match I-NNN")
@@ -209,6 +212,15 @@ def _check_candidate_row(
     if next_phase not in _NEXT_PHASES:
         errors.append(f"row {idx}: Recommended next-phase '{next_phase}' must be one of {_NEXT_PHASES}")
 
+    # A candidate nobody can describe an observable change for is not a finding;
+    # it is a preference. Making this a cell rather than prose is what stops the
+    # candidate list from growing past what a downstream brief can pin.
+    if not expected_after.strip():
+        errors.append(
+            f"row {idx}: `Expected behavior after` is empty — state what becomes "
+            "observably different once this candidate is applied, or drop the row"
+        )
+
 
 def _check_candidate_rows(
     data_rows: list[list[str]],
@@ -233,7 +245,8 @@ def _check_candidates_table(
     header, *data = rows
     expected_columns = [
         "Cand ID", "Lens", "Title", "Scope", "Severity", "Effort",
-        "Consensus", "Source workers", "Recommended next-phase", "Evidence",
+        "Consensus", "Source workers", "Recommended next-phase",
+        "Expected behavior after", "Evidence",
     ]
     if header != expected_columns:
         errors.append(