okstra 0.121.1 → 0.123.0

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

@@ -408,6 +408,7 @@
           "minItems": 1,
           "items": { "$ref": "#/$defs/ImplementationPlanStage" }
         },
+        "designPreparation": { "$ref": "#/$defs/DesignPreparation" },
         "stepwiseExecution": {
           "description": "Legacy flat summary kept for compatibility only. New reports use stageMap/stages.",
           "type": "array",
@@ -1296,6 +1297,337 @@
       }
     },
 
+    "DesignPreparation": {
+      "type": "object",
+      "required": ["mode", "reason", "items"],
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "enum": ["assessed", "no-design-inputs"] },
+        "reason": { "type": "string", "minLength": 1 },
+        "items": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/DesignPrepItem" }
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "mode": { "const": "no-design-inputs" } }
+          },
+          "then": { "properties": { "items": { "maxItems": 0 } } }
+        }
+      ]
+    },
+
+    "DesignPrepKnownFact": {
+      "type": "object",
+      "required": ["statement", "evidence"],
+      "additionalProperties": false,
+      "properties": {
+        "statement": { "type": "string", "minLength": 1 },
+        "evidence": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "DesignPrepProposal": {
+      "type": "object",
+      "required": ["summary", "details", "assumptions", "evidence", "confidence"],
+      "additionalProperties": false,
+      "properties": {
+        "summary": { "type": "string", "minLength": 1 },
+        "details": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "assumptions": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "evidence": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "confidence": { "enum": ["low", "medium", "high"] }
+      }
+    },
+
+    "DesignPrepHumanConfirmation": {
+      "type": "object",
+      "required": ["required", "reason", "suggestedAction"],
+      "additionalProperties": false,
+      "properties": {
+        "required": { "type": "boolean" },
+        "reason": { "type": "string", "minLength": 1 },
+        "suggestedAction": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "DesignPrepReviewPoint": {
+      "type": "object",
+      "required": ["phase"],
+      "additionalProperties": false,
+      "properties": {
+        "phase": { "enum": ["implementation", "final-verification"] },
+        "stage": { "type": "integer", "minimum": 1 }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "phase": { "const": "implementation" } } },
+          "then": { "required": ["stage"] }
+        }
+      ]
+    },
+
+    "DesignPrepItem": {
+      "type": "object",
+      "required": [
+        "id",
+        "kind",
+        "title",
+        "stageRefs",
+        "status",
+        "need",
+        "knownFacts",
+        "openQuestions",
+        "aiProposal",
+        "humanConfirmation"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^PREP-[0-9]{3}$" },
+        "kind": {
+          "enum": [
+            "domain-contract",
+            "persistence-schema",
+            "external-interface",
+            "transaction-consistency",
+            "transformation-mapping",
+            "lifecycle-state-machine",
+            "rollout-observability",
+            "manual-user-test",
+            "other"
+          ]
+        },
+        "title": { "type": "string", "minLength": 1 },
+        "stageRefs": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "integer", "minimum": 1 }
+        },
+        "status": {
+          "enum": ["ready", "provisional", "blocked", "not-applicable"]
+        },
+        "need": { "type": "string", "minLength": 1 },
+        "knownFacts": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/DesignPrepKnownFact" }
+        },
+        "openQuestions": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "aiProposal": { "$ref": "#/$defs/DesignPrepProposal" },
+        "humanConfirmation": {
+          "$ref": "#/$defs/DesignPrepHumanConfirmation"
+        },
+        "workingAssumption": { "type": "string", "minLength": 1 },
+        "guardrails": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "reviewAt": { "$ref": "#/$defs/DesignPrepReviewPoint" },
+        "ifStillOpen": { "enum": ["block", "follow-up"] },
+        "requestPath": {
+          "type": "string",
+          "pattern": "^design-prep-requests/design-prep-request-[0-9]+-PREP-[0-9]{3}\\.md$"
+        },
+        "blockReason": { "type": "string", "minLength": 1 },
+        "requiredDecision": { "type": "string", "minLength": 1 },
+        "notApplicableReason": { "type": "string", "minLength": 1 },
+        "replanTriggerFields": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[^.\\s]+(\\.[^.\\s]+)*$"
+          }
+        }
+      },
+      "oneOf": [
+        {
+          "properties": { "status": { "const": "ready" } },
+          "allOf": [
+            { "not": { "required": ["workingAssumption"] } },
+            { "not": { "required": ["blockReason"] } },
+            { "not": { "required": ["requiredDecision"] } },
+            { "not": { "required": ["notApplicableReason"] } },
+            { "not": { "required": ["requestPath"] } }
+          ]
+        },
+        {
+          "properties": { "status": { "const": "provisional" } },
+          "required": [
+            "workingAssumption",
+            "guardrails",
+            "reviewAt",
+            "ifStillOpen",
+            "requestPath"
+          ],
+          "allOf": [
+            { "not": { "required": ["blockReason"] } },
+            { "not": { "required": ["requiredDecision"] } },
+            { "not": { "required": ["notApplicableReason"] } }
+          ]
+        },
+        {
+          "properties": {
+            "status": { "const": "blocked" },
+            "humanConfirmation": {
+              "properties": { "required": { "const": true } }
+            }
+          },
+          "required": [
+            "blockReason",
+            "requiredDecision",
+            "reviewAt",
+            "ifStillOpen",
+            "requestPath"
+          ],
+          "allOf": [
+            { "not": { "required": ["workingAssumption"] } },
+            { "not": { "required": ["guardrails"] } },
+            { "not": { "required": ["notApplicableReason"] } }
+          ]
+        },
+        {
+          "properties": { "status": { "const": "not-applicable" } },
+          "required": ["notApplicableReason"],
+          "allOf": [
+            { "not": { "required": ["workingAssumption"] } },
+            { "not": { "required": ["guardrails"] } },
+            { "not": { "required": ["reviewAt"] } },
+            { "not": { "required": ["ifStillOpen"] } },
+            { "not": { "required": ["blockReason"] } },
+            { "not": { "required": ["requiredDecision"] } },
+            { "not": { "required": ["requestPath"] } }
+          ]
+        }
+      ]
+    },
+
+    "TriggerEvidence": {
+      "type": "object",
+      "required": ["step", "field", "match"],
+      "additionalProperties": false,
+      "properties": {
+        "step": {
+          "type": ["integer", "null"],
+          "minimum": 1
+        },
+        "field": { "enum": ["files", "action"] },
+        "match": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "InlineDesignContract": {
+      "type": "object",
+      "required": ["summary", "details", "evidence"],
+      "additionalProperties": false,
+      "properties": {
+        "summary": { "type": "string", "minLength": 1 },
+        "details": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "evidence": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+
+    "DesignSurfaceCoverage": {
+      "type": "object",
+      "required": ["kind", "triggerEvidence", "disposition"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "enum": [
+            "domain-contract",
+            "persistence-schema",
+            "external-interface",
+            "transaction-consistency",
+            "transformation-mapping",
+            "lifecycle-state-machine",
+            "rollout-observability",
+            "manual-user-test",
+            "other"
+          ]
+        },
+        "triggerEvidence": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/TriggerEvidence" }
+        },
+        "disposition": {
+          "enum": ["inline-contract", "prep-item", "not-applicable"]
+        },
+        "inlineContract": { "$ref": "#/$defs/InlineDesignContract" },
+        "prepItemId": {
+          "type": "string",
+          "pattern": "^PREP-[0-9]{3}$"
+        },
+        "prepItemIds": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^PREP-[0-9]{3}$" }
+        },
+        "rationale": { "type": "string", "minLength": 1 }
+      },
+      "oneOf": [
+        {
+          "properties": { "disposition": { "const": "inline-contract" } },
+          "required": ["inlineContract"],
+          "allOf": [
+            { "not": { "required": ["prepItemId"] } },
+            { "not": { "required": ["prepItemIds"] } },
+            { "not": { "required": ["rationale"] } }
+          ]
+        },
+        {
+          "properties": { "disposition": { "const": "prep-item" } },
+          "allOf": [
+            { "not": { "required": ["inlineContract"] } },
+            { "not": { "required": ["rationale"] } }
+          ],
+          "oneOf": [
+            {
+              "required": ["prepItemId"],
+              "not": { "required": ["prepItemIds"] }
+            },
+            {
+              "required": ["prepItemIds"],
+              "not": { "required": ["prepItemId"] }
+            }
+          ]
+        },
+        {
+          "properties": { "disposition": { "const": "not-applicable" } },
+          "required": ["rationale"],
+          "allOf": [
+            { "not": { "required": ["inlineContract"] } },
+            { "not": { "required": ["prepItemId"] } },
+            { "not": { "required": ["prepItemIds"] } }
+          ]
+        }
+      ]
+    },
+
     "ImplementationPlanStage": {
       "type": "object",
       "required": [
@@ -1364,6 +1696,10 @@
           "maxItems": 6,
           "items": { "$ref": "#/$defs/StageStepRow" }
         },
+        "designSurfaceCoverage": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/DesignSurfaceCoverage" }
+        },
         "exitContract": { "type": "string", "minLength": 1 },
         "stageValidation": { "type": "string", "minLength": 1 }
       }
@@ -1508,6 +1844,7 @@
             "aborted-non-result"
           ]
         },
+        "selfFixRoundApplied": { "type": "boolean" },
         "planItems": {
           "type": "array",
           "items": {
@@ -1525,6 +1862,7 @@
                   { "type": "string", "pattern": "^C-\\d{3,}$" }
                 ]
               },
+              "selfFixNote": { "type": "string" },
               "verdicts": {
                 "type": "array",
                 "items": {
@@ -1537,6 +1875,7 @@
                       "enum": ["AGREE", "DISAGREE", "SUPPLEMENT", "verification-error"]
                     },
                     "breakageKind": { "type": "string" },
+                    "fixability": { "enum": ["planner-fixable", "needs-user-input"] },
                     "note": { "type": "string" }
                   }
                 }

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

@@ -1,7 +1,7 @@
 ---
 name: okstra-inspect
 description: >-
-  Use this for everything that happens AFTER a single okstra task has already run — inspecting it or light bookkeeping on it, never launching new work. The tell is usually a named task id (PROD-1623, dev-9184), often dropped without the word "okstra." Reach for it when the user wants one task's: status, current/next phase, blockers, or approval gate; its final report — where it is or whether it passed (결론·통과); its elapsed time (소요 시간) or context/read cost (컨텍스트 비용); its run history, re-run, or resume; to mark it done / in-progress / blocked / todo; or a failed run's error logs gathered into a report (에러 리포트). Also bundles cross-project okstra errors into an anonymized feedback zip (에러 환류). Use it even for a bare "mark it done" or "where's the report." NOT for starting a run (okstra-run), rollups/schedules (okstra-rollup / okstra-schedule), a brief (okstra-brief-gen), setup (okstra-setup), or cross-project management (okstra-manager).
+  Use this for everything that happens AFTER a single okstra task has already run — inspecting it or light bookkeeping on it, never launching new work. The tell is usually a named task id (PROD-1623, dev-9184), often dropped without the word "okstra." Reach for it when the user wants one task's: status, current/next phase, blockers, or approval gate; its final report — where it is or whether it passed (결론·통과); its elapsed time (소요 시간) or context/read cost (컨텍스트 비용); its run history, re-run, or resume; to mark it done / in-progress / blocked / todo; or a failed run's error logs gathered into a report (에러 리포트). Also bundles cross-project okstra errors into an anonymized feedback zip (에러 환류). Use it even for a bare "mark it done" or "where's the report." NOT for starting a run (okstra-run), rollups/schedules (okstra-rollup / okstra-schedule-gen), a brief (okstra-brief-gen), setup (okstra-setup), or cross-project management (okstra-manager).
 ---
 
 # OKSTRA Inspect
@@ -186,7 +186,7 @@ Confirm in Korean:
 
 Annotate inferred values with `(inferred)` or `(default)`. Do not back-fill on read; only write when the user explicitly issues an update.
 
-**Catalog sync note:** the CLI updates `task-manifest.json` only. `discovery/task-catalog.json` may be stale until the next run regenerates it; downstream consumers (e.g. `okstra-schedule`) re-read each manifest directly.
+**Catalog sync note:** the CLI updates `task-manifest.json` only. `discovery/task-catalog.json` may be stale until the next run regenerates it; downstream consumers (e.g. `okstra-schedule-gen`) re-read each manifest directly.
 
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 name: okstra-rollup
 description: |
-  Use when the user wants run results from MULTIPLE okstra tasks collected and summarized at once — a task-group digest or a whole-project roll-up, not a single task. Aggregates per-task run count, elapsed time, error count, and latest report path, plus group-level totals and status/category/phase tallies, then synthesizes a cross-task prose summary from the report files. Make sure to use this skill whenever the user mentions "okstra rollup", "롤업", "task-group 요약", "그룹 단위 리포트", "여러 task 결과 모아", "전체 task 현황 요약", "cross-task summary", "그룹 종합 리포트", "모든 task 정리", "run 결과 한꺼번에", even if they don't say "rollup". For a SINGLE task's report/time/errors/recap use okstra-inspect instead; for a forward-looking work plan over non-done tasks use okstra-schedule.
+  Use when the user wants run results from MULTIPLE okstra tasks collected and summarized at once — a task-group digest or a whole-project roll-up, not a single task. Aggregates per-task run count, elapsed time, error count, and latest report path, plus group-level totals and status/category/phase tallies, then synthesizes a cross-task prose summary from the report files. Make sure to use this skill whenever the user mentions "okstra rollup", "롤업", "task-group 요약", "그룹 단위 리포트", "여러 task 결과 모아", "전체 task 현황 요약", "cross-task summary", "그룹 종합 리포트", "모든 task 정리", "run 결과 한꺼번에", even if they don't say "rollup". For a SINGLE task's report/time/errors/recap use okstra-inspect instead; for a forward-looking work plan over non-done tasks use okstra-schedule-gen.
 ---
 
 # OKSTRA Rollup

package/runtime/skills/{okstra-schedule → okstra-schedule-gen}/SKILL.md

@@ -1,12 +1,12 @@
 ---
-name: okstra-schedule
+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" / "일정" / "작업 계획표" for non-done tasks. Trigger words include "okstra schedule", "<task-group> 일정 만들어", "<task-group> schedule 생성", "task-group 작업 계획".
 model: opus
 ---
 
-# OKSTRA Schedule
+# OKSTRA Schedule Gen
 
-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/skills/okstra-user-response/SKILL.md

@@ -57,19 +57,21 @@ Carry the chosen entry's `reportPath` and `taskKey` forward.
 okstra user-response show --report <reportPath>
 ```
 
-Returns `{reportPath, rows: [{id, kind, blocks, status, statement, recommended, alternatives, contextRefs}]}`. For each open `C-*` row, present to the user:
+Returns `{reportPath, rows: [{id, kind, blocks, status, statement, recommended, alternatives, contextRefs, resolvedRefs}]}`. `resolvedRefs` is `[{ref, definition}]` — the CLI has already looked up what each internal token (`RB-002`, `FU-001`, `§4.7`, …) means in the report body; `definition` is `null` only when the report text alone could not resolve it (e.g. a `path:line` pointer).
 
-- **`id`** and its **`statement`** (the original question).
-- **`recommended`** — the answer okstra proposed (+ rationale). It is only a recommendation.
-- **`alternatives[]`** — list them if present.
-- **`contextRefs[]`** — the report `§`/`C-id`/`path:line` references this question points at.
+**Do NOT paste the raw `statement` as the question.** A `statement` like `Rewrite RB-002 rollback (see §4.7)` is meaningless to the user on its own — that is the whole reason this skill exists. For each open `C-*` row, you MUST present:
+
+- **A rewritten, self-contained question** (lead with this): rewrite `statement` in plain language with **every internal token expanded inline** from its `resolvedRefs` `definition` — the user must never have to know what `RB-002` is to answer. If a token's `definition` is `null`, resolve it yourself **using Read** on the report `§`/`path:line` before asking; only if it is genuinely unresolvable do you say so plainly.
+- **`recommended`** — the answer okstra proposed (+ rationale), also stated in plain language. It is only a recommendation.
+- **`alternatives[]`** — list them if present, each in plain language.
+- **Raw source** (secondary, for traceability): the raw `id` + `statement` so the mapping back to the report stays visible.
 
 ## Step 3: Per-item — collect the user's decision (4 branches)
 
 For each open item, the user picks one of four dispositions. You relay and transcribe; you never choose:
 
 1. **Answer** — the user accepts the recommendation or gives their own answer. `disposition: "answer"`, `value` = the user's utterance verbatim.
-2. **Ask-to-explain** — if the user asks "what does this mean?", open the report `§`/`path:line` that this item's `contextRefs[]` points at **using Read** and explain it in plain language. Only explain — **do not pick the answer for the user**; after explaining, hand the decision back to the user.
+2. **Ask-to-explain (fallback)** — Step 2 already expanded every internal token, so the question should already be self-contained. If the user still asks "what does this mean?" or a `resolvedRefs` `definition` was `null`, open the report `§`/`path:line` that this item's `contextRefs[]` points at **using Read** and explain it in plain language. Only explain — **do not pick the answer for the user**; after explaining, hand the decision back to the user.
 3. **Free-form** — the user gives a narrative answer that matches neither a recommendation nor an alternative. `value` = that narrative verbatim, with the rationale in `rationale` if needed. `disposition: "answer"`.
 4. **Hold + reframe** — if the user asks to "re-frame this question itself", record it as `disposition: "reframe"`. Put what the user wants re-asked into `value` verbatim. A reframe is not an answer, so it does not satisfy the approval gate — the next run re-frames that question.