okstra 0.47.0 → 0.49.0

package/docs/superpowers/plans/2026-06-05-acceptance-critic.md

@@ -0,0 +1,251 @@
+# Acceptance devil's-advocate critic 구현 계획 (sub-project B2)
+
+> **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:** B1 의 critic primitive 를 `final-verification` 으로 확장해 "받아들이면 안 되는 이유/놓친 acceptance blocker" 를 캐는 악마의 변호인 패스를 추가하고, 후보 blocker 를 confirm-or-downgrade(확인→Acceptance Blocker, 미확인→Residual Risk)로 검증해 verdict 에 반영한다.
+
+**Architecture:** selection·`--critic`·`convergence.critic` 블록·dispatch primitive 는 B1 그대로 재사용; 적용 phase 집합(render `critic_phases` + wizard `S_CRITIC_PICK.applies`)에 `final-verification` 만 추가. critic *행동*은 convergence skill 에서 phase 로 분기 — 3 finding-phase=coverage(B1), final-verification=acceptance devil's-advocate(신규, confirm-or-downgrade, Acceptance Blockers/Residual Risk 출력). 새 enum/validator 없음(기존 verdict↔blocker validator 재사용).
+
+**Tech Stack:** Python 3 (okstra_ctl: render/wizard, pytest), Markdown skill/prompt 문서. 빌드: `npm run build`.
+
+**설계 근거:** [`docs/superpowers/specs/2026-06-05-acceptance-critic-design.md`](../specs/2026-06-05-acceptance-critic-design.md)
+
+---
+
+## 파일 구조
+
+| 파일 | 책임 | 작업 |
+|---|---|---|
+| [`scripts/okstra_ctl/render.py`](../../../scripts/okstra_ctl/render.py) | `critic_phases` 에 final-verification 추가 | Modify (928) |
+| [`scripts/okstra_ctl/wizard.py`](../../../scripts/okstra_ctl/wizard.py) | `S_CRITIC_PICK.applies`(1979) + summary(2313) phase tuple 에 final-verification | Modify |
+| [`tests/test_render_critic_block.py`](../../../tests/test_render_critic_block.py) | final-verification 비적용→적용 플립 | Modify |
+| [`tests/test_wizard_critic_pick.py`](../../../tests/test_wizard_critic_pick.py) | final-verification skipped→applies 플립 | Modify |
+| [`skills/okstra-convergence/SKILL.md`](../../../skills/okstra-convergence/SKILL.md) | "Acceptance critic pass (final-verification)" 절 + Index | Modify |
+| [`prompts/profiles/final-verification.md`](../../../prompts/profiles/final-verification.md) | 악마의 변호인 critic opt-in 선언 + verdict 영향 | Modify |
+| [`agents/SKILL.md`](../../../agents/SKILL.md) | Phase 5.6 critic 가 final-verification 에도 적용 | Modify |
+| [`prompts/wizard/prompts.ko.json`](../../../prompts/wizard/prompts.ko.json) | `critic_pick` label phase-중립 일반화 | Modify |
+| [`CHANGES.md`](../../../CHANGES.md) | 사용자 영향 항목 | Modify |
+
+작업 순서: 적용 phase 확장(render+wizard+test) → convergence skill 모드 → 프로필+agents+label → CHANGES+검증.
+
+---
+
+### B2-Task1: 적용 phase 에 final-verification 추가 (render + wizard + 테스트 플립)
+
+**Files:**
+- Modify: `scripts/okstra_ctl/render.py:928`
+- Modify: `scripts/okstra_ctl/wizard.py` (1979, 2313)
+- Modify: `tests/test_render_critic_block.py`
+- Modify: `tests/test_wizard_critic_pick.py`
+
+- [ ] **Step 1: 테스트를 새 기대값으로 갱신 (red 유발)**
+
+(1a) `tests/test_render_critic_block.py`: `test_critic_enabled_for_applicable_phases` 의 parametrize 리스트에 `"final-verification"` 을 추가:
+```python
+@pytest.mark.parametrize("task_type", ["requirements-discovery", "error-analysis", "implementation-planning", "final-verification"])
+def test_critic_enabled_for_applicable_phases(task_type):
+```
+그리고 `test_critic_disabled_for_non_applicable_phases` 의 리스트에서 `"final-verification"` 을 삭제(남는 것: `["implementation", "release-handoff"]`).
+
+(1b) `tests/test_wizard_critic_pick.py`: `test_critic_step_applies_for_three_phases_when_unset` 의 parametrize 리스트에 `"final-verification"` 추가(원하면 함수명도 `_for_applicable_phases` 로 변경 — 선택). `test_critic_step_skipped_for_other_phases` 리스트에서 `"final-verification"` 삭제(남는 것: `["implementation", "release-handoff"]`).
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_render_critic_block.py tests/test_wizard_critic_pick.py -q`
+Expected: FAIL — final-verification 이 아직 critic 적용 phase 가 아님.
+
+- [ ] **Step 3: render + wizard 구현**
+
+(3a) `scripts/okstra_ctl/render.py:928` 의 줄
+`    critic_phases = {"requirements-discovery", "error-analysis", "implementation-planning"}`
+를:
+`    critic_phases = {"requirements-discovery", "error-analysis", "implementation-planning", "final-verification"}`
+
+(3b) `scripts/okstra_ctl/wizard.py` 의 `S_CRITIC_PICK` Step applies(현 1979) 의 phase tuple
+`s.task_type in ("requirements-discovery", "error-analysis", "implementation-planning")`
+를:
+`s.task_type in ("requirements-discovery", "error-analysis", "implementation-planning", "final-verification")`
+
+(3c) 같은 파일 summary 조건(현 2313) 의 동일 tuple 도 같은 4-phase tuple 로 교체.
+
+(주의: 이 phase tuple 이 wizard.py 에 두 곳 — applies, summary — 있다. 둘 다 갱신. grep `"requirements-discovery", "error-analysis", "implementation-planning"` 로 누락 확인.)
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_render_critic_block.py tests/test_wizard_critic_pick.py -q`
+Expected: PASS.
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/render.py scripts/okstra_ctl/wizard.py tests/test_render_critic_block.py tests/test_wizard_critic_pick.py
+git commit -m "feat(okstra_ctl): enable coverage critic selection for final-verification"
+```
+
+---
+
+### B2-Task2: convergence skill — Acceptance critic pass (final-verification) 모드
+
+**Files:**
+- Modify: `skills/okstra-convergence/SKILL.md`
+
+- [ ] **Step 1: 새 "## Acceptance critic pass (final-verification)" 절 추가**
+
+기존 `## Coverage critic pass` 절이 끝나는 지점 직후(다음 `## Output` 헤딩 **앞**)에 새 절 삽입:
+
+```markdown
+## Acceptance critic pass (final-verification)
+
+The `final-verification` phase reuses the SAME reused-worker dispatch as §"Coverage critic pass" (provider + `config.critic.modelExecutionValue` from the `convergence.critic` block; default off; same model-unresolved skip rule). Only the prompt, the verification semantics, and the output sink differ — final-verification's findings are defects/blockers, so the critic acts as an **acceptance devil's advocate** (find reasons NOT to accept), and its candidate blockers are NEVER dropped (that would suppress real defects).
+
+### Prompt
+```
+You are the acceptance devil's advocate for <task-key>. The delivered work is about
+to be judged for acceptance. Your ONLY job is to find reasons it should NOT be
+accepted — surface candidate acceptance BLOCKERS the verifiers may have missed:
+- requirements / acceptance points with no covering evidence,
+- DB / IO / SQL changes lacking real-execution evidence,
+- regressions or broken error paths,
+- scope / contract violations.
+For each, emit a candidate blocker with a one-line statement, evidence (file:line /
+log / test output), and a severity (critical / major / minor). Do NOT restate an
+existing Acceptance Blocker. If you find none, say so explicitly.
+```
+
+### Verification — confirm-or-downgrade (BLOCKING)
+Each candidate blocker is verified by the Phase 4 analysers (excluding the critic). Do NOT use the adversarial finding classifier's "uncertain → reject" rule here.
+- **Confirmed** (an analyser reproduces it or cites supporting evidence) → promote to a `## 4 Acceptance Blockers` row (keep severity + recommended follow-up phase).
+- **Not confirmed** (cannot reproduce, or evidence is weak) → **downgrade to a Residual Risk row — never drop it.** Record the escalation trigger so the user can re-judge a high-severity-but-unconfirmed candidate.
+
+### Verdict impact
+Promoted blockers enter `## 4 Acceptance Blockers`; since `accepted` requires zero blockers, the verdict moves to `conditional-accept` / `blocked` automatically. The existing verdict↔blocker consistency validator (`validators/validate-run.py` `_validate_final_verification_consistency`) enforces this unchanged — no new enum or validator.
+
+### State
+Critic output lives at `runs/final-verification/worker-results/<provider>-critic-final-verification-<seq>.md`. The convergence state `config.critic` summary (see §"Coverage critic pass") records `mode: "acceptance-devils-advocate"`, `candidatesProposed`, `confirmedBlockers`, `downgradedToResidual` (optional v1.2 fields; readers treat absence as null).
+```
+
+- [ ] **Step 2: Index 항목 추가**
+
+`## Index` 목록에서 `- [Coverage critic pass](#coverage-critic-pass)` 다음 줄에 추가:
+```markdown
+- [Acceptance critic pass (final-verification)](#acceptance-critic-pass-final-verification)
+```
+
+- [ ] **Step 3: 빌드 + 검증**
+
+Run: `npm run build && bash validators/validate-workflow.sh`
+Expected: build 22/22 synced, validator PASS.
+
+- [ ] **Step 4: 커밋**
+
+```bash
+git add skills/okstra-convergence/SKILL.md runtime/
+git commit -m "feat(skills/okstra-convergence): acceptance devil's-advocate critic mode for final-verification"
+```
+
+---
+
+### B2-Task3: final-verification 프로필 + agents/SKILL.md + label 일반화
+
+**Files:**
+- Modify: `prompts/profiles/final-verification.md`
+- Modify: `agents/SKILL.md`
+- Modify: `prompts/wizard/prompts.ko.json`
+
+- [ ] **Step 1: final-verification 프로필에 critic opt-in 선언**
+
+`prompts/profiles/final-verification.md` 의 `- Non-goals:` 줄(현 47) **앞에** 새 top-level bullet 삽입:
+
+```markdown
+- Cross-verification mode:
+  - **Acceptance critic (opt-in)**: when `convergence.critic.enabled=true` (chosen via the okstra-run picker or `--critic`), a reused-worker **acceptance devil's-advocate** pass runs after convergence to surface candidate acceptance blockers the verifiers may have missed. Each candidate is verified **confirm-or-downgrade**: confirmed → an `Acceptance Blockers` row (which, since `accepted` requires zero blockers, moves the verdict to `conditional-accept` / `blocked`); unconfirmed → a `Residual Risk` row (never dropped). See `skills/okstra-convergence/SKILL.md` "Acceptance critic pass (final-verification)".
+```
+
+- [ ] **Step 2: agents/SKILL.md — Phase 5.6 행이 final-verification 도 커버함을 명시**
+
+`agents/SKILL.md` 의 `| 5.6 Coverage critic | ... |` 행을 찾아, 설명 셀을 final-verification 모드도 포함하도록 보강. 행 텍스트를:
+```markdown
+| 5.6 Critic pass | (opt-in) reused-worker critic pass: coverage gaps (discovery/error-analysis/impl-planning) or acceptance devil's-advocate (final-verification), each verified one round | `okstra-convergence` "Coverage critic pass" / "Acceptance critic pass" |
+```
+로 교체(컬럼 수 유지). PROGRESS 라인(`phase-5.6-critic ...`)은 그대로 두되, 그 설명에 final-verification 도 포함됨을 한 구절 덧붙여도 좋다(선택).
+
+- [ ] **Step 3: prompts.ko.json critic_pick label 일반화**
+
+`prompts/wizard/prompts.ko.json` 의 `critic_pick.label` 이 현재 coverage 중심 문구라면 phase-중립으로 일반화:
+```json
+"label": "추가 critic 패스를 돌릴까요? (놓친 finding/blocker 를 캐는 검증 패스 — opt-in)",
+```
+(label 만 변경; options/echo_template 불변.)
+
+- [ ] **Step 4: 빌드 + 검증**
+
+Run: `npm run build && bash validators/validate-workflow.sh`
+Expected: build 성공, validator PASS.
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add prompts/profiles/final-verification.md agents/SKILL.md prompts/wizard/prompts.ko.json runtime/
+git commit -m "feat(profiles,agents): declare acceptance devil's-advocate critic for final-verification"
+```
+
+---
+
+### B2-Task4: CHANGES + 전체 검증 + 최종 커밋
+
+**Files:**
+- Modify: `CHANGES.md`
+
+- [ ] **Step 1: CHANGES.md 항목 추가**
+
+`## 2026-06-05` 날짜 헤더가 있으면 그 다음에, 없으면 파일 맨 위 `# 변경 이력` 설명 단락 다음에 새 `## 2026-06-05` 헤더를 만들고 그 아래에 삽입:
+
+```markdown
+### feat(convergence): final-verification 악마의 변호인 critic — 놓친 acceptance blocker 발굴
+
+- B1 의 opt-in critic 을 final-verification 으로 확장했다. 단, final-verification 의 finding 은 결함/blocker 이라 B1 의 적대적-drop 검증을 그대로 쓰면 "재현 못 한 진짜 결함" 을 억누른다. 그래서 여기서 critic 은 **악마의 변호인** — "받아들이면 안 되는 이유/놓친 acceptance blocker" 를 캐고 — 후보 blocker 는 **confirm-or-downgrade** 로 검증한다: analyser 가 확인하면 Acceptance Blocker 로 승격(→ `accepted` 는 blocker 0 을 요구하므로 verdict 가 conditional-accept/blocked 로 밀림), 확인 못 하면 **기각이 아니라 Residual Risk** 로 강등(추적 보존). 선택 UX·`--critic`·모델은 B1 그대로이고 적용 phase 에 final-verification 만 추가(이제 4 phase). 기본 off.
+- 사용자 영향: 다음 release + `npx -y okstra@latest install` 후 적용. 이제 final-verification 에서도 critic 을 켜면 검증자가 놓친 수용 차단 사유를 한 번 더 캐고, 확인된 것만 verdict 를 막고 미확인은 잔여 위험으로 남는다(기본 꺼짐). 새 verdict/validator 추가 없이 기존 verdict↔blocker 규칙으로 동작한다. critic *행동*은 lead/워커 prompt 지시(LLM).
+```
+
+- [ ] **Step 2: 전체 검증**
+
+Run:
+```bash
+npm run build
+python3 -m pytest tests/ -q
+bash validators/validate-workflow.sh
+node bin/okstra --version
+```
+ALL must pass. `tests/test_okstra_worktree.py` 의 알려진 간헐 flake 는 단독 재실행으로 확인. 그 외 실패 → STOP + BLOCKED.
+
+- [ ] **Step 3: 일관성 self-review**
+
+Run:
+```bash
+grep -rn "final-verification" scripts/okstra_ctl/render.py scripts/okstra_ctl/wizard.py | grep -i critic
+grep -rn "Acceptance critic\|acceptance-devils-advocate\|devil's-advocate\|confirm-or-downgrade" skills/okstra-convergence/SKILL.md prompts/profiles/final-verification.md CHANGES.md
+```
+Confirm: render/wizard 가 final-verification 을 critic 적용 phase 로 포함; skill·profile·CHANGES 가 악마의 변호인/confirm-or-downgrade 를 일관되게 기술. 댕글링 없음.
+
+- [ ] **Step 4: 최종 커밋**
+
+```bash
+git add CHANGES.md
+git commit -m "docs(changes): log acceptance devil's-advocate critic for final-verification"
+```
+
+---
+
+## Self-Review (작성자 체크리스트)
+
+**1. Spec coverage**
+- §2.1 적용 phase 확장 → B2-Task1(render+wizard) + B2-Task3(profile).
+- §2.2 악마의 변호인 모드(프롬프트·confirm-or-downgrade·verdict 연동) → B2-Task2(skill) + B2-Task3(profile 선언).
+- §2.3 상태 기록(config.critic mode/counts) → B2-Task2 State 단락.
+- §3 변경 파일 9종 → B2-Task1–4 전부.
+- §4 enforcement(render/wizard 테스트 + 기존 verdict validator 재사용) → B2-Task1 테스트, B2-Task2 명시.
+- §6 수용기준 1–5 → B2-Task1(1,2), B2-Task2(3), B2-Task3(4), B2-Task4(5).
+
+**2. Placeholder scan:** 코드/markdown 블록 실제 내용. TBD/TODO 없음.
+
+**3. 식별자 일관성:** `critic_phases`(render set), `S_CRITIC_PICK`(wizard, 불변), `convergence.critic`(B1, 불변), "Acceptance critic pass (final-verification)"(신규 절 제목, Task2 정의 → Task3 profile 참조 동일), `confirm-or-downgrade`/`acceptance-devils-advocate`(skill+CHANGES 동일 철자). 4 적용 phase 집합이 render(set)·wizard(applies+summary)에서 동일.

package/docs/superpowers/plans/2026-06-05-compact-markdown-report-tables.md

@@ -0,0 +1,323 @@
+# Compact markdown final-report tables (option X) 구현 계획
+
+> **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:** 정본 final-report `.md` 의 narrative 표를 `meta(<br> stack) + prose` 형태로 재구성해 markdown 에디터에서도 핵심 본문이 넓게 읽히게 한다. §5 Clarification 은 평면 유지.
+
+**Architecture:** 변경은 (1) jinja 템플릿 레이아웃 + i18n 라벨 1개, (2) `report_views._inline` 의 `<br>` 보존 + 이제 불필요한 grouping 분기 제거(§5 만 유지)에 한정. `data.json`·report-writer 계약 불변.
+
+**Tech Stack:** jinja2 템플릿, Python 3 (report_views, pytest), JSON i18n. 빌드 `npm run build`.
+
+**설계 근거:** [`docs/superpowers/specs/2026-06-05-compact-markdown-report-tables-design.md`](../specs/2026-06-05-compact-markdown-report-tables-design.md)
+
+**범위 메모:** spec 표 목록(§1, §1.1, §1.2, §3.1, §3.2, §4, Execution Status)에 더해 **§7 Follow-up Tasks** 도 동일 안전 md-merge 대상에 포함한다(코드가 컬럼 파싱하지 않음 — §5 와 달리 안전, 일관성 확보). §5 만 평면 예외.
+
+---
+
+## 파일 구조
+
+| 파일 | 책임 | 작업 |
+|---|---|---|
+| [`templates/reports/final-report.template.md`](../../../templates/reports/final-report.template.md) | §1/§1.1/§1.2/§3.1/§3.2/§4/§7/Exec 표를 meta+prose 로 | Modify |
+| [`templates/reports/i18n/ko.json`](../../../templates/reports/i18n/ko.json) · [`en.json`](../../../templates/reports/i18n/en.json) | `columns.recordMeta` 키 추가 | Modify |
+| [`scripts/okstra_ctl/report_views.py`](../../../scripts/okstra_ctl/report_views.py) | `_inline` `<br>` 보존; generic/Exec/§7 grouping 분기 제거(§5 유지) | Modify |
+| [`tests/test_report_views.py`](../../../tests/test_report_views.py) | `<br>` 보존 + §5 유지 + §1/§3/§4 plain 테스트 | Modify |
+| [`CHANGES.md`](../../../CHANGES.md) | 사용자 영향 항목 | Modify |
+
+작업 순서: 템플릿+i18n(.md 구조) → report_views(`<br>` 보존 + 분기 정리) → CHANGES + 전체 검증 + 실제 재렌더.
+
+---
+
+### Task 1: 템플릿 + i18n — narrative 표를 meta(`<br>`)+prose 로
+
+**Files:**
+- Modify: `templates/reports/i18n/ko.json`, `templates/reports/i18n/en.json`
+- Modify: `templates/reports/final-report.template.md`
+
+- [ ] **Step 1: i18n 에 meta 헤더 키 추가**
+
+`templates/reports/i18n/ko.json` 의 `"columns"` 객체에 추가: `"recordMeta": "항목"`.
+`templates/reports/i18n/en.json` 의 `"columns"` 객체에 추가: `"recordMeta": "Record"`.
+
+- [ ] **Step 2: §1 Summary 표 교체**
+
+`templates/reports/final-report.template.md` 의 §1 표 블록
+```
+| ID | Ticket ID | {{ t("columns.summary") }} | {{ t("columns.source") }} |
+|----|-----------|------------|----------------------------|
+{% for row in summary -%}
+| {{ row.id }} | `{{ row.ticketId }}` | {{ row.summary }} | {{ row.source }} |
+{% endfor %}
+```
+를 다음으로 교체:
+```
+| {{ t("columns.recordMeta") }} | {{ t("columns.summary") }} |
+|--------|------------|
+{% for row in summary -%}
+| **{{ row.id }}**<br>Ticket: `{{ row.ticketId }}`<br>{{ t("columns.source") }}: {{ row.source }} | {{ row.summary }} |
+{% endfor %}
+```
+
+- [ ] **Step 3: §1.1 Consensus 표 교체**
+
+```
+| ID | Ticket ID | Statement | Source items (worker:item) | Evidence (path:line / log / worker report) |
+|----|-----------|-----------|----------------------------|---------------------------------------------|
+{% for row in crossVerification.consensus -%}
+| {{ row.id }} | `{{ row.ticketId }}` | {{ row.statement }} | {{ row.sourceItems | join(', ') }} | {{ row.evidence }} |
+{% endfor %}
+```
+를:
+```
+| {{ t("columns.recordMeta") }} | Statement | Evidence (path:line / log / worker report) |
+|--------|-----------|---------------------------------------------|
+{% for row in crossVerification.consensus -%}
+| **{{ row.id }}**<br>Ticket: `{{ row.ticketId }}`<br>Source items: {{ row.sourceItems | join(', ') }} | {{ row.statement }} | {{ row.evidence }} |
+{% endfor %}
+```
+
+- [ ] **Step 4: §1.2 Differences 표 교체**
+
+```
+| ID | Ticket ID | Disagreement | Workers (position + item) | Evidence |
+|----|-----------|--------------|---------------------------|----------|
+{% for row in crossVerification.differences -%}
+| {{ row.id }} | `{{ row.ticketId }}` | {{ row.disagreement }} | {% for w in row.workersPosition %}{{ w.worker }}:{{ w.itemId }} ({{ w.position }}){% if not loop.last %} / {% endif %}{% endfor %} | {{ row.evidence }} |
+{% endfor %}
+```
+를:
+```
+| {{ t("columns.recordMeta") }} | Disagreement | Evidence |
+|--------|--------------|----------|
+{% for row in crossVerification.differences -%}
+| **{{ row.id }}**<br>Ticket: `{{ row.ticketId }}`<br>Workers: {% for w in row.workersPosition %}{{ w.worker }}:{{ w.itemId }} ({{ w.position }}){% if not loop.last %} / {% endif %}{% endfor %} | {{ row.disagreement }} | {{ row.evidence }} |
+{% endfor %}
+```
+
+- [ ] **Step 5: §3.1 Primary Evidence 표 교체**
+
+```
+| ID | Ticket ID | Evidence | Source items (worker:item) | Source (path:line / log) |
+|----|-----------|----------|----------------------------|---------------------------|
+{% for row in evidence.primary -%}
+| {{ row.id }} | `{{ row.ticketId }}` | {{ row.evidence }} | {{ row.sourceItems | join(', ') }} | {{ row.source }} |
+{% endfor %}
+```
+를:
+```
+| {{ t("columns.recordMeta") }} | Evidence |
+|--------|----------|
+{% for row in evidence.primary -%}
+| **{{ row.id }}**<br>Ticket: `{{ row.ticketId }}`<br>Source items: {{ row.sourceItems | join(', ') }}<br>Source: {{ row.source }} | {{ row.evidence }} |
+{% endfor %}
+```
+
+- [ ] **Step 6: §3.2 Secondary 표 교체**
+
+```
+| ID | Ticket ID | Hypothesis or supporting evidence | Source / confidence |
+|----|-----------|-----------------------------------|---------------------|
+{% for row in evidence.secondary -%}
+| {{ row.id }} | `{{ row.ticketId }}` | {{ row.hypothesis }} | {{ row.confidence }} |
+{% endfor %}
+```
+를:
+```
+| {{ t("columns.recordMeta") }} | Hypothesis or supporting evidence | Source / confidence |
+|--------|-----------------------------------|---------------------|
+{% for row in evidence.secondary -%}
+| **{{ row.id }}**<br>Ticket: `{{ row.ticketId }}` | {{ row.hypothesis }} | {{ row.confidence }} |
+{% endfor %}
+```
+
+- [ ] **Step 7: §4 Risks 표 교체**
+
+```
+| ID | Ticket ID | Item | Risk if ignored | Mitigation Owner |
+|----|-----------|------|-----------------|------------------|
+{% for row in missingInformation -%}
+| {{ row.id }} | `{{ row.ticketId }}` | {{ row.item }} | {{ row.risk }} | {{ row.owner }} |
+```
+의 헤더/구분/row 3줄을:
+```
+| {{ t("columns.recordMeta") }} | Item | Risk if ignored | Mitigation Owner |
+|--------|------|-----------------|------------------|
+{% for row in missingInformation -%}
+| **{{ row.id }}**<br>Ticket: `{{ row.ticketId }}` | {{ row.item }} | {{ row.risk }} | {{ row.owner }} |
+```
+(`{% endfor %}` 이후는 그대로.)
+
+- [ ] **Step 8: Execution Status 표 교체**
+
+```
+| Agent | Role | Model | Status | {{ t("columns.rawTokens") }} | {{ t("columns.billableTokens") }} | {{ t("columns.cost") }} | Duration | Summary of Key Findings |
+|-------|------|-------|--------|-----------|-----------|------------|----------|-------------------------|
+{% for row in executionStatus -%}
+| {{ row.agent }} | {{ row.role }} | {{ row.model }} | {{ row.status }} | {{ row.totalTokens | format_int }}{% if row.cliTotalTokens %} (CLI: {{ row.cliTotalTokens | format_int }}){% endif %} | {{ row.billableTokens | format_int }} | {{ row.costUsd | format_usd }}{% if row.cliCostUsd %} (+ CLI {{ row.cliCostUsd | format_usd }}){% endif %} | {{ row.durationMs | format_duration_ms }} | {{ row.summary }} |
+{% endfor %}
+```
+를:
+```
+| {{ t("columns.recordMeta") }} | Summary of Key Findings |
+|--------|-------------------------|
+{% for row in executionStatus -%}
+| **{{ row.agent }}**<br>Role: {{ row.role }}<br>Model: {{ row.model }}<br>Status: {{ row.status }}<br>{{ t("columns.rawTokens") }}: {{ row.totalTokens | format_int }}{% if row.cliTotalTokens %} (CLI: {{ row.cliTotalTokens | format_int }}){% endif %}<br>{{ t("columns.billableTokens") }}: {{ row.billableTokens | format_int }}<br>{{ t("columns.cost") }}: {{ row.costUsd | format_usd }}{% if row.cliCostUsd %} (+ CLI {{ row.cliCostUsd | format_usd }}){% endif %}<br>Duration: {{ row.durationMs | format_duration_ms }} | {{ row.summary }} |
+{% endfor %}
+```
+
+- [ ] **Step 9: §7 Follow-up Tasks 표 교체**
+
+§7 표를 찾아(헤더에 `Title` / `Scope` / `Reason`), 짧은 컬럼(ID, Ticket ID, Origin, New Task ID, Suggested task-type, Priority, Auto-spawn 등)을 meta 셀에 `<br>` stack 하고 Title/Scope/Reason 을 prose 컬럼으로 둔다. 헤더를 `| {{ t("columns.recordMeta") }} | Title | Scope (files/areas) | Reason / Why deferred |` 로, row 의 meta 셀은 `**{{ row.id }}**<br>Ticket: \`{{ row.ticketId }}\`<br>Origin: {{ row.origin }}<br>New Task ID: {{ row.newTaskId }}<br>Type: {{ row.suggestedTaskType }}<br>Priority: {{ row.priority }}<br>Auto-spawn: {{ row.autoSpawn }}` 로 구성(현 row 의 필드명을 그대로 사용 — 먼저 현 §7 row 의 jinja 필드명을 읽어 정확히 매핑할 것). 빈 상태 분기 유지.
+
+- [ ] **Step 10: §5 는 건드리지 않음 (확인)**
+
+§5 Clarification Items 의 8-컬럼 표(`| ID | Ticket ID | Kind | Statement | Expected form | Blocks | Status | User input |`)는 **변경하지 않는다**. grep 으로 §5 표가 8-컬럼 그대로인지 확인.
+
+- [ ] **Step 11: 렌더 스모크 + 커밋**
+
+기존 렌더 테스트로 회귀 확인 후, 픽스처 data.json 으로 렌더해 §1/§1.1/§1.2/§3.1/§3.2/§4/§7/Exec 가 `recordMeta` 헤더 + `<br>` 를 포함하고 §5 가 8-컬럼인지 확인:
+```bash
+python3 -m pytest tests/test_render_final_report.py tests/test_template_full_render_both_langs.py -q
+```
+Expected: PASS (템플릿 문법 OK). 실패 시 jinja 문법/필드명 교정.
+
+```bash
+git add templates/reports/final-report.template.md templates/reports/i18n/ko.json templates/reports/i18n/en.json
+git commit -m "feat(report-template): compact narrative tables as meta(<br>)+prose; §5 stays flat"
+```
+
+---
+
+### Task 2: report_views — `<br>` 보존 + grouping 분기 정리
+
+**Files:**
+- Modify: `scripts/okstra_ctl/report_views.py`
+- Modify: `tests/test_report_views.py`
+
+- [ ] **Step 1: 실패 테스트 작성 (`<br>` 보존 + §1 plain)**
+
+`tests/test_report_views.py` 끝에 추가:
+```python
+def test_inline_preserves_br_tags():
+    from okstra_ctl.report_views import _inline  # noqa: PLC0415
+    out = _inline("**C-1**<br>Ticket: `DEV-1`<br>Source items: claude:F-001")
+    assert "<br>" in out
+    assert "&lt;br&gt;" not in out
+    assert "<strong>C-1</strong>" in out
+    assert "<code>DEV-1</code>" in out
+
+
+def test_summary_meta_table_renders_plain_with_br():
+    # §1 Summary is now pre-merged in the .md (meta col + Summary col); the
+    # grouped-table branch must NOT fire (no separate `Ticket ID` column) and
+    # the <br> in the meta cell survives.
+    html_out = _emit(
+        "| 항목 | 한 줄 요약 |",
+        "| **P-001**<br>Ticket: `DEV-9184`<br>출처: task-brief.md:19 | " + ("on-the-fly 계산 전환 핵심 변경 " * 4) + " |",
+        section="1. Summary of the Problem or Verification Target",
+    )
+    assert 'class="grouped-table"' not in html_out
+    assert "<br>" in html_out
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_report_views.py -q -k "inline_preserves_br or summary_meta_table"`
+Expected: FAIL — `_inline` escapes `<br>`; §1 still hits the generic grouping branch (grouped-table present).
+
+- [ ] **Step 3: `_inline` 가 `<br>` 보존**
+
+`scripts/okstra_ctl/report_views.py` `_inline` 의 `return out` 직전에 추가:
+```python
+    # Preserve explicit <br> line breaks used inside compact meta cells (the
+    # markdown source intentionally stacks short fields with <br>). They are
+    # escaped to &lt;br&gt; by html.escape above; restore the tag.
+    out = out.replace("&lt;br&gt;", "<br>").replace("&lt;br/&gt;", "<br>").replace("&lt;br /&gt;", "<br>")
+```
+
+- [ ] **Step 4: generic/Exec/§7 grouping 분기 제거 (§5 유지)**
+
+`_grouped_table_spec` 에서 다음을 **삭제**:
+- "Execution Status by Agent" 분기 (`if len(norm) >= 3 and norm[0] == "Agent" ...`).
+- "§7 Follow-up Tasks" 분기 (`if any("Follow-up Tasks" in h ...)`).
+- generic "Ticket ID" 분기 (`if any(h == "Ticket ID" for h in norm): ...`) + 그 헬퍼 `_is_force_meta`, `_column_is_wide`, 상수 `_WIDE_PROSE_TOKENS`, `_FORCE_META_TOKENS`, `_WIDE_CONTENT_THRESHOLD`, `_FOLLOWUP_WIDE_PREFIXES` (이제 미사용).
+- **유지:** §5 Clarification 분기(Expected form/Statement/User input wide) + signature 의 `rows` 파라미터(호출부 호환). `rows` 가 더는 분기 로직에 안 쓰이면, 호출부 `_grouped_table_spec(header_cells, rows, section_path)` 도 `_grouped_table_spec(header_cells, section_path)` 로 되돌리고 시그니처에서 `rows` 제거(미사용 인자 정리).
+
+docstring 을 "§5 Clarification Items 만 grouped (interactive form). 나머지 narrative 표는 템플릿에서 이미 compact 하게 렌더되므로 여기서 grouping 하지 않는다." 로 갱신.
+
+- [ ] **Step 5: 통과 확인 + 기존 grouped 테스트 정리**
+
+Run: `python3 -m pytest tests/test_report_views.py -q`
+Expected: 신규 2개 PASS. **단, Task 직전(2343e30)에 추가한 §1/§3/§4 grouped 테스트**(`test_summary_table_groups_short_cols_and_widens_prose`, `test_risks_table_widens_item_risk_mitigation`)는 이제 의도가 바뀌었으므로 제거하거나 plain+`<br>` 기대로 갱신한다. `test_clarification_expected_form_is_wide_not_meta` 는 **유지**(§5 grouping 살아있음). 모든 report_views 테스트 PASS 확인.
+
+- [ ] **Step 6: 빌드 + 커밋**
+
+```bash
+npm run build && bash validators/validate-workflow.sh
+git add scripts/okstra_ctl/report_views.py tests/test_report_views.py runtime/
+git commit -m "refactor(report-views): preserve <br>; group only §5 (narrative tables compact in md)"
+```
+
+---
+
+### Task 3: CHANGES + 전체 검증 + 실제 재렌더
+
+**Files:**
+- Modify: `CHANGES.md`
+
+- [ ] **Step 1: CHANGES 항목 추가**
+
+`## 2026-06-05` 아래(직전 report-views 항목 근처)에 삽입:
+```markdown
+### feat(report-template): 정본 final-report `.md` 표를 compact 하게 (meta + prose)
+
+- markdown 표는 컬럼 병합이 안 돼 ID·Ticket·Source 같은 짧은 코드 컬럼이 칸을 차지하면 요약·근거·이견·위험 같은 긴 본문이 좁아져 뭉개졌다(에디터에서 한 글자/줄). 이제 §1 Summary·§1.1 Consensus·§1.2 Differences·§3.1/§3.2 Evidence·§4 Risks·§7 Follow-up·Execution Status 표를 **짧은 코드 필드는 `<br>` 로 한 meta 셀에 stack + 긴 본문은 별도 컬럼**으로 렌더한다. §5 Clarification 은 carry-in 파서·validator 8-컬럼 계약 때문에 평면 유지(§5 compact 는 HTML view grouping 담당). `data.json`·report-writer 계약은 불변(템플릿 레이아웃만). HTML self-contained view 도 `_inline` 이 `<br>` 를 보존해 동일하게 compact 하게 보인다.
+- 사용자 영향: 다음 release + `npx -y okstra@latest install` 후 적용. 이제 final-report 를 어떤 markdown 에디터로 열어도 핵심 본문이 넓게 읽힌다. `.md`↔HTML 레이아웃이 일관된다.
+```
+
+- [ ] **Step 2: 전체 검증**
+
+```bash
+npm run build
+python3 -m pytest tests/ -q
+bash validators/validate-workflow.sh
+node bin/okstra --version
+```
+ALL must pass (worktree 격리 flake 예외는 단독 재실행 확인). 그 외 실패 → STOP/BLOCKED.
+
+- [ ] **Step 3: 실제 재렌더 검증 (BLOCKING — 육안)**
+
+기존 사용자 리포트를 /tmp 복사본으로 재렌더하고 구조 확인:
+```bash
+SRC="/Volumes/Workspaces/workspace/projects/FontsNinja/app/fontradar-v2-api/.okstra/tasks/calcule-des-prix-1-1/dev-9184/runs/requirements-discovery/reports/final-report-requirements-discovery-001.data.json"
+```
+NOTE: HTML view 는 `.md` 에서 파생되므로, **새 템플릿으로 `.md` 를 다시 렌더**해야 한다. data.json → md 렌더는 `scripts/okstra-render-final-report.py`(또는 report-writer 경로) 사용. 해당 CLI 의 인자를 `--help` 로 확인 후, /tmp 에 새 `.md` 를 렌더하고:
+- 새 `.md` 의 §1/§1.1/§1.2/§3.1/§3.2/§4/§7/Exec 가 `**ID**<br>Ticket: …` meta 셀 + prose 컬럼인지,
+- §5 가 여전히 `| ID | Ticket ID | Kind | Statement | Expected form | Blocks | Status | User input |` 8-컬럼인지,
+- 그 `.md` 로 `okstra-render-report-views.py` 를 돌려 HTML 의 meta 셀이 `<br>` 줄바꿈으로 보이는지(literal `&lt;br&gt;` 아님),
+- `python3 -c "import sys; sys.path.insert(0,'scripts'); from okstra_ctl.clarification_items import parse_clarification_items; print(len(parse_clarification_items(open('<new-md>').read()) or []))"` 로 §5 carry-in 파서가 여전히 행을 파싱하는지
+확인. /tmp 산출물은 정리(사용자 프로젝트 파일은 건드리지 않음).
+
+- [ ] **Step 4: 최종 커밋**
+
+```bash
+git add CHANGES.md
+git commit -m "docs(changes): log compact markdown final-report tables"
+```
+
+---
+
+## Self-Review (작성자 체크리스트)
+
+**1. Spec coverage**
+- §2.1 대상 표 7종 + §7 → Task 1 Step 2–9.
+- §2.1 §5 평면 유지 → Task 1 Step 10 + 미변경.
+- §2.2 meta `<br>` 포맷 + i18n → Task 1 Step 1–9.
+- §2.3 `_inline` `<br>` 보존 → Task 2 Step 3.
+- §2.3 generic/Exec 분기 제거, §5 유지 → Task 2 Step 4(§7 도 제거).
+- §2.4 계약 불변 → Task 1(템플릿만), §5 미변경.
+- §4 검증(실제 재렌더 + §5 파서) → Task 3 Step 2–3.
+
+**2. Placeholder scan:** §7(Step 9)은 현 row 필드명을 "먼저 읽어 매핑"하라고 명시 — 구현자가 실제 필드명 확인 후 작성(추측 금지). 그 외 모든 jinja/코드 블록은 실제 내용. TBD 없음.
+
+**3. 식별자 일관성:** `columns.recordMeta`(i18n, Task1) ↔ 템플릿 헤더 사용 동일. `_inline`(Task2) ↔ report_views. `_grouped_table_spec` 시그니처에서 `rows` 제거 시 호출부도 함께(Task2 Step4 명시).