okstra 0.52.0 → 0.54.0

package/runtime/python/okstra_ctl/wizard.py

@@ -36,6 +36,8 @@ from okstra_ctl.pr_template import PrTemplateError, resolve_pr_template_path
 from okstra_ctl.run import (
     APPROVED_FRONTMATTER_PATTERN,
     _extract_frontmatter_block,
+    _reject_blocking_plan_body_gate,
+    _validate_data_json_approval_consistency,
 )
 from okstra_ctl.workers import (
     ALLOWED_WORKERS,
@@ -77,6 +79,11 @@ TASK_TYPE_VALUES = [tt for tt, _ in TASK_TYPES]
 
 EXECUTORS = ["claude", "codex", "gemini"]
 
+# Task types that consume an approved plan and need a stage-scope pick:
+# implementation executes a stage, final-verification verifies a stage
+# (or the whole task via `auto`). Both gate the approved-plan + stage steps.
+_STAGE_SCOPED_TASK_TYPES = ("implementation", "final-verification")
+
 CANONICAL_BASE_REFS = ["main", "dev", "staging", "preprod", "prod"]
 BASE_REF_FREE_INPUT_TOKEN = "__free_input__"
 
@@ -410,6 +417,8 @@ def _validate_approved_plan(path_str: str, project_root: Path) -> Path:
             "  edit the report and change the line to `approved: true`, or re-run "
             "okstra with `--approve` to flip it from the CLI."
         )
+    _reject_blocking_plan_body_gate(p, body, action="approved plan validation")
+    _validate_data_json_approval_consistency(p, markdown_approved=True)
     # frontmatter approved == true 라도 §1 의 Blocks=approval 행이 미해결이면
     # 승인이 무효 — prepare_task_bundle 의 _validate_approved_plan 과 동일 규약.
     blockers = unresolved_approval_blockers(body)
@@ -1220,7 +1229,12 @@ def _build_stage_pick(state: WizardState) -> Prompt:
         stages, _errs = mod._parse_stage_map(plan_text)
     finally:
         _sys.modules.pop("_ip_stage_v_wizard", None)
-    options = [_opt(k, v) for k, v in t["options"].items()]
+    auto_label = (
+        t["options"].get("auto_final_verification", t["options"]["auto"])
+        if state.task_type == "final-verification"
+        else t["options"]["auto"]
+    )
+    options = [_opt("auto", auto_label)]
     for s in stages:
         depends = ",".join(map(str, s.depends_on)) or "(none)"
         options.append(_opt(
@@ -1969,7 +1983,7 @@ STEPS: list[Step] = [
          build=_build_base_ref_text, submit=_submit_base_ref_text,
          owns=("base_ref", "base_ref_pending_text")),
     Step(S_APPROVED_PLAN_PICK,
-         applies=lambda s: (s.task_type == "implementation"
+         applies=lambda s: (s.task_type in _STAGE_SCOPED_TASK_TYPES
                             and not s.approved_plan_path
                             and not s.approved_plan_pending_text
                             and S_APPROVED_PLAN_PICK not in s.answered
@@ -1981,7 +1995,7 @@ STEPS: list[Step] = [
          build=_build_approved_plan_pick, submit=_submit_approved_plan_pick,
          owns=("approved_plan_path", "approved_plan_pending_text")),
     Step(S_APPROVED_PLAN,
-         applies=lambda s: (s.task_type == "implementation"
+         applies=lambda s: (s.task_type in _STAGE_SCOPED_TASK_TYPES
                             and not s.approved_plan_path
                             and bool(s.brief_path)
                             and (s.reuse_worktree is True
@@ -1992,7 +2006,7 @@ STEPS: list[Step] = [
          build=_build_approved_plan, submit=_submit_approved_plan,
          owns=("approved_plan_path", "approved_plan_pending_text")),
     Step(S_STAGE_PICK,
-         applies=lambda s: (s.task_type == "implementation"
+         applies=lambda s: (s.task_type in _STAGE_SCOPED_TASK_TYPES
                             and bool(s.approved_plan_path)
                             and S_STAGE_PICK not in s.answered),
          build=_build_stage_pick, submit=_submit_stage_pick,
@@ -2155,8 +2169,11 @@ def _identity_ready(s: WizardState) -> bool:
         return False
     if s.base_ref_pending_text:
         return False
+    if s.task_type in _STAGE_SCOPED_TASK_TYPES:
+        if not s.approved_plan_path:
+            return False
     if s.task_type == "implementation":
-        if not s.approved_plan_path or not s.executor:
+        if not s.executor:
             return False
     return True
 
@@ -2350,7 +2367,7 @@ def render_args(state: WizardState) -> dict[str, str]:
         "executor": state.executor,
         "critic": state.critic,
         "approved-plan": state.approved_plan_path,
-        "stage": (state.selected_stage or "auto") if state.task_type == "implementation" else "",
+        "stage": (state.selected_stage or "auto") if state.task_type in _STAGE_SCOPED_TASK_TYPES else "",
         "base-ref": base_ref,
         "workers": workers,
         "directive": state.directive,
@@ -2395,8 +2412,9 @@ def confirmation_block(state: WizardState) -> str:
     lines.append(f"  directive     : {state.directive or '(none)'}")
     if state.task_type in ("requirements-discovery", "error-analysis", "implementation-planning", "final-verification"):
         lines.append(f"  critic        : {state.critic or '(off)'}")
-    if state.task_type == "implementation":
+    if state.task_type in _STAGE_SCOPED_TASK_TYPES:
         lines.append(f"  approved-plan : {state.approved_plan_path}")
+        lines.append(f"  stage         : {state.selected_stage or 'auto'}")
     if state.clarification_response_path:
         lines.append(f"  clarification : {state.clarification_response_path}")
     if state.task_type == "release-handoff" and state.pr_template_path:

package/runtime/python/okstra_ctl/worktree.py

@@ -491,30 +491,37 @@ def compute_worktree_path(
     project_id: str,
     task_group_segment: str,
     task_id_segment: str,
+    stage_number: Optional[int] = None,
 ) -> Path:
-    """Pure path computation. One worktree dir per task-key.
-
-    Uses `OKSTRA_HOME` when set (test hook), else `~/.okstra`. Note
-    there is NO run-seq segment — every phase of the same task-key
-    shares this dir.
-    """
+    """Pure path computation. One worktree dir per task-key, or per
+    `<task-key>/stage-<N>` when stage_number is given (implementation
+    stage isolation). Uses `OKSTRA_HOME` when set (test hook), else
+    `~/.okstra`."""
     okstra_home = os.environ.get("OKSTRA_HOME", "").strip()
     base = Path(okstra_home) if okstra_home else (Path.home() / ".okstra")
-    return (
+    path = (
         base / "worktrees"
         / _safe_segment(project_id)
         / _safe_segment(task_group_segment)
         / _safe_segment(task_id_segment)
     )
+    if stage_number is not None:
+        path = path / f"stage-{stage_number}"
+    return path
 
 
 def compute_branch_name(
     *,
     work_category: str,
     task_id_segment: str,
+    stage_number: Optional[int] = None,
 ) -> str:
-    """One branch per task-key. No run-seq — phases share the branch."""
-    return f"{_work_category_prefix(work_category)}-{_safe_segment(task_id_segment)}"
+    """One branch per task-key, or `<prefix>-<task-id>-s<N>` for an
+    implementation stage worktree."""
+    name = f"{_work_category_prefix(work_category)}-{_safe_segment(task_id_segment)}"
+    if stage_number is not None:
+        name = f"{name}-s{stage_number}"
+    return name
 
 
 def provision_task_worktree(
@@ -693,3 +700,113 @@ def provision_task_worktree(
             f"(base {base_label}; phase {task_type}){linked_suffix}"
         ),
     )
+
+
+def provision_stage_worktree(
+    *,
+    project_root: Path,
+    project_id: str,
+    task_group_segment: str,
+    task_id_segment: str,
+    work_category: str,
+    stage_number: int,
+    base_commit: str,
+) -> WorktreeProvision:
+    """Materialise an isolated worktree for one implementation stage.
+
+    Unlike `provision_task_worktree` (one worktree per task-key shared
+    across phases), this provisions a per-stage worktree branched from
+    `base_commit` at `<task-key>/stage-<N>/` on branch `<prefix>-<task>-s<N>`.
+    The stage-key (`<task-key>#stage-<N>`) is reserved atomically through
+    `worktree_registry`; re-entry of the same stage-key returns the
+    existing entry. Branch / on-disk conflicts roll back the worktree
+    before re-raising so a retry is not blocked.
+    """
+    if not base_commit:
+        raise RuntimeError("provision_stage_worktree requires a base_commit")
+
+    safe_project = _safe_segment(project_id)
+    safe_group = _safe_segment(task_group_segment)
+    safe_task = _safe_segment(task_id_segment)
+    worktree_path = compute_worktree_path(
+        project_id=safe_project, task_group_segment=safe_group,
+        task_id_segment=safe_task, stage_number=stage_number,
+    )
+    branch = compute_branch_name(
+        work_category=work_category, task_id_segment=safe_task,
+        stage_number=stage_number,
+    )
+
+    existing = worktree_registry.lookup(
+        safe_project, safe_group, safe_task, stage_number=stage_number)
+    if existing is not None and existing.status == "active":
+        return WorktreeProvision(
+            status="reused", path=existing.worktree_path,
+            branch=existing.branch, base_ref=existing.base_ref,
+            note=(
+                f"stage {stage_number} worktree reused at "
+                f"{existing.worktree_path} on branch {existing.branch} "
+                f"(base {existing.base_ref[:12]})"
+            ),
+        )
+
+    if worktree_path.exists():
+        raise RuntimeError(
+            f"stage worktree path already exists but is not in the registry: "
+            f"{worktree_path}. Remove it before retrying."
+        )
+    if _branch_exists(project_root, branch):
+        raise RuntimeError(
+            f"stage worktree branch already exists: {branch}. "
+            "Delete it (`git branch -D <branch>`) before retrying."
+        )
+
+    main_root = main_worktree_path(project_root)
+    resolved_sha = _resolve_commit_sha(main_root, base_commit)
+    if not resolved_sha:
+        raise RuntimeError(
+            f"could not resolve base_commit `{base_commit}` in main worktree "
+            f"({main_root}); ensure the commit exists locally"
+        )
+
+    worktree_path.parent.mkdir(parents=True, exist_ok=True)
+    res = _git(
+        main_root,
+        "worktree", "add", "-b", branch, str(worktree_path), resolved_sha,
+    )
+    if res.returncode != 0:
+        raise RuntimeError(
+            f"`git worktree add` failed (exit={res.returncode}): "
+            f"{(res.stderr or res.stdout).strip()}"
+        )
+
+    _link_sync_dirs(main_root, worktree_path)
+    _link_sync_files(main_root, worktree_path)
+    _copy_snapshot_files(main_root, worktree_path)
+
+    try:
+        worktree_registry.reserve(
+            project_id=safe_project,
+            task_group=safe_group,
+            task_id=safe_task,
+            worktree_path=str(worktree_path),
+            branch=branch,
+            base_ref=resolved_sha,
+            phase="implementation",
+            stage_number=stage_number,
+        )
+    except RuntimeError:
+        _git(main_root, "worktree", "remove", "--force", str(worktree_path))
+        _git(main_root, "branch", "-D", branch)
+        raise
+
+    _seed_worktree_settings_symlink(worktree_path)
+
+    return WorktreeProvision(
+        status="created", path=str(worktree_path),
+        branch=branch, base_ref=resolved_sha,
+        note=(
+            f"stage {stage_number} worktree created at {worktree_path} "
+            f"on branch {branch} (base {resolved_sha[:12]})"
+        ),
+    )

package/runtime/python/okstra_ctl/worktree_registry.py

@@ -43,15 +43,17 @@ def _okstra_worktrees_dir() -> Path:
     return base / "worktrees"
 
 
-def task_key(project_id: str, task_group: str, task_id: str) -> str:
-    """Canonical task-key string used as the registry primary key.
-
-    Segments are NOT re-slugified here — callers must pass already
-    sanitised segments (see `worktree._safe_segment`). The key form
-    `<project>/<group>/<task>` is the same shape used for filesystem
-    paths so a key can be visually correlated with the worktree dir.
-    """
-    return f"{project_id}/{task_group}/{task_id}"
+def task_key(
+    project_id: str, task_group: str, task_id: str,
+    stage_number: Optional[int] = None,
+) -> str:
+    """Canonical task-key. With stage_number, returns the stage-scoped
+    key `<proj>/<group>/<task>#stage-<N>` used to reserve a per-stage
+    worktree independently of the task-key entry."""
+    base = f"{project_id}/{task_group}/{task_id}"
+    if stage_number is not None:
+        return f"{base}#stage-{stage_number}"
+    return base
 
 
 @dataclass
@@ -66,6 +68,8 @@ class WorktreeEntry:
     created_at: str
     last_phase: str = ""
     status: str = "active"  # "active" | "released"
+    stage: Optional[int] = None
+    implementation_base_commit: str = ""
 
 
 @contextlib.contextmanager
@@ -112,13 +116,11 @@ def _save(data: dict) -> None:
     os.replace(tmp, p)
 
 
-def lookup(project_id: str, task_group: str, task_id: str) -> Optional[WorktreeEntry]:
-    """Return the registered entry for this task-key, or None.
-
-    Does not validate that `worktree_path` still exists on disk — that
-    is the caller's responsibility (so reclaim logic can decide policy).
-    """
-    key = task_key(project_id, task_group, task_id)
+def lookup(
+    project_id: str, task_group: str, task_id: str,
+    stage_number: Optional[int] = None,
+) -> Optional[WorktreeEntry]:
+    key = task_key(project_id, task_group, task_id, stage_number)
     with _registry_lock():
         data = _load()
         row = data["tasks"].get(key)
@@ -136,13 +138,14 @@ def reserve(
     branch: str,
     base_ref: str,
     phase: str = "",
+    stage_number: Optional[int] = None,
 ) -> WorktreeEntry:
     """Atomically insert a new entry. Raises RuntimeError if the
     task-key already exists or the branch is already owned by a
     different task-key. Callers should `lookup()` first when re-entry
     is expected.
     """
-    key = task_key(project_id, task_group, task_id)
+    key = task_key(project_id, task_group, task_id, stage_number)
     now = time.strftime("%Y-%m-%dT%H:%M:%S%z") or time.strftime("%Y-%m-%dT%H:%M:%S")
     with _registry_lock():
         data = _load()
@@ -170,6 +173,7 @@ def reserve(
             "created_at": now,
             "last_phase": phase,
             "status": "active",
+            "stage": stage_number,
         }
         data["tasks"][key] = row
         data["branches"][branch] = key
@@ -191,6 +195,73 @@ def touch_phase(project_id: str, task_group: str, task_id: str, phase: str) -> N
         _save(data)
 
 
+def set_implementation_base(
+    project_id: str, task_group: str, task_id: str, commit: str,
+) -> str:
+    """Fix the shared base commit for this task's implementation stages,
+    once. Idempotent: if already set, the existing value is returned and
+    `commit` is ignored (so two concurrent first-stage runs converge).
+    Raises RuntimeError when the task-key entry does not exist."""
+    key = task_key(project_id, task_group, task_id)
+    with _registry_lock():
+        data = _load()
+        row = data["tasks"].get(key)
+        if row is None:
+            raise RuntimeError(
+                f"no task-key entry to anchor implementation base: {key}"
+            )
+        already = row.get("implementation_base_commit")
+        if already:
+            return already
+        row["implementation_base_commit"] = commit
+        _save(data)
+        return commit
+
+
+def get_implementation_base(
+    project_id: str, task_group: str, task_id: str,
+) -> Optional[str]:
+    """Return the fixed implementation base commit, or None when unset /
+    task-key missing."""
+    key = task_key(project_id, task_group, task_id)
+    with _registry_lock():
+        data = _load()
+        row = data["tasks"].get(key)
+        if row is None:
+            return None
+        return row.get("implementation_base_commit") or None
+
+
+def get_stage_row(
+    project_id: str, task_group: str, task_id: str, stage: int,
+) -> Optional[dict]:
+    """Return the stage-key registry row (worktree_path / base_ref / branch)
+    for `<task-key>#stage-<stage>`, or None when no such reservation exists."""
+    key = task_key(project_id, task_group, task_id, stage)
+    with _registry_lock():
+        data = _load()
+        return data["tasks"].get(key)
+
+
+def list_active_stage_numbers(
+    project_id: str, task_group: str, task_id: str,
+) -> set:
+    """Return the set of stage numbers with an active stage-key reservation
+    for this task. Used by the stage resolver to exclude stages a concurrent
+    run already holds (the occupancy SSOT). Excludes the task-key entry
+    (stage is None) and released entries."""
+    prefix = task_key(project_id, task_group, task_id) + "#stage-"
+    with _registry_lock():
+        data = _load()
+        out = set()
+        for key, row in data["tasks"].items():
+            if (key.startswith(prefix)
+                    and row.get("status") == "active"
+                    and row.get("stage") is not None):
+                out.add(row["stage"])
+        return out
+
+
 def release(project_id: str, task_group: str, task_id: str) -> Optional[WorktreeEntry]:
     """Mark the entry as `released` (worktree dir intact — preservation
     is the project's policy). The branch index is freed so future

package/runtime/schemas/final-report-v1.0.schema.json

@@ -117,6 +117,8 @@
       }
     },
 
+    "verificationScope": { "enum": ["whole-task", "single-stage"] },
+
     "clarificationCarryIn": {
       "type": "object",
       "description": "RENDER_IF non-empty. Carry-in clarifications from the previous run.",
@@ -337,6 +339,7 @@
         "dependencyMigrationRisk",
         "validationChecklist",
         "rollbackStrategy",
+        "requirementCoverage",
         "planBodyVerification"
       ],
       "additionalProperties": false,
@@ -371,6 +374,11 @@
           "minItems": 1,
           "items": { "$ref": "#/$defs/RollbackRow" }
         },
+        "requirementCoverage": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/ImplementationRequirementCoverageRow" }
+        },
         "planBodyVerification": { "$ref": "#/$defs/PlanBodyVerification" }
       }
     },
@@ -565,6 +573,18 @@
             "gitDiffStat": { "type": "string" }
           }
         },
+        "stageReports": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["stage", "reportPath"],
+            "properties": {
+              "stage": { "type": "integer" },
+              "reportPath": { "type": "string" }
+            }
+          }
+        },
         "acceptanceBlockers": {
           "type": "array",
           "items": { "$ref": "#/$defs/AcceptanceBlockerRow" }
@@ -1294,6 +1314,22 @@
       }
     },
 
+    "ImplementationRequirementCoverageRow": {
+      "type": "object",
+      "required": ["id", "source", "requirement", "coveredBy", "status"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^R-\\d{3,}$" },
+        "source": { "type": "string", "minLength": 1 },
+        "requirement": { "type": "string", "minLength": 1 },
+        "coveredBy": { "type": "string", "minLength": 1 },
+        "status": {
+          "type": "string",
+          "pattern": "^(covered|gap|blocked C-\\d{3,})$"
+        }
+      }
+    },
+
     "ReadonlyCommandRow": {
       "type": "object",
       "required": ["number", "tier", "command", "status", "exitCode", "outputTail"],

package/runtime/skills/okstra-convergence/SKILL.md

@@ -639,6 +639,7 @@ From the report-writer's draft of `## 5.5 Implementation Plan Deliverables`, lea
 | `P-Dep-<N>` | `4.5.5 Dependency / Migration Risk` | one dependency row |
 | `P-Val-<N>` | `4.5.6 Validation Checklist` | one checklist item |
 | `P-Rb-<N>` | `4.5.7 Rollback Strategy` | one rollback path |
+| `P-Req-<N>` | `4.5.8 Requirement Coverage` | one requirement coverage row |
 
 `4.5.2 Trade-off Matrix` and `4.5.3 Recommended Option` are NOT extracted as standalone plan items — the trade-off matrix is evaluated implicitly through each option's `P-Opt-*` verification, and the recommended option is one of those `P-Opt-*` rows.
 
@@ -655,6 +656,7 @@ The verdict tokens `AGREE` / `DISAGREE` / `SUPPLEMENT` are reused, but their mea
   - `c` — validation signal is not observable
   - `d` — rollback violates commit / dependency order
   - `e` — item contradicts the trade-off matrix
+  - `f` — requirement coverage row cites no concrete option / stage / step, cites a non-existent option / stage / step, or marks a requirement `covered` while the cited plan item does not satisfy the row's stated requirement
 - **SUPPLEMENT**: the item is sound but is missing a dependency / edge case / precondition.
 
 Worker non-result handling (`timeout`, `error`, no result file, wrapper `cli-failure`) is identical to finding convergence: do NOT aggregate as DISAGREE, record `contract-violation`, and apply the round-level abort rule below.
@@ -663,6 +665,8 @@ Worker non-result handling (`timeout`, `error`, no result file, wrapper `cli-fai
 
 Plan-body verification only supports **lightweight mode** (defined in §"Verification Mode" above). `full-reanalysis` is not meaningful here because the "original source materials" for a plan item are the worker's own analysis plus the lead-mediated synthesis — there is no independent ground truth to re-read. The manifest's top-level `verificationMode` is ignored for this round; lightweight is always used.
 
+Exception for `P-Req-*`: verifiers still MUST NOT re-open the original task brief for this round, but they MUST compare the requirement text embedded in the `Requirement Coverage` row with the cited Option / Stage / Step in the draft plan. A row is not sound merely because it says `covered`; the cited plan item must actually satisfy the stated requirement.
+
 ### Adversarial plan-body posture
 
 When `config.adversarial == true` (the default for `implementation-planning`; see the top-level §"Configuration" table), the plan-body round runs with an **adversarial posture**. The classification rules and gate arithmetic in §"Round protocol" are UNCHANGED — `majority-disagree` (a *majority* of analysers DISAGREE) remains the only classification that blocks the Approval marker, and `dissent-isolated` still passes the gate. Adversarial mode changes only *how each verifier evaluates an item*:
@@ -670,6 +674,7 @@ When `config.adversarial == true` (the default for `implementation-planning`; se
 - The burden of proof sits on the plan: an item earns `AGREE` only if the verifier actively tried to break it and could not.
 - The verifier MUST open the file paths / symbols / commands the item cites and confirm they exist and are executable as written. This is the one allowed widening of the lightweight "judge from internal consistency and stated commands / paths" rule — confirming the existence of cited paths is not "re-analyzing the original requirements".
 - If a cited path / command / validation signal cannot be confirmed, the verifier responds `DISAGREE(<kind>)` with the applicable breakage kind (a–e); uncertainty resolves toward DISAGREE, not AGREE.
+- For `P-Req-*` items, a single `DISAGREE(f)` is approval-blocking even in a two-worker roster. Requirement coverage is a hard gate: one verified contradiction between a requirement row and its cited plan item creates a `majority-disagree` classification for gate purposes and MUST become a `Blocks=approval` clarification row.
 
 Plan-body verification stays **lightweight** even under this posture — the `verificationMode = "full-reanalysis"` forcing in §"Adversarial Verification Mode" applies to finding convergence only (see §"Mode constraint"); the adversarial posture here only changes verifier behaviour, not the mode. This raises verification *quality* (active refutation, plan-side burden) without changing the gate *threshold* — a single dissent still does not block approval; a majority is required (deliberate design decision).
 
@@ -682,7 +687,7 @@ Plan-body verification stays **lightweight** even under this posture — the `ve
    - `full-consensus` — all participating analysers `AGREE` (SUPPLEMENT counts as agree on the item itself).
    - `partial-consensus` — majority `AGREE`, dissenting `DISAGREE` recorded.
    - `dissent-isolated` — only one worker `DISAGREE`s, others `AGREE` — treat as `partial-consensus` for gate purposes; record dissent. (Distinct from finding-convergence `worker-unique`, which means the *opposite*: only one worker AGREEs. Plan-body classifications use this dedicated label to avoid the collision.)
-   - `majority-disagree` — majority of analysers `DISAGREE` on this item. This is the only classification that **blocks the Approval marker**.
+   - `majority-disagree` — majority of analysers `DISAGREE` on this item, OR any analyser emits `DISAGREE(f)` for a `P-Req-*` item. This classification **blocks the Approval marker**.
    - `contested` only meaningful when `maxRounds > 1`; at default `maxRounds=1`, fold any unresolved item into `partial-consensus`.
 5. Gate result resolution:
    - any `majority-disagree` item present AND `gating=true` → `blocked-by-disagreement`
@@ -737,7 +742,7 @@ Plan-body verification stays **lightweight** even under this posture — the `ve
 
 `planItems[].classification` enum: `full-consensus | partial-consensus | dissent-isolated | majority-disagree | contested`. `contested` only appears when `maxRounds > 1`; at default `maxRounds=1` any otherwise-unresolved item folds into `partial-consensus` per the round protocol above.
 
-`planItems[].votes.<worker>` is the verbatim verdict token emitted by the worker — `AGREE | DISAGREE(<a|b|c|d|e>) | SUPPLEMENT` — or `verification-error` for terminal non-result dispatches. The `DISAGREE` token retains its `<kind>` suffix so the breakage class is recoverable from the state file alone.
+`planItems[].votes.<worker>` is the verbatim verdict token emitted by the worker — `AGREE | DISAGREE(<a|b|c|d|e|f>) | SUPPLEMENT` — or `verification-error` for terminal non-result dispatches. The `DISAGREE` token retains its `<kind>` suffix so the breakage class is recoverable from the state file alone.
 
 ### Plan-body reverify prompt
 
@@ -759,7 +764,8 @@ verdict:
   (b) command is not executable or is ambiguous,
   (c) validation signal is not observable,
   (d) rollback violates commit / dependency order,
-  (e) item contradicts the trade-off matrix.
+  (e) item contradicts the trade-off matrix,
+  (f) requirement coverage row does not actually map the stated requirement to a concrete satisfying option / stage / step.
 - **SUPPLEMENT**: The item is sound but a dependency / edge case / precondition
   is missing.
 
@@ -767,6 +773,11 @@ Do NOT re-analyze the original requirements. Judge solely from plan internal
 consistency and stated commands / paths. Do NOT inspect the original task brief
 or worker analyses for this round.
 
+For `P-Req-*` items, compare only the requirement text embedded in the row
+against the cited plan item(s). Do not open the original brief, but do reject
+coverage rows that cite no concrete option/stage/step or cite a plan item that
+does not satisfy the row's own requirement.
+
 ## Plan items to verify
 
 ### P-Step-3 [TICKETID: <id>]: <one-line summary>

package/runtime/skills/okstra-run/SKILL.md

@@ -122,7 +122,7 @@ That is the entire interactive flow. The wizard handles:
 - task-type pick (with `nextRecommendedPhase` surfaced as recommended for existing tasks),
 - brief path (with `유지 / 변경` for existing tasks),
 - base-ref pick + git rev-parse validation (skipped when reusing an active worktree),
-- `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + executor pick,
+- `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = 의존성 충족된 가장 빠른 미완료 stage, 또는 특정 stage 번호) + executor pick,
 - `Use defaults / Customize` branch with profile-aware worker/model questions,
 - `release-handoff` PR template override + persist scope,
 - final `Proceed / Edit` confirmation; on `Edit` the wizard asks which step to rewind to and clears every later answer.

package/runtime/templates/reports/final-report.template.md

@@ -211,6 +211,14 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 | {{ row.id }} | {{ row.step }} | `{{ row.action }}` | {{ row.triggerSignal }} | `{{ row.verificationMethod }}` |
 {% endfor %}
 
+### 5.5.8 Requirement Coverage
+
+| ID | Source | Requirement | Covered by option / stage / step | Status |
+|----|--------|-------------|-----------------------------------|--------|
+{% for row in implementationPlanning.requirementCoverage -%}
+| {{ row.id }} | `{{ row.source }}` | {{ row.requirement }} | {{ row.coveredBy }} | `{{ row.status }}` |
+{% endfor %}
+
 ### 5.5.9 Plan Body Verification{% if t("sectionAside.planBodyVerification") != "Plan Body Verification" %} ({{ t("sectionAside.planBodyVerification") }}){% endif %}
 
 {{ t("sectionIntro.planBodyVerification") }}
@@ -416,6 +424,10 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
   ```
   {{ finalVerification.sourceImplementationReport.gitDiffStat }}
   ```
+{% if verificationScope in ['whole-task', 'single-stage'] %}- {{ t("finalVerification.verificationScope") }}: `{{ verificationScope }}`
+{% endif %}{% if finalVerification.stageReports %}- {{ t("finalVerification.stageReportsLabel") }}:
+{% for row in finalVerification.stageReports %}  - stage {{ row.stage }}: `{{ row.reportPath }}`
+{% endfor %}{% endif %}
 
 ### 5.8.2 Acceptance Blockers
 

package/runtime/templates/reports/final-verification-input.template.md

@@ -29,15 +29,18 @@ taskType: "{{FM_TASK_TYPE}}"
 - What was supposed to be delivered?
 - What is the intended acceptance decision?
 
+## 검증 모드
+
+- 기본은 **전체-task** 검증입니다(`--stage auto`): 모든 Stage Map stage 가 구현·머지된 뒤 한 번 실행합니다.
+- 특정 stage 만 격리 검증하려면 `--stage N` 으로 **단독-stage** 모드를 씁니다(release-handoff 진입 불가, 부분 검증).
+- worktree / base / head 는 okstra 가 registry 와 `consumers.jsonl` 에서 자동 해소하므로 이 입력서에 수동 기입하지 않습니다.
+
 ## Source Implementation Report
 
 - Path (project-relative) to the originating `implementation` final-report:
-- Worktree / checkout path that final-verification must inspect:
-- Implementation base ref (`<base>` for `git diff --stat <base>..HEAD`):
-- Implementation head SHA expected at verification start:
 - Quoted `Commit list` / `Diff summary` excerpt from the implementation report:
 
-> If this section is empty, points to a missing report, or names a checkout that does not match the implementation report's commit list / diff summary, final-verification MUST end with status `blocked` and route back to `implementation` or `implementation-planning`. Do not verify an ambiguous target.
+> 보고서 경로가 비거나 누락된 보고서를 가리키면 final-verification 은 status `blocked` 으로 끝내고 `implementation` 또는 `implementation-planning` 으로 라우팅합니다. 검증 대상(worktree/base/head)은 okstra 가 자동 해소하므로 수동 기입이 어긋나 막히는 일은 없습니다.
 
 ## Requirement Coverage Source
 
@@ -87,7 +90,7 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Questions for Analysers
 
-1. Does the verification target (head SHA / diff stat) match the implementation report's commit list and diff summary?
+1. Did your analysis run against the injected `VERIFICATION_TARGET` (base / head SHA / worktree), and does the diff at that target fully cover the stage(s) under verification? (A head you cannot confirm against the injected target is a `tool-failure`, not a silent proceed.)
 2. For each requirement / acceptance criterion, what exact artifact (commit SHA, test output, log line, config value) proves coverage?
 3. Are there any acceptance blockers?
 4. What residual risks remain?

package/runtime/templates/reports/i18n/en.json

@@ -134,6 +134,8 @@
   },
   "finalVerification": {
     "validationEvidenceAside": "requirements coverage",
-    "columnRequirement": "Requirement (plan/brief citation)"
+    "columnRequirement": "Requirement (plan/brief citation)",
+    "verificationScope": "Verification scope",
+    "stageReportsLabel": "Source implementation reports (per stage)"
   }
 }

package/runtime/templates/reports/i18n/ko.json

@@ -134,6 +134,8 @@
   },
   "finalVerification": {
     "validationEvidenceAside": "요구사항 커버리지",
-    "columnRequirement": "Requirement (plan/brief 인용)"
+    "columnRequirement": "Requirement (plan/brief 인용)",
+    "verificationScope": "검증 범위",
+    "stageReportsLabel": "stage 별 구현 리포트"
   }
 }