okstra 0.121.1 → 0.122.0

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

@@ -6,7 +6,7 @@ model: opus
 
 # OKSTRA Schedule
 
-Generate a consolidated work schedule for all non-done tasks in a given `task-group`. The skill reads each task's `task-manifest.json` and `latestReport`, classifies tasks into phases by priority and risk, and writes a single Markdown plan file under `.okstra/tasks/<task-group>/schedule/`. It runs as a single Claude lead synthesis (lightweight mode); the frontmatter `model: opus` switches supporting harnesses to Opus-class for the turn — 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 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.
 
 ## When to Use
 
@@ -47,20 +47,23 @@ The installed template `~/.okstra/templates/reports/schedule.template.md` is the
 
 `~/.okstra/lib/validators/validate-schedule.py` is the enforcement for all of the above (heading order, field labels, controlled vocabulary — e.g. `Med-High` is the canonical risk form — forbidden translations, checkbox bans, Gantt fence rules, unresolved-code detection). The Step 4 ambiguous-classification rationale line is the one rule the validator does not yet enforce — emit it yourself.
 
-Two computation rules the template scaffold cannot carry inline:
+One computation rule the template scaffold cannot carry inline:
 
 - **Effort-to-Day mapping**: day ranges per size are defined once in the template's `### Effort Sizing 기준` table. For the At a Glance totals line, sum that table's lower bounds across in-scope tasks for the lower total and upper bounds for the upper total.
-- **`[NEEDS-OKSTRA-RUN]` / `[PARSE-ERROR: <section>]` placement**: put the marker immediately under the per-task heading inside its Phase section and fill only the available fields — never relocate it to a sibling section.
 
 ## Procedure
 
 ### Step 1: Resolve task-group and collect tasks
 
 1. Read `.okstra/discovery/task-catalog.json`.
-2. **Normalise the user-supplied `<task-group>` argument:** 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.
-3. If no tasks found, output `해당 task-group을 찾을 수 없습니다.` and stop.
-4. For each matched task, read `.okstra/tasks/<task-group-segment>/<task-id-segment>/task-manifest.json` directly. Catalog data may be stale; the manifest is authoritative.
-5. **Derive `<project-id>`** for the header: prefer `task-catalog.json`'s top-level `projectId`, otherwise the first matched manifest's `projectId`. Do not invent a value.
+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 **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 `직접 입력`** (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 `해당 task-group의 모든 task가 done 상태입니다. 생성할 schedule이 없습니다.` (or `해당 task-group을 찾을 수 없습니다.` 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.
+4. If no tasks found, output `해당 task-group을 찾을 수 없습니다.` and stop.
+5. For each matched task, read `.okstra/tasks/<task-group-segment>/<task-id-segment>/task-manifest.json` directly. Catalog data may be stale; the manifest is authoritative.
+6. **Derive `<project-id>`** for the header: prefer `task-catalog.json`'s top-level `projectId`, otherwise the first matched manifest's `projectId`. Do not invent a value.
 
 ### Step 2: Filter by workStatus
 
@@ -68,18 +71,35 @@ For inference when `workStatus` is missing or empty, defer to the inference tabl
 
 If 0 tasks remain, output `해당 task-group의 모든 task가 done 상태입니다. 생성할 schedule이 없습니다.` and stop **without creating a file**.
 
-### Step 3: Per-task data extraction
+### Step 3: Per-task stage extraction (Stage Map source)
 
-From `task-manifest.json`: `taskId`, `taskGroup`, `taskKey`, `workCategory`, `workflow.currentPhase`, `workflow.currentPhaseState`, `taskType`, `workStatus`, `latestReportPath`.
+For each in-scope task, the **authoritative source is its `implementation-planning` final-report**, NOT `latestReportPath`. Resolve and parse it as follows:
 
-From the report file (`latestReportPath`): Title / Problem statement, Solution / Architecture, Work Breakdown table, Verification Commands, Rollback strategy, Effort, Risk, Priority, Scope, Repos. Blocking items / approval requests in the report are **not** extracted (see Audience).
+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).
 
-If the report file does not exist or cannot be parsed, attempt the **manifest-staleness fallback** before tagging (`latestReportPath` can go stale when an interleaved `--render-only` prep advances it to a path that is never written):
+**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.
 
-1. Resolve `<task-root>` from the manifest's `taskRootPath`.
-2. List `<task-root>/runs/<taskType>/reports/final-report-*.md` and pick the **newest existing file by mtime** (NOT by filename timestamp). If none, try `<task-root>/runs/*/reports/final-report-*.md` across all task-types.
-3. If found, parse it and add one line at the top of that task's block: `> _Report fallback: manifest pointed at non-existent <pointed-name>, used <actual-name> (mtime <ts>) instead._`
-4. Only if no candidate exists, tag the entry `[NEEDS-OKSTRA-RUN]`, use manifest metadata only, and continue with the remaining tasks. If parsing fails for one section, tag `[PARSE-ERROR: <section>]` and continue.
+**`remainingStages` is empty** (every stage done but `workStatus` not `done`) → not a scheduling target. Render the task as `_완료 — 남은 stage 없음_` under its phase section; contribute no forward day total.
+
+### Step 3.5: Stage selection (per task, user input)
+
+Run this **once per in-scope task that has a non-empty `remainingStages`**, sequentially. A single `task-id` invocation runs it once; a `task-group` runs it per task-id in At-a-Glance order.
+
+**Build dependency-closed cumulative bundles over `remainingStages`:**
+
+1. Order `remainingStages` topologically by `depends_on` (a stage may only appear after all its `depends_on` stages).
+2. Pick natural cut points to form up to **3 cumulative bundles**: `B1` = through the first milestone, `B2` = through the core, `B3` = all remaining. Each bundle is a **dependency-closed prefix** — selecting it never omits a prerequisite stage. Label each bundle with its stage list and summed `step_count` (e.g. `B2: stage 1–4 (steps 12)`).
+3. If `remainingStages` has ≤2 stages, emit only the bundles that are distinct (1–2), never pad to 3.
+
+**Render the picker** with `AskUserQuestion` (one question for this task):
+- Options = the distinct bundles + a final `"남은 stage 전부"` option. `AskUserQuestion`'s built-in Other slot serves the `직접 입력` (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 생략: 남은 stage가 단일 의존성 체인._`).
+
+Record the chosen `selectedStages` for this task. Any custom selection that breaks `depends_on` closure is rejected — re-prompt the same task.
 
 ### Step 4: Phase classification
 
@@ -94,16 +114,35 @@ If the report file does not exist or cannot be parsed, attempt the **manifest-st
 
 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 `> _완료 stage: stage <n>, …_` and carry no forward effort. This keeps the mandatory heading skeleton unchanged while moving the unit of work to the stage.
+
 ### 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 `> 일별 배분은 추정치이며 차단 항목 해소 후 갱신 권장.`). "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 you do skip, insert in the section's position exactly: `> _Gantt Chart 생략: <concrete reason referencing the actual data>._`
 
 **Directive override (highest priority).** Before applying the heuristic, check for a `## Directive` section, first hit wins: (1) the `--directive-file <abs-path>` argument; (2) `<PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/instruction-set/analysis-material.md`; (3) none → apply the default heuristic silently. A found directive overrides the render/skip heuristic for the affected section — note it inline as `> _Per Directive directive: <verbatim short excerpt>._` — and its pre-supplied day allocations / phase weights are used verbatim as bar lengths. A directive file without a `## Directive` heading counts as "no directive".
 
+### 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.
+
 ### 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):
+
 ```
 .okstra/tasks/<task-group-segment>/schedule/<task-group-segment>-plan-<YYYY-MM-DD_HH-MM-SS>.md
 ```
@@ -124,7 +163,7 @@ When you do skip, insert in the section's position exactly: `> _Gantt Chart 생
 - 포함 task: N개
 - 제외(done) task: M개
 - 예상 소요: X.X ~ Y.Y days (Effort 합산)
-- 모드: lightweight
+- 모드: lead + verifier
 ```
 
 ## Edge Cases
@@ -133,8 +172,10 @@ When you do skip, insert in the section's position exactly: `> _Gantt Chart 생
 |------|----------|
 | `workStatus` absent or empty | Resolve via the `okstra-inspect status.4` inference table; include unless resolved `done` |
 | Filtered task count is 0 | Emit "모든 task가 done" message; do NOT create a file |
-| `latestReportPath` missing or unreadable | Staleness fallback, then `[NEEDS-OKSTRA-RUN]` with manifest metadata only |
-| Report parsing fails for one section | `[PARSE-ERROR: <section>]`; continue with the rest |
+| implementation-planning 리포트 없음 | `[NEEDS-PLANNING]` 배너로만 나열, stage picker·Gantt·day total 없음 |
+| 남은 stage 0개(전부 done, workStatus 미표기) | `_완료 — 남은 stage 없음_`, forward 산출 없음 |
+| 남은 stage ≤2개 | 누적 묶음을 나오는 만큼만(1~2), 단일 체인이면 picker 생략·전부 진행 |
+| verifier 2회 미통과 | 최종 파일 미작성, 잔여 missing/extra/order 사용자 보고 |
 | `task-group` matches no tasks | "해당 task-group을 찾을 수 없습니다." 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 |
@@ -144,3 +185,4 @@ When you do skip, insert in the section's position exactly: `> _Gantt Chart 생
 - 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.
+- Per-task section Work Breakdown rows are **selected stages**, not free-form items; done stages are summarized, never scheduled forward.

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

@@ -368,12 +368,12 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 {{ t("implementationPlanning.planBodyBreakageLegend") }}
 
 {% for item in implementationPlanning.planBodyVerification.planItems %}
-**{{ item.id }} — {{ item.subject }}**{% if item.sourceSection %} ({{ t("implementationPlanning.planBodySourceLabel") }} {{ item.sourceSection }}){% endif %}{% if item.clarificationId %} — {{ t("implementationPlanning.planBodyBlockerLabel") }} {{ item.clarificationId }}{% endif %}
+**{{ item.id }} — {{ item.subject }}**{% if item.sourceSection %} ({{ t("implementationPlanning.planBodySourceLabel") }} {{ item.sourceSection }}){% endif %}{% if item.clarificationId %} — {{ t("implementationPlanning.planBodyBlockerLabel") }} {{ item.clarificationId }}{% endif %}{% if item.selfFixNote %} — {{ item.selfFixNote }}{% endif %}
 
 
-| Worker | Verdict | Breakage kind | Note |
-|--------|---------|---------------|------|
-{% for v in item.verdicts %}| {{ v.worker | mdcell }} | {{ v.verdict | mdcell }} | {{ (v.breakageKind or '--') | mdcell }} | {{ (v.note or '') | mdcell }} |
+| Worker | Verdict | Breakage kind | Fixability | Note |
+|--------|---------|---------------|------------|------|
+{% for v in item.verdicts %}| {{ v.worker | mdcell }} | {{ v.verdict | mdcell }} | {{ (v.breakageKind or '--') | mdcell }} | {{ (v.fixability or '--') | mdcell }} | {{ (v.note or '') | mdcell }} |
 {% endfor %}
 
 {% endfor %}

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

@@ -104,7 +104,7 @@
   "implementationPlanning": {
     "planBodyGateLegend": "Gate values — `passed`: agreed, no dissent · `passed-with-dissent`: a minority dissent remains but the gate passes (a majority dissent would block approval) · `blocked-by-disagreement`: majority dissent blocks approval · `aborted-non-result`: verification itself produced no result.",
     "planBodyVerdictLegend": "Verdict — **AGREE**: executable as written and internally consistent with other items · **SUPPLEMENT**: item is sound but a dependency / edge case / precondition is missing · **DISAGREE**: has a defect (see Breakage kind) · **verification-error**: the worker produced no result.",
-    "planBodyBreakageLegend": "Breakage kind — a: cited file path/symbol mismatches another step or option · b: command is not executable or is ambiguous · c: validation signal is not observable · d: rollback violates commit/dependency order · e: contradicts the trade-off matrix · f: requirement-coverage row does not map to an option/stage/step that actually satisfies the requirement. (`--` = not applicable)",
+    "planBodyBreakageLegend": "Breakage kind — a: cited file path/symbol mismatches another step or option · b: command is not executable or is ambiguous · c: validation signal is not observable · d: rollback violates commit/dependency order · e: contradicts the trade-off matrix · f: requirement-coverage row does not map to an option/stage/step that actually satisfies the requirement. (`--` = not applicable) Fixability: planner-fixable = correctable from code + plan + brief; needs-user-input = requires an external decision.",
     "planBodySourceLabel": "source §",
     "planBodyBlockerLabel": "blocks approval →",
     "optionInterfacesLabel": "Affected interfaces / public contracts / downstream consumers",

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

@@ -104,7 +104,7 @@
   "implementationPlanning": {
     "planBodyGateLegend": "게이트 결과 값 뜻 — `passed`: 이견 없이 통과 · `passed-with-dissent`: 소수 워커의 반대가 남았으나 통과(반대가 다수였다면 승인 차단) · `blocked-by-disagreement`: 다수 반대로 승인 차단 · `aborted-non-result`: 검증 자체가 결과를 내지 못함.",
     "planBodyVerdictLegend": "판정(Verdict) — **AGREE**: 적힌 대로 실행 가능하고 다른 항목과 내부적으로 일관됨 · **SUPPLEMENT**: 항목 자체는 타당하나 의존성·엣지케이스·전제조건이 누락됨 · **DISAGREE**: 결함이 있음(결함 유형 참조) · **verification-error**: 워커 검증이 결과를 내지 못함.",
-    "planBodyBreakageLegend": "결함 유형(Breakage kind) — a: 인용한 파일 경로/심볼이 다른 스텝·옵션과 불일치 · b: 명령이 실행 불가하거나 모호함 · c: 검증 신호가 관측 불가 · d: 롤백이 커밋/의존성 순서를 위반 · e: 트레이드오프 매트릭스와 모순 · f: 요구사항 커버리지 행이 요구사항을 실제로 충족하는 옵션/스테이지/스텝에 매핑되지 않음. (`--` = 해당 없음)",
+    "planBodyBreakageLegend": "결함 유형(Breakage kind) — a: 인용한 파일 경로/심볼이 다른 스텝·옵션과 불일치 · b: 명령이 실행 불가하거나 모호함 · c: 검증 신호가 관측 불가 · d: 롤백이 커밋/의존성 순서를 위반 · e: 트레이드오프 매트릭스와 모순 · f: 요구사항 커버리지 행이 요구사항을 실제로 충족하는 옵션/스테이지/스텝에 매핑되지 않음. (`--` = 해당 없음) · 자가수정 가능 여부(Fixability) — planner-fixable: 코드·계획·브리프만으로 수정 가능 · needs-user-input: 외부 결정 필요",
     "planBodySourceLabel": "출처 §",
     "planBodyBlockerLabel": "승인 차단 →",
     "optionInterfacesLabel": "영향 인터페이스 / 공개 계약 / 다운스트림 소비자",

package/runtime/validators/validate-run.py

@@ -1590,6 +1590,8 @@ def validate_final_report_data(report_path: Path, failures: list[str]) -> None:
         _validate_plan_item_extraction_completeness(data, failures)
         _validate_plan_item_subject_substance(data, failures)
         _validate_plan_body_clarification_matching(data, failures)
+        _validate_disagree_has_fixability(data, failures)
+        _validate_self_fix_before_clarification(data, failures)
         _validate_requirement_coverage_covered_by(data, failures)
 
 
@@ -1986,6 +1988,93 @@ def _validate_plan_body_clarification_matching(data: dict, failures: list[str])
             )
 
 
+def _validate_self_fix_before_clarification(data: dict, failures: list[str]) -> None:
+    """A planner-fixable defect MUST pass through a self-fix round before it is
+    promoted to a `## 1. Clarification Items` row. Closes the hole where the
+    lead dumps a fixable plan defect (abbreviated path, prose command,
+    placeholder, coverage remap) onto the user instead of having report-writer
+    correct it (plan-body-verification.md "Self-fix round").
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    pbv = ip.get("planBodyVerification")
+    if not isinstance(pbv, dict):
+        return
+    round_count = pbv.get("roundCount")
+    if not isinstance(round_count, int) or round_count < 1:
+        return
+    if pbv.get("selfFixRoundApplied") is True:
+        return
+    for item in pbv.get("planItems") or []:
+        if not isinstance(item, dict):
+            continue
+        if _classify_plan_item_gate(item) != "majority-disagree":
+            continue
+        disagrees = [
+            v for v in (item.get("verdicts") or [])
+            if isinstance(v, dict) and str(v.get("verdict") or "").upper() == "DISAGREE"
+        ]
+        fixable = [v for v in disagrees if v.get("fixability") == "planner-fixable"]
+        if disagrees and len(fixable) * 2 > len(disagrees):
+            failures.append(
+                "final-report data.json: plan item "
+                f"`{item.get('id') or '<unknown>'}` is majority-disagree with a "
+                "planner-fixable majority but `selfFixRoundApplied` is not true. A "
+                "planner-fixable defect MUST be corrected by a report-writer self-fix "
+                "round before it becomes a clarification row "
+                "(plan-body-verification.md Self-fix round)."
+            )
+
+
+# Allowed `fixability` values, mirroring the schema enum
+# (schemas/final-report-v1.0.schema.json planItems[].verdicts[].fixability).
+_FIXABILITY_VALUES = frozenset({"planner-fixable", "needs-user-input"})
+
+
+def _validate_disagree_has_fixability(data: dict, failures: list[str]) -> None:
+    """Every `DISAGREE` verdict MUST carry a valid `fixability`
+    (`planner-fixable` / `needs-user-input`). The schema enum only constrains a
+    *present* value; it does not require the field, so a DISAGREE with a missing
+    or mislabelled fixability is schema-valid. That silently degrades
+    `_validate_self_fix_before_clarification`, which counts a non-`planner-fixable`
+    DISAGREE as non-fixable and thus lets a genuinely planner-fixable defect
+    skip the self-fix round and land on the user. This is the enforcement point
+    for the "fixability is DISAGREE-only 필수" MUST in plan-body-verification.md.
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    pbv = ip.get("planBodyVerification")
+    if not isinstance(pbv, dict):
+        return
+    round_count = pbv.get("roundCount")
+    if not isinstance(round_count, int) or round_count < 1:
+        return
+    for item in pbv.get("planItems") or []:
+        if not isinstance(item, dict):
+            continue
+        item_id = item.get("id") or "<unknown>"
+        for verdict in item.get("verdicts") or []:
+            if not isinstance(verdict, dict):
+                continue
+            if str(verdict.get("verdict") or "").upper() != "DISAGREE":
+                continue
+            fixability = verdict.get("fixability")
+            if fixability not in _FIXABILITY_VALUES:
+                worker = verdict.get("worker") or "<worker>"
+                allowed = " / ".join(sorted(_FIXABILITY_VALUES))
+                failures.append(
+                    f"final-report data.json: plan item `{item_id}` has a "
+                    f"`DISAGREE` verdict from `{worker}` with "
+                    f"fixability `{fixability}` — a DISAGREE MUST declare a "
+                    f"fixability of {allowed}. A missing/invalid value is "
+                    "counted as non-fixable and lets a planner-fixable defect "
+                    "skip the self-fix round (plan-body-verification.md "
+                    "\"fixability (DISAGREE 전용, 필수)\")."
+                )
+
+
 _COVERED_BY_ANCHOR_RE = re.compile(r"option|stage|step", re.IGNORECASE)
 _COVERED_BY_STAGE_REF_RE = re.compile(r"stage\s*(\d+)", re.IGNORECASE)
 _COVERED_BY_VAGUE = {"recommended option", "the recommended option", "recommended"}

package/runtime/validators/validate-schedule.py

@@ -442,9 +442,13 @@ def validate(path: Path) -> list[str]:
         block = text[block_start:block_end]
         heading_line = text[block_start : text.find("\n", block_start)].strip()
 
-        # Skip blocks marked as NEEDS-OKSTRA-RUN or PARSE-ERROR — these are
-        # intentionally partial.
-        if "[NEEDS-OKSTRA-RUN]" in block or "[PARSE-ERROR" in block:
+        # Skip blocks marked as NEEDS-OKSTRA-RUN, PARSE-ERROR, or NEEDS-PLANNING
+        # — these are intentionally partial.
+        if (
+            "[NEEDS-OKSTRA-RUN]" in block
+            or "[PARSE-ERROR" in block
+            or "[NEEDS-PLANNING]" in block
+        ):
             continue
 
         last_pos = -1

package/runtime/validators/validate_session_conformance.py

@@ -1,22 +1,20 @@
-"""prompts/lead/okstra-lead-contract.md BLOCKING 계약 3종의 post-hoc conformance 검사.
-
-설계: docs/superpowers/specs/2026-06-10-blocking-contract-posthoc-conformance-design.md
-
-| 검사 | 선언 위치 | 증거 |
-|------|----------|------|
-| 1. lead PROGRESS 체크포인트 라인 | prompts/lead/okstra-lead-contract.md "Progress reporting (BLOCKING)" | lead 세션 jsonl 의 assistant text 블록 |
-| 2. claude-worker 5분 heartbeat | agents/workers/claude-worker.md "Heartbeat" | audit 사이드카의 `- PROGRESS: <stage> <ISO>` 라인 |
-| 3. implementation sidecar entry guard | prompts/lead/okstra-lead-contract.md "Entry guard (BLOCKING)" | lead 세션 jsonl 의 Read tool_use |
-
-스캔 규칙 (false-pass 방지가 핵심):
-- `type == "assistant"` 레코드만 본다 — Skill 호출 시 SKILL.md 본문(체크포인트
-  라인 예시 포함)이 tool_result(user 레코드)로 transcript 에 주입되므로,
-  assistant 외 레코드를 보면 즉시 false pass 가 난다. `isSidechain` 레코드도 제외.
-- run 윈도우(`resolve_run_window`)로 스코핑한다 — in-session lead 는 세션 전체
-  jsonl 에 기록되므로, 같은 세션의 직전 run 이 남긴 라인이 증거로 오인된다.
-  (실측: dev-9692 lead 세션 1개에 implementation run 001–003 이 모두 들어 있음.)
-- validator 실행 시점(Phase 7) **이후** 에 출력되는 체크포인트
-  (`phase-7-teardown`, `complete`)는 구조적으로 검사 불가 — 요구하지 않는다.
+"""Post-hoc checks for three BLOCKING neutral lead lifecycle contracts.
+
+Design: docs/superpowers/specs/2026-06-10-blocking-contract-posthoc-conformance-design.md
+
+| Check | Contract | Evidence |
+|-------|----------|----------|
+| 1. lead PROGRESS checkpoints | prompts/lead/okstra-lead-contract.md "Progress reporting (BLOCKING)" | selected adapter evidence source |
+| 2. worker-provider heartbeat | worker provider contract | audit sidecar `- PROGRESS: <stage> <ISO>` lines |
+| 3. implementation sidecar entry guard | prompts/lead/okstra-lead-contract.md "Entry guard (BLOCKING)" | selected adapter evidence source |
+
+Evidence rules prevent false passes:
+- `claude-jsonl` accepts only assistant text and Read tool-use records, excluding
+  injected skill text and sidechain records.
+- Session evidence is scoped to the current run window so a previous run cannot
+  satisfy the neutral lead lifecycle contract.
+- Checkpoints emitted after validation begins (`phase-7-teardown`, `complete`)
+  cannot be observed and are not required.
 """
 from __future__ import annotations
 
@@ -202,7 +200,8 @@ def _collect_lead_evidence(
     if not evidence.scanned_files:
         return None, (
             f"lead session jsonl not found under {proj_dir} "
-            f"(lead.sessionId={lead_sid or '<empty>'}) — PROGRESS checkpoint / "
+            f"(lead.sessionId={lead_sid or '<empty>'}) — selected adapter evidence "
+            "source `claude-jsonl` cannot verify the PROGRESS checkpoint / "
             "implementation entry-guard conformance cannot be verified, which "
             "fails the run (same principle as the token-usage accuracy contract)."
         )
@@ -223,15 +222,16 @@ def _resolve_lead_events_path(
     if not raw:
         return None, (
             "artifact lead event log path missing from team-state "
-            "(`leadEventsPath`) — artifact-only conformance cannot be verified."
+            "(`leadEventsPath`) — selected adapter evidence source `artifact-only` "
+            "cannot verify conformance."
         )
     path = Path(str(raw))
     if not path.is_absolute():
         path = project_root / path
     if not path.is_file():
         return None, (
-            f"artifact lead event log not found: {path} — artifact-only "
-            "conformance cannot be verified."
+            f"artifact lead event log not found: {path} — selected adapter evidence "
+            "source `artifact-only` cannot verify conformance."
         )
     return path, None
 
@@ -301,7 +301,10 @@ def _collect_artifact_lead_evidence(
     try:
         events = read_lead_events(events_path)
     except LeadEventParseError as exc:
-        return None, f"artifact lead event log is malformed — {exc}"
+        return None, (
+            "artifact lead event log is malformed — selected adapter evidence "
+            f"source `artifact-only` cannot verify conformance: {exc}"
+        )
 
     run_seq = suffix.rsplit("-", 1)[1]
     evidence = _LeadEvidence(scanned_files=[events_path])
@@ -324,6 +327,27 @@ def _collect_artifact_lead_evidence(
     return evidence, None
 
 
+def _conformance_evidence_source(
+    team_state: dict,
+) -> tuple[str | None, str | None]:
+    dispatch_mode = str(team_state.get("dispatchMode", "")).strip()
+    if dispatch_mode in _WORKER_DISPATCH_MODES:
+        return "artifact-only", None
+
+    adapter = team_state.get("leadAdapter")
+    if isinstance(adapter, dict):
+        accounting = str(adapter.get("sessionAccounting", "")).strip()
+        if accounting in {"claude-jsonl", "artifact-only"}:
+            return accounting, None
+        if accounting:
+            return None, f"unsupported sessionAccounting: `{accounting}`"
+
+    legacy_runtime = str(team_state.get("leadRuntime", "") or "claude-code")
+    if legacy_runtime in {"codex", "external"}:
+        return "artifact-only", None
+    return "claude-jsonl", None
+
+
 def _convergence_rounds_ran(run_dir: Path, suffix: str | None) -> bool:
     """이 run 의 convergence state artifact 가 실제 round 를 1회 이상 돌았는지.
     auto-disable(`totalRounds: 0`)·artifact 부재는 phase-5.5 라인을 요구하지 않는다."""
@@ -569,7 +593,8 @@ def _check_implementation_sidecar_reads(evidence: _LeadEvidence, errors: list[st
         if not ts_list:
             errors.append(
                 f"implementation entry guard: no `Read` of `{basename}` found in "
-                f"the lead session jsonl within this run's window — the sidecar "
+                "the selected adapter evidence source within this run's window — "
+                "the sidecar "
                 f"MUST be read fresh at {read_at} every implementation run "
                 "(prompts/lead/okstra-lead-contract.md 'Entry guard (BLOCKING)')."
             )
@@ -593,10 +618,10 @@ def validate_session_conformance(
     task_type: str,
     claude_projects_dir: Path | None = None,
 ) -> SessionConformanceResult:
-    """post-hoc conformance 검사 3종을 수행하고 실패 목록을 돌려준다.
+    """Run three post-hoc checks for the neutral lead lifecycle contract.
 
-    `claude_projects_dir` 는 테스트/진단용 주입 시드 (기본: 실제 ~/.claude/projects).
-    검사 2(heartbeat)는 디스크 사이드카만 보므로 lead jsonl 미발견 시에도 수행된다.
+    `claude_projects_dir` injects the Claude project root for tests and diagnostics.
+    Heartbeat validation runs before selecting the adapter evidence source.
     """
     result = SessionConformanceResult()
     _ensure_token_usage_importable()
@@ -610,11 +635,11 @@ def validate_session_conformance(
     suffix = run_artifact_suffix(team_state_path)
     _check_heartbeat_sidecars(run_dir, task_type, suffix, result.errors)
 
-    lead_runtime = team_state.get("leadRuntime", "") or "claude-code"
-    dispatch_mode = str(team_state.get("dispatchMode", "")).strip()
-    if lead_runtime in {"codex", "external"} or (
-        lead_runtime == "claude-code" and dispatch_mode in _WORKER_DISPATCH_MODES
-    ):
+    evidence_source, source_error = _conformance_evidence_source(team_state)
+    if source_error:
+        result.errors.append(source_error)
+        return result
+    if evidence_source == "artifact-only":
         evidence, error = _collect_artifact_lead_evidence(
             team_state, project_root, task_type, suffix
         )

package/src/cli-registry.mjs

@@ -110,6 +110,13 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Summarize a task's manifest + workflow phase state"],
   },
+  {
+    name: "stage-map",
+    module: "./commands/inspect/stage-map.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Dump a task's implementation-planning Stage Map + done stages"],
+  },
   {
     name: "context-cost",
     module: "./commands/inspect/context-cost.mjs",

package/src/commands/inspect/stage-map.mjs

@@ -0,0 +1,100 @@
+import { runPythonSnippet, emitJsonError } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra stage-map — dump a task's implementation-planning Stage Map + done stages
+
+Usage:
+  okstra stage-map <task-key>                  task-key is project-id:task-group:task-id
+  okstra stage-map <task-key> --cwd <dir>      Resolve PROJECT_ROOT from <dir>
+  okstra stage-map <task-key> --project <dir>  Use <dir> directly as PROJECT_ROOT
+
+Output: JSON { ok, taskKey, taskRoot, stages:[{stage_number,title,depends_on,step_count}], doneStages:[int] }.
+stages is [] when no implementation-planning Stage Map exists.
+`;
+
+function parseArgs(args) {
+  const opts = { cwd: process.cwd(), projectRoot: "", taskKey: "" };
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--cwd") {
+      opts.cwd = args[++i];
+      if (!opts.cwd) throw new Error("--cwd requires a path");
+    } else if (a === "--project") {
+      opts.projectRoot = args[++i];
+      if (!opts.projectRoot) throw new Error("--project requires a path");
+    } else if (a === "--json") {
+      // JSON is always emitted; accept the flag for parity with sibling commands.
+    } else if (a.startsWith("--")) {
+      throw new Error(`unknown argument '${a}'`);
+    } else {
+      positional.push(a);
+    }
+  }
+  if (positional.length !== 1) {
+    throw new Error("expected exactly one positional argument: <task-key>");
+  }
+  opts.taskKey = positional[0];
+  return opts;
+}
+
+const SCRIPT = `
+import json, sys
+from pathlib import Path
+from okstra_project import resolve_project_root, find_task_root, read_task_manifest, ResolverError
+from okstra_ctl.implementation_outcome import _load_stage_map
+from okstra_ctl.consumers import read_stage_consumer_state
+
+explicit, cwd, task_key = sys.argv[1], sys.argv[2], sys.argv[3]
+
+try:
+    pr = resolve_project_root(explicit_root=explicit, cwd=cwd)
+except ResolverError as e:
+    print(json.dumps({"ok": False, "stage": "resolve", "reason": str(e)}))
+    sys.exit(2)
+
+task_root = find_task_root(Path(pr), task_key)
+if task_root is None:
+    print(json.dumps({"ok": False, "stage": "task_root", "reason": f"task root not found for {task_key}"}))
+    sys.exit(1)
+
+manifest = read_task_manifest(task_root) or {}
+stages = _load_stage_map(task_root, manifest)
+
+plan_run_root = task_root / "runs" / "implementation-planning"
+done = sorted(read_stage_consumer_state(plan_run_root, recover_from_carry=True).done_stages) if plan_run_root.is_dir() else []
+
+print(json.dumps({
+    "ok": True,
+    "taskKey": task_key,
+    "taskRoot": str(task_root),
+    "stages": stages,
+    "doneStages": done,
+}, ensure_ascii=False, indent=2))
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  let opts;
+  try {
+    opts = parseArgs(args);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
+    return 2;
+  }
+  const result = await runPythonSnippet({
+    script: SCRIPT,
+    args: [opts.projectRoot, opts.cwd, opts.taskKey],
+  });
+  if (result.code !== 0 && !result.stdout.trim()) {
+    emitJsonError({
+      stage: "python",
+      reason: `python invocation failed: ${result.stderr.trim() || "no output"}`,
+    });
+    return 1;
+  }
+  process.stdout.write(result.stdout);
+  return result.code === 0 ? 0 : result.code;
+}

package/src/commands/lifecycle/install.mjs

@@ -45,6 +45,9 @@ const BIN_ENTRYPOINTS = [
 // depend on. Intentionally an exact allowlist, not a directory wildcard.
 const REQUIRED_PROMPT_RESOURCE_FILES = Object.freeze([
   ["prompts", "lead", "okstra-lead-contract.md"],
+  ["prompts", "lead", "adapters", "claude-code.md"],
+  ["prompts", "lead", "adapters", "codex.md"],
+  ["prompts", "lead", "adapters", "external.md"],
   ["prompts", "lead", "context-loader.md"],
   ["prompts", "lead", "team-contract.md"],
   ["prompts", "lead", "convergence.md"],