okstra 0.156.0 → 0.157.0

package/docs/architecture.md

@@ -737,7 +737,9 @@ Resume decision rules:
 
 New task bundles use `schemas/final-report-v2.0.schema.json` as the final-report data contract. The report writer authors one data.json source of truth, including the required `humanSummary` and exactly one task-type deliverable. Two renderers consume it independently:
 
-- `templates/reports/final-report-v2.template.md` produces compact AI handoff Markdown in a fixed order: handoff summary, clarifications, evidence ledger, one task deliverable, cross-verification audit, execution audit, and token/cost audit. Human narrative fields are excluded from this artifact.
+- `templates/reports/final-report-v2.template.md` produces the AI handoff Markdown spine in a fixed order: handoff summary, decision context, next-task contract, clarifications, evidence ledger, one task deliverable, cross-verification audit, execution audit, and token/cost audit. The task deliverable body comes from `templates/reports/md/tasks/<task-type>.template.md`, the Markdown sibling of the HTML task template below. Human narrative fields are excluded from this artifact.
+  - Section bodies are rendered as Markdown — headings, tables for uniform row sets, prose for narrative fields — by `scripts/okstra_ctl/report_markdown.py`, never serialized as JSON. Field order within a section comes from `schemas/final-report-v2.0.schema.json`, whose properties are authored in reading order (a decision draft reads `context → decision → consequences`).
+  - Each task template names the sections a reading agent should meet first and closes with a `md_rest()` sweep, so a field added to the schema reaches the Markdown without a template edit. **Enforced:** `tests/contract/test_ai_markdown_rendering.py`.
 - `templates/reports/html/tasks/<task-type>.template.html` produces the task-specific human-facing HTML. It leads with a plain-language decision summary and presents the selected task's findings, diagrams, tables, evidence, and actions. Worker execution and convergence detail stays in a visually subordinate audit section.
 
 The legacy schema v1 contract remains supported by `schemas/final-report-v1.0.schema.json` and `templates/reports/final-report.template.md`. Its Markdown structure is:

package/docs/for-ai/skills/okstra-schedule-gen.md

@@ -191,11 +191,11 @@ An unrepresentable half-day allocation is a validation error. Do not substitute
 Render a plain fenced relative-day Gantt when the selected stages have finite day ranges. Every forward row is identified by stage and repeats its Work Breakdown range:
 
 ```text
-DEV-1/S2  ████      days=2.0~3.0
-DEV-1/S3      ████  days=1.0~2.0
+DEV-1 Stage 2  ████      days=2.0~3.0
+DEV-1 Stage 3      ████  days=1.0~2.0
 ```
 
-The identifier format is `<TASK-ID>/S<stage-number>` and the annotation is `days=<lower>~<upper>`. Do not emit a row for a completed, unselected, missing, or unknown stage. Bar length is illustrative; `days=` is the validated duration contract.
+A row is labelled `Stage <n>` when exactly one task is scheduled and `<TASK-ID> Stage <n>` when more than one is; the annotation is `days=<lower>~<upper>`. Spell the stage out — `S1` is an opaque code that costs the reader a lookup and saves five characters. Do not emit a row for a completed, unselected, missing, or unknown stage. Bar length is arithmetic: one column is half a day, so a bar runs `lower / 0.5` filled cells `█` then `(upper - lower) / 0.5` open cells `░`.
 
 Skip the chart only when no forward task has a finite day signal, and state the concrete reason. Do not use calendar dates, Mermaid, PlantUML, Graphviz, or another graph language.
 
@@ -233,7 +233,8 @@ After both gates pass:
 - Guessing a planning report after `stage-map` reports a structured error.
 - Treating `workStatus` as the detailed schedule status.
 - Scheduling completed or non-selected stages.
-- Publishing a task-level Gantt row without the `/S<stage-number>` suffix and `days=` range.
+- Publishing a Gantt row without its `Stage <n>` label and `days=` range, or abbreviating that label to `S<n>`.
+- Drawing stage order in `## Task Dependency Graph` — that graph carries cross-task edges only; stage order lives in the Work Breakdown's `Depends On` column.
 - Dispatching narrative validation before deterministic `--selection-json` validation.
 - Re-rendering after validation instead of promoting the same draft.
 - Deleting the selection contract before final validation.

package/docs/project-structure-overview.md

@@ -261,6 +261,7 @@ Important modules:
 | `conformance.py` | validates task-level Tier 3 manifests, parses `QA-RESULT`, detects diff capability surfaces, and reduces results to PASS/ADVISORY/BLOCKING; DB/HTTP/external non-PASS is user-owned advisory while local IO and contract defects remain blocking, enforced by `scripts/okstra_ctl/conformance.py::decide_conformance_gate` and `validators/validate-run.py::_validate_conformance` |
 | `pr_template.py` | PR body template resolution for release-handoff |
 | `report_views.py`, `render_final_report.py`, `final_report_schema.py` | Versioned final-report contract: schema v2 data independently produces AI handoff Markdown and human HTML; schema v1 keeps the legacy Markdown/view pipeline |
+| `report_markdown.py` | Schema-ordered Markdown serialisation of a data.json subtree for the AI handoff report — headings, tables for uniform row sets, prose for narrative fields; field order read from the schema, not from the mapping |
 | `final_report_paths.py`, `report_view_artifacts.py` | Path-helper SSOT for the final-report markdown/data.json pair and the generated view artifacts (HTML view, user-responses directory) |
 | `wizard.py` | `okstra-run` prompt state machine; user-facing Korean strings live in `prompts/wizard/prompts.ko.json` |
 | `wizard_stage_intent.py` | stage-related intent projection of the `okstra-run` wizard output — normalizes whole-task (`__whole_task__`) vs single/multi stage selection into render-args (`resolve_wizard_stage_intent`) |
@@ -352,7 +353,8 @@ Token/cost accounting:
 | Path | Role |
 |---|---|
 | `templates/reports/final-report.template.md` | Schema v1 compatibility Markdown template |
-| `templates/reports/final-report-v2.template.md` | Compact schema v2 AI handoff Markdown template |
+| `templates/reports/final-report-v2.template.md` | Schema v2 AI handoff Markdown spine |
+| `templates/reports/md/tasks/*.template.md`, `md/macros/sections.md` | Ten dedicated task bodies for the AI handoff Markdown, sibling of `html/tasks/`; shared section macro |
 | `templates/reports/html/base.template.html`, `html/tasks/*.template.html` | Shared HTML shell plus ten dedicated task templates for human reports; task bodies are not shared |
 | `templates/reports/report.css`, `report.js` | Inline assets for self-contained HTML report views |
 | `templates/reports/*.template.md` | Inputs, schedule, user-response, settings templates |
@@ -431,6 +433,10 @@ The neutral lead lifecycle contract lives at `prompts/lead/okstra-lead-contract.
 
 - `tests/`: pytest modules, layered into per-domain subfolders — `run/` (prepare/dispatch/run-index core), `contract/` (validator, repo/docs contract, phase rules, profile), `report/` (render, convergence, language, template), `inspect/` (recap, error, context-cost, token-usage), `worktree/` (worktree, stage isolation, reconcile, reclaim), `wizard/`, `handoff/`. The shared path SSOT is `tests/_paths.py` (`REPO_ROOT`/`TESTS_DIR`/`FIXTURES`), and the setting that puts `tests/` on the import path is the repo-root `pytest.ini` (`pythonpath = tests`). Fixtures live in `tests/fixtures/`.
 - `tests-e2e/`: `scenario-<id>-<name>.sh` shell scenarios (record-start/reconcile, rerun, task lock, agent install, report view, etc.).
+- Each behavior branch has one owning test at the lowest practical layer.
+- An end-to-end scenario must cross the public CLI or installed-runtime boundary.
+- Tests replace operating-system resources and wall-clock waits with controlled doubles.
+- A higher-layer test keeps only the minimum positive flow needed to detect wiring failures.
 
 ### 4.13 `tools/korean-sources/`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.156.0",
+  "version": "0.157.0",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.156.0",
-  "builtAt": "2026-08-07T06:39:03.548Z",
+  "package": "0.157.0",
+  "builtAt": "2026-08-07T06:39:25.315Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/profiles/_common-contract.md

@@ -59,7 +59,7 @@ profile document.
   - Any decision in this run that contradicts the brief's `Source Material` must be raised back to the reporter via a `Clarification Items` row; it must NOT be silently overridden. Disagreement with the reporter is allowed only after the row is resolved.
   - This contract is the single authority on brief consumption. Phase-specific addenda may *tighten* these rules but may not relax them.
 - Clarification request policy (shared — applies whenever a profile uses `## 1. Clarification Items`):
-  - Schema-v2 final reports author `clarificationItems[]` in data.json; task-specific HTML renders the question and response controls directly from those IDs, and AI handoff Markdown serializes the same array for the next agent. The remaining table-layout rules describe schema-v1 compatibility and analysis-worker result tables only.
+  - Schema-v2 final reports author `clarificationItems[]` in data.json; task-specific HTML renders the question and response controls directly from those IDs, and AI handoff Markdown renders the same array as one headed section per row for the next agent. The remaining table-layout rules describe schema-v1 compatibility and analysis-worker result tables only.
   - **Legacy canonical column schema (must match `templates/reports/final-report.template.md` §1 exactly):** every `## 1. Clarification Items` table has exactly these 4 columns, in this order:
     `| <record-meta> | Statement | Expected form | User input |` (the first header is the i18n `columns.recordMeta` label — `Record`).
     The five short fields (ID, Ticket ID, Kind, Blocks, Status) are stacked inside the single record-meta cell, one per line separated by `<br>`, in this fixed order (mirrors the §2.1 Primary-Evidence meta column):

package/runtime/python/okstra_ctl/clarification_items.py

@@ -12,9 +12,9 @@ read functions take a report **path**, not its text:
 * schema-v1 — the ``## 1. Clarification Items`` markdown table (introduced
   when §4.5.9 / §5.1 / §5.2 collapsed into a single section).
 * schema-v2 — ``clarificationItems[]`` in the ``.data.json`` sibling. Its AI
-  handoff markdown serialises them as a JSON block under
-  ``## Clarification and User Decisions``, so the §1 table walk finds nothing
-  there by construction.
+  handoff markdown renders them as one section per row under
+  ``## Clarification and User Decisions``, not as a §1 table, so the §1 table
+  walk finds nothing there by construction.
 
 Every gate goes through ``scan_approval_gate`` / ``scan_open_user_input`` so
 run-prep (``_validate_approved_plan``), the wizard, and the user-response CLI

package/runtime/python/okstra_ctl/render_final_report.py

@@ -52,7 +52,8 @@ from okstra_ctl.final_report_schema import (
 from okstra_ctl.i18n import I18nError, SUPPORTED_LANGS, load_dictionary, make_jinja_global
 from okstra_ctl.md_table import UNESCAPED_PIPE_RE, to_cell_text
 from okstra_ctl.models import UnknownModelError, resolve_model_metadata
-from okstra_ctl.report_contract import TASK_TYPE_DATA_PROPERTY
+from okstra_ctl.report_contract import TASK_TYPE_DATA_PROPERTY, markdown_template_for
+from okstra_ctl.report_markdown import ReportSections
 from okstra_ctl.schema_excerpt import excerpt_cut_from_version
 from okstra_ctl.seeding import installed_version
 
@@ -474,9 +475,12 @@ def inject_index_into_file(md_path: Path) -> int:
     return len(injected.encode("utf-8"))
 
 
-def _enforce_schema(data: dict) -> None:
+def _enforce_schema(data: dict) -> dict | None:
     """렌더 전에 data.json 을 스키마에 대해 검증하는 seam.
 
+    검증에 쓴 스키마를 그대로 돌려준다 — v2 마크다운 렌더러가 필드 순서를
+    이 스키마에서 읽기 때문에, 같은 파일을 두 번 찾지 않는다.
+
     스키마 파일을 찾지 못하는 경우(손상된 설치 환경)는 경고만 출력하고 계속
     진행한다 — validate-run 과 install 경고가 이미 해당 상황을 표면화하므로
     Phase 7 재렌더를 hard-fail 시키는 것은 과도하다.
@@ -488,13 +492,14 @@ def _enforce_schema(data: dict) -> None:
             f"render-final-report: schema not locatable; skipping schema enforcement ({exc})",
             file=sys.stderr,
         )
-        return
+        return None
     errors = schema_validate(data, schema)
     if errors:
         raise FinalReportRenderError(
             f"final-report data.json fails schema validation ({len(errors)} error(s)): "
             + "; ".join(errors[:5])
         )
+    return schema
 
 
 # 일반 alias('opus'/'sonnet'/'haiku')가 런타임에 해소되는, okstra 가 아는 최신
@@ -556,7 +561,6 @@ def _build_environment(template_dir: Path) -> Environment:
     env.filters["yaml_scalar"] = _yaml_scalar
     env.filters["yaml_inline_list"] = _yaml_inline_list
     env.filters["model_detail"] = _model_detail
-    env.filters["json_block"] = _json_markdown_block
     # `mdcell` neutralises the two things in worker prose that can break a
     # markdown table row: a literal `|` (splits the row) and a newline
     # (truncates it, dropping every later column). Table-cell interpolations
@@ -571,50 +575,15 @@ def _build_environment(template_dir: Path) -> Environment:
     return env
 
 
-def _json_markdown_block(value: Any) -> str:
-    serialized = json.dumps(value, ensure_ascii=False, indent=2, sort_keys=True)
-    return "\n".join(f"    {line}" for line in serialized.splitlines())
-
-
-def _without_human_narrative(value: Any) -> Any:
-    if isinstance(value, dict):
-        return {
-            key: _without_human_narrative(item)
-            for key, item in value.items()
-            if key != "userNarrative"
-        }
-    if isinstance(value, list):
-        return [_without_human_narrative(item) for item in value]
-    return value
-
-
-def _ai_markdown_context(data: dict) -> dict:
+def _ai_markdown_context(data: dict, schema: dict | None) -> dict:
     context = _with_optional_defaults(data)
     header = data.get("header") if isinstance(data.get("header"), dict) else {}
     task_type = header.get("taskType", "")
-    property_name = TASK_TYPE_DATA_PROPERTY.get(task_type, "")
     context["aiTaskDeliverableTitle"] = TASK_DELIVERABLE_TITLES.get(
         task_type, task_type
     )
-    context["aiTaskDeliverable"] = _without_human_narrative(
-        data.get(property_name, {})
-    )
-    context["aiEvidenceLedger"] = {
-        "evidence": data.get("evidence", {}),
-        "missingInformation": data.get("missingInformation", []),
-        "endStateCoverage": data.get("endStateCoverage", []),
-        "analysisCommon": data.get("analysisCommon"),
-    }
-    context["aiRoutingContract"] = {
-        "recommendedNextSteps": data.get("recommendedNextSteps", []),
-        "followUpTasks": data.get("followUpTasks", []),
-    }
-    context["aiDecisionContext"] = {
-        "rationale": data.get("rationale", {}),
-        "summary": data.get("summary", []),
-        "ticketCoverage": data.get("ticketCoverage"),
-        "finalVerdict": data.get("finalVerdict", {}),
-    }
+    context["aiTaskProperty"] = TASK_TYPE_DATA_PROPERTY.get(task_type, "")
+    context["aiTaskTemplate"] = _markdown_task_template(task_type)
     context["aiBlockingIds"] = [
         row.get("id")
         for row in data.get("clarificationItems", [])
@@ -623,9 +592,27 @@ def _ai_markdown_context(data: dict) -> dict:
         and row.get("blocks") in {"approval", "next-phase"}
         and isinstance(row.get("id"), str)
     ]
+    sections = ReportSections(data, schema or {})
+    context["md"] = sections.section
+    context["md_rest"] = sections.rest
+    context["md_has"] = sections.has
+    context["md_claim"] = sections.mark_rendered
     return context
 
 
+def _markdown_task_template(task_type: str) -> str:
+    """The task body this report includes, or '' for an unknown task type.
+
+    An unknown type still renders the shared spine plus the generic sweep, so a
+    task type that reaches the renderer before its template exists produces a
+    complete report rather than a crash.
+    """
+    try:
+        return markdown_template_for(task_type)
+    except ValueError:
+        return ""
+
+
 # The Markdown is the AI handoff sibling of the data.json — same content, same
 # audience, so it renders in the SSOT's language and nothing else. The field
 # still has to be well-formed here because it decides whether Phase 7 pays for
@@ -700,7 +687,7 @@ def render(
     if not template_path.is_file():
         raise FinalReportRenderError(f"template not found: {template_path}")
 
-    _enforce_schema(data)
+    schema = _enforce_schema(data)
 
     lang = validate_report_language(data)
     try:
@@ -714,7 +701,7 @@ def render(
     try:
         template = env.get_template(template_path.name)
         context = (
-            _ai_markdown_context(data)
+            _ai_markdown_context(data, schema)
             if data.get("schemaVersion") == "2.0"
             else _with_optional_defaults(data)
         )

package/runtime/python/okstra_ctl/report_contract.py

@@ -36,6 +36,14 @@ TASK_TYPE_HTML_TEMPLATE = {
     for task_type in PUBLIC_REPORT_TASK_TYPES
 }
 
+# The AI handoff Markdown's task body, sibling of the human HTML template above.
+# Both are keyed off the same task-type list so a new task type cannot ship one
+# audience's view without the other.
+TASK_TYPE_MARKDOWN_TEMPLATE = {
+    task_type: f"md/tasks/{task_type}.template.md"
+    for task_type in PUBLIC_REPORT_TASK_TYPES
+}
+
 TASK_TYPE_REQUIRED_HUMAN_FIELDS = {
     "requirements-discovery": (
         "requirementsDiscovery.requestVerbatim",
@@ -122,3 +130,10 @@ def html_template_for(task_type: str) -> str:
         return TASK_TYPE_HTML_TEMPLATE[task_type]
     except KeyError as exc:
         raise ValueError(f"no task-specific html template for: {task_type}") from exc
+
+
+def markdown_template_for(task_type: str) -> str:
+    try:
+        return TASK_TYPE_MARKDOWN_TEMPLATE[task_type]
+    except KeyError as exc:
+        raise ValueError(f"no task-specific markdown template for: {task_type}") from exc