okstra 0.139.0 → 0.141.0

package/runtime/prompts/profiles/requirements-discovery.md

@@ -35,7 +35,7 @@
     `domain`(work-category 5-enum: bugfix / feature / refactor / ops / improvement),
     `depends-on`(an inline list of unit-ids within the same fan-out `[unit-001]`, or `[]` if none),
     `recommended-next-phase`(error-analysis | implementation-planning) are filled in.
-    Each packet MUST carry a non-empty `## Requirement Provenance` section whose every bullet is `brief:<heading>` (a heading that literally exists in the task brief) or `contract:<rule>`. `derived:` is not admissible in a packet — cross-packet derivation cannot be resolved from a single packet, so each unit anchors directly on the brief. A unit you cannot source that way is not a work item: raise it as a clarification row instead of publishing a packet for it. **Enforced:** `validators/validate_fanout.py` `_check_provenance`.
+    Each packet MUST carry a non-empty `## Requirement Provenance` section whose every bullet is `brief:EB-001` / `brief:PB-001` / `brief:EO-001` — an end-state id the brief declares — or `contract:<rule>`. When the brief pins ids, citing a heading is rejected: every brief carries the same generic headings, so a heading cannot say WHICH reporter line demanded this unit, and a fan-out unit becomes the brief for a whole downstream task. Only a brief authored before the end-state sections existed still takes the older `brief:<heading>` form, and there the heading must literally exist in it. `derived:` is not admissible in a packet — cross-packet derivation cannot be resolved from a single packet, so each unit anchors directly on the brief. A unit you cannot source that way is not a work item: raise it as a clarification row instead of publishing a packet for it. **Enforced:** `validators/validate_fanout.py` `_check_provenance`.
   - in `runs/requirements-discovery/fan-out/index.md`, list the packets in depends-on topological order
     as a numbered list (`1. unit-001`) (a generated view; explicitly do not hand-edit). The depends-on graph
     must be a DAG — `validate_fanout` rejects a cycle as a validation failure, so if a cycle appears,
@@ -56,6 +56,7 @@
   - uncertainty boundaries and missing inputs
   - next recommended phase and safe resume guidance
   - canonical-term resolution for every `terminology:*` brief item as `<term> = <definition>`, plus whether `<PROJECT_ROOT>/.okstra/glossary.md` should be updated
+  - one `endStateCoverage` row per brief end-state id (`EB-NNN` / `PB-NNN` / `EO-NNN`). `coveredBy` names the routing decision, the fan-out unit id, or the `C-NNN` clarification that accounts for it. This phase does NOT author a goal of its own — the brief already pinned the end state, and restating it here is how four phases end up with four different targets. **Enforced:** `validators/validate-run.py` `_validate_end_state_coverage`.
 - Report assembly instructions:
   - write canonical-term resolutions in a new `Domain Alignment` subsection of the final report; actual glossary writes happen via `okstra-brief-gen` Step 4.5 on a subsequent run
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):

package/runtime/python/okstra_ctl/build_tools.py

@@ -0,0 +1,95 @@
+"""Decide whether a plan's command cell invokes the project's build toolchain.
+
+The planning worktree has no dependencies installed, so a stage that calls the
+toolchain needs its precondition declared once and referenced (see the
+plan-body contract's "Planning-time environment gap"). This module owns the
+set of commands that counts as such a call.
+
+An allowlist, not a denylist: a tool nobody listed goes undetected, which
+weakens one advisory check, whereas treating every unknown leading token as a
+build call would fire on `grep` and `sed` in every plan and train readers to
+ignore the warning.
+"""
+from __future__ import annotations
+
+import json
+import shlex
+from pathlib import Path
+
+DEFAULT_BUILD_TOOL_TOKENS: tuple[str, ...] = (
+    "npm",
+    "yarn",
+    "pnpm",
+    "npx",
+    "bun",
+    "pytest",
+    "tox",
+    "poetry",
+    "uv",
+    "cargo",
+    "go",
+    "gradle",
+    "mvn",
+    "make",
+    "bundle",
+    "composer",
+    "dotnet",
+)
+
+# Prefixes that stand in front of the real command without being it.
+_TRANSPARENT_LEADERS = frozenset({"sudo", "env", "time", "nice", "exec", "command"})
+_CLAUSE_SEPARATORS = ("&&", "||", ";", "|", "\n")
+
+
+def resolve_build_tool_tokens(project_root: Path) -> tuple[str, ...]:
+    """Project override, else the built-in list.
+
+    `buildToolTokens` in `.okstra/project.json` REPLACES the defaults and an
+    empty array disables detection — the same precedence `worktreeSyncDirs`
+    uses, so one rule covers both.
+    """
+    try:
+        payload = json.loads(
+            (Path(project_root) / ".okstra" / "project.json").read_text(encoding="utf-8")
+        )
+    except (OSError, json.JSONDecodeError):
+        return DEFAULT_BUILD_TOOL_TOKENS
+    configured = payload.get("buildToolTokens") if isinstance(payload, dict) else None
+    if not isinstance(configured, list):
+        return DEFAULT_BUILD_TOOL_TOKENS
+    return tuple(str(token).strip() for token in configured if str(token).strip())
+
+
+def _clauses(command: str) -> list[str]:
+    parts = [command]
+    for separator in _CLAUSE_SEPARATORS:
+        parts = [piece for part in parts for piece in part.split(separator)]
+    return [part.strip() for part in parts if part.strip()]
+
+
+def _leading_token(clause: str) -> str:
+    try:
+        words = shlex.split(clause)
+    except ValueError:
+        words = clause.split()
+    for word in words:
+        # `cd <dir>` and `VAR=value` lead a clause without being the command;
+        # step past them rather than reading the directory as the tool.
+        if word == "cd" or "=" in word.split("/")[0] and not word.startswith("-"):
+            continue
+        if word in _TRANSPARENT_LEADERS:
+            continue
+        if word.startswith("-"):
+            continue
+        return Path(word).name
+    return ""
+
+
+def command_invokes_build_tool(
+    command: str, *, tokens: tuple[str, ...] | None = None
+) -> bool:
+    """True when any clause of *command* starts with an allowlisted tool."""
+    allowed = DEFAULT_BUILD_TOOL_TOKENS if tokens is None else tokens
+    if not allowed:
+        return False
+    return any(_leading_token(clause) in allowed for clause in _clauses(command))

package/runtime/python/okstra_ctl/incremental_scope.py

@@ -10,14 +10,28 @@ from __future__ import annotations
 
 import argparse
 import json
+import re
 import sys
 from dataclasses import asdict, dataclass
 from pathlib import Path
 
+from okstra_ctl.stage_citations import cited_stage_numbers
 from okstra_ctl.stage_targets import downstream_stage_closure
 
 CUTOFF_RATIO = 0.5
 
+# Prefix that marks a full decision the lead *chose* rather than fell back to.
+# Both cases return `mode: full`, and without this the two are one string —
+# which is what made a re-run's "no impacted stages resolved" unreadable as
+# either a structural judgement or a mapping the lead never made.
+DECLARED_FULL_PREFIX = "declared structural change:"
+
+# `P-Step-<stage>.<step>` and `P-Prep-S<stage>-<kind>` carry their stage in the
+# id itself. Every other prefix (`P-Opt`, `P-Dep`, `P-Val`, `P-Rb`, `P-Req`) is
+# numbered by position in its own array, so its stage is only recoverable from
+# the prose the planner wrote.
+_STRUCTURAL_STAGE_IN_ID_RE = re.compile(r"^P-(?:Step-(\d+)\.\d+|Prep-S(\d+)-)")
+
 
 @dataclass
 class IncrementalDecision:
@@ -73,6 +87,60 @@ def design_prep_impacted_stages(data: dict, item_ids: set[str]) -> set[int]:
     return impacted
 
 
+def _plan_item_stages(item: dict) -> set[int]:
+    structural = _STRUCTURAL_STAGE_IN_ID_RE.match(str(item.get("id") or ""))
+    if structural:
+        return {int(structural.group(1) or structural.group(2))}
+    return cited_stage_numbers(str(item.get("subject") or ""))
+
+
+def _stages_blocked_on(coverage: object, clarification_id: str) -> set[int]:
+    blocked = f"blocked {clarification_id}"
+    stages: set[int] = set()
+    for row in coverage if isinstance(coverage, list) else []:
+        if not isinstance(row, dict):
+            continue
+        if str(row.get("status") or "").strip() != blocked:
+            continue
+        stages |= cited_stage_numbers(str(row.get("coveredBy") or ""))
+    return stages
+
+
+def clarification_impacted_stages(
+    data: dict, clarification_ids: set[str]
+) -> set[int]:
+    """Stage Map stages the answered clarifications touch, read off the prior run.
+
+    Two links the prior report already recorded: the `P-*` plan item that blocked
+    on the clarification, and the requirement-coverage row blocked on the same
+    id. Resolving them here removes the discretionary mapping step that made the
+    lead fall back to full even for an answer that changed nothing.
+
+    Raises when any id resolves to no stage — a partially-resolved set would
+    narrow the re-run past an answer whose blast radius nobody established.
+    """
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        raise ValueError("implementationPlanning is missing")
+    verification = planning.get("planBodyVerification")
+    plan_items = (verification or {}).get("planItems") if isinstance(verification, dict) else []
+    coverage = planning.get("requirementCoverage")
+
+    impacted: set[int] = set()
+    for clarification_id in sorted(clarification_ids):
+        stages = _stages_blocked_on(coverage, clarification_id)
+        for item in plan_items if isinstance(plan_items, list) else []:
+            if isinstance(item, dict) and item.get("clarificationId") == clarification_id:
+                stages |= _plan_item_stages(item)
+        if not stages:
+            raise ValueError(
+                f"answered clarification {clarification_id} traces to no stage "
+                "(no plan item or coverage row cites one)"
+            )
+        impacted |= stages
+    return impacted
+
+
 def decide_scope(
     *,
     stages: list[tuple[int, list[int]]],
@@ -107,14 +175,41 @@ def main(argv: list[str]) -> int:
     ap.add_argument("--prev-base-sha", required=True)
     ap.add_argument("--impacted", default="", help="comma-separated impacted stage numbers")
     ap.add_argument("--prep-items", default="", help="comma-separated changed PREP item IDs")
+    ap.add_argument(
+        "--answered-clarifications",
+        default="",
+        help="comma-separated C-NNN ids answered since the prior run; their "
+             "stages are resolved from that run's plan-item and coverage links",
+    )
+    ap.add_argument(
+        "--full-reason",
+        default="",
+        help="declare that an answer changes the selected option, Stage Map, or "
+             "recommended approach. Forces full and records the judgement, so it "
+             "is distinguishable from a re-run that simply resolved no stage",
+    )
     args = ap.parse_args(argv)
 
+    declared = args.full_reason.strip()
+    if declared:
+        # The lead's structural judgement is exactly what the back-trace cannot
+        # make, so a successful trace must not override it.
+        print(json.dumps(asdict(IncrementalDecision(
+            "full", [], [], f"{DECLARED_FULL_PREFIX} {declared}",
+        )), ensure_ascii=False))
+        return 0
+
     try:
         data = json.loads(Path(args.prev_data).read_text(encoding="utf-8"))
         stages = parse_stage_graph(data)
         impacted = {int(t.strip()) for t in args.impacted.split(",") if t.strip()}
         prep_ids = {t.strip() for t in args.prep_items.split(",") if t.strip()}
         impacted.update(design_prep_impacted_stages(data, prep_ids))
+        answered = {
+            t.strip() for t in args.answered_clarifications.split(",") if t.strip()
+        }
+        if answered:
+            impacted.update(clarification_impacted_stages(data, answered))
         unknown_stages = impacted - {stage for stage, _ in stages}
         if unknown_stages:
             unknown = ", ".join(str(stage) for stage in sorted(unknown_stages))

package/runtime/python/okstra_ctl/render.py

@@ -104,23 +104,38 @@ def _runtime_resolution(ctx: dict) -> dict:
     return payload if isinstance(payload, dict) else {}
 
 
+# The phases a `{% if header.taskType ... %}` block may target: the lifecycle
+# sequence itself, kept as an allowlist rather than `[a-z-]+` so a typo'd phase
+# name fails to match and the block survives the copy — caught by eye instead of
+# silently vanishing from every phase's excerpt. Longest-first so
+# `implementation-planning` is never matched as `implementation`.
+_PHASE_ALT = "|".join(
+    re.escape(phase) for phase in sorted(PHASE_SEQUENCE, key=len, reverse=True)
+)
+# Two forms: a single-phase block (`== 'X'`) and a multi-phase one
+# (`in ('X', 'Y')`). The multi form exists because a section can belong to a
+# set of phases — `### 2.3 End State Coverage` is written by the three
+# pre-implementation phases and by no other.
 _PHASE_BLOCK_RE = re.compile(
-    r"\{% if header\.taskType == '(implementation-planning|release-handoff|implementation|final-verification)' %\}\n(.*?)\{% endif %\}\n",
+    r"\{% if header\.taskType (?:"
+    rf"== '(?P<one>{_PHASE_ALT})'"
+    rf"|in \((?P<many>'(?:{_PHASE_ALT})'(?:\s*,\s*'(?:{_PHASE_ALT})')*),?\s*\)"
+    r") %\}\n(?P<body>.*?)\{% endif %\}\n",
     re.DOTALL,
 )
+_PHASE_NAME_RE = re.compile(r"'([a-z-]+)'")
 
 
 def _strip_phase_blocks(text: str, current_phase: str) -> str:
     """Resolve phase-conditional blocks (`{% if header.taskType == 'X' %}
     ... {% endif %}`) against *current_phase*.
 
-    Blocks whose target equals *current_phase* keep their body (jinja
-    markers dropped); blocks targeting a different phase are removed
-    entirely. When *current_phase* is empty or not one of the four
-    block-targetable phases (e.g. `requirements-discovery`,
-    `error-analysis`), every block is dropped — correct because none of
-    the `## 5.5` / `5.6` / `5.7` / `5.8` deliverable sections apply
-    there.
+    Blocks whose target set contains *current_phase* keep their body (jinja
+    markers dropped); blocks targeting only other phases are removed
+    entirely. A phase that no block names keeps none of them — and when
+    *current_phase* is empty that is every block. The `## 5.5` / `5.6` /
+    `5.7` / `5.8` deliverable sections stay single-phase, so they still
+    apply to exactly one task-type each.
 
     Observed (fontsninja-classifier-v2 RD run): the raw final-report
     template copied into instruction-set/final-report-template.md was
@@ -135,9 +150,9 @@ def _strip_phase_blocks(text: str, current_phase: str) -> str:
     """
 
     def repl(m: "re.Match[str]") -> str:
-        target_phase = m.group(1)
-        body = m.group(2)
-        return body if target_phase == current_phase else ""
+        one = m.group("one")
+        targets = {one} if one else set(_PHASE_NAME_RE.findall(m.group("many")))
+        return m.group("body") if current_phase in targets else ""
 
     return _PHASE_BLOCK_RE.sub(repl, text)
 

package/runtime/python/okstra_ctl/render_final_report.py

@@ -577,6 +577,29 @@ def resolve_report_language(data: dict, *, override: str | None) -> str:
     return candidate
 
 
+# Schema-optional top-level arrays, and the value a template may assume when
+# the report omits them. The vendored jinja2 does not resolve a missing
+# top-level name to `Undefined`: `| default([])` passes the sentinel straight
+# through, `| length` raises on it, and both `x` and `not x` evaluate true. So a
+# template cannot test for absence at all, and the value has to arrive filled.
+_OPTIONAL_ARRAY_DEFAULTS = ("endStateCoverage",)
+
+
+def _with_optional_defaults(data: dict) -> dict:
+    """Render context with schema-optional arrays filled in.
+
+    Keeps the schema field optional — an omitted `endStateCoverage` stays absent
+    in data.json, which is what the run validator reads to tell a legacy brief
+    apart from a dropped requirement — while giving the template a value it can
+    branch on.
+    """
+    filled = dict(data)
+    for key in _OPTIONAL_ARRAY_DEFAULTS:
+        if not isinstance(filled.get(key), list):
+            filled[key] = []
+    return filled
+
+
 def render(
     data: dict,
     *,
@@ -606,7 +629,7 @@ def render(
 
     try:
         template = env.get_template(template_path.name)
-        rendered = template.render(**data)
+        rendered = template.render(**_with_optional_defaults(data))
         rendered = _inject_index_and_anchors(rendered, dictionary)
         return _ventilate_prose(rendered)
     except I18nError as exc:

package/runtime/python/okstra_ctl/rollup.py

@@ -23,6 +23,38 @@ from okstra_project import (
 )
 
 
+_CRITIC_COUNTERS = (
+    "gapsProposed",
+    "gapsMerged",
+    "gapsRejected",
+    "gapsUnverified",
+)
+
+
+def _collect_critic(task_root: Path) -> dict:
+    """task 의 모든 run 에서 커버리지 크리틱 결과를 합산.
+
+    크리틱은 opt-in 이라 대부분의 run 에 `config.critic` 이 없다. 그런 run 은
+    `runsWithCritic` 에 세지 않는다 — "쓰지 않았다" 와 "썼는데 0건" 은 정책 판단이
+    갈리는 서로 다른 사실이다. 읽기 전용이므로 깨진 state 파일은 건너뛴다.
+    """
+    totals = {"runsWithCritic": 0} | {name: 0 for name in _CRITIC_COUNTERS}
+    for state_path in sorted(task_root.glob("runs/*/state/convergence-*.json")):
+        try:
+            payload = json.loads(state_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        critic = (payload.get("config") or {}).get("critic")
+        if not isinstance(critic, dict):
+            continue
+        totals["runsWithCritic"] += 1
+        for name in _CRITIC_COUNTERS:
+            value = critic.get(name)
+            if isinstance(value, int) and not isinstance(value, bool):
+                totals[name] += value
+    return totals
+
+
 def _collect_task(entry: dict, project_root: Path) -> dict:
     """list_project_tasks entry → roll-up 한 줄. catalog 상태 필드 + time/error 측정.
 
@@ -33,7 +65,13 @@ def _collect_task(entry: dict, project_root: Path) -> dict:
     runs, _ = load_runs(task_root)
     time_agg = aggregate_time(runs, project_root)
     records, _ = parse_records(glob_error_logs(task_root))
+    critic = _collect_critic(task_root)
     return {
+        "criticRuns": critic["runsWithCritic"],
+        "criticGapsProposed": critic["gapsProposed"],
+        "criticGapsMerged": critic["gapsMerged"],
+        "criticGapsRejected": critic["gapsRejected"],
+        "criticGapsUnverified": critic["gapsUnverified"],
         "taskKey": entry.get("taskKey", ""),
         "taskGroup": entry.get("taskGroup", ""),
         "taskId": entry.get("taskId", ""),
@@ -62,10 +100,21 @@ def _tally(tasks: list[dict], key: str) -> dict:
     return dict(sorted(counts.items()))
 
 
+def _critic_totals(tasks: list[dict]) -> dict:
+    return {
+        "runsWithCritic": sum(t["criticRuns"] for t in tasks),
+        "gapsProposed": sum(t["criticGapsProposed"] for t in tasks),
+        "gapsMerged": sum(t["criticGapsMerged"] for t in tasks),
+        "gapsRejected": sum(t["criticGapsRejected"] for t in tasks),
+        "gapsUnverified": sum(t["criticGapsUnverified"] for t in tasks),
+    }
+
+
 def build_rollup(project_root: Path, task_group: str | None) -> dict:
     entries = list_project_tasks(project_root, task_group=task_group or None)
     tasks = [_collect_task(e, project_root) for e in entries]
     totals = {
+        "critic": _critic_totals(tasks),
         "runs": sum(t["runCount"] for t in tasks),
         "cpuSumMs": sum(t["cpuSumMs"] for t in tasks),
         "wallClockMs": sum(t["wallClockMs"] for t in tasks),

package/runtime/python/okstra_ctl/scope_provenance.py

@@ -29,6 +29,17 @@ _CONTRACT_RE = re.compile(r"^contract:\s*(?P<rule>.+?)\s*$")
 _BRIEF_HEADING_RE = re.compile(r"^(#{1,6}\s+.+?)\s*$")
 _FENCE_RE = re.compile(r"^\s*(`{3,}|~{3,})")
 
+_END_STATE_ID_RE = re.compile(r"^(?:EB|PB|EO)-\d{3}$")
+_END_STATE_HEADINGS = frozenset(
+    {"Expected Behavior", "Preserved Behavior", "Expected Outcome"}
+)
+_END_STATE_BULLET_RE = re.compile(r"^-\s+(?P<id>(?:EB|PB|EO)-\d{3})\b")
+# Only `## ` closes a section, mirroring validate-brief.py's section_body
+# lookahead. `_BRIEF_HEADING_RE` above matches `#` through `######` and is for
+# heading citations, which are checked against a different reader.
+_SECTION_HEADING_RE = re.compile(r"^##\s+(?P<heading>.+?)\s*$")
+_HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
+
 
 def normalize_heading(text: str) -> str:
     """Heading text stripped of its `#` markers and surrounding whitespace.
@@ -37,6 +48,11 @@ def normalize_heading(text: str) -> str:
     Criteria` and `brief:## Acceptance Criteria` both name the same heading.
     The comparison stays exact after this — a heading the brief lacks must
     still fail.
+
+    Heading citations are the legacy form, reachable only for briefs authored
+    before the end-state sections existed (`brief_end_state_ids` returns an
+    empty set for those). A brief that pins ids takes `brief:EB-001` instead,
+    and `brief_citation_problem` rejects a heading there.
     """
     return " ".join(text.lstrip("#").split())
 
@@ -73,12 +89,62 @@ def brief_headings(brief_path: Path) -> set[str]:
     return headings
 
 
+def brief_end_state_ids(brief_path: Path) -> set[str]:
+    """End-state ids the brief declares, across all three sections.
+
+    The reading rules mirror validators/validate-brief.py exactly, because that
+    file checks the very same lines for their format and the two readers must
+    not disagree about what the brief declared. Concretely: only `## ` closes a
+    section (its `section_body`), fenced regions are NOT skipped (its
+    `meaningful_bullets` knows nothing about fences), and HTML comments are
+    removed (it strips them file-wide before any check).
+
+    This is the one function here that does not follow brief_headings' fence
+    discipline, and the asymmetry is deliberate. A heading citation and an
+    end-state item are validated by different code; each reader has to match its
+    own checker. Diverging the other way — skipping a fenced item the checker
+    accepted — is the worse failure: the brief passes, the id is absent from the
+    declared set, and no phase is ever asked to account for it.
+
+    An empty set means the brief predates the end-state sections, which is what
+    the downstream conditional gate keys on: a legacy brief keeps the legacy
+    path instead of being wedged by a contract it was never written against.
+    """
+    try:
+        text = _HTML_COMMENT_RE.sub("", Path(brief_path).read_text(encoding="utf-8"))
+    except OSError:
+        return set()
+
+    ids: set[str] = set()
+    section = ""
+    for line in text.splitlines():
+        if m := _SECTION_HEADING_RE.match(line):
+            heading = normalize_heading(m.group("heading"))
+            section = heading if heading in _END_STATE_HEADINGS else ""
+            continue
+        if not section:
+            continue
+        if m := _END_STATE_BULLET_RE.match(line.strip()):
+            ids.add(m.group("id"))
+    return ids
+
+
 @dataclass(frozen=True)
 class SourceRef:
     kind: Literal["brief", "derived", "contract", "invalid"]
     value: str = ""
     reason: str = ""
 
+    @property
+    def is_end_state_id(self) -> bool:
+        """True when a `brief:` citation names an end-state id rather than a heading.
+
+        Heading citations survive only for briefs authored before the end-state
+        sections existed; the id form is what makes a citation checkable against
+        a specific reporter line instead of a heading every brief carries.
+        """
+        return self.kind == "brief" and bool(_END_STATE_ID_RE.match(self.value))
+
 
 def parse_source(raw: str) -> SourceRef:
     text = (raw or "").strip()
@@ -97,6 +163,36 @@ def parse_source(raw: str) -> SourceRef:
     return SourceRef("invalid")
 
 
+def brief_citation_problem(
+    ref: SourceRef, headings: set[str], end_state: set[str]
+) -> str | None:
+    """Why a `brief:` citation is inadmissible, or None when it is fine.
+
+    Shared by validators/validate-run.py (requirementCoverage) and
+    validators/validate_fanout.py (fan-out packets): both decide admissibility
+    the same way and differ only in how they word the failure, so the decision
+    lives here and the wording stays with the caller.
+
+    A brief that pins ids refuses heading citations outright: every brief
+    carries the same generic headings, so a heading cannot say WHICH reporter
+    line the item came from — that is the loophole the id form closes.
+    """
+    if ref.kind != "brief":
+        return None
+    if end_state:
+        if not ref.is_end_state_id:
+            return (
+                f"cites `brief:{ref.value}`, but this brief pins end-state ids. "
+                "Cite the end-state id the item came from (`brief:EB-001`)"
+            )
+        if ref.value not in end_state:
+            return f"cites `brief:{ref.value}` which the brief does not declare"
+        return None
+    if headings and normalize_heading(ref.value) not in headings:
+        return f"cites brief heading `{ref.value}` which does not exist in the brief"
+    return None
+
+
 def resolve_chain(rows: dict[str, SourceRef]) -> dict[str, str]:
     """Walk each row's derivation chain to its terminator.
 
@@ -123,7 +219,8 @@ def resolve_chain(rows: dict[str, SourceRef]) -> dict[str, str]:
                 continue
             result[rid] = (
                 f"unrecognized source on `{cursor}` — must be one of "
-                "`brief:<heading>`, `derived:R-NNN — <reason>`, `contract:<rule>`"
+                "`brief:EB-001` (or the legacy `brief:<heading>`), "
+                "`derived:R-NNN — <reason>`, `contract:<rule>`"
             )
             break
     return result

package/runtime/python/okstra_ctl/stage_citations.py

@@ -0,0 +1,47 @@
+"""Read the Stage Map stage numbers a prose cell cites.
+
+Two readers depend on this grammar and must not drift apart: the coverage
+validator proving every stage traces back to a requirement, and the
+incremental-scope back-trace resolving which stages an answered clarification
+touches. A second copy would let one side accept a citation the other rejects,
+which decides whether a re-run narrows or stays full.
+"""
+from __future__ import annotations
+
+import re
+
+_RANGE = r"(?:[-–]|\bto\b|\bthrough\b)"
+_ITEM = rf"\d+(?:\s*{_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.
+_SEP = r"(?:,\s*(?:and|&)?|and|&)"
+_LIST_RE = re.compile(
+    rf"\bstages?[ \t]*({_ITEM}(?:\s*{_SEP}\s*{_ITEM})*)",
+    re.IGNORECASE,
+)
+_ITEM_RE = re.compile(rf"(\d+)(?:\s*{_RANGE}\s*(\d+))?", re.IGNORECASE)
+RANGE_MAX_SPAN = 64
+
+
+def cited_stage_numbers(text: str) -> set[int]:
+    """Stage numbers *text* cites, in every prose form a planner writes.
+
+    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 _LIST_RE.finditer(text):
+        for item in _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 <= RANGE_MAX_SPAN:
+                cited.update(range(start, end))
+    return cited

package/runtime/python/okstra_ctl/workflow.py

@@ -43,14 +43,15 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - work-category classification (bugfix / feature / refactor / ops / improvement)\n"
             "  - routing decision toward the next safe lifecycle phase\n"
             "  - missing-input list and clarification requests\n"
-            "  - approval / confirmation checkpoints recorded for the next phase"
+            "  - approval / confirmation checkpoints recorded for the next phase\n"
+            "  - one endStateCoverage row per brief end-state id (this phase authors no goal of its own)"
         ),
     },
     "improvement-discovery": {
         "allowed": (
             "  - improvement candidate discovery within the lens whitelist defined in `scripts/okstra_ctl/improvement_lenses.py`\n"
             "  - top-N ranking (default 8, brief `candidate-cap` overrides within 1..12)\n"
-            "  - per-candidate columns Lens / Scope / Severity / Effort / Consensus / Source workers / Recommended next-phase / Evidence (path:line)\n"
+            "  - per-candidate columns Lens / Scope / Severity / Effort / Consensus / Source workers / Recommended next-phase / Expected behavior after / Evidence (path:line)\n"
             "  - Phase 1.5 reflect-back grilling log at `runs/improvement-discovery/<seq>/state/phase-1.5-grilling.md`\n"
             "  - Phase 5.5 consensus classification (full / partial / contested / worker-unique)"
         ),
@@ -60,7 +61,8 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - symptom and trigger evidence\n"
             "  - root-cause hypotheses with supporting citations\n"
             "  - reproduction gaps and missing observability\n"
-            "  - validation paths to confirm or refute hypotheses"
+            "  - validation paths to confirm or refute hypotheses\n"
+            "  - one endStateCoverage row per brief end-state id (this phase authors no goal of its own)"
         ),
     },
     "implementation-planning": {
@@ -72,7 +74,8 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - dependency / migration risk assessment, validation checklist (pre / mid / post with exact commands), rollback strategy with revert path and trigger signal\n"
             "  - every unresolved ambiguity registered as a `Blocks=approval` row in the `## 1. Clarification Items` table (do NOT create a separate `Open Questions` block under `5.5.x` — the unified table is the single home)\n"
             "  - YAML frontmatter line `approved: false` awaiting human flip to `true`\n"
-            "  - self-review confirmation (spec coverage, placeholder scan, internal consistency, ambiguity, scope)"
+            "  - self-review confirmation (spec coverage, placeholder scan, internal consistency, ambiguity, scope)\n"
+            "  - one endStateCoverage row per brief end-state id, each mapped to the R-NNN row that carries it"
         ),
     },
     "implementation": {