okstra 0.27.0 → 0.29.0

package/runtime/templates/reports/report.css

@@ -0,0 +1,151 @@
+/* Single self-contained stylesheet for the okstra final-report HTML view.
+ * Inlined verbatim by scripts/okstra_ctl/report_views.py render_html.
+ * No external @import, no url() references. System colors only so dark
+ * mode follows the user's OS without a media query toggle.
+ */
+
+* { box-sizing: border-box; }
+
+html { color-scheme: light dark; }
+
+body {
+  margin: 0;
+  padding: 0;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  font-size: 15px;
+  line-height: 1.55;
+  background: Canvas;
+  color: CanvasText;
+}
+
+.report-header,
+.report-footer {
+  position: sticky;
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  padding: 0.6rem 1rem;
+  background: Canvas;
+  border-bottom: 1px solid GrayText;
+  z-index: 10;
+}
+
+.report-header { top: 0; }
+.report-footer {
+  bottom: 0;
+  border-top: 1px solid GrayText;
+  border-bottom: none;
+  flex-wrap: wrap;
+}
+
+.report-header > div { flex: 1; font-weight: 600; }
+
+main {
+  max-width: 80ch;
+  margin: 1.5rem auto;
+  padding: 0 1rem 4rem;
+}
+
+h1, h2, h3, h4, h5, h6 { line-height: 1.25; margin-top: 1.6em; margin-bottom: 0.4em; }
+h1 { font-size: 1.7rem; }
+h2 { font-size: 1.35rem; border-bottom: 1px solid GrayText; padding-bottom: 0.2em; }
+h3 { font-size: 1.12rem; }
+h4 { font-size: 1rem; }
+
+p, ul, ol, blockquote, pre, table { margin: 0.6em 0; }
+
+ul, ol { padding-left: 1.4em; }
+
+blockquote {
+  border-left: 3px solid GrayText;
+  padding: 0.2em 0.8em;
+  color: GrayText;
+}
+
+code {
+  font-family: "SFMono-Regular", Menlo, Consolas, monospace;
+  font-size: 0.92em;
+  padding: 0.1em 0.35em;
+  background: color-mix(in srgb, CanvasText 8%, transparent);
+  border-radius: 3px;
+}
+
+pre {
+  overflow-x: auto;
+  padding: 0.8em 1em;
+  background: color-mix(in srgb, CanvasText 6%, transparent);
+  border-radius: 4px;
+}
+pre code { background: transparent; padding: 0; }
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.92rem;
+}
+th, td {
+  border: 1px solid color-mix(in srgb, GrayText 50%, transparent);
+  padding: 0.45em 0.6em;
+  vertical-align: top;
+  text-align: left;
+}
+thead th {
+  position: sticky;
+  top: 3rem;
+  background: Canvas;
+  z-index: 5;
+}
+
+tr[data-response-id] {
+  background: color-mix(in srgb, Highlight 6%, transparent);
+}
+tr[data-response-id][data-status="resolved"],
+tr[data-response-id][data-status="obsolete"] {
+  background: transparent;
+  opacity: 0.65;
+}
+
+textarea {
+  width: 100%;
+  min-height: 2.2em;
+  font: inherit;
+  padding: 0.3em 0.4em;
+  border: 1px solid GrayText;
+  border-radius: 3px;
+  background: Canvas;
+  color: CanvasText;
+  resize: vertical;
+}
+textarea[disabled] { opacity: 0.55; }
+
+button[data-action] {
+  font: inherit;
+  padding: 0.4em 0.9em;
+  border: 1px solid GrayText;
+  border-radius: 4px;
+  background: ButtonFace;
+  color: ButtonText;
+  cursor: pointer;
+}
+button[data-action]:hover { background: color-mix(in srgb, Highlight 20%, ButtonFace); }
+
+#user-response-output {
+  flex-basis: 100%;
+  max-height: 14em;
+  overflow: auto;
+  margin: 0.6em 0 0;
+  padding: 0.6em 0.8em;
+  background: color-mix(in srgb, CanvasText 6%, transparent);
+  border-radius: 4px;
+  white-space: pre-wrap;
+  font-family: "SFMono-Regular", Menlo, Consolas, monospace;
+  font-size: 0.85rem;
+}
+#user-response-output:empty { display: none; }
+
+@media print {
+  .report-header, .report-footer { position: static; }
+  thead th { position: static; }
+  button[data-action] { display: none; }
+  #user-response-output { display: none; }
+}

package/runtime/templates/reports/report.js

@@ -0,0 +1,163 @@
+/* Client-side glue for the okstra final-report HTML view.
+ *
+ * Responsibilities:
+ *   1. Collect <textarea> values for every <tr data-response-id> whose
+ *      Status is open/answered (disabled rows are skipped automatically).
+ *   2. Serialise them into markdown whose bytes are IDENTICAL to
+ *      scripts/okstra_ctl/report_views.py serialize_user_response.
+ *   3. Write the result to <pre id="user-response-output"> and offer a
+ *      [Copy] button.
+ *
+ * The byte-identity contract is enforced by tests/test_report_views.py
+ * which spawns Node to execute buildUserResponseMarkdown and diffs the
+ * output against the Python function. If you edit the format here you
+ * MUST edit serialize_user_response too. The template at
+ * templates/reports/user-response.template.md documents the schema.
+ */
+
+(function () {
+  "use strict";
+
+  function readRunMeta() {
+    var el = document.getElementById("run-meta");
+    if (!el) return {};
+    try {
+      return JSON.parse(el.textContent || "{}");
+    } catch (e) {
+      return {};
+    }
+  }
+
+  function isoNowUtc() {
+    return new Date().toISOString().replace(/\.\d+Z$/, "Z");
+  }
+
+  function trimMultiline(s) {
+    return String(s == null ? "" : s).replace(/^\s+|\s+$/g, "");
+  }
+
+  function collectEntries() {
+    var entries = [];
+    var rows = document.querySelectorAll("tr[data-response-id]");
+    for (var i = 0; i < rows.length; i++) {
+      var row = rows[i];
+      var ta = row.querySelector("textarea[data-response-id]");
+      if (!ta || ta.disabled) continue;
+      var value = trimMultiline(ta.value);
+      if (!value) continue;
+      entries.push({
+        responseId: row.getAttribute("data-response-id") || "",
+        kind: row.getAttribute("data-kind") || "",
+        value: value,
+        rationale: null,
+      });
+    }
+    return entries;
+  }
+
+  function buildUserResponseMarkdown(runMeta, entries, createdAt) {
+    var head =
+      "---\n" +
+      "task-key: " + (runMeta["task-key"] || "") + "\n" +
+      "task-type: " + (runMeta["task-type"] || "") + "\n" +
+      "seq: " + (runMeta["seq"] || "") + "\n" +
+      "source-report: " + (runMeta["source-report"] || "") + "\n" +
+      "created-by: user\n" +
+      "created-at: " + createdAt + "\n" +
+      "---\n" +
+      "\n" +
+      "# User Response\n";
+
+    if (!entries || entries.length === 0) {
+      return head + "\n_(No user responses recorded.)_\n";
+    }
+
+    var chunks = "";
+    for (var i = 0; i < entries.length; i++) {
+      var e = entries[i];
+      var chunk =
+        "\n## " + e.responseId + "\n" +
+        "- Kind: " + e.kind + "\n" +
+        "- Value:\n" +
+        "  > " + trimMultiline(e.value) + "\n";
+      if (e.rationale) {
+        chunk += "- Rationale: " + trimMultiline(e.rationale) + "\n";
+      }
+      chunks += chunk;
+    }
+    return head + chunks;
+  }
+
+  function exportUserResponse() {
+    var runMeta = readRunMeta();
+    var entries = collectEntries();
+    var md = buildUserResponseMarkdown(runMeta, entries, isoNowUtc());
+    var out = document.getElementById("user-response-output");
+    if (out) out.textContent = md;
+    return md;
+  }
+
+  function copyUserResponse() {
+    var out = document.getElementById("user-response-output");
+    if (!out || !out.textContent) return;
+    var text = out.textContent;
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(text).catch(function () {
+        fallbackCopy(text);
+      });
+    } else {
+      fallbackCopy(text);
+    }
+  }
+
+  function fallbackCopy(text) {
+    var ta = document.createElement("textarea");
+    ta.value = text;
+    ta.style.position = "fixed";
+    ta.style.opacity = "0";
+    document.body.appendChild(ta);
+    ta.select();
+    try { document.execCommand("copy"); } catch (e) {}
+    document.body.removeChild(ta);
+  }
+
+  function bind() {
+    var clickables = document.querySelectorAll("button[data-action]");
+    for (var i = 0; i < clickables.length; i++) {
+      var btn = clickables[i];
+      var action = btn.getAttribute("data-action");
+      if (action === "export-user-response") {
+        btn.addEventListener("click", exportUserResponse);
+      } else if (action === "copy-user-response") {
+        btn.addEventListener("click", copyUserResponse);
+      }
+    }
+  }
+
+  if (typeof window !== "undefined") {
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", bind);
+    } else {
+      bind();
+    }
+    // Expose for tests / debug.
+    window.okstraReportView = {
+      buildUserResponseMarkdown: buildUserResponseMarkdown,
+      collectEntries: collectEntries,
+      exportUserResponse: exportUserResponse,
+    };
+  }
+
+  // Node export for cross-impl byte-identity test. We expose on both
+  // CommonJS module.exports (works in `require()` callers) and
+  // globalThis (works under ESM where the parent uses `vm.runInThisContext`
+  // — see tests/test_report_views.py for the byte-identity harness).
+  if (typeof module !== "undefined" && module.exports) {
+    module.exports = { buildUserResponseMarkdown: buildUserResponseMarkdown };
+  }
+  if (typeof globalThis !== "undefined") {
+    globalThis.__okstraReportViewExports__ = {
+      buildUserResponseMarkdown: buildUserResponseMarkdown,
+    };
+  }
+})();

package/runtime/templates/reports/user-response.template.md

@@ -0,0 +1,69 @@
+<!-- single source of truth: scripts/okstra_ctl/report_views.py serialize_user_response -->
+<!-- byte-identical client implementation: templates/reports/report.js buildUserResponseMarkdown -->
+
+# User-Response Sidecar Template
+
+이 파일은 final-report HTML 의 **Export user response** 버튼이 만들어내는 markdown 의 표준 포맷을 정의합니다. 산출물은 `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md` 경로에 저장됩니다. 원본 final-report MD 는 어떤 경우에도 머지하지 않습니다.
+
+## Frontmatter 스키마
+
+```yaml
+task-key: <task-group>/<task-id>
+task-type: <requirements-discovery | error-analysis | implementation-planning | implementation | final-verification | release-handoff>
+seq: <3-digit zero-padded run sequence>
+source-report: <project-relative path to the final-report .md the HTML was derived from>
+created-by: user
+created-at: <ISO 8601 UTC timestamp>
+```
+
+## Body 스키마
+
+본문은 `# User Response` 단일 H1 헤딩 아래, 각 응답을 `## <Response ID>` 헤딩으로 구분합니다. Response ID 는 final-report `## 5. Clarification Items` 표의 `ID` 컬럼(`C-NNN`)을 그대로 인용합니다.
+
+각 응답 블록의 schema:
+
+```markdown
+## <Response ID>
+- Kind: <material | decision | data-point>
+- Value:
+  > <multi-line value, trimmed>
+- Rationale: <optional one-line rationale>
+```
+
+빈 응답 집합(사용자가 어떤 행도 채우지 않고 Export 를 누른 경우)은 다음 한 줄을 본문에 출력합니다:
+
+```markdown
+_(No user responses recorded.)_
+```
+
+## Example
+
+```markdown
+---
+task-key: demo/T-1
+task-type: implementation-planning
+seq: 003
+source-report: runs/implementation-planning/reports/final-report-implementation-planning-003.md
+created-by: user
+created-at: 2026-05-17T10:00:00Z
+---
+
+# User Response
+
+## C-001
+- Kind: decision
+- Value:
+  > (a) 일회성. 재발 없음.
+- Rationale: 결제 로그 재확인 결과 동일 패턴 미관측.
+
+## C-003
+- Kind: data-point
+- Value:
+  > (prediction=0: 1,204) (prediction=1: 38)
+```
+
+## 호환성 규칙
+
+- `Kind` 가 알 수 없는 값이면 폼은 `<textarea>` fallback 으로 렌더되며, 직렬화 시 받은 `Kind` 문자열을 그대로 보존합니다.
+- `Status` 가 `resolved` 또는 `obsolete` 인 행은 HTML 폼이 `disabled` 로 렌더되어 Export 결과에서 자동 제외됩니다. 그 행을 다시 열려면 final-report 의 `Status` 를 `open` / `answered` 로 되돌리고 보고서를 재생성해야 합니다.
+- Python (`scripts/okstra_ctl/report_views.py` `serialize_user_response`) 과 JavaScript (`templates/reports/report.js` `buildUserResponseMarkdown`) 의 출력은 **byte-identical** 이어야 합니다. `tests/test_report_views.py` 가 두 구현의 동일성을 검증합니다.

package/runtime/validators/lib/fixtures.sh

@@ -250,6 +250,24 @@ for worker in team_state.get("workers", []):
             )
             + "\n"
         )
+        # Mirror the audit sidecar contract — every completed worker-results
+        # file ships alongside `<worker>-audit-<task-type>-<seq>.md` carrying
+        # the Reading Confirmation block. Derive the sidecar path by
+        # inserting `-audit` after the worker-role segment of the
+        # result-file stem.
+        result_stem = result_path.stem  # e.g. claude-worker-error-analysis-001
+        audit_stem = result_stem.replace("-worker-", "-worker-audit-", 1)
+        audit_path = result_path.with_name(f"{audit_stem}{result_path.suffix}")
+        audit_path.write_text(
+            "\n".join(
+                [
+                    f"# {worker.get('role', worker_id)} Audit",
+                    "",
+                    "- Read task-brief.md end-to-end (validation fixture).",
+                ]
+            )
+            + "\n"
+        )
 
 lead = team_state.get("lead")
 if isinstance(lead, dict):
@@ -305,6 +323,16 @@ if not isinstance(required_status_entries, list):
 report_lines = [
     "# Validation Fixture Report",
     "",
+    "## Verdict Card",
+    "",
+    "| 항목 | 값 |",
+    "|------|----|",
+    "| Final Conclusion | validation fixture |",
+    "| Verdict Token | `accepted` |",
+    "| Direction | `continue-investigation` |",
+    "| Approval Required? | `no` |",
+    "| Next Step | fixture |",
+    "",
     "## Agent Execution Status",
 ]
 for label in required_status_entries:
@@ -313,13 +341,59 @@ for label in required_status_entries:
 report_lines.extend(
     [
         "",
-        "## Final Verdict",
-        "- Validation fixture report generated.",
+        "## Token Usage Summary",
+        "",
+        "| 항목 | 처리 토큰 | 환산 토큰 | 비용 (USD) |",
+        "|------|-----------|-----------|------------|",
+        "| Lead | `1` | `1` | `$0.01` |",
+        "| Worker 합계 | `1` | `1` | `$0.01` |",
+        "| **전체 합계** | **`2`** | **`2`** | **`$0.02`** |",
+        "| Codex/Gemini CLI 추가 비용 |  |  | `$0.00` |",
+        "",
+        "## 2. Final Verdict",
+        "",
+        "| 항목 | 값 |",
+        "|------|----|",
+        "| Verdict Token | `accepted` |",
+        "",
+        "## 4.8 Final Verification Deliverables",
+        "",
+        "Source Implementation Report / Acceptance Blockers / Residual Risk / "
+        "Validation Evidence / Read-only Command Log / Routing Recommendation: "
+        "fixture stub.",
     ]
 )
 report_path.parent.mkdir(parents=True, exist_ok=True)
 report_path.write_text("\n".join(report_lines) + "\n")
 
+# Phase 7 step 1.5 (BLOCKING) — render the slim/html sibling artifacts
+# next to the final-report so validate-run.py's new report-views hook
+# passes. The workflow validator's fixture predates that step; we
+# materialise both files in-place using the same single-reference-point
+# helper the CLI uses.
+import os
+WORKSPACE_ROOT = os.environ.get("OKSTRA_WORKSPACE_ROOT_FOR_FIXTURE", "")
+if WORKSPACE_ROOT:
+    import sys as _sys
+    _sys.path.insert(0, str(Path(WORKSPACE_ROOT) / "scripts"))
+    try:
+        from okstra_ctl.report_views import RunMeta, render_both_views
+        css = (Path(WORKSPACE_ROOT) / "templates" / "reports" / "report.css").read_text(encoding="utf-8")
+        js = (Path(WORKSPACE_ROOT) / "templates" / "reports" / "report.js").read_text(encoding="utf-8")
+        render_both_views(
+            report_path,
+            run_meta=RunMeta(
+                task_key=str(task_manifest.get("taskKey", "validation/fixture")),
+                task_type=str(task_manifest.get("taskType", "validation")),
+                seq="001",
+                source_report=report_path.name,
+            ),
+            css=css,
+            js=js,
+        )
+    except Exception as exc:  # pragma: no cover — fixture path only
+        raise SystemExit(f"failed to render report views in fixture: {exc}")
+
 if final_status_path.exists():
     final_status_path.unlink()