okstra 0.175.1 → 0.176.0

package/runtime/python/okstra_ctl/workflow.py

@@ -1,8 +1,11 @@
 """Phase / workflow state computation.
 
-bash `compute_workflow_render_context` + `default_next_phase_for_task_type` 의
-python 구현. (task-type, current task/run status, render-only flag) 만 받아서
-WORKFLOW_* 필드 dict 를 돌려준다.
+bash `compute_workflow_render_context` 의 python 구현. (task-type, current
+task/run status, render-only flag) 만 받아서 WORKFLOW_* 필드 dict 를 돌려준다.
+
+다음 phase 는 이 모듈이 계산하지 않는다. 포인터의 shape·승격·투영은
+`okstra_ctl.next_phase` 하나가 소유하고, 값은 리포트가 저작한 라우팅에서
+투영된다.
 
 task-type 별 PHASE_ALLOWED_OUTPUTS 본문 매핑은 모듈 상수(`PHASE_RULES`)로 보유하고,
 PHASE_FORBIDDEN_ACTIONS 는 `prompts/profiles/forbidden-actions.json` SSOT 에서 로드한다.
@@ -12,8 +15,6 @@ from __future__ import annotations
 import json
 from pathlib import Path
 
-from okstra_ctl.analysis_inputs import ANALYSIS_TASK_TYPES
-
 PHASE_SEQUENCE = [
     "requirements-discovery",
     "error-analysis",
@@ -33,22 +34,6 @@ ERROR_ANALYSIS_ROUTING_DIRECTIONS = {
     "implementation-option-selection": "begin-option-selection",
 }
 
-DEFAULT_NEXT_PHASE = {
-    "requirements-discovery": "implementation-option-selection",
-    "improvement-discovery": "pending-routing-decision",
-    **{task_type: "pending-routing-decision" for task_type in ANALYSIS_TASK_TYPES},
-    "error-analysis": "implementation-option-selection",
-    "implementation-option-selection": "implementation-planning",
-    "implementation-planning": "implementation",
-    "implementation": "final-verification",
-    # final-verification 의 다음 단계는 verdict 에 따라 갈리므로 정적 매핑은
-    # `pending-release-handoff` 로 둔다 (accepted 일 때만 release-handoff 로
-    # 진입; 그 외에는 error-analysis / implementation-option-selection /
-    # implementation-planning 으로 리라우팅).
-    "final-verification": "pending-release-handoff",
-    "release-handoff": "done-or-follow-up",
-}
-
 # Phase 별 allowed outputs. bash heredoc 원문 그대로 옮긴 값 — 들여쓰기와 백틱은
 # prompt template 에 그대로 박혀 lead 가 읽는다. forbidden actions 는 이 dict 가
 # 아니라 prompts/profiles/forbidden-actions.json (load_phase_forbidden) 이 SSOT.
@@ -56,7 +41,7 @@ PHASE_RULES: dict[str, dict[str, str]] = {
     "requirements-discovery": {
         "allowed": (
             "  - work-category classification (bugfix / feature / refactor / ops / improvement)\n"
-            "  - routing decision toward the next safe lifecycle phase\n"
+            "  - routing decision as the `routing` object `{nextTaskType, readyWhen, rationale}`: `nextTaskType` is `error-analysis` or `implementation-option-selection` and nothing else — this phase never hands off directly to planning or implementation. Prose alone does not route the task — Phase 7 projects `workflow.nextRecommendedPhase` from `nextTaskType`\n"
             "  - missing-input list and clarification requests\n"
             "  - approval / confirmation checkpoints recorded for the next phase\n"
             "  - one endStateCoverage row per brief end-state id (this phase authors no goal of its own)"
@@ -132,14 +117,14 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - TDD evidence for TDD-applicable steps: failing-test output before implementation commit and passing-test output after, with framing SHAs\n"
             "  - per-verifier sections for every verifier in the resolved roster, with an independent verdict (PASS / CONCERNS / FAIL) and cited diff snippets; dissent is preserved by the Okstra lead\n"
             "  - rollback verification (advisory, never blocks — record the revert path for a human; `result` is ok / not-applicable / advisory — human-run)\n"
-            "  - routing recommendation for `final-verification` (ready / needs new error-analysis or planning loop)"
+            "  - routing recommendation as the `routingRecommendation` object `{target, rationale}`: `target` is one of `final-verification`, `error-analysis`, `implementation-planning`, `implementation`, and `rationale` is why that one and nothing else. Prose alone does not route the task — Phase 7 projects `workflow.nextRecommendedPhase` from `target`"
         ),
     },
     "final-verification": {
         "allowed": (
             "  - acceptance verdict with requirement coverage assessment\n"
             "  - residual risk and regression notes\n"
-            "  - recommended follow-up routing (`error-analysis` / `implementation-option-selection` / `implementation-planning` / `release-handoff`) for any defects detected"
+            "  - routing recommendation as the `routingRecommendation` object `{target, rationale}`: `target` is one of `release-handoff`, `release-handoff(stage-group)`, `error-analysis`, `implementation-option-selection`, `implementation-planning`, `implementation`, `done`, and `rationale` ties that choice to the verdict and the blocker list. Both `release-handoff` forms require the `accepted` verdict; plain `release-handoff` additionally requires `whole-task` verification scope. Prose alone does not route the task — Phase 7 projects `workflow.nextRecommendedPhase` from `target`"
         ),
     },
     "release-handoff": {
@@ -187,10 +172,6 @@ def load_phase_forbidden(workspace_root: Path) -> dict[str, str]:
     return {phase: render_forbidden(items) for phase, items in data.items()}
 
 
-def default_next_phase_for(task_type: str) -> str:
-    return DEFAULT_NEXT_PHASE.get(task_type, "unknown")
-
-
 def compute_workflow_state(
     *,
     task_type: str,
@@ -221,8 +202,6 @@ def compute_workflow_state(
         else:
             phase_state = "not-started"
 
-    routing_status = "pending" if task_type == "requirements-discovery" else "not-applicable"
-
     if render_only:
         checkpoint_label = "instruction-set-prepared"
     elif current_run_status == "in-progress":
@@ -239,10 +218,17 @@ def compute_workflow_state(
         "WORKFLOW_WORK_CATEGORY": resolved_work_category,
         "WORKFLOW_CURRENT_PHASE": task_type,
         "WORKFLOW_CURRENT_PHASE_STATE": phase_state,
-        "WORKFLOW_NEXT_RECOMMENDED_PHASE": default_next_phase_for(task_type),
+        # 값이 아니라 자리표시자다. 실제 포인터는 리포트 라우팅에서 투영돼
+        # 매니페스트의 `workflow.nextRecommendedPhase` 구조체로 저장된다.
+        # 이 ctx 값은 그 구조체로 대체되지 않는다 — 남은 소비자는
+        # `render.py` 의 `_active_workflow` 하나이고, 그것은 이 빈 문자열을
+        # 승격해 phase 없는 pending 포인터를 active-run-context 에 적는다.
+        # `prompts/launch.template.md` 는 더 이상 이 토큰을 쓰지 않는다.
+        # 다음 phase 이름을 문장에 끼워 넣던 두 줄이, 이름 없이 읽히는 문장으로
+        # 바뀌었기 때문이다.
+        "WORKFLOW_NEXT_RECOMMENDED_PHASE": "",
         "WORKFLOW_LAST_COMPLETED_PHASE": last_completed,
         "WORKFLOW_AWAITING_APPROVAL": "false",
-        "WORKFLOW_ROUTING_STATUS": routing_status,
         "WORKFLOW_LAST_SAFE_CHECKPOINT_LABEL": checkpoint_label,
         "PHASE_ALLOWED_OUTPUTS": rules["allowed"],
         "PHASE_FORBIDDEN_ACTIONS": forbidden_by_phase.get(

package/runtime/python/okstra_ctl/worktree.py

@@ -4,9 +4,9 @@ Every okstra task — regardless of task-type/phase — runs inside an
 isolated git worktree rooted at
 `~/.okstra/worktrees/<project_id>/<task_group>/<task_id>/`. The same
 worktree is reused across all phases of one task-key (requirements-
-discovery → error-analysis → implementation-planning → implementation),
-so phase N picks up exactly the working-tree state phase N-1 left
-behind.
+discovery → error-analysis → implementation-option-selection →
+implementation-planning → implementation), so phase N picks up exactly
+the working-tree state phase N-1 left behind.
 
 A global registry (`worktree_registry.py`) maps task-keys to the
 on-disk path + branch and serialises reservations, so two concurrent

package/runtime/python/okstra_ctl/worktree_registry.py

@@ -8,10 +8,11 @@ processes cannot race to reserve the same path or branch.
 
 Why a global registry:
   - A single task-key spans multiple phases (requirements-discovery →
-    error-analysis → implementation-planning → implementation). All
-    phases must land in the **same** worktree on the **same** branch.
-    Re-entry from any phase must look up the existing entry instead of
-    creating a duplicate.
+    error-analysis → implementation-option-selection →
+    implementation-planning → implementation). All phases must land in
+    the **same** worktree on the **same** branch. Re-entry from any
+    phase must look up the existing entry instead of creating a
+    duplicate.
   - Two different task-keys must never collide on the same branch name.
     A global branch index makes that detectable cheaply.
   - Cleanup of stale entries (worktree dir removed manually) needs a

package/runtime/python/okstra_project/state.py

@@ -53,6 +53,20 @@ def _load_json(path: Path) -> Optional[dict]:
         raise StateError(f"failed to parse {path}: {exc}") from exc
 
 
+def _next_phase():
+    """`okstra_ctl.next_phase` 를 호출 시점에 가져온다.
+
+    모듈 최상단에서 import 하면 순환이 된다 — `okstra_ctl/__init__.py` 가
+    `.ids` 를 거쳐 이 모듈의 `slugify` 를 도로 import 하기 때문에, 여기서
+    okstra_ctl 을 먼저 끌어오면 아직 정의되지 않은 이름을 찾다가 ImportError 로
+    죽는다. 같은 파일의 `_reconcile_task_root_best_effort` 도 같은 이유로 지연
+    import 를 쓴다.
+    """
+    from okstra_ctl import next_phase
+
+    return next_phase
+
+
 def slugify(value: str) -> str:
     """task-group / task-id segment 를 디스크 경로용 slug 로 정규화한다.
 
@@ -83,8 +97,32 @@ def read_latest_task(project_root: Path) -> Optional[dict]:
 
 
 def read_task_manifest(task_root: Path) -> Optional[dict]:
-    """<task-root>/task-manifest.json 을 dict 로. 파일 없으면 None."""
-    return _load_json(Path(task_root) / TASK_MANIFEST_FILENAME)
+    """<task-root>/task-manifest.json 을 dict 로. 파일 없으면 None.
+
+    구형 문자열 포인터는 반환값에서 승격한다. 읽는 곳이 여럿이므로 승격을 seam
+    하나에 두지 않으면 형태가 갈라진다 (ADR-0004).
+
+    **디스크는 건드리지 않는다.** 승격한 값을 여기서 되적으면 lock 없는
+    read-modify-write 가 되어, 파싱과 쓰기 사이에 다른 프로세스가 적은
+    `currentPhase` · `phaseStates` · `latestReportPath` 를 되돌린다
+    (`os.replace` 는 찢어진 읽기만 막고 갱신 유실은 못 막는다). 이 분기는
+    디스크 포인터가 아직 문자열일 때 — 즉 업그레이드 직후 진행 중인 task 가
+    살아 있을 때 — 만 발화하므로 되돌릴 수 있는 값이 바로 phase 진행 상태다.
+    그래서 디스크 형태는 다음 writer 가 손댈 때까지 구형으로 남는다. 모든
+    읽기가 여기서 승격하므로 소비자는 그 차이를 보지 않는다.
+    """
+    manifest = _load_json(Path(task_root) / TASK_MANIFEST_FILENAME)
+    if not isinstance(manifest, dict):
+        return manifest
+    workflow = manifest.get("workflow")
+    if not isinstance(workflow, dict):
+        return manifest
+    workflow["nextRecommendedPhase"] = _next_phase().promote(
+        workflow.get("nextRecommendedPhase")
+    )
+    # routingStatus 는 포인터 status 로 흡수됐다 — 승격과 같은 자리에서 지운다.
+    workflow.pop("routingStatus", None)
+    return manifest
 
 
 def read_task_key(task_root: Path) -> str:
@@ -146,11 +184,18 @@ def _entry_with_manifest_state(entry: dict, task_root: Path) -> dict:
         ("currentPhase", "currentPhase"),
         ("currentPhaseState", "currentPhaseState"),
         ("lastCompletedPhase", "lastCompletedPhase"),
-        ("nextRecommendedPhase", "nextRecommendedPhase"),
     ):
         value = workflow.get(source)
         if isinstance(value, str):
             out[target] = value
+    # 포인터는 구조체라 위 루프의 str 검사에 걸리지 않는다 — 그 검사에 남겨두면
+    # 값이 예외도 로그도 없이 버려진다. 매니페스트가 값을 가질 때만 카탈로그
+    # 항목을 덮는 규칙은 위 세 필드와 같게 유지하고, 덮지 않을 때는 카탈로그에
+    # 남아 있던 구형 문자열을 승격해 내보낸다.
+    raw = workflow.get("nextRecommendedPhase")
+    if raw is None:
+        raw = entry.get("nextRecommendedPhase")
+    out["nextRecommendedPhase"] = _next_phase().promote(raw)
     out.update(derived_task_status(manifest))
     return out
 
@@ -334,7 +379,9 @@ def resolve_task_identity(project_root: Path, task_key: str) -> dict:
         "taskType": manifest.get("taskType") or "",
         "currentPhase": workflow.get("currentPhase") or "",
         "currentPhaseState": workflow.get("currentPhaseState") or "",
-        "nextRecommendedPhase": workflow.get("nextRecommendedPhase") or "",
+        "nextRecommendedPhase": _next_phase().promote(
+            workflow.get("nextRecommendedPhase")
+        ),
         "lastCompletedPhase": workflow.get("lastCompletedPhase") or "",
         "awaitingApproval": bool(workflow.get("awaitingApproval", False)),
         "taskBriefPath": manifest.get("taskBriefPath") or "",
@@ -363,8 +410,9 @@ def task_read_side_snapshot(project_root: Path, task_key: str) -> dict:
             "currentPhase": workflow.get("currentPhase"),
             "currentPhaseState": workflow.get("currentPhaseState"),
             "lastCompletedPhase": workflow.get("lastCompletedPhase"),
-            "nextRecommendedPhase": workflow.get("nextRecommendedPhase"),
-            "routingStatus": workflow.get("routingStatus"),
+            "nextRecommendedPhase": _next_phase().promote(
+                workflow.get("nextRecommendedPhase")
+            ),
             "phaseStates": workflow.get("phaseStates"),
         },
         "status": derived_task_status(manifest),

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

@@ -1375,8 +1375,26 @@
           }
         },
         "routingRecommendation": {
-          "type": "string",
-          "minLength": 1
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "target",
+            "rationale"
+          ],
+          "properties": {
+            "target": {
+              "enum": [
+                "final-verification",
+                "error-analysis",
+                "implementation-planning",
+                "implementation"
+              ]
+            },
+            "rationale": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
         },
         "userNarrative": {
           "$ref": "#/$defs/ImplementationUserNarrative"
@@ -1528,9 +1546,29 @@
           }
         },
         "routingRecommendation": {
-          "type": "string",
-          "minLength": 1,
-          "pattern": "(^|[^A-Za-z-])(release-handoff\\(stage-group\\)|release-handoff|done|implementation|error-analysis|implementation-option-selection|implementation-planning)([^A-Za-z-]|$)"
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "target",
+            "rationale"
+          ],
+          "properties": {
+            "target": {
+              "enum": [
+                "release-handoff",
+                "release-handoff(stage-group)",
+                "error-analysis",
+                "implementation-option-selection",
+                "implementation-planning",
+                "implementation",
+                "done"
+              ]
+            },
+            "rationale": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
         },
         "userNarrative": {
           "$ref": "#/$defs/FinalVerificationUserNarrative"

package/runtime/skills/okstra-inspect/facets/recap.md

@@ -24,6 +24,8 @@ okstra recap assemble <resolved-target> --project-root <projectRoot>
 
 Parse the stdout JSON (`{taskKey, runCount, transitions[], latestPhaseStates}`) and narrate the per-run before/after transitions. For each `transitions[]` entry, show `fromPhase → toPhase` (previous run currentPhase → this run currentPhase), `status`, `lastCompletedPhase`, `nextRecommendedPhase`, and `reportPath` in chronological order. If `runCount == 0`, answer only "This task has no recorded runs." and do not claim to have read any file.
 
+`nextRecommendedPhase` in each entry is an **object** `{phase, status, rationale}`, not a phase-name string. Narrate it as `phase` when `phase` is non-empty, and as what `status` says otherwise — `pending` (that run did not settle the route), `blocked` (it stopped on something outside the run), `terminal` (the lifecycle ended there). Printing the object itself puts a raw dict in front of the reader.
+
 For a run that has a `reportPath`, read that final-report to enrich the summary only when the user wants a deeper one (do not read them all automatically).
 
 ### recap.3 — Free-form Q&A loop

package/runtime/skills/okstra-inspect/facets/report.md

@@ -27,7 +27,7 @@ D. **Specific task-type (fallback):** `latestReportPath` is task-type-agnostic.
 1. Verify `latestReportPath` is non-empty AND the file exists on disk. Either signal indicates report presence (tolerant).
 2. If present, display the path and ask the user whether to read it.
 3. If absent, check `task-manifest.json` signals:
-   - `latestReportPath` empty/missing AND `currentStatus != completed` AND `workStatus != done` AND `workflow.routingStatus` not completion-like → `This task is not yet complete (currentStatus: <currentStatus>, workStatus: <workStatus>).`
+   - `latestReportPath` empty/missing AND `currentStatus != completed` AND `workStatus != done` AND `workflow.nextRecommendedPhase.status != "terminal"` → `This task is not yet complete (currentStatus: <currentStatus>, workStatus: <workStatus>).`
    - Any signal indicates completion but the file is missing → `Report file does not exist: <path>`
 
 `workStatus` enum: `todo | in-progress | blocked | done`. `currentStatus`: `completed` / `contract-violated` etc. `"completed"` string does NOT exist in `workStatus` — do not confuse the two.

package/runtime/skills/okstra-inspect/facets/status.md

@@ -18,8 +18,7 @@ Read `.okstra/discovery/task-catalog.json`. The catalog is the authoritative sou
 | `currentStatus` | task-level status |
 | `currentPhase` | lifecycle current phase |
 | `currentPhaseState` | lifecycle phase state |
-| `nextRecommendedPhase` | next recommended phase |
-| `routingStatus` | routing decision status |
+| `nextRecommendedPhase` | next-phase pointer — an **object** `{phase, status, rationale}`, never a string. `status` is `ready` / `pending` / `blocked` / `terminal`. The lead writes `phase` only under `ready`, but that is an authoring rule, not a constraint the struct enforces — `prepare` lowers a `ready` pointer to `pending` and keeps its `phase`, so a non-`ready` pointer that still names a phase is a normal state to read. Decide launchability from `status` alone. Render `phase` (or `--` when it is empty) — never the object itself. |
 | `awaitingApproval` | whether awaiting approval |
 | `latestRunStatus` | latest run status |
 | `latestReportPath` | latest report path |
@@ -29,9 +28,9 @@ Read `.okstra/discovery/task-catalog.json`. The catalog is the authoritative sou
 
 Sort by `updatedAt` desc, then `taskKey`.
 
-The overview table is intentionally narrow so it renders cleanly in a terminal. Only six columns are shown; for any task that needs a closer look (phase state, routing, approval gate, last run status, resume path, etc.) tell the user to run `/okstra-inspect status <task-key>` for the detail view in `status.2`.
+The overview table is intentionally narrow so it renders cleanly in a terminal. Only six columns are shown; for any task that needs a closer look (phase state, the pointer's status and rationale, approval gate, last run status, resume path, etc.) tell the user to run `/okstra-inspect status <task-key>` for the detail view in `status.2`.
 
-If `awaitingApproval` is true OR `routingStatus == "pending"`, append a `*` to the `Next` cell and explain the marker once below the table.
+The `Next` cell is `nextRecommendedPhase.phase`, or `--` when that string is empty. If `awaitingApproval` is true OR `nextRecommendedPhase.status` is anything other than `ready`, append a `*` to the cell and explain the marker once below the table — an unset or non-`ready` pointer means no next run is launchable yet.
 
 ```markdown
 ## okstra Status — <project-id>
@@ -39,9 +38,9 @@ If `awaitingApproval` is true OR `routingStatus == "pending"`, append a `*` to t
 | # | Task Key | Category | Phase | workStatus | Next |
 |---|----------|----------|-------|------------|------|
 | 1 | proj:group:id | bugfix | error-analysis | in-progress | implementation-planning |
-| 2 | proj:group:id2 | feature | requirements-discovery | done | pending-routing-decision* |
+| 2 | proj:group:id2 | feature | requirements-discovery | done | --* |
 
-`*` = awaiting user approval or pending routing decision. Run `/okstra-inspect status <task-key>` for details.
+`*` = awaiting user approval, or the next-phase pointer is not `ready`. Run `/okstra-inspect status <task-key>` for details.
 ```
 
 ### status.2 — Specific task status
@@ -52,7 +51,9 @@ Given a specific `task-key` or `task-group + task-id`:
 2. If necessary, read `.okstra/tasks/<task-group>/<task-id>/task-manifest.json` directly.
 3. If you need the latest run information, read `history/timeline.json` along with the latest run manifest.
 
-Required fields: `taskKey`, `taskType`, `workCategory`, `currentStatus`, `latestRunStatus`, `workflow.{currentPhase, currentPhaseState, phaseStates, lastCompletedPhase, nextRecommendedPhase, awaitingApproval, routingStatus, lastSafeCheckpoint}`, `workStatus`, `workStatusUpdatedAt`, `workStatusNote`, `latestReportPath`, `latestResumeCommandPath`, `historyTimelinePath`.
+Required fields: `taskKey`, `taskType`, `workCategory`, `currentStatus`, `latestRunStatus`, `workflow.{currentPhase, currentPhaseState, phaseStates, lastCompletedPhase, nextRecommendedPhase, awaitingApproval, lastSafeCheckpoint}`, `workStatus`, `workStatusUpdatedAt`, `workStatusNote`, `latestReportPath`, `latestResumeCommandPath`, `historyTimelinePath`.
+
+`workflow.nextRecommendedPhase` is the `{phase, status, rationale}` object described in `status.1` — read its three fields, do not print it whole. A `task-manifest.json` written before the object existed still holds a bare string there; `scripts/okstra_ctl/next_phase.py::promote` is what turns that string into the object, and every CLI-projected surface you can read instead (`task-catalog.json`, `okstra rollup`, `okstra recap`) has already applied it. Prefer those over a raw manifest rather than promoting a legacy string yourself.
 
 ```markdown
 ## okstra Task Status — <task-key>
@@ -61,9 +62,8 @@ Required fields: `taskKey`, `taskType`, `workCategory`, `currentStatus`, `latest
 - Current phase: `<phase>`
 - Current phase state: `<phase-state>`
 - Last completed phase: `<phase-or-->`
-- Next recommended phase: `<phase>`
+- Next phase pointer: `<phase-or-->` (`<status>`) — `<rationale-or-->`
 - Awaiting approval: `<yes|no>`
-- Routing status: `<routing-status>`
 - Task status: `<task-status>`
 - Latest run status: `<run-status>`
 - Latest report: `<relative-path-or-->`
@@ -95,9 +95,11 @@ The status response always includes one of:
 
 1. **Resume current run** — if `latestResumeCommandPath` exists, display that path.
 2. **Restart current phase** — task can be re-run with the same `task-key` and current `taskType`.
-3. **Start next phase** — if `workflow.nextRecommendedPhase` is one of `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff`, that phase is proposed. If `nextRecommendedPhase` is `pending-release-handoff`, surface as verdict-gated and propose `release-handoff` only when the cited verdict is `accepted`.
-4. **Need more information** — if `nextRecommendedPhase` is `pending-routing-decision` or `routingStatus` is `pending`.
-5. **Task complete (terminal)** — if `nextRecommendedPhase` is `done-or-follow-up`, the task lifecycle has reached its terminal signal. This is **not** a "next phase" — do not propose a new okstra run. Surface the latest report and ask the user whether any follow-up task should be opened separately.
+Branches 3–5 are decided by `workflow.nextRecommendedPhase.status` alone — one status, one branch, no other field consulted:
+
+3. **Start next phase** — `status` is `ready`. Propose `nextRecommendedPhase.phase` as the next run's `--task-type` and quote its `rationale` as the reason. This is the only status under which a named phase may be launched, so it is the only branch that proposes a run. A `ready` pointer to `release-handoff` already implies an `accepted` final-verification verdict (the report validator refuses that routing target otherwise), so do not re-gate it here.
+4. **Need more information** — `status` is `pending` (the last run did not settle where this task goes next) or `blocked` (it did settle, and the answer is that something outside the run has to change first). Neither proposes a run, and a leftover `phase` name does not change that — `prepare` keeps the name when it lowers a pointer to `pending`, so read `status`, not the emptiness of `phase`. Show the `rationale`, and for `blocked` state what it names as the obstacle. The way forward is a fresh brief, a clarification response, or a re-run of the current phase — not a next-phase launch.
+5. **Task complete (terminal)** — `status` is `terminal`: the task lifecycle ends here. This is **not** a "next phase" — do not propose a new okstra run. Surface the latest report and ask the user whether any follow-up task should be opened separately.
 
 ### status.4 — Update workStatus (write)
 
@@ -135,7 +137,7 @@ Confirm in Korean (the block below shows the message shape only — render the a
 
 | Manifest state | Inferred display |
 |---|---|
-| `currentStatus == "completed"` AND `workflow.nextRecommendedPhase == "done-or-follow-up"` | `done` (inferred) |
+| `currentStatus == "completed"` AND `workflow.nextRecommendedPhase.status == "terminal"` | `done` (inferred) |
 | `currentStatus == "completed"` AND `workflow.currentPhaseState == "completed"` | `phase-done` (inferred) |
 | `currentStatus == "contract-violated"` OR `workflow.currentPhaseState == "blocked"` | `blocked` (inferred) |
 | anything else | `in-progress` (default) |

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

@@ -42,6 +42,7 @@ Omit `--task-group` for the whole project. The JSON shape (all durations are **r
 
 - `taskGroup` — the scope (`null` = whole project), `taskCount` — number of tasks.
 - `tasks[]` — per task: `taskKey, taskGroup, taskId, taskType, workCategory, workStatus, currentPhase, currentPhaseState, nextRecommendedPhase, latestRunStatus, updatedAt, reportPath, runCount, cpuSumMs, wallClockMs, errorCount`, plus `criticRuns, criticGapsProposed, criticGapsMerged, criticGapsRejected, criticGapsUnverified`.
+  - `nextRecommendedPhase` is an **object** `{phase, status, rationale}`, not a phase-name string. Anywhere you surface it, print `nextRecommendedPhase.phase` — or `--` when that string is empty, which is what `status` `pending` / `blocked` / `terminal` all produce. Never interpolate the object into a table cell or a sentence: it renders as a raw dict.
 - `totals` — `runs, cpuSumMs, wallClockMs, errors`, plus `byWorkStatus`, `byWorkCategory`, `byCurrentPhase`, `byTaskType` (each a `{value: count}` map), plus `critic` (`runsWithCritic, gapsProposed, gapsMerged, gapsRejected, gapsUnverified`).
 - The coverage critic is opt-in, so `totals.critic.runsWithCritic == 0` means it was never used — report that as "not used", never as a zero-yield result. When it IS non-zero, the merge rate (`gapsMerged / gapsProposed`) is what tells the user whether the pass earns its tokens; state it only when at least one run used it.
 

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

@@ -32,7 +32,7 @@ Every wizard call returns JSON. The two shapes you'll see:
             "progress": { "index": 5, "total": 11, "remaining": 6 } } }
 ```
 
-Every non-terminal `next` carries a `progress` object (`done` / `aborted` omit it). It holds `index` (1-based number of the **current screen**; pick_group counts as one screen), `total` (the wizard's forward estimate of the full screen count — may grow by a few when the user opens a branch, e.g. choosing *Customize* adds the model screen), `remaining` (`total − index`), and **`label`** — the ready-to-render marker the wizard already composed (e.g. `Step 10/11 · 1 step remaining`, or `Step 11/11 · final step` on the final screen). **Always suffix the rendered prompt with `progress.label` verbatim** — see Step 3. Do not recompute the marker or decide "final step" yourself; only the wizard knows whether more screens follow.
+Every non-terminal `next` carries a `progress` object (`done` / `aborted` omit it). It holds `index` (1-based number of the **current screen**; pick_group counts as one screen), `total` (the wizard's forward estimate of the full screen count — may grow by a few when the user opens a branch, e.g. role-add or extra role-model slots), `remaining` (`total − index`), and **`label`** — the ready-to-render marker the wizard already composed (e.g. `Step 10/11 · 1 step remaining`, or `Step 11/11 · final step` on the final screen). **Always suffix the rendered prompt with `progress.label` verbatim** — see Step 3. Do not recompute the marker or decide "final step" yourself; only the wizard knows whether more screens follow.
 
 ```json
 { "ok": false, "error": "approved plan has no APPROVED marker: ...",
@@ -179,14 +179,14 @@ Repeat until `next.kind == "done"` (or `"aborted"` — terminal cancel, see "How
 That is the entire interactive flow. The wizard handles:
 
 - new-vs-existing task split (remaining work — `workStatus != done` — top-3 newest recommendations + Enter directly), task-group / task-id slug validation (task-group offers the top-3 newest candidates combining recent task use + recent `.okstra/briefs/<group>/` creation activity + Enter directly; task-id offers the top-3 recent candidates from the same group + Enter directly),
-- task-type pick (3 recommendations — `nextRecommendedPhase` recommended / re-run the current phase / the lifecycle's next step — + Enter directly; Enter directly is validated against the full task-type whitelist in a follow-up `text` step),
+- task-type pick (3 options + Enter directly; Enter directly is validated against the full task-type whitelist in a follow-up `text` step). What fills those three depends on `workflow.nextRecommendedPhase` — an object `{phase, status, rationale}`, not a phase-name string. `status: ready` gives the classic trio: its `phase` marked recommended, re-run the current phase, the lifecycle's next step. Any other status contributes nothing at all, since both the recommended slot and the next-step slot derive from that phase — re-run the current phase becomes the first option and the remaining slots fill unlabelled from recently used task-types and then the whitelist. Never recover a phase name from a non-`ready` pointer and propose it yourself: prepare deliberately lowers the pointer to `pending` while its run is unfinished, and the missing recommendation is that signal,
 - brief path — **asked only for entry task-types (requirements-discovery / error-analysis / improvement-discovery / project-analysis / feature-analysis / change-impact-analysis)** (same-group `.okstra/briefs/<task-group>/**/*.md` candidates first, sorted by the newer of file-created/modified time and latest task-catalog use; direct input last; `Keep / Change` for existing entry tasks). `project-analysis`, `feature-analysis`, and `change-impact-analysis` are brief entry task types. A downstream lifecycle task-type auto carries in the manifest's brief, and when no registered brief exists a `brief_carry` 3-option prompt appears (recommend switching to entry / Enter directly / Abort). `release-handoff` has no brief step at all — prepare generates the input document that cites the verification report,
 - analysis-input sub-flow — `project-analysis` has no target or evidence step. `feature-analysis` runs `project_evidence_pick` / `project_evidence`, then `analysis_target_pick` / `analysis_target`; the target is required even when the user skips project evidence. `change-impact-analysis` runs `feature_evidence_pick` / `feature_evidence`, then `project_evidence_pick` / `project_evidence`. The evidence steps show accepted compatible reports first and retain direct-path entry; do not invent a different relation or reorder these steps,
 - base-ref pick + git rev-parse validation (skipped when reusing an active worktree),
-- `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = the earliest incomplete stage whose dependencies are satisfied, or a specific stage number) + executor pick. When an approved plan is selected and a `## PLAN DECISION` sidecar carrying `Status: approved`, exported from the report — matching the plan on source-report·seq — is detected in that run's sibling `user-responses/`, the approve-confirm step expands to 3 options (`yes_apply` recommended: approve + apply the option as exported / `yes` approve only / `no` abort) — `yes_apply` validates the option against the plan's `optionCandidates` before applying it via the existing approval·option path,
+- `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = the earliest incomplete stage whose dependencies are satisfied, or a specific stage number). Implementer slots use role-count / role-model like every other role (`executor` is only a compatibility alias for `implementer`). When an approved plan is selected and a `## PLAN DECISION` sidecar carrying `Status: approved`, exported from the report — matching the plan on source-report·seq — is detected in that run's sibling `user-responses/`, the approve-confirm step expands to 3 options (`yes_apply` recommended: approve + apply the option as exported / `yes` approve only / `no` abort) — `yes_apply` validates the option against the plan's `optionCandidates` before applying it via the existing approval·option path,
 - `release-handoff`-only sub-flow: after the approved plan auto-resolves, a `handoff_stage_pick` multi-select — choose an eligible stage bundle (stage-group) or the whole task (when an accepted whole-task verification report exists); the result goes out as render-args' `stages` key (csv, empty when whole-task),
-- `Use defaults / Customize` branch with profile-aware worker/model questions,
-- **resume-clarification (in-session equivalent)** — there is no separate mode or flag matching the shell's `okstra.sh --resume-clarification`; two steps of the standard flow carry out its substance. (1) `reuse_previous` (yes/no to reuse the previous run's settings — in `requirements-discovery` / `error-analysis` / `implementation-planning`, only when prior run-inputs exist): YES prefills workers·model·directive·related-tasks at once. (2) `clarification_pick`: if the **task-type's own** previous `final-report` exists it is auto-recommended as the carry-in input (falling back to the newest by mtime across all phases when absent), and the same run's `user-responses/` sidecar (answers the user filled in) is attached alongside. The chosen path is passed to prepare as `--clarification-response` — the user makes the sidecar via the report's `Export user response`, places it in `runs/<task-type>/user-responses/`, and re-runs the same phase,
+- launch selection after identity/worktree steps: leader session read-only (current-session) → role-count per static role (`min..max`, omit uses **recommended**, skip when `min == max`) → role-model `provider/model` per slot → min=0 roles only via role-add (default skip). The wizard does not fork on defaults-vs-customize, does not show a provider roster multi-pick, and does not offer a separate implementer-provider pick. Dynamic verifiers are not chosen at launch. `--workers` is compatibility-only, not a launch picker. Repeated `--role-count` / `--role-model` tokens on `renderArgv` are intentional,
+- **resume-clarification (in-session equivalent)** — there is no separate mode or flag matching the shell's `okstra.sh --resume-clarification`; two steps of the standard flow carry out its substance. (1) `reuse_previous` (yes/no to reuse the previous run's settings — in `requirements-discovery` / `error-analysis` / `implementation-planning`, only when prior run-inputs exist): YES prefills role-count·role-model·directive·related-tasks at once. (2) `clarification_pick`: if the **task-type's own** previous `final-report` exists it is auto-recommended as the carry-in input (falling back to the newest by mtime across all phases when absent), and the same run's `user-responses/` sidecar (answers the user filled in) is attached alongside. The chosen path is passed to prepare as `--clarification-response` — the user makes the sidecar via the report's `Export user response`, places it in `runs/<task-type>/user-responses/`, and re-runs the same phase,
 - **re-verification scope (`reverify_scope_pick`, `implementation-planning` clarification re-runs only)** — asked right before `confirm`, and **only when the re-run is narrowable** (every answered `C-NNN` traces back to a stage in the prior report). 3 options: `auto` (recommended — leave it to the lead's `okstra incremental-scope` decision) / `full` (re-verify every stage) / Enter directly (a stage-number CSV, validated against the prior report's Stage Map). The answer goes out as `--reverify-scope` and reaches the lead prompt as the `REVERIFY_SCOPE_MODE` / `REVERIFY_SCOPE_STAGES` tokens; it shapes that CLI's inputs rather than replacing the decision. When the re-run is not narrowable the step does not appear — full is already fixed, and the confirmation block's `reverify-scope` line says which answered id broke the link,
 - `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/implementation-worker-preamble.md

@@ -29,24 +29,9 @@ When `**Evidence ledger:** required-v1` is present, append one canonical row to
 
 Every file citation in the result MUST use backticks, a line suffix, and the same project-relative path its ledger row carries — for example `src/config/env.ts:1-22`. A bare filename (`env.ts:1-22`) does not match its row and fails exactly like a file you never opened, however many times you cited the full path earlier. A cited path without a matching ledger row fails Phase 7 in `validators/validate-run.py` `validate_worker_results_audit()`. Do not add a row for a file you did not open.
 
-## Anchor headers
-
-Every initial implementation prompt begins with these generated common anchors in this exact order, before its implementation-specific body:
-
-1. `**Project Root:** <absolute-path>`
-2. `**Prompt History Path:** <project-relative-path>`
-3. `**Result Path:** <project-relative-path>`
-4. `Assigned worker prompt history path: <absolute-path>`
-5. `**Worker Preamble Path:** <absolute-path>`
-6. `**Worker Error Contract Path:** <absolute-path>`
-7. `**Coding preflight pack:** <absolute-path>`
-8. `**Evidence ledger:** required-v1`
-9. `**Evidence citations:** <rule>` — the ledger-row and citation-path rule of §"Evidence read ledger", restated inline so it is in front of you before your first citation.
-10. `**Errors log path:** <absolute-path>`
-11. `**Errors sidecar path:** <absolute-path>`
-12. `**Read scope:** <allowlist>`
-
-The implementation body additionally carries `**Worktree:**` and its role-sidecar inputs. Do not synthesize any missing path.
+## Injected paths
+
+Use the path headers in the dispatch prompt exactly as written, including `**Coding preflight pack:**` and `**Worktree:**` when present. Do not synthesize any missing path.
 
 ## Return message to the lead
 

package/runtime/templates/project-docs/task-index.template.md

@@ -36,7 +36,6 @@ taskType: "{{FM_TASK_TYPE}}"
 - Last Completed Phase: `{{WORKFLOW_LAST_COMPLETED_PHASE}}`
 - Next Recommended Phase: `{{WORKFLOW_NEXT_RECOMMENDED_PHASE}}`
 - Awaiting Approval: `{{WORKFLOW_AWAITING_APPROVAL}}`
-- Routing Status: `{{WORKFLOW_ROUTING_STATUS}}`
 - Fix cycles: {{FIX_CYCLES_SUMMARY}}
 
 ## Phase States

package/runtime/templates/reports/html/macros/forms.html

@@ -63,6 +63,7 @@
   {% for row in items %}
   {% set is_closed = row.status in ['resolved', 'obsolete'] %}
   {% set approval_context = row.approvalContext | default(None) %}
+  {% set options = row.options | default([]) %}
   <article class="clarification-item" id="id-{{ row.id }}" data-response-id="{{ row.id }}" data-kind="{{ row.kind }}" data-status="{{ row.status }}">
     <p class="eyebrow">{{ row.id }} · {{ row.kind }}</p>
     {{ row.statement | paragraphs }}
@@ -76,9 +77,9 @@
       </p>
     </div>
     {% endif %}
-    {% if row.options %}
+    {% if options %}
     <ol class="clarification-options">
-      {% for option in row.options %}
+      {% for option in options %}
       <li class="clarification-option{% if option.role == 'recommended' %} is-recommended{% endif %}">
         <p class="clarification-option-answer">{{ option.answer }}{% if option.role == 'recommended' %} <span class="badge">{{ t('macros.forms.recommended') }}</span>{% endif %}</p>
         {% if option.disposition | default(None) %}<p class="clarification-option-disposition"><code>{{ option.disposition }}</code></p>{% endif %}
@@ -93,10 +94,10 @@
     </ol>
     {% endif %}
     <label for="response-{{ row.id }}">{{ t('macros.forms.your-answer-to-id') | replace('{id}', row.id) }}</label>
-    {% if row.kind == 'decision' and approval_context and row.options %}
+    {% if row.kind == 'decision' and approval_context and options %}
     <select id="response-{{ row.id }}" data-response-id="{{ row.id }}"{% if is_closed %} disabled{% endif %}>
       <option value="">{{ t('macros.forms.choose-one') }}</option>
-      {% for option in row.options %}<option value="{{ option.answer }}" data-disposition="{{ option.disposition }}"{% if option.role == 'recommended' %} data-recommended="true"{% endif %}{% if row.userInput | default('') == option.answer %} selected{% endif %}>{{ option.answer }}</option>{% endfor %}
+      {% for option in options %}<option value="{{ option.answer }}" data-disposition="{{ option.disposition | default('') }}"{% if option.role == 'recommended' %} data-recommended="true"{% endif %}{% if row.userInput | default('') == option.answer %} selected{% endif %}>{{ option.answer }}</option>{% endfor %}
     </select>
     {% else %}
     <textarea id="response-{{ row.id }}" data-response-id="{{ row.id }}" rows="4"{% if is_closed %} disabled{% endif %}>{{ row.userInput | default('') }}</textarea>

package/runtime/templates/reports/html/tasks/final-verification.template.html

@@ -41,6 +41,6 @@
 <section data-report-section="release-route">
   <h2>{{ t('tasks.final-verification.release-path') }}</h2>
   {{ render_narrative(narrative.releaseReadiness, "finalVerification.userNarrative.releaseReadiness") }}
-  {% if releaseAllowed %}<p>{{ final.routingRecommendation | inline_code }}</p>{% else %}<p>{{ t('tasks.final-verification.the-current-verdict-does-not-allow-release-h') }}</p>{% endif %}
+  {% if releaseAllowed %}<p><strong><code>{{ final.routingRecommendation.target }}</code></strong> — {{ final.routingRecommendation.rationale | inline_code }}</p>{% else %}<p>{{ t('tasks.final-verification.the-current-verdict-does-not-allow-release-h') }}</p>{% endif %}
 </section>
 {% endblock %}

package/runtime/templates/reports/html/tasks/implementation.template.html

@@ -53,6 +53,6 @@
 
 <section data-report-section="next-step" data-report-field="implementation.routingRecommendation">
   <h2>{{ t('tasks.implementation.next-step') }}</h2>
-  <p>{{ implementation.routingRecommendation | inline_code }}</p>
+  <p><strong><code>{{ implementation.routingRecommendation.target }}</code></strong> — {{ implementation.routingRecommendation.rationale | inline_code }}</p>
 </section>
 {% endblock %}

package/runtime/templates/worker-prompt-preamble.md

@@ -25,32 +25,11 @@ Every file citation in the result MUST use backticks, a line suffix, and the sam
 
 ## Evidence command ledger
 
-Append one canonical JSON row to the audit sidecar for each command that produced or verified a conclusion:
+Follow the `**Evidence commands:**` header in the dispatch prompt. That header is the worker-facing rule.
 
-- Evidence command: {"command":"npm run check","cwd":"<project-root>","exitCode":0,"outputSummary":"all checks passed"}
+## Injected paths
 
-Do not record commands used only to explore, including `rg`, `ls`, and file-opening commands. `okstra worker-audit-check` rejects malformed command rows through `okstra_ctl.worker_audit_ledger`.
-
-Write the command as you ran it. Nothing scans these rows for secrets, so a row is never refused for how a setting is named — `AUTH_MODE=off` and `TOKEN_TTL=60` record verbatim. What the row needs to carry is the command's shape, its keys; a value that must not be written down is yours to leave out or pass as a `$VAR` reference, and at execution time that value comes from the environment or from the person running the command.
-
-## Anchor headers (lead-injected, BLOCKING)
-
-Every initial analysis prompt begins with these generated anchors in this exact order, before any other content:
-
-1. `**Project Root:** <absolute-path>`
-2. `**Prompt History Path:** <project-relative-path>`
-3. `**Result Path:** <project-relative-path>`
-4. `**Audit sidecar path:** <absolute-path>` — the generated audit destination; write the sidecar here and never synthesize a `runs/<task-type>/...` path.
-5. `Assigned worker prompt history path: <absolute-path>`
-6. `**Worker Preamble Path:** <absolute-path>` — selects this analysis preamble.
-7. `**Worker Error Contract Path:** <absolute-path>` — shared by every initial audience.
-8. `**Evidence ledger:** required-v1`
-9. `**Evidence citations:** <rule>` — the ledger-row and citation-path rule of §"Evidence read ledger", restated inline so it is in front of you before your first citation.
-10. `**Errors log path:** <absolute-path>`
-11. `**Errors sidecar path:** <absolute-path>`
-12. `**Read scope:** <allowlist>`
-
-`final-verification` additionally carries its six verification-target anchors. `improvement-discovery` carries `**Phase 1.5 Grilling Log:**`. Reverify prompts are lightweight and do not use this preamble.
+Use the path headers in the dispatch prompt exactly as written. Do not synthesize a missing path from a run-directory pattern. `final-verification` may carry verification-target headers. `improvement-discovery` may carry `**Phase 1.5 Grilling Log:**`. Treat extra generated headers the same way. Reverify prompts are lightweight and do not use this preamble.
 
 ## Worker output sections
 
@@ -65,18 +44,6 @@ Every analysis result starts with YAML frontmatter containing the task identity,
 
 Every item has a worker-local ID and file:line evidence where code evidence exists. Sections 1–5 are the common core: feasibility, requirement interpretation, hidden assumptions, alternatives, and execution risk. Section 6 is the only legal home for specialization and is not consensus input.
 
-### Selected-direction planning ownership
-
-For `implementation-planning` with `selected-direction.json`, sections 1–5 read that snapshot and the original requirements, then assess only its realization into files, interfaces, stages, validation, rollback, bidirectional requirement links, and `direction-invalidated` evidence. Direction selection remains upstream of this prompt.
-
-### Legacy candidate-comparison ownership
-
-For an implementation-planning compatibility rerun without the snapshot, sections 1–5 retain candidate comparison, trade-off, recommendation, and `P-Opt-*` evidence.
-
-### Ticket Tagging
-
-For `requirements-discovery`, `error-analysis`, and `implementation-planning`, tag every section 1–5 item with its related ticket. Use `Issue / Ticket`, fall back to Task ID, then `unknown`; comma-separate multiple tickets.
-
 ## Return message to the lead
 
 Begin the inline return with the model identity copied verbatim from the `**Model:** <Role>, <modelExecutionValue>` line in the prompt, followed by the status summary. Never invent or abbreviate the model.