okstra 0.28.0 → 0.30.0

package/runtime/bin/okstra-render-report-views.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""CLI entrypoint for Phase 7 step 1.5 — render two derived views of
+an okstra final-report markdown.
+
+Usage:
+  okstra-render-report-views.py <path-to-final-report.md>
+      [--task-key <task-group/task-id>]
+      [--task-type <profile>]
+      [--seq <NNN>]
+      [--source-report <relative-path>]
+
+When the optional flags are omitted, the script infers what it can from
+the report path (``runs/<task-type>/reports/final-report-<task-type>-<seq>.md``)
+and the report's frontmatter / ``- Task Key:`` / ``- Task Type:`` lines.
+
+Outputs (idempotent — overwrites):
+  - <stem>.slim.md  — token-saving copy for the next-phase lead prompt
+  - <stem>.html      — single-file self-contained HTML view
+
+This script is the canonical single-reference-point. The Node CLI
+(``bin/okstra render-views``) is a thin wrapper that spawns it.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS_DIR = REPO_ROOT / "scripts"
+HOME_LIB = Path(os.environ.get("OKSTRA_HOME", str(Path.home() / ".okstra"))) / "lib" / "python"
+
+# Prefer dev sources when present, fall back to install. Without this
+# order, a stale install (~/.okstra/lib/python/okstra_ctl) without the
+# report_views module shadows the in-repo copy during development.
+if (SCRIPTS_DIR / "okstra_ctl" / "report_views.py").is_file():
+    if str(SCRIPTS_DIR) in sys.path:
+        sys.path.remove(str(SCRIPTS_DIR))
+    sys.path.insert(0, str(SCRIPTS_DIR))
+    if HOME_LIB.is_dir() and str(HOME_LIB) not in sys.path:
+        sys.path.append(str(HOME_LIB))
+elif HOME_LIB.is_dir() and str(HOME_LIB) not in sys.path:
+    sys.path.insert(0, str(HOME_LIB))
+
+from okstra_ctl.report_views import RunMeta, render_both_views  # noqa: E402
+
+
+_TEMPLATES_DIRS = (
+    REPO_ROOT / "templates" / "reports",
+    Path.home() / ".okstra" / "lib" / "templates" / "reports",
+)
+
+# task-type itself can contain hyphens (``implementation-planning``,
+# ``final-verification``, ``release-handoff``), so the filename segment
+# between ``final-report-`` and ``-<seq>.md`` is matched greedily; the
+# trailing ``-(?P<seq>\d+)\.md$`` anchor pins seq to the last numeric tail.
+_PATH_RE = re.compile(
+    r"runs/(?P<task_type>[^/]+)/reports/final-report-.+-(?P<seq>\d+)\.md$"
+)
+
+
+def _load_assets() -> tuple[str, str]:
+    css_text: str | None = None
+    js_text: str | None = None
+    for d in _TEMPLATES_DIRS:
+        css = d / "report.css"
+        js = d / "report.js"
+        if css.is_file() and js.is_file():
+            css_text = css.read_text(encoding="utf-8")
+            js_text = js.read_text(encoding="utf-8")
+            break
+    if css_text is None or js_text is None:
+        raise SystemExit(
+            "report.css / report.js not found. Looked under: "
+            + ", ".join(str(d) for d in _TEMPLATES_DIRS)
+        )
+    return css_text, js_text
+
+
+def _infer_from_path(path: Path) -> dict[str, str]:
+    posix = path.as_posix()
+    m = _PATH_RE.search(posix)
+    if m:
+        return {"task_type": m.group("task_type"), "seq": m.group("seq")}
+    return {}
+
+
+def _infer_from_body(text: str) -> dict[str, str]:
+    found: dict[str, str] = {}
+    for label, key in (("Task Key", "task_key"), ("Task Type", "task_type")):
+        m = re.search(rf"^- {label}:\s*(\S.*?)\s*$", text, re.MULTILINE)
+        if m:
+            found[key] = m.group(1)
+    return found
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Render slim AI + self-contained HTML views of an okstra final-report."
+    )
+    parser.add_argument("report_path", type=Path)
+    parser.add_argument("--task-key", default=None)
+    parser.add_argument("--task-type", default=None)
+    parser.add_argument("--seq", default=None)
+    parser.add_argument("--source-report", default=None)
+    args = parser.parse_args(argv)
+
+    report_path: Path = args.report_path.resolve()
+    if not report_path.is_file():
+        parser.error(f"final-report not found: {report_path}")
+
+    inferred = {**_infer_from_path(report_path), **_infer_from_body(report_path.read_text(encoding="utf-8"))}
+    task_key = args.task_key or inferred.get("task_key") or "unknown"
+    task_type = args.task_type or inferred.get("task_type") or "unknown"
+    seq = args.seq or inferred.get("seq") or "000"
+    source_report = args.source_report or report_path.name
+
+    css, js = _load_assets()
+    meta = RunMeta(task_key=task_key, task_type=task_type, seq=seq, source_report=source_report)
+    slim_path, html_path = render_both_views(report_path, run_meta=meta, css=css, js=js)
+    print(f"slim: {slim_path}")
+    print(f"html: {html_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/runtime/prompts/profiles/implementation-planning.md

@@ -69,7 +69,7 @@
   - dependency / migration risk assessment (ordering constraints, data backfills, feature-flag prerequisites, repo-internal sequencing)
   - validation checklist (pre / mid / post) — each item is an exact command or observable outcome
   - rollback strategy — exact revert path (commits, flags, migrations) and the signal that triggers rollback
-  - explicit `User Approval Request (사용자 승인 게이트)` block placed at the **top of the report** with a single canonical checkbox marker `- [ ] Approved` (user toggles to `- [x] Approved` to authorise the next `implementation` run). Section `4.5.8` is retained only as a back-pointer to this top block for validator/key-substring compatibility — it must NOT carry an independent marker.
+  - explicit `User Approval Request (사용자 승인 게이트)` block placed at the **top of the report** with a single canonical checkbox marker `- [ ] Approved` (user toggles to `- [x] Approved` to authorise the next `implementation` run). The `User Approval Request` validator key-substring is satisfied by this top block — do NOT recreate a `### 4.5.8 User Approval Request` body stub (the validator now fails reports that contain one, see `validators/validate-run.py` and `templates/reports/final-report.template.md` §4.5.8).
   - **the marker line is rendered only when the plan-body verification gate (§4.5.9) returns `passed` or `passed-with-dissent`.** When the gate returns `blocked-by-disagreement` or `aborted-non-result`, the top-of-report Approval block is rendered **without** the canonical `- [ ] Approved` bullet (the rest of the block — title, summary, audit lines — stays). The `validators/validate-run.py` `validate_phase_boundary` function enforces this exact correspondence between gate result and marker line presence.
   - every ambiguity flagged during pre-planning that the user must resolve before approval registered as a `Blocks=approval` row in the `## 5. Clarification Items` table (do NOT create a separate `Open Questions` block under `4.5.x` — the unified table is the single home)
   - **§4.5.9 Plan Body Verification (BLOCKING).** After report-writer finishes the draft, the lead MUST run a worker peer-review round on the consolidated plan body (sections 4.5.1 – 4.5.7) and populate `### 4.5.9 Plan Body Verification` in the final report. The round protocol, plan-item ID scheme (`P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*`), verdict semantics, gate-result classification, and dissent log format are defined in `skills/okstra-convergence/SKILL.md` "Plan-body verification mode". The four gate-result values are `passed`, `passed-with-dissent`, `blocked-by-disagreement`, `aborted-non-result`. When the gate would have been `blocked-by-disagreement` or `aborted-non-result`, the lead MUST NOT silently flip it to one of the passing values to "unblock" the run — that is a contract violation.