okstra 0.151.1 → 0.153.0

package/runtime/bin/okstra-wrapper-agy-stream.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Split `agy --output-format stream-json` output for okstra-antigravity-exec.sh.
+
+Everything agy emits is appended to the live log, so the log becomes an audit
+trail of what the worker actually did — which tools it called, on which paths,
+for how long. In the default `text` format agy prints only its closing summary,
+so an antigravity dispatch left ~2KB of self-report against codex's ~487KB of
+tool trace, and whether the worker ever opened the evidence it was asked to
+verify could not be checked from outside.
+
+stdout stays what the dispatcher's contract expects: the final response text
+only, so the subagent's captured output is unchanged by the format switch.
+"""
+from __future__ import annotations
+
+import json
+import sys
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print("usage: okstra-wrapper-agy-stream.py <log-path>", file=sys.stderr)
+        return 2
+    log_path = sys.argv[1]
+    final: str | None = None
+    # Lines agy emitted that are not stream-json events. Normally empty; kept so
+    # a non-JSON emitter (a stub, an older agy, a crash banner) still reaches
+    # stdout instead of being silently swallowed.
+    passthrough: list[str] = []
+    with open(log_path, "a", encoding="utf-8") as log:
+        for line in sys.stdin:
+            log.write(line)
+            log.flush()
+            stripped = line.strip()
+            if not stripped:
+                continue
+            try:
+                event = json.loads(stripped)
+            except json.JSONDecodeError:
+                passthrough.append(line)
+                continue
+            if isinstance(event, dict) and event.get("event") == "result":
+                result = event.get("result")
+                if isinstance(result, dict):
+                    final = result.get("response") or ""
+    if final is not None:
+        sys.stdout.write(final)
+    elif passthrough:
+        sys.stdout.writelines(passthrough)
+    else:
+        print(
+            "okstra-wrapper-agy-stream: no result event in agy output — "
+            f"see {log_path}",
+            file=sys.stderr,
+        )
+    sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/prompts/lead/convergence.md

@@ -204,7 +204,8 @@ hard_refutes = [v for v in disagrees if v.disagreeBasis == "counter-evidence"]
 all_others_disagree = (every non-discoverer non-error vote is "disagree")
 
 IF len(disagrees) == 0:
-    resolve F as "full-consensus"   (or "partial-consensus" if any SUPPLEMENT/caveat)
+    resolve F as "partial-consensus" if SUPPLEMENT/caveat votes are a majority of
+    non-error votes, otherwise "full-consensus"
 ELIF all_others_disagree:
     resolve F as "worker-unique"    # only the discoverer still holds it
 ELIF len(hard_refutes) >= 1:
@@ -219,7 +220,7 @@ ELSE:
 
 `contested` remains a **final classification only** (per §"Scope and Terminology"): a disputed finding is carried forward through intermediate rounds and labelled `contested` only at the last executed round. For `requirements-discovery` (`effectiveMaxRounds = 1`) the single round IS the last round, so a split-with-hard-refute finding is labelled `contested` in that one round. The final-classifier block of §"Convergence Algorithm" honours this: its first branch classifies an adversarially carried-forward finding `contested` regardless of the AGREE tally, so the two sections cannot assign the same finding different labels.
 
-Design intent: one `counter-evidence` refute denies a claim consensus (it cannot rise above `contested` however many others AGREE); later-round agreement does not erase that refutation history. The only resolution that overrides prior `counter-evidence` is a later round where every non-discoverer non-error worker disagrees, producing `worker-unique`. A lone `burden-not-met` doubt does not sink an otherwise-surviving claim — only a majority of them does. When every non-discoverer refutes (all_others_disagree) the finding is worker-unique regardless of refute basis — only the discoverer still holds it. A SUPPLEMENT/caveat with zero disagrees lands partial-consensus, not full-consensus, because a caveat means the claim does not pass cleanly (unlike the collaborative classifier, where SUPPLEMENT counts as full agreement).
+Design intent: one `counter-evidence` refute denies a claim consensus (it cannot rise above `contested` however many others AGREE); later-round agreement does not erase that refutation history. The only resolution that overrides prior `counter-evidence` is a later round where every non-discoverer non-error worker disagrees, producing `worker-unique`. A lone `burden-not-met` doubt does not sink an otherwise-surviving claim — only a majority of them does. When every non-discoverer refutes (all_others_disagree) the finding is worker-unique regardless of refute basis — only the discoverer still holds it. A caveat is weighed the same way a weak doubt is: with zero disagrees, SUPPLEMENT lands partial-consensus only when caveats are a **majority** of the non-error votes. A single verifier's scope note does not by itself deny a claim the rest of the roster passed cleanly — the caveat is still recorded in the dissent log either way, so the majority rule changes the label, never the record. (The collaborative classifier is more permissive still: there SUPPLEMENT counts as full agreement at any count.)
 
 ## Re-verification Dispatch
 

package/runtime/prompts/lead/plan-body-verification.md

@@ -194,7 +194,7 @@ Plan-body verification stays **lightweight** even under this posture — the `ve
    **Record the cause, not just the outcome.** The gate value names the outcome; `planBodyVerification.gateBlockedBy` (array) names every input that blocked it — `majority-disagree`, `coverage-gap`, `non-result`. Two independent inputs can block: a `majority-disagree` plan item, and a Requirement Coverage `gap` / `blocked C-NNN` row (`prompts/profiles/implementation-planning.md` §"Requirement Coverage"). A coverage-only block still renders as `blocked-by-disagreement` because that is the only blocking non-abort value, so **without `gateBlockedBy` the report asserts a worker disagreement that never happened** and the reader hunts for a dissent that does not exist. Leave the array empty for a passing gate. **Enforced:** `validators/validate-run.py` `_validate_gate_blocked_by` cross-checks the declared causes against the recorded verdicts and coverage rows, and fails a passing gate that has a blocking coverage row — the coverage rule was prose-only before.
 
    **A coverage row citing this run's own `C-NNN` is not an independent blocker.** When a coverage row's `blocked C-NNN` points at a clarification that step 8 below promoted from a `majority-disagree` item in *this same run*, that blocker is already counted once as the plan item. Counting it again as a coverage gap makes the run block on a clarification it just authored, and the row carries into the next run as a fresh blocker — the Requirement Coverage ↔ Clarification cycle. Such rows are excluded from `coverage-gap`. **Enforced:** `validators/validate-run.py` `_independent_coverage_blockers`.
-6. Lead records `planBodyVerification.participatingAnalysers` as `{rostered, voting}` — how many analysers the roster carried, and how many actually returned a non-error vote. The gate arithmetic is unchanged, but a shrunken roster loosens it silently: with two participating analysers a 1-AGREE / 1-DISAGREE split is a tie, so it never reaches `majority-disagree` and the dissent passes as `dissent-isolated`. A reader comparing two runs' gate values cannot see that without this pair. **Enforced:** `validators/validate-run.py` `_validate_participating_analysers` recomputes `voting` from the recorded verdicts and fails a declared figure the table denies. Then lead writes `runs/<task-type>/state/plan-body-verification-<task-type>-<seq>.json` (schema below), **appending this round** — one new `roundHistory[]` entry plus this round's votes on each verified item's `planItems[].rounds[]`. The file accumulates across rounds; it is never truncated to the latest one. Lead then populates `### 5.5.9 Plan Body Verification` in the final report's data.json (`implementationPlanning.planBodyVerification`, schema `schemas/final-report-v1.0.schema.json`; template at `templates/reports/final-report.template.md`). The §5.5.9 body is **grouped by plan item**: `planItems[]`, each carrying its `id`, its plain-language `subject` (rendered as the item heading), an optional `sourceSection`, an optional `clarificationId` (the `C-<N>` this item blocks on when `majority-disagree`), and a `verdicts[]` list (`worker / verdict / breakageKind / note`) — one verdict row per worker under that item. The renderer prints three fixed legends (gate values, verdict tokens, breakage kinds a–f) so the reader can decode every cell without opening this spec. The older flat `#### Verdict details` table (`Plan item / Worker / …`, one row per plan-item × worker pair) is superseded by the grouped layout — it hid *what* each vote was about behind a bare `P-*` ID; the subject heading is the fix. The validator's `Plan Body Verification` + `Gate result:` substring checks still gate this section.
+6. Lead records `planBodyVerification.participatingAnalysers` as `{rostered, voting}` — how many analysers the roster carried, and how many actually returned a non-error vote. The gate arithmetic is unchanged, but a shrunken roster loosens it silently: with two participating analysers a 1-AGREE / 1-DISAGREE split is a tie, so it never reaches `majority-disagree` and the dissent passes as `dissent-isolated`. A reader comparing two runs' gate values cannot see that without this pair. **Enforced:** `validators/validate-run.py` `_validate_participating_analysers` recomputes `voting` from the recorded verdicts and fails a declared figure the table denies. That pair still counts only *whether* a worker voted: an analyser that answers the same verdict to every item is carried in `voting` as a third opinion while contributing no refutation signal, so the gate reads as a three-way cross-check backed by two. **Enforced (advisory):** `validators/validate-run.py` `_detect_uniform_verifier` reports any worker whose every vote in the round was one verdict, with its item count — it does not fail the run, because a unanimous round is also a legitimate outcome and no ratio separates the two reliably. Then lead writes `runs/<task-type>/state/plan-body-verification-<task-type>-<seq>.json` (schema below), **appending this round** — one new `roundHistory[]` entry plus this round's votes on each verified item's `planItems[].rounds[]`. The file accumulates across rounds; it is never truncated to the latest one. Lead then populates `### 5.5.9 Plan Body Verification` in the final report's data.json (`implementationPlanning.planBodyVerification`, schema `schemas/final-report-v1.0.schema.json`; template at `templates/reports/final-report.template.md`). The §5.5.9 body is **grouped by plan item**: `planItems[]`, each carrying its `id`, its plain-language `subject` (rendered as the item heading), an optional `sourceSection`, an optional `clarificationId` (the `C-<N>` this item blocks on when `majority-disagree`), and a `verdicts[]` list (`worker / verdict / breakageKind / note`) — one verdict row per worker under that item. The renderer prints three fixed legends (gate values, verdict tokens, breakage kinds a–f) so the reader can decode every cell without opening this spec. The older flat `#### Verdict details` table (`Plan item / Worker / …`, one row per plan-item × worker pair) is superseded by the grouped layout — it hid *what* each vote was about behind a bare `P-*` ID; the subject heading is the fix. The validator's `Plan Body Verification` + `Gate result:` substring checks still gate this section.
 7. **Self-fix loop (up to `selfFixMaxRounds`, targeting planner-fixable defects).** After aggregation, while at least one `majority-disagree` item has a majority of its `DISAGREE` verdicts at `fixability == planner-fixable`, lead runs self-fix rounds **before** promoting anything to the user:
    - **Group the targets by cause before instructing (BLOCKING).** Blocked items are usually several derivatives of one defect — one constant declared twice, one responsibility given two owners — and the coverage rows that cite them fail as a consequence, not independently. Lead MUST partition this round's targets into cause groups and instruct each group as **"remove this cause"**, naming the derivatives it accounts for. **Handing report-writer a bare item list is forbidden**: patched one at a time, each correction leaves the sibling sections still asserting the old value, so the next round re-finds the same family and the budget drains without converging. Record the partition in `planBodyVerification.selfFixGroups[]` (`round`, `causeSummary`, `itemIds`). One group per item is a legitimate outcome only when the items genuinely share no cause — recorded that way, it is a visible diagnosis rather than a skipped one. **Enforced:** `validators/validate-run.py` `_validate_self_fix_grouping` requires the partition, ties `selfFixRoundsApplied` to the highest recorded round, and fails any corrected item that belongs to no group.
    - lead instructs report-writer to rewrite the items in each cause group (NOT a full draft regeneration; procedure in [report-writer](./report-writer.md) §"Self-fix rewrite").
@@ -430,6 +430,35 @@ When `config.adversarial == true`, the lead prepends the adversarial framing fro
 
 The "Reverify prompt: required-reading suppression" rule in [convergence](./convergence.md) (lightweight mode does NOT inject a `[Required reading]` clause) applies here as well.
 
+## Re-verification rounds (round 2+) — carry the dissent forward (BLOCKING)
+
+The template above is the round-1 prompt. A round 2+ prompt exists to settle the *previous* round's dissent, so it MUST carry that dissent forward. Re-rendering the round-1 template alone is a contract violation: with no record of what was objected to, the dissenting worker restates its verdict unchanged and its peers re-judge from nothing, so the loop spends its whole `selfFixMaxRounds` budget re-deriving the same split. Telling the worker that a prior verdict "carries no weight" is the same defect stated as an instruction — prior dissent is evidence about the plan, and discarding it is what makes the round repeat.
+
+Changes from the round-1 template:
+
+- The heading reads `(round <N>)`.
+- Every re-dispatched item carries a `**Prior round dissent**` block, built from the state file's `planItems[].rounds[].votes` and the item's `selfFixNote`:
+
+  ```text
+  **Prior round dissent** (round <N-1>):
+  - <worker>: DISAGREE(<kind>) — <that worker's verbatim explanation>
+  - <worker>: SUPPLEMENT — <verbatim explanation>
+  **What the planner changed**: <the item's selfFixNote, or "no correction — this item's
+  text shifted under a neighbouring rewrite">
+  ```
+
+  An item re-dispatched as `needs-reverify` (its peer returned a non-result, so nothing was objected to) carries the block with `- none — the peer vote was a non-result` in place of the verdict lines.
+
+- The `## Instructions` block gains this paragraph, which supersedes any "judge the corrected text on its own merits" framing:
+
+  > Each item below was objected to in the previous round, or its text shifted under a neighbouring correction. Read the prior dissent and the planner's correction before judging the CURRENT text. If you raised the prior objection and still DISAGREE, you MUST state what you re-opened after the rewrite and why the correction is insufficient — restating your previous explanation without engaging the correction is not a valid verdict. If the correction resolves your objection, say so and AGREE.
+
+- The response format gains one line per item, directly under `**Verdict**`:
+
+  `**Prior dissent**: resolved | unresolved | none — <which prior objection, and what the current text does about it>`
+
+**Enforced:** `validators/validate-run.py` `_validate_reverify_prompt_carries_dissent` fails a run whose `plan-verify-r<N>` (N ≥ 2) prompt file lacks the `**Prior round dissent**` block.
+
 ## Worker non-result handling in plan-body round (BLOCKING)
 
 Mirrors finding convergence ([convergence](./convergence.md) §"Worker failure handling in reverify"). Concretely:

package/runtime/prompts/profiles/implementation-planning.md

@@ -84,8 +84,12 @@
   - The plan lives in `data.json` under `implementationPlanning`, and `schemas/final-report-v2.0.schema.json` requires every one of these keys: `optionCandidates`, `tradeoffMatrix`, `recommendedOption`, `stageMap`, `stages`, `dependencyMigrationRisk`, `validationChecklist`, `rollbackStrategy`, `requirementCoverage`, `planBodyVerification`, `crossProjectDependencies`, `decisionDrafts`, `skippedAdrCandidates`, `variationPointAnalysis`, `userNarrative`. A missing block fails schema validation; there is nothing to satisfy by naming a heading. (Approval is not a body section — it is the YAML frontmatter `approved` field.)
   - Each `stages[]` entry requires `stage`, `title`, `sliceValue`, `acceptance`, `carryIn`, `stepwiseExecution` (1–6 rows), `exitContract`, and `stageValidation`. Each `stageMap[]` row requires `stage`, `title`, `dependsOn`, `stepCount`, `exitContractSummary`.
   - Beyond the schema, `validators/validate-run.py` reads the same data.json for `_validate_planning_conformance_declared`, `_validate_end_state_coverage`, `_validate_requirement_provenance`, `_validate_stage_has_requirement`, and `_validate_plan_body_state_file`. These run for every planning report regardless of schema version.
-  - **Do not chase English heading substrings.** `PLANNING_REQUIRED_SECTIONS` and the structural Stage Map scan (`validators/validate-implementation-plan-stages.py`) live inside `validate_phase_boundary`, which returns immediately when `schemaVersion == "2.0"` — they gate historical v1 Markdown only. The v2 AI-handoff template renders nine headings and serialises the plan as JSON beneath them, so those substrings cannot appear, and a report is not defective for lacking them.
-  - *Guideline, not gated:* write each `stepwiseExecution` row's `action` with a `RED:` / `GREEN:` prefix (or state a TDD exemption in `stageValidation`), and name the success / boundary / failure cases in `acceptance`. The v1 scan checked those tokens literally; v2 requires only that the fields be non-empty, so this is now review-enforced rather than validator-enforced.
+  - **Do not chase English heading substrings.** `PLANNING_REQUIRED_SECTIONS` and the Markdown scan in `collect_validation_errors` live inside `validate_phase_boundary`, which returns immediately when `schemaVersion == "2.0"` — they gate historical v1 Markdown only. The v2 AI-handoff template renders nine headings and serialises the plan as JSON beneath them, so those substrings cannot appear, and a report is not defective for lacking them.
+- Per-stage vertical slice and TDD contract (BLOCKING — enforced on the data, not on heading tokens):
+  - Every stage declares `sliceValue`, `acceptance`, and the three cases `testCaseSuccess` / `testCaseBoundary` / `testCaseFailure` — happy path, edge/boundary input, failure input. **Enforced:** the v2 schema's `if not tddExemption then require` conditional on `ImplementationPlanStage`.
+  - The first `stepwiseExecution` row's `action` starts with `RED:` and its `expected` reads FAIL; some later row's `action` starts with `GREEN:` and its `expected` reads PASS. **Enforced (S10c):** `collect_data_validation_errors` in `validators/validate-implementation-plan-stages.py`, run from `validate-run.py` `_append_stage_data_failures`.
+  - `tddExemption` waives both rules above, and only for `doc-only`, `config-only`, or `pure-rename` work. An empty or arbitrary reason waives nothing. **Enforced (S10e):** same function — the schema alone cannot reject it, because it types the field as a plain string and keys its conditional on the property merely being present.
+  - `stageMap[].dependsOn` must form a DAG (no self-dependency, no unknown stage, no cycle), each row's `stepCount` must equal its stage's actual `stepwiseExecution` row count, and two `(none)`-dependency stages must not name the same file in their `exitContract` — they run as concurrent implementation runs in separate worktrees. **Enforced (S8/S4/S9):** same function.
 - Required deliverable shape (final report, in addition to the standard sections):
   - at least two implementation options. **Each option must include**:
     - **File Structure**: an explicit list of files to create / modify / delete with each file's responsibility (one-line each). Use the form `Create: path — responsibility` / `Modify: path:line-range — change summary` / `Delete: path — reason`. Write every `path` in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...` / a trailing `/…`); an abbreviated path does not resolve and is rejected by plan-body verification as a kind-b path mismatch.

package/runtime/python/okstra_ctl/container.py

@@ -27,6 +27,7 @@ from pathlib import Path
 from typing import Callable, Iterable
 
 from .stage_targets import PrepareError  # 단일 PrepareError 타입 재노출(run.py 와 공유)
+from .stage_map import StageMapError, parse_stage_map_file, stage_map_records
 
 OKSTRA_LABEL_KEYS = ("okstra.task-key", "okstra.project-name", "okstra.run-trace")
 
@@ -530,16 +531,14 @@ def _resolve_up_inputs(project_root: Path, task_key: str) -> dict:
 
 
 def _plan_stage_map(approved_plan_path: str) -> list[dict]:
-    """approved-plan(implementation-planning final-report)에서 전체 stage 목록 파싱.
-
-    done 행만으로 합성하면 whole-task 완료 게이트(stage N not done)가 vacuous 해진다
-    — 게이트가 같은 done 집합을 기준으로 검사하기 때문. final-verification 과
-    동일한 파서(`_parse_stage_map_into_ctx`)를 써 계획에 선언된 미완 stage 를
-    container up 도 거부하게 한다(stage 1 만 done 인 3-stage task 를 '완성'으로
-    배포하지 않음). 빈/손상 Stage Map 거부는 `_parse_stage_map_into_ctx` 가
-    공통으로 수행한다."""
-    from .run import _parse_stage_map_into_ctx
-    return _parse_stage_map_into_ctx(approved_plan_path)
+    """Parse the approved plan's complete Stage Map for container gating."""
+    try:
+        return stage_map_records(parse_stage_map_file(Path(approved_plan_path)))
+    except StageMapError as exc:
+        raise PrepareError(
+            "approved-plan 의 Stage Map 을 신뢰할 수 없어 거부합니다 "
+            f"({approved_plan_path}): {exc.reason}. plan 의 Stage Map 을 점검하세요."
+        ) from exc
 
 
 def _verify_compose_present(worktree_root: Path) -> Path:

package/runtime/python/okstra_ctl/convergence_engine.py

@@ -191,9 +191,10 @@ def classify_adversarial_round(
         return None
     disagrees = [vote for vote in usable if vote["verdict"] == "disagree"]
     if not disagrees:
+        caveats = sum(vote["verdict"] == "supplement" for vote in usable)
         return (
             "partial-consensus"
-            if any(vote["verdict"] == "supplement" for vote in usable)
+            if caveats > len(usable) / 2
             else "full-consensus"
         )
     if len(disagrees) == len(usable):

package/runtime/python/okstra_ctl/handoff.py

@@ -15,6 +15,7 @@ from typing import Any, Callable, Dict, List, Optional, Tuple
 from . import consumers, stage_targets, worktree_registry
 from .final_report_paths import final_report_markdown_path
 from .paths import RunRef
+from .stage_map import StageMapError, parse_stage_map_file, stage_map_records
 from .worktree import (compute_branch_name, compute_worktree_path,
                        main_worktree_path, is_dirty_excluding_okstra,
                        nested_worktree_excludes, is_ancestor, merge_branch,
@@ -411,8 +412,6 @@ def _parse_stages_csv(raw: str) -> List[int]:
 def main(argv: Optional[list] = None) -> int:
     import argparse
 
-    from .run import _parse_stage_map_into_ctx, PrepareError
-
     p = argparse.ArgumentParser(prog="okstra handoff")
     sub = p.add_subparsers(dest="cmd", required=True)
 
@@ -458,14 +457,14 @@ def main(argv: Optional[list] = None) -> int:
     a = p.parse_args(argv)
     try:
         if a.cmd == "eligible":
-            stage_map = _parse_stage_map_into_ctx(a.approved_plan)
+            stage_map = stage_map_records(parse_stage_map_file(Path(a.approved_plan)))
             rows = consumers.read_consumers(Path(a.plan_run_root))
             out = {"stages": compute_eligibility(stage_map, rows)}
         elif a.cmd == "assemble":
             out = assemble(
                 project_root=Path(a.project_root).resolve(),
                 plan_run_root=Path(a.plan_run_root),
-                stage_map=_parse_stage_map_into_ctx(a.approved_plan),
+                stage_map=stage_map_records(parse_stage_map_file(Path(a.approved_plan))),
                 stages=_parse_stages_csv(a.stages), base_branch=a.base,
                 work_category=a.work_category, project_id=a.project_id,
                 task_group=a.task_group, task_id=a.task_id)
@@ -490,10 +489,7 @@ def main(argv: Optional[list] = None) -> int:
     except HandoffError as exc:
         print(json.dumps({"error": str(exc)}, ensure_ascii=False))
         return 1
-    except PrepareError as exc:
-        # _parse_stage_map_into_ctx 가 빈/손상 Stage Map 을 거부하면 PrepareError 가
-        # 오른다(HandoffError 의 형제 — 위 except 로 안 잡힘). JSON 계약을 깨고
-        # traceback 으로 죽지 않도록 error envelope + exit 1 로 처리한다.
+    except StageMapError as exc:
         print(json.dumps({"error": str(exc)}, ensure_ascii=False))
         return 1
     print(json.dumps(out, ensure_ascii=False, indent=2))

package/runtime/python/okstra_ctl/implementation_outcome.py

@@ -12,6 +12,7 @@ from .consumers import (
     read_stage_consumer_state,
 )
 from .paths import RunRef, task_manifest_file
+from .stage_map import StageMapError, load_task_stage_map
 from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
 
 
@@ -36,9 +37,15 @@ def derive_implementation_outcome(task_root: Path) -> ImplementationOutcome:
     if not plan_run_root.is_dir():
         return ImplementationOutcome(completed=False, reason="implementation-planning run root missing")
 
-    stage_map = load_stage_map(task_root, manifest)
-    if not stage_map:
-        return ImplementationOutcome(completed=False, reason="stage map unavailable")
+    try:
+        stage_snapshot = load_task_stage_map(task_root, manifest)
+    except StageMapError as exc:
+        return ImplementationOutcome(
+            completed=False, reason=f"{exc.code}: {exc.reason}"
+        )
+    if stage_snapshot.state == "missing":
+        return ImplementationOutcome(completed=False, reason="stage map missing")
+    stage_map = stage_snapshot.stages
 
     consumers = read_stage_consumer_state(plan_run_root, recover_from_carry=True)
     required_stages = {stage["stage_number"] for stage in stage_map}
@@ -114,59 +121,6 @@ def _load_json(path: Path) -> dict[str, Any]:
     return data if isinstance(data, dict) else {}
 
 
-def load_stage_map(task_root: Path, manifest: dict[str, Any]) -> list[dict[str, Any]]:
-    plan_path = _source_plan_path(task_root, manifest)
-    if not plan_path.is_file():
-        return []
-    from .run import PrepareError, _load_parsed_stage_map, _stage_map_reject_detail
-
-    try:
-        stages, errs = _load_parsed_stage_map(plan_path.read_text(encoding="utf-8"))
-    except PrepareError:
-        return []
-    if _stage_map_reject_detail(stages, errs) is not None:
-        return []
-    return [
-        {
-            "stage_number": stage.stage_number,
-            "title": stage.title,
-            "depends_on": list(stage.depends_on),
-            "step_count": stage.step_count,
-        }
-        for stage in stages
-    ]
-
-
-def _source_plan_path(task_root: Path, manifest: dict[str, Any]) -> Path:
-    carry_dir = RunRef.from_task_root(task_root, "implementation").carry_dir
-    for carry_path in sorted(carry_dir.glob("stage-*.json")):
-        value = _load_json(carry_path).get("sourcePlanPath")
-        if isinstance(value, str) and value:
-            return _resolve_relative(task_root, value)
-
-    latest = manifest.get("latestReportPath")
-    if isinstance(latest, str) and "implementation-planning" in latest:
-        return _resolve_relative(task_root, latest)
-
-    reports = RunRef.from_task_root(task_root, "implementation-planning").reports_dir
-    candidates = sorted(reports.glob("final-report-implementation-planning-*.md"))
-    return candidates[-1] if candidates else Path()
-
-
-def _resolve_relative(task_root: Path, value: str) -> Path:
-    path = Path(value)
-    if path.is_absolute():
-        return path
-    project_root = _project_root_from_task_root(task_root)
-    project_relative = project_root / path
-    if project_relative.exists():
-        return project_relative
-    task_relative = task_root / path
-    if task_relative.exists():
-        return task_relative
-    return project_relative
-
-
 def _project_root_from_task_root(task_root: Path) -> Path:
     parts = task_root.resolve().parts
     if ".okstra" not in parts:

package/runtime/python/okstra_ctl/model_discovery.py

@@ -30,6 +30,27 @@ def role_effort(role: str) -> str:
     return ROLE_EFFORT.get(role, _DEFAULT_EFFORT)
 
 
+# agy lists a tier per model, but the listed slug is not always the model it
+# serves: on agy 1.1.10 a `gemini-3.1-pro-high` session identifies itself as
+# "Gemini 3.6 Flash", while `gemini-3.1-pro-low` correctly identifies as
+# "Gemini 3.1 Pro". The substitution is not visible anywhere in the dispatch —
+# `agy models` lists the slug and the run exits 0 — so it surfaces only as a
+# verifier that never refutes anything: measured over one 63-item plan-body
+# prompt, the high slug returned all-AGREE in 64s while the low slug spent 328s
+# and raised three DISAGREEs, one of them the defect claude and codex both
+# caught that round. Only the `high` tier is affected, so a role asking for any
+# other effort still resolves normally (and a tier agy does not offer still
+# hard-fails below).
+_UNTRUSTED_HIGH_TIER_EXECUTIONS = frozenset({"gemini-3.1-pro"})
+
+
+def _dispatch_effort(execution: str, role: str) -> str:
+    effort = role_effort(role).lower()
+    if effort == "high" and execution in _UNTRUSTED_HIGH_TIER_EXECUTIONS:
+        return "low"
+    return effort
+
+
 @lru_cache(maxsize=1)
 def agy_models(agy_bin: str = "agy") -> tuple[str, ...]:
     """Live `agy models` list, or () when agy is unavailable (non-blocking)."""
@@ -91,7 +112,7 @@ def normalize_execution_for_dispatch(
     # (`gemini-3.1-pro-high`) and rejects the bare slug with "requires --effort"
     # — a flag the wrapper never sends. So the suffixed form is the only
     # dispatchable spelling, including on the un-verified fallback below.
-    tiered = f"{execution}-{role_effort(role).lower()}"
+    tiered = f"{execution}-{_dispatch_effort(execution, role)}"
     available = agy_models()
     if not available:
         return tiered  # discovery unavailable → dispatch anyway, wrapper still guards

package/runtime/python/okstra_ctl/plan_run_root.py

@@ -26,6 +26,17 @@ class PlanRun(NamedTuple):
     approved_plan_path: str
 
 
+def list_implementation_planning_reports(reports_dir: Path) -> list[Path]:
+    """Return numbered implementation-planning reports in latest-first order."""
+    numbered: list[tuple[int, Path]] = []
+    for report in reports_dir.glob("final-report-implementation-planning-*.md"):
+        match = _FINAL_REPORT_RE.fullmatch(report.name)
+        if match:
+            numbered.append((int(match.group(1)), report))
+    numbered.sort(key=lambda item: item[0], reverse=True)
+    return [report for _, report in numbered]
+
+
 def plan_run_root_from_approved_plan(approved_plan_path: str | Path) -> Path:
     """approved-plan(final-report) 경로에서 plan_run_root 를 역산한다.
 
@@ -58,21 +69,17 @@ def resolve_plan_run_root_by_task_key(
             f"({reports_dir} 없음). 먼저 implementation-planning 을 완료하거나 "
             "approved-plan 경로를 직접 지정하세요."
         )
-    candidates: list[tuple[int, Path, Path]] = []
-    for report in reports_dir.glob("final-report-implementation-planning-*.md"):
-        m = _FINAL_REPORT_RE.search(report.name)
-        if not m:
-            continue
+    candidates: list[tuple[Path, Path]] = []
+    for report in list_implementation_planning_reports(reports_dir):
         run_root = plan_run_root_from_approved_plan(report)
         done = [r for r in read_consumers(run_root) if r.get("status") == "done"]
         if done:
-            candidates.append((int(m.group(1)), run_root, report))
+            candidates.append((run_root, report))
     if not candidates:
         raise PrepareError(
             "container up: done 상태의 implementation-planning run 이 없습니다. "
             "stage 를 완료(implementation done)한 뒤 다시 시도하거나 approved-plan "
             "경로를 직접 지정하세요."
         )
-    candidates.sort(key=lambda c: c[0])
-    _, run_root, report = candidates[-1]
+    run_root, report = candidates[0]
     return PlanRun(run_root=run_root, approved_plan_path=str(report))

package/runtime/python/okstra_ctl/run.py

@@ -15,7 +15,6 @@ state passing, and are read once at the start.
 """
 from __future__ import annotations
 
-import importlib.util
 import hashlib
 import json
 import os
@@ -475,62 +474,17 @@ def _validate_stage_structure(plan_path: str) -> None:
 RUN_STEP_BUDGET = _stage_targets.RUN_STEP_BUDGET
 
 
-def _stage_map_reject_detail(stages, errs):
-    """빈/손상 Stage Map 의 거부 사유 문자열을 돌려준다. 정상이면 None.
-
-    빈/손상 Stage Map 을 흘려보내면 whole-task 완료 게이트
-    (`_resolve_whole_task_target`의 `for stage in stage_map`)가 0회 순회로 vacuous
-    통과해 미완 task 를 '완성'으로 배포·검증한다. 빈 파싱(heading rename·표 손상)과
-    stage 번호 비단조(중간 행 누락 → S2)의 판정을 한 곳에 모아, run.py 의 prepare
-    게이트와 wizard 의 stage picker 가 같은 기준을 상속하게 한다(single-reference)."""
-    if stages and not errs:
-        return None
-    return (
-        "; ".join(e.message for e in errs) if errs
-        else "'## 5.5 Stage Map' heading 이 없거나 표가 비었습니다")
-
-
-def _load_parsed_stage_map(text: str):
-    """validator 모듈을 로드해 `_parse_stage_map(text)` 의 (stages, errs) 를 돌려준다.
+def _parse_stage_map_into_ctx(plan_path: str) -> list:
+    """Parse the approved plan into context records for execution consumers."""
+    from .stage_map import StageMapError, parse_stage_map_file, stage_map_records
 
-    run.py 와 wizard 가 공유하는 단일 validator-load 경로 — 둘 다 `_STAGE_VALIDATOR_PATH`
-    (설치 시 `~/.okstra/lib/validators` 로 배치돼 `parents[2]/validators` 로 해소)로
-    수렴해 경로 해소가 갈라지지 않게 한다."""
-    spec = importlib.util.spec_from_file_location(
-        "_ip_stage_validator", _STAGE_VALIDATOR_PATH
-    )
-    if spec is None or spec.loader is None:
-        raise PrepareError(f"cannot load stage validator at {_STAGE_VALIDATOR_PATH}")
-    mod = importlib.util.module_from_spec(spec)
-    # Register before exec_module so dataclass field-type resolution can find
-    # the module in sys.modules (required on Python 3.9).
-    sys.modules["_ip_stage_validator"] = mod
     try:
-        spec.loader.exec_module(mod)
-        return mod._parse_stage_map(text)
-    finally:
-        sys.modules.pop("_ip_stage_validator", None)
-
-
-def _parse_stage_map_into_ctx(plan_path: str) -> list:
-    """Reuse the validator's parser to extract StageMeta dicts for the ctx."""
-    text = Path(plan_path).read_text(encoding="utf-8")
-    stages, errs = _load_parsed_stage_map(text)
-    detail = _stage_map_reject_detail(stages, errs)
-    if detail is not None:
+        return stage_map_records(parse_stage_map_file(Path(plan_path)))
+    except StageMapError as exc:
         raise PrepareError(
-            f"approved-plan 의 Stage Map 을 신뢰할 수 없어 거부합니다 ({plan_path}): "
-            f"{detail}. plan 의 Stage Map 을 점검하세요.")
-    return [
-        {
-            "stage_number": s.stage_number,
-            "title": s.title,
-            "depends_on": list(s.depends_on),
-            "step_count": s.step_count,
-            "exit_contract_summary": s.exit_contract_summary,
-        }
-        for s in stages
-    ]
+            "approved-plan 의 Stage Map 을 신뢰할 수 없어 거부합니다 "
+            f"({plan_path}): {exc.reason}. plan 의 Stage Map 을 점검하세요."
+        ) from exc
 
 
 def _apply_cli_approval(path: str) -> str: