okstra 0.146.0 → 0.147.0

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

@@ -0,0 +1,36 @@
+{% extends "html/base.template.html" %}
+{% from "html/macros/layout.html" import narrative as render_narrative, summary_card %}
+{% from "html/macros/visualizations.html" import figure %}
+
+{% block human_content %}
+<section data-report-section="handoff-outcome">
+  <h2>인계 결과</h2>
+  {{ render_narrative(narrative.handoffOutcome, "releaseHandoff.userNarrative.handoffOutcome") }}
+  {{ figure(handoffFigure) }}
+</section>
+
+<section data-report-section="user-selection" data-report-field="releaseHandoff.userSelections">
+  <h2>사용자가 선택한 동작</h2>
+  <dl><dt>인계 방식</dt><dd>{{ handoff.userSelections.h1 }}</dd><dt>충돌 확인</dt><dd>{{ handoff.userSelections.h2b }}</dd><dt>PR 본문</dt><dd>{{ handoff.userSelections.h3 }}</dd></dl>
+</section>
+
+<section data-report-section="branch-and-pr" data-report-field="releaseHandoff.featureBranchState">
+  <h2>브랜치와 PR</h2>
+  {{ render_narrative(narrative.branchAndPrExplanation, "releaseHandoff.userNarrative.branchAndPrExplanation") }}
+  <p><strong>브랜치:</strong> {{ handoff.featureBranchState.branchName }}</p>
+  <p data-report-field="releaseHandoff.pullRequestOutcome"><strong>PR 결과:</strong> {{ handoff.pullRequestOutcome.kind }}{% if prUrl %} · <a href="{{ prUrl }}" rel="noopener noreferrer">Pull request 열기</a>{% endif %}</p>
+</section>
+
+<section data-report-section="conflicts" data-report-field="releaseHandoff.mergeConflictProbe">
+  <h2>충돌 판정</h2>
+  {{ render_narrative(narrative.conflictExplanation, "releaseHandoff.userNarrative.conflictExplanation") }}
+  {{ summary_card(handoff.mergeConflictProbe.kind, "기준 브랜치: " ~ (handoff.mergeConflictProbe.baseBranch | default('not-run'))) }}
+  {% if handoff.mergeConflictProbe.conflictingPaths %}<ul>{% for path in handoff.mergeConflictProbe.conflictingPaths %}<li>{{ path }}</li>{% endfor %}</ul>{% endif %}
+</section>
+
+<section data-report-section="next-action">
+  <h2>다음 행동</h2>
+  {{ render_narrative(narrative.nextAction, "releaseHandoff.userNarrative.nextAction") }}
+  <p>{{ handoff.routingRecommendation }}</p>
+</section>
+{% endblock %}

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

@@ -0,0 +1,37 @@
+{% extends "html/base.template.html" %}
+{% from "html/macros/layout.html" import narrative as render_narrative, action_list, summary_card %}
+{% from "html/macros/visualizations.html" import figure %}
+
+{% block human_content %}
+<section data-report-section="request">
+  <h2>요청 이해</h2>
+  {{ render_narrative(narrative.requestUnderstanding, "requirementsDiscovery.userNarrative.requestUnderstanding") }}
+  <h3>사용자 요청 원문</h3>
+  <p data-report-field="requirementsDiscovery.requestVerbatim">{{ requirements.requestVerbatim }}</p>
+  <h3>시스템 해석</h3>
+  <p data-report-field="requirementsDiscovery.systemInterpretation">{{ requirements.systemInterpretation }}</p>
+  <dl data-report-field="requirementsDiscovery.classification">{% for key, value in requirements.classification.items() %}<dt>{{ key }}</dt><dd>{{ value }}</dd>{% endfor %}</dl>
+</section>
+
+<section data-report-section="requirements">
+  <h2>확정 요구사항과 미확정 요구사항</h2>
+  {{ render_narrative(narrative.confirmedRequirements, "requirementsDiscovery.userNarrative.confirmedRequirements") }}
+  <div class="summary-grid" data-report-field="requirementsDiscovery.confirmedRequirements">{% for row in requirements.confirmedRequirements %}{{ summary_card(row.id ~ " · 확정", row.statement) }}{% endfor %}</div>
+  {{ render_narrative(narrative.unresolvedRequirements, "requirementsDiscovery.userNarrative.unresolvedRequirements") }}
+  <div class="summary-grid" data-report-field="requirementsDiscovery.unresolvedRequirements">{% for row in requirements.unresolvedRequirements %}{{ summary_card(row.id ~ " · 결정 필요", row.statement, "important") }}{% else %}<p>미확정 요구사항이 없습니다.</p>{% endfor %}</div>
+</section>
+
+<section data-report-section="routing">
+  <h2>다음 태스크와 의존성</h2>
+  {{ render_narrative(narrative.routingExplanation, "requirementsDiscovery.userNarrative.routingExplanation") }}
+  <p><strong>다음 태스크:</strong> {{ requirements.routing.nextTaskType }} · {{ requirements.routing.rationale }}</p>
+  {{ figure(routingFigure) }}
+  {% if not requirements.taskDependencies %}<p class="empty-state">이 요구사항 태스크는 다른 태스크에 의존하지 않는 단일 작업입니다.</p>{% endif %}
+</section>
+
+<section data-report-section="decisions">
+  <h2>사용자가 결정할 항목</h2>
+  <div class="summary-grid">{% for row in clarificationItems %}{{ summary_card(row.id ~ " · " ~ row.kind, row.statement, "important") }}{% else %}<p>추가 결정이 필요하지 않습니다.</p>{% endfor %}</div>
+  {{ action_list(humanSummary.actions) }}
+</section>
+{% endblock %}

package/runtime/validators/validate-report-views.py

@@ -23,6 +23,8 @@ per line to stderr.
 from __future__ import annotations
 
 import argparse
+import hashlib
+import json
 import re
 import sys
 from pathlib import Path
@@ -43,6 +45,8 @@ from okstra_ctl.report_views import (  # noqa: E402
     source_digest,
 )
 from okstra_ctl.report_view_artifacts import html_view_path  # noqa: E402
+from okstra_ctl.final_report_paths import final_report_data_path  # noqa: E402
+from okstra_ctl.report_contract import TASK_TYPE_REQUIRED_HUMAN_FIELDS  # noqa: E402
 
 
 _EXTERNAL_URL_RE = re.compile(
@@ -66,11 +70,86 @@ _ANALYSIS_REVIEW_STATUSES = ["accepted", "rejected", "revision-requested"]
 
 
 def _main_body(html_text: str) -> str:
-    start = html_text.find("<main>")
-    end = html_text.find("</main>", start) if start >= 0 else -1
-    if start < 0 or end < 0:
+    match = re.search(r"<main[^>]*>(?P<body>.*?)</main>", html_text, re.DOTALL)
+    if match is None:
         return html_text
-    return html_text[start + len("<main>"): end]
+    return match.group("body")
+
+
+def _sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _digest_from_run_meta(html_text: str, key: str) -> str:
+    match = re.search(rf'"{re.escape(key)}"\s*:\s*"([0-9a-f]{{64}})"', html_text)
+    return match.group(1) if match else ""
+
+
+def _load_v2_data(report_path: Path) -> tuple[Path, dict] | None:
+    data_path = final_report_data_path(report_path)
+    if not data_path.is_file():
+        return None
+    try:
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if isinstance(data, dict) and data.get("schemaVersion") == "2.0":
+        return data_path, data
+    return None
+
+
+def _validate_v2(report_path: Path, data_path: Path, data: dict) -> list[str]:
+    html_path = html_view_path(report_path)
+    if not html_path.is_file():
+        return [f"missing html artifact: {html_path}"]
+    html_text = html_path.read_text(encoding="utf-8")
+    main_body = _main_body(html_text)
+    failures: list[str] = []
+
+    for key, path in (
+        ("source-data-sha256", data_path),
+        ("source-md-sha256", report_path),
+    ):
+        recorded = _digest_from_run_meta(html_text, key)
+        expected = _sha256(path)
+        if not recorded:
+            failures.append(f"html missing {key} in run-meta")
+        elif recorded != expected:
+            failures.append(f"stale html: {key} does not match current source")
+
+    task_type = data.get("header", {}).get("taskType", "")
+    if f'data-task-template="{task_type}"' not in html_text:
+        failures.append(f"v2 html task template mismatch for {task_type}")
+    actual_fields = set(re.findall(r'data-report-field="([^"]+)"', main_body))
+    for field in TASK_TYPE_REQUIRED_HUMAN_FIELDS.get(task_type, ()):
+        if field not in actual_fields:
+            failures.append(f"missing human field: {field}")
+
+    if "data-audit-field=" in main_body:
+        failures.append("audit field inside human main")
+    node_ids = set(re.findall(r'data-node-id="([^"]+)"', html_text))
+    fallback_ids = set(re.findall(r'data-fallback-id="([^"]+)"', html_text))
+    if node_ids != fallback_ids:
+        failures.append(
+            f"visualization ID mismatch: svg={sorted(node_ids)}, fallback={sorted(fallback_ids)}"
+        )
+
+    data_ids = []
+    for row in data.get("clarificationItems", []):
+        if not isinstance(row, dict):
+            continue
+        response_id = row.get("id")
+        if isinstance(response_id, str) and re.fullmatch(r"C-\d+", response_id):
+            data_ids.append(response_id)
+    data_ids.sort()
+    html_ids = sorted(set(_RESPONSE_ID_ATTR_RE.findall(html_text)))
+    if data_ids != html_ids:
+        failures.append(
+            f"Response ID mismatch: data.json has {data_ids}, HTML has {html_ids}"
+        )
+    if _EXTERNAL_URL_RE.search(html_text):
+        failures.append("html contains external URL in script/link/img — must be self-contained")
+    return failures
 
 
 def _no_form_sections(html_body: str) -> list[str]:
@@ -128,6 +207,9 @@ def validate(report_path: Path) -> list[str]:
         return [f"final-report not found: {report_path}"]
 
     md = report_path.read_text(encoding="utf-8")
+    v2 = _load_v2_data(report_path)
+    if v2 is not None:
+        return _validate_v2(report_path, v2[0], v2[1])
     html_path = html_view_path(report_path)
     # §1 헤딩이 있는데 파싱이 실패하면 md_ids 가 빈 []이 되어 "clarification 없음
     # → skip" 으로 흘러 HTML form parity 게이트가 조용히 열린다. fail-closed.

package/runtime/validators/validate-run.py

@@ -30,12 +30,12 @@ for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "
 try:
     from okstra_ctl.final_report_schema import (
         SchemaError,
-        load_schema,
+        load_schema_for_data,
         validate as schema_validate,
     )
 except ImportError:  # pragma: no cover — runtime guarantees this import
     SchemaError = None  # type: ignore[assignment]
-    load_schema = None  # type: ignore[assignment]
+    load_schema_for_data = None  # type: ignore[assignment]
     schema_validate = None  # type: ignore[assignment]
 
 from okstra_project import project_json_path  # noqa: E402
@@ -1021,6 +1021,48 @@ def _scan_token_usage_summary(
 # a section heading line (not as inline text inside a paragraph or table).
 _VERDICT_CARD_HEADING_RE = re.compile(r"^##[ \t]+Verdict Card\b", re.MULTILINE)
 
+_V2_AI_HANDOFF_HEADINGS = (
+    "## AI Handoff Summary",
+    "## Clarification and User Decisions",
+    "## Evidence Ledger",
+    "## Task Deliverable:",
+    "## Cross Verification Audit",
+    "## Execution Audit",
+    "## Token and Cost Audit",
+)
+
+
+def _validate_v2_ai_handoff(content: str, failures: list[str]) -> None:
+    positions: list[int] = []
+    for heading in _V2_AI_HANDOFF_HEADINGS:
+        count = content.count(heading)
+        if count != 1:
+            failures.append(
+                "schema-v2 AI handoff markdown requires exactly one "
+                f"`{heading}` heading; found {count}."
+            )
+            continue
+        positions.append(content.index(heading))
+    if len(positions) == len(_V2_AI_HANDOFF_HEADINGS) and positions != sorted(
+        positions
+    ):
+        failures.append(
+            "schema-v2 AI handoff markdown heading order does not match "
+            "templates/reports/final-report-v2.template.md."
+        )
+    for human_only_field in ('"humanSummary"', '"userNarrative"'):
+        if human_only_field in content:
+            failures.append(
+                "schema-v2 AI handoff markdown contains human-only field "
+                f"{human_only_field}; render it only in the task-specific HTML."
+            )
+    if _READING_CONFIRMATION_HEADING_RE.search(content) is not None:
+        failures.append(
+            "final report contains a `## 0. Reading Confirmation` heading — "
+            "Reading Confirmation lives in the worker audit sidecar, never "
+            "in the AI handoff markdown."
+        )
+
 # Top-of-report Index block. The renderer
 # (scripts/okstra_ctl/render_final_report.py) injects `<a id="report-index">`
 # into the index heading; a missing anchor means the markdown was produced
@@ -2229,6 +2271,10 @@ def validate_report(
                 "run `okstra-token-usage.py ... --substitute-data <report-path>` during Phase 7"
             )
 
+    if (report_data or {}).get("schemaVersion") == "2.0":
+        _validate_v2_ai_handoff(content, failures)
+        return
+
     # Catch the "workers typed `0` / `pending` instead of the placeholder"
     # failure mode that bypasses the placeholder check above.
     _scan_token_usage_summary(
@@ -2995,7 +3041,7 @@ def validate_final_report_data(
     project_root: Path | None = None,
     clarification_text: str = "",
 ) -> Mapping[str, Any] | None:
-    """Validate the final-report data.json against the v1.0 schema.
+    """Validate final-report data.json against its declared versioned schema.
 
     The data.json is the source-of-truth that the renderer reads to
     produce the markdown. If schema validation passes here, the rendered
@@ -3010,7 +3056,7 @@ def validate_final_report_data(
     The returned mapping is the exact loaded snapshot consumed by later
     finalization checks and workflow persistence.
     """
-    if schema_validate is None or load_schema is None:
+    if schema_validate is None or load_schema_for_data is None:
         # Module-load fallback path; should never fire in a real install.
         failures.append(
             "validate-run: okstra_ctl.final_report_schema is not importable — "
@@ -3028,13 +3074,11 @@ def validate_final_report_data(
         return
 
     try:
-        schema = load_schema()
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+        schema = load_schema_for_data(data)
     except SchemaError as exc:
         failures.append(f"final-report schema could not be loaded: {exc}")
         return
-
-    try:
-        data = json.loads(data_path.read_text(encoding="utf-8"))
     except json.JSONDecodeError as exc:
         failures.append(f"final-report data.json is not valid JSON: {exc}")
         return
@@ -6035,6 +6079,8 @@ def validate_phase_boundary(
     task_type: str,
     report_path: Path,
     failures: list[str],
+    *,
+    report_data: Mapping[str, Any] | None = None,
 ) -> None:
     """Phase-specific contract checks.
 
@@ -6050,6 +6096,8 @@ def validate_phase_boundary(
       MUST be absent (lead converted findings into Clarification rows
       instead of opening the gate).
     """
+    if (report_data or {}).get("schemaVersion") == "2.0":
+        return
     if not report_path.exists():
         return
     content = report_path.read_text()
@@ -7167,7 +7215,12 @@ def main() -> int:
     )
     validate_team_state_usage(team_state, failures)
 
-    validate_phase_boundary(task_type, report_path, failures)
+    validate_phase_boundary(
+        task_type,
+        report_path,
+        failures,
+        report_data=validation_data,
+    )
     _validate_phase_boundary_error_log(
         report_path.parent.parent,
         task_type,

package/runtime/validators/validate_improvement_report.py

@@ -7,6 +7,7 @@ Called by validators/validate-run.py when task_type == "improvement-discovery".
 """
 from __future__ import annotations
 
+import json
 import re
 import sys
 from dataclasses import dataclass, field
@@ -25,6 +26,10 @@ from okstra_ctl.improvement_lenses import (
     ABSOLUTE_CANDIDATE_CAP,
     SOURCE_WORKERS,
 )
+from okstra_ctl.final_report_schema import (
+    load_schema_version,
+    validate as validate_final_report_data,
+)
 from okstra_ctl.md_table import split_pipe_row
 
 
@@ -290,6 +295,47 @@ def _check_verdict_card(
         errors.append("Verdict Card row must byte-match `## 7. Final Verdict` row")
 
 
+def _v2_candidate_rows(data: dict) -> list[list[str]]:
+    candidates = data["improvementDiscovery"]["candidates"]
+    return [
+        [
+            row["id"],
+            ",".join(row["lens"]),
+            row["title"],
+            ",".join(row["scope"]),
+            row["severity"],
+            row["effort"],
+            row["consensus"],
+            ",".join(row["sourceWorkers"]),
+            row["recommendedNextPhase"],
+            row["expectedBehaviorAfter"],
+            ",".join(row["evidence"]),
+        ]
+        for row in candidates
+    ]
+
+
+def _validate_v2_report(
+    data: dict,
+    run_dir: Path,
+    brief_frontmatter: dict,
+) -> ValidationResult:
+    errors = validate_final_report_data(data, load_schema_version("2.0"))
+    _check_grilling_log(run_dir, errors)
+    if errors:
+        return ValidationResult(ok=False, errors=errors)
+
+    rows = _v2_candidate_rows(data)
+    _check_candidates_cap(len(rows), brief_frontmatter, errors)
+    _check_candidate_rows(
+        rows,
+        brief_frontmatter.get("scan-scope") or [],
+        brief_frontmatter.get("out-of-scope") or [],
+        errors,
+    )
+    return ValidationResult(ok=not errors, errors=errors)
+
+
 def validate_improvement_report(
     report_path: Path, run_dir: Path, brief_frontmatter: dict
 ) -> ValidationResult:
@@ -299,6 +345,15 @@ def validate_improvement_report(
         errors.append(f"report file not found: {report_path}")
         return ValidationResult(ok=False, errors=errors)
 
+    data_path = report_path.with_suffix(".data.json")
+    if data_path.exists():
+        try:
+            data = json.loads(data_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            return ValidationResult(ok=False, errors=[f"invalid report data: {exc}"])
+        if data.get("schemaVersion") == "2.0":
+            return _validate_v2_report(data, run_dir, brief_frontmatter)
+
     body = report_path.read_text(encoding="utf-8")
 
     _check_grilling_log(run_dir, errors)

package/src/commands/lifecycle/install.mjs

@@ -80,7 +80,8 @@ Effect (copy mode):
   ${"$HOME"}/.okstra/lib/python   <- runtime/python
   ${"$HOME"}/.okstra/lib/validators <- runtime/validators  (stage/report structure validators)
   ${"$HOME"}/.okstra/bin           <- runtime/bin
-  ${"$HOME"}/.okstra/templates     <- runtime/templates  (report.css / report.js / *.template.md)
+  ${"$HOME"}/.okstra/templates     <- runtime/templates  (v1 assets + v2 AI/HTML template trees)
+  ${"$HOME"}/.okstra/schemas       <- runtime/schemas  (final-report schema v1 + v2)
   ${"$HOME"}/.okstra/prompts       <- runtime/prompts  (lead contracts + coding-preflight pack)
   ${"$HOME"}/.okstra/templates/settings.local.json <- runtime/templates/reports/settings.template.json
   ${"$HOME"}/.claude/skills/<name> <- skills when ${"$HOME"}/.claude exists
@@ -775,8 +776,9 @@ export async function runInstall(args) {
     paths.bin,
     { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o755 },
   );
-  // templates/ tree — report.css / report.js / *.template.md are consumed at
-  // runtime by okstra-render-report-views.py and final-report assembly. They
+  // templates/ tree — the v1 report.css/report.js compatibility assets, the
+  // v2 AI handoff template, and the task-specific html/** tree are consumed by
+  // okstra-render-report-views.py and final-report assembly. They
   // are NOT covered by installNamedTemplate (which only handles the renamed
   // settings.local.json sidecar), so without this step copy-mode installs
   // miss every asset other than that single file. See
@@ -786,13 +788,10 @@ export async function runInstall(args) {
     join(paths.home, "templates"),
     { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o644 },
   );
-  // schemas/ tree — final-report-v1.0.schema.json is loaded at runtime by
-  // okstra_ctl.final_report_schema.load_schema() (parent-walk from the
-  // installed okstra_ctl package finds ~/.okstra/schemas/). It is needed by
-  // (a) prepare_task_bundle to write the per-task-type schema excerpt into
-  // each run's instruction-set, and (b) validate-run's data.json schema
-  // check. Without this step copy-mode installs leave load_schema() unable
-  // to locate the schema. Link mode resolves it through the repo symlink.
+  // schemas/ tree — version-selected final-report v1/v2 schemas are loaded by
+  // okstra_ctl.final_report_schema. They support bundle excerpts, legacy
+  // re-renders, new task HTML, and validate-run. Link mode resolves the same
+  // files through the repo symlink.
   const schemasResult = await copyTreeIfChanged(
     join(runtimeRoot, "schemas"),
     join(paths.home, "schemas"),
@@ -840,7 +839,7 @@ export async function runInstall(args) {
   }
   if (templatesResult.missingSource) {
     process.stderr.write(
-      "warning: runtime/templates is empty. report.css / report.js will be missing — re-run the build step.\n",
+      "warning: runtime/templates is empty. final-report Markdown and HTML templates will be missing — re-run the build step.\n",
     );
   }
   if (schemasResult.missingSource) {
@@ -994,8 +993,14 @@ export async function runEnsureInstalled(args) {
   }
   if (!(await dirExists(paths.pythonpath))) reasons.push(`missing ${paths.pythonpath}`);
   if (!(await dirExists(paths.agents))) reasons.push(`missing agents dir ${paths.agents}`);
-  if (!(await fileExists(join(paths.home, "schemas", "final-report-v1.0.schema.json")))) {
-    reasons.push(`missing ${join(paths.home, "schemas", "final-report-v1.0.schema.json")}`);
+  for (const relative of [
+    ["schemas", "final-report-v1.0.schema.json"],
+    ["schemas", "final-report-v2.0.schema.json"],
+    ["templates", "reports", "final-report-v2.template.md"],
+    ["templates", "reports", "html", "base.template.html"],
+  ]) {
+    const installedPath = join(paths.home, ...relative);
+    if (!(await fileExists(installedPath))) reasons.push(`missing ${installedPath}`);
   }
   for (const reason of await promptResourceDriftReasons(paths)) {
     reasons.push(reason);

package/src/commands/report/finalize.mjs

@@ -10,9 +10,8 @@ Usage:
 Runs the four Phase 7 steps in their contractual order against one final-report:
 
   1. token-usage       substitute real token/cost numbers into the data.json
-  2. render-views      write the self-contained *.html sibling (skipped when the
-                       report has no C-* clarification rows and is not a plan
-                       approval target)
+  2. render-views      write the schema-v2 task-specific *.html sibling; v1
+                       keeps the legacy conditional interactive view
   3. spawn-followups   turn section 4 rows into task stubs
   4. validate-run      validate the finished run artifacts
 

package/src/commands/report/render-final-report.mjs

@@ -1,6 +1,6 @@
 import { runInstalledScript } from "../../lib/python-helper.mjs";
 
-const USAGE = `okstra render-final-report — render the markdown sibling of a final-report data.json
+const USAGE = `okstra render-final-report — render the AI handoff Markdown sibling of final-report data.json
 
 Wraps the python helper (\`okstra-render-final-report.py\`) installed under
 \`~/.okstra/bin/\` so skills call \`okstra render-final-report\` instead of
@@ -10,7 +10,9 @@ permission matching and prompts on every call).
 Usage:
   okstra render-final-report <path-to-final-report.data.json>
 
-The argument is forwarded verbatim to the python helper.
+The argument is forwarded verbatim to the Python helper. schemaVersion 1.0
+keeps the legacy Markdown template; schemaVersion 2.0 selects the AI handoff
+template. Human HTML is rendered separately from the same data.json.
 `;
 
 export async function run(args) {

package/src/commands/report/render-views.mjs

@@ -3,20 +3,20 @@ import { runInstalledScript } from "../../lib/python-helper.mjs";
 const USAGE = `okstra render-views — render the self-contained HTML view of a final-report
 
 A thin spawn shim over \`scripts/okstra-render-report-views.py\` (installed
-at \`$HOME/.okstra/bin/okstra-render-report-views.py\`). Reads the final-
-report MD and writes a single sibling:
+at \`$HOME/.okstra/bin/okstra-render-report-views.py\`). Resolves the final-
+report data and Markdown pair, then writes a single sibling:
 
-  <stem>.html       — single-file self-contained human view with form
-                       controls on §5 clarification rows (skipped when the
-                       report has no §5 C-* clarification rows)
+  <stem>.html       — single-file self-contained human view; schema v2 is
+                       always generated, while v1/quick remains conditional
 
 Usage:
-  okstra render-views <path-to-final-report.md>
+  okstra render-views <path-to-final-report.data.json|path-to-final-report.md>
       [--task-key <key>] [--task-type <type>] [--seq <NNN>]
       [--source-report <project-relative-path>]
 
-When the optional flags are omitted the script infers from the report
-path and its '- Task Type:' / '- Task Key:' lines.
+Schema v2 data is rendered directly into its task-specific HTML view and is
+always generated. Schema v1 and quick reports keep the legacy conditional
+Markdown view. Optional flags override inferred report metadata.
 `;
 
 export async function run(args) {