okstra 0.152.0 → 0.154.0

package/runtime/python/okstra_ctl/stage_map.py

@@ -0,0 +1,288 @@
+"""Strict Stage Map parsing shared by planning consumers."""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable
+
+from .md_table import is_separator_row, split_pipe_row
+from .paths import RunRef
+from .plan_run_root import list_implementation_planning_reports
+from .task_target import infer_project_root
+
+
+STAGE_MAP_HEADING = re.compile(r"^##\s+5\.5\s+Stage\s+Map\b", re.MULTILINE)
+_STAGE_MAP_HEADER = (
+    "stage",
+    "title",
+    "depends-on",
+    "step-count",
+    "exit-contract-summary",
+)
+_LEGACY_STAGE_MAP_HEADER = (
+    "stage",
+    "title",
+    "depends_on",
+    "step_count",
+    "exit_contract",
+)
+_STAGE_MAP_HEADERS = {_STAGE_MAP_HEADER, _LEGACY_STAGE_MAP_HEADER}
+
+
+@dataclass(frozen=True)
+class StageMapStage:
+    stage_number: int
+    title: str
+    depends_on: tuple[int, ...]
+    step_count: int
+    exit_contract_summary: str
+
+
+@dataclass(frozen=True)
+class StageMapSnapshot:
+    state: str
+    source_plan_path: str
+    stages: list[dict[str, Any]]
+
+
+class StageMapError(Exception):
+    def __init__(
+        self,
+        code: str,
+        reason: str,
+        source_plan_path: str = "",
+        conflicting_paths: tuple[str, ...] = (),
+    ) -> None:
+        self.code = code
+        self.reason = reason
+        self.source_plan_path = source_plan_path
+        self.conflicting_paths = conflicting_paths
+        details = reason
+        if source_plan_path:
+            details += f"; source={source_plan_path}"
+        if conflicting_paths:
+            details += "; conflicts=" + ", ".join(conflicting_paths)
+        super().__init__(details)
+
+
+def _stage_map_table_lines(text: str, source_plan_path: str) -> list[str]:
+    heading = STAGE_MAP_HEADING.search(text)
+    if heading is None:
+        raise StageMapError(
+            "stage_map", "section '## 5.5 Stage Map' is missing", source_plan_path
+        )
+    body = text[heading.end():]
+    next_heading = re.search(r"^##\s", body, re.MULTILINE)
+    if next_heading is not None:
+        body = body[:next_heading.start()]
+    lines = body.splitlines()
+    headers = [
+        index
+        for index, line in enumerate(lines)
+        if tuple(cell.lower() for cell in split_pipe_row(line))
+        in _STAGE_MAP_HEADERS
+    ]
+    if len(headers) != 1:
+        raise StageMapError(
+            "stage_map",
+            "Stage Map requires exactly one canonical 5-column header",
+            source_plan_path,
+        )
+    header_index = headers[0]
+    if header_index + 1 >= len(lines) or not is_separator_row(lines[header_index + 1]):
+        raise StageMapError(
+            "stage_map", "Stage Map requires a separator row", source_plan_path
+        )
+    return [
+        line for line in lines[header_index + 2:]
+        if line.strip().startswith("|") and not is_separator_row(line)
+    ]
+
+
+def _parse_depends_on(
+    value: str, row_number: int, source_plan_path: str,
+) -> tuple[int, ...]:
+    if value in {"", "(none)"}:
+        return ()
+    dependencies: list[int] = []
+    for token in value.split(","):
+        normalized = token.strip()
+        if not normalized.isdigit() or int(normalized) < 1:
+            raise StageMapError(
+                "stage_map",
+                f"Stage Map row {row_number} has invalid depends-on token "
+                f"{normalized!r}",
+                source_plan_path,
+            )
+        dependencies.append(int(normalized))
+    return tuple(dependencies)
+
+
+def _parse_stage_map_row(
+    line: str, row_number: int, source_plan_path: str,
+) -> StageMapStage:
+    cells = split_pipe_row(line)
+    if len(cells) != 5:
+        raise StageMapError(
+            "stage_map",
+            f"Stage Map row {row_number} requires 5 columns, got {len(cells)}",
+            source_plan_path,
+        )
+    try:
+        stage_number = int(cells[0])
+    except ValueError as exc:
+        raise StageMapError(
+            "stage_map",
+            f"Stage Map row {row_number} has invalid stage number {cells[0]!r}",
+            source_plan_path,
+        ) from exc
+    try:
+        step_count = int(cells[3])
+    except ValueError as exc:
+        raise StageMapError(
+            "stage_map",
+            f"Stage Map row {row_number} has invalid step-count {cells[3]!r}",
+            source_plan_path,
+        ) from exc
+    if stage_number < 1 or step_count < 1:
+        field = "stage number" if stage_number < 1 else "step-count"
+        value = stage_number if stage_number < 1 else step_count
+        raise StageMapError(
+            "stage_map",
+            f"Stage Map row {row_number} has invalid {field} {value!r}",
+            source_plan_path,
+        )
+    return StageMapStage(
+        stage_number,
+        cells[1],
+        _parse_depends_on(cells[2].strip(), row_number, source_plan_path),
+        step_count,
+        cells[4],
+    )
+
+
+def _validate_stage_numbers(
+    stages: list[StageMapStage], source_plan_path: str,
+) -> None:
+    numbers = [stage.stage_number for stage in stages]
+    duplicates = sorted({number for number in numbers if numbers.count(number) > 1})
+    if duplicates:
+        raise StageMapError(
+            "stage_map",
+            f"Stage Map has duplicate stage {duplicates[0]}",
+            source_plan_path,
+        )
+    for row_number, stage in enumerate(stages, start=1):
+        if stage.stage_number != row_number:
+            raise StageMapError(
+                "stage_map",
+                "stage numbers must be 1..N monotonic, "
+                f"got {stage.stage_number} at row {row_number}",
+                source_plan_path,
+            )
+
+
+def parse_stage_map_text(
+    text: str, *, source_plan_path: str = "",
+) -> list[StageMapStage]:
+    if not isinstance(text, str):
+        raise StageMapError(
+            "stage_map", "Stage Map text must be a string", source_plan_path
+        )
+    try:
+        lines = _stage_map_table_lines(text, source_plan_path)
+        if not lines:
+            raise StageMapError(
+                "stage_map", "Stage Map table is empty", source_plan_path
+            )
+        stages = [
+            _parse_stage_map_row(line, row_number, source_plan_path)
+            for row_number, line in enumerate(lines, start=1)
+        ]
+        _validate_stage_numbers(stages, source_plan_path)
+        return stages
+    except StageMapError:
+        raise
+    except (AttributeError, OSError, TypeError, UnicodeError, ValueError) as exc:
+        raise StageMapError("stage_map", str(exc), source_plan_path) from exc
+
+
+def parse_stage_map_file(path: Path) -> list[StageMapStage]:
+    resolved = Path(path).resolve()
+    try:
+        text = resolved.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise StageMapError("stage_map", str(exc), str(resolved)) from exc
+    return parse_stage_map_text(text, source_plan_path=str(resolved))
+
+
+def stage_map_records(stages: Iterable[StageMapStage]) -> list[dict[str, Any]]:
+    return [
+        {
+            "stage_number": stage.stage_number,
+            "title": stage.title,
+            "depends_on": list(stage.depends_on),
+            "step_count": stage.step_count,
+            "exit_contract_summary": stage.exit_contract_summary,
+        }
+        for stage in stages
+    ]
+
+
+def load_task_stage_map(
+    task_root: Path, manifest: dict[str, Any],
+) -> StageMapSnapshot:
+    carried = _unique_carry_source_paths(task_root)
+    if len(carried) > 1:
+        paths = tuple(str(path) for path in carried)
+        raise StageMapError(
+            "plan-source-conflict",
+            "implementation carries reference different source plans",
+            conflicting_paths=paths,
+        )
+    if carried:
+        source = carried[0]
+    else:
+        reports_dir = RunRef.from_task_root(
+            task_root, "implementation-planning"
+        ).reports_dir
+        reports = list_implementation_planning_reports(reports_dir)
+        source = reports[0] if reports else None
+    if source is None:
+        return StageMapSnapshot("missing", "", [])
+    resolved = source.resolve()
+    return StageMapSnapshot(
+        "ready",
+        str(resolved),
+        stage_map_records(parse_stage_map_file(resolved)),
+    )
+
+
+def _unique_carry_source_paths(task_root: Path) -> list[Path]:
+    carry_dir = RunRef.from_task_root(task_root, "implementation").carry_dir
+    paths: set[Path] = set()
+    for carry_path in sorted(carry_dir.glob("stage-*.json")):
+        try:
+            carry = json.loads(carry_path.read_text(encoding="utf-8"))
+        except (OSError, UnicodeError, json.JSONDecodeError):
+            continue
+        value = carry.get("sourcePlanPath") if isinstance(carry, dict) else None
+        if isinstance(value, str) and value:
+            paths.add(_resolve_plan_path(task_root, value).resolve())
+    return sorted(paths, key=str)
+
+
+def _resolve_plan_path(task_root: Path, value: str) -> Path:
+    path = Path(value)
+    if path.is_absolute():
+        return path
+    project_root = infer_project_root(task_root)
+    project_relative = project_root / path
+    if project_relative.exists():
+        return project_relative
+    task_relative = task_root / path
+    if task_relative.exists():
+        return task_relative
+    return project_relative

package/runtime/python/okstra_ctl/wizard.py

@@ -62,6 +62,7 @@ from okstra_ctl.design_prep import (
     write_design_prep_input,
 )
 from okstra_ctl.final_report_paths import final_report_data_path
+from okstra_ctl.plan_run_root import list_implementation_planning_reports
 from okstra_ctl.pr_template import PrTemplateError, resolve_pr_template_path
 from okstra_ctl.run import (
     APPROVED_FRONTMATTER_PATTERN,
@@ -69,12 +70,16 @@ from okstra_ctl.run import (
     _apply_cli_implementation_option,
     _extract_frontmatter_block,
     _load_final_report_data_if_present,
-    _load_parsed_stage_map,
     _reject_blocking_plan_body_gate,
     _set_data_json_approved_true_if_present,
-    _stage_map_reject_detail,
     recommended_role_models,
 )
+from okstra_ctl.stage_map import (
+    StageMapError,
+    parse_stage_map_file,
+    parse_stage_map_text,
+    stage_map_records,
+)
 from okstra_ctl.user_response import (
     UserResponseApprovalRecord,
     parse_user_response_approval,
@@ -1027,27 +1032,23 @@ def _fix_cycle_confirm_required(state: WizardState) -> bool:
 
 
 def _parse_stage_objects(state: WizardState) -> list:
-    """승인 plan 의 Stage Map stage 객체 목록. validator 의 _parse_stage_map 재사용.
-    `_build_stage_pick` 과 `_whole_task_allowed` 가 공유한다.
-
-    빈/손상 Stage Map 은 prepare 게이트(`_parse_stage_map_into_ctx`)와 같은 기준
-    (`_stage_map_reject_detail`)으로 거부한다 — 안 그러면 손상된 맵이 stage 일부만
-    파싱돼 picker 가 '전체 task' 검증을 제안·수락하지만 prepare 가 같은 맵을 하드
-    거부하는 불일치가 생긴다.
-
-    validator 로드는 prepare 와 같은 단일 경로(`_load_parsed_stage_map`)로 위임하고,
-    PrepareError 는 picker 디스패처가 처리하는 WizardError 로 변환한다."""
-    plan_text = Path(state.approved_plan_path).read_text(encoding="utf-8")
+    """Return the approved plan's strict Stage Map objects for the picker."""
     try:
-        stages, errs = _load_parsed_stage_map(plan_text)
-    except PrepareError as exc:
-        raise WizardError(str(exc)) from exc
-    detail = _stage_map_reject_detail(stages, errs)
-    if detail is not None:
+        plan_text = Path(state.approved_plan_path).read_text(encoding="utf-8")
+        return parse_stage_map_text(
+            plan_text,
+            source_plan_path=str(Path(state.approved_plan_path).resolve()),
+        )
+    except OSError as exc:
+        raise WizardError(
+            f"approved plan 의 Stage Map 을 읽을 수 없습니다 "
+            f"({state.approved_plan_path}): {exc}"
+        ) from exc
+    except StageMapError as exc:
         raise WizardError(
             f"approved plan 의 Stage Map 을 신뢰할 수 없습니다 "
-            f"({state.approved_plan_path}): {detail}. plan 의 Stage Map 을 점검하세요.")
-    return stages
+            f"({state.approved_plan_path}): {exc.reason}. plan 의 Stage Map 을 점검하세요."
+        ) from exc
 
 
 def _stage_lifecycle_snapshot(
@@ -2153,16 +2154,8 @@ def _list_implementation_planning_reports(
     ).reports_dir
     if not reports_dir.is_dir():
         return []
-    pat = re.compile(r"^final-report-implementation-planning-(\d+)\.md$")
-    found: list[tuple[int, Path]] = []
-    for child in reports_dir.iterdir():
-        m = pat.match(child.name)
-        if not m:
-            continue
-        found.append((int(m.group(1)), child))
-    found.sort(key=lambda x: -x[0])
     out: list[Path] = []
-    for _, p in found[:limit]:
+    for p in list_implementation_planning_reports(reports_dir)[:limit]:
         try:
             out.append(p.relative_to(Path(state.project_root)))
         except ValueError:
@@ -2691,15 +2684,11 @@ def _resolve_handoff_plan(state: WizardState) -> Path:
 def _handoff_eligibility(state: WizardState) -> list:
     """stage 별 PR 자격 — okstra_ctl.handoff 의 SSOT 판정을 그대로 재사용한다."""
     from okstra_ctl.handoff import compute_eligibility
-    from okstra_ctl.run import _parse_stage_map_into_ctx
     from okstra_ctl.consumers import read_consumers
     plan = _resolve_handoff_plan(state)
     try:
-        stage_map = _parse_stage_map_into_ctx(str(plan))
-    except PrepareError as exc:
-        # PrepareError 가 비어있음(heading rename)·손상(비단조 등)을 이미 구체적으로
-        # 구분해 전달하므로 그 메시지를 그대로 surface 한다 — 'no_stage_map' 으로
-        # 덮으면 손상된 맵을 '맵 없음'으로 오표기하고 어느 행이 깨졌는지 detail 을 잃는다.
+        stage_map = stage_map_records(parse_stage_map_file(plan))
+    except StageMapError as exc:
         raise WizardError(str(exc)) from exc
     rows = read_consumers(plan.resolve().parents[1])
     return compute_eligibility(stage_map, rows)

package/runtime/python/okstra_project/state.py

@@ -383,12 +383,15 @@ def stage_map_read_side_snapshot(project_root: Path, task_key: str) -> dict:
     직접 조립하지 않도록 하는 어댑터다.
     """
     from okstra_ctl.consumers import read_stage_consumer_state
-    from okstra_ctl.implementation_outcome import load_stage_map
     from okstra_ctl.paths import RunRef
+    from okstra_ctl.stage_map import StageMapError, load_task_stage_map
 
     identity = resolve_task_identity(project_root, task_key)
     task_root = Path(identity["taskRoot"])
-    stages = load_stage_map(task_root, identity["manifest"])
+    try:
+        stage_snapshot = load_task_stage_map(task_root, identity["manifest"])
+    except StageMapError as exc:
+        raise StateError(str(exc), stage=exc.code) from exc
     plan_run_root = RunRef.from_task_root(
         task_root, "implementation-planning"
     ).run_dir
@@ -402,7 +405,9 @@ def stage_map_read_side_snapshot(project_root: Path, task_key: str) -> dict:
     return {
         "taskKey": identity["taskKey"],
         "taskRoot": identity["taskRoot"],
-        "stages": stages,
+        "state": stage_snapshot.state,
+        "sourcePlanPath": stage_snapshot.source_plan_path,
+        "stages": stage_snapshot.stages,
         "doneStages": done,
     }
 
@@ -424,11 +429,20 @@ def code_review_target_snapshot(
     비거나 뒤집히고, 단일의존 stage 는 선행 stage 가 재실행되면 어긋난다.
     """
     from okstra_ctl import code_review_paths, worktree_registry
-    from okstra_ctl.implementation_outcome import load_stage_map
+    from okstra_ctl.stage_map import StageMapError, load_task_stage_map
 
     identity = resolve_task_identity(project_root, task_key)
     task_root = Path(identity["taskRoot"])
-    stages = load_stage_map(task_root, identity["manifest"])
+    try:
+        stage_snapshot = load_task_stage_map(task_root, identity["manifest"])
+    except StageMapError as exc:
+        raise StateError(str(exc), stage=exc.code) from exc
+    if stage_snapshot.state != "ready":
+        raise StateError(
+            "implementation-planning Stage Map is missing",
+            stage="missing",
+        )
+    stages = stage_snapshot.stages
     selected = next((s for s in stages if s["stage_number"] == stage), None)
     if selected is None:
         raise StateError(

package/runtime/skills/okstra-schedule-gen/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: okstra-schedule-gen
-description: Use when the user asks for a task-group work schedule, a consolidated implementation plan across multiple tasks in a task-group, or wants to generate a "schedule" / "work plan" for non-done tasks. Trigger words include "okstra schedule", "make a schedule for <task-group>", "generate a <task-group> schedule", "task-group work plan".
+description: Use when the user asks for a task-group work schedule, a consolidated implementation plan across multiple tasks in a task-group, or wants to generate a schedule or work plan for non-done tasks.
 model: opus
 ---
 
 # OKSTRA Schedule Gen
 
-Generate a consolidated work schedule for the selected `implementation-planning` stages of every non-done task in a given `task-group` (or a single `task-id`). For each task the skill reads its `implementation-planning` final-report **Stage Map** as the authoritative forward-looking decomposition, asks the user which stages to include, drafts a single Markdown plan, and only writes the final file after an **independent verifier subagent** confirms the draft covers exactly the selected stages. It runs as a **lead + verifier** flow; the frontmatter `model: opus` switches supporting harnesses to Opus-class for the turn — stage-level cross-task synthesis needs that reasoning depth.
+Generate a consolidated work schedule for the selected `implementation-planning` stages of every non-done task in a given `task-group` (or a single `task-id`). For each task the skill reads the source-aware **Stage Map**, records the user's stage choices in a temporary selection contract, and gates the same draft through deterministic validation followed by an independent narrative review. It runs as a **lead + verifier** flow; the frontmatter `model: opus` switches supporting harnesses to Opus-class for the turn — stage-level cross-task synthesis needs that reasoning depth.
 
 ## When to Use
 
@@ -15,7 +15,7 @@ Generate a consolidated work schedule for the selected `implementation-planning`
 
 **Do NOT use** for single-task analysis (use `okstra-inspect status`) or to execute one task (use `okstra-run`).
 
-Explicit command form: `okstra schedule <task-group> [--title "<custom title>"] [--directive-file <abs-path>]`. If `--title` is omitted, derive a default from `task-group` (e.g. `uploadFont` → `uploadFont — Work Schedule`).
+Public invocation: `/okstra-schedule-gen [task-group]`. A title or directive may be supplied in the host conversation. If no title is supplied, derive a default from `task-group` (e.g. `uploadFont` → `uploadFont — Work Schedule`).
 
 ## Step 0: Preflight
 
@@ -63,7 +63,7 @@ One computation rule the template scaffold cannot carry inline:
 
 1. Read `.okstra/discovery/task-catalog.json`.
 2. **Resolve which task-group to schedule — never silently guess.**
-   - The user **explicitly named a task-group** (as the `okstra schedule <task-group>` argument or unambiguously in the request) → use that token; skip the picker and go to sub-step 3.
+   - The user **explicitly named a task-group** (as the `/okstra-schedule-gen [task-group]` argument or unambiguously in the request) → use that token; skip the picker and go to sub-step 3.
    - The user **named no task-group, or the named token matches 0 or ≥2 groups** → present a 3-option picker via `AskUserQuestion` and do NOT proceed until the user chooses. Build the options from the catalog: walk `tasks[]` in catalog order (already `updatedAt` desc — see `scripts/okstra_ctl/render.py:654`), collect distinct `taskGroupPathSegment` values that have ≥1 entry whose resolved `workStatus` is **non-done** (defer to Step 2's inference table), and offer the newest **1–2** such groups as recommendations. The **last option is always `Enter directly`** (free-text group token, fed into sub-step 3). Label each recommendation with its non-done task count (e.g. `uploadFont (non-done 3)`).
    - If **zero groups have a non-done task** (or the catalog is empty), do NOT open a picker — emit `All tasks in this task-group are done. There is no schedule to generate.` (or `That task-group could not be found.` when the catalog has no tasks at all) and stop **without creating a file**.
 3. **Normalise the resolved `<task-group>`:** lowercase it, then strip every character that is not `[a-z0-9]`. Apply the same transform to each entry's `taskGroupPathSegment`. Match on equality — this is the single comparison rule; do NOT also fall back to the raw `taskGroup` field.
@@ -79,17 +79,23 @@ If 0 tasks remain, output `All tasks in this task-group are done. There is no sc
 
 ### Step 3: Per-task stage extraction (Stage Map source)
 
-For each in-scope task, the **authoritative source is its `implementation-planning` final-report**, NOT `latestReportPath`. Resolve and parse it as follows:
+For each in-scope task, the **authoritative source is its `implementation-planning` Stage Map resolved by the CLI**. Do not hand-parse it or use `latestReportPath` to choose its source. Call:
 
-1. Resolve `<task-root>` from the manifest's `taskRootPath`. The planning report lives under `<task-root>/runs/implementation-planning/**/reports/final-report-*.md`. If several exist, pick the **newest by mtime**.
-2. Do NOT hand-parse the Stage Map markdown. Call `okstra stage-map <task-key> --json` (Task 0). It returns `{ok, taskRoot, stages:[{stage_number,title,depends_on,step_count}], doneStages:[int]}` by wrapping `_load_stage_map` + `read_stage_consumer_state().done_stages`. `stages: []` means no planning Stage Map exists → treat as **no planning report** below.
-3. From each stage row keep `stage_number`, `title`, `depends_on`, `step_count`. Compute `remainingStages = stages − doneStages`.
-4. From `task-manifest.json` still read task-level metadata for the header and phase bucket: `taskId`, `taskGroup`, `taskKey`, `workCategory`, `workStatus`, `taskType`, `workflow.currentPhase`.
-5. From the planning report also read task-level Priority / Risk / Scope / Repos for phase classification and the At a Glance row. Blocking / approval items are **not** extracted (see Audience & authority).
+```bash
+okstra stage-map <task-key> --json
+```
+
+The response is source-aware: `{ok, taskKey, taskRoot, state, sourcePlanPath, stages:[{stage_number,title,depends_on,step_count}], doneStages:[int]}`. Branch on it explicitly:
+
+The resolved source, when ready, is a report under `runs/implementation-planning`; the CLI owns choosing exactly one report from that domain.
+
+- `ok: true, state: "ready"` — preserve `sourcePlanPath`, stage rows, and `doneStages`. Compute unfinished stages as `stages − doneStages`. Only unfinished stages can be selected. Every selected stage's transitive prerequisites must be either selected or present in `doneStages`; the completed prerequisite closure is retained as evidence, never rendered as forward work.
+- `ok: true, state: "missing"` — record an empty source and empty stage sets. Tag the task `[NEEDS-PLANNING]`, skip the stage picker, and render task-level metadata only, with no forward Work Breakdown row, Gantt row, or day total.
+- `ok: false` or any state other than `ready` and `missing` — this is a structured Stage Map error, such as a corrupt or conflicting plan source. Stop before drafting, preserve the CLI `stage` and `reason` in the user-facing error, and do not guess from another report.
 
-**No planning Stage Map** (`stage-map` returned `stages: []`) → this task cannot be stage-scheduled. Tag it `[NEEDS-PLANNING]`, skip the Step 3.5 stage picker for it, and render it under its phase section as a single banner line with task-level metadata only (no Gantt bars, no day total). Continue with the remaining tasks.
+For `ready`, read task-level Priority / Risk / Scope / Repos from `sourcePlanPath`. Read header and phase-bucket metadata from `task-manifest.json`: `taskId`, `taskGroup`, `taskKey`, `workCategory`, `workStatus`, `taskType`, and `workflow.currentPhase`. Blocking and approval items are not extracted (see Audience & authority).
 
-**`remainingStages` is empty** (every stage done but `workStatus` not `done`) → not a scheduling target. Render the task as `_Complete — no remaining stage_` under its phase section; contribute no forward day total.
+If unfinished stages are empty while `workStatus` is not `done`, render `_Complete — no remaining stage_` under the task's phase section and contribute no forward day total.
 
 ### Step 3.5: Stage selection (per task, user input)
 
@@ -105,28 +111,32 @@ Run this **once per in-scope task that has a non-empty `remainingStages`**, sequ
 - Options = the distinct bundles + a final `"All remaining stages"` option. `AskUserQuestion`'s built-in Other slot serves the `Enter directly` (arbitrary stage subset) case; when the user supplies a custom subset, close it under `depends_on` before accepting.
 - **Degenerate skip:** if only one distinct bundle exists AND it already equals all remaining stages, skip the picker for this task and set `selectedStages = remainingStages` (log `> _Stage picker skipped: remaining stages form a single dependency chain._`).
 
-Record the chosen `selectedStages` for this task. Any custom selection that breaks `depends_on` closure is rejected — re-prompt the same task.
+Record the chosen `selectedStages` for this task. Reject and re-prompt any custom selection whose transitive `depends_on` closure is not covered by `selectedStages ∪ doneStages`.
 
 ### Step 4: Phase classification
 
-`workCategory` keys come from `scripts/okstra_ctl/worktree.py::_WORK_CATEGORY_PREFIX` (code source) plus the `unknown` fallback from `render.py`. When a category is added there, add a row here — otherwise it falls through to `unknown` → Phase 2.
+The canonical categories come from `scripts/okstra_ctl/work_categories.py::WORK_CATEGORIES`. Do not infer or publish another category.
 
 | workCategory | Default phase |
 |--------------|---------------|
 | `bugfix` | Phase 1 when risk is High/Med-High; otherwise Phase 2 |
-| `feature` / `improvement` / `docs` / `doc` | Phase 2 |
+| `feature` / `improvement` | Phase 2 |
 | `refactor` / `ops` | Phase 3 |
-| `unknown` (or unmatched / missing) | Phase 2, with rationale `> _workCategory '<raw-value>' undefined — defaulting to Phase 2._` at the top of that phase section |
+| unmatched or missing | Phase 2, with rationale `> _workCategory '<raw-value>' undefined — defaulting to Phase 2._` at the top of that phase section |
 
 Priority overrides category: `P0` → Phase 1; `P1`/`P2` → Phase 2; `P3` or multi-repo + infrastructure scope → Phase 3. When still ambiguous, place the task in the closest phase and add a one-line rationale at the top of that phase section (not validator-enforced — emit it yourself).
 
-Phase bucketing stays **task-level** (a task lands in one Phase by its `workCategory`/Priority). Within a task's per-task section, the **selected stages become the Work Breakdown rows**: one row per `selectedStages` entry with its `title`, `step_count`-derived effort, and `depends_on`. Stages excluded from `selectedStages` because they are already done are listed once as `> _Done stages: stage <n>, …_` and carry no forward effort. This keeps the mandatory heading skeleton unchanged while moving the unit of work to the stage.
+Phase bucketing stays **task-level** (a task lands in one Phase by its `workCategory`/Priority). `workStatus` is only a Step 2 candidate filter. In the per-task `Item / Detail` table, render `Status` as `<taskType> / <currentPhase>`.
+
+Within a task's per-task section, selected stages become the Work Breakdown rows under the exact header `| Stage | Title | Steps | Depends On | Days |`. Render one row per selected stage using its Stage Map `title`, `step_count`, and `depends_on`, plus its proportional day range. Stages excluded because they are already done are listed once as `> _Done stages: stage <n>, …_` and carry no forward effort.
 
 ### Step 5: Gantt decision (render by default)
 
 `## Gantt Chart` is **rendered by default** — skip ONLY when literally no day signal exists (every task is effort=XXL with no visible decomposition, or all tasks lack both effort sizing and decomposition). Render whenever any of these hold: 2+ tasks with effort sizing; 1 task whose effort yields a range (mid-point bar, or `lo`/`hi` two-bar form); 1 task with Part/Phase/Step decomposition in the source (bars at decomposition-unit level); total estimated effort ≥ 3 days. When per-unit day allocations aren't itemized, split the parent range across the visible units yourself and append the `est` annotation (or add `> Per-day allocation is an estimate; refresh recommended after blocking items are resolved.`). "Range is wide", "single task", "user decisions pending" are NOT skip reasons — render an estimate-tagged chart instead.
 
-When the source is a Stage Map, the Gantt **bars are the selected stages** (one bar per `selectedStages` entry), day length split from `step_count` (or the effort range across the stage's steps), and cross-stage `(after stage <n>)` / `(after <TASK-ID>)` edges follow `depends_on`. Already-done stages never get a bar. A task tagged `[NEEDS-PLANNING]` contributes no bars.
+When the source is a Stage Map, the Gantt bars are selected stages. Every row identifier is `<TASK-ID>/S<stage-number>` and carries `days=<lower>~<upper>` matching the Work Breakdown row. Split the task effort range proportionally by `step_count`; round every stage except the last to 0.5 day and let the last stage absorb the remainder. Cross-stage dependency annotations follow `depends_on`. Already-done and non-selected stages never get a bar. A task tagged `[NEEDS-PLANNING]` contributes no bars.
+
+An unrepresentable half-day allocation is a validation error. Do not switch to a fallback allocation algorithm or publish that draft.
 
 When you do skip, insert in the section's position exactly: `> _Gantt Chart skipped: <concrete reason referencing the actual data>._`
 
@@ -134,20 +144,51 @@ When you do skip, insert in the section's position exactly: `> _Gantt Chart skip
 
 ### Step 5.5: Draft, verify, gate
 
-1. **Draft to staging (never the final path yet).** Write the assembled schedule to `.okstra/tasks/<task-group-segment>/schedule/.draft/<YYYY-MM-DD_HH-MM-SS>.md`. Auto-create the parent.
-2. **Dispatch an independent verifier subagent** with the `Agent` tool. It receives, per task: the `selectedStages` list (stage numbers + titles) and `depends_on` edges, plus the draft file path. It must NOT see the lead's reasoning — only these inputs and the draft. It returns a structured verdict:
-   - `coverage`: every `selectedStages` entry appears as a forward Work Breakdown / Gantt unit in the draft (nothing missing).
-   - `noExcess`: no non-selected stage and no done stage appears as forward work.
-   - `depOrder`: stage ordering and `(after …)` edges honor `depends_on`.
-   - `pass = coverage && noExcess && depOrder`; on fail it lists the offending stages as `missing[]` / `extra[]` / `orderViolations[]`.
-3. **Gate:**
-   - `pass` → promote the draft to the final path (Step 6) and continue.
-   - `fail` → hand the verifier's `missing`/`extra`/`orderViolations` back to the lead, revise the draft in place, and re-dispatch the verifier. **Max 2 revise cycles.**
-   - Still failing after the 2nd cycle → do **NOT** write the final file. Remove the staging draft, and report the residual `missing`/`extra`/`orderViolations` to the user in Korean. Stop.
+1. **Write paired staging artifacts.** Write the schedule to `.okstra/tasks/<task-group-segment>/schedule/.draft/<YYYY-MM-DD_HH-MM-SS>.md` and its temporary selection contract to the sibling `.draft/<YYYY-MM-DD_HH-MM-SS>.selection.json`. Use the same timestamp and auto-create the parent.
+2. **Write schema version 1 selection JSON.** Include every in-scope task, including `missing` and ready tasks with no unfinished stage. Map CLI stage fields to the validator's camel-case boundary:
+
+```json
+{
+  "schemaVersion": 1,
+  "tasks": [{
+    "taskKey": "<project>:<group>:<task>",
+    "taskId": "<TASK-ID>",
+    "state": "ready",
+    "sourcePlanPath": "<resolved planning report>",
+    "selectedStages": [2, 3],
+    "doneStages": [1],
+    "stages": [
+      {
+        "stageNumber": 1,
+        "title": "Prepare port",
+        "dependsOn": [],
+        "stepCount": 2
+      },
+      {
+        "stageNumber": 2,
+        "title": "Build adapter",
+        "dependsOn": [1],
+        "stepCount": 3
+      },
+      {
+        "stageNumber": 3,
+        "title": "Wire consumer",
+        "dependsOn": [2],
+        "stepCount": 2
+      }
+    ]
+  }]
+}
+```
+
+3. **Run the deterministic gate first.** Execute `python3 ~/.okstra/lib/validators/validate-schedule.py <draft> --selection-json <selection>`. Do not dispatch the narrative verifier when this exits non-zero.
+4. **Run the independent LLM verifier second.** Only after the deterministic gate passes, dispatch an independent verifier subagent with the draft and selection JSON, but without the lead's reasoning. It checks client-facing coherence, phase rationale, executable ordering, engineering-only scope, and whether the prose contradicts the structured schedule. It returns `pass` plus concrete findings.
+5. **Revise from the first gate after every change.** If either gate requests a change, the lead revises the same draft in place, then starts again at the deterministic `--selection-json` gate. Allow **Max 2 revise cycles** total across both gates.
+6. **Gate publication.** Only the same draft that passes both gates may be promoted in Step 6. If it still fails after the second revision, do not write the final file; remove the paired staging artifacts and report the residual findings in Korean.
 
 ### Step 6: Write the schedule file
 
-Reached only after Step 5.5 returns `pass`. **Promote** the verified staging draft to the final path (do not re-render from scratch):
+Reached only after both Step 5.5 gates return `pass`. Promote the verified same draft to the final path; do not re-render or regenerate it:
 
 ```
 .okstra/tasks/<task-group-segment>/schedule/<task-group-segment>-plan-<YYYY-MM-DD_HH-MM-SS>.md
@@ -157,10 +198,9 @@ Reached only after Step 5.5 returns `pass`. **Promote** the verified staging dra
 
 ### Step 7: Self-validate before reporting completion
 
-1. Re-read the file you just wrote.
-2. Run `python3 ~/.okstra/lib/validators/validate-schedule.py <output-path>`.
-3. If it exits non-zero, fix the file and re-validate. Do not print the Step 8 message until it passes.
-4. If the validator is not installed, fall back to a manual check against the template: every template `##` heading present with exact spelling, title ends with `— Work Schedule`, `> Generated:` block present.
+1. Re-read the file you just promoted and confirm it is byte-identical to the gate-passing draft content.
+2. Run `python3 ~/.okstra/lib/validators/validate-schedule.py <output-path>` as a final format check; use the repository validator only when the installed validator is absent.
+3. Delete the temporary `.selection.json` only after that final check passes. Do not print the Step 8 message while the selection contract still exists or validation is failing.
 
 ### Step 8: Completion message (Korean)
 
@@ -181,7 +221,7 @@ Reached only after Step 5.5 returns `pass`. **Promote** the verified staging dra
 | No implementation-planning report | List with a `[NEEDS-PLANNING]` banner only; no stage picker / Gantt / day total |
 | 0 remaining stages (all done, workStatus unmarked) | `_Complete — no remaining stage_`, no forward computation |
 | ≤2 remaining stages | Emit only as many cumulative bundles as arise (1–2); a single chain skips the picker and proceeds with all |
-| verifier fails twice | Final file not written; report residual missing/extra/order to the user |
+| either validation gate still fails after two revisions | Final file not written; report residual findings to the user |
 | `task-group` matches no tasks | "That task-group could not be found." and stop |
 | Catalog and manifest disagree on `workStatus` | Manifest wins (catalog may be stale) |
 | task-group casing / punctuation variants | Normalise both sides (lowercase + strip non-`[a-z0-9]`), compare against `taskGroupPathSegment` only; use the manifest's segment verbatim for path output |
@@ -190,5 +230,5 @@ Reached only after Step 5.5 returns `pass`. **Promote** the verified staging dra
 
 - All user-facing messages in Korean; schedule body prose Korean, identifiers/headings/field labels English (template literals).
 - Use project-relative paths in completion messages.
-- Use `taskType` (not `workStatus`) for the At a Glance status column — it carries lifecycle phase information.
+- Use `<taskType> / <currentPhase>` (not `workStatus`) for each detail `Status`; `workStatus` only filters candidates.
 - Per-task section Work Breakdown rows are **selected stages**, not free-form items; done stages are summarized, never scheduled forward.