okstra 0.28.0 → 0.29.0

package/runtime/skills/okstra-report-writer/SKILL.md

@@ -83,7 +83,19 @@ The four steps below MUST execute in this exact order. Reordering them is the re
    ```
 
    The 10 substituted placeholders: `{{LEAD_TOTAL_TOKENS}}`, `{{LEAD_BILLABLE_TOKENS}}`, `{{LEAD_COST_USD}}`, `{{WORKER_TOTAL_TOKENS}}`, `{{WORKER_BILLABLE_TOKENS}}`, `{{WORKER_COST_USD}}`, `{{GRAND_TOTAL_TOKENS}}`, `{{GRAND_BILLABLE_TOKENS}}`, `{{GRAND_COST_USD}}`, `{{CLI_COST_USD}}`. The final-report file MUST already exist (Phase 6 output).
-3. **Phase 7 step 2 — Follow-up task spawner** (BLOCKING when Section 7 is non-empty). Turns the report's `## 7. Follow-up Tasks (후속 작업)` rows into `tasks/<task-group>/<new-task-id>/` stubs.
+3. **Phase 7 step 1.5 — Render report views** (BLOCKING). Produces two derived artifacts from the now-substituted final-report MD:
+
+   ```bash
+   python3 scripts/okstra-render-report-views.py \
+     <runDirectoryPath>/reports/final-report-<task-type>-<seq>.md
+   ```
+
+   Outputs (idempotent — re-running overwrites):
+   - `runs/<task-type>/reports/final-report-<task-type>-<seq>.slim.md` — token-saving AI-consumption copy.
+   - `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` — single-file self-contained human view. Section 5 `C-*` clarification rows with `Status` ∈ {`open`, `answered`} embed `<textarea>` controls; an `Export user response` button serialises form values to a markdown sidecar (schema in [`templates/reports/user-response.template.md`](../../templates/reports/user-response.template.md)) that the user pastes to `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md`. The original final-report MD is **never** mutated by user input — the sidecar is the single write target.
+
+   Must run AFTER step 1 (so token placeholders are substituted in both derived views) and BEFORE step 2 (so the slim/html artifacts exist for any validator step that checks them).
+4. **Phase 7 step 2 — Follow-up task spawner** (BLOCKING when Section 7 is non-empty). Turns the report's `## 7. Follow-up Tasks (후속 작업)` rows into `tasks/<task-group>/<new-task-id>/` stubs.
 
    ```bash
    python3 scripts/okstra-spawn-followups.py \
@@ -98,7 +110,7 @@ The four steps below MUST execute in this exact order. Reordering them is the re
    - Rows with `Auto-spawn? != yes` are reported as `skipped` and never written; surface them in Section 6 if manual action is still needed.
    - An invalid `Origin`, `Suggested task-type`, missing `Title`, or missing `Reason / Why deferred` exits `1`. The report-writer MUST refuse to ship a Section 7 with such rows.
    - **Canonical spawn rule (single source of truth):** the spawner runs when `task-type` ∈ {`implementation`, `final-verification`, `release-handoff`}, OR when Section 7 is non-empty for any other task-type. For the listed task-types Section 7 must be present in the report; an empty section renders as `- 후속 작업 없음.`. Missing / empty sections are no-ops (exit `0`). All other references to this rule (including the Persistence Checklist) defer to this statement.
-4. **Phase 7 step 3 — Update Section 6** after the spawner. The report-writer MUST append one row per newly spawned task-key with its entry command:
+5. **Phase 7 step 3 — Update Section 6** after the spawner. The report-writer MUST append one row per newly spawned task-key with its entry command:
 
    ```
    - Follow-up: `<task-group>/<new-task-id>` — Claude Code 세션 안 `/okstra-run task-key=<task-group>/<new-task-id> task-type=<suggested>` / 별도 터미널 `scripts/okstra.sh --task-key <task-group>/<new-task-id> --task-type <suggested>`
@@ -117,7 +129,8 @@ The final report follows the structure below. If `instruction-set/final-report-t
 - Date: <ISO 8601 timestamp>
 - Task Key: <task-key>
 - Task Type: <task-type>
-- Author: `<Report writer worker if in roster, else Claude lead>`
+- Report Owner: `Claude lead`
+- Report Author: `<Report writer worker if in roster, else Claude lead (release-handoff or recorded-fallback only)>`
 - Lead model: `<lead-model>`
 - Preparation Method: Final report authored by Report writer worker (or lead-authored fallback — record the documented dispatch failure reason here when applicable)
 ```
@@ -208,7 +221,7 @@ The final-report template `okstra-final-report.template.md` Section 2 already en
 
 ### Release-handoff section contract (release-handoff runs only)
 
-When the run's `task-type` is `release-handoff`, the final report MUST include Section `## 4.6 Release Handoff Deliverables` with all seven sub-sections (`4.6.1` Source Verification Report, `4.6.2` Feature Branch & Working-Tree State, `4.6.3` User Selections, `4.6.4` Executed Commands, `4.6.5` Commit List, `4.6.6` Pull Request Outcome, `4.6.7` Routing Recommendation). Every entry is dictated by the lead's recorded git/gh command log and the user's verbatim answers to the H1/H2/H3 menu prompts. H1 choices are `local only`, `push + PR`, or `skip`; release-handoff records existing implementation commits and MUST NOT create new commits. If the user picked `skip` (H1) or `cancel` (H3), keep 4.6.3 populated but leave 4.6.4–4.6.6 explicitly empty per the template's empty-state lines.
+When the run's `task-type` is `release-handoff`, the final report MUST include Section `## 4.6 Release Handoff Deliverables` with all eight sub-sections (`4.6.1` Source Verification Report, `4.6.2` Feature Branch & Working-Tree State, `4.6.3` User Selections, `4.6.4` Executed Commands, `4.6.5` Commit List, `4.6.6` Merge Conflict Probe, `4.6.7` Pull Request Outcome, `4.6.8` Routing Recommendation). Every entry is dictated by the lead's recorded git/gh command log and the user's verbatim answers to the H1/H2/H3 menu prompts. H1 choices are `local only`, `push + PR`, or `skip`; release-handoff records existing implementation commits and MUST NOT create new commits. If the user picked `skip` (H1) or `cancel` (H3), keep 4.6.3 populated but leave 4.6.4–4.6.6 explicitly empty per the template's empty-state lines.
 
 **Single-lead authorship (release-handoff only):** release-handoff has no worker roster (no `Report writer worker`, no `Claude worker` drafter). The Claude lead authors the final-report file directly — there is no `Report writer worker` dispatch to perform in Phase 6, no resume-safe dispatch concern, and no mandatory worker-results file for a report-writer role. The rest of this skill's dispatch / resume / fallback machinery applies ONLY when `Report writer worker` is in the roster (i.e. every task-type other than `release-handoff`).
 
@@ -278,6 +291,8 @@ Persistence steps that must be performed in Phase 7:
 - [ ] 6. **Generate final status file**: `runs/<task-type>/status/final-<task-type>-<seq>.status` (if necessary)
 - [ ] 7. **Save convergence state**: `runs/<task-type>/state/convergence-<task-type>-<seq>.json` (when convergence is enabled)
 - [ ] 8. **Spawn follow-up task stubs**: run `scripts/okstra-spawn-followups.py` against the final-report per the canonical spawn rule defined in "Phase 7 follow-up task spawner" above. Do not restate the trigger condition here — that section is the single source of truth. The script is idempotent across reruns.
+- [ ] 9. **Slim AI report**: `runs/<task-type>/reports/final-report-<task-type>-<seq>.slim.md` (produced by Phase 7 step 1.5 — see "Phase 6 → Phase 7 execution sequence" above)
+- [ ] 10. **Human HTML report**: `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` (same step 1.5; self-contained, embeds `Export user response` button)
 
 ### Response after Persistence
 

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -213,7 +213,7 @@ Terminal statuses that can be recorded for a worker:
 
 **Authoritative source.** If other documents (SKILL.md, worker agent definitions) disagree with this section, this section wins.
 
-### Result Frontmatter (mandatory, precedes Section 0)
+### Result Frontmatter (mandatory, precedes Section 1)
 
 Every worker result file MUST begin with a YAML frontmatter block. The values are sourced from the corresponding fields of the input files' frontmatter (e.g. `analysis-material.md`, `task-brief.md`) — copy them verbatim; do NOT regenerate them. Only `workerId` and `title` are worker-specific.
 
@@ -260,11 +260,8 @@ The same frontmatter contract applies to the `Report writer worker`'s final-repo
 
 A successful worker result must include the following sections in this exact order, beneath the frontmatter block:
 
-0. **Reading Confirmation** — one short line per input file stating that the worker read it end-to-end. Each line takes the form `- Read <file-name> end-to-end (<line-count> lines).`. The enumerated files are audience-scoped — they MUST match the recipient's row in the "Audience-scoped enumeration" table above:
-   - **Claude / Codex / Gemini analysis workers**: `task-brief.md`, `analysis-profile.md`, `analysis-material.md` (if present), `reference-expectations.md`, `clarification-response.md` (if a carry-in was provided). Analysis workers MUST NOT include `final-report-template.md` — it is not in their `[Required reading]` block.
-   - **Report writer worker (Phase 6)**: all of the above **plus** `final-report-template.md`.
+> **Reading Confirmation lives in the audit sidecar, NOT in the main worker result.** Section 0 is intentionally absent from the main file. The worker writes Reading Confirmation to `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md` per the dispatch-prompt clause above; the validator FAILS any main worker-result file that contains a `## 0. Reading Confirmation` heading. If a file was skipped or only partially read, the worker MUST NOT produce sections 1–5 — instead it records a `tool-failure` in the errors sidecar and stops.
 
-   If a file was skipped or only partially read, the worker MUST NOT produce sections 1–5; instead it records a `tool-failure` in the errors sidecar and stops. This section exists specifically to counteract the common failure mode where workers skim long inputs because they share structure with the file the run will eventually write into.
 1. Findings
 2. Missing Information or Assumptions
 3. Safe or Reasonable Areas

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

@@ -33,6 +33,7 @@ Template authoring notes (NOT rendered to readers — HTML comments).
 - Task Key: {{TASK_KEY}}
 - Task Type: {{TASK_TYPE}}
 - Report Owner: `Claude lead`
+- Report Author: `<Report writer worker | Claude lead (release-handoff or recorded-fallback only)>`
 - Lead Model: `{{LEAD_MODEL}}`
 - Okstra Version: `{{OKSTRA_VERSION}}`
 
@@ -360,7 +361,17 @@ H1 = `skip` 이거나 H3 = `cancel` 인 경우 4.6.4 ~ 4.6.6 은 빈 결과로
 
 commit 범위가 비어 있으면 release-handoff 는 실행되면 안 됩니다 → `- No implementation commits found; release-handoff is blocked.` + routing 을 `implementation` 으로 되돌림.
 
-### 4.6.6 Pull Request Outcome (PR 결과)
+### 4.6.6 Merge Conflict Probe (사전 머지 충돌 점검)
+
+`push + PR` 경로에서만 실행. 다음 셋 중 정확히 하나의 형식으로 한 줄을 기록합니다 (read-only — `git fetch origin <base>` + `git merge-tree --merge-base origin/<base> HEAD origin/<base>` 만 허용; mutating git 명령 금지):
+
+- `- Not run (user picked local only or skip).`
+- `- Clean — no conflicts against <base> at <origin/base SHA>.`
+- `- Conflicts detected against <base> at <origin/base SHA>; user chose <proceed anyway | change base branch | cancel>. Conflicting paths: <list>.`
+
+`push + PR` 인데 본 항목이 없거나 위 셋 외의 자유 서술이면 self-review 가 `contract-violated` 로 종료합니다 (`release-handoff` profile self-review 6번 — merge-conflict probe audit).
+
+### 4.6.7 Pull Request Outcome (PR 결과)
 
 다음 네 가지 중 정확히 하나의 형식으로 한 줄:
 
@@ -369,7 +380,7 @@ commit 범위가 비어 있으면 release-handoff 는 실행되면 안 됩니다
 - `- PR reused: <url>` (run 시작 시 같은 head 의 open PR 이 이미 존재해 `gh pr create` 생략)
 - `- PR creation skipped: <reason>` (H3 = `cancel`, 또는 push/PR 도중 사용자 중단)
 
-### 4.6.7 Routing Recommendation (마지막 phase 라우팅)
+### 4.6.8 Routing Recommendation (마지막 phase 라우팅)
 
 `release-handoff` 는 lifecycle 종착 phase 이므로 일반적으로 `done` 으로 라우팅합니다. H1 = `skip` 또는 H3 = `cancel` 로 종료된 경우 재진입 가능 여부를 한 줄로 명시합니다.
 
@@ -377,6 +388,162 @@ commit 범위가 비어 있으면 release-handoff 는 실행되면 안 됩니다
 
 <!-- /RENDER_IF (task-type == release-handoff) -->
 
+<!-- RENDER_IF: task-type == implementation
+     Delete the entire `## 4.7` block + sub-sections otherwise. -->
+
+## 4.7 Implementation Deliverables
+
+`implementation` profile 의 "Required deliverable shape" 를 보고서 본문 구조로 옮겨 적습니다. 모든 sub-section 은 필수이며, 비어 있는 경우에도 헤딩은 유지하고 본문에 명시적 빈 상태 한 줄을 적습니다. validator 는 8 개 substring (`Approved Plan Reference`, `Commit List`, `Diff Summary`, `Out-of-plan Edits`, `Validation Evidence`, `Verifier Results`, `Rollback Verification`, `Routing Recommendation`) 의 등장 여부를 검사합니다.
+
+### 4.7.1 Approved Plan Reference (승인된 계획 참조)
+
+- Plan file (project-relative): `<runs/implementation-planning/.../reports/final-report-implementation-planning-<seq>.md>`
+- Approval evidence (해당 plan 의 정확한 인용 — `- [x] Approved` 마커 + Section 4.5.3 Recommended Option 한 줄):
+  > <원문 인용>
+- 본 run 의 `EXECUTOR_WORKTREE_PATH`: `<absolute path>`
+- 본 run 의 base ref (`{{EXECUTOR_WORKTREE_BASE_REF}}`): `<commit SHA>`
+
+### 4.7.2 Commit List (생성된 commit)
+
+| # | Short SHA | Full SHA | Plan Step | Subject | Files |
+|---|-----------|----------|-----------|---------|-------|
+| 1 | `<abc1234>` | `<full-sha>` | Step 1 | `<exact commit subject>` | `<file paths>` |
+
+규칙: 한 commit = 한 plan step (또는 cohesive sub-step). `Subject` 는 git log 에 적힌 원문 그대로 — 재해석·요약 금지. commit 이 없으면 본 run 은 실행되지 않아야 했음 → `- No implementation commits produced; routing recommendation must be back to implementation-planning.` 한 줄.
+
+### 4.7.3 Diff Summary (변경 요약)
+
+```
+<git diff --stat <base>..HEAD 의 raw 출력>
+```
+
+다음으로 file-by-file 한 줄 요약 표:
+
+| File | Action | Lines (+/-) | Plan step / Out-of-plan |
+|------|--------|-------------|--------------------------|
+| `<path>` | created / modified / deleted | `+12 / -3` | Step 2 또는 `Out-of-plan` |
+
+### 4.7.4 Out-of-plan Edits (계획 외 편집)
+
+승인된 plan 의 file list 에 없는 파일을 편집한 경우 row 로 기록. 없으면 `- 계획 외 편집 없음.` 한 줄.
+
+| ID | File | Rationale | Trigger (어떤 step 수행 중 발견) |
+|----|------|-----------|--------------------------------|
+| OOP-001 | `<path>` | <한 두 문장> | Step `<N>` |
+
+### 4.7.5 Validation Evidence (검증 증거)
+
+plan 의 `4.5.6 Validation Checklist` 의 pre / mid / post 각 row 에 대해 실제 명령과 출력 / exit code 를 모두 기록합니다. 요약·"tests pass" 같은 단어 금지 — 명령 line 과 exit code 는 원문 그대로.
+
+| Phase | Command | Exit code | Output tail (≤10 lines) | TDD evidence (failing→passing SHAs) |
+|-------|---------|-----------|--------------------------|--------------------------------------|
+| pre   | `<cmd>` | `0` | <인용> | -- |
+| mid   | `<cmd>` | `0` | <인용> | `<failing SHA>` → `<passing SHA>` |
+| post  | `<cmd>` | `0` | <인용> | -- |
+
+### 4.7.6 Verifier Results (verifier 별 결과)
+
+verifier role 마다 한 sub-block 으로 정리합니다 (`Claude verifier`, `Codex verifier`, opt-in 시 `Gemini verifier`). 각 verifier 의 read-only 명령 로그, 독립 재실행 결과, lint/format/typecheck 결과, 그리고 Discrepancy 라인을 모두 보존합니다. lead 는 합의 verdict 를 합성하되 의견을 collapse 하지 않습니다.
+
+- **Claude verifier** — Verdict: `<PASS | CONCERNS | FAIL>`
+  - Read-only command log: <verifier 의 worker result 에서 원문 인용>
+  - Independent validation re-run: <plan validation command 별 exit code + tail>
+  - Style / lint / type-check: <도구·exit code·새 위반 수>
+  - Declined fix recommendations: <한 줄씩 — 없으면 `- 없음.`>
+  - Discrepancy (vs executor): `- 없음.` 또는 `- <plan step / command>: executor=<result>, verifier=<result>`
+- **Codex verifier** — Verdict: ...
+- **Gemini verifier** (opt-in 시) — Verdict: ...
+
+합의 verdict (lead 합성): `<PASS | CONCERNS | FAIL>` — 한 verifier 라도 `FAIL` 이면 합의는 `FAIL` (override 시 lead 가 구체적 재현 시점 이유 인용 필수).
+
+### 4.7.7 Rollback Verification (롤백 검증)
+
+변경 카테고리별로 다른 강도의 확인. 표 1 행 = 1 카테고리.
+
+| Category | Rollback command | Verification | Result |
+|----------|-------------------|---------------|--------|
+| Pure code | `git revert <SHA>` | `git rev-parse <SHA>` 가 resolve 됨 | `ok` |
+| Feature-flag-gated | flag off 상태 validation run | 위 4.7.5 의 해당 명령 인용 | `ok` |
+| Schema/config/stateful | rollback step `<cmd>` dry-run | exit code + stdout 인용 | `ok` 또는 `unable — route back to planning` |
+
+dry-run 모드가 없는 stateful 변경은 본 항목을 `unable` 로 적고 `## 6.` 의 첫 항목을 `implementation-planning` 재진입으로 권장해야 합니다.
+
+### 4.7.8 Routing Recommendation (다음 phase 라우팅)
+
+다음 셋 중 하나의 형식으로 한 줄:
+
+- `- Routing: final-verification. All plan steps satisfied; rollback verified; verifier consensus <PASS|CONCERNS>.`
+- `- Routing: error-analysis. <한 줄 — 어떤 결함이 추가 분석을 요구하는지>.`
+- `- Routing: implementation-planning. <한 줄 — 왜 새 plan 이 필요한지 (drift / scope-mismatch / stateful-rollback-gap)>.`
+
+<!-- /RENDER_IF (task-type == implementation) -->
+
+<!-- RENDER_IF: task-type == final-verification
+     Delete the entire `## 4.8` block + sub-sections otherwise. -->
+
+## 4.8 Final Verification Deliverables
+
+`final-verification` profile 의 "Required deliverable shape" 를 본문 구조로 옮겨 적습니다. 모든 sub-section 필수. validator 는 6 개 substring (`Source Implementation Report`, `Acceptance Blockers`, `Residual Risk`, `Validation Evidence`, `Read-only Command Log`, `Routing Recommendation`) 등장과 `## 2. Final Verdict` 의 `Verdict Token` 값이 `accepted` / `conditional-accept` / `blocked` 중 하나인지 검사합니다.
+
+### 4.8.1 Source Implementation Report (선행 implementation 인용)
+
+- Path (project-relative): `<runs/implementation/.../reports/final-report-implementation-<seq>.md>`
+- 인용된 commit list / diff summary 요약:
+  > <원문 인용 — `## 4.7.2` / `## 4.7.3` 에서>
+- 검증 대상 worktree path: `<absolute path>`
+- run 시작 시 capture 한 head/base SHA: `<base SHA> .. <head SHA>`
+- `git status --short` (run 시작 시점):
+  ```
+  <원문 그대로>
+  ```
+
+### 4.8.2 Acceptance Blockers (수락 차단 항목)
+
+비어 있으면 표 대신 `- No acceptance blockers found.` 한 줄. 모든 blocker 는 구체적 artifact (file:line, log, exit code, MCP SELECT 결과) 인용 필수 — 증거 없는 blocker 는 4.8.3 residual risk 로 강등.
+
+| ID | Severity | Statement | Evidence (path:line / log / exit code) | Recommended follow-up phase |
+|----|----------|-----------|-----------------------------------------|------------------------------|
+| AB-001 | `critical / major / minor` | <한 줄 결함 요약> | `<file>:<line>` 또는 로그 인용 | `error-analysis` / `implementation-planning` |
+
+### 4.8.3 Residual Risk (잔존 위험)
+
+blocker 는 아니지만 추적해야 할 위험. 각 항목에 mitigation owner 와 blocker 로 격상되는 trigger 를 명시.
+
+| ID | Item | Mitigation owner | Escalation trigger |
+|----|------|------------------|---------------------|
+| RR-001 | <한 줄> | <역할 / 팀> | <어떤 조건이면 AB-? 로 격상> |
+
+비어 있으면: `- 추적 대상 잔존 위험 없음.`
+
+### 4.8.4 Validation Evidence (요구사항 커버리지)
+
+선행 plan / task brief 의 모든 요구사항에 대해 cover 한 artifact 를 cite. 패러프레이즈 ("verified") 금지.
+
+| ID | Requirement (plan/brief 인용) | Artifact (commit SHA / test output / log line / MCP SELECT) | Status (covered / blocker AB-? / gap) |
+|----|--------------------------------|--------------------------------------------------------------|----------------------------------------|
+| VE-001 | <한 줄> | `<artifact>` | covered |
+
+### 4.8.5 Read-only Command Log (실행 명령 로그)
+
+본 run 에서 실행한 모든 명령 (Tier 1 plan validation + Tier 2 `project.json.qaCommands`) 을 실행 순서대로 한 row 씩 기록. mutating 명령은 등장하면 안 됨.
+
+| # | Tier | Command (verbatim) | Exit code | Output tail (≤5 lines) |
+|---|------|---------------------|-----------|-------------------------|
+| 1 | 1    | `<plan validation cmd>` | `0` | <인용> |
+| 2 | 2    | `cargo clippy --all-targets -- -D warnings` | `0` | <인용> |
+
+`project.json.qaCommands` 의 category 가 비어 있으면 `qa-command not configured: <lint/format/typecheck/test>` 한 줄. deny-list (`--fix`, `--write`, ` -w`, ` -u`, `--snapshot-update`, `INSTA_UPDATE=<not-no>`, `cargo update`, `npm install` without `ci` 등) 토큰을 포함한 cmd 는 `qa-command rejected (denied token: <token>): <label>` 한 줄로 기록 후 실행하지 않음.
+
+### 4.8.6 Routing Recommendation (다음 phase 라우팅)
+
+`## 2. Final Verdict` 의 `Verdict Token` 과 1:1 대응. 다음 셋 중 하나:
+
+- `- Routing: release-handoff. Verdict Token = accepted; PR-ready.`
+- `- Routing: release-handoff with conditions. Verdict Token = conditional-accept; conditions listed in 4.8.2 / 4.8.3 must be resolved before push.`
+- `- Routing: error-analysis (or implementation-planning). Verdict Token = blocked; <blocker AB-?> requires <re-analysis | replan>.`
+
+<!-- /RENDER_IF (task-type == final-verification) -->
+
 ## 5. Clarification Items
 
 다음 run 으로 넘어가기 전에 사용자가 답하거나 자료를 첨부해야 하는 항목을 **한 표 안에서** 추적합니다. `task-type` 이 `error-analysis` / `requirements-discovery` 이고 지금까지의 증거만으로 확신 있는 최종 판단이 어려울 때는 반드시 채웁니다. 그 외 task-type 에서는 lead 가 필요하다고 판단할 때만 채우고, 그렇지 않다면 `- 추가 정보 요청 없음. Section 2 의 최종 판단이 그대로 유효합니다.` 한 줄만 남깁니다.

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` 가 두 구현의 동일성을 검증합니다.