okstra 0.47.0 → 0.48.0

package/docs/superpowers/plans/2026-06-04-adversarial-implementation-planning.md

@@ -0,0 +1,294 @@
+# 적대적 모드 implementation-planning 확장 구현 계획 (sub-project A)
+
+> **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:** `implementation-planning` 의 finding convergence 를 기존 적대적 기계로 켜고, plan-body verification 에 적대적 *자세*(게이트 과반 유지)를 더한다.
+
+**Architecture:** `render.py` 의 `adversarial_phases` 집합에 `implementation-planning` 한 항목을 추가하면 finding convergence 가 적대적 기계를 상속한다. plan-body 는 convergence skill 에 "적대적 자세" 절을 추가해 프롬프트/입증책임만 바꾸고 classification·gate·validator 는 불변. 적대 phase 목록이 적힌 문서 6곳을 2→3개로 일치시킨다.
+
+**Tech Stack:** Python 3 (okstra_ctl, pytest), Markdown skill/prompt 문서. 빌드: `npm run build`.
+
+**설계 근거:** [`docs/superpowers/specs/2026-06-04-adversarial-implementation-planning-design.md`](../specs/2026-06-04-adversarial-implementation-planning-design.md)
+
+---
+
+## 파일 구조
+
+| 파일 | 책임 | 작업 |
+|---|---|---|
+| [`scripts/okstra_ctl/render.py`](../../../scripts/okstra_ctl/render.py) | `adversarial_phases` 에 implementation-planning 추가 | Modify (917, docstring 906) |
+| [`tests/test_render_convergence_adversarial.py`](../../../tests/test_render_convergence_adversarial.py) | impl-planning 을 적대 파라미터로 이동 | Modify |
+| [`tests/test_plan_body_verification.py`](../../../tests/test_plan_body_verification.py) | impl-planning convergence 블록 기대값 플립 | Modify (53–65) |
+| [`skills/okstra-convergence/SKILL.md`](../../../skills/okstra-convergence/SKILL.md) | phase-목록 3곳 + 비용근거 2곳 갱신, "Adversarial plan-body posture" 절 추가 | Modify |
+| [`prompts/profiles/implementation-planning.md`](../../../prompts/profiles/implementation-planning.md) | Phase 5.5 적대 + plan-body 적대 자세 선언 | Modify |
+| [`prompts/profiles/_common-contract.md`](../../../prompts/profiles/_common-contract.md) | Phase 5.5 문장에 impl-planning 추가 | Modify (17) |
+| [`agents/SKILL.md`](../../../agents/SKILL.md) | `convergence.adversarial` knob 행에 impl-planning 추가 | Modify |
+| [`CHANGES.md`](../../../CHANGES.md) | 사용자 영향 항목 | Modify |
+
+작업 순서: render+테스트(behavior) → convergence skill(plan-body 정의 + sweep) → 프로필/계약/agents 선언 → CHANGES + 전체 검증.
+
+---
+
+### Task 1: render.py — implementation-planning 적대화 + 테스트 플립
+
+**Files:**
+- Modify: `scripts/okstra_ctl/render.py` (`_build_convergence_block`, 917 + docstring 906)
+- Modify: `tests/test_render_convergence_adversarial.py`
+- Modify: `tests/test_plan_body_verification.py:53-65`
+
+- [ ] **Step 1: 테스트를 새 기대값으로 갱신 (red 유발)**
+
+(1a) `tests/test_render_convergence_adversarial.py` 의 모듈 docstring 3번째 줄
+`requirements-discovery / error-analysis 만 adversarial=true + full-reanalysis 를`
+를 다음으로 교체:
+`requirements-discovery / error-analysis / implementation-planning 이 adversarial=true + full-reanalysis 를`
+
+(1b) 같은 파일 `test_adversarial_phases_get_adversarial_full_reanalysis` 의 parametrize 리스트
+`@pytest.mark.parametrize("task_type", ["requirements-discovery", "error-analysis"])`
+를 다음으로 교체:
+`@pytest.mark.parametrize("task_type", ["requirements-discovery", "error-analysis", "implementation-planning"])`
+
+(1c) 같은 파일 `test_non_adversarial_phases_stay_lightweight` 의 parametrize 리스트에서 `"implementation-planning",` 줄을 삭제 (남는 목록: `"implementation"`, `"final-verification"`, `"release-handoff"`).
+
+(1d) `tests/test_plan_body_verification.py` 의 `test_convergence_block_default_for_implementation_planning` 기대 dict 를 교체:
+
+```python
+def test_convergence_block_default_for_implementation_planning(build_block):
+    block = build_block({"TASK_TYPE": "implementation-planning"})
+    assert block == {
+        "enabled": True,
+        "adversarial": True,
+        "maxRounds": 2,
+        "verificationMode": "full-reanalysis",
+        "planBodyVerification": {
+            "enabled": True,
+            "maxRounds": 1,
+            "gating": True,
+        },
+    }
+```
+
+- [ ] **Step 2: 실패 확인**
+
+Run: `python3 -m pytest tests/test_render_convergence_adversarial.py tests/test_plan_body_verification.py -q`
+Expected: FAIL — impl-planning 이 아직 `adversarial=False` 라 새 단언과 불일치.
+
+- [ ] **Step 3: render 구현**
+
+`scripts/okstra_ctl/render.py` `_build_convergence_block` 의 줄
+`    adversarial_phases = {"requirements-discovery", "error-analysis"}`
+를 다음으로 교체:
+`    adversarial_phases = {"requirements-discovery", "error-analysis", "implementation-planning"}`
+
+같은 함수 docstring 의 두 줄
+```
+    - `adversarial` default True for `requirements-discovery` / `error-analysis`
+      (forces `verificationMode` to "full-reanalysis"), False otherwise
+```
+를 다음으로 교체:
+```
+    - `adversarial` default True for `requirements-discovery` / `error-analysis` /
+      `implementation-planning` (forces `verificationMode` to "full-reanalysis"),
+      False otherwise
+```
+
+- [ ] **Step 4: 통과 확인**
+
+Run: `python3 -m pytest tests/test_render_convergence_adversarial.py tests/test_plan_body_verification.py -q`
+Expected: PASS (전부).
+
+- [ ] **Step 5: 커밋**
+
+```bash
+git add scripts/okstra_ctl/render.py tests/test_render_convergence_adversarial.py tests/test_plan_body_verification.py
+git commit -m "feat(okstra_ctl/render): turn on adversarial convergence for implementation-planning"
+```
+
+---
+
+### Task 2: convergence SKILL.md — plan-body 적대 자세 + phase-목록 sweep
+
+**Files:**
+- Modify: `skills/okstra-convergence/SKILL.md`
+
+- [ ] **Step 1: Configuration 표 `adversarial` 행 — phase 목록 3개로**
+
+찾기:
+`| `adversarial` | phase-aware: `true` for `requirements-discovery` / `error-analysis`, `false` otherwise |`
+의 앞부분을 다음으로 교체(행 뒷부분 설명은 그대로 유지):
+`| `adversarial` | phase-aware: `true` for `requirements-discovery` / `error-analysis` / `implementation-planning`, `false` otherwise |`
+
+- [ ] **Step 2: §"Adversarial Verification Mode" 전제 문장 — phase 목록 3개로**
+
+찾기:
+`Active only when `config.adversarial == true` (default for `requirements-discovery` and `error-analysis`; see §"Configuration").`
+교체:
+`Active only when `config.adversarial == true` (default for `requirements-discovery`, `error-analysis`, and `implementation-planning`; see §"Configuration").`
+
+- [ ] **Step 3: `config.adversarial` 스키마 불릿 — phase 목록 3개로**
+
+찾기(Schema rules 목록):
+`- `config.adversarial`: boolean. `true` when this run used adversarial verification (default for `requirements-discovery` / `error-analysis`).`
+교체(문장 나머지 "When `true`, …" 부분은 그대로 유지):
+`- `config.adversarial`: boolean. `true` when this run used adversarial verification (default for `requirements-discovery` / `error-analysis` / `implementation-planning`).`
+
+- [ ] **Step 4: 비용-근거 산문 2곳 — phase 목록 보강**
+
+(4a) §"Scoped full-reanalysis" 의 문장
+`This keeps the documented "single largest avoidable cost in requirements-discovery and error-analysis" (see §"Reverify prompt: required-reading suppression") bounded`
+를:
+`This keeps the documented "single largest avoidable cost in requirements-discovery, error-analysis, and implementation-planning" (see §"Reverify prompt: required-reading suppression") bounded`
+
+(4b) §"Reverify prompt: required-reading suppression" 의 문장
+`This is the single largest avoidable cost in `requirements-discovery` and `error-analysis` runs. Treat as BLOCKING.`
+를:
+`This is the single largest avoidable cost in `requirements-discovery`, `error-analysis`, and `implementation-planning` runs. Treat as BLOCKING.`
+
+- [ ] **Step 5: "Adversarial plan-body posture" 절 추가**
+
+§"Mode constraint" 블록 끝(`... lightweight is always used.` 줄) 다음, `### Round protocol` 헤딩 **앞에** 새 절 삽입:
+
+```markdown
+
+### Adversarial plan-body posture
+
+When `config.adversarial == true` (the default for `implementation-planning`; see §"Configuration"), the plan-body round runs with an **adversarial posture**. The classification rules and gate arithmetic in §"Round protocol" are UNCHANGED — `majority-disagree` (a *majority* of analysers DISAGREE) remains the only classification that blocks the Approval marker, and `dissent-isolated` still passes the gate. Adversarial mode changes only *how each verifier evaluates an item*:
+
+- The burden of proof sits on the plan: an item earns `AGREE` only if the verifier actively tried to break it and could not.
+- The verifier MUST open the file paths / symbols / commands the item cites and confirm they exist and are executable as written. This is the one allowed widening of the lightweight "judge from internal consistency and stated commands / paths" rule — confirming the existence of cited paths is not "re-analyzing the original requirements".
+- If a cited path / command / validation signal cannot be confirmed, the verifier responds `DISAGREE(<kind>)` with the applicable breakage kind (a–e); uncertainty resolves toward DISAGREE, not AGREE.
+
+This raises verification *quality* (active refutation, plan-side burden) without changing the gate *threshold* — a single dissent still does not block approval; a majority is required (deliberate sub-project A decision).
+```
+
+- [ ] **Step 6: plan-body reverify 프롬프트에 적대 framing 주입 지시**
+
+§"Plan-body reverify prompt" 의 프롬프트 코드펜스가 끝난 직후(다음 `###` 헤딩 `### Worker non-result handling in plan-body round` **앞**)에 한 문단 추가:
+
+```markdown
+When `config.adversarial == true`, the lead prepends the adversarial framing from §"Adversarial plan-body posture" to the `## Instructions` block: the burden of proof is on the plan, the verifier opens and confirms every cited path / command, and an item whose cited references cannot be confirmed is answered `DISAGREE(<kind>)` rather than `AGREE`. The verdict tokens, breakage kinds (a–e), classification, and the majority gate threshold are unchanged.
+```
+
+- [ ] **Step 7: 빌드 + 검증**
+
+Run: `npm run build && bash validators/validate-workflow.sh`
+Expected: build 22/22 synced, validator PASS.
+
+- [ ] **Step 8: 커밋**
+
+```bash
+git add skills/okstra-convergence/SKILL.md runtime/
+git commit -m "feat(skills/okstra-convergence): adversarial plan-body posture + 3-phase adversarial list"
+```
+
+---
+
+### Task 3: 프로필 + 공통계약 + agents 선언
+
+**Files:**
+- Modify: `prompts/profiles/implementation-planning.md`
+- Modify: `prompts/profiles/_common-contract.md`
+- Modify: `agents/SKILL.md`
+
+- [ ] **Step 1: implementation-planning 프로필 — Cross-verification mode 선언**
+
+`prompts/profiles/implementation-planning.md` 의 `- Non-goals:` 줄(현 40) **앞에** 삽입:
+
+```markdown
+- Cross-verification mode:
+  - Phase 5.5 finding convergence runs in **adversarial mode** for this phase (`convergence.adversarial=true`). Verifiers actively try to refute each worker finding (requirement gap / risk / option) by re-inspecting its cited evidence; the burden of proof sits on the claim. See `skills/okstra-convergence/SKILL.md` §"Adversarial Verification Mode".
+  - §4.5.9 plan-body verification runs with an **adversarial posture** (`skills/okstra-convergence/SKILL.md` §"Adversarial plan-body posture"): verifiers open and confirm every cited path / command and put the burden of proof on the plan. The gate threshold is unchanged — a *majority* `DISAGREE` (`majority-disagree`) is still required to block approval; a single dissent does not.
+```
+
+- [ ] **Step 2: implementation-planning 프로필 — §4.5.9 BLOCKING 불릿에 적대 자세 한 문장**
+
+`prompts/profiles/implementation-planning.md` 의 §4.5.9 BLOCKING 불릿(현 77, `**§4.5.9 Plan Body Verification (BLOCKING).**` 로 시작) 문장 끝
+`... that is a contract violation.`
+다음에 한 문장 추가(같은 불릿 내):
+` When `convergence.adversarial=true` (the default for this phase), this round uses the adversarial posture — verifiers confirm cited paths/commands and the burden of proof is on the plan — but the gate threshold stays `majority-disagree` (see that skill's §"Adversarial plan-body posture").`
+
+- [ ] **Step 3: _common-contract.md — Phase 5.5 문장에 impl-planning 추가**
+
+`prompts/profiles/_common-contract.md` 의 Phase 5.5 불릿(현 17) 끝 문장
+`For `requirements-discovery` and `error-analysis` this phase runs in **adversarial mode** (`convergence.adversarial=true`): verifiers try to refute each finding against its cited evidence and the burden of proof sits on the claim — see that skill's §"Adversarial Verification Mode".`
+의 앞부분 phase 목록을 교체:
+`For `requirements-discovery`, `error-analysis`, and `implementation-planning` this phase runs in **adversarial mode** (`convergence.adversarial=true`): verifiers try to refute each finding against its cited evidence and the burden of proof sits on the claim — see that skill's §"Adversarial Verification Mode".`
+
+- [ ] **Step 4: agents/SKILL.md — convergence.adversarial knob 행에 impl-planning 추가**
+
+`agents/SKILL.md` 의 `- `convergence.adversarial`:` 로 시작하는 줄에서 phase 목록
+`**phase-aware default**: `true` for `requirements-discovery` / `error-analysis`, `false` otherwise.`
+를:
+`**phase-aware default**: `true` for `requirements-discovery` / `error-analysis` / `implementation-planning`, `false` otherwise.`
+
+- [ ] **Step 5: 빌드 + 검증**
+
+Run: `npm run build && bash validators/validate-workflow.sh`
+Expected: build 성공, validator PASS.
+
+- [ ] **Step 6: 커밋**
+
+```bash
+git add prompts/profiles/implementation-planning.md prompts/profiles/_common-contract.md agents/SKILL.md runtime/
+git commit -m "feat(prompts/profiles): declare adversarial Phase 5.5 + plan-body posture for implementation-planning"
+```
+
+---
+
+### Task 4: CHANGES.md + 전체 검증 + 최종 커밋
+
+**Files:**
+- Modify: `CHANGES.md`
+
+- [ ] **Step 1: CHANGES.md 항목 추가**
+
+`## 2026-06-04` 헤더 바로 다음, 기존 첫 `###` 블록 **앞에** 삽입:
+
+```markdown
+### feat(convergence): implementation-planning 의 Phase 5.5 + plan-body 검증을 적대적으로
+
+- implementation-planning 은 통과한 계획이 곧장 implementation run 의 실행 대상이 되는 지점이라 거짓 합의 비용이 큰데, 두 검증 라운드가 모두 협조적이었다. 이제 (1) finding convergence 가 requirements-discovery·error-analysis 와 동일한 **적대적 모드**(`convergence.adversarial=true`, full-reanalysis scoped, 증거기반 반박 1건→강등)로 돌고, (2) plan-body verification(§4.5.9)이 **적대적 자세**로 — 검증자가 각 계획 항목의 인용 경로/명령을 직접 열어 실존·실행성을 확인하고 입증 책임을 계획 쪽에 둔다. plan-body 게이트 임계값은 **과반 유지**(`majority-disagree` 만 approval 차단; 단일 dissent 는 비차단) — classification/gate enum/validator 불변. 적대 phase 는 이제 3개(requirements-discovery / error-analysis / implementation-planning).
+- 사용자 영향: 다음 release + `npx -y okstra@latest install` 후 적용. 계획 단계 교차검증이 워커 주장과 계획 항목을 적극 반박·추적해 근거 약한 계획이 승인까지 가는 걸 줄인다. plan-body 승인 차단 기준은 종전과 동일(과반)이라 한 명의 오탐이 approval 을 막지 않는다. 적대적 *행동*은 lead/워커 prompt 지시(LLM)이며 런타임 강제가 아니다 — 강제되는 건 render 주입값과 gate↔approval 대응(validator)뿐.
+```
+
+- [ ] **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건이라도 있으면 STOP + BLOCKED 보고.
+
+- [ ] **Step 3: 일관성 self-review (Rule 2)**
+
+Run:
+```bash
+grep -rn "requirements-discovery\` / \`error-analysis\` / \`implementation-planning\|requirements-discovery\`, \`error-analysis\`, and \`implementation-planning\|requirements-discovery\` / \`error-analysis\`,\? \`false\|implementation-planning" scripts/okstra_ctl/render.py skills/okstra-convergence/SKILL.md prompts/profiles/_common-contract.md prompts/profiles/implementation-planning.md agents/SKILL.md
+```
+Confirm: 적대 phase 목록을 *열거*하는 모든 지점이 3개(requirements-discovery / error-analysis / implementation-planning)로 일치. 2개만 남은 곳(누락)이 없어야 함 — 있으면 보고.
+
+- [ ] **Step 4: 최종 커밋**
+
+```bash
+git add CHANGES.md
+git commit -m "docs(changes): log adversarial implementation-planning convergence + plan-body posture"
+```
+
+---
+
+## Self-Review (작성자 체크리스트)
+
+**1. Spec coverage**
+- §2.1 finding convergence 재사용 → Task 1.
+- §2.2 plan-body 적대 자세(과반 유지) → Task 2 Step 5/6, Task 3 Step 1/2.
+- §2.3 phase-목록 sweep 6곳 → render(Task 1) + skill 3곳·비용근거 2곳(Task 2) + _common-contract(Task 3) + agents(Task 3). 합산 일치, Task 4 Step 3 grep 로 검증.
+- §3 변경 파일 8종 → Task 1–4 전부 커버.
+- §4 enforcement → Task 1(render/test) machine-강제; plan-body 는 prompt-only(Task 2/3 선언).
+- §6 수용기준 1–5 → Task 4 Step 2/3.
+
+**2. Placeholder scan:** 모든 코드/markdown 블록 실제 내용. TBD/TODO 없음.
+
+**3. 식별자 일관성:** `adversarial`(bool), `verificationMode`("full-reanalysis"), `majority-disagree`/`dissent-isolated`(기존 enum, 불변), `Adversarial plan-body posture`(신규 절 제목, Task 2 정의 → Task 3 참조 동일 철자) 확인.