okstra 0.155.0 → 0.157.0

package/runtime/templates/reports/schedule.template.md

@@ -22,11 +22,17 @@ taskType: "{{FM_TASK_TYPE}}"
 
 **<N> tasks total / estimated effort: <X.X> ~ <Y.Y> days (Effort sum)**
 
-| # | Task ID | Title | Category | Priority | Effort | Days | taskType | Risk | Phase |
-|---|---------|-------|----------|----------|--------|------|----------|------|-------|
-| 1 | <TASK-ID> | <Title> | <category> | <P0~P3> | <S/M/L/XL> | <range> | <taskType> | <risk> | <1/2/3> |
+<!-- `Days` is the task's own range and MUST equal the sum of its Work Breakdown
+     stage rows. Append ` (est)` when the range was derived from `step_count`
+     rather than stated by the plan — which is every range today, because
+     implementation-planning does not estimate duration. `[NEEDS-PLANNING]` is
+     reserved for a task with NO planning report at all. -->
 
-**Effort distribution**: S × <n> / M × <n> / L × <n> / XL × <n>
+| # | Task ID | Title | Category | Priority | Effort | Days | Risk |
+|---|---------|-------|----------|----------|--------|------|------|
+| 1 | <TASK-ID> | <Title> | <category> | <P0~P3> | <S/M/L/XL/XXL> | <X.X> ~ <Y.Y> (est) | <risk> |
+
+**Effort distribution**: S × <n> / M × <n> / L × <n> / XL × <n> / XXL × <n>
 **Risk distribution**: Very Low × <n> / Low × <n> / Medium × <n> / Med-High × <n> / High × <n>
 **Impact by repo**: <repo1> (<n>) / <repo2> (<n>)
 
@@ -34,11 +40,13 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Executive Summary
 
-<2-4 sentences — phase-classification summary + execution strategy>
+<2-4 sentences — what this schedule covers and the execution strategy.>
+
+<!-- One bullet per in-scope task, naming the stages actually selected. This is
+     the stage roster, not a priority bucket — At a Glance is sorted
+     Priority-first and that ordering is where priority lives. -->
 
-- **Phase 1 (Critical Fixes)**: <n> tasks — <summary>
-- **Phase 2 (Enhancements)**: <n> tasks — <summary>
-- **Phase 3 (Architecture)**: <n> tasks — <summary>
+- **<TASK-ID>**: stages <n>–<m> selected (<total> steps) — <summary>
 
 ### Effort Sizing Criteria
 
@@ -48,31 +56,54 @@ taskType: "{{FM_TASK_TYPE}}"
 | **M** | 3-5 files, 1 repo, includes new tests, no DB changes | 2 - 3 |
 | **L** | 5-15 files, 2-3 repos, sequential deploy, may include package release | 3 - 5 |
 | **XL** | 15+ files, 3+ repos + infra, concurrent frontend changes, architecture migration | 5 - 10 |
-| **XXL** | needs further decomposition | 10 - |
+| **XXL** | decomposed into stages; the day range is the stage sum | 10 - |
+
+<!-- XXL has no finite upper bound in this table on purpose: an XXL task is
+     sized by its own stage decomposition, so its `Days` range comes from the
+     Work Breakdown sum and NOT from this row. Every other size takes its range
+     from here. -->
+
+### Priority & Risk Scale
+
+<!-- Controlled vocabulary the At a Glance cells draw from. The schedule is read by people who never saw the source report,
+     so a `P0` or a `High` that is never defined is an opaque code with a
+     friendlier shape. Keep both tables verbatim. -->
+
+| Priority | 기준 |
+|----------|------|
+| **P0** | 다른 작업을 막고 있거나 운영 중인 서비스에 직접 영향 — 이번 주기에 착수 |
+| **P1** | 다음 주기 안에 착수해야 하며, 미루면 P0 로 올라갈 사유가 있음 |
+| **P2** | 계획된 개선 — 일정 여유에 맞춰 배치 |
+| **P3** | 가치는 인정되나 착수 시점이 정해지지 않음 |
+
+| Risk | 기준 |
+|------|------|
+| **High** | 되돌림 비용이 크거나, 실패가 사용자에게 보이는 형태로 드러남 |
+| **Med-High** | 회귀 가능성이 있고 감지 장치가 일부 구간에만 있음 |
+| **Medium** | 표준 절차로 감지·복구 가능 |
+| **Low** | 영향 범위가 좁고 즉시 되돌릴 수 있음 |
+| **Very Low** | 실패해도 관측 가능한 영향이 없음 |
 
 ---
 
 ## Task Dependency Graph
 
-<!-- Use ONE of:
-     (A) literal `_none_` when no edges exist (single-task scope or no extracted edges).
-     (B) plain ``` fenced adjacency-list block. Each non-empty line is one of:
-         - adjacency: `<TASK-ID> -> <TASK-ID>[, <TASK-ID>]*`
-         - comment: `# <free prose>` (max one per group)
-         - blank: group separator
-     Example (B):
-     ```
-     DEV-1 -> DEV-2, DEV-3
-     DEV-2 -> DEV-4
-     # Phase 3 fan-out
-     DEV-5 -> DEV-6
-     ```
-     Rules:
-     - ASCII arrow `->` only; Unicode `→` is rejected so downstream tooling does not handle both.
-     - Both endpoints MUST be `TASK-ID` literals (same identifiers as the At a Glance table). Free text is forbidden.
-     - Fence MUST be plain ``` with NO language tag. ```mermaid / ```plantuml / ```graphviz / ```dot are all rejected.
-     - If only one task is in scope (no dependencies), use Shape A — do NOT emit an empty fence. -->
-_none_
+<!-- OPTIONAL — omit the whole section, heading included, when no task depends on
+     another. That is always the case for a single-task schedule, and a section
+     whose entire body says "the relation is in that other table" is noise the
+     reader steps over. Stage order is NEVER drawn here: the Work Breakdown's
+     `Depends On` column owns it.
+     When two or more tasks are coupled, render a plain ``` fenced adjacency
+     list, `<TASK-ID> -> <TASK-ID>[, …]`, one edge per line, `# <prose>`
+     comments allowed. ASCII `->` only; Unicode `→` is rejected. The fence takes
+     no language tag — ```mermaid / ```plantuml / ```graphviz / ```dot are all
+     rejected. -->
+
+```
+DEV-1 -> DEV-2, DEV-3
+# release order
+DEV-2 -> DEV-4
+```
 
 ---
 
@@ -82,35 +113,56 @@ _none_
      If included, MUST use this exact heading literal `## Gantt Chart`.
      Render as ASCII inside a fenced ``` block with NO language tag.
      Mermaid / PlantUML / Graphviz are forbidden.
-     The axis is RELATIVE DAY-COUNTS (Day 1 / J1, …) — never calendar dates.
+
+     GEOMETRY — the validator checks these, they are not decoration:
+     - One column = 0.5 day. This is what lets a 2.5-day stage draw honestly.
+     - The axis starts at Day 1 and its last tick is the smallest multiple of 5
+       that covers the schedule's upper bound. Do not draw empty months.
+     - A row's bar starts at the cumulative LOWER bound of everything it waits
+       on, and runs `lower / 0.5` filled cells `█` then `(upper - lower) / 0.5`
+       open cells `░`.
+     - Row label is `Stage <n>` for a single-task schedule, spelled out so the
+       reader never cross-references an abbreviation. With 2+ tasks, prefix the
+       task-id: `<TASK-ID> Stage <n>`.
+     - A row is a label and a bar, with NOTHING after it. No `days=` (the Work
+       Breakdown's Days column owns those numbers and the validator compares the
+       bar against it), and no per-row `! crit` / `est` markers — when every row
+       carries the same marker it distinguishes nothing.
      If day estimates are missing, omit this whole section and replace it with one blockquote: `> _Gantt Chart omitted: <reason>_`. -->
 
+> 한 칸은 반나절이다. `█` 는 하한 일수만큼, `░` 는 거기서 상한까지의 여유만큼 그린다.
+
 ```
-Day:            1    5    10   15   20   25   30
-                |    |    |    |    |    |    |
-Phase 1
-  <TASK-ID>/S<stage-number>    ██████          ! crit days=<lower>~<upper>
-  <TASK-ID>/S<stage-number>          ████████  days=<lower>~<upper>
-Phase 2
-  <TASK-ID>/S<stage-number>                  ██████░░  est days=<lower>~<upper>
-Phase 3
-  <TASK-ID>/S<stage-number>                           ████  (after <TASK-ID>/S<stage-number>) days=<lower>~<upper>
+Day:      1       5         10        15
+          |       |         |         |
+Stage 1   ████░░
+Stage 2       ████░░
+Stage 3           ██████░░░░
 ```
 
-> The axis is in **relative day-counts** (Day 1 = Phase 1 start). Legend: `! crit` = critical path, `est` = estimated allocation, `█` = confirmed span, `░` = upper-bound / uncertain span.
-
 ---
 
-## Phase 1: Critical Fixes
+## Task Details
+
+<!-- One `### <n>. <Title>` block per in-scope task, numbered from 1 in At a
+     Glance order — which is Priority-first, so that order carries priority.
+     There are no phase buckets and no separate priority table; stages carry
+     sequence.
+
+     The heading is the work's NAME, not its task-id. A task-id is a machine key
+     (`nestjs-migration-nlpvibe-to-nestjs-and-org-standard-structure`); printing
+     it as the reader's heading makes them decode a slug to learn what the work
+     is. The id stays in the At a Glance row, and the block binds to that row by
+     its number — which is also what the validator matches on. -->
 
-### 1-1. <TASK-ID> — <Title>
+### 1. <Title>
 
 | Item | Detail |
 |------|--------|
 | **Category** | <category> |
 | **Priority** | <P0~P3> |
-| **Effort** | **<S/M/L/XL>** (<scope summary>) |
-| **Status** | <taskType> / <currentPhase> |
+| **Effort** | **<S/M/L/XL/XXL>** (<scope summary>) |
+| **Status** | <작업이 지금 어느 단계인지, 사람 말로> |
 | **Risk** | <risk> |
 | **Scope** | <files / repos summary> |
 | **Repo** | <repos> |
@@ -119,56 +171,107 @@ Phase 3
 
 **Solution**: <…>
 
+<!-- Everything below this line is transcribed from the planning report the CLI
+     resolved — `okstra stage-map <task-key> --json` carries each stage's
+     `acceptance` / `exitContract` / `sliceValue` and the task-level
+     `rollbackStrategy` / `validationChecklist` / `dependencyMigrationRisk`
+     rows. Transcribe those rows; do not re-summarise the report body. -->
+
 **Work Breakdown**:
 
+<!-- `Depends On` spells the stage out: `None`, `Stage 2`, `Stage 1 (done)`.
+     A bare number makes the reader match a digit against the Stage column of
+     the same table. -->
+
 | Stage | Title | Steps | Depends On | Days |
 |---:|---|---:|---|---:|
-| 2 | Build adapter | 3 | 1 (done) | 2.0 ~ 3.0 |
-| 3 | Wire consumer | 2 | 2 | 1.0 ~ 2.0 |
+| 2 | Build adapter | 3 | Stage 1 (done) | 2.0 ~ 3.0 |
+| 3 | Wire consumer | 2 | Stage 2 | 1.0 ~ 2.0 |
 
-**Verification Commands**:
-```bash
-<commands>
-```
+<!-- One `#### Stage <n> — <title>` per SELECTED stage, in Work Breakdown order.
 
-**Rollback**: <…>
+     `Steps` comes from that stage's `stepwiseExecution`: what the step does
+     (keep a leading RED:/GREEN: marker), the files it touches, and what the
+     executor should see when it succeeds — the step's own `expected`, written
+     as an outcome they can check, not pasted.
 
----
+     `Exit criteria` is one line from `exitContract`: when the stage is done.
 
-## Phase 2: Enhancements
+     Do NOT render `sliceValue`. It argues why the plan sliced the work this
+     way, which is a reviewer's question; an implementer gets nothing from it.
+     Do NOT render `acceptance` next to `exitContract` — they restate each
+     other, `exitContract` being the wider of the two. -->
 
-_none_ <!-- or repeat per-task block -->
+#### Stage 2 — Build adapter
 
----
+**Steps**:
 
-## Phase 3: Architecture
+| Step | 작업 | 대상 | 기대 결과 |
+|---:|---|---|---|
+| 1 | RED: <무엇을 왜 하는지> | `<files>` | <성공했을 때 보이는 것> |
+| 2 | GREEN: <무엇을 왜 하는지> | `<files>` | <성공했을 때 보이는 것> |
 
-_none_ <!-- or repeat per-task block -->
+**Exit criteria**: <이 stage 가 끝났다고 판정하는 상태>
 
----
+**Verification Commands**:
+
+<!-- One row per `validationChecklist` entry whose stage is in scope, SORTED
+     `pre` → `mid` → `post`. Source order interleaves them, and a reader working
+     down the table then runs a precondition after the post checks it gates.
+     Introduce the three values in one line above the table — they are
+     controlled vocabulary like `P0`, and just as opaque undefined.
+     Do NOT carry the source row's `id`: a schedule reader has no access to the
+     report those codes index, and the self-contained rule rejects them. -->
+
+`Phase` 는 이 검사를 언제 돌리는지를 뜻한다 — **pre**: 첫 stage 착수 전, **mid**: 매 stage 진행 중 상시, **post**: 각 stage 종료 조건으로.
 
-## Execution Priority Matrix
+| Phase | Check | Command / Observation | Expected |
+|-------|-------|-----------------------|----------|
+| pre | <check> | `<commandOrObservation>` | <expectedOutcome> |
 
-| Priority | Task | Effort | Risk | Next Action |
-|----------|------|--------|------|-------------|
+**Rollback**:
+
+<!-- One row per `rollbackStrategy` entry, in source order. The source `id` is
+     dropped for the same reason as the verification table. -->
+
+| Stage | Action | Trigger Signal | Verification |
+|------:|--------|----------------|--------------|
+| 1 | <action> | <triggerSignal> | <verificationMethod> |
 
 ---
 
 ## Cross-Task Dependencies & Shared Concerns
 
+<!-- When the planning report carries `crossProjectDependencies`, render one row
+     per entry before any prose. Prose covers only what those rows do not. -->
+
+| Direction | Project | Required Work | Verification Signal |
+|-----------|---------|---------------|---------------------|
+| upstream-precondition | <project> | <requiredWork> | <verificationSignal> |
+
 <free-form prose — inter-task overlap, shared packages, release order>
 
 ---
 
 ## Risk Mitigation Strategy
 
-1. <…>
-2. <…>
+<!-- When the planning report carries `dependencyMigrationRisk`, render one row
+     per entry. Additional numbered prose items may follow for risks the report
+     does not carry. -->
+
+| Kind | Item | Impact | Mitigation |
+|------|------|--------|------------|
+| order | <item> | <impact> | <mitigation> |
 
 ---
 
 ## Recommended Immediate Actions
 
+<!-- The single place the schedule says what to do next. With several tasks in
+     scope, lead each task's first action with its `<TASK-ID>` and keep them in
+     At a Glance order — that ordering is already Priority-first, so a separate
+     priority table would restate the At a Glance row and this list at once. -->
+
 - <action>
 - <action>
 

package/runtime/validators/validate-run.py

@@ -1045,6 +1045,19 @@ _V2_AI_HANDOFF_HEADINGS = (
 )
 
 
+# `humanSummary` / `userNarrative` belong to the human HTML. The AI Markdown
+# renders field names as headings or bold labels
+# (scripts/okstra_ctl/report_markdown.py `humanise`), so this matches the two
+# forms the renderer can emit rather than the raw JSON key — a key name in
+# quotes no longer appears anywhere in the Markdown. Anchored to the start of a
+# line so the same words inside worker prose are not a violation.
+_V2_HUMAN_ONLY_RENDERED_RE = re.compile(
+    r"^(?:#{2,6}[ \t]+(?P<heading>Human Summary|User Narrative)[ \t]*$"
+    r"|[ \t]*-[ \t]+\*\*(?P<label>Human Summary|User Narrative)\*\*[ \t]*:)",
+    re.MULTILINE,
+)
+
+
 def _validate_v2_ai_handoff(content: str, failures: list[str]) -> None:
     positions: list[int] = []
     for heading in _V2_AI_HANDOFF_HEADINGS:
@@ -1063,12 +1076,12 @@ def _validate_v2_ai_handoff(content: str, failures: list[str]) -> None:
             "schema-v2 AI handoff markdown heading order does not match "
             "templates/reports/final-report-v2.template.md."
         )
-    for human_only_field in ('"humanSummary"', '"userNarrative"'):
-        if human_only_field in content:
-            failures.append(
-                "schema-v2 AI handoff markdown contains human-only field "
-                f"{human_only_field}; render it only in the task-specific HTML."
-            )
+    for match in _V2_HUMAN_ONLY_RENDERED_RE.finditer(content):
+        field = match.group("heading") or match.group("label")
+        failures.append(
+            "schema-v2 AI handoff markdown contains human-only field "
+            f"{field!r}; render it only in the task-specific HTML."
+        )
     if _READING_CONFIRMATION_HEADING_RE.search(content) is not None:
         failures.append(
             "final report contains a `## 0. Reading Confirmation` heading — "

package/runtime/validators/validate-schedule.py

@@ -36,21 +36,26 @@ from okstra_ctl.schedule_semantics import (  # noqa: E402
 REQUIRED_SECTIONS_IN_ORDER: list[str] = [
     "## At a Glance",
     "## Executive Summary",
-    "## Task Dependency Graph",
-    "## Phase 1: Critical Fixes",
-    "## Phase 2: Enhancements",
-    "## Phase 3: Architecture",
-    "## Execution Priority Matrix",
+    "## Task Details",
     "## Cross-Task Dependencies & Shared Concerns",
     "## Risk Mitigation Strategy",
     "## Recommended Immediate Actions",
 ]
 
+# Both are omitted when they carry nothing: a single-task schedule has no
+# cross-task edge to draw, and a section whose whole body says "look at the
+# other table" is noise the reader has to step over.
 OPTIONAL_GRAPHIC_SECTIONS_IN_ORDER: list[str] = [
+    "## Task Dependency Graph",
     "## Gantt Chart",
 ]
 
 REQUIRED_EXEC_SUMMARY_SUBSECTION = "### Effort Sizing Criteria"
+# `P0` and `High` are controlled vocabulary the tables draw from, and a reader who
+# never saw the source report cannot rank work by a code the document never
+# defines — an opaque code with a friendlier shape.
+REQUIRED_SCALE_SUBSECTION = "### Priority & Risk Scale"
+REQUIRED_SCALE_HEADERS = ("| Priority | 기준 |", "| Risk | 기준 |")
 
 REQUIRED_TASK_FIELDS = [
     "**Category**",
@@ -93,10 +98,21 @@ FORBIDDEN_FRENCH_BODY_RE = re.compile(
 ALLOWED_EFFORT = {"S", "M", "L", "XL", "XXL"}
 ALLOWED_PRIORITY = {"P0", "P1", "P2", "P3"}
 ALLOWED_RISK = {"Very Low", "Low", "Medium", "Med-High", "High"}
-ALLOWED_PHASE = {"1", "2", "3"}
 
 # Per-task block sub-section labels in REQUIRED order. Each label is matched
 # at the start of a line as `**Label**:` or as a `####` heading for the last.
+# A stage block states what the stage does and when it is finished. `Value` was
+# the plan arguing its own slicing at a reviewer; `Acceptance` restated
+# `Exit contract`. Both are refused by label so a regenerated schedule cannot
+# quietly bring them back.
+STAGE_BLOCK_RE = re.compile(r"^####\s+Stage\s+(\d+)\s+—", re.MULTILINE)
+STAGE_REQUIRED_LABELS = ("**Steps**:", "**Exit criteria**:")
+STAGE_FORBIDDEN_LABELS = (
+    ("**Value**:", "the plan's justification for its own slicing"),
+    ("**Acceptance**:", "a restatement of Exit criteria"),
+    ("**Exit contract**:", "renamed to `**Exit criteria**:`"),
+)
+
 PER_TASK_SUBSECTIONS_IN_ORDER = [
     "**Problem**:",
     "**Solution**:",
@@ -194,8 +210,8 @@ def _validate_format(path: Path) -> list[str]:
         violations.append("missing `> Source: okstra <mode> …` metadata line")
 
     # 3. Required sections present and in order. The optional `## Gantt Chart`
-    #    section, if present, MUST sit between Task Dependency Graph and
-    #    Phase 1: Critical Fixes.
+    #    sections, if present, MUST sit between Executive Summary and
+    #    Task Details.
     section_positions: dict[str, int] = {}
     optional_positions: dict[str, int] = {}
     for idx, line in enumerate(visible_lines):
@@ -230,15 +246,31 @@ def _validate_format(path: Path) -> list[str]:
                 + "\n  ".join(ordered_actual)
             )
 
-        # Optional sections must sit between Task Dependency Graph and Phase 1
-        dep_idx = section_positions["## Task Dependency Graph"]
-        phase1_idx = section_positions["## Phase 1: Critical Fixes"]
+        # Optional sections sit between Executive Summary and Task Details
+        summary_idx = section_positions["## Executive Summary"]
+        details_idx = section_positions["## Task Details"]
         for opt_name, opt_idx in optional_positions.items():
-            if not (dep_idx < opt_idx < phase1_idx):
+            if not (summary_idx < opt_idx < details_idx):
                 violations.append(
                     f"optional section {opt_name!r} is misplaced — must appear between "
-                    "'## Task Dependency Graph' and '## Phase 1: Critical Fixes'"
+                    "'## Executive Summary' and '## Task Details'"
+                )
+    # 3b. Priority / Risk scale definitions
+    if sum(
+        line.rstrip() == REQUIRED_SCALE_SUBSECTION for line in visible_lines
+    ) != 1:
+        violations.append(
+            f"missing subsection {REQUIRED_SCALE_SUBSECTION!r} — `P0` and "
+            "`High` are undefined codes without it"
+        )
+    else:
+        for header in REQUIRED_SCALE_HEADERS:
+            if header not in text:
+                violations.append(
+                    f"{REQUIRED_SCALE_SUBSECTION} requires the header literal "
+                    f"{header!r}"
                 )
+
     # 4. Executive Summary subsection
     effort_heading_count = sum(
         line.rstrip() == REQUIRED_EXEC_SUMMARY_SUBSECTION
@@ -271,7 +303,7 @@ def _validate_format(path: Path) -> list[str]:
 
     # 7. Per-task field labels — every per-task heading (### N-i.) MUST be followed
     #    (within the next 60 lines) by all required field labels.
-    task_heading_re = re.compile(r"^###\s+\d+-\d+\.\s+", re.MULTILINE)
+    task_heading_re = re.compile(r"^###\s+\d+\.\s+", re.MULTILINE)
     for m in task_heading_re.finditer(text):
         start = m.start()
         # find the next ### or ## heading
@@ -285,41 +317,14 @@ def _validate_format(path: Path) -> list[str]:
                 )
 
     # 8. Item table header literal
-    if "| Item | Detail |" not in text and any(
-        h.startswith("## Phase") for h in section_positions
-    ):
-        # only flag if there is at least one phase with a per-task block
-        if task_heading_re.search(text):
-            violations.append(
-                "per-task tables must use header `| Item | Detail |` (literal English)"
-            )
-
-    # 9. Checklist tables MUST carry a leading `Done` column with markdown
-    #    checkboxes. The check is a header-presence test — we require the
-    #    canonical header literal to appear in the section's text block.
-    checklist_header_specs = [
-        (
-            "## Execution Priority Matrix",
-            ["| Priority | Task | Effort | Risk | Next Action |"],
-            "Execution Priority Matrix table must use header "
-            "`| Priority | Task | Effort | Risk | Next Action |` "
-            "(client-facing schedule — no Done/Ready/Blocking columns)",
-        ),
-    ]
-    for section_name, expected_substrings, message in checklist_header_specs:
-        if section_name not in section_positions:
-            continue
-        start = section_positions[section_name]
-        # slice from this heading to the next `## ` (string offsets, not line idx)
-        rest = "\n".join(lines[start + 1:])
-        next_h = re.search(r"^##\s", rest, re.MULTILINE)
-        section_text = rest[: next_h.start()] if next_h else rest
-        if not any(sub in section_text for sub in expected_substrings):
-            violations.append(message)
+    if "| Item | Detail |" not in text and task_heading_re.search(text):
+        violations.append(
+            "per-task tables must use header `| Item | Detail |` (literal English)"
+        )
 
-    # Forbid client-leaking artifacts: Consolidated User Decision Checklist /
-    # per-task 사용자 확인 필요 항목 — schedule is for client delivery, blocking
-    # / approval items must NOT surface.
+    # 9. Forbid client-leaking artifacts: Consolidated User Decision Checklist /
+    #    per-task 사용자 확인 필요 항목 — schedule is for client delivery, blocking
+    #    / approval items must NOT surface.
     if "## Consolidated User Decision Checklist" in text:
         violations.append(
             "`## Consolidated User Decision Checklist` is forbidden — schedule "
@@ -333,6 +338,28 @@ def _validate_format(path: Path) -> list[str]:
             "report instead"
         )
 
+    # 9b. Stage blocks: Steps + Exit criteria, and neither reviewer-facing label.
+    stage_headings = list(STAGE_BLOCK_RE.finditer(text))
+    for index, heading in enumerate(stage_headings):
+        end = (
+            stage_headings[index + 1].start()
+            if index + 1 < len(stage_headings)
+            else len(text)
+        )
+        block = text[heading.start():end]
+        stage_no = heading.group(1)
+        for label in STAGE_REQUIRED_LABELS:
+            if label not in block:
+                violations.append(
+                    f"Stage {stage_no} block is missing {label!r}"
+                )
+        for label, why in STAGE_FORBIDDEN_LABELS:
+            if label in block:
+                violations.append(
+                    f"Stage {stage_no} block carries forbidden {label!r} — "
+                    f"{why}; a stage block is Steps plus Exit criteria"
+                )
+
     # 10. Days total format inside At a Glance: `**N tasks total / estimated effort: X.X ~ Y.Y days (Effort sum)**`
     if "## At a Glance" in section_positions:
         start = section_positions["## At a Glance"]
@@ -350,15 +377,14 @@ def _validate_format(path: Path) -> list[str]:
             r"^\|\s*\d+\s*\|.*$", body, re.MULTILINE
         ):
             cells = split_pipe_row(row.group(0))
-            # header: # | Task ID | Title | Category | Priority | Effort | Days | taskType | Risk | Phase
-            if len(cells) < 10:
+            # header: # | Task ID | Title | Category | Priority | Effort | Days | Risk
+            if len(cells) < 8:
                 continue
             priority = re.sub(r"\*+", "", cells[4]).strip()
             effort = re.sub(r"\*+", "", cells[5]).strip()
             # `Effort` cell may contain extra hint like `L (5-15 files)`; pick the leading token
             effort_token = effort.split()[0] if effort else ""
-            risk = re.sub(r"\*+", "", cells[8]).strip()
-            phase = re.sub(r"\*+", "", cells[9]).strip()
+            risk = re.sub(r"\*+", "", cells[7]).strip()
             task_id = cells[1]
             if priority and priority not in ALLOWED_PRIORITY:
                 violations.append(
@@ -375,11 +401,6 @@ def _validate_format(path: Path) -> list[str]:
                     f"At a Glance row for {task_id!r}: Risk {risk!r} "
                     f"not in allowed set {sorted(ALLOWED_RISK)}"
                 )
-            if phase and phase not in ALLOWED_PHASE:
-                violations.append(
-                    f"At a Glance row for {task_id!r}: Phase {phase!r} "
-                    f"not in allowed set {sorted(ALLOWED_PHASE)}"
-                )
 
     # 12. Gantt Chart content checks — forbid DSL fences, force relative-day axis
     if "## Gantt Chart" in optional_positions:
@@ -413,9 +434,9 @@ def _validate_format(path: Path) -> list[str]:
                 "(`Day 1`, `J1`, …)"
             )
 
-    # 12b. Task Dependency Graph content check.
-    if "## Task Dependency Graph" in section_positions:
-        start = section_positions["## Task Dependency Graph"]
+    # 12b. Task Dependency Graph content check (the section is optional).
+    if "## Task Dependency Graph" in optional_positions:
+        start = optional_positions["## Task Dependency Graph"]
         rest = "\n".join(lines[start + 1:])
         next_h = re.search(r"^##\s", rest, re.MULTILINE)
         body = (rest[: next_h.start()] if next_h else rest).strip()
@@ -442,9 +463,15 @@ def _validate_format(path: Path) -> list[str]:
                         f"`## Task Dependency Graph` contains forbidden DSL fence "
                         f"{forbidden!r} — only ASCII adjacency lines are allowed"
                     )
+            # A node is a TASK-ID. Stage order is deliberately NOT drawn here —
+            # the Work Breakdown's `Depends On` column already carries it, and
+            # a second arrow-list rendering makes the reader cross-reference one
+            # table against another to learn nothing new. A stage node would
+            # also reintroduce the `S<n>` abbreviation the schedule spells out
+            # everywhere else.
+            node = r"[A-Za-z][A-Za-z0-9_-]*"
             adjacency_re = re.compile(
-                r"^[A-Za-z][A-Za-z0-9_-]*\s*->\s*"
-                r"[A-Za-z][A-Za-z0-9_-]*(?:\s*,\s*[A-Za-z][A-Za-z0-9_-]*)*\s*$"
+                rf"^{node}\s*->\s*{node}(?:\s*,\s*{node})*\s*$"
             )
             for line_no, raw in enumerate(inner.splitlines(), start=1):
                 ln = raw.rstrip()
@@ -461,8 +488,10 @@ def _validate_format(path: Path) -> list[str]:
                 if not adjacency_re.match(ln.strip()):
                     violations.append(
                         f"`## Task Dependency Graph` line {line_no} is not a valid "
-                        "adjacency line: expected `<TASK-ID> -> <TASK-ID>[, <TASK-ID>]*`; "
-                        f"got {ln.strip()!r}"
+                        "adjacency line: expected `<TASK-ID> -> <TASK-ID>[, <TASK-ID>]*` "
+                        "— this graph carries cross-task edges only, and stage "
+                        "order belongs to the Work Breakdown's `Depends On` "
+                        f"column; got {ln.strip()!r}"
                     )
         elif no_data_marker not in body:
             violations.append(
@@ -472,7 +501,7 @@ def _validate_format(path: Path) -> list[str]:
             )
 
     # 13. Per-task block sub-section order check
-    task_heading_re = re.compile(r"^###\s+\d+-\d+\.\s+", re.MULTILINE)
+    task_heading_re = re.compile(r"^###\s+\d+\.\s+", re.MULTILINE)
     headings = list(task_heading_re.finditer(text))
     for idx, m in enumerate(headings):
         block_start = m.start()

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

@@ -7,7 +7,12 @@ Usage:
   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, state, sourcePlanPath, stages:[{stage_number,title,depends_on,step_count}], doneStages:[int] }.
+Output: JSON { ok, taskKey, taskRoot, state, sourcePlanPath, stages:[…], doneStages:[int], planning:{…} }.
+Each stage row carries stage_number, title, depends_on, step_count and exit_contract_summary; a
+schema-v2 report adds that stage's sliceValue, acceptance and exitContract.
+planning carries the report's task-level rows — rollbackStrategy, validationChecklist,
+crossProjectDependencies, dependencyMigrationRisk, recommendedOption — so a consumer renders the
+plan instead of re-summarising the report body. Both are absent for a schema-v1 report.
 stages is [] when no implementation-planning Stage Map exists.
 `;