okstra 0.205.1 → 0.206.0

package/runtime/python/okstra_ctl/verification_target.py

@@ -1,6 +1,6 @@
 """Read the prepared final-verification target snapshot.
 
-`run.write_verification_target_snapshot` writes it; two consumers read it —
+`phases.final_verification.entry.write_verification_target_snapshot` writes it; two consumers read it —
 report assembly, which records the run's `verificationScope`, and `validate-run`,
 which re-checks the published report against it. The digest rule lived only in
 the validator, so a second reader would have been a second implementation of it;

package/runtime/python/okstra_ctl/wizard/state.py

@@ -14,6 +14,7 @@ from okstra_ctl.role_requirements import (
     load_role_profile,
 )
 from okstra_ctl.ids import slugify_task_segment
+from okstra_ctl.phases.catalog import PhaseAssetError, profile_markdown
 
 from .ids import (
     PICK_TYPE_CUSTOM,
@@ -307,7 +308,10 @@ def _slug_or_die(value: str, field_name: str) -> str:
 # ---- Roster / profile helpers -------------------------------------------
 
 def _profile_path(workspace_root: Path, task_type: str) -> Path:
-    return workspace_root / "prompts" / "profiles" / f"{task_type}.md"
+    try:
+        return profile_markdown(workspace_root, task_type)
+    except PhaseAssetError as exc:
+        raise WizardError(str(exc)) from exc
 
 
 _V2_STATE_FIELDS = (
@@ -366,7 +370,7 @@ def _role_selection_enabled(state: WizardState) -> bool:
         return False
     try:
         load_role_profile(_profile_path(Path(state.workspace_root), state.task_type))
-    except (OSError, RoleProfileError):
+    except (OSError, RoleProfileError, WizardError):
         return False
     return True
 

package/runtime/python/okstra_ctl/wizard/steps_plan.py

@@ -29,6 +29,11 @@ from okstra_ctl.user_response import PlanDecisionRecord, parse_plan_decision
 from okstra_ctl.wizard_stage_intent import WHOLE_TASK_STAGE
 from okstra_ctl import fix_cycles
 from okstra_ctl.paths import task_dir, task_runs_dir
+from okstra_ctl.phases.final_verification.wizard import (
+    StageAnswerError,
+    validate_stage_answer,
+    whole_task_verification_allowed,
+)
 from okstra_project.state import read_task_manifest
 
 from .ids import (
@@ -422,7 +427,10 @@ def _whole_task_allowed(
         return False
     if done is None:
         done = _stage_lifecycle_snapshot(state, stages).done_stages
-    return all(s.stage_number in done for s in stages)
+    return whole_task_verification_allowed(
+        stage_numbers=tuple(stage.stage_number for stage in stages),
+        done_stages=done,
+    )
 
 
 def _build_approved_plan_pick(state: WizardState) -> Prompt:
@@ -623,20 +631,14 @@ def _impl_stage_marker(t, lifecycle) -> str:
 def _submit_stage_pick(state: WizardState, answer: str) -> Optional[str]:
     if state.task_type == "implementation":
         return _submit_impl_stage_pick(state, answer)
-    # final-verification: 단일선택 유지 (whole-task 또는 단일 정수; auto 불가)
-    if not answer:
-        raise WizardError("value required")
-    if answer == WHOLE_TASK_STAGE:
-        if not _whole_task_allowed(state):
-            raise WizardError(
-                "whole-task verification requires final-verification "
-                "with all stages done")
-    else:
-        try:
-            int(answer)
-        except ValueError:
-            raise WizardError(
-                f"answer must be whole-task or a stage number, got {answer!r}")
+    try:
+        validate_stage_answer(
+            answer,
+            whole_task_token=WHOLE_TASK_STAGE,
+            whole_task_allowed=answer == WHOLE_TASK_STAGE and _whole_task_allowed(state),
+        )
+    except StageAnswerError as exc:
+        raise WizardError(str(exc)) from exc
     state.selected_stage = answer
     return f"stage: {answer}"
 

package/runtime/skills/okstra-user-response/SKILL.md

@@ -6,7 +6,7 @@ description: >-
 
 # OKSTRA User Response
 
-Use this skill for open `C-*` clarification items and explicit plan decisions. The user alone selects or writes every answer. Never infer an answer or approval.
+Use this skill for open `C-*` clarification items, explicit plan decisions, and the implementation direction a finished `implementation-option-selection` comparison awaits. The user alone selects or writes every answer. Never infer an answer or approval.
 
 The model-facing commands are fixed text reads and typed transaction writes:
 
@@ -17,6 +17,7 @@ The model-facing commands are fixed text reads and typed transaction writes:
 | `user-response begin` | Open a sidecar transaction for one report identity. |
 | `user-response answer` | Add or replace one validated clarification answer. |
 | `user-response plan-decision` | Record an explicit plan decision in the transaction. |
+| `user-response direction` | Record the implementation direction the user picked in the transaction. |
 | `user-response legacy-report-authoring` | Record legacy report-authoring permission for report contract 2.0 only. |
 | `user-response finalize` | Atomically merge and publish the user-owned sidecar. |
 
@@ -71,7 +72,7 @@ Never invent a picker function. Never ask the user to type a number when the nat
 okstra user-response list-view --home <resolved-home> --project <projectId> --limit 3
 ```
 
-The view gives `Task key`, `Task type`, `Report`, open-item counts, and readability status. If the count is zero, answer `No task has open clarification items.` and stop. Do not continue with an unreadable entry.
+The view gives `Task key`, `Task type`, `Report`, open-item counts, `Direction selection required`, and readability status. If the count is zero, answer `No task has open clarification items.` and stop. Do not continue with an unreadable entry.
 
 Present up to three task choices through the host picker. A host free-text row or unmatched next message is the report path or task key.
 
@@ -89,6 +90,8 @@ Contract 3.0 options also expose `reach` and `scopeEffects`. Contract 3.0 approv
 
 When an axis says `not stated in the report`, repeat that text. Do not infer missing report-owned impact. The skill must **never invent it**.
 
+When the view prints `Direction candidates:`, the comparison awaits a direction. Each `Direction option N:` row gives the candidate id and name, `Recommended`, `Goal`, `Core mechanism`, and `Selectable`. The `Direction picker:` block lists only selectable candidates, recommended first, each with its `Option number`.
+
 ## Step 2b: Investigate cited context before asking
 
 Do not present a picker from the raw field dump. For each still-open item, read the investigation list the view printed:
@@ -127,9 +130,15 @@ Use the displayed values to confirm the user's choice. Do not copy a predefined
 
 Copy `kind` from the view. A `reframe` does not satisfy the gate. If the user asks what an item means, explain from the view plus the cited files already read, then ask the same item again.
 
+## Step 3b: Ask for the direction
+
+Only when `Current direction selection: none` and `Direction picker:` has rows. Ask one single-select question through the host picker, after any clarification whose answer would change the choice. The body says that the comparison is finished, that the chosen candidate becomes the input of `implementation-planning`, and that planning cannot start until one is chosen. Copy each `Direction picker:` `- Label:` / `Description:` pair in order. Remember the `Option number` of the picked row. A `Selectable: no - <reason>` candidate is never offered; when the user asks for it, state the reason.
+
+When the user adds a note or a constraint for the planner, keep their words verbatim for Step 6.
+
 ## Step 4: Confirm the complete response
 
-Echo each clarification ID, kind, disposition, value, and rationale. Include any explicit plan decision or legacy report-authoring decision. Ask through the host picker, two options:
+Echo each clarification ID, kind, disposition, value, and rationale. Include any explicit plan decision, direction, or legacy report-authoring decision. Ask through the host picker, two options:
 
 1. `Record as shown` (Recommended)
 2. `Change an answer`
@@ -150,7 +159,7 @@ For a predefined option, pass only its one-based number from the fixed view:
 okstra user-response answer --transaction <transaction> --clarification-id <C-NNN> --kind <kind> --option-number <N>
 ```
 
-Every value, rationale, and reason body file must be a regular file under `<projectRoot>/.okstra/tmp/user-response/`; do not use an external file or a symbolic link. For a direct user answer, write the exact value there. Write the rationale to a separate Markdown file only when present. Then run:
+Every value, rationale, and reason body file — and every direction note or constraints file — must be a regular file under `<projectRoot>/.okstra/tmp/user-response/`; do not use an external file or a symbolic link. For a direct user answer, write the exact value there. Write the rationale to a separate Markdown file only when present. Then run:
 
 ```bash
 okstra user-response answer --transaction <transaction> --clarification-id <C-NNN> --kind <kind> --disposition <disposition> --value-file <value.md> [--rationale-file <rationale.md>]
@@ -174,6 +183,14 @@ okstra user-response plan-decision --transaction <transaction> --status <revisio
 
 Never infer a plan decision from the user's tone.
 
+When the user picked a direction, pass the picked row's `Option number`. Write a note or constraints the user stated to separate Markdown files in that same temporary directory, one constraint per line:
+
+```bash
+okstra user-response direction --transaction <transaction> --option-number <N> [--note-file <note.md>] [--constraints-file <constraints.md>]
+```
+
+The command refuses a candidate the planning gate would refuse and a report that does not await a direction.
+
 Only for a report whose fixed view says `Report contract: 2.0`, an explicit legacy report-authoring decision may be recorded. A reason file in that same temporary directory is always required:
 
 ```bash
@@ -194,6 +211,8 @@ Leave this guidance in the final answer:
 
 > This answer was recorded in the `user-responses/` sidecar (`<sidecar path>`). Re-running this task with `/okstra-run` attaches the answer to the next eligible phase.
 
+When a direction was recorded, add: start `implementation-planning` with `/okstra-run` and pick this report in the wizard's direction-report step.
+
 ## Output rules
 
 - Keep responses in the user's language.

package/runtime/validators/validate-run.py

@@ -101,6 +101,10 @@ from okstra_ctl.incremental_scope import (  # noqa: E402
     stages_for_clarification,
 )
 from okstra_ctl import next_phase  # noqa: E402
+from okstra_ctl.phases.final_verification.validation import (  # noqa: E402
+    validate_final_verification_content,
+    validate_verification_target_match,
+)
 from okstra_ctl.clarification_items import (  # noqa: E402
     APPROVAL_BLOCKS,
     clarification_disposition,
@@ -5376,19 +5380,6 @@ def _consumers_rows(report_path: Path) -> list[dict] | None:
     return rows
 
 
-# 이 스냅샷의 다이제스트 규칙과 파싱은 `okstra_ctl.verification_target` 하나가
-# 쥔다. 조립도 같은 파일을 읽어 `verificationScope` 를 기록하므로, 사본을 두면
-# 규칙이 갈리는 순간 한쪽이 정상 target 을 변조로 판정한다.
-from okstra_ctl.verification_target import (  # noqa: E402
-    TARGET_FIELD_RES as _TARGET_FIELD_RES,
-    read_verification_target as _read_verification_target_impl,
-)
-
-
-def _read_verification_target(project_root: Path, relative: str) -> dict | None:
-    return _read_verification_target_impl(project_root, relative)
-
-
 _PLAN_BODY_STATE_KEYS = ("schemaVersion", "planItems", "roundHistory")
 
 
@@ -5748,66 +5739,6 @@ def _validate_verifier_command_log_is_read_only(
 
 
 
-def _validate_verification_target_match(
-    data: dict,
-    run_manifest: dict,
-    project_root: Path,
-    failures: list[str],
-) -> None:
-    """The verification report must mirror the target it was prepared against.
-
-    `verificationScope`, the worktree, and the base/head refs were entirely
-    self-declared: the schema required the fields to exist but nothing compared
-    them to the digest-verified snapshot written at prep time. That matters
-    because both `handoff.compute_eligibility` and the `release-handoff`
-    routing check read `verificationScope` — a single-stage run that writes
-    `whole-task` passes both, and an `accepted` verdict can be rendered against
-    a worktree or head nobody verified.
-    """
-    # 최상위 `verificationTargetPath` 가 run 매니페스트의 실물 키다(render.py).
-    # `instructionSet` 블록은 active-run-context 의 것이라 여기서 읽으면 검사가
-    # 통째로 건너뛰어졌다(실측 2026-09-06, dev-10626 final-verification 001).
-    relative = str(run_manifest.get("verificationTargetPath") or "").strip()
-    if not relative:
-        return
-    target = _read_verification_target(project_root, relative)
-    if target is None:
-        return
-
-    source = (data.get("finalVerification") or {}).get("sourceImplementationReport") or {}
-    declared = {
-        "scope": str(data.get("verificationScope") or "").strip(),
-        "worktree": str(source.get("worktreePath") or "").strip(),
-        "base": str(source.get("implementationBaseRef") or "").strip(),
-        "head": str(source.get("capturedHeadSha") or "").strip(),
-    }
-    for key, expected in ((k, target[k]) for k in _TARGET_FIELD_RES):
-        actual = declared[key]
-        if expected and actual and actual != expected:
-            failures.append(
-                f"final-verification report declares {key} `{actual}` but the "
-                f"prepared verification target says `{expected}` "
-                f"(`{relative}`). The report must mirror the target it was "
-                "prepared against — `verificationScope` in particular gates "
-                "both stage-group eligibility and release-handoff routing, so "
-                "a self-declared value lets a run be judged as something it "
-                "was not."
-            )
-
-    declared_stages = {
-        row.get("stage")
-        for row in ((data.get("finalVerification") or {}).get("stageReports") or [])
-        if isinstance(row, dict) and isinstance(row.get("stage"), int)
-    }
-    if target["stages"] and declared_stages and declared_stages != target["stages"]:
-        failures.append(
-            f"final-verification report covers stages {sorted(declared_stages)} "
-            f"but the prepared target names {sorted(target['stages'])} "
-            f"(`{relative}`). A verdict must not be rendered for a stage set "
-            "nobody prepared evidence for."
-        )
-
-
 def _validate_verified_row_recorded(
     data: dict,
     report_path: Path,
@@ -8025,98 +7956,19 @@ def _validate_stage_has_requirement(data: dict, failures: list[str]) -> None:
         )
 
 
-_ADDED_SURFACE_NO_CALLER_RE = re.compile(r"^\s*none\b", re.IGNORECASE)
-
-
-def _validate_added_surface_audit(data: dict, failures: list[str]) -> None:
-    """Every surface the diff added is traced to a requirement, exempted, or paid for.
-
-    The coverage table proves each requirement reached the diff. Nothing proved
-    the reverse — that each thing the diff added answers a requirement — so work
-    nobody asked for passed every gate. This check reads the reverse table and
-    refuses a row that calls itself over-delivery without the blocker or
-    condition it became: a caller-less surface is an acceptance blocker, and a
-    surface with callers but no requirement is a conditional-acceptance
-    condition (ADR-0009 grades the two differently on purpose).
-    """
-    fv = data.get("finalVerification")
-    if not isinstance(fv, Mapping):
-        return
-    rows = fv.get("addedSurfaceAudit")
-    if not isinstance(rows, list):
-        return
-    blocker_ids = {
-        str(row.get("id"))
-        for row in (fv.get("acceptanceBlockers") or [])
-        if isinstance(row, Mapping)
-    }
-    condition_ids = {
-        str(row.get("id"))
-        for row in ((data.get("finalVerdict") or {}).get(
-            "conditionalAcceptanceConditions") or [])
-        if isinstance(row, Mapping)
-    }
-    for row in rows:
-        if not isinstance(row, Mapping):
-            continue
-        row_id = str(row.get("id") or "<id 없음>")
-        disposition = str(row.get("disposition") or "")
-        note = str(row.get("note") or "")
-        if disposition == "traced" and not str(row.get("requirement") or "").strip():
-            failures.append(
-                f"final-verification: addedSurfaceAudit {row_id} is `traced` but "
-                "names no requirement — a surface is traced to something the "
-                "brief asked for, or it is not traced."
-            )
-            continue
-        if disposition != "over-delivery":
-            continue
-        caller_less = bool(
-            _ADDED_SURFACE_NO_CALLER_RE.match(str(row.get("callers") or ""))
-        )
-        expected, known = (
-            ("AB", blocker_ids) if caller_less else ("CA", condition_ids)
-        )
-        cited = set(re.findall(rf"\b{expected}-\d{{3,}}\b", note))
-        if not cited:
-            failures.append(
-                f"final-verification: addedSurfaceAudit {row_id} is "
-                f"`over-delivery` with callers "
-                f"{'none' if caller_less else 'recorded'}, so its note MUST cite "
-                f"the `{expected}-NNN` row it became — "
-                + (
-                    "a caller-less surface is an acceptance blocker"
-                    if caller_less
-                    else "a surface with callers but no requirement is a "
-                         "conditional-acceptance condition"
-                )
-                + "."
-            )
-            continue
-        missing = sorted(cited - known)
-        if missing:
-            failures.append(
-                f"final-verification: addedSurfaceAudit {row_id} cites "
-                f"{missing}, which the report does not carry."
-            )
-
-
 def _validate_final_verification_consistency(data: dict, failures: list[str]) -> None:
-    """Enforce verdict ↔ blocker/condition/routing consistency on the
-    final-verification data.json (SSOT). The schema guarantees field SHAPE;
-    these are the cross-field invariants the release-handoff gate depends on.
-
-    No-op for non-final-verification data so the caller's gate stays defensive.
-    """
+    """단계 내용 판정 뒤에 이동 적합성을 본다. 다른 작업 유형은 건너뛴다."""
     if (data.get("header") or {}).get("taskType") != "final-verification":
         return
-    _validate_added_surface_audit(data, failures)
+    validate_final_verification_content(data, failures)
+    _validate_final_verification_routing(data, failures)
+
+
+def _validate_final_verification_routing(data: dict, failures: list[str]) -> None:
+    """다음 단계 이름이 판정과 맞는지 본다. 대상 선택은 추론하지 않는다."""
     verdict = data.get("finalVerdict") or {}
     token = (verdict.get("verdictToken") or "").strip().lower()
-    fv = data.get("finalVerification") or {}
-    blockers = fv.get("acceptanceBlockers") or []
-    conditions = verdict.get("conditionalAcceptanceConditions") or []
-    routing_value = fv.get("routingRecommendation")
+    routing_value = (data.get("finalVerification") or {}).get("routingRecommendation")
     routing_token = ""
     if isinstance(routing_value, dict):
         routing_token = str(routing_value.get("target") or "")
@@ -8125,23 +7977,16 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
             "final-verification: routingRecommendation.target must name exactly one "
             "supported routing target."
         )
-        routing_token = None
+        return
+    _refuse_unsuitable_final_verification_route(data, failures, token, routing_token)
 
-    if token == "accepted" and blockers:
-        failures.append(
-            "final-verification: verdict `accepted` but acceptanceBlockers is "
-            "non-empty — an accepted verdict must have zero blockers."
-        )
-    if token == "blocked" and not blockers:
-        failures.append(
-            "final-verification: verdict `blocked` but acceptanceBlockers is "
-            "empty — a blocked verdict must list at least one blocker."
-        )
-    if token == "conditional-accept" and not conditions:
-        failures.append(
-            "final-verification: verdict `conditional-accept` but "
-            "conditionalAcceptanceConditions is empty — list every condition."
-        )
+
+def _refuse_unsuitable_final_verification_route(
+    data: dict,
+    failures: list[str],
+    token: str,
+    routing_token: str,
+) -> None:
     if routing_token in RELEASE_HANDOFF_TARGETS and not release_handoff_allowed(data):
         blocking = blocking_condition_ids(data)
         reason = (
@@ -8156,7 +8001,6 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
             "or a `conditional-accept` whose every condition declares "
             "`blocksReleaseHandoff: false`."
         )
-
     if routing_token == "final-verification" and token == "accepted":
         failures.append(
             "final-verification: routingRecommendation cites `final-verification` "
@@ -8164,13 +8008,6 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
             "to re-verify. Route to release-handoff or done."
         )
 
-    scope = data.get("verificationScope", "whole-task")
-    if scope not in ("whole-task", "single-stage"):
-        failures.append(
-            f"final-verification: verificationScope must be `whole-task` or "
-            f"`single-stage`, got {scope!r}."
-        )
-
 
 def validate_report_views(report_path: Path, failures: list[str]) -> None:
     """Enforce Phase 7 step 1.5 (BLOCKING) — the self-contained HTML
@@ -9848,7 +9685,7 @@ def main() -> int:
             Path(args.state).resolve() if args.state else None,
         )
     if task_type == "final-verification":
-        _validate_verification_target_match(
+        validate_verification_target_match(
             validation_data,
             run_manifest,
             project_root,

package/docs/task-process/README.md

@@ -1,82 +0,0 @@
-# okstra-run task process
-
-## Index
-
-- [1. Reading order](#1-reading-order)
-- [2. Big picture](#2-big-picture)
-- [3. task-type documents](#3-task-type-documents)
-- [4. Key code locations](#4-key-code-locations)
-- [5. Quick comparison table](#5-quick-comparison-table)
-
-## 1. Reading order
-
-`okstra-run` is the path that starts a task inside a supported Claude Code, Codex, or Antigravity host session. This folder organizes that execution flow into two layers.
-
-1. First read [common-flow.md](common-flow.md). It is the wizard, render-bundle, lead phase, and artifact flow shared by every task-type.
-2. Then read the document for the task-type you want to run.
-3. Check the per-task-type differences across three places: "what the wizard additionally asks", "what `prepare_task_bundle()` blocks in the runtime", and "what the lead profile enforces within the phase".
-
-## 2. Big picture
-
-```mermaid
-flowchart TD
-    U[User in supported host] --> S[okstra-run skill]
-    S --> R[Step 1<br/>ensure-installed / paths / check-project]
-    R --> W[okstra wizard<br/>state machine]
-    W --> A[render-args]
-    A --> B[okstra render-bundle<br/>--render-only]
-    B --> P[prepare_task_bundle()]
-    P --> I["runs/task-type/prompts<br/>lead-execution-prompt-*.md"]
-    I --> L[Current host session<br/>takes over as Okstra lead]
-    L --> F[Phase 1-7 lead workflow]
-    F --> O[final-report + manifests + status]
-```
-
-`okstra-run` does not call `scripts/okstra.sh`. Instead it goes through `okstra wizard` and `okstra render-bundle` and converges on the same single Python entrypoint, `prepare_task_bundle()`.
-
-Launch selection is role slots and model refs, not a provider roster. The wizard asks one screen per static role: a checkbox of candidate models for a role that runs several instances (the number checked is the instance count, rendered as `--role-count <role>=<N>` plus one `--role-model <role>=<provider>/<model>` per checked model; the label states the profile range and recommended count), a single pick for a fixed single-instance role. current-session lead is this session and is listed on the confirmation summary. Roles with `min = 0` stay closed unless the user adds them. There is no provider multi-pick and no `Use defaults / Customize` fork for worker selection. `--workers` is compatibility-only. `lead` is a compatibility alias for `leader`. `executor` is a compatibility alias for `implementer`. New records write `leader` and `implementer`.
-
-## 3. task-type documents
-
-| task-type | Document | One-line purpose |
-|---|---|---|
-| `requirements-discovery` | [requirements-discovery.md](requirements-discovery.md) | Classify the request and choose the next safe phase. |
-| `error-analysis` | [error-analysis.md](error-analysis.md) | Find cause candidates and validation paths from symptoms and evidence. |
-| `implementation-option-selection` | [implementation-option-selection.md](implementation-option-selection.md) | Compare or validate exact-coverage directions before detailed planning. |
-| `implementation-planning` | [implementation-planning.md](implementation-planning.md) | Realize one selected direction as an exact-coverage plan with a separate approval gate. |
-| `implementation` | [implementation.md](implementation.md) | The executor implements the approved plan and the verifier verifies it independently. |
-| `final-verification` | [final-verification.md](final-verification.md) | Judge whole-task or single-stage acceptance of the implementation result. |
-| `release-handoff` | [release-handoff.md](release-handoff.md) | Perform the push/PR handoff lead-only after an accepted verdict. |
-
-## 4. Key code locations
-
-| Concern | Source of truth |
-|---|---|
-| okstra-run skill procedure | [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md) |
-| wizard state machine | [`scripts/okstra_ctl/wizard/`](../../scripts/okstra_ctl/wizard/) |
-| wizard prompt text | [`prompts/wizard/prompts.ko.json`](../../prompts/wizard/prompts.ko.json) |
-| render-bundle Node shim | [`src/commands/execute/render-bundle.mts`](../../src/commands/execute/render-bundle.mts) |
-| single entrypoint for bundle creation | [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py) |
-| implementation stage selection/provisioning | [`scripts/okstra_ctl/implementation_stage.py`](../../scripts/okstra_ctl/implementation_stage.py) |
-| Stage Lifecycle Snapshot + stage target/base/verification policy | [`scripts/okstra_ctl/stage_targets.py`](../../scripts/okstra_ctl/stage_targets.py) |
-| phase boundary | [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py) |
-| task worktree | [`scripts/okstra_ctl/worktree/`](../../scripts/okstra_ctl/worktree/) |
-| stage-group handoff | [`scripts/okstra_ctl/handoff.py`](../../scripts/okstra_ctl/handoff.py) |
-| worker roster parser | [`scripts/okstra_ctl/workers.py`](../../scripts/okstra_ctl/workers.py) |
-| lead operating contract | [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md) |
-| phase profiles | [`prompts/profiles/`](../../prompts/profiles/) |
-| final report shape / HTML view | [`templates/reports/final-report-v2.template.md`](../../templates/reports/final-report-v2.template.md), [`scripts/okstra_ctl/report_views.py`](../../scripts/okstra_ctl/report_views.py) |
-
-## 5. Quick comparison table
-
-The last column is the `workflow.nextRecommendedPhase` pointer Phase 7 leaves behind — an object `{phase, status, rationale}`, projected from the report's own routing field. There is no static default: a run that settles no route ends `pending` with no phase. The routing field's `rationale` is carried into the pointer, and the lead's closeout quotes it. The rule for authoring that field is stated once, in the Phase 6 checklist of [`prompts/lead/report-writer.md`](../../prompts/lead/report-writer.md).
-
-| task-type | wizard special question | runtime prepare gate | lead/worker mode | next-phase pointer |
-|---|---|---|---|---|
-| `requirements-discovery` | common questions only | profile/brief/base-ref exist | multi-worker analysis, convergence 1 round default | `ready` at `error-analysis` or `implementation-option-selection`; `pending` when neither is settled |
-| `error-analysis` | common questions only | profile/brief/base-ref exist | multi-worker analysis, convergence 2 rounds default | `ready` at `implementation-option-selection`, or at `error-analysis` while the investigation continues |
-| `implementation-option-selection` | comparison or preselected-validation context | stable brief IDs and at least three analysers | read-only candidate validation, exact coverage, separate direction confirmation | `ready` at `implementation-planning` (a confirmed direction, or ranked candidates the planning wizard lets the user pick from), `pending` when no candidate was ranked, or `blocked` |
-| `implementation-planning` | selected-direction report for a new plan | selection report/sidecar/digest or same-task planning rerun | one-direction realization + Phase 6 plan-body verification | `ready` at `implementation` on approvable `plan-ready` (`awaitingApproval` until the user flips `approved`); `blocked` when the gate is blocking or a `Blocks=approval` row is open; `ready` at `implementation-option-selection` on `direction-invalidated` |
-| `implementation` | approved plan, stage multi-pick, executor | approved marker, Stage Lifecycle Snapshot, stage-key reservation, QA command deny-list | one run = one stage; executor writes in isolated stage worktree, verifiers read-only | `ready` at the stage report's `routingRecommendation.target` — `final-verification` on a clean stage |
-| `final-verification` | approved plan, stage pick (whole-task or single-stage) | `VERIFICATION_TARGET` resolved; whole-task auto integration/teardown or single-stage worktree reuse | whole-task may integrate stages first; analyser verification itself is read-only | `ready` at `release-handoff` on an `accepted` verdict, otherwise at the phase owning the defect; `terminal` on `done` |
-| `release-handoff` | handoff scope (stage-group or whole-task), PR template override/scope | Stage Lifecycle Snapshot eligibility, generated `release-handoff-input.md`, empty worker roster | single-lead; whole-task PR or stage-group collector branch/PR | always `terminal` |