okstra 0.139.0 → 0.141.0

package/runtime/validators/validate-brief.py

@@ -37,6 +37,11 @@ Checks performed per brief file:
     columns and relation/direction values from the okstra-brief-gen contract.
 13. The requirement/objective section `## Desired Outcome` (required in every
     brief variant) exists and its body is not blank. `_(none)_` stays valid.
+14. The end-state sections `## Expected Behavior` (EB-NNN) / `## Preserved
+    Behavior` (PB-NNN) / `## Expected Outcome` (EO-NNN): each item carries a
+    3-digit id and an `— verify: <how>` observation method, EB/EO are rejected
+    in the codebase-scan variant, and `## External Gates` — the destination for
+    an item with no observation method — is required in every variant.
 
 Exit code 0 on PASS, 1 on FAIL.
 """
@@ -426,42 +431,182 @@ def check_requirement_section(text: str, errors: list[str]) -> None:
         )
 
 
-# Splitting the source checklist across these two sections is what keeps a
-# person-owned gate ("validated in staging by <name>") out of the requirement
-# set. Both must exist even when empty, because a missing heading is
-# indistinguishable from "the reporter listed no gates" — and the silent
-# version of that mistake is what puts an unmeetable requirement into
-# Requirement Coverage.
-SCOPE_SPLIT_SECTIONS = ("Acceptance Criteria", "External Gates")
+# The brief pins the end state once; every later phase maps to it by id rather
+# than restating a goal of its own. Splitting behavior from outcome is what lets
+# a refactor say "nothing observable changes" without leaving the upper bound
+# blank — `Preserved Behavior` carries the bound that `Expected Behavior` can't.
+_END_STATE_SECTIONS = (
+    ("Expected Behavior", "EB"),
+    ("Preserved Behavior", "PB"),
+    ("Expected Outcome", "EO"),
+)
+# The destination for a must-pass point nobody can hand an observation method.
+# It is enforced here rather than in ALWAYS_REQUIRED_SECTIONS so the failure can
+# still say WHY the section exists: a generic "required section missing" gives
+# the reporter no way to tell a gate apart from an end state.
+_GATE_SECTION = "External Gates"
+_END_STATE_ID_RE = re.compile(r"^(?P<id>(?:EB|PB|EO)-\d{3})\b")
+# Mirrors the `[—-]` tolerance in scripts/okstra_ctl/scope_provenance.py so a
+# reporter who cannot type an em dash is not silently rejected.
+_VERIFY_RE = re.compile(r"[—-]{1,2}\s*verify:\s*(?P<how>\S.*)$")
+_SCAN_ONLY_PREFIXES = frozenset({"EB", "EO"})
+
+
+def _has_bullet(body: str) -> bool:
+    return any(line.strip().startswith("- ") for line in body.splitlines())
+
+
+def _declares_nothing(body: str) -> bool:
+    """True when the body is the contract's explicit empty marker and nothing else.
+
+    `_(none)_` is written bare in every other brief section — `is_placeholder`
+    accepts both the bare and the `- ` form, and the template tells the reporter
+    to "use _(none)_ if none". Demanding a dash here alone would reject the house
+    form, and the message that fires would tell the author to write the very
+    thing they wrote.
+    """
+    lines = [line.strip() for line in body.splitlines() if line.strip()]
+    return bool(lines) and all(is_placeholder(line) for line in lines)
 
 
-def check_scope_split_sections(text: str, errors: list[str]) -> None:
-    """Both halves of the requirement/gate split must exist with a body.
+def _check_gate_section(text: str, errors: list[str]) -> None:
+    if not has_section_heading(text, _GATE_SECTION):
+        errors.append(
+            f"required section '## {_GATE_SECTION}' is missing — it is where a "
+            "must-pass point that a person or live infrastructure owns goes. "
+            "Without it, an item okstra cannot satisfy has nowhere to land but "
+            "the end-state sections, and the plan is then forced to build a "
+            "stage for work no phase can do"
+        )
+        return
+    if not section_body(text, _GATE_SECTION).strip():
+        errors.append(
+            f"required section '## {_GATE_SECTION}' has an empty body "
+            "(use _(none)_ only for a deliberately-empty section)"
+        )
+
 
-    `## Acceptance Criteria` holds must-pass points an okstra phase can satisfy
-    by changing repository files; `## External Gates` holds the ones a person or
-    live infrastructure owns (okstra-brief-gen SKILL.md §"Splitting a source
-    checklist"). `_(none)_` stays valid — it is the contract's explicit
-    placeholder for a deliberately-empty section.
-    """
-    for heading in SCOPE_SPLIT_SECTIONS:
-        if not has_section_heading(text, heading):
+def _check_end_state_items(
+    text: str, heading: str, prefix: str, seen: set[str], errors: list[str]
+) -> None:
+    for bullet in meaningful_bullets(text, heading):
+        match = _END_STATE_ID_RE.match(bullet)
+        if match is None or not match.group("id").startswith(f"{prefix}-"):
             errors.append(
-                f"required section '## {heading}' is missing (a brief must split "
-                "must-pass points into repo-satisfiable criteria and "
-                "person/infrastructure-owned gates)"
+                f"'## {heading}' item {bullet!r} must start with a `{prefix}-NNN` id "
+                "(3 digits) — later phases map to the brief by id, not by heading"
             )
             continue
-        if not section_body(text, heading).strip():
+        item_id = match.group("id")
+        if item_id in seen:
+            errors.append(f"duplicate end-state id {item_id!r}")
+        seen.add(item_id)
+        if not _VERIFY_RE.search(bullet):
             errors.append(
-                f"required section '## {heading}' has an empty body "
-                "(use _(none)_ only for a deliberately-empty section)"
+                f"end-state item {item_id!r} has no observation method — append "
+                "`— verify: <command or observation point>`. An item nobody can "
+                "observe is not an end state. It has two destinations, both of "
+                f"which keep it in the brief: '## {_GATE_SECTION}' when a person "
+                "or live infrastructure owns it, or '## Open Questions' as a "
+                "`general:` row when the observation method is what is still "
+                "unknown. Deleting it is not one of them."
+            )
+
+
+def _check_one_end_state_section(
+    text: str, heading: str, prefix: str, scope: str, seen: set[str], errors: list[str]
+) -> None:
+    """One end-state section: whether it may exist here, its body shape, its items.
+
+    A codebase-scan brief is authored before anything has been found, so it can
+    only pin what must NOT change. Declaring an expected behavior there would be
+    an invented requirement, which is why EB/EO are rejected rather than treated
+    as optional — and why `_(none)_` is rejected for the one section that
+    survives there: it is the whole upper bound of that variant.
+    """
+    if scope == "codebase" and prefix in _SCAN_ONLY_PREFIXES:
+        if has_section_heading(text, heading):
+            errors.append(
+                f"section '## {heading}' is not allowed in a codebase-scan brief "
+                "(the scan has not run yet, so its outcome cannot be declared) — "
+                "use '## Preserved Behavior' for what must not change"
+            )
+        return
+    if not has_section_heading(text, heading):
+        errors.append(
+            f"required section '## {heading}' is missing (the brief pins the "
+            "end state that every later phase maps to)"
+        )
+        return
+    body = section_body(text, heading)
+    if not body.strip():
+        errors.append(
+            f"required section '## {heading}' has an empty body "
+            "(use _(none)_ only for a deliberately-empty section)"
+        )
+        return
+    if _declares_nothing(body):
+        # In a scan this is the only section left, so an empty marker here is
+        # not "deliberately empty" — it is a brief with no upper bound at all,
+        # which is what improvement-discovery reads as its bound.
+        if scope == "codebase":
+            errors.append(
+                f"'## {heading}' is _(none)_ in a codebase-scan brief. It is the "
+                "only end-state section this variant carries, and "
+                "improvement-discovery treats it as the bound on what a "
+                "candidate may change — an empty one bounds nothing. State at "
+                "least one behaviour no candidate from this scan may break"
             )
+        return
+    # Only `- ` lines are read as items, so prose here is silently dropped
+    # rather than rejected — the reporter believes they pinned an end state
+    # and every downstream phase sees a section that declared nothing.
+    if not _has_bullet(body):
+        errors.append(
+            f"'## {heading}' has a body but no `- ` item — prose in this "
+            "section is dropped, not read. Every end state is a "
+            f"`- {prefix}-NNN <condition> — verify: <how>` bullet; write "
+            "_(none)_ on its own line if the section is deliberately empty"
+        )
+        return
+    _check_end_state_items(text, heading, prefix, seen, errors)
+
+
+def _check_end_state_declared(text: str, errors: list[str]) -> None:
+    """A reporter-input brief declares at least one observable end state."""
+    if meaningful_bullets(text, "Expected Behavior") or meaningful_bullets(
+        text, "Expected Outcome"
+    ):
+        return
+    errors.append(
+        "'## Expected Behavior' and '## Expected Outcome' are both empty — a brief "
+        "must declare at least one observable end state. A pure bugfix may leave "
+        "Expected Outcome as _(none)_ and a pure refactor may leave Expected "
+        "Behavior as _(none)_, but not both. If every must-pass point you have is "
+        f"owned by a person ('## {_GATE_SECTION}') or still lacks an observation "
+        "method ('## Open Questions'), this brief is not ready to start a run — "
+        "answer the open question first rather than emptying the end state"
+    )
+
+
+def check_end_state_sections(text: str, scope: str, errors: list[str]) -> None:
+    """The brief's end state: expected behavior, preserved behavior, expected outcome.
+
+    `## External Gates` is checked here too, in every variant: it is where an
+    item with no observation method goes, so the admissible set and its overflow
+    have to be required by the same check or the overflow silently disappears.
+    """
+    _check_gate_section(text, errors)
+    seen: set[str] = set()
+    for heading, prefix in _END_STATE_SECTIONS:
+        _check_one_end_state_section(text, heading, prefix, scope, seen, errors)
+    if scope != "codebase":
+        _check_end_state_declared(text, errors)
 
 
 # The variant-independent rows of the skill's "Required sections by variant"
-# table (okstra-brief-gen SKILL.md). Desired Outcome and the Acceptance
-# Criteria / External Gates split have dedicated checks with richer messages;
+# table (okstra-brief-gen SKILL.md). Desired Outcome and the end-state
+# sections / External Gates have dedicated checks with richer messages;
 # Scan Scope / Priority Lenses are codebase-only (check_codebase_scope);
 # Source Material / Problem / Symptom are omitted by the codebase variant, so
 # they are enforced only off it.
@@ -563,7 +708,7 @@ def validate_brief(path: Path, briefs_root: Path) -> list[str]:
     check_related_task_graph(text, errors)
 
     check_requirement_section(text, errors)
-    check_scope_split_sections(text, errors)
+    check_end_state_sections(text, scope, errors)
     check_variant_required_sections(text, scope, errors)
 
     # 2. brief-id matches filename stem