okstra 0.155.0 → 0.157.0

package/runtime/python/okstra_ctl/wizard.py

@@ -77,7 +77,6 @@ from okstra_ctl.run import (
 from okstra_ctl.stage_map import (
     StageMapError,
     parse_stage_map_file,
-    parse_stage_map_text,
     stage_map_records,
 )
 from okstra_ctl.user_response import (
@@ -1034,16 +1033,7 @@ def _fix_cycle_confirm_required(state: WizardState) -> bool:
 def _parse_stage_objects(state: WizardState) -> list:
     """Return the approved plan's strict Stage Map objects for the picker."""
     try:
-        plan_text = Path(state.approved_plan_path).read_text(encoding="utf-8")
-        return parse_stage_map_text(
-            plan_text,
-            source_plan_path=str(Path(state.approved_plan_path).resolve()),
-        )
-    except OSError as exc:
-        raise WizardError(
-            f"approved plan 의 Stage Map 을 읽을 수 없습니다 "
-            f"({state.approved_plan_path}): {exc}"
-        ) from exc
+        return parse_stage_map_file(Path(state.approved_plan_path))
     except StageMapError as exc:
         raise WizardError(
             f"approved plan 의 Stage Map 을 신뢰할 수 없습니다 "

package/runtime/python/okstra_project/state.py

@@ -384,12 +384,23 @@ def stage_map_read_side_snapshot(project_root: Path, task_key: str) -> dict:
     """
     from okstra_ctl.consumers import read_stage_consumer_state
     from okstra_ctl.paths import RunRef
-    from okstra_ctl.stage_map import StageMapError, load_task_stage_map
+    from okstra_ctl.stage_map import (
+        PlanningDetail,
+        StageMapError,
+        load_planning_detail,
+        load_task_stage_map,
+        merge_planning_detail,
+    )
 
     identity = resolve_task_identity(project_root, task_key)
     task_root = Path(identity["taskRoot"])
     try:
         stage_snapshot = load_task_stage_map(task_root, identity["manifest"])
+        detail = (
+            load_planning_detail(Path(stage_snapshot.source_plan_path))
+            if stage_snapshot.source_plan_path
+            else PlanningDetail({}, {})
+        )
     except StageMapError as exc:
         raise StateError(str(exc), stage=exc.code) from exc
     plan_run_root = RunRef.from_task_root(
@@ -407,8 +418,9 @@ def stage_map_read_side_snapshot(project_root: Path, task_key: str) -> dict:
         "taskRoot": identity["taskRoot"],
         "state": stage_snapshot.state,
         "sourcePlanPath": stage_snapshot.source_plan_path,
-        "stages": stage_snapshot.stages,
+        "stages": merge_planning_detail(stage_snapshot.stages, detail),
         "doneStages": done,
+        "planning": detail.task_narratives,
     }
 
 

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

@@ -49,13 +49,13 @@ If the call fails with `unknown command: preflight`, the `okstra` binary on PATH
 
 ## Contract SSOT — template + validator
 
-The installed template `~/.okstra/templates/reports/schedule.template.md` is the **byte-for-byte SSOT** for the output shape: frontmatter, top header block, the mandatory `##` heading list and order, per-task `Item / Detail` field labels and sub-section order, table column shapes, the ASCII Gantt format (relative day axis, plain fence, `█`/`░`/`! crit`/`est` legend), the dependency-graph shapes, and the optional `## Glossary` gate. **Read the template before writing the schedule and follow it exactly** — do not re-derive section shapes from memory. Headings and field labels stay English literals regardless of the source-report language; body prose is Korean. When a section has no data, render its heading with `_none_` — never delete or reorder headings. Never emit mermaid or any graph DSL.
+The installed template `~/.okstra/templates/reports/schedule.template.md` is the **byte-for-byte SSOT** for the output shape: frontmatter, top header block, the mandatory `##` heading list and order, per-task `Item / Detail` field labels and sub-section order, table column shapes, the ASCII Gantt format (relative day axis, plain fence, bar-only rows), the dependency-graph shapes, and the optional `## Glossary` gate. **Read the template before writing the schedule and follow it exactly** — do not re-derive section shapes from memory. Headings and field labels stay English literals regardless of the source-report language; body prose is Korean. When a section has no data, render its heading with `_none_` — never delete or reorder headings. Never emit mermaid or any graph DSL.
 
 `~/.okstra/lib/validators/validate-schedule.py` is the enforcement for all of the above (heading order, field labels, controlled vocabulary — e.g. `Med-High` is the canonical risk form — forbidden translations, checkbox bans, Gantt fence rules, unresolved-code detection). The Step 4 ambiguous-classification rationale line is the one rule the validator does not yet enforce — emit it yourself.
 
 One computation rule the template scaffold cannot carry inline:
 
-- **Effort-to-Day mapping**: day ranges per size are defined once in the template's `### Effort Sizing Criteria` table. For the At a Glance totals line, sum that table's lower bounds across in-scope tasks for the lower total and upper bounds for the upper total.
+- **Effort-to-Day mapping**: day ranges per size are defined once in the template's `### Effort Sizing Criteria` table, and a task's `Days` cell takes its range from that row. `XXL` is the exception — it has no finite upper bound there, so an XXL task is sized by its own stage decomposition and its `Days` cell is the sum of its Work Breakdown rows. The At a Glance totals line sums every in-scope task's `Days`, XXL included. Append ` (est)` to a `Days` range the schedule derived rather than read from the plan; implementation-planning states no durations, so that is every range today.
 
 ## Procedure
 
@@ -85,7 +85,7 @@ For each in-scope task, the **authoritative source is its `implementation-planni
 okstra stage-map <task-key> --json
 ```
 
-The response is source-aware: `{ok, taskKey, taskRoot, state, sourcePlanPath, stages:[{stage_number,title,depends_on,step_count}], doneStages:[int]}`. Branch on it explicitly:
+The response is source-aware: `{ok, taskKey, taskRoot, state, sourcePlanPath, stages:[…], doneStages:[int], planning:{…}}`. Each stage row carries `stage_number`, `title`, `depends_on`, `step_count`, `exit_contract_summary` and — from a schema-v2 report — that stage's `stepwiseExecution` (the numbered steps, each with `action`, `files`, `command`, `expected`), `sliceValue`, `acceptance` and `exitContract`. `planning` carries the report's task-level rows: `rollbackStrategy`, `validationChecklist`, `crossProjectDependencies`, `dependencyMigrationRisk`, `recommendedOption`. Branch on it explicitly:
 
 The resolved source, when ready, is a report under `runs/implementation-planning`; the CLI owns choosing exactly one report from that domain.
 
@@ -93,7 +93,7 @@ The resolved source, when ready, is a report under `runs/implementation-planning
 - `ok: true, state: "missing"` — record an empty source and empty stage sets. Tag the task `[NEEDS-PLANNING]`, skip the stage picker, and render task-level metadata only, with no forward Work Breakdown row, Gantt row, or day total.
 - `ok: false` or any state other than `ready` and `missing` — this is a structured Stage Map error, such as a corrupt or conflicting plan source. Stop before drafting, preserve the CLI `stage` and `reason` in the user-facing error, and do not guess from another report.
 
-For `ready`, read task-level Priority / Risk / Scope / Repos from `sourcePlanPath`. Read header and phase-bucket metadata from `task-manifest.json`: `taskId`, `taskGroup`, `taskKey`, `workCategory`, `workStatus`, `taskType`, and `workflow.currentPhase`. Blocking and approval items are not extracted (see Audience & authority).
+For `ready`, the CLI response is the source for everything the schedule renders — stage rows and `planning` together. Read `sourcePlanPath` only for the task-level Priority / Risk / Scope / Repos that the payload does not carry, and read no further into it: transcribing the payload is the whole point of Step 4. Read header metadata from `task-manifest.json`: `taskId`, `taskGroup`, `taskKey`, `workCategory`, `workStatus`, `taskType`, and `workflow.currentPhase`. Blocking and approval items are not extracted (see Audience & authority).
 
 If unfinished stages are empty while `workStatus` is not `done`, render `_Complete — no remaining stage_` under the task's phase section and contribute no forward day total.
 
@@ -113,28 +113,44 @@ Run this **once per in-scope task that has a non-empty `remainingStages`**, sequ
 
 Record the chosen `selectedStages` for this task. Reject and re-prompt any custom selection whose transitive `depends_on` closure is not covered by `selectedStages ∪ doneStages`.
 
-### Step 4: Phase classification
+### Step 4: Task ordering and per-task transcription
 
 The canonical categories come from `scripts/okstra_ctl/work_categories.py::WORK_CATEGORIES`. Do not infer or publish another category.
 
-| workCategory | Default phase |
-|--------------|---------------|
-| `bugfix` | Phase 1 when risk is High/Med-High; otherwise Phase 2 |
-| `feature` / `improvement` | Phase 2 |
-| `refactor` / `ops` | Phase 3 |
-| unmatched or missing | Phase 2, with rationale `> _workCategory '<raw-value>' undefined — defaulting to Phase 2._` at the top of that phase section |
+**There are no phase buckets and no priority table.** `## Task Details` holds one `### <n>. <Title>` block per in-scope task, numbered from 1 in At a Glance order. The heading is the work's name — the task-id is a machine key and belongs in the At a Glance row, not in a heading the reader has to decode; the block binds to its row by number. At a Glance is already sorted Priority-first, so that ordering carries priority; sequence lives in the stages; and `## Recommended Immediate Actions` is the one place that says what to do next. In the per-task `Item / Detail` table, `Status` says where the work stands in plain words — "구현 계획 승인됨 — 실행 미착수", not `implementation-planning / implementation-planning`. Derive it from `taskType` and `workflow.currentPhase`, but never print those tokens: they are okstra's phase names and the reader has no phases.
 
-Priority overrides category: `P0` → Phase 1; `P1`/`P2` → Phase 2; `P3` or multi-repo + infrastructure scope → Phase 3. When still ambiguous, place the task in the closest phase and add a one-line rationale at the top of that phase section (not validator-enforced — emit it yourself).
+Order At a Glance by Priority (`P0` first), breaking ties by `workCategory` in this canonical order: `bugfix`, `feature`, `refactor`, `ops`, `improvement`. A task whose `workCategory` is unmatched or missing sorts last within its priority and keeps its raw value in the `Category` cell — never substitute a category that is not in that list.
 
-Phase bucketing stays **task-level** (a task lands in one Phase by its `workCategory`/Priority). `workStatus` is only a Step 2 candidate filter. In the per-task `Item / Detail` table, render `Status` as `<taskType> / <currentPhase>`.
+Within a task's block, selected stages become the Work Breakdown rows under the exact header `| Stage | Title | Steps | Depends On | Days |`. Render one row per selected stage using its Stage Map `title`, `step_count`, and `depends_on`, plus its proportional day range. Stages excluded because they are already done are listed once as `> _Done stages: stage <n>, …_` and carry no forward effort.
 
-Within a task's per-task section, selected stages become the Work Breakdown rows under the exact header `| Stage | Title | Steps | Depends On | Days |`. Render one row per selected stage using its Stage Map `title`, `step_count`, and `depends_on`, plus its proportional day range. Stages excluded because they are already done are listed once as `> _Done stages: stage <n>, …_` and carry no forward effort.
+**Write the schedule FOR the team executing it, FROM the plan.** Two different duties:
+
+- **Facts are carried exactly.** File paths, commands, counts, day ranges, rollback triggers, the number of specs or tables — a wrong path or a dropped item is a defect. This is what a hand-written summary of the report loses, and why `okstra stage-map` hands them over structurally.
+- **Prose is rewritten for the reader doing the work.** Say what the step does, why it exists, and what they should see when it succeeds. Do NOT paste a source field wholesale: the planning report was written to justify a design to a reviewer, so it carries sentences arguing for the approach — `sliceValue` is exactly that — which tell an implementer nothing. A schedule full of them reads as a record of someone else's deliberation.
+
+Selecting which source rows belong in a schedule is not summarising. Dropping a justification is correct; dropping a file path is not.
+
+**The reader has no access to the plan's review history.** A sentence like "this answers the objection that sank the direction the first time" or "the reporter's rationale is …" assumes the reader watched the plan being argued. State the engineering reason directly — *why this order, what breaks without it* — and never cite a prior revision, a reviewer, or a decision's provenance. The same applies to okstra's own vocabulary: `task-group`, `implementation-planning`, a `taskType` printed as a Status, a sibling task-id nobody outside the run can look up. Every enum the schedule prints is either defined on the page or replaced by words — the `Kind` / `Direction` labels on the risk and dependency tables classify rows for the plan's author and tell an implementer nothing.
+
+**Stage titles and every table cell are written in the schedule's prose language.** Headings and field labels stay English literals; the content beside them does not. A Work Breakdown whose `Title` column is English next to a `Steps` table in Korean makes the reader switch languages inside one block. The selection contract carries the same titles the schedule prints, so the two stay comparable.
+
+**A stage block is `Steps` plus `Exit criteria`, and nothing else.** The `Steps` table comes from `stepwiseExecution` — one row per step with what it does (keep the leading `RED:` / `GREEN:` marker), the files it touches, and what the executor should see when it succeeds, from that step's `expected`. `Exit criteria` is one line from `exitContract` saying when the stage is finished.
+
+Do not render `sliceValue` — it argues why the plan sliced the work this way, which is a reviewer's question, not an implementer's. Do not render `acceptance` alongside `exitContract`: they restate each other. Measured on one real plan, `acceptance`'s four claims all reappeared in `exitContract`, which then added two more. Sort `Verification Commands` `pre` → `mid` → `post` and introduce those three values above the table — source order interleaves them, and a reader working down the table would run a precondition after the checks it gates.
+
+**Transcribing means the content, never the source row's `id`.** `VC-001`, `RB-003`, `XP-001`, `DM-002`, `EO-015` and their kin index a report the schedule's reader cannot open, so the self-contained rule rejects them and the validator enforces it. Drop the id column, and where a row's body cites a sibling code, replace the citation with the thing it names ("the boot probe asserts all 29 keys", not "VC-006").
 
 ### Step 5: Gantt decision (render by default)
 
-`## Gantt Chart` is **rendered by default** — skip ONLY when literally no day signal exists (every task is effort=XXL with no visible decomposition, or all tasks lack both effort sizing and decomposition). Render whenever any of these hold: 2+ tasks with effort sizing; 1 task whose effort yields a range (mid-point bar, or `lo`/`hi` two-bar form); 1 task with Part/Phase/Step decomposition in the source (bars at decomposition-unit level); total estimated effort ≥ 3 days. When per-unit day allocations aren't itemized, split the parent range across the visible units yourself and append the `est` annotation (or add `> Per-day allocation is an estimate; refresh recommended after blocking items are resolved.`). "Range is wide", "single task", "user decisions pending" are NOT skip reasons — render an estimate-tagged chart instead.
+`## Gantt Chart` is **rendered by default** — skip ONLY when literally no day signal exists (every in-scope task lacks both effort sizing and stage decomposition). An XXL task is not a skip reason: it is sized by its stages. Render whenever any of these hold: 2+ tasks with effort sizing; 1 task whose effort yields a range (mid-point bar, or `lo`/`hi` two-bar form); 1 task with Part/Phase/Step decomposition in the source (bars at decomposition-unit level); total estimated effort ≥ 3 days. When per-unit day allocations aren't itemized, split the parent range across the visible units yourself and append the `est` annotation (or add `> Per-day allocation is an estimate; refresh recommended after blocking items are resolved.`). "Range is wide", "single task", "user decisions pending" are NOT skip reasons — render an estimate-tagged chart instead.
+
+When the source is a Stage Map, the Gantt bars are selected stages. A row is labelled `Stage <n>` when exactly one task is scheduled, and `<TASK-ID> Stage <n>` when more than one is. Spell the stage out — `S1` costs the reader a lookup and saves five characters. A row is a label and a bar and nothing else: no `days=` annotation (the Work Breakdown owns those numbers, and the validator compares the bar against that column), and no per-row `! crit` / `est` markers, which distinguish nothing when every row carries them. One line above the fence states the column unit and what `█` and `░` mean — that is the whole legend, because those two glyphs are the only notation left. Split the task effort range proportionally by `step_count`; round every stage except the last to 0.5 day and let the last stage absorb the remainder. Cross-stage dependency annotations follow `depends_on`. Already-done and non-selected stages never get a bar. A task tagged `[NEEDS-PLANNING]` contributes no bars.
+
+**Bar geometry is checked, not decorative.** One column is half a day: a bar runs `lower / 0.5` filled cells `█` then `(upper - lower) / 0.5` open cells `░`. A bar drawn to any other width is a validation error, as is an axis whose last tick overshoots the scheduled work by 5 days or more.
+
+**Every controlled code the schedule prints must be defined on the page.** The template's `### Priority & Risk Scale` resolves `P0`–`P3` and `Very Low`–`High`; the validator requires that subsection and both header literals. Stage labels are spelled out for the same reason — Gantt rows read `Stage 3`, and `Depends On` cells read `None` / `Stage 2` / `Stage 1 (done)` rather than a bare number the reader has to match against the Stage column of the same table. A reader who never saw the source report cannot rank `P0` against `P1`, calibrate `High`, or expand `S3`; those are opaque codes wearing a friendlier shape.
 
-When the source is a Stage Map, the Gantt bars are selected stages. Every row identifier is `<TASK-ID>/S<stage-number>` and carries `days=<lower>~<upper>` matching the Work Breakdown row. Split the task effort range proportionally by `step_count`; round every stage except the last to 0.5 day and let the last stage absorb the remainder. Cross-stage dependency annotations follow `depends_on`. Already-done and non-selected stages never get a bar. A task tagged `[NEEDS-PLANNING]` contributes no bars.
+**`## Task Dependency Graph` is optional and carries cross-task edges only.** Stage order already lives in the Work Breakdown's `Depends On` column; drawing it again as an arrow list makes the reader cross-reference one table against another to learn nothing new. Omit the section entirely — heading included — when no task depends on another, which is always true of a single-task schedule. A heading whose body only redirects to another table is noise, the same defect as a priority table that restates At a Glance.
 
 An unrepresentable half-day allocation is a validation error. Do not switch to a fallback allocation algorithm or publish that draft.
 
@@ -182,7 +198,16 @@ When you do skip, insert in the section's position exactly: `> _Gantt Chart skip
 ```
 
 3. **Run the deterministic gate first.** Execute `python3 ~/.okstra/lib/validators/validate-schedule.py <draft> --selection-json <selection>`. Do not dispatch the narrative verifier when this exits non-zero.
-4. **Run the independent LLM verifier second.** Only after the deterministic gate passes, dispatch an independent verifier subagent with the draft and selection JSON, but without the lead's reasoning. It checks client-facing coherence, phase rationale, executable ordering, engineering-only scope, and whether the prose contradicts the structured schedule. It returns `pass` plus concrete findings.
+4. **Run the independent LLM verifier second.** Only after the deterministic gate passes, dispatch an independent verifier subagent with the draft and selection JSON, but without the lead's reasoning. It returns `pass` plus concrete findings. Give it these checks:
+   - **Executable ordering** — stage sequence, `Depends On`, and Gantt bar positions tell the same story; nothing depends on something scheduled after it.
+   - **Arithmetic** — the Work Breakdown `Days` column sums to the At a Glance `Days` cell and to the `Effort sum` line.
+   - **Engineering-only scope** — no approval gate, permission check, stakeholder alignment or decision checklist.
+   - **Prose vs structure** — the narrative does not contradict the tables.
+   - **No assumed background.** Flag any sentence that only parses if the reader watched the plan being argued: a cited objection, a prior revision, "the reporter's rationale", a decision's provenance. Flag okstra's own vocabulary reaching the page — `task-group`, a `taskType` printed as a status, a task-id nobody outside the run can look up — and any enum printed without being defined on the page.
+   - **Written for the executor.** Each step says what to do and what the executor should see; a step that only explains why the plan chose this shape is a finding.
+   - **One language.** Table cells and stage titles follow the schedule's prose language; only headings and field labels stay English literals.
+
+   These last three are the checks no validator can make. Do not accept a `pass` that skipped them.
 5. **Revise from the first gate after every change.** If either gate requests a change, the lead revises the same draft in place, then starts again at the deterministic `--selection-json` gate. Allow **Max 2 revise cycles** total across both gates.
 6. **Gate publication.** Only the same draft that passes both gates may be promoted in Step 6. If it still fails after the second revision, do not write the final file; remove the paired staging artifacts and report the residual findings in Korean.
 
@@ -230,5 +255,5 @@ Reached only after both Step 5.5 gates return `pass`. Promote the verified same
 
 - All user-facing messages in Korean; schedule body prose Korean, identifiers/headings/field labels English (template literals).
 - Use project-relative paths in completion messages.
-- Use `<taskType> / <currentPhase>` (not `workStatus`) for each detail `Status`; `workStatus` only filters candidates.
+- Each detail `Status` is derived from `taskType` and `workflow.currentPhase` but written in plain words; `workStatus` only filters candidates and is never printed.
 - Per-task section Work Breakdown rows are **selected stages**, not free-form items; done stages are summarized, never scheduled forward.

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

@@ -14,6 +14,14 @@ approved: {{ "true" if frontmatter.approved else "false" }}
 implementation-option: {{ frontmatter.implementationOption | default("") | yaml_scalar }}
 schema-version: {{ schemaVersion | yaml_scalar }}
 ---
+{#
+  The spine renders these by hand or leaves them to the human HTML, so the
+  closing `md_rest("")` sweep must not repeat them: `frontmatter` and `header`
+  appear above, `humanSummary` is the HTML's own narrative, and `verdictCard`
+  is a non-authoritative index of `finalVerdict`, which §Final Verdict already
+  carries in full.
+-#}
+{{ md_claim("schemaVersion", "meta", "frontmatter", "header", "humanSummary", "verdictCard") }}
 
 # {{ frontmatter.title }}
 
@@ -33,34 +41,90 @@ schema-version: {{ schemaVersion | yaml_scalar }}
 - Blocking IDs: {{ aiBlockingIds | join(", ") if aiBlockingIds else "none" }}
 - Next step: {{ finalVerdict.nextStep }}
 
-### Decision Context
+## Decision Context
 
-{{ aiDecisionContext | json_block }}
+### Final Verdict
 
-### Next Task Contract
+{{ md("finalVerdict", 4) }}
 
-{{ aiRoutingContract | json_block }}
+### Summary
+
+{{ md("summary", 4) }}
+
+### Rationale
+
+{{ md("rationale", 4) }}
+{% if md_has("ticketCoverage") %}
+
+### Ticket Coverage
+
+{{ md("ticketCoverage", 4) }}
+{% endif %}
+
+## Next Task Contract
+
+### Recommended Next Steps
+
+{{ md("recommendedNextSteps", 4) }}
+
+### Follow-up Tasks
+
+{{ md("followUpTasks", 4) }}
 
 ## Clarification and User Decisions
 
-{{ clarificationItems | json_block }}
+{{ md("clarificationItems", 3) }}
+{% if md_has("clarificationCarryIn") %}
+
+### Clarification Carried In
+
+{{ md("clarificationCarryIn", 4) }}
+{% endif %}
 
 ## Evidence Ledger
 
-{{ aiEvidenceLedger | json_block }}
+### Evidence
+
+{{ md("evidence", 4) }}
+
+### Missing Information
+
+{{ md("missingInformation", 4) }}
+
+### End-State Coverage
+
+{{ md("endStateCoverage", 4) }}
+{% if md_has("analysisCommon") %}
+
+### Analysis Common
+
+{{ md("analysisCommon", 4) }}
+{% endif %}
 
 ## Task Deliverable: {{ aiTaskDeliverableTitle }}
+{% if aiTaskTemplate %}
+
+{% include aiTaskTemplate %}
+{% else %}
 
-{{ aiTaskDeliverable | json_block }}
+{{ md_rest(aiTaskProperty, 3) }}
+{% endif %}
 
 ## Cross Verification Audit
 
-{{ crossVerification | json_block }}
+{{ md("crossVerification", 3) }}
 
 ## Execution Audit
 
-{{ executionStatus | json_block }}
+{{ md("executionStatus", 3) }}
 
 ## Token and Cost Audit
 
-{{ tokenUsage | json_block }}
+{{ md("tokenUsage", 3) }}
+{% set trailing = md_rest("", 3) %}
+{% if trailing %}
+
+## Additional Report Data
+
+{{ trailing }}
+{% endif %}

package/runtime/templates/reports/md/macros/sections.md

@@ -0,0 +1,19 @@
+{#
+  Task-body section helper.
+
+  The report spine renders its own fixed sections unconditionally — an empty
+  `Missing Information` there is a positive statement. A task body is
+  variable-shaped instead: most of its fields are schema-optional, so a heading
+  over `_none_` would be noise rather than news. `section` therefore emits
+  nothing at all when the path carries no value.
+
+  Import `with context`, otherwise the `md` / `md_has` globals the renderer
+  binds are not visible inside the macro.
+-#}
+{% macro section(path, title, level=3) -%}
+{% if md_has(path) %}
+{{ "#" * level }} {{ title }}
+
+{{ md(path, level + 1) }}
+{% endif %}
+{%- endmacro %}

package/runtime/templates/reports/md/tasks/change-impact-analysis.template.md

@@ -0,0 +1,18 @@
+{% import "md/macros/sections.md" as s with context -%}
+{#
+  Reading order for the phase that plans this change: what is being asked, what
+  must not move, what the change reaches, and what the planner needs carried
+  forward. Unaffected boundaries sit next to the blast radius because the pair
+  is what bounds the change.
+-#}
+{{ s.section("changeImpactAnalysis.changeRequest", "Change Request") }}
+{{ s.section("changeImpactAnalysis.preservedBehaviors", "Preserved Behaviors") }}
+{{ s.section("changeImpactAnalysis.impactItems", "Impact Items") }}
+{{ s.section("changeImpactAnalysis.dependencyBlastRadius", "Dependency Blast Radius") }}
+{{ s.section("changeImpactAnalysis.unaffectedBoundaries", "Unaffected Boundaries") }}
+{{ s.section("changeImpactAnalysis.compatibilityImpact", "Compatibility Impact") }}
+{{ s.section("changeImpactAnalysis.migrationImpact", "Migration Impact") }}
+{{ s.section("changeImpactAnalysis.rollbackImpact", "Rollback Impact") }}
+{{ s.section("changeImpactAnalysis.securityAndPerformanceImpact", "Security and Performance Impact") }}
+{{ s.section("changeImpactAnalysis.planningInputs", "Planning Inputs") }}
+{{ md_rest("changeImpactAnalysis", 3) }}

package/runtime/templates/reports/md/tasks/error-analysis.template.md

@@ -0,0 +1,13 @@
+{% import "md/macros/sections.md" as s with context -%}
+{#
+  Reading order for the agent that fixes this: the symptom as reported, what is
+  observably failing, how to reproduce it, the ranked causes with what would
+  disprove each, and the next probe to run.
+-#}
+{{ s.section("errorAnalysis.symptomVerbatim", "Symptom Verbatim") }}
+{{ s.section("errorAnalysis.observableFailure", "Observable Failure") }}
+{{ s.section("errorAnalysis.reproduction", "Reproduction") }}
+{{ s.section("errorAnalysis.causeCandidates", "Cause Candidates") }}
+{{ s.section("errorAnalysis.nextDiagnostic", "Next Diagnostic") }}
+{{ s.section("errorAnalysis.routing", "Routing") }}
+{{ md_rest("errorAnalysis", 3) }}

package/runtime/templates/reports/md/tasks/feature-analysis.template.md

@@ -0,0 +1,13 @@
+{% import "md/macros/sections.md" as s with context -%}
+{#
+  Reading order for an agent about to change this feature: what the feature is,
+  how it runs, the rules it must keep, what it writes, and what already covers
+  it in tests.
+-#}
+{{ s.section("featureAnalysis.target", "Target") }}
+{{ s.section("featureAnalysis.flows", "Flows") }}
+{{ s.section("featureAnalysis.domainRules", "Domain Rules") }}
+{{ s.section("featureAnalysis.stateChanges", "State Changes") }}
+{{ s.section("featureAnalysis.externalInteractions", "External Interactions") }}
+{{ s.section("featureAnalysis.testCoverage", "Test Coverage") }}
+{{ md_rest("featureAnalysis", 3) }}

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

@@ -0,0 +1,13 @@
+{% import "md/macros/sections.md" as s with context -%}
+{#
+  Reading order for whoever decides whether this ships: what blocks acceptance,
+  what proves the rest passed, and what risk survives a pass.
+-#}
+{{ s.section("finalVerification.acceptanceBlockers", "Acceptance Blockers") }}
+{{ s.section("finalVerification.validationEvidence", "Validation Evidence") }}
+{{ s.section("finalVerification.residualRisk", "Residual Risk") }}
+{{ s.section("finalVerification.manualUserTest", "Manual User Test") }}
+{{ s.section("finalVerification.sourceImplementationReport", "Source Implementation Report") }}
+{{ s.section("finalVerification.stageReports", "Stage Reports") }}
+{{ s.section("finalVerification.routingRecommendation", "Routing Recommendation") }}
+{{ md_rest("finalVerification", 3) }}

package/runtime/templates/reports/md/tasks/implementation-planning.template.md

@@ -0,0 +1,15 @@
+{% import "md/macros/sections.md" as s with context -%}
+{#
+  Reading order for the agent that executes this plan: what was chosen, the
+  stages it is cut into, how to run each one, and how to tell a stage is done.
+  Option candidates and the trade-off matrix answer "why this one" and sit
+  after that, in the closing sweep.
+-#}
+{{ s.section("implementationPlanning.recommendedOption", "Recommended Option") }}
+{{ s.section("implementationPlanning.stageMap", "Stage Map") }}
+{{ s.section("implementationPlanning.stages", "Stages") }}
+{{ s.section("implementationPlanning.stepwiseExecution", "Stepwise Execution") }}
+{{ s.section("implementationPlanning.validationChecklist", "Validation Checklist") }}
+{{ s.section("implementationPlanning.rollbackStrategy", "Rollback Strategy") }}
+{{ s.section("implementationPlanning.requirementCoverage", "Requirement Coverage") }}
+{{ md_rest("implementationPlanning", 3) }}

package/runtime/templates/reports/md/tasks/implementation.template.md

@@ -0,0 +1,15 @@
+{% import "md/macros/sections.md" as s with context -%}
+{#
+  Reading order for the verifier that picks this stage up: what the plan asked
+  for, what actually landed, what proves it, and what the implementer knows is
+  still open.
+-#}
+{{ s.section("implementation.approvedPlanReference", "Approved Plan Reference") }}
+{{ s.section("implementation.diffSummary", "Diff Summary") }}
+{{ s.section("implementation.commitList", "Commit List") }}
+{{ s.section("implementation.requirementCoverage", "Requirement Coverage") }}
+{{ s.section("implementation.validationEvidence", "Validation Evidence") }}
+{{ s.section("implementation.outOfPlanEdits", "Out-of-Plan Edits") }}
+{{ s.section("implementation.manualUserTest", "Manual User Test") }}
+{{ s.section("implementation.routingRecommendation", "Routing Recommendation") }}
+{{ md_rest("implementation", 3) }}

package/runtime/templates/reports/md/tasks/improvement-discovery.template.md

@@ -0,0 +1,10 @@
+{% import "md/macros/sections.md" as s with context -%}
+{#
+  Reading order for whoever picks work off this sidetrack: the candidates
+  themselves, then the lens coverage that says which angles were actually swept
+  and which were not.
+-#}
+{{ s.section("improvementDiscovery.candidates", "Candidates") }}
+{{ s.section("improvementDiscovery.lensCoverage", "Lens Coverage") }}
+{{ s.section("improvementDiscovery.selectionLimit", "Selection Limit") }}
+{{ md_rest("improvementDiscovery", 3) }}

package/runtime/templates/reports/md/tasks/project-analysis.template.md

@@ -0,0 +1,15 @@
+{% import "md/macros/sections.md" as s with context -%}
+{#
+  Reading order for an agent orienting in an unfamiliar repository: the feature
+  index and entry points first, because they are how it finds anything, then the
+  component map, then where the risk and the coverage gaps are.
+-#}
+{{ s.section("projectAnalysis.featureIndex", "Feature Index") }}
+{{ s.section("projectAnalysis.entryPoints", "Entry Points") }}
+{{ s.section("projectAnalysis.components", "Components") }}
+{{ s.section("projectAnalysis.dataStores", "Data Stores") }}
+{{ s.section("projectAnalysis.externalSystems", "External Systems") }}
+{{ s.section("projectAnalysis.rankedHotspots", "Ranked Hotspots") }}
+{{ s.section("projectAnalysis.qualityCoverage", "Quality Coverage") }}
+{{ s.section("projectAnalysis.scanCoverage", "Scan Coverage") }}
+{{ md_rest("projectAnalysis", 3) }}

package/runtime/templates/reports/md/tasks/release-handoff.template.md

@@ -0,0 +1,13 @@
+{% import "md/macros/sections.md" as s with context -%}
+{#
+  Reading order for whoever picks the release up: what was handed off, what the
+  branch and PR ended up as, and whether a merge would conflict.
+-#}
+{{ s.section("releaseHandoff.handoffScope", "Handoff Scope") }}
+{{ s.section("releaseHandoff.userSelections", "User Selections") }}
+{{ s.section("releaseHandoff.featureBranchState", "Feature Branch State") }}
+{{ s.section("releaseHandoff.pullRequestOutcome", "Pull Request Outcome") }}
+{{ s.section("releaseHandoff.mergeConflictProbe", "Merge Conflict Probe") }}
+{{ s.section("releaseHandoff.executedCommands", "Executed Commands") }}
+{{ s.section("releaseHandoff.routingRecommendation", "Routing Recommendation") }}
+{{ md_rest("releaseHandoff", 3) }}

package/runtime/templates/reports/md/tasks/requirements-discovery.template.md

@@ -0,0 +1,15 @@
+{% import "md/macros/sections.md" as s with context -%}
+{#
+  Reading order for the phase that plans from these requirements: what the user
+  asked verbatim, how the system read it, and which requirements are settled
+  versus still open. The verbatim request leads because every later reading is
+  judged against it.
+-#}
+{{ s.section("requirementsDiscovery.requestVerbatim", "Request Verbatim") }}
+{{ s.section("requirementsDiscovery.systemInterpretation", "System Interpretation") }}
+{{ s.section("requirementsDiscovery.classification", "Classification") }}
+{{ s.section("requirementsDiscovery.confirmedRequirements", "Confirmed Requirements") }}
+{{ s.section("requirementsDiscovery.unresolvedRequirements", "Unresolved Requirements") }}
+{{ s.section("requirementsDiscovery.rejectionCriteria", "Rejection Criteria") }}
+{{ s.section("requirementsDiscovery.routing", "Routing") }}
+{{ md_rest("requirementsDiscovery", 3) }}