okstra 0.172.0 → 0.174.0

package/runtime/python/okstra_ctl/run.py

@@ -26,6 +26,7 @@ import tempfile
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
+from typing import Sequence
 
 from okstra_project import project_json_path, upsert_project_json
 from okstra_project.state import slugify
@@ -48,6 +49,15 @@ from .clarification_items import (
 )
 from .error_report import prior_run_error_digest
 from .incremental_scope import ReverifyScopeError, parse_user_reverify_scope
+from .implementation_direction import (
+    DirectionSelectionError,
+    SelectedDirection,
+    lexical_absolute_path,
+    resolve_selected_direction,
+    validate_selected_direction_plan,
+    validate_task_artifact_path,
+    write_selected_direction_snapshot,
+)
 from .qa_commands import format_errors as _format_qa_errors, validate_qa_commands
 from .material import (
     build_analysis_material,
@@ -115,7 +125,11 @@ from .render import (
 )
 from okstra_project.dirs import okstra_home
 
-from .dispatch_state import BACKEND_CMUX_PANE, detect_terminal_backend
+from .dispatch_state import (
+    BACKEND_CMUX_PANE,
+    detect_terminal_backend,
+    generate_claude_session_id,
+)
 from .run_context import (
     compute_and_write_run_context,
     refresh_run_context_snapshot,
@@ -129,7 +143,6 @@ from .seeding import (
     verify_installation,
 )
 from .session import (
-    generate_claude_session_id,
     resolve_inproc_lead_session_id,
     write_claude_resume_command_file,
 )
@@ -154,6 +167,7 @@ from .brief_frontmatter import (
     has_reporter_confirmation_contract,
     read_brief_frontmatter,
 )
+from .scope_provenance import brief_end_state_id_sequence
 
 # Frontmatter approval-flag matcher.
 #
@@ -183,6 +197,10 @@ IMPLEMENTATION_OPTION_FRONTMATTER_PATTERN = re.compile(
     r"^implementation-option:[ \t]*(.*)$",
     re.MULTILINE,
 )
+SELECTED_DIRECTION_FRONTMATTER_PATTERN = re.compile(
+    r"^selected-direction-ref:[ \t]*(.*)$",
+    re.MULTILINE,
+)
 
 # validators/validate-run.py:_FRONTMATTER_BLOCK_RE 의 미러 — 선행 BOM/빈 줄을
 # 허용해 두 모듈이 같은 리포트의 frontmatter 게이트를 동일하게 판정하게 한다.
@@ -281,6 +299,43 @@ def _validate_data_json_approval_consistency(
         )
 
 
+def _validate_approved_plan_conformance(path: Path) -> None:
+    """승인 계획의 stage conformance 선언 형식을 승인 경계에서 판정한다.
+
+    같은 판정이 지금까지는 구현 런의 마지막 `validate-run` 에서만 나왔다. 그때는
+    워커 배치와 수렴이 이미 끝난 뒤라 런 하나를 통째로 버려야 했다 — 실측된
+    실패에서 승인 계획의 stage 2~7 이 기계 형식이 아니라 산문이었다.
+
+    선언이 없는 stage 는 건드리지 않는다(`conformance.malformed_conformance_stages`
+    참조): XOR 부재는 계획 단계의 check S11 이 이미 막고, 구현 진입 게이트도
+    validate-run 이 계속 요구한다. 여기서 다시 하면 같은 규칙이 두 곳이 된다.
+    """
+    from .conformance import malformed_conformance_stages
+
+    loaded = _load_final_report_data_if_present(path)
+    if loaded is None:
+        return
+    data_path, data = loaded
+    bad = malformed_conformance_stages(data)
+    if not bad:
+        return
+    # 한 stage 씩 고치고 다시 막히는 왕복을 피하려면 전부 나열해야 한다 —
+    # 실패한 런에서 검증기는 stage 2 만 지목했지만 실제로는 2~7 전부였다.
+    stages = ", ".join(str(number) for number in bad)
+    raise PrepareError(
+        f"approved plan data.json has malformed conformanceTests for stage(s) "
+        f"{stages}: {data_path}\n"
+        "  each declaring stage must read "
+        "`<task_root>/qa/scripts/stage-<N>.<ext> "
+        "(requires=[db|io|http|external,...])` after the "
+        "`Conformance tests: stage-<N> — ` prefix "
+        "(prompts/profiles/implementation-planning.md), or carry "
+        "`Conformance exemption: <reason>` instead.\n"
+        "  re-run implementation-planning so the declaration is regenerated in "
+        "that form, then approve it."
+    )
+
+
 def _set_data_json_approved_true_if_present(path: Path) -> bool:
     loaded = _load_final_report_data_if_present(path)
     if loaded is None:
@@ -393,6 +448,8 @@ class PrepareInputs:
     # 별개 채널이다.
     stages: str = ""
     clarification_response_path: str = ""  # absolute or empty
+    # implementation-planning 신규 실행 전용: 검증된 방향 선택 최종 보고서.
+    selected_direction_path: str = ""
     # implementation-planning 전용: 사용자가 고른 이번 재실행의 재검증 범위.
     # "" / "auto" = 리드의 `okstra incremental-scope` 판정에 맡김, "full" =
     # 전체 재검증 강제, "<stage csv>" = 그 stage 들을 impacted 로 지정.
@@ -457,6 +514,7 @@ def _validate_approved_plan(path: str) -> None:
         )
     _reject_blocking_plan_body_gate(p, body, action="approved plan validation")
     _validate_data_json_approval_consistency(p, markdown_approved=True)
+    _validate_approved_plan_conformance(p)
     # frontmatter approved == true 상태. §1 Clarification Items 의
     # Blocks=approval 행이 아직 open/answered 면 승인을 무효화한다.
     scan = scan_approval_gate(p)
@@ -781,6 +839,7 @@ def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
         ("--approved-plan", inp.approved_plan_path),
         ("--implementation-option", inp.implementation_option),
         ("--clarification-response", inp.clarification_response_path),
+        ("--selected-direction", inp.selected_direction_path),
         ("--workers", workers),
         ("--lead-provider", inp.lead_provider or ctx.get("LEAD_PROVIDER", "")),
         ("--lead-model", inp.lead_model or ctx.get("LEAD_MODEL", "")),
@@ -992,6 +1051,13 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
         pass
     elif not inp.brief_path.is_file():
         raise PrepareError(f"task brief not found: {inp.brief_path}")
+    elif inp.task_type == "implementation-option-selection" and not brief_end_state_id_sequence(
+        inp.brief_path
+    ):
+        raise PrepareError(
+            "regenerate the brief with stable end-state IDs before starting "
+            "implementation-option-selection"
+        )
     ctx_stage_map: list = []
     # implementation 과 final-verification 은 둘 다 승인된 plan 의 Stage Map 을
     # 입력으로 받는다(전자는 실행 scope, 후자는 검증 scope).
@@ -1041,10 +1107,123 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
         raise PrepareError(
             f"clarification response file not found: {inp.clarification_response_path}"
         )
+    _validate_planning_entry_inputs(project_root, inp)
     _validate_reverify_scope(inp)
     return ctx_stage_map
 
 
+_PLANNING_REPORT_RE = re.compile(
+    r"^final-report-implementation-planning-\d{3,}\.md$"
+)
+
+
+def _resolve_planning_input_path(
+    path_value: str, project_root: Path
+) -> Path | None:
+    """Resolve cwd-first planning inputs without following symbolic links."""
+    raw_path = Path(path_value).expanduser()
+    cwd_candidate = lexical_absolute_path(raw_path)
+    if cwd_candidate.is_file():
+        return cwd_candidate
+    if not raw_path.is_absolute():
+        project_candidate = lexical_absolute_path(project_root / raw_path)
+        if project_candidate.is_file():
+            return project_candidate
+    return None
+
+
+def _is_existing_planning_report(
+    path_value: str, project_root: Path, inp: PrepareInputs
+) -> bool:
+    from .paths import task_dir
+
+    try:
+        report = lexical_absolute_path(Path(path_value))
+        task_root = lexical_absolute_path(
+            task_dir(project_root, inp.task_group, inp.task_id)
+        )
+        relative = report.relative_to(task_root)
+    except ValueError:
+        return False
+    has_planning_layout = (
+        _PLANNING_REPORT_RE.fullmatch(report.name) is not None
+        and relative.parts[:3] == (
+            "runs",
+            "implementation-planning",
+            "reports",
+        )
+        and len(relative.parts) == 4
+    )
+    if not has_planning_layout:
+        return False
+    try:
+        validate_task_artifact_path(report, task_root, "planning report")
+    except DirectionSelectionError:
+        return False
+    return True
+
+
+def _validate_planning_entry_inputs(
+    project_root: Path, inp: PrepareInputs
+) -> None:
+    if inp.task_type != "implementation-planning":
+        if inp.selected_direction_path:
+            raise PrepareError(
+                "--selected-direction is only meaningful with --task-type "
+                f"implementation-planning; got {inp.task_type}"
+            )
+        return
+    if inp.selected_direction_path and inp.clarification_response_path:
+        raise PrepareError(
+            "implementation-planning accepts either --selected-direction for a "
+            "new plan or --clarification-response for a rerun, not both"
+        )
+    if inp.selected_direction_path:
+        return
+    if inp.clarification_response_path:
+        if not _is_existing_planning_report(
+            inp.clarification_response_path, project_root, inp
+        ):
+            raise PrepareError(
+                "implementation-planning rerun --clarification-response must point "
+                "to an existing implementation-planning report for the same task"
+            )
+        return
+    raise PrepareError(
+        "implementation-planning requires --selected-direction for a new plan or "
+        "--clarification-response to an existing implementation-planning report"
+    )
+
+
+def _resolve_planning_direction(inp: PrepareInputs) -> SelectedDirection | None:
+    if inp.task_type != "implementation-planning" or not inp.selected_direction_path:
+        return None
+    from .paths import task_dir
+
+    try:
+        report = lexical_absolute_path(Path(inp.selected_direction_path))
+        expected_task_root = lexical_absolute_path(
+            task_dir(Path(inp.project_root), inp.task_group, inp.task_id)
+        )
+        report.relative_to(expected_task_root)
+    except ValueError as exc:
+        raise PrepareError(
+            "selected direction report must belong to the same task"
+        ) from exc
+    try:
+        validate_task_artifact_path(
+            report, expected_task_root, "selected direction report"
+        )
+        return resolve_selected_direction(
+            report,
+            expected_task_key=(
+                f"{inp.project_id}:{inp.task_group}:{inp.task_id}"
+            ),
+        )
+    except DirectionSelectionError as exc:
+        raise PrepareError(str(exc)) from exc
+
+
 def _validate_reverify_scope(inp: PrepareInputs) -> None:
     """A pinned re-verification scope is only actionable on a planning re-run.
 
@@ -1070,8 +1249,165 @@ def _validate_reverify_scope(inp: PrepareInputs) -> None:
         raise PrepareError(str(exc)) from exc
 
 
+def _implementation_plan_contract(
+    inp: PrepareInputs,
+) -> tuple[str, Path, dict | None]:
+    """Classify an implementation plan from its sibling data.json contract."""
+    plan_path = Path(inp.approved_plan_path)
+    body = plan_path.read_text(encoding="utf-8", errors="replace")
+    frontmatter = _extract_frontmatter_block(body) or ""
+    markdown_ref_match = SELECTED_DIRECTION_FRONTMATTER_PATTERN.search(frontmatter)
+    markdown_ref: str | None = None
+    if markdown_ref_match is not None:
+        markdown_ref = markdown_ref_match.group(1).strip()
+        if markdown_ref.startswith('"'):
+            try:
+                markdown_ref = json.loads(markdown_ref)
+            except json.JSONDecodeError as exc:
+                raise PrepareError(
+                    "selected-direction plan markdown `selected-direction-ref` is "
+                    "not a valid quoted string"
+                ) from exc
+        elif len(markdown_ref) >= 2 and markdown_ref[0] == markdown_ref[-1] == "'":
+            markdown_ref = markdown_ref[1:-1].replace("''", "'")
+        if not isinstance(markdown_ref, str) or not markdown_ref.strip():
+            raise PrepareError(
+                "selected-direction plan markdown `selected-direction-ref` must "
+                "be a non-empty string"
+            )
+    loaded = _load_final_report_data_if_present(plan_path)
+    if loaded is None:
+        if markdown_ref_match is not None:
+            raise PrepareError(
+                "selected-direction plan requires its sibling data.json before "
+                f"implementation entry: {_final_report_data_path(plan_path)}"
+            )
+        return "legacy", plan_path, None
+    _, data = loaded
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        raise PrepareError(
+            "approved plan sibling data.json must contain an "
+            "implementationPlanning object"
+        )
+    contract = planning.get("planningContract")
+    selected_payload = any(
+        field in planning
+        for field in (
+            "selectedDirectionRef",
+            "directionRealization",
+            "directionInvalidation",
+            "outcome",
+        )
+    )
+    if contract is None:
+        if markdown_ref_match is not None or selected_payload:
+            raise PrepareError(
+                "selected-direction markers require "
+                "implementationPlanning.planningContract=`selected-direction`; "
+                "the markdown `selected-direction-ref` and data contract disagree"
+            )
+        return "legacy", plan_path, data
+    if contract != "selected-direction":
+        raise PrepareError(
+            "approved plan sibling data.json has unsupported planningContract "
+            f"{contract!r}"
+        )
+    if markdown_ref_match is None:
+        raise PrepareError(
+            "selected-direction plan markdown frontmatter must contain "
+            "`selected-direction-ref:`"
+        )
+    selected_ref = planning.get("selectedDirectionRef")
+    snapshot_ref = (
+        selected_ref.get("snapshotPath")
+        if isinstance(selected_ref, dict)
+        else None
+    )
+    if not isinstance(markdown_ref, str) or markdown_ref != snapshot_ref:
+        raise PrepareError(
+            "selected-direction plan markdown `selected-direction-ref` must "
+            "exactly match implementationPlanning.selectedDirectionRef.snapshotPath"
+        )
+    if IMPLEMENTATION_OPTION_FRONTMATTER_PATTERN.search(frontmatter):
+        raise PrepareError(
+            "selected-direction plan must not contain an `implementation-option:` "
+            "frontmatter field"
+        )
+    return "selected-direction", plan_path, data
+
+
+def _validate_selected_implementation_plan(
+    inp: PrepareInputs,
+    plan_path: Path,
+    data: dict,
+) -> None:
+    """Apply the Task 8 selected-direction semantics at implementation entry."""
+    planning = data.get("implementationPlanning") or {}
+    if planning.get("outcome") != "plan-ready":
+        raise PrepareError(
+            "selected-direction plan is not implementation-ready: "
+            f"outcome={planning.get('outcome')!r}; direction-invalidated plans "
+            "must re-enter implementation-option-selection"
+        )
+    summary = planning.get("coverageSummary") or {}
+    if summary.get("coverageVerdict") != "exact":
+        raise PrepareError(
+            "selected-direction plan requires exact coverage before implementation"
+        )
+
+    from .paths import task_dir
+
+    expected_task_root = lexical_absolute_path(
+        task_dir(Path(inp.project_root), inp.task_group, inp.task_id)
+    )
+    try:
+        validate_task_artifact_path(plan_path, expected_task_root, "approved plan")
+        data_path = validate_task_artifact_path(
+            _final_report_data_path(plan_path),
+            expected_task_root,
+            "approved plan data.json",
+        )
+        if data_path != _final_report_data_path(plan_path):
+            raise DirectionSelectionError("approved plan data.json must be a sibling")
+        snapshot_path = validate_task_artifact_path(
+            expected_task_root / "instruction-set" / "selected-direction.json",
+            expected_task_root,
+            "selected direction snapshot",
+        )
+        brief_path = validate_task_artifact_path(
+            expected_task_root / "instruction-set" / "task-brief.md",
+            expected_task_root,
+            "selected direction task brief",
+        )
+    except DirectionSelectionError as exc:
+        raise PrepareError(f"selected-direction plan input is invalid: {exc}") from exc
+
+    expected_task_key = f"{inp.project_id}:{inp.task_group}:{inp.task_id}"
+    actual_task_key = (data.get("header") or {}).get("taskKey")
+    if actual_task_key != expected_task_key:
+        raise PrepareError(
+            "selected-direction plan header.taskKey must match the implementation "
+            f"task: expected {expected_task_key!r}, got {actual_task_key!r}"
+        )
+    failures = validate_selected_direction_plan(data, brief_path, snapshot_path)
+    if failures:
+        raise PrepareError(
+            "selected-direction plan failed implementation entry validation:\n  - "
+            + "\n  - ".join(failures)
+        )
+
+
 def _prepare_implementation_approved_plan(inp: PrepareInputs) -> list:
     """Apply approved-plan inputs only after canonical brief preflight succeeds."""
+    contract, plan_path, data = _implementation_plan_contract(inp)
+    if contract == "selected-direction":
+        assert data is not None
+        _validate_selected_implementation_plan(inp, plan_path, data)
+        if inp.implementation_option:
+            raise PrepareError(
+                "--implementation-option is not accepted for a selected-direction plan"
+            )
     if inp.approve_plan_ack or inp.implementation_option:
         with worktree_provision_mutex(
             okstra_home(), inp.project_id,
@@ -1083,7 +1419,11 @@ def _prepare_implementation_approved_plan(inp: PrepareInputs) -> list:
                 _apply_cli_implementation_option(
                     inp.approved_plan_path, inp.implementation_option
                 )
+    contract, plan_path, data = _implementation_plan_contract(inp)
     _validate_approved_plan(inp.approved_plan_path)
+    if contract == "selected-direction":
+        assert data is not None
+        _validate_selected_implementation_plan(inp, plan_path, data)
     _validate_stage_structure(inp.approved_plan_path)
     return _parse_stage_map_into_ctx(inp.approved_plan_path)
 
@@ -1348,9 +1688,23 @@ def _resolve_roster(inp: PrepareInputs, profile_file: Path) -> tuple[list[str],
         validate_workers_against_profile(workers, profile_workers, optional_workers)
     if not workers:
         raise PrepareError(f"no workers resolved for profile: {inp.task_type}")
+    _validate_option_selection_roster(inp.task_type, workers)
     return workers, ",".join(workers)
 
 
+def _validate_option_selection_roster(
+    task_type: str, workers: Sequence[str]
+) -> None:
+    """Require independent analysis from three workers before option selection."""
+    if task_type != "implementation-option-selection":
+        return
+    analyser_count = sum(worker != "report-writer" for worker in workers)
+    if analyser_count < 3:
+        raise PrepareError(
+            "implementation-option-selection requires at least 3 analyser workers"
+        )
+
+
 def _resolve_pr_template(inp: PrepareInputs) -> tuple[str, str]:
     """release-handoff 전용 PR 본문 템플릿 경로 + 출처를 해소한다 (그 외엔 빈 값)."""
     if inp.task_type != "release-handoff":
@@ -1987,11 +2341,17 @@ def _write_instruction_set_sources(
     profile_content: str,
     review_material: str,
     host_rules_file: Path | None,
+    selected_direction: SelectedDirection | None,
 ) -> Path:
     """instruction-set 디렉터리에 profile/material/brief/clarification/directive 와
     reference-expectations 를 기록하고 디렉터리 경로를 돌려준다."""
     instruction_set = Path(ctx["INSTRUCTION_SET_PATH"])
     instruction_set.mkdir(parents=True, exist_ok=True)
+    if selected_direction is not None:
+        write_selected_direction_snapshot(
+            selected_direction,
+            instruction_set / "selected-direction.json",
+        )
     _write_analysis_evidence_artifact(ctx, instruction_set)
     _write_verification_target_artifact(inp, ctx, instruction_set)
     _write_prior_run_error_digest(ctx, instruction_set)
@@ -2252,6 +2612,7 @@ def _persist_run_inputs(
             "relatedTasks": inp.related_tasks_raw,
             "approvedPlanPath": approved_plan_path,
             "clarificationResponsePath": inp.clarification_response_path,
+            "selectedDirectionPath": inp.selected_direction_path,
             "analysisTarget": json.loads(ctx.get("ANALYSIS_TARGET_JSON", "{}")).get(
                 "requestedValue", ""
             ),
@@ -2796,6 +3157,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
             inp.brief_path,
             assets.brief_validator,
         )
+    selected_direction = _resolve_planning_direction(inp)
     if inp.task_type == "implementation":
         ctx_stage_map = _prepare_implementation_approved_plan(inp)
 
@@ -2929,6 +3291,10 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         relative_to_project_root(Path(inp.clarification_response_path), project_root)
         if inp.clarification_response_path else ""
     )
+    selected_direction_relative = (
+        relative_to_project_root(Path(inp.selected_direction_path), project_root)
+        if inp.selected_direction_path else ""
+    )
 
     forbidden_by_phase = load_phase_forbidden(workspace_root)
 
@@ -2946,6 +3312,8 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "CLAUDE_SESSION_ID": claude_session_id,
         "CLARIFICATION_RESPONSE_PATH": inp.clarification_response_path,
         "CLARIFICATION_RESPONSE_RELATIVE_PATH": clarification_relative,
+        "SELECTED_DIRECTION_PATH": inp.selected_direction_path,
+        "SELECTED_DIRECTION_RELATIVE_PATH": selected_direction_relative,
         **_reverify_scope_ctx(inp.reverify_scope),
         "BRIEF_FILE_PATH": str(inp.brief_path),
         "BRIEF_RELATIVE_PATH": brief_relative,
@@ -2978,7 +3346,12 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
 
     # ---- write instruction-set scaffolding ----
     instruction_set = _write_instruction_set_sources(
-        inp, ctx, profile_content, review_material, assets.host_rules_file
+        inp,
+        ctx,
+        profile_content,
+        review_material,
+        assets.host_rules_file,
+        selected_direction,
     )
     # ---- run-inputs persistence ----
     _persist_run_inputs(inp, ctx, models, selected_reviewers, brief_relative)
@@ -3134,6 +3507,7 @@ def main(argv: list[str]) -> int:
         ),
     )
     p.add_argument("--clarification-response", default="", dest="clarification_response_path")
+    p.add_argument("--selected-direction", default="", dest="selected_direction_path")
     p.add_argument(
         "--reverify-scope",
         default="",
@@ -3212,7 +3586,9 @@ def main(argv: list[str]) -> int:
             return 1
     clarification_abs = ""
     if args.clarification_response_path:
-        cr = resolve_user_file(args.clarification_response_path, project_root)
+        cr = _resolve_planning_input_path(
+            args.clarification_response_path, project_root
+        )
         if cr is None:
             print(
                 f"clarification response file not found: {args.clarification_response_path}",
@@ -3220,6 +3596,18 @@ def main(argv: list[str]) -> int:
             )
             return 1
         clarification_abs = str(cr)
+    selected_direction_abs = ""
+    if args.selected_direction_path:
+        selected = _resolve_planning_input_path(
+            args.selected_direction_path, project_root
+        )
+        if selected is None:
+            print(
+                f"selected direction report not found: {args.selected_direction_path}",
+                file=__import__("sys").stderr,
+            )
+            return 1
+        selected_direction_abs = str(selected)
 
     inputs = PrepareInputs(
         workspace_root=Path(args.workspace_root).resolve(),
@@ -3254,6 +3642,7 @@ def main(argv: list[str]) -> int:
         stage=args.stage,
         stages=args.stages,
         clarification_response_path=clarification_abs,
+        selected_direction_path=selected_direction_abs,
         reverify_scope=args.reverify_scope,
         pr_template_path=args.pr_template_path,
         render_only=args.render_only,

package/runtime/python/okstra_ctl/schema_excerpt.py

@@ -1,6 +1,6 @@
 """Build a task-type-scoped excerpt of the final-report schema.
 
-The full schema (``schemas/final-report-v1.0.schema.json``) carries the
+The full schema (``schemas/final-report-v2.0.schema.json``) carries the
 deliverable property blocks for ALL task-types (``errorAnalysis``, the three
 read-only analysis blocks, ``implementationPlanning``, ``releaseHandoff``,
 ``implementation``, and ``finalVerification``) plus a

package/runtime/python/okstra_ctl/scope_provenance.py

@@ -21,7 +21,7 @@ CONTRACT_RULES = frozenset(
 )
 
 # Mirrors the report schema's requirement id pattern
-# (schemas/final-report-v1.0.schema.json: `^R-\d{3,}$`).
+# (schemas/final-report-v2.0.schema.json: `^R-\d{3,}$`).
 _REQ_ID_RE = re.compile(r"^R-\d{3,}$")
 _BRIEF_RE = re.compile(r"^brief:\s*(?P<heading>.+?)\s*$")
 _DERIVED_RE = re.compile(r"^derived:\s*(?P<parent>\S+)\s*[—-]\s*(?P<reason>.+?)\s*$")
@@ -89,8 +89,8 @@ 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.
+def brief_end_state_id_sequence(brief_path: Path) -> tuple[str, ...]:
+    """End-state ids the brief declares, preserving section and item order.
 
     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
@@ -106,16 +106,17 @@ def brief_end_state_ids(brief_path: Path) -> set[str]:
     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.
+    An empty sequence 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()
+        return ()
 
-    ids: set[str] = set()
+    ids: list[str] = []
     section = ""
     for line in text.splitlines():
         if m := _SECTION_HEADING_RE.match(line):
@@ -125,8 +126,13 @@ def brief_end_state_ids(brief_path: Path) -> set[str]:
         if not section:
             continue
         if m := _END_STATE_BULLET_RE.match(line.strip()):
-            ids.add(m.group("id"))
-    return ids
+            ids.append(m.group("id"))
+    return tuple(ids)
+
+
+def brief_end_state_ids(brief_path: Path) -> set[str]:
+    """End-state ids the brief declares, across all three sections."""
+    return set(brief_end_state_id_sequence(brief_path))
 
 
 @dataclass(frozen=True)