okstra 0.102.2 → 0.102.4

package/docs/superpowers/plans/2026-05-17-dual-format-final-report.md

@@ -1,167 +0,0 @@
-# Dual-Format Final Report (AI MD slim + Human HTML) Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Phase 6 의 final-report 산출물에 두 가지 파생 view(AI 용 토큰-절약형 `*.slim.md`, 사람 용 self-contained `*.html`)를 추가한다. HTML 안에서 사용자가 의사결정 입력을 채우면 “Export to MD” 버튼이 그 입력을 AI 가 다음 phase 입력으로 바로 쓸 수 있는 user-response markdown 으로 직렬화한다. 원본 final-report MD 는 단일 source-of-truth 로 유지되며 사용자가 손으로 머지하지 않는다.
-
-**Architecture:**
-- **Source of truth:** 기존 `runs/<task-type>/reports/final-report-<task-type>-<seq>.md`. 변경 없음. report-writer-worker 의 작성 계약은 그대로.
-- **파생 산출물:**
-  - `final-report-<task-type>-<seq>.slim.md` — 결정론적 stripper 가 원본 MD 에서 생성. 토큰 부담이 큰 섹션(장식 헤더, sentinel/placeholder 셀, verdict-detail 중복, 캡션, 구분선)을 규칙 기반으로 제거.
-  - `final-report-<task-type>-<seq>.html` — 결정론적 renderer 가 원본 MD 에서 생성. 단일 파일, 인라인 CSS, vanilla JS 만 사용(외부 CDN 금지). Section 5(Clarification Items) / Section 6(Recommended Next Steps) / Section 7(Follow-up Tasks) 의 “user-actionable” 행에 자동으로 `<form>` 컨트롤이 부착된다.
-- **사용자 응답 경로:** HTML 안의 “Export user response” 버튼은 폼 값을 `.md` 텍스트(고정 스키마)로 직렬화하여 페이지 하단 `<pre>` 에 출력하고 클립보드 복사 버튼을 제공한다. 사용자는 그 텍스트를 `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md` 경로에 붙여넣어 저장한다(Phase 7 후속 단계 또는 다음 phase 의 lead 가 그 파일을 입력으로 소비). **원본 final-report MD 는 절대 수정하지 않는다.**
-- **용어 충돌 회피:** 2026-05-17 머지된 변경에서 worker-results audit 파일은 "audit sidecar"로, Section 0 Reading Confirmation 은 그 audit sidecar 전용으로 단일화되었다. 따라서 본 plan 의 "decision sidecar" 용어는 **사용 금지**. 사용자 입력 산출물은 `user response` / `user-response-*.md` 로 일관되게 부른다. 경로도 `decisions/` 가 아닌 `user-responses/`.
-- **호출 경로 single reference:** 두 변환은 모두 새 Python 모듈 `scripts/okstra_ctl/report_views.py` 한 곳에서 처리한다. 다음 세 entrypoint 가 같은 함수를 호출:
-  1. `scripts/okstra-render-report-views.py` (CLI, Phase 7 step 0 에서 호출)
-  2. `bin/okstra render-views <task-key>` (node CLI 래퍼)
-  3. report-writer-worker SKILL 의 Persistence Checklist 항목 (실패 시 lead fallback)
-
-**Tech Stack:** Python 3 (markdown stripper + HTML renderer, 표준 라이브러리만 — `markdown` 의존성 추가 금지), pytest fixtures, HTML5 + vanilla JS, JSON Schema(hand-rolled) for decision sidecar.
-
-> 참고: 본 plan 은 **Phase 6 → Phase 7 실행 순서(BLOCKING order)** 의 step 2(token substitution) 직후, step 3(follow-up spawner) 전에 “step 2.5 — render report views” 를 삽입한다. token placeholder 가 치환된 MD 가 두 view 의 입력이어야 슬림 MD/HTML 에도 실제 토큰 숫자가 들어간다. 이 순서는 BLOCKING.
-
----
-
-## File Structure
-
-| 경로 | 책임 | 변경 종류 |
-|---|---|---|
-| `scripts/okstra_ctl/report_views.py` | `slim_markdown(src_md) -> str`, `render_html(src_md, *, run_meta) -> str`, `serialize_user_response(form_payload) -> str` 의 단일 reference 구현 | Create |
-| `scripts/okstra-render-report-views.py` | 위 모듈을 호출하는 CLI entrypoint. 입력: 원본 final-report 경로. 출력: `*.slim.md`, `*.html` | Create |
-| `bin/okstra` (또는 `src/commands/render-views.mjs`) | node CLI `okstra render-views` 서브커맨드 — 단순 위임 | Modify (or Create one file) |
-| `skills/okstra-report-writer/SKILL.md` | Phase 6→7 sequence 에 step 2.5 추가, Persistence Checklist 에 두 산출물 항목 추가 | Modify |
-| `agents/workers/report-writer-worker.md` | required-reading 에 본 plan / 결정 sidecar 스키마 링크 추가 | Modify |
-| `templates/reports/final-report.template.md` | 변경 없음 (source of truth 유지). 단 “user-actionable 행” 인식 마커(예: 행 ID `D-*` for decision) 가 이미 존재하는지 확인하고 없으면 Section 5 / 6 / 7 의 row 스키마에 `Response ID` 컬럼만 옵션으로 추가 | Modify (좁은 범위) |
-| `templates/reports/user-response.template.md` | 사용자 응답 직렬화 포맷의 single reference (예: 각 Response ID 별 한 블록, frontmatter 포함) | Create |
-| `templates/reports/report.css` | HTML view 의 인라인 임포트 대상 (build 시 인라인 됨). 외부 CDN 없음 | Create |
-| `templates/reports/report.js` | HTML view 의 인라인 임포트 대상. form → MD 직렬화 + 복사 로직 | Create |
-| `validators/validate-report-views.py` | 원본 MD 의 결정 행 수와 HTML/slim/sidecar 스키마 일관성 검사. Phase 7 의 validator 체인에 추가 | Create |
-| `tests/fixtures/reports/golden-original.md` | 결정/비결정 행을 모두 포함한 합성 final-report | Create |
-| `tests/fixtures/reports/golden-original.slim.md` | 위 입력의 기대 slim 산출물 | Create |
-| `tests/fixtures/reports/golden-original.html` | 위 입력의 기대 HTML 산출물(테스트는 normalize 후 diff) | Create |
-| `tests/test_report_views.py` | golden fixture round-trip + sidecar 직렬화 단위 테스트 | Create |
-| `CHANGES.md` | 사용자 영향 한 줄 추가 | Modify |
-
----
-
-## Convention Notes (모든 task 공통)
-
-- 모든 변경은 **end-user seed 경로**(repo 안 `scripts/`, `skills/`, `agents/`, `templates/`, `validators/`)에 들어가며, 빌드 후 `runtime/` 에 동기화된다. 개인 `~/.claude/` 직접 편집 금지(MEMORY: `feedback_okstra_fixes_target_end_users.md`).
-- HTML 은 반드시 **단일 `.html` 파일**. `<script src=>` / `<link href=>` 의 외부 URL 금지. 차트는 인라인 SVG 로 직접 그린다(필요 시 추후 plan 에서 작은 sparkline 모듈 추가). 이 제약은 self-contained 정책의 BLOCKING 요건.
-- Slim MD 가 제거하는 항목은 **결정론적**이어야 한다. “LLM 이 보기에 안 중요해 보이는 문장”을 제거하지 않는다. 제거 규칙은 module docstring + `templates/reports/user-response.template.md` 헤더에 명시.
-- 사용자가 만든 user-response 파일은 `runs/<task-type>/user-responses/` 아래에 둔다. 이 경로는 새로 추가. validator 는 파일이 없어도 OK(사용자 의사결정이 필요 없는 run 일 수 있다); 있을 때만 스키마 검사.
-- **Slim/HTML 양쪽 모두에 대한 “absolutely preserve” invariant** (validator failure 방지 목적, BLOCKING):
-  - `## Verdict Card` 블록 전체 (셀 byte-identical 유지 — whitespace 정규화 금지)
-  - `## 2. Final Verdict` 표의 `Verdict Token` / `Direction` / `Next Step` 행
-  - `## 0. Clarification Response Carried In` (존재 시)
-  - `implementation-planning` 의 9개 substring (`Option Candidates` / `Trade-off` / `Recommended Option` / `Stepwise Execution Order` / `Dependency` / `Validation Checklist` / `Rollback` / `User Approval Request` / `Plan Body Verification` + `Gate result:`)
-  - `implementation` 의 §4.7 8개 sub-section substring (Approved Plan Reference / Commit List / Diff Summary / Out-of-plan Edits / Validation Evidence / Verifier Results / Rollback Verification / Routing Recommendation)
-  - `final-verification` 의 §4.8 6개 sub-section substring (Source Implementation Report / Acceptance Blockers / Residual Risk / Validation Evidence / Read-only Command Log / Routing Recommendation)
-  - `release-handoff` 의 §4.6 모든 sub-section (4.6.1–4.6.7) **포함 §4.6.6 Merge Conflict Probe**
-  Slim stripper 는 이 substring/블록이 포함된 행 또는 그 행에서 직접 참조하는 표/리스트 cell 을 제거하지 않는다. HTML renderer 도 같다(다만 `<details>` 접힘은 허용).
-- Pre-1.0 정책(MEMORY: `feedback_pre_v1_no_compat.md`): 기존 final-report 와 호환되지 않는 행 스키마 변경이 필요하면 즉시 도입한다. compat shim 만들지 않는다.
-
----
-
-## Tasks
-
-### Task 1 — Stripper + Renderer 모듈 (`report_views.py`) 작성
-
-- [ ] 1.1 입력/출력 spec 을 module docstring 에 fix. slim 의 제거 규칙(아래)을 enum 으로 명시:
-  - `STRIP_TOKEN_PLACEHOLDER_ZEROS` (`$0.00` 행 — `Codex/Gemini CLI 추가 비용` 만 예외로 keep)
-  - `STRIP_DECORATIVE_HR` (3개 이상 `---` 연속 구분선)
-  - `STRIP_VERDICT_DETAIL` (`§4.5.9 Verdict details` 의 wide matrix — `Verdict summary` 카드만 keep)
-  - `STRIP_INTRO_RECIPE` (“> **읽는 법**:” 인용 단락 — 정의 라인은 keep)
-  - `COLLAPSE_EMPTY_SECTIONS` (`- 후속 작업 없음.` / `- 합의 미달 항목 없음.` 류 한 줄 placeholder 는 keep, 그러나 그 위 빈 줄 2개 이상은 1개로 정규화)
-- [ ] 1.2 `slim_markdown` 구현 — line-based scanner. 정규식은 module top-level 에 컴파일.
-- [ ] 1.3 `render_html` 구현 — 원본 MD 를 자체 mini-parser(테이블 / 헤딩 / 코드블록 / 인용 / 리스트 / 인라인 코드 / link 만 지원)로 토큰화 후 HTML emit. 외부 markdown 라이브러리 import 금지(제로 의존성). 헤딩 ID 는 slugify. `<a class="toc">` 자동 생성.
-- [ ] 1.4 “User-response row” 검출 — Section 5/6/7 의 표 안에서 `Response ID` 컬럼이 비어 있지 않은 행을 만나면, 그 셀들을 `<form data-response-id="...">` 안에 wrap. 각 행 타입별 컨트롤 매핑:
-  - 자유 텍스트 응답 → `<textarea>`
-  - 단일 선택(예: accept / reject / hold) → `<select>` 또는 `<input type=radio>`
-  - 다중 선택 → `<input type=checkbox>` 그룹
-  - 승인 게이트 → `<input type=checkbox> I approve`
-  컨트롤 종류는 행의 `Response Type` 옵션 컬럼(또는 `templates/reports/user-response.template.md` 의 enum)으로 결정. 알 수 없으면 textarea fallback.
-  **제외 대상(폼 부착 금지):** §4.6 sub-sections(release-handoff deliverables — H1/H2/H3 메뉴로 이미 처리됨, §4.6.6 Merge Conflict Probe 포함), §4.7 sub-sections(implementation deliverables — read-only 결과 보고), §4.8 sub-sections(final-verification deliverables — 동일). 이들 섹션은 Response ID 가 있더라도 무시하고 raw 텍스트로 렌더한다.
-- [ ] 1.5 `serialize_user_response(form_payload)` 구현 — 입력은 JS 측에서 보낼 dict. 출력은 `user-response.template.md` 포맷의 문자열. Python 측에서도 호출 가능(server-side fallback 용)하지만 1차 구현은 JS 가 클라이언트에서 직접 같은 포맷을 만든다 — Python 의 이 함수는 **그 직렬화 결과가 스키마에 맞는지 검증**하는 reference (validator 가 호출).
-
-### Task 2 — `templates/reports/user-response.template.md` 작성
-
-- [ ] 2.1 frontmatter 스키마 정의: `task-key`, `task-type`, `seq`, `source-report`, `decisions[].id`, `decisions[].type`, `decisions[].value`, `decisions[].rationale?`, `created-by: user`, `created-at: <ISO>`.
-- [ ] 2.2 본문 포맷: Response ID 별로 `### D-001 — <title>` 헤딩 + `Type: <select|radio|checkbox|textarea|approval>` 라인 + `Value:` 블록 + 선택적 `Rationale:`.
-- [ ] 2.3 “Why” 주석 한 줄(`<!-- single source of truth: scripts/okstra_ctl/report_views.py serialize_user_response -->`).
-
-### Task 3 — HTML 자산 (`templates/reports/report.css`, `report.js`)
-
-- [ ] 3.1 `report.css` — 읽기 폭 80ch 최대, 테이블 sticky header, `details` 토글, 인쇄 대응(`@media print`). 색은 시스템 색(`Canvas` / `CanvasText`) 기반으로 다크모드 자동.
-- [ ] 3.2 `report.js` —
-  - `collectFormValues()` 함수: 모든 `[data-decision-id]` form 의 현재 값을 수집.
-  - `buildSidecarMarkdown(values)` 함수: `templates/reports/user-response.template.md` 스키마와 **byte-identical** 출력을 만들도록 작성. (Task 4 의 golden fixture 가 Python ↔ JS 결과를 동시 검증.)
-  - 상단/하단에 각각 `[Export decision sidecar]` 버튼, 출력 `<pre id="sidecar-output">`, `[Copy]` 버튼. Copy 는 `navigator.clipboard.writeText`, 실패 시 selectRange fallback.
-- [ ] 3.3 HTML renderer 는 빌드 시 두 파일을 `<style>` / `<script>` 로 인라인. 외부 참조 0.
-
-### Task 4 — Golden fixtures + 테스트
-
-- [ ] 4.1 `tests/fixtures/reports/golden-original.md` 작성 — 다음을 모두 포함: token 치환 후의 비용 행(`$26.55` 등), §4.5.9 Verdict details, §0 Clarification Response Carried In, §5 Clarification Items 표(Response ID 2개), §6 Recommended Next Steps(Response ID 1개 — approval), §7 Follow-up Tasks(자동 생성 1행). **추가로 phase-별 fixture 3개**: `golden-implementation.md`(§4.7 8 sub-section 모두 포함), `golden-final-verification.md`(§4.8 6 sub-section + Verdict Token=`accepted|conditional-accept|blocked` 한 케이스씩), `golden-release-handoff.md`(§4.6.1–4.6.7 모두 포함, §4.6.6 Merge Conflict Probe 포함). 각 fixture 의 slim/html 기대 산출물을 동봉.
-- [ ] 4.2 기대 산출물 작성 — `.slim.md`, `.html`. HTML 비교는 (a) DOCTYPE + 인라인 자산 strip, (b) whitespace normalize 후 byte diff.
-- [ ] 4.3 `tests/test_report_views.py` — slim/HTML round-trip + `serialize_user_response` 가 example payload 로 스키마 검증 통과 + JS 직렬화 결과(Node 로 `templates/reports/report.js` 의 `buildSidecarMarkdown` 호출)와 Python 결과가 동일한지 확인하는 cross-check.
-
-### Task 5 — Phase 6→7 sequence 통합
-
-- [ ] 5.1 `skills/okstra-report-writer/SKILL.md` — “Phase 6 → Phase 7 execution sequence (BLOCKING order)” 섹션에 **step 2.5 — Render report views (BLOCKING)** 를 추가. 명령:
-
-  ```bash
-  python3 scripts/okstra-render-report-views.py \
-    <runDirectoryPath>/reports/final-report-<task-type>-<seq>.md
-  ```
-
-  step 2 이후 step 3 이전. 실패 시 lead 가 자체 호출 후 fallback. 두 산출물(`*.slim.md`, `*.html`) 부재 시 validator 가 run 을 실패시킨다(아래 Task 6).
-- [ ] 5.2 Persistence Checklist 에 두 항목 추가:
-  - `[ ] Slim AI report: runs/<task-type>/reports/final-report-<task-type>-<seq>.slim.md`
-  - `[ ] Human HTML report: runs/<task-type>/reports/final-report-<task-type>-<seq>.html`
-- [ ] 5.3 `agents/workers/report-writer-worker.md` 의 required-reading 에 본 plan + `user-response.template.md` 추가. 단, **report-writer worker 자체는 HTML/slim 을 만들지 않는다** — 그건 phase 7 의 결정론적 스크립트의 책임. worker 는 원본 MD 만 쓴다(현재와 동일).
-- [ ] 5.4 `skills/okstra-report-writer/SKILL.md` 의 작성자 표기는 2026-05-17 머지의 **Report Owner: Claude lead / Report Author: `<Report writer worker | Claude lead (release-handoff or fallback)>`** 용어를 그대로 따른다(별도 신규 용어 도입 금지).
-- [ ] 5.5 Analysis worker(`claude/codex/gemini-worker.md`) 의 required-reading 은 **건드리지 않는다** — 2026-05-17 정정에서 final-report template 을 의도적으로 제외했다. slim/HTML renderer 는 그 worker 들의 입력이 아니다.
-
-### Task 6 — Validator
-
-- [ ] 6.1 `validators/validate-report-views.py` 작성 — 원본 MD 가 있는 run 폴더에서:
-  - 두 파생 파일이 존재하는가
-  - slim 의 헤딩 집합이 원본의 헤딩 집합의 부분집합인가
-  - **slim 이 `validators/validate-run.py` 가 검사하는 모든 substring(Verdict Card 셀, §2 Verdict Token, implementation-planning 9개, implementation §4.7 8개, final-verification §4.8 6개, release-handoff §4.6 + §4.6.6)을 원본과 byte-identical 로 보존하는가** — 신규 strip 규칙이 future validator 와 충돌하는 회귀를 차단.
-  - HTML 에서 검출된 Response ID 집합이 원본 MD 의 Response ID 집합과 동일한가
-  - HTML 의 §4.6 / §4.7 / §4.8 안에 `<form>` 또는 `<input>` 가 **없는가** (deliverable section 에 폼 부착 금지 규칙)
-  - 외부 URL(`http(s)://`) 이 HTML 의 `<script src>` / `<link href>` / `<img src>` 에 등장하지 않는가 (self-contained 보장)
-- [ ] 6.2 `validators/validate-run.py` 의 기존 phase-별 substring 검사 직후에 위 호출을 hook. 실패 시 `exit 1`. 2026-05-17 머지된 Verdict Card byte-match / §4.6.6 / verdict vocabulary / §4.7 / §4.8 검사와 같은 단계에서 실행되도록 한다.
-
-### Task 7 — Node CLI 위임 + 문서
-
-- [ ] 7.1 `src/commands/render-views.mjs` (또는 기존 command 디렉토리 규약에 맞춰) 추가. 단순히 `~/.okstra/lib/python/.../okstra-render-report-views.py` 를 spawn. 인자 파싱만 JS.
-- [ ] 7.2 `bin/okstra` 의 서브커맨드 라우팅 테이블에 등록.
-- [ ] 7.3 `node bin/okstra doctor` 가 새 스크립트의 존재 확인 항목을 출력하는지 확인(있으면 추가, 없으면 보류).
-- [ ] 7.4 `CHANGES.md` 한 줄 추가:
-  - `feat(report-views): Phase 7 이 final-report 외에 *.slim.md(AI용 토큰절약) + *.html(self-contained, 결정폼 포함) 두 view 를 자동 생성. 사용자 결정은 HTML 의 [Export decision sidecar] 버튼으로 markdown 직렬화 후 runs/<task-type>/decisions/ 에 저장. 사용자 영향: 보고서 디렉토리에 두 파일 추가, 원본 MD 형식 변경 없음.`
-
-### Task 8 — End-to-end smoke
-
-- [ ] 8.1 `tests-e2e/` 아래에 새 시나리오 추가(또는 기존 scenario-01 에 후속 step 추가): 작은 fake run 의 phase 6 산출물에 대해 render-views 를 호출하고, 두 파일이 생성되며 validator 가 통과하는지.
-- [ ] 8.2 실제 브라우저에서 HTML 을 열고 (a) form 선택, (b) Export 버튼 클릭, (c) `<pre>` 출력이 `serialize_user_response` Python 출력과 byte-match 하는지 수동 확인. (CLAUDE.md: UI 변경은 브라우저에서 직접 확인.)
-
----
-
-## Out of scope (본 plan 에서 하지 않음)
-
-- 사용자가 만든 decision sidecar 를 **다음 phase 의 lead 가 어떻게 소비하는지** 의 계약 변경. 그건 별도 plan 으로 다룬다 (phase profile 의 required-reading 에 sidecar 경로 추가, lead 가 sidecar 의 Response ID 별 응답을 prompt 에 어떻게 인용하는지 등).
-- 차트 라이브러리 도입. 현재는 인라인 SVG 의 sparkline 정도만. 본격적인 시각화는 후속 plan.
-- 원본 final-report 의 한국어 본문 자체를 줄이는 prompt-diet 작업(이건 v2 plan 의 P2 범위).
-- `release-handoff` 단독 lead 분기에서의 동작 차이. 일단 같은 스크립트를 호출하되, release-handoff 의 Section 4.6 은 사용자 결정 행이 이미 H1/H2/H3 메뉴로 처리되므로 form 부착 대상에서 제외하는 special-case 만 Task 1.4 단계에서 추가.
-
----
-
-## Open questions for approval
-
-다음 항목에 대해 사용자 응답을 기다린다 (구현 시작 전 BLOCKING):
-
-1. Response ID 컬럼을 Section 5/6/7 의 표 스키마에 **신설**해도 되는가? 또는 §5 의 기존 `C-*`(Clarification) ID 를 그대로 user-response 트리거로 재사용해야 하는가? — 후자라면 `templates/reports/final-report.template.md` 수정이 거의 0 이고, 8-column SSOT(`_common-contract.md §Clarification request policy`)와도 충돌하지 않는다. **권장: 재사용**.
-2. user-response 파일 위치를 `runs/<task-type>/user-responses/` 로 신설할까, 아니면 audit sidecar 와 같은 `runs/<task-type>/worker-results/` 디렉토리에 다른 prefix(`user-response-*.md`)로 둘까? 후자는 디렉토리 신설 없이 끝나지만 author 가 사람이라 audit 파일과 섞이는 부담이 있다.
-3. HTML 의 차트 표현은 1차에서는 “표 그대로 + 작은 인라인 SVG 진행바” 정도로 충분한가? (본격 차트는 후속 plan)
-4. 2026-05-17 머지로 추가된 §4.7 / §4.8 / §4.6.6 / Verdict Card 검사는 모두 substring 기반이다. slim stripper 가 “보존 invariant” 를 지키는지 검증하는 방법으로 **substring 검사를 그대로 재실행**하는 게 가장 안전한가, 아니면 별도 “preserved heading” 화이트리스트를 두는 게 맞나? **권장: 전자 — `validate-run.py` 의 substring 목록을 import 하여 동일 함수로 검사**하면 단일 reference point 가 유지된다.