okstra 0.38.1 → 0.40.0

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

@@ -293,7 +293,11 @@
           "items": { "type": "string" },
           "minItems": 1
         },
-        "nextStep": { "type": "string", "minLength": 1 }
+        "nextStep": { "type": "string", "minLength": 1 },
+        "conditionalAcceptanceConditions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ConditionalAcceptanceConditionRow" }
+        }
       }
     },
 
@@ -544,14 +548,17 @@
       "properties": {
         "sourceImplementationReport": {
           "type": "object",
-          "required": ["path", "commitListQuote", "worktreePath", "baseHeadSha", "gitStatusShort"],
+          "required": ["path", "commitListQuote", "diffSummaryQuote", "worktreePath", "implementationBaseRef", "capturedHeadSha", "gitStatusShort", "gitDiffStat"],
           "additionalProperties": false,
           "properties": {
             "path": { "type": "string" },
             "commitListQuote": { "type": "string" },
+            "diffSummaryQuote": { "type": "string" },
             "worktreePath": { "type": "string" },
-            "baseHeadSha": { "type": "string" },
-            "gitStatusShort": { "type": "string" }
+            "implementationBaseRef": { "type": "string" },
+            "capturedHeadSha": { "type": "string" },
+            "gitStatusShort": { "type": "string" },
+            "gitDiffStat": { "type": "string" }
           }
         },
         "acceptanceBlockers": {
@@ -1092,7 +1099,7 @@
 
     "PlanBodyVerification": {
       "type": "object",
-      "required": ["roundCount", "gateResult", "verdictSummary", "verdictDetails", "dissentLog"],
+      "required": ["roundCount", "gateResult", "verdictDetails", "dissentLog"],
       "additionalProperties": false,
       "properties": {
         "roundCount": { "type": "integer", "minimum": 0 },
@@ -1104,26 +1111,6 @@
             "aborted-non-result"
           ]
         },
-        "verdictSummary": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "required": ["planItem", "ticketId", "section", "classification"],
-            "additionalProperties": false,
-            "properties": {
-              "planItem": {
-                "type": "string",
-                "pattern": "^P-(Opt|Step|Dep|Val|Rb)-\\d+$"
-              },
-              "ticketId": { "$ref": "#/$defs/TicketId" },
-              "section": { "type": "string", "minLength": 1 },
-              "classification": {
-                "type": "string",
-                "pattern": "^(full-consensus|partial-consensus|worker-unique|majority-disagree → C-\\d+)$"
-              }
-            }
-          }
-        },
         "verdictDetails": {
           "type": "array",
           "items": {
@@ -1305,14 +1292,34 @@
 
     "ReadonlyCommandRow": {
       "type": "object",
-      "required": ["number", "tier", "command", "exitCode", "outputTail"],
+      "required": ["number", "tier", "command", "status", "exitCode", "outputTail"],
       "additionalProperties": false,
       "properties": {
         "number": { "type": "integer", "minimum": 1 },
         "tier": { "enum": [1, 2] },
         "command": { "type": "string", "minLength": 1 },
-        "exitCode": { "type": "integer" },
+        "status": { "enum": ["executed", "rejected", "not-configured"] },
+        "exitCode": { "type": ["integer", "null"] },
+        "rejectionReason": { "type": ["string", "null"] },
         "outputTail": { "type": "string" }
+      },
+      "allOf": [
+        { "if": { "properties": { "status": { "const": "executed" } } },
+          "then": { "properties": { "exitCode": { "type": "integer" } } } },
+        { "if": { "properties": { "status": { "const": "rejected" } } },
+          "then": { "required": ["rejectionReason"] } }
+      ]
+    },
+
+    "ConditionalAcceptanceConditionRow": {
+      "type": "object",
+      "required": ["id", "condition", "evidenceRequired", "blocksReleaseHandoff"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^CA-\\d{3,}$" },
+        "condition": { "type": "string", "minLength": 1 },
+        "evidenceRequired": { "type": "string", "minLength": 1 },
+        "blocksReleaseHandoff": { "type": "boolean" }
       }
     },
 

package/runtime/skills/okstra-context-loader/SKILL.md

@@ -44,7 +44,7 @@ user-invocable: false
 | `taskGroup` | Task group |
 | `taskId` | Task ID |
 | `taskType` | Analysis type (requirements-discovery, error-analysis, implementation-planning, implementation, final-verification, release-handoff) |
-| `workCategory` | bugfix / feature / improvement / refactor / ops-change / unknown |
+| `workCategory` | bugfix / feature / improvement / refactor / ops / unknown |
 | `recommendedWorkers` | List of selected workers |
 | `currentStatus` | Current task status |
 | `workflow.phaseSequence` | Ordered lifecycle phases for the task |

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

@@ -507,7 +507,7 @@ Plan-body verification only supports **lightweight mode** (defined in §"Verific
    - all dispatches non-result → `aborted-non-result`
    - any `partial-consensus` / `dissent-isolated` present, no `majority-disagree` → `passed-with-dissent`
    - all items `full-consensus` → `passed`
-6. Lead writes `runs/<task-type>/state/plan-body-verification-<task-type>-<seq>.json` (schema below) and populates `### 4.5.9 Plan Body Verification` in the final report (template at `templates/reports/final-report.template.md`). The §4.5.9 body in the template is split into two tables: a narrow `#### Verdict summary` (`Plan item / Ticket ID / Section / Classification` only — one row per plan item) and a tall `#### Verdict details` (`Plan item / Worker / Verdict / Breakage kind / Note` — one row per plan-item × worker pair). The older wide `| Plan item | <worker1> | <worker2> | … | Classification |` matrix is removed — it scaled horizontally with the worker count and lost readability past 3 workers. Lead MUST emit both tables (the validator's `Plan Body Verification` + `Gate result:` substring checks still pass either layout, but reviewers depend on the split form).
+6. Lead writes `runs/<task-type>/state/plan-body-verification-<task-type>-<seq>.json` (schema below) and populates `### 4.5.9 Plan Body Verification` in the final report (template at `templates/reports/final-report.template.md`). The §4.5.9 body uses a single `#### Verdict details` table (`Plan item / Worker / Verdict / Breakage kind / Note` — one row per plan-item × worker pair). The older wide `| Plan item | <worker1> | <worker2> | … | Classification |` matrix and the former narrow `#### Verdict summary` card are both removed — the matrix scaled horizontally with the worker count, and the summary only restated per-item classifications already derivable from the details table. The validator's `Plan Body Verification` + `Gate result:` substring checks gate this section.
 7. For every `majority-disagree` item, lead adds a row to `## 5. Clarification Items` with:
    - new `C-<N>` ID (numbering continues from any existing rows)
    - `Statement` summarising the disagreement and the worker breakage `<kind>`

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

@@ -51,7 +51,7 @@ Read `.okstra/discovery/task-catalog.json`. The catalog is the authoritative sou
 |------|------|
 | `taskKey` | `<project-id>:<task-group>:<task-id>` |
 | `taskType` | latest task type |
-| `workCategory` | bugfix / feature / improvement / refactor / ops-change / unknown. Display `unknown` as-is, but flag with `(unset)` annotation so the reader knows the requirements-discovery classification was skipped or no `--work-category` flag was passed. |
+| `workCategory` | bugfix / feature / improvement / refactor / ops / unknown. Display `unknown` as-is, but flag with `(unset)` annotation so the reader knows the requirements-discovery classification was skipped or no `--work-category` flag was passed. |
 | `currentStatus` | task-level status |
 | `currentPhase` | lifecycle current phase |
 | `currentPhaseState` | lifecycle phase state |

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

@@ -45,6 +45,8 @@ The wizard tells you *which UI to use* via `kind` (and the optional `multi` flag
 - `kind: "text"` → write `label` as a plain text message and consume the user's NEXT message as the answer.
 - `kind: "done"` → input collection finished; move to Step 5.
 
+The `branch_confirm` step (shown just before `confirm`) is a normal `pick` step and is rendered the same way — no special handling needed.
+
 Never invent additional questions. Never reorder. Never use `AskUserQuestion` for `text` prompts — the wizard explicitly chose `text` to avoid the picker-Other re-render lag.
 
 ## Step 1: Verify okstra runtime + project setup

package/runtime/templates/prd/brief.template.md

@@ -138,7 +138,7 @@ Codex/Gemini는 이 코드베이스를 모릅니다. 핵심 용어 5-15개를
   <증거 또는 "weak signal — none observed">
 - **Why might this be a feature/improvement?**
   <증거>
-- **Why might this be a refactor/ops-change?**
+- **Why might this be a refactor/ops?**
   <증거>
 - **Classification blockers** — 무엇이 분류 확신을 막고 있는가?
   <evidence gap을 구체적으로>

package/runtime/templates/reports/fan-out-unit.template.md

@@ -0,0 +1,25 @@
+<!-- templates/reports/fan-out-unit.template.md -->
+---
+unit-id: {{UNIT_ID}}
+domain: {{DOMAIN}}
+<!-- depends-on 예: [unit-001] (의존 없으면 []) -->
+depends-on: {{DEPENDS_ON}}
+recommended-next-phase: {{NEXT_PHASE}}
+---
+
+# Fan-out Unit: {{UNIT_ID}} ({{DOMAIN}})
+
+> requirements-discovery fan-out 산출 packet. `okstra-run --task-brief <이 파일 경로>`
+> 로 새 task-key 를 시작한다. 이 파일은 그 run 의 입력 packet 이다.
+
+## Scope
+
+<!-- 이 단위가 다루는 작업 항목 1개를 자족적으로 서술. 다른 단위와 섞지 말 것. -->
+
+## Evidence
+
+<!-- path:line 근거. requirements-discovery 가 file inspection 으로 확인한 위치. -->
+
+## Depends-on rationale
+
+<!-- depends-on 에 적은 각 unit 에 왜 의존하는지 1줄씩. 없으면 _(none)_ -->

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

@@ -286,14 +286,6 @@ approved: {{ frontmatter.approved | yaml_scalar }}
 - **Round count**: `{{ implementationPlanning.planBodyVerification.roundCount }}`
 - **Gate result**: `{{ implementationPlanning.planBodyVerification.gateResult }}`
 
-#### Verdict summary
-
-| Plan item | Ticket ID | Section | Classification |
-|-----------|-----------|---------|----------------|
-{% for row in implementationPlanning.planBodyVerification.verdictSummary -%}
-| {{ row.planItem }} | `{{ row.ticketId }}` | {{ row.section }} | {{ row.classification }} |
-{% endfor %}
-
 #### Verdict details
 
 | Plan item | Worker | Verdict | Breakage kind | Note |
@@ -479,12 +471,19 @@ approved: {{ frontmatter.approved | yaml_scalar }}
 - Path (project-relative): `{{ finalVerification.sourceImplementationReport.path }}`
 - {{ t("evidenceMeta.commitListSummary") }}:
   > {{ finalVerification.sourceImplementationReport.commitListQuote }}
+- {{ t("evidenceMeta.diffSummaryQuote") }}:
+  > {{ finalVerification.sourceImplementationReport.diffSummaryQuote }}
 - {{ t("evidenceMeta.targetWorktreePath") }}: `{{ finalVerification.sourceImplementationReport.worktreePath }}`
-- {{ t("evidenceMeta.capturedHeadBaseSha") }}: `{{ finalVerification.sourceImplementationReport.baseHeadSha }}`
+- {{ t("evidenceMeta.implementationBaseRef") }}: `{{ finalVerification.sourceImplementationReport.implementationBaseRef }}`
+- {{ t("evidenceMeta.capturedHeadSha") }}: `{{ finalVerification.sourceImplementationReport.capturedHeadSha }}`
 - {{ t("evidenceMeta.gitStatusAtRunStart") }}:
   ```
   {{ finalVerification.sourceImplementationReport.gitStatusShort }}
   ```
+- {{ t("evidenceMeta.gitDiffStatAtRunStart") }}:
+  ```
+  {{ finalVerification.sourceImplementationReport.gitDiffStat }}
+  ```
 
 ### 4.8.2 Acceptance Blockers
 
@@ -520,13 +519,25 @@ approved: {{ frontmatter.approved | yaml_scalar }}
 
 ### 4.8.5 Read-only Command Log
 
-| # | Tier | Command (verbatim) | Exit code | Output tail |
-|---|------|---------------------|-----------|-------------|
+| # | Tier | Command (verbatim) | Status | Exit code | Output tail |
+|---|------|---------------------|--------|-----------|-------------|
 {% for row in finalVerification.readonlyCommandLog -%}
-| {{ row.number }} | {{ row.tier }} | `{{ row.command }}` | `{{ row.exitCode }}` | {{ row.outputTail }} |
+| {{ row.number }} | {{ row.tier }} | `{{ row.command }}` | `{{ row.status }}` | {{ row.exitCode if row.exitCode is not none else '—' }} | {{ row.rejectionReason if row.status == 'rejected' else row.outputTail }} |
 {% endfor %}
 
-### 4.8.6 Routing Recommendation
+### 4.8.6 Conditional Acceptance Conditions
+
+{% if not finalVerdict.conditionalAcceptanceConditions -%}
+- Not applicable (verdict is not `conditional-accept`).
+{%- else %}
+| ID | Condition | Evidence required | Blocks release-handoff |
+|----|-----------|-------------------|------------------------|
+{% for row in finalVerdict.conditionalAcceptanceConditions -%}
+| {{ row.id }} | {{ row.condition }} | {{ row.evidenceRequired }} | {{ row.blocksReleaseHandoff }} |
+{% endfor %}
+{%- endif %}
+
+### 4.8.7 Routing Recommendation
 
 {{ finalVerification.routingRecommendation }}
 

package/runtime/templates/reports/final-verification-input.template.md

@@ -39,6 +39,15 @@ taskType: "{{FM_TASK_TYPE}}"
 
 > If this section is empty, points to a missing report, or names a checkout that does not match the implementation report's commit list / diff summary, final-verification MUST end with status `blocked` and route back to `implementation` or `implementation-planning`. Do not verify an ambiguous target.
 
+## Requirement Coverage Source
+
+- Approved implementation-planning report path:
+- Requirement source used for coverage (plan section / brief Acceptance Criteria):
+- Requirement IDs / acceptance IDs to verify:
+- Requirements intentionally excluded from this verification:
+
+> final-verification 은 위 source 의 각 requirement / acceptance id 마다 Validation Evidence 에 artifact 를 cite 해야 한다. source 가 비면 brief 의 `## Acceptance Criteria` 를 기본 source 로 사용한다.
+
 ## Verification Evidence
 
 - PR or change summary:
@@ -78,11 +87,13 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Questions for Analysers
 
-1. Are there any acceptance blockers?
-2. What residual risks remain?
-3. Is additional validation needed before release?
-4. Which acceptance checks did you consider and **deliberately exclude** from this verification, and why must each be a separate verification task instead of being folded in here?
-5. Did any check go beyond `Acceptance Criteria` (e.g., quality improvements, unrelated regressions)? If yes, separate them from the pass/fail decision and report as follow-up only.
+1. Does the verification target (head SHA / diff stat) match the implementation report's commit list and diff summary?
+2. For each requirement / acceptance criterion, what exact artifact (commit SHA, test output, log line, config value) proves coverage?
+3. Are there any acceptance blockers?
+4. What residual risks remain?
+5. Is additional validation needed before release?
+6. Which acceptance checks did you consider and **deliberately exclude** from this verification, and why must each be a separate verification task instead of being folded in here?
+7. Did any check go beyond `Acceptance Criteria` (e.g., quality improvements, unrelated regressions)? If yes, separate them from the pass/fail decision and report as follow-up only.
 
 ## Conversion Note
 

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

@@ -117,10 +117,13 @@
     "runBaseRef": "This run's base ref"
   },
   "evidenceMeta": {
-    "commitListSummary": "Cited commit list / diff summary",
+    "commitListSummary": "Cited commit list",
+    "diffSummaryQuote": "Cited diff summary (from implementation report)",
     "targetWorktreePath": "Target worktree path for verification",
-    "capturedHeadBaseSha": "head/base SHA captured at run start",
-    "gitStatusAtRunStart": "`git status --short` (at run start)"
+    "implementationBaseRef": "Implementation base ref",
+    "capturedHeadSha": "Head SHA captured at run start",
+    "gitStatusAtRunStart": "`git status --short` (at run start)",
+    "gitDiffStatAtRunStart": "`git diff --stat <base>..HEAD` (at run start)"
   },
   "clarification": {
     "fillAndRerun": "Fill in your answers then re-run the same phase:",

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

@@ -117,10 +117,13 @@
     "runBaseRef": "본 run 의 base ref"
   },
   "evidenceMeta": {
-    "commitListSummary": "인용된 commit list / diff summary 요약",
+    "commitListSummary": "인용된 commit list",
+    "diffSummaryQuote": "인용된 diff summary (implementation 보고서)",
     "targetWorktreePath": "검증 대상 worktree path",
-    "capturedHeadBaseSha": "run 시작 시 capture 한 head/base SHA",
-    "gitStatusAtRunStart": "`git status --short` (run 시작 시점)"
+    "implementationBaseRef": "Implementation base ref",
+    "capturedHeadSha": "run 시작 시 capture 한 head SHA",
+    "gitStatusAtRunStart": "`git status --short` (run 시작 시점)",
+    "gitDiffStatAtRunStart": "`git diff --stat <base>..HEAD` (run 시작 시점)"
   },
   "clarification": {
     "fillAndRerun": "답을 채우신 뒤 같은 phase 를 다시 실행:",

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

@@ -86,6 +86,13 @@ For the **implementation phase** specifically, the dispatched prompt MUST also i
 - `**Worktree:** <absolute-path>` — the task worktree path.
 - `cwd for every mutating command: <absolute-path>` — same as Worktree path; used by codex / gemini wrappers as `--add-dir` / `--include-directories`.
 
+For the **final-verification phase** specifically, the dispatched prompt MUST also include the verification target snapshot so every analyser verifies the SAME target the lead captured at the entry gate:
+
+- `**Worktree:** <absolute-path>` — the checkout under verification (read-only).
+- `**Verification base ref:** <base-ref>` — the implementation base for the diff.
+- `**Verification head SHA:** <sha>` — head SHA captured at run start.
+- `**Verification diff stat:** <git diff --stat output>` — the captured diff-stat that bounds the verification scope.
+
 When a worker reads any project-relative path from the prompt, it MUST resolve it against `Project Root` (e.g. `<Project Root>/<Result Path>`) — never use bare relative paths that depend on cwd.
 
 ---

package/runtime/validators/lib/fixtures.sh

@@ -359,8 +359,8 @@ report_lines.extend(
         "## 4.8 Final Verification Deliverables",
         "",
         "Source Implementation Report / Acceptance Blockers / Residual Risk / "
-        "Validation Evidence / Read-only Command Log / Routing Recommendation: "
-        "fixture stub.",
+        "Validation Evidence / Read-only Command Log / Conditional Acceptance "
+        "Conditions / Routing Recommendation: fixture stub.",
     ]
 )
 report_path.parent.mkdir(parents=True, exist_ok=True)

package/runtime/validators/lib/validate-assets.sh

@@ -40,12 +40,21 @@ def check(source_path: Path, target_path: Path) -> None:
 
 
 # 1. Worker agent files: agents/workers/*-worker.md -> runtime/agents/workers/*-worker.md
+#
+# `_cli-wrapper-template.md` is a build-time render INPUT, not a shipped
+# artifact — tools/build.mjs renders it (with each *.params.json) into
+# codex-worker.md / gemini-worker.md and excludes the template itself from the
+# runtime payload. Skip it here so parity is checked only on shipped files.
+# Keep this set in sync with TEMPLATE_INPUT_BASENAMES in tools/build.mjs.
+template_input_basenames = {"_cli-wrapper-template.md"}
 workers_source = agents_source_root / "workers"
 workers_target = runtime_root / "agents" / "workers"
 if not workers_source.is_dir():
     errors.append(f"missing agents/workers source directory: {workers_source}")
 else:
     for source_path in sorted(workers_source.glob("*.md")):
+        if source_path.name in template_input_basenames:
+            continue
         check(source_path, workers_target / source_path.name)
 
 # 2. Lead agent SKILL.md: agents/SKILL.md -> runtime/agents/SKILL.md

package/runtime/validators/validate-implementation-plan-stages.py

@@ -181,25 +181,33 @@ def _check_depends_on(stages: List[StageMeta]) -> List[ValidationError]:
     return errs
 
 
-def main(argv: List[str]) -> int:
-    p = argparse.ArgumentParser()
-    p.add_argument("--plan", required=True)
-    args = p.parse_args(argv)
-    text = Path(args.plan).read_text(encoding="utf-8")
+def collect_validation_errors(text: str) -> List[ValidationError]:
+    """All S1–S8 checks against the report text; empty list means valid.
 
-    errors: List[ValidationError] = []
-    errors.extend(_check_stage_map_present(text))
-    if errors:
-        for e in errors:
-            print(f"{e.code} stage={e.stage}: {e.message}", file=sys.stderr)
-        return 1
+    S1 (missing `## 4.5 Stage Map` heading) makes the rest unparseable, so it
+    short-circuits. Shared by `main()` (CLI / implementation entry) and the
+    implementation-planning boundary check in validate-run.py — one validator,
+    one reference point, enforced at both produce-time and consume-time."""
+    present = _check_stage_map_present(text)
+    if present:
+        return present
 
+    errors: List[ValidationError] = []
     stages, s2_errs = _parse_stage_map(text)
     errors.extend(s2_errs)
     if stages:
         errors.extend(_check_each_stage_section(text, stages))
         errors.extend(_check_depends_on(stages))
+    return errors
+
+
+def main(argv: List[str]) -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--plan", required=True)
+    args = p.parse_args(argv)
+    text = Path(args.plan).read_text(encoding="utf-8")
 
+    errors = collect_validation_errors(text)
     if errors:
         for e in errors:
             print(f"{e.code} stage={e.stage}: {e.message}", file=sys.stderr)

package/runtime/validators/validate-run.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import argparse
+import importlib.util
 import json
 import os
 import re
@@ -878,6 +879,7 @@ FINAL_VERIFICATION_REQUIRED_SECTIONS = (
     "Residual Risk",
     "Validation Evidence",
     "Read-only Command Log",
+    "Conditional Acceptance Conditions",
     "Routing Recommendation",
 )
 
@@ -1057,6 +1059,48 @@ def validate_final_report_data(report_path: Path, failures: list[str]) -> None:
     for err in errors:
         failures.append(f"final-report data.json: {err}")
 
+    if (data.get("header") or {}).get("taskType") == "final-verification":
+        _validate_final_verification_consistency(data, failures)
+
+
+def _validate_final_verification_consistency(data: dict, failures: list[str]) -> None:
+    """Enforce verdict ↔ blocker/condition/routing consistency on the
+    final-verification data.json (SSOT). The schema guarantees field SHAPE;
+    these are the cross-field invariants the release-handoff gate depends on.
+
+    No-op for non-final-verification data so the caller's gate stays defensive.
+    """
+    if (data.get("header") or {}).get("taskType") != "final-verification":
+        return
+    verdict = data.get("finalVerdict") or {}
+    token = (verdict.get("verdictToken") or "").strip().lower()
+    fv = data.get("finalVerification") or {}
+    blockers = fv.get("acceptanceBlockers") or []
+    conditions = verdict.get("conditionalAcceptanceConditions") or []
+    routing = fv.get("routingRecommendation") or ""
+
+    if token == "accepted" and blockers:
+        failures.append(
+            "final-verification: verdict `accepted` but acceptanceBlockers is "
+            "non-empty — an accepted verdict must have zero blockers."
+        )
+    if token == "blocked" and not blockers:
+        failures.append(
+            "final-verification: verdict `blocked` but acceptanceBlockers is "
+            "empty — a blocked verdict must list at least one blocker."
+        )
+    if token == "conditional-accept" and not conditions:
+        failures.append(
+            "final-verification: verdict `conditional-accept` but "
+            "conditionalAcceptanceConditions is empty — list every condition."
+        )
+    if "release-handoff" in routing and token != "accepted":
+        failures.append(
+            f"final-verification: routingRecommendation cites `release-handoff` "
+            f"but verdict is `{token}` — release-handoff routing is allowed only "
+            "when the verdict is `accepted`."
+        )
+
 
 def validate_report_views(report_path: Path, failures: list[str]) -> None:
     """Enforce Phase 7 step 1.5 (BLOCKING) — the self-contained HTML
@@ -1095,6 +1139,44 @@ def validate_report_views(report_path: Path, failures: list[str]) -> None:
                 failures.append(f"report-views: {line}")
 
 
+_STAGE_VALIDATOR_PATH = _VALIDATORS_DIR / "validate-implementation-plan-stages.py"
+
+
+def _load_stage_validator():
+    spec = importlib.util.spec_from_file_location(
+        "_ip_stage_validator", _STAGE_VALIDATOR_PATH
+    )
+    if spec is None or spec.loader is None:
+        return None
+    mod = importlib.util.module_from_spec(spec)
+    # Register before exec so the dataclass field-type resolution can find the
+    # module in sys.modules (mirrors run.py._parse_stage_map_into_ctx).
+    sys.modules["_ip_stage_validator"] = mod
+    try:
+        spec.loader.exec_module(mod)
+    finally:
+        sys.modules.pop("_ip_stage_validator", None)
+    return mod
+
+
+def _append_stage_structure_failures(content: str, failures: list[str]) -> None:
+    """Enforce the Stage Map structural contract at the implementation-planning
+    boundary. Without this, a plan missing `## 4.5 Stage Map` passes the
+    planning gate, gets approved, and only fails later at the `implementation`
+    entry (validators/validate-implementation-plan-stages.py via
+    prepare_task_bundle). Running the same validator here moves the failure to
+    produce-time."""
+    mod = _load_stage_validator()
+    if mod is None:  # pragma: no cover — repo/runtime always ship the file
+        failures.append(f"cannot load Stage Map validator at {_STAGE_VALIDATOR_PATH}")
+        return
+    for e in mod.collect_validation_errors(content):
+        failures.append(
+            f"implementation-planning Stage Map structure invalid "
+            f"[{e.code} stage={e.stage}]: {e.message}"
+        )
+
+
 def validate_phase_boundary(
     task_type: str,
     report_path: Path,
@@ -1210,6 +1292,12 @@ def validate_phase_boundary(
             "must NOT publish a pre-approved plan when verification did not pass."
         )
 
+    # Only a publishable plan (gate passed) can be flipped to `approved: true`
+    # and reach the `implementation` entry, so the Stage Map structure is
+    # enforced only here — a blocked/aborted plan may legitimately be incomplete.
+    if gate_value in ("passed", "passed-with-dissent"):
+        _append_stage_structure_failures(content, failures)
+
 
 def _parse_brief_frontmatter(brief_path: Path) -> dict:
     """Parse YAML frontmatter from a brief file into a flat dict.
@@ -1286,6 +1374,29 @@ def _validate_improvement_discovery(
             failures.append(f"improvement-discovery: {err}")
 
 
+def _validate_requirements_discovery_fanout(run_dir, failures) -> None:
+    """requirements-discovery run 에 fan-out/ 이 있으면 packet+index 를 검증해
+    실패를 ``requirements-discovery: `` 접두로 folding 한다. fan-out 이 없으면 no-op.
+    """
+    from pathlib import Path as _Path
+    if not (_Path(run_dir) / "fan-out").is_dir():
+        return
+    _validators_dir = _Path(__file__).resolve().parent
+    if str(_validators_dir) not in sys.path:
+        sys.path.insert(0, str(_validators_dir))
+    try:
+        from validate_fanout import validate_fanout  # noqa: E402
+    except Exception as exc:  # pragma: no cover - import guard
+        failures.append(
+            f"requirements-discovery: validate_fanout import failed — {exc}"
+        )
+        return
+    result = validate_fanout(_Path(run_dir))
+    if not result.ok:
+        for err in result.errors:
+            failures.append(f"requirements-discovery: {err}")
+
+
 def _refresh_task_catalog(project_root: Path, task_manifest: dict) -> tuple[bool, str]:
     """Regenerate `discovery/task-catalog.json` so it stops trailing the
     authoritative `task-manifest.json` after validation.
@@ -1634,6 +1745,9 @@ def main() -> int:
         )
         run_dir = report_path.parent.parent
         _validate_improvement_discovery(report_path, run_dir, brief_path, failures)
+    if task_type == "requirements-discovery":
+        run_dir = report_path.parent.parent
+        _validate_requirements_discovery_fanout(run_dir, failures)
     validate_report_views(report_path, failures)
 
     validation_status = "passed" if not failures else "failed"

package/runtime/validators/validate-schedule.py

@@ -259,10 +259,10 @@ def validate(path: Path) -> list[str]:
         if section_name not in section_positions:
             continue
         start = section_positions[section_name]
-        # find next `## ` heading or end of file
-        next_h = re.search(r"^##\s", "\n".join(lines[start + 1:]), re.MULTILINE)
-        end = (start + 1 + (next_h.start() if next_h else len(text))) if next_h else len(lines)
-        section_text = "\n".join(lines[start:end])
+        # 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)