okstra 0.55.0 → 0.56.1

package/runtime/python/okstra_ctl/run.py

@@ -276,6 +276,9 @@ class PrepareInputs:
     work_category: str = ""
     base_ref: str = ""
     approved_plan_path: str = ""
+    # implementation 전용: `--qa-waiver "<stageKey>:<reason>"` 사용자 확인형 우회.
+    # prepare-time 에 task-level conformance 매니페스트 entry.waiver 를 채운다.
+    qa_waiver: str = ""
     stage: str = "auto"
     clarification_response_path: str = ""  # absolute or empty
     # release-handoff 전용: PR 본문 템플릿 1회성 override. 빈 문자열이면
@@ -1092,6 +1095,28 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
     return ctx_stage_map
 
 
+def _apply_qa_waiver_if_requested(inp: "PrepareInputs", project_root: Path) -> None:
+    """`--qa-waiver` 가 있으면 task-level 매니페스트 entry 의 waiver 를 채운다."""
+    if not inp.qa_waiver:
+        return
+    from .conformance import apply_qa_waiver, parse_qa_waiver_arg
+    from .paths import task_dir
+    parsed = parse_qa_waiver_arg(inp.qa_waiver)
+    if parsed is None:
+        raise PrepareError(
+            f'--qa-waiver must be "<stageKey>:<reason>", got {inp.qa_waiver!r}'
+        )
+    stage_key, reason = parsed
+    manifest_path = task_dir(project_root, inp.task_group, inp.task_id) / "qa" / "conformance-manifest.json"
+    if not manifest_path.is_file():
+        raise PrepareError(f"--qa-waiver: conformance manifest not found at {manifest_path}")
+    manifest = json.loads(manifest_path.read_text())
+    when = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    if not apply_qa_waiver(manifest, stage_key, reason, at=when):
+        raise PrepareError(f"--qa-waiver: stageKey {stage_key!r} not in manifest {manifest_path}")
+    manifest_path.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n")
+
+
 def _register_and_check_project(project_root: Path, inp: PrepareInputs) -> None:
     """project.json self-registration + (implementation 한정) qaCommands gate 검증."""
     from okstra_project import ResolverError
@@ -1120,6 +1145,7 @@ def _register_and_check_project(project_root: Path, inp: PrepareInputs) -> None:
             qa_errors = validate_qa_commands(project_meta.get("qaCommands"))
             if qa_errors:
                 raise PrepareError(_format_qa_errors(qa_errors))
+        _apply_qa_waiver_if_requested(inp, project_root)
 
 
 def _resolve_roster(inp: PrepareInputs, profile_file: Path) -> tuple[list[str], str]:
@@ -1860,6 +1886,8 @@ def main(argv: list[str]) -> int:
     p.add_argument("--critic", default="")
     p.add_argument("--related-tasks", default="", dest="related_tasks_raw")
     p.add_argument("--approved-plan", default="", dest="approved_plan_path")
+    p.add_argument("--qa-waiver", default="", dest="qa_waiver",
+                   help='Stage conformance 우회: "<stageKey>:<reason>" (사용자 확인형, 매니페스트 entry.waiver 기록)')
     p.add_argument(
         "--stage", default="auto", dest="stage",
         help=(
@@ -1975,6 +2003,7 @@ def main(argv: list[str]) -> int:
         work_category=args.work_category,
         base_ref=args.base_ref,
         approved_plan_path=args.approved_plan_path,
+        qa_waiver=args.qa_waiver,
         stage=args.stage,
         clarification_response_path=clarification_abs,
         pr_template_path=args.pr_template_path,

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

@@ -330,12 +330,13 @@
 
     "implementationPlanning": {
       "type": "object",
-      "description": "RENDER_IF taskType == implementation-planning. §4.5 deliverables.",
+      "description": "RENDER_IF taskType == implementation-planning. §5.5 deliverables.",
       "required": [
         "optionCandidates",
         "tradeoffMatrix",
         "recommendedOption",
-        "stepwiseExecution",
+        "stageMap",
+        "stages",
         "dependencyMigrationRisk",
         "validationChecklist",
         "rollbackStrategy",
@@ -355,7 +356,18 @@
           "items": { "$ref": "#/$defs/TradeoffRow" }
         },
         "recommendedOption": { "$ref": "#/$defs/RecommendedOption" },
+        "stageMap": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/StageMapRow" }
+        },
+        "stages": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/ImplementationPlanStage" }
+        },
         "stepwiseExecution": {
+          "description": "Legacy flat summary kept for compatibility only. New reports use stageMap/stages.",
           "type": "array",
           "minItems": 1,
           "items": { "$ref": "#/$defs/StepRow" }
@@ -385,7 +397,7 @@
 
     "releaseHandoff": {
       "type": "object",
-      "description": "RENDER_IF taskType == release-handoff. §4.6 deliverables.",
+      "description": "RENDER_IF taskType == release-handoff. §5.6 deliverables.",
       "required": [
         "sourceVerificationReport",
         "featureBranchState",
@@ -419,11 +431,14 @@
         },
         "userSelections": {
           "type": "object",
-          "required": ["h1", "h3"],
+          "required": ["h1", "h2b", "h3"],
           "additionalProperties": false,
           "properties": {
             "h1": { "enum": ["local only", "push + PR", "skip"] },
             "h2": { "type": "string" },
+            "h2b": {
+              "enum": ["not-run", "clean", "proceed anyway", "change base branch", "cancel"]
+            },
             "h3": { "enum": ["use as-is", "edit then proceed", "cancel"] }
           }
         },
@@ -482,12 +497,13 @@
 
     "implementation": {
       "type": "object",
-      "description": "RENDER_IF taskType == implementation. §4.7 deliverables.",
+      "description": "RENDER_IF taskType == implementation. §5.7 deliverables.",
       "required": [
         "approvedPlanReference",
         "commitList",
         "diffSummary",
         "outOfPlanEdits",
+        "stageSidecarEvidence",
         "validationEvidence",
         "verifierResults",
         "rollbackVerification",
@@ -526,6 +542,7 @@
           "type": "array",
           "items": { "$ref": "#/$defs/OutOfPlanEditRow" }
         },
+        "stageSidecarEvidence": { "$ref": "#/$defs/StageSidecarEvidence" },
         "validationEvidence": {
           "type": "array",
           "minItems": 1,
@@ -547,7 +564,7 @@
 
     "finalVerification": {
       "type": "object",
-      "description": "RENDER_IF taskType == final-verification. §4.8 deliverables.",
+      "description": "RENDER_IF taskType == final-verification. §5.8 deliverables.",
       "required": [
         "sourceImplementationReport",
         "acceptanceBlockers",
@@ -624,7 +641,7 @@
 
   "allOf": [
     {
-      "description": "implementation-planning task-type requires §4.5 block.",
+      "description": "implementation-planning task-type requires §5.5 block.",
       "if": {
         "properties": { "header": { "properties": { "taskType": { "const": "implementation-planning" } } } },
         "required": ["header"]
@@ -634,7 +651,7 @@
       }
     },
     {
-      "description": "release-handoff task-type requires §4.6 block.",
+      "description": "release-handoff task-type requires §5.6 block.",
       "if": {
         "properties": { "header": { "properties": { "taskType": { "const": "release-handoff" } } } },
         "required": ["header"]
@@ -644,7 +661,7 @@
       }
     },
     {
-      "description": "implementation task-type requires §4.7 block.",
+      "description": "implementation task-type requires §5.7 block.",
       "if": {
         "properties": { "header": { "properties": { "taskType": { "const": "implementation" } } } },
         "required": ["header"]
@@ -654,7 +671,7 @@
       }
     },
     {
-      "description": "final-verification task-type requires §4.8 block.",
+      "description": "final-verification task-type requires §5.8 block.",
       "if": {
         "properties": { "header": { "properties": { "taskType": { "const": "final-verification" } } } },
         "required": ["header"]
@@ -1066,6 +1083,90 @@
       }
     },
 
+    "StageMapRow": {
+      "type": "object",
+      "required": ["stage", "title", "dependsOn", "stepCount", "exitContractSummary"],
+      "additionalProperties": false,
+      "properties": {
+        "stage": { "type": "integer", "minimum": 1 },
+        "title": { "type": "string", "minLength": 1 },
+        "dependsOn": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Literal Stage Map depends-on cell: `(none)` or a comma-separated stage number list."
+        },
+        "stepCount": { "type": "integer", "minimum": 0, "maximum": 6 },
+        "exitContractSummary": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "ImplementationPlanStage": {
+      "type": "object",
+      "required": [
+        "stage",
+        "title",
+        "sliceValue",
+        "acceptance",
+        "carryIn",
+        "stepwiseExecution",
+        "exitContract",
+        "stageValidation"
+      ],
+      "additionalProperties": false,
+      "oneOf": [
+        {
+          "required": ["conformanceTests"],
+          "not": { "required": ["conformanceExemption"] }
+        },
+        {
+          "required": ["conformanceExemption"],
+          "not": { "required": ["conformanceTests"] }
+        }
+      ],
+      "properties": {
+        "stage": { "type": "integer", "minimum": 1 },
+        "title": { "type": "string", "minLength": 1 },
+        "sliceValue": { "type": "string", "minLength": 1 },
+        "acceptance": { "type": "string", "minLength": 1 },
+        "conformanceTests": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Text after the `Conformance tests: stage-N — ...` prefix."
+        },
+        "conformanceExemption": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Text after the `Conformance exemption:` prefix."
+        },
+        "tddExemption": {
+          "type": "string",
+          "description": "Optional text after the `TDD exemption:` prefix."
+        },
+        "carryIn": { "type": "string", "minLength": 1 },
+        "stepwiseExecution": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 6,
+          "items": { "$ref": "#/$defs/StageStepRow" }
+        },
+        "exitContract": { "type": "string", "minLength": 1 },
+        "stageValidation": { "type": "string", "minLength": 1 }
+      }
+    },
+
+    "StageStepRow": {
+      "type": "object",
+      "required": ["step", "action", "files", "command", "expected"],
+      "additionalProperties": false,
+      "properties": {
+        "step": { "type": "integer", "minimum": 1 },
+        "action": { "type": "string", "minLength": 1 },
+        "files": { "type": "string", "minLength": 1 },
+        "command": { "type": "string", "minLength": 1 },
+        "expected": { "type": "string", "minLength": 1 }
+      }
+    },
+
     "StepRow": {
       "type": "object",
       "required": ["step", "ticketId", "action", "files", "commandOrTest", "expectedOutcome"],
@@ -1080,6 +1181,22 @@
       }
     },
 
+    "StageSidecarEvidence": {
+      "type": "object",
+      "required": ["stageNumber", "stageTitle", "carryJson", "consumerRows"],
+      "additionalProperties": false,
+      "properties": {
+        "stageNumber": { "type": "integer", "minimum": 1 },
+        "stageTitle": { "type": "string", "minLength": 1 },
+        "carryJson": { "type": "string", "minLength": 1 },
+        "consumerRows": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+
     "DependencyRow": {
       "type": "object",
       "required": ["id", "kind", "item", "impact", "mitigation"],

package/runtime/skills/okstra-coding-preflight/SKILL.md

@@ -62,6 +62,14 @@ If you suspect an overlay applies but the layout is non-standard, ask one questi
 - [ ] Existing code searched: `grep` for the symbol / file / identifier you are about to add. Do not duplicate.
 - [ ] Project conventions checked: `.editorconfig`, `CONTRIBUTING.md`, formatter config (`.prettierrc`, `rustfmt.toml`, `ktlint`, `google-java-format`, etc.). **Project rules override this skill on conflict.**
 
+## Completion sweep (before declaring a multi-file change done)
+
+Per-file checks miss cross-cutting issues; each commit can be individually clean while the sum violates DRY. Before saying "done":
+
+- [ ] **Domain-literal sweep:** `grep -rn` every domain enum value / predicate you added or touched in WHERE clauses, filters, or branches. The same literal at 2+ I/O sites is a *candidate* scattered decision — ask: would these sites change together when the business rule changes? Same decision → consolidate into one named constant or query builder in the domain layer and make every site reference it. Different decisions that merely share a value → leave them separate; coupling incidental duplication is worse than the repetition. (The identifier grep above does NOT catch this — sweep *values*, not just names.)
+- [ ] **Stand-alone name test for exports:** for each exported identifier, look at its siblings — can a caller pick the right one from the names alone? If a comment must explain which to use, the name fails; encode the distinguishing fact in it (e.g., the input shape: `parseRows` vs `parseRowsFromFlatItems`).
+- [ ] **No documented forks:** two deliberate variants of one capability must not survive as parallel implementations with a comment explaining the delta. Re-read both bodies and check the deltas are genuinely parametric: if they reduce to a few orthogonal options, collapse into one implementation taking explicit option parameters that encode them. If encoding the delta would take more than ~3 options, or add more branching than the duplication it removes, they are two capabilities — keep two implementations with distinct honest names and delete the "variant of" framing. Either way the comment-documented fork dies. "The divergence is documented" stays a refused rationalization, and a two-capabilities verdict must come from reading the bodies, not from reluctance to refactor.
+
 ## Boundaries
 
 - This skill does **not** auto-format. Run the project's formatter yourself.

package/runtime/skills/okstra-coding-preflight/clean-code.md

@@ -22,6 +22,11 @@ const sum = (arr) => arr.reduce((acc, x) => acc + x, 0);
 
 Caveat: do not extract until the duplication is real (rule of three). Premature abstraction is also a code smell.
 
+Two more forms of duplication that hide from symbol-level grep:
+
+- **Scattered domain literals** — the same enum value / predicate repeated across queries or filters *may* be one business decision duplicated. The test: would the sites change together when the rule changes? If yes, consolidate to a named constant or builder at a single reference point; if they merely share a value, leave them apart — coupling incidental duplication is worse than repetition.
+- **Documented forks** — two deliberate variants of one capability kept as parallel implementations "because the delta is commented". If the delta is genuinely parametric (a few orthogonal options), collapse into one implementation with explicit option parameters; if not, split into two distinctly named capabilities. The commented fork itself is never the end state.
+
 ## KISS — Keep It Simple
 
 The simplest solution that meets the requirement wins. Cleverness has a maintenance cost.
@@ -104,6 +109,7 @@ The test: if the name appeared in a stacktrace, an autocomplete list, or a grep
 - Generic verbs with no information: `handle`, `process`, `execute`, `doStuff`, `manage`. If the function deletes-then-inserts, name it `replace`, not `update`.
 - Constants that will collide with siblings later: `BUCKET` → `FONTS_BUCKET`, `TIMEOUT` → `HTTP_READ_TIMEOUT_MS`, `URL` → `AUTH_SERVICE_URL`.
 - Repository / port methods named after the rule they enforce, not the data they fetch: `findValid*` / `findActive*` / `findEligible*` — the adjective encodes a business rule the caller can't inspect from the name. Prefer `findDesktopLibrariesForUser(userId)` + a domain predicate applied by the caller.
+- Near-twin siblings a caller can't tell apart from the names alone (`parseRows` vs `parseRowsFromItems`): if a comment must explain which to pick, rename — encode the distinguishing fact (e.g., input shape: `parseRowsFromFlatItems`). Matching the existing sibling's style does not excuse the ambiguity.
 
 This rule applies most strongly to **names crossing module boundaries**: public methods, exported constants, port methods. Private helpers in a tight local scope get more slack.
 

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

@@ -184,6 +184,18 @@ The python function underneath is mutex-protected (`~/.okstra/.locks/<task-key>.
 
 You can delete the literal state-file path after this point — its job is done. Invoke `rm` with the literal path (e.g. `rm /var/folders/.../okstra-wizard.AbCd.json`), not a shell variable.
 
+### Step 5.1 (implementation only): conformance waiver offer
+
+`render-bundle` accepts an optional `--qa-waiver "<stageKey>:<reason>"` flag (implementation only). It records a **user-acknowledged** waiver into the task-level conformance manifest entry (`entry.waiver`), letting the run proceed when a stage's Tier 3 conformance script genuinely cannot run (e.g. the replica DB is unreachable). The waiver records the user's reason **verbatim**.
+
+This is **never** a lead/worker self-exemption — only the user may waive. Offer it **only** when conformance BLOCKING is expected (the chosen stage declares a conformance entry whose script you cannot run in this environment). Surface it as a 3-option recommendation picker (per the run-prompt recommendation rule):
+
+1. (recommended) Run the conformance script — no waiver.
+2. Waive this stage — ask the user for the exact `<stageKey>` and reason, then pass `--qa-waiver "<stageKey>:<reason>"` to `render-bundle` (reason = the user's words, unedited).
+3. 직접 입력 — the user types the full `<stageKey>:<reason>` value.
+
+When the user picks a waiver, append `--qa-waiver "<stageKey>:<reason>"` to the `render-bundle` invocation above. Omit the flag entirely otherwise (do **not** pass `--qa-waiver ""`). A malformed value or unknown `<stageKey>` aborts `render-bundle` with a `PrepareError`.
+
 ## Step 6: Take over as Claude lead
 
 Read `<INSTRUCTION_SET_PATH>/claude-execution-prompt.md` verbatim and enter `Claude lead` mode. The lead prompt now points to compact intake artifacts first (`active-run-context`, `analysis-profile.md`, and `analysis-packet.md`); full source files such as `analysis-material.md`, `reference-expectations.md`, and `final-report-template.md` are lazy/fallback inputs. Follow the rendered prompt order, do not preempt it.

package/runtime/skills/okstra-run/templates/pr-body.template.md

@@ -17,25 +17,25 @@ okstra release-handoff 기본 PR 본문 템플릿.
   - `git log --oneline <base>..HEAD` 의 commit 범위
   - `git diff <base>..HEAD --stat` 의 변경 파일 통계
 
-빈 섹션은 그대로 두지 말고 통째로 삭제합니다. HTML 주석은 PR 생성 전에
-모두 제거됩니다.
 -->
 
-## Summary
+## **Please check if the PR fulfills these requirements**
+- [ ] Commits have a single intent
+- [ ] Tests for the changes have been added (for bug fixes / features)
+- [ ] I reviewed my own code
+- [ ] I tested the changes (if not, explain why in the "Other information" section)
+- [ ] Docs have been added / updated
 
-<!-- 1–3 bullets. 변경의 동기(WHY)와 결과(WHAT changed at a high level). -->
+## **What kind of change does this PR introduce?** (Bug fix, feature, docs update, ...)
 
-## Changes
 
-<!-- 영역별로 묶은 구체적 변경 목록. 파일/모듈 단위 그룹화 권장. -->
+## **What is the current behavior?** (You can also link to an open issue here)
 
-## Test plan
 
-<!-- 리뷰어가 따라 할 수 있는 검증 절차. 자동/수동 모두 가능. -->
+## **What is the new behavior (if this is a feature change)?**
 
-- [ ] <검증 항목>
-- [ ] <검증 항목>
 
-## Linked issues
+## **Does this PR introduce a breaking change?** (What changes might users need to make in their application due to this PR?)
 
-<!-- `Refs: TICKET-123`, `Closes #N`, 관련 PR 링크 등. 없으면 섹션 통째로 삭제. -->
+
+## **Other information**:

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

@@ -181,6 +181,41 @@ The field is preserved across the runtime's auto-upserts of
 `updatedAt` are runtime-owned, so manual edits to `qaCommands`
 survive every subsequent `okstra setup` / `okstra run` invocation.
 
+### Step 4.6.1 (optional): `qaEnv` — Tier 3 conformance environment
+
+`implementation` / `final-verification` verifiers run **stage
+conformance scripts** (Tier 3) that may need to reach a database or an
+HTTP endpoint to prove the diff satisfies upstream requirements. Declare
+the environment those scripts are allowed to touch under `qaEnv`. Every
+field is optional; declare only what your conformance scripts use.
+
+```json
+"qaEnv": {
+  "replicaDbDsn": "<replica/test DB DSN — never shared/staging/prod>",
+  "appBaseUrl": "http://localhost:3000",
+  "envFile": ".okstra/qa.env",
+  "surfacePatterns": { "db": ["*.sql", "*repository*"], "http": ["*controller*"] }
+}
+```
+
+- `replicaDbDsn` — DSN the conformance script connects to. MUST be a
+  replica / disposable test DB, **never** a shared, staging, or
+  production database (conformance scripts may write).
+- `appBaseUrl` — base URL for endpoint-level conformance checks
+  (local app only).
+- `envFile` — path (under `.okstra/`) to an env file the verifier
+  sources before running conformance scripts.
+- `surfacePatterns` — per-project **override** of the diff-surface
+  cross-check map (`capability → glob list`). The validator maps each
+  changed file to a capability surface (`db` / `http` / `io`) and fails
+  the run when the diff touches a surface no stage `requires`. The
+  built-in patterns (e.g. `*router*` for `http`, `*storage*` for `io`)
+  are broad and match many front-end files, so front-end-heavy repos
+  should override with narrower globs to avoid false BLOCKING verdicts
+  (Phase 4b review note). An over-broad pattern over-blocks; an
+  over-narrow one lets an undeclared surface through — tune to the
+  repo's real db/http/io file naming.
+
 ## Step 4.7 (automatic): project-local Claude settings symlink
 
 `okstra setup` (and `okstra run` on its first invocation per project)

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

@@ -140,7 +140,7 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 {% if header.taskType == 'implementation-planning' %}
 ## 5.5 Implementation Plan Deliverables
 
-### 5.5.1 Option Candidates{% if t("sectionAside.optionCandidates") != "Option Candidates" %} ({{ t("sectionAside.optionCandidates") }}){% endif %}
+### Option Candidates{% if t("sectionAside.optionCandidates") != "Option Candidates" %} ({{ t("sectionAside.optionCandidates") }}){% endif %}
 
 {% for opt in implementationPlanning.optionCandidates %}
 **{{ opt.name }}**
@@ -158,7 +158,7 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 
 {% endfor %}
 
-### 5.5.2 Trade-off Matrix{% if t("sectionAside.tradeOffMatrix") != "Trade-off Matrix" %} ({{ t("sectionAside.tradeOffMatrix") }}){% endif %}
+### Trade-off Matrix{% if t("sectionAside.tradeOffMatrix") != "Trade-off Matrix" %} ({{ t("sectionAside.tradeOffMatrix") }}){% endif %}
 
 | Option | Complexity | Risk | Reversibility | Test Coverage Cost | Rollout Cost |
 |--------|-----------|------|---------------|--------------------|--------------|
@@ -166,7 +166,7 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 | {{ row.option }} | {{ row.complexity }} | {{ row.risk }} | {{ row.reversibility }} | {{ row.testCoverageCost }} | {{ row.rolloutCost }} |
 {% endfor %}
 
-### 5.5.3 Recommended Option{% if t("sectionAside.recommendedOption") != "Recommended Option" %} ({{ t("sectionAside.recommendedOption") }}){% endif %}
+### Recommended Option{% if t("sectionAside.recommendedOption") != "Recommended Option" %} ({{ t("sectionAside.recommendedOption") }}){% endif %}
 
 | {{ t("implementationPlanning.recommendedTableHeaderLabel") }} | {{ t("implementationPlanning.recommendedTableHeaderValue") }} |
 |------|----|
@@ -175,15 +175,7 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 | {{ t("implementationPlanning.rationaleLabel") }} | {{ implementationPlanning.recommendedOption.rationale }} |
 | {{ t("implementationPlanning.rejectedSummaryLabel") }} | {{ implementationPlanning.recommendedOption.rejectedSummary }} |
 
-### 5.5.4 Stepwise Execution Order{% if t("sectionAside.stepwiseExecutionOrder") != "Stepwise Execution Order" %} ({{ t("sectionAside.stepwiseExecutionOrder") }}){% endif %}
-
-| Step | Ticket ID | Action (≤ 5min) | Files | Command / Test | Expected outcome |
-|------|-----------|------------------|-------|----------------|-------------------|
-{% for row in implementationPlanning.stepwiseExecution -%}
-| {{ row.step }} | `{{ row.ticketId }}` | {{ row.action }} | `{{ row.files }}` | `{{ row.commandOrTest }}` | {{ row.expectedOutcome }} |
-{% endfor %}
-
-### 5.5.5 Dependency / Migration Risk{% if t("sectionAside.dependencyRisk") != "Dependency / Migration Risk" %} ({{ t("sectionAside.dependencyRisk") }}){% endif %}
+### Dependency / Migration Risk{% if t("sectionAside.dependencyRisk") != "Dependency / Migration Risk" %} ({{ t("sectionAside.dependencyRisk") }}){% endif %}
 
 {% if implementationPlanning.dependencyMigrationRisk | length == 0 -%}
 {{ t("emptyState.dependencyRisk") }}
@@ -195,7 +187,7 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 {% endfor %}
 {%- endif %}
 
-### 5.5.6 Validation Checklist{% if t("sectionAside.validationChecklist") != "Validation Checklist" %} ({{ t("sectionAside.validationChecklist") }}){% endif %}
+### Validation Checklist{% if t("sectionAside.validationChecklist") != "Validation Checklist" %} ({{ t("sectionAside.validationChecklist") }}){% endif %}
 
 | Phase | Ticket ID | Check | Command / Observation | Expected outcome |
 |-------|-----------|-------|------------------------|-------------------|
@@ -203,7 +195,7 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 | {{ row.phase }} | `{{ row.ticketId }}` | {{ row.check }} | `{{ row.commandOrObservation }}` | {{ row.expectedOutcome }} |
 {% endfor %}
 
-### 5.5.7 Rollback Strategy{% if t("sectionAside.rollbackStrategy") != "Rollback Strategy" %} ({{ t("sectionAside.rollbackStrategy") }}){% endif %}
+### Rollback Strategy{% if t("sectionAside.rollbackStrategy") != "Rollback Strategy" %} ({{ t("sectionAside.rollbackStrategy") }}){% endif %}
 
 | ID | Step | Action | Trigger signal | {{ t("columns.checkMethod") }} |
 |----|------|--------|----------------|-----------|
@@ -211,7 +203,7 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 | {{ row.id }} | {{ row.step }} | `{{ row.action }}` | {{ row.triggerSignal }} | `{{ row.verificationMethod }}` |
 {% endfor %}
 
-### 5.5.8 Requirement Coverage
+### Requirement Coverage
 
 | ID | Source | Requirement | Covered by option / stage / step | Status |
 |----|--------|-------------|-----------------------------------|--------|
@@ -219,6 +211,45 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 | {{ row.id }} | `{{ row.source }}` | {{ row.requirement }} | {{ row.coveredBy }} | `{{ row.status }}` |
 {% endfor %}
 
+## 5.5 Stage Map
+
+| stage | title | depends-on | step-count | exit-contract-summary |
+|-------|-------|------------|------------|-----------------------|
+{% for row in implementationPlanning.stageMap -%}
+| {{ row.stage }} | {{ row.title }} | {{ row.dependsOn }} | {{ row.stepCount }} | {{ row.exitContractSummary }} |
+{% endfor %}
+
+{% for stage in implementationPlanning.stages %}
+## 5.5.{{ stage.stage }} Stage {{ stage.stage }}: {{ stage.title }}
+
+Slice value: {{ stage.sliceValue }}
+Acceptance: {{ stage.acceptance }}
+{% if stage.conformanceTests %}Conformance tests: stage-{{ stage.stage }} — {{ stage.conformanceTests }}
+{% else %}Conformance exemption: {{ stage.conformanceExemption }}
+{% endif %}{% if stage.tddExemption %}TDD exemption: {{ stage.tddExemption }}
+{% endif %}
+### Carry-In
+
+{{ stage.carryIn }}
+
+### Stepwise Execution Order
+
+| step | action | files | command | expected |
+|------|--------|-------|---------|----------|
+{% for row in stage.stepwiseExecution -%}
+| {{ row.step }} | {{ row.action }} | `{{ row.files }}` | `{{ row.command }}` | {{ row.expected }} |
+{% endfor %}
+
+### Stage Exit Contract
+
+{{ stage.exitContract }}
+
+### Stage Validation
+
+{{ stage.stageValidation }}
+
+{% endfor %}
+
 ### 5.5.9 Plan Body Verification{% if t("sectionAside.planBodyVerification") != "Plan Body Verification" %} ({{ t("sectionAside.planBodyVerification") }}){% endif %}
 
 {{ t("sectionIntro.planBodyVerification") }}
@@ -271,6 +302,7 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 |---------|-----------|--------------------|--------------------|
 | H1 | {{ t("releaseHandoff.h1Body") }} | `{{ releaseHandoff.userSelections.h1 }}` | `local only` / `push + PR` / `skip` |
 | H2 | {{ t("releaseHandoff.h2Body") }} | `{{ releaseHandoff.userSelections.h2 or t("releaseHandoff.h2DefaultLabel") }}` | {{ t("releaseHandoff.h2OptionsLabel") }} |
+| H2b | Merge conflict probe | `{{ releaseHandoff.userSelections.h2b or releaseHandoff.mergeConflictProbe.kind }}` | `not-run` / `clean` / `proceed anyway` / `change base branch` / `cancel` |
 | H3 | {{ t("releaseHandoff.h3Body") }} | `{{ releaseHandoff.userSelections.h3 }}` | `use as-is` / `edit then proceed` / `cancel` |
 
 ### 5.6.4 Executed Commands
@@ -371,7 +403,19 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 {% endfor %}
 {%- endif %}
 
-### 5.7.5 Validation Evidence
+### 5.7.5 Stage Sidecar Evidence
+
+- Stage: `{{ implementation.stageSidecarEvidence.stageNumber }}` — {{ implementation.stageSidecarEvidence.stageTitle }}
+- Carry sidecar JSON:
+  ```json
+  {{ implementation.stageSidecarEvidence.carryJson }}
+  ```
+- Appended `consumers.jsonl` rows:
+{% for row in implementation.stageSidecarEvidence.consumerRows -%}
+  > {{ row }}
+{% endfor %}
+
+### 5.7.6 Validation Evidence
 
 | Phase | Command | Exit code | Output tail | TDD evidence |
 |-------|---------|-----------|-------------|--------------|
@@ -379,7 +423,7 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 | {{ row.phase }} | `{{ row.command }}` | `{{ row.exitCode }}` | {{ row.outputTail }} | {{ row.tddEvidence or '--' }} |
 {% endfor %}
 
-### 5.7.6 Verifier Results
+### 5.7.7 Verifier Results
 
 {% for block in implementation.verifierResults %}
 - **{{ block.verifier }}** — Verdict: `{{ block.verdict }}`
@@ -390,7 +434,7 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
   - Discrepancy: {{ block.discrepancy or t("emptyState.discrepancy") }}
 {% endfor %}
 
-### 5.7.7 Rollback Verification
+### 5.7.8 Rollback Verification
 
 | Category | Rollback command | Verification | Result |
 |----------|-------------------|---------------|--------|
@@ -398,7 +442,7 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 | {{ row.category }} | `{{ row.rollbackCommand }}` | {{ row.verification }} | `{{ row.result }}` |
 {% endfor %}
 
-### 5.7.8 Routing Recommendation
+### 5.7.9 Routing Recommendation
 
 {{ implementation.routingRecommendation }}
 

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

@@ -105,7 +105,7 @@
     "h2Body": "PR base branch (when H1 = `push + PR`)",
     "h3Body": "How should the PR title/body draft be handled?",
     "h2DefaultLabel": "(n/a)",
-    "h2OptionsLabel": "staging / preprod / prod / main / dev / user input",
+    "h2OptionsLabel": "staging / preprod / main / user input",
     "noMutationNote": "(no mutating command — H1=`skip` or H3=`cancel`)",
     "commandsTableHeader": {
       "outputSummary": "stdout/stderr summary"

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

@@ -105,7 +105,7 @@
     "h2Body": "PR base 브랜치 (H1=`push + PR` 인 경우)",
     "h3Body": "PR title/body 초안 처리",
     "h2DefaultLabel": "(n/a)",
-    "h2OptionsLabel": "staging / preprod / prod / main / dev / 사용자 입력",
+    "h2OptionsLabel": "staging / preprod / main / 사용자 입력",
     "noMutationNote": "(mutating 명령 미실행 — H1=`skip` 또는 H3=`cancel`)",
     "commandsTableHeader": {
       "outputSummary": "stdout/stderr 요약"

package/runtime/templates/reports/implementation-input.template.md

@@ -27,7 +27,7 @@ taskType: "{{FM_TASK_TYPE}}"
 ## Approved Plan Reference (mandatory)
 
 - Approved plan path: `runs/implementation-planning/<run-id>/reports/final-report.md`
-- Approval evidence (quoted exactly from the plan's `User Approval Request` resolution):
+- Approval evidence (quoted exactly from the plan's YAML frontmatter, e.g. `approved: true`):
 - Recommended option name selected from the plan:
 - Plan's bite-sized step list (paste or reference by anchor):