okstra 0.46.0 → 0.48.0

package/docs/superpowers/plans/2026-06-04-coverage-critic.md

@@ -0,0 +1,516 @@
+# Coverage critic 구현 계획 (sub-project B1)
+
+> **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:** requirements-discovery / error-analysis / implementation-planning 에 opt-in coverage critic pass 를 추가한다 — Phase 5.5 직후 기존 worker 를 critic 프롬프트로 재사용 dispatch 하고, gap 은 1회 적대적 reverify 후 병합. 사용 여부·provider 는 okstra-run select box(또는 `--critic` 플래그)로 고른다.
+
+**Architecture:** 백엔드는 `convergence.critic {enabled,provider,modelExecutionValue}` manifest 블록 — `render._build_convergence_block` 가 ctx `CRITIC_CHOICE` + 기존 `*_MODEL_EXECUTION_VALUE` 로 해석. 선택은 `--critic` CLI 플래그 + okstra-run wizard `S_CRITIC_PICK` step(플래그 미지정 시에만 표시). critic *행동*(gap 탐색·1회 적대 reverify·병합)은 convergence skill + lead/profile 의 prompt 지시(런타임 강제 아님).
+
+**Tech Stack:** Python 3 (okstra_ctl: run/render/wizard, pytest), wizard prompts JSON, Markdown skill/prompt 문서. 빌드: `npm run build`.
+
+**설계 근거:** [`docs/superpowers/specs/2026-06-04-coverage-critic-design.md`](../specs/2026-06-04-coverage-critic-design.md)
+
+---
+
+## 파일 구조
+
+| 파일 | 책임 | 작업 |
+|---|---|---|
+| [`scripts/okstra_ctl/run.py`](../../../scripts/okstra_ctl/run.py) | `--critic` 플래그 + `PrepareInputs.critic` + ctx `CRITIC_CHOICE` + canonical_argv + 값 검증 | Modify |
+| [`scripts/okstra_ctl/render.py`](../../../scripts/okstra_ctl/render.py) | `_build_convergence_block` 에 `critic` 블록 (phase-gated) | Modify (899–) |
+| `tests/test_render_critic_block.py` | critic 블록 resolve 단위 테스트 | Create |
+| [`scripts/okstra_ctl/wizard.py`](../../../scripts/okstra_ctl/wizard.py) | `S_CRITIC_PICK` step (state/constant/build/submit/Step/finalize/summary) | Modify |
+| [`prompts/wizard/prompts.ko.json`](../../../prompts/wizard/prompts.ko.json) | `critic_pick` step label/options | Modify |
+| `tests/test_wizard_critic_pick.py` | wizard step build/submit/applies 테스트 | Create |
+| [`skills/okstra-convergence/SKILL.md`](../../../skills/okstra-convergence/SKILL.md) | "Coverage critic pass" 절 | Modify |
+| [`agents/SKILL.md`](../../../agents/SKILL.md) | Phase 5.5→6 critic pass + PROGRESS 라인 | Modify |
+| [`prompts/profiles/requirements-discovery.md`](../../../prompts/profiles/requirements-discovery.md) / [`error-analysis.md`](../../../prompts/profiles/error-analysis.md) / [`implementation-planning.md`](../../../prompts/profiles/implementation-planning.md) | coverage critic opt-in 선언 | Modify |
+| [`CHANGES.md`](../../../CHANGES.md) | 사용자 영향 항목 | Modify |
+
+작업 순서: 백엔드(run+render+test) → wizard(step+json+test) → convergence skill → agents+profiles → CHANGES+검증.
+
+---
+
+### B1-Task1: 백엔드 — `--critic` 플래그 + manifest `convergence.critic` 블록
+
+**Files:**
+- Modify: `scripts/okstra_ctl/run.py`
+- Modify: `scripts/okstra_ctl/render.py` (`_build_convergence_block`)
+- Create: `tests/test_render_critic_block.py`
+
+- [ ] **Step 1: 실패하는 render 테스트 작성**
+
+Create `tests/test_render_critic_block.py`:
+
+```python
+"""_build_convergence_block — coverage critic 블록 phase-gated resolve.
+
+critic 은 requirements-discovery / error-analysis / implementation-planning 에서만
+enabled 가능. provider 는 ctx CRITIC_CHOICE, 모델은 해당 provider 의
+*_MODEL_EXECUTION_VALUE 에서. 미지정/off/비적용 phase 면 disabled.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(_REPO_ROOT / "scripts"))
+
+from okstra_ctl.render import _build_convergence_block  # noqa: E402
+
+_MODEL_CTX = {
+    "CLAUDE_WORKER_MODEL_EXECUTION_VALUE": "opus",
+    "CODEX_WORKER_MODEL_EXECUTION_VALUE": "gpt-5.5",
+    "GEMINI_WORKER_MODEL_EXECUTION_VALUE": "auto",
+}
+
+
+def _ctx(task_type, critic_choice):
+    return {"TASK_TYPE": task_type, "CRITIC_CHOICE": critic_choice, **_MODEL_CTX}
+
+
+def test_critic_disabled_when_unset():
+    block = _build_convergence_block(_ctx("error-analysis", ""))
+    assert block["critic"] == {"enabled": False, "provider": None, "modelExecutionValue": None}
+
+
+def test_critic_disabled_when_off():
+    block = _build_convergence_block(_ctx("error-analysis", "off"))
+    assert block["critic"]["enabled"] is False
+
+
+@pytest.mark.parametrize("task_type", ["requirements-discovery", "error-analysis", "implementation-planning"])
+def test_critic_enabled_for_applicable_phases(task_type):
+    block = _build_convergence_block(_ctx(task_type, "claude"))
+    assert block["critic"] == {"enabled": True, "provider": "claude", "modelExecutionValue": "opus"}
+
+
+def test_critic_model_follows_provider():
+    block = _build_convergence_block(_ctx("error-analysis", "codex"))
+    assert block["critic"]["provider"] == "codex"
+    assert block["critic"]["modelExecutionValue"] == "gpt-5.5"
+
+
+@pytest.mark.parametrize("task_type", ["implementation", "final-verification", "release-handoff"])
+def test_critic_disabled_for_non_applicable_phases(task_type):
+    block = _build_convergence_block(_ctx(task_type, "claude"))
+    assert block["critic"]["enabled"] is False
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_render_critic_block.py -q`
+Expected: FAIL — `block` 에 `"critic"` 키 없음 (`KeyError`).
+
+- [ ] **Step 3: render `_build_convergence_block` 에 critic 블록 추가**
+
+`scripts/okstra_ctl/render.py` `_build_convergence_block` 의 `return { ... }` 직전(현재 `plan_verify_enabled = ...` 다음)에 삽입:
+
+```python
+    critic_choice = (ctx.get("CRITIC_CHOICE", "") or "").strip().lower()
+    critic_phases = {"requirements-discovery", "error-analysis", "implementation-planning"}
+    critic_exec_key = {
+        "claude": "CLAUDE_WORKER_MODEL_EXECUTION_VALUE",
+        "codex": "CODEX_WORKER_MODEL_EXECUTION_VALUE",
+        "gemini": "GEMINI_WORKER_MODEL_EXECUTION_VALUE",
+    }
+    critic_enabled = critic_choice in critic_exec_key and task_type in critic_phases
+    critic_block = {
+        "enabled": critic_enabled,
+        "provider": critic_choice if critic_enabled else None,
+        "modelExecutionValue": (ctx.get(critic_exec_key[critic_choice]) or None) if critic_enabled else None,
+    }
+```
+
+그리고 같은 함수의 반환 dict 에 `"planBodyVerification": {...}` 항목 **앞에** `"critic": critic_block,` 한 줄 추가. docstring 의 ctx knobs 목록에 한 줄 추가:
+
+```python
+    - `CRITIC_CHOICE`: "" | "off" | "claude" | "codex" | "gemini" — coverage critic
+      backing provider (enabled only for requirements-discovery / error-analysis /
+      implementation-planning); model taken from that provider's execution value.
+```
+
+- [ ] **Step 4: render 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_render_critic_block.py -q`
+Expected: PASS.
+
+- [ ] **Step 5: run.py — `--critic` 플래그 + PrepareInputs + ctx + canonical_argv + 검증**
+
+(5a) `PrepareInputs` dataclass 의 `executor: str = ""` 줄 다음에 추가:
+```python
+    critic: str = ""
+```
+
+(5b) argparse 의 `p.add_argument("--executor", default="")` 다음 줄에 추가:
+```python
+    p.add_argument("--critic", default="")
+```
+그리고 argparse 결과를 `PrepareInputs(...)` 로 묶는 생성부에 `critic=args.critic,` 를 (executor 인자 옆에) 추가. (생성부는 argparse 직후 `PrepareInputs(` 호출 — `executor=args.executor` 패턴을 그대로 따라 한 줄 추가.)
+
+(5c) `_canonical_argv` 의 pairs 리스트에서 `("--executor", ...)` 다음에 추가:
+```python
+        ("--critic", inp.critic or ctx.get("CRITIC_CHOICE", "")),
+```
+
+(5d) 모델 메타데이터 resolve 직후(executor binding 블록 시작 `# ---- executor binding` 줄 **앞**)에 critic 검증 + ctx 변수 삽입:
+```python
+    # ---- coverage critic choice (validated; phase-gating happens in render) ----
+    critic_choice = (inp.critic or "").strip().lower()
+    if critic_choice not in ("", "off", "claude", "codex", "gemini"):
+        raise PrepareError(
+            f"--critic must be one of: off, claude, codex, gemini (got: {critic_choice!r})"
+        )
+```
+(use whatever error type the file already raises for `--executor` validation — match the executor validator's exception class, seen near the `--executor must be one of` raise.)
+
+(5e) ctx dict 빌드부(`"RENDER_ONLY": ...` 등이 있는 dict)에 한 줄 추가:
+```python
+        "CRITIC_CHOICE": critic_choice,
+```
+
+- [ ] **Step 6: run.py 검증 동작 테스트 (수동)**
+
+Run: `python3 -c "import sys; sys.path.insert(0,'scripts'); from okstra_ctl.run import build_arg_parser" 2>/dev/null; python3 -m pytest tests/ -q -k "convergence or critic or plan_body"`
+Expected: PASS (critic 블록 테스트 + 기존 convergence/plan-body 테스트 무회귀).
+
+- [ ] **Step 7: 전체 빠른 회귀 + 커밋**
+
+Run: `python3 -m pytest tests/ -q`
+Expected: PASS (전체).
+
+```bash
+git add scripts/okstra_ctl/run.py scripts/okstra_ctl/render.py tests/test_render_critic_block.py
+git commit -m "feat(okstra_ctl): --critic flag + convergence.critic manifest block (phase-gated)"
+```
+
+---
+
+### B1-Task2: okstra-run wizard `S_CRITIC_PICK` step
+
+**Files:**
+- Modify: `scripts/okstra_ctl/wizard.py`
+- Modify: `prompts/wizard/prompts.ko.json`
+- Create: `tests/test_wizard_critic_pick.py`
+
+- [ ] **Step 1: 실패하는 wizard 테스트 작성**
+
+Create `tests/test_wizard_critic_pick.py`:
+
+```python
+"""S_CRITIC_PICK wizard step — coverage critic 선택.
+
+3 적용 phase 에서만 표시, 미선택 시. provider/off 를 state.critic 에 기록.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_REPO_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(_REPO_ROOT / "scripts"))
+
+from okstra_ctl import wizard as W  # noqa: E402
+
+
+def _state(task_type="error-analysis", critic=""):
+    s = W.WizardState(workspace_root=str(_REPO_ROOT))
+    s.task_type = task_type
+    s.critic = critic
+    return s
+
+
+def test_critic_pick_build_offers_off_and_provider_and_custom():
+    p = W._build_critic_pick(_state())
+    values = [o["value"] if isinstance(o, dict) else o.value for o in p.options]
+    assert "off" in values
+    assert "claude" in values
+
+
+def test_critic_pick_submit_records_provider():
+    s = _state()
+    W._submit_critic_pick(s, "codex")
+    assert s.critic == "codex"
+
+
+def test_critic_pick_submit_records_off():
+    s = _state()
+    W._submit_critic_pick(s, "off")
+    assert s.critic == "off"
+
+
+def test_critic_pick_submit_rejects_unknown():
+    s = _state()
+    with pytest.raises(W.WizardError):
+        W._submit_critic_pick(s, "bogus")
+
+
+@pytest.mark.parametrize("task_type", ["requirements-discovery", "error-analysis", "implementation-planning"])
+def test_critic_step_applies_for_three_phases_when_unset(task_type):
+    step = next(st for st in W.STEPS if st.id == W.S_CRITIC_PICK)
+    assert step.applies(_state(task_type=task_type, critic="")) is True
+
+
+@pytest.mark.parametrize("task_type", ["implementation", "final-verification", "release-handoff"])
+def test_critic_step_skipped_for_other_phases(task_type):
+    step = next(st for st in W.STEPS if st.id == W.S_CRITIC_PICK)
+    assert step.applies(_state(task_type=task_type, critic="")) is False
+
+
+def test_critic_step_skipped_when_preseeded():
+    step = next(st for st in W.STEPS if st.id == W.S_CRITIC_PICK)
+    assert step.applies(_state(task_type="error-analysis", critic="claude")) is False
+```
+
+NOTE (confirmed against wizard.py): the step list is the module-level `STEPS: list[Step]` (≈line 1806) and the `Step` dataclass field is `id` (≈line 617: `id`, `applies`, `build`, `submit`, `owns`). `Prompt` is constructed with `step=` (see `_build_executor`). `_opt(value, label)` returns `Option(value, label, description)`. The test above is already written to these confirmed names.
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_wizard_critic_pick.py -q`
+Expected: FAIL — `_build_critic_pick` / `S_CRITIC_PICK` 미정의 (`AttributeError`).
+
+- [ ] **Step 3: wizard 구현**
+
+(3a) `S_EXECUTOR = "executor"` 류 상수 근처에 추가:
+```python
+S_CRITIC_PICK = "critic_pick"
+```
+
+(3b) `WizardState` 의 `executor: str = ""` 줄 다음에 추가:
+```python
+    critic: str = ""
+```
+
+(3c) `_build_executor` / `_submit_executor` 패턴을 그대로 따라 새 함수 추가(파일 내 다른 `_build_*`/`_submit_*` 모음 근처):
+```python
+CRITIC_CHOICES = ["off", "claude", "codex", "gemini"]
+
+
+def _build_critic_pick(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, "critic_pick")
+    return Prompt(
+        step=S_CRITIC_PICK, kind="pick",
+        label=t["label"],
+        options=[_opt(k, v) for k, v in t["options"].items() if not k.startswith("_")],
+        echo_template=t["echo_template"],
+    )
+
+
+def _submit_critic_pick(state: WizardState, value: str) -> Optional[str]:
+    if value not in CRITIC_CHOICES:
+        raise WizardError(f"critic must be one of {CRITIC_CHOICES}, got: {value!r}")
+    state.critic = value
+    return f"critic: {value}"
+```
+(If `Prompt`/`_opt`/`_p` signatures differ from what `_build_executor` uses, mirror `_build_executor` exactly — it is the canonical static-pick precedent.)
+
+(3d) `Step(...)` 리스트(STEPS)에 `S_DEFAULTS_OR_CUSTOM` Step **앞에** 추가:
+```python
+    Step(S_CRITIC_PICK,
+         applies=lambda s: (s.task_type in ("requirements-discovery", "error-analysis", "implementation-planning")
+                            and not s.critic
+                            and S_CRITIC_PICK not in s.answered),
+         build=_build_critic_pick, submit=_submit_critic_pick,
+         owns=("critic",)),
+```
+
+(3e) finalize dict(반환 dict, `"executor": state.executor,` 가 있는 곳)에 추가:
+```python
+        "critic": state.critic,
+```
+
+(3f) summary 출력부(`executor` summary line 근처)에, 3 적용 phase 일 때 critic 줄 추가:
+```python
+    if state.task_type in ("requirements-discovery", "error-analysis", "implementation-planning"):
+        lines.append(f"  critic        : {state.critic or '(off)'}")
+```
+
+(3g) wizard `_cli` 의 argparse(pre-seed 용)에 `--critic` 추가하고 초기 state 에 반영 — `executor` 가 pre-seed 되는 방식을 그대로 따라 `--critic` 를 받아 `state.critic` 에 넣는다(없으면 빈 문자열). 이로써 플래그가 넘어오면 `not s.critic` 가 거짓이 되어 step 이 건너뛰어진다. (executor 의 pre-seed 경로를 grep 해 동일하게 배선.)
+
+- [ ] **Step 4: prompts.ko.json `critic_pick` 항목 추가**
+
+`prompts/wizard/prompts.ko.json` 에 새 키 추가(다른 step 항목과 같은 형식):
+```json
+"critic_pick": {
+  "label": "coverage critic 를 추가로 돌릴까요? (놓친 finding·각도를 캐는 검증 패스 — opt-in)",
+  "echo_template": "critic: {value}",
+  "options": {
+    "off": "사용 안 함 (기본·추천)",
+    "claude": "claude critic (추천)",
+    "직접 입력": "직접 입력 (codex / gemini 등 provider 직접 지정)"
+  }
+}
+```
+NOTE — "직접 입력" custom row (REQUIRED by the user's standing picker convention: 추천 1~2개 + 마지막 "직접 입력"). The codebase's custom-input mechanism is `PICK_TYPE_CUSTOM = "__free_input__"` (≈line 87) plus a per-field `*_pending_text` flag, used by pickers like `directive` / `task_group`. The fixed-choice `executor` step does NOT use it. So model the critic picker on a custom-input picker (grep `pending_text` and `PICK_TYPE_CUSTOM` and read e.g. the `directive` build/submit pair): the "직접 입력" row emits `PICK_TYPE_CUSTOM`, the wizard then prompts free text, and `_submit_critic_pick` receives that text (a provider string `codex`/`gemini`) and validates it against `CRITIC_CHOICES`. If wiring a full pending-text round is disproportionate for a closed 4-value enum, the acceptable fallback is to list all four values (`off`/`claude`/`codex`/`gemini`) as explicit options with "직접 입력" still present as the trailing custom row — but do NOT silently drop the custom row. Confirm the chosen approach in the implementer report.
+
+- [ ] **Step 5: wizard 테스트 통과 확인**
+
+Run: `python3 -m pytest tests/test_wizard_critic_pick.py -q`
+Expected: PASS.
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add scripts/okstra_ctl/wizard.py prompts/wizard/prompts.ko.json tests/test_wizard_critic_pick.py
+git commit -m "feat(okstra_ctl/wizard): S_CRITIC_PICK step for coverage critic selection"
+```
+
+---
+
+### B1-Task3: convergence SKILL.md — "Coverage critic pass" 절
+
+**Files:**
+- Modify: `skills/okstra-convergence/SKILL.md`
+
+- [ ] **Step 1: "Coverage critic pass" 절 추가**
+
+`## Output` 절(Phase 6 로 넘기는 정보) **앞에**(또는 §"Plan-body verification mode" 앞 적절한 위치에) 새 절 삽입:
+
+```markdown
+## Coverage critic pass
+
+Runs only when `convergence.critic.enabled == true` (set by `--critic <provider>` or the okstra-run `critic_pick` step; default off). Applies to `requirements-discovery`, `error-analysis`, and `implementation-planning`. This pass targets **coverage** (missed findings), distinct from convergence which targets **agreement quality**.
+
+### When
+After Phase 5.5 finding convergence completes (findings classified) and BEFORE the Phase 6 report-writer dispatch.
+
+### Dispatch (reused worker)
+Dispatch ONE pass to the `config.critic.provider`'s existing subagent (`claude-worker` / `codex-worker` / `gemini-worker`) with `model = config.critic.modelExecutionValue` — no new agent type. Result path: `runs/<task-type>/worker-results/<provider>-critic-<task-type>-<seq>.md`. The critic prompt seeds the consolidated findings and asks ONLY for coverage gaps:
+
+```
+You are the coverage critic for <task-key>. Below are the findings the workers
+already agreed on. Your ONLY job is to name what is MISSING:
+- files / directories / execution paths nobody inspected,
+- requirements or acceptance points with zero findings,
+- claims raised but never verified.
+For each gap, emit a NEW finding with evidence (file:line or the requirement quote).
+Do NOT restate an existing finding. If nothing is missing, say so explicitly.
+```
+
+### Gap verification (1 adversarial reverify round)
+Each critic gap enters the verification queue as a finding with `originWorker = "<provider>-critic"` and `source = "critic"`. The lead runs ONE adversarial reverify round (§"Adversarial Verification Mode" classifier) with the Phase 4 analysers (excluding the critic itself) as voters. Only gaps classified `full-consensus` / `partial-consensus` merge into the final report findings; `contested` / `worker-unique` gaps are treated as hallucinations and dropped (recorded in the convergence state, not promoted). If fewer than one non-critic analyser is available to vote, the gaps are surfaced as unverified `clarification` items rather than merged, and that fact is recorded.
+
+### State
+- `convergence.critic` manifest block: `{ enabled, provider, modelExecutionValue }`.
+- Convergence state artifact: critic gaps appear in `findings[]` with `source: "critic"`. Add a `config.critic` summary `{ provider, modelExecutionValue, gapsProposed, gapsMerged }`. `source` and `config.critic` are optional v1.2 fields (readers treat absence as null); no enum changes.
+```
+
+- [ ] **Step 2: 빌드 + 검증**
+
+Run: `npm run build && bash validators/validate-workflow.sh`
+Expected: build 22/22 synced, validator PASS.
+
+- [ ] **Step 3: 커밋**
+
+```bash
+git add skills/okstra-convergence/SKILL.md runtime/
+git commit -m "feat(skills/okstra-convergence): define coverage critic pass"
+```
+
+---
+
+### B1-Task4: agents/SKILL.md 흐름 + 3 프로필 opt-in 선언
+
+**Files:**
+- Modify: `agents/SKILL.md`
+- Modify: `prompts/profiles/requirements-discovery.md`, `error-analysis.md`, `implementation-planning.md`
+
+- [ ] **Step 1: agents/SKILL.md — Phase 5.5→6 critic pass + PROGRESS**
+
+(1a) lead phase 표/Phase 6 설명에서 Phase 5.5 와 Phase 6 사이에 한 줄 추가(Phase 5.5 행 설명 끝 또는 Phase 6 행 앞):
+```markdown
+| 5.6 Coverage critic | (opt-in) reused-worker critic pass for missed findings, 1 adversarial reverify round | `okstra-convergence` "Coverage critic pass" |
+```
+(표 컬럼 수에 맞춰 기존 행 형식대로.)
+
+(1b) Progress reporting 체크포인트 목록에서 `PROGRESS: phase-6-synthesis ...` 줄 **앞에** 추가:
+```markdown
+- `PROGRESS: phase-5.6-critic provider=<provider> gaps=<n>` — when the coverage critic pass runs (Phase 5.6, opt-in). Omitted when `convergence.critic.enabled == false`.
+```
+
+- [ ] **Step 2: 3 프로필에 coverage critic opt-in 선언**
+
+세 파일 각각의 `- Cross-verification mode:` bullet(requirements-discovery / error-analysis 는 직전 sub-project 가 추가한 bullet; implementation-planning 도 동일 bullet 존재) 아래에 sub-bullet 추가. requirements-discovery 예:
+```markdown
+  - **Coverage critic (opt-in)**: when `convergence.critic.enabled=true` (chosen via `--critic` or the okstra-run picker), a reused-worker critic pass runs after convergence to surface missed findings; its gaps are merged only after a 1-round adversarial reverify. See `skills/okstra-convergence/SKILL.md` "Coverage critic pass".
+```
+error-analysis / implementation-planning 도 동일 문장(phase 명만 자연스럽게). requirements-discovery / error-analysis 가 `- Cross-verification mode:` bullet 을 아직 안 가졌다면(직전 sub-project 가 error-analysis 에 추가했는지 확인 — 안 했으면 새 `- Cross-verification mode:` top-level bullet 을 `- Non-goals:` 앞에 만들고 그 안에 이 sub-bullet 을 넣는다).
+
+- [ ] **Step 3: 빌드 + 검증**
+
+Run: `npm run build && bash validators/validate-workflow.sh`
+Expected: build 성공, validator PASS.
+
+- [ ] **Step 4: 커밋**
+
+```bash
+git add agents/SKILL.md prompts/profiles/requirements-discovery.md prompts/profiles/error-analysis.md prompts/profiles/implementation-planning.md runtime/
+git commit -m "feat(agents,prompts/profiles): declare opt-in coverage critic pass"
+```
+
+---
+
+### B1-Task5: CHANGES + 전체 검증 + 최종 커밋
+
+**Files:**
+- Modify: `CHANGES.md`
+
+- [ ] **Step 1: CHANGES.md 항목 추가**
+
+`## 2026-06-04` 헤더 바로 다음, 기존 첫 `###` 블록 앞에 삽입:
+
+```markdown
+### feat(convergence): opt-in coverage critic — 놓친 finding 을 캐는 검증 패스
+
+- 워커들은 설계상 같은 질문을 triangulate 하므로 "아무도 안 본 각도" 는 구조적으로 비어 있다(커버리지 갭). requirements-discovery / error-analysis / implementation-planning 에 **opt-in coverage critic** 을 추가 — Phase 5.5 직후, 선택한 provider 의 기존 worker 를 critic 프롬프트로 재사용 dispatch 해 "빠진 파일/각도/요구사항" 을 새 finding 으로 내게 하고, 그 gap 은 **1회 적대적 reverify** 를 거쳐 살아남은 것만 최종 리포트에 병합한다(환각 gap 기각). 사용 여부·provider 는 okstra-run 초기 select box(추천 + 직접 입력) 또는 `--critic <off|claude|codex|gemini>` 로 고른다 — 플래그를 넘기면 선택 단계는 건너뛴다. 모델은 선택한 provider 의 모델을 따른다. **기본 off** 라 미선택 run 의 비용은 0.
+- 사용자 영향: 다음 release + `npx -y okstra@latest install` 후 적용. 이제 세 phase 에서 교차검증이 끝난 뒤 원하면 critic 패스를 켜 놓친 finding 을 한 번 더 캘 수 있다(기본 꺼짐). critic gap 은 적대적 검증을 통과해야 리포트에 들어가므로 근거 약한 gap 은 걸러진다. critic *행동*은 lead/워커 prompt 지시(LLM)이며, 강제되는 건 `--critic` 해석·`convergence.critic` manifest 형태·wizard step 뿐이다.
+```
+
+- [ ] **Step 2: 전체 검증**
+
+Run:
+```bash
+npm run build
+python3 -m pytest tests/ -q
+bash validators/validate-workflow.sh
+node bin/okstra --version
+```
+ALL must pass. pytest 실패가 1건이라도 있으면(단, `tests/test_okstra_worktree.py` 의 알려진 간헐 격리 flake 는 단독 재실행으로 확인) STOP + BLOCKED 보고.
+
+- [ ] **Step 3: 일관성 self-review**
+
+Run:
+```bash
+grep -rn "convergence.critic\|CRITIC_CHOICE\|critic_pick\|S_CRITIC_PICK\|Coverage critic" scripts/okstra_ctl/ skills/okstra-convergence/SKILL.md agents/SKILL.md prompts/ tests/ CHANGES.md
+```
+Confirm: `--critic`/CRITIC_CHOICE(run+render), critic_pick/S_CRITIC_PICK(wizard+json+test), convergence.critic(render+skill+profiles), Coverage critic(skill+agents+profiles+CHANGES) 가 정의/참조 일관. 댕글링 토큰 없음.
+
+- [ ] **Step 4: 최종 커밋**
+
+```bash
+git add CHANGES.md
+git commit -m "docs(changes): log opt-in coverage critic pass"
+```
+
+---
+
+## Self-Review (작성자 체크리스트)
+
+**1. Spec coverage**
+- §2.1 critic primitive(dispatch·1회 적대 reverify·병합·모델) → Task3(skill 정의) + Task1(모델/블록).
+- §2.2 wizard select + CLI bypass → Task2(S_CRITIC_PICK, pre-seed bypass) + Task1(`--critic`).
+- §2.3 manifest critic 블록 + render resolve → Task1.
+- §2.4 3 적용 phase → Task1(render phase-gate) + Task4(프로필 선언).
+- §3 데이터(manifest/state source/config.critic) → Task1 + Task3.
+- §4 변경 파일 → Task1–5 전부.
+- §5 enforcement(테스트 강제 vs prompt-only) → Task1/Task2 테스트, Task3/4 prompt 선언.
+- §7 수용기준 1–5 → Task2(wizard), Task1(manifest), Task3(skill), Task4(profile), Task5(검증).
+
+**2. Placeholder scan:** 코드 블록은 실제 내용. wizard 의 일부 anchor(STEPS 리스트명·Prompt 필드명·custom-input 인코딩)는 "read-before-edit + mirror executor step" 으로 명시 — 추측 금지 지시. TBD/TODO 없음.
+
+**3. 식별자 일관성:** `critic`(PrepareInputs/WizardState field), `CRITIC_CHOICE`(ctx), `S_CRITIC_PICK`/`critic_pick`(wizard step/json), `convergence.critic`(manifest), `source:"critic"`(state) — Task 간 동일 철자 확인.