okstra 0.20.0 → 0.21.0

package/docs/superpowers/plans/2026-05-14-convergence-queue-pruning.md

@@ -0,0 +1,1568 @@
+# Convergence Queue Pruning (P0+P1) 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:** P0(용어/측정 기준 정리) + P1(convergence 재검증 queue pruning)을 구현하여 lead가 confirmed finding을 다음 라운드 prompt에 다시 넣지 않게 하고, Round 2 진입 조건과 worker-failure 처리를 문서·스키마·픽스처·계약 테스트로 고정한다.
+
+**Architecture:** Convergence 동작은 lead(Claude)가 `skills/okstra-convergence/SKILL.md`를 따라 수행하는 문서 계약이다. 코드가 convergence state JSON을 읽거나 쓰지 않는다(`grep -r convergence- scripts/` 결과 없음). 따라서 변경 범위는 시드(seed) 문서 4개와 templates 1개, 검증용 fixture 3개, contract test 1개, baseline 계측 헬퍼 1개로 한정한다. Worker prompt 생성도 lead 책임이므로 의사코드(pseudocode)에서 verification queue를 "Round 1 이후에도 mixed/unresolved인 항목" 으로 좁히면 dispatch 수가 자동으로 줄어든다.
+
+**Tech Stack:** Markdown 시드 문서, JSON Schema(hand-rolled), pytest, jq, Python 3.
+
+> 참고: 본 plan은 `docs/kr/performance-improvement-plan-v2.md` Section 9의 결론 1(P0)·2(P1)만 다룬다. P2(prompt diet) / P3(fast-track) / P4(prompt caching) / P5(render 병렬화) / P6(token-usage 증분화)는 본 plan의 범위가 **아니다** — 별도 plan으로 작성한다.
+
+---
+
+## File Structure
+
+| 경로 | 책임 | 변경 종류 |
+|---|---|---|
+| `skills/okstra-convergence/SKILL.md` | Phase 5.5 계약. 용어, Round 0/1/2 의사코드, queue pruning rule, worker-failure 처리, state schema v1.1 | Modify |
+| `agents/SKILL.md` | Lifecycle phase 경계와 Phase 5.5 진입점 | Modify (좁은 범위, Phase 5.5 블록만) |
+| `skills/okstra-report-writer/SKILL.md` | Phase 6 dispatch template, final-report 본문 구조에 round history 반영 | Modify |
+| `agents/workers/report-writer-worker.md` | report-writer subagent의 required-reading + authoring contract에 round history 추가 | Modify |
+| `templates/reports/final-report.template.md` | Section 1(Cross Verification Results) 하위에 round-history sub-section 추가 | Modify |
+| `tests/fixtures/convergence/early-exit.json` | Round 1에서 queue가 비어 Round 2가 skipped된 케이스 | Create |
+| `tests/fixtures/convergence/mixed-round2.json` | Round 1 후 unresolved queue가 있어 Round 2가 실행된 케이스 | Create |
+| `tests/fixtures/convergence/reverify-all-failed.json` | Round 1의 모든 reverify dispatch가 terminal non-result여서 Round 2가 suppress된 케이스 | Create |
+| `tests/test_convergence_state_contract.py` | 위 3개 fixture가 schema v1.1 contract를 만족하는지 검사 | Create |
+| `scripts/okstra-convergence-stats.py` | team-state + convergence-state에서 dispatch count / wall-clock / worker token을 집계하는 baseline 계측 helper | Create |
+| `docs/kr/performance-improvement-plan-v2.md` | Section 9 결론에 본 plan과 구현 상태 링크 추가 | Modify |
+
+---
+
+## Convention Notes (모든 task 공통)
+
+- 모든 새 문서/스키마 표현은 **end-user 시드 경로**에 배치한다 (개인 `.claude/` 가 아님). 본 plan의 모든 변경은 위 표의 경로에 들어간다.
+- `effectiveMaxRounds`는 `task-manifest.json`의 `convergence.maxRounds` 가 비어 있을 때 lead가 phase-aware default(`requirements-discovery → 1`, otherwise → 2)로 해석한 후 state artifact에 기록하는 값이다. 이미 `agents/SKILL.md` Phase 5.5 문구에 존재하므로 본 plan은 그 값을 schema 필드로 승격하기만 한다.
+- `round2SkippedReason` 의 enum 값: `queue-empty` | `max-rounds-1` | `all-reverify-non-result` | `not-skipped`.
+- `finalClassificationCounts` 의 키: `fullConsensus`, `partialConsensus`, `contested`, `workerUnique`. 기존 `summary` 객체는 동일 키 구조이므로 별칭(alias)로 유지.
+- `roundHistory[]`라는 기존 배열명은 유지하며 그 안의 필드를 확장한다(이름 변경은 lead가 따르는 mental model을 깨므로 보류).
+
+---
+
+## Task 1: Convergence SKILL — 용어 분리 + `contested` 중간 상태 제거
+
+**Files:**
+- Modify: `skills/okstra-convergence/SKILL.md`
+- Test: `tests/test_convergence_state_contract.py` (Task 12에서 생성. 이 단계에서는 verify only)
+
+- [ ] **Step 1: 파일 확인**
+
+Run: `wc -l /Volumes/Workspaces/workspace/projects/Okstra/skills/okstra-convergence/SKILL.md`
+Expected: 약 298 lines (existing).
+
+- [ ] **Step 2: `# OKSTRA Convergence` 헤더 바로 아래에 "Scope and Terminology" 섹션 삽입**
+
+`skills/okstra-convergence/SKILL.md` 의 `## When to Use` 직전 위치(line 7~9 사이)에 아래 블록을 삽입한다.
+
+````markdown
+## Scope and Terminology (BLOCKING)
+
+This skill governs **Phase 5.5 (Convergence loop)** — a *lead operating phase* inside a single okstra run, not a task-type lifecycle phase. The 6 task-type lifecycle phases (`requirements-discovery` → `error-analysis` → `implementation-planning` → `implementation` → `final-verification` → `release-handoff`, see [agents/SKILL.md](../../SKILL.md) "Lifecycle Phase Boundaries") are unchanged by this skill. The lead operating phases (Phase 1 Intake → Phase 7 Persist, see [agents/SKILL.md](../../SKILL.md) "Quick Reference") describe how the lead drives a *single* task-type run.
+
+**`contested` is a final classification only.** It is NEVER an intermediate queue label. The verification queue carries findings that are *unique to a single worker* (entered in Round 0) or *mixed/unresolved after a re-verification round* (carried forward). The `contested` label is assigned only when the **last executed round** completes and the queue is still non-empty.
+
+When this skill says "queue" without qualifier, it means the *verification queue*: the set of findings that are still candidates for re-verification in subsequent rounds. The queue shrinks monotonically as findings get classified as `full-consensus`, `partial-consensus`, or `worker-unique`. Findings classified into any of these three categories MUST NOT appear in any subsequent round's reverify prompt, for any worker.
+````
+
+- [ ] **Step 3: Finding Category 표의 `contested` row description을 명시적 최종-라운드 조건으로 강화**
+
+기존 (line 31 부근):
+
+```markdown
+| `contested` | No consensus reached even after max rounds; each worker's position is recorded | Required |
+```
+
+다음으로 교체:
+
+```markdown
+| `contested` | Final classification only. Assigned to a finding that remains in the verification queue after the **last executed round** completes (round index = `effectiveMaxRounds`). Each worker's position across all executed rounds is recorded. NEVER used as an intermediate label. | Required |
+```
+
+- [ ] **Step 4: Convergence Test 섹션의 final-classification 트리거를 last-executed-round로 명시**
+
+기존 (line 81~84 부근):
+
+```markdown
+- If the validation queue is empty → Convergence complete (`converged`)
+- Upon reaching the maximum number of rounds → Apply final classification to remaining unresolved findings:
+  - Majority agreement → `partial-consensus`
+  - Otherwise → `contested`
+```
+
+다음으로 교체:
+
+```markdown
+- If the verification queue is empty at the end of any round → Convergence complete (`finalState: "converged"`), remaining rounds are not executed
+- Upon completing the **last executed round** (where round index == `effectiveMaxRounds`, OR where Round 2 was suppressed per the Round 2 gate below) → Apply final classification to remaining queue items:
+  - Majority agreement across executed rounds → `partial-consensus`
+  - Otherwise → `contested`
+- The final classification step never runs while the queue is still being re-verified — confirmed items always exit the queue first.
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add skills/okstra-convergence/SKILL.md
+git commit -m "docs(convergence): scope terminology, contested as final-only label
+
+Adds 'Scope and Terminology' BLOCKING section to disambiguate Phase 5.5 from
+task-type lifecycle phases. Tightens 'contested' definition to a terminal
+classification only — it never labels intermediate queue items. Aligns the
+final-classification trigger to 'last executed round' so the queue-pruning
+algorithm in subsequent tasks reads cleanly."
+```
+
+---
+
+## Task 2: Convergence SKILL — Round 0 / Round 1 / Optional Round 2 의사코드 재작성
+
+**Files:**
+- Modify: `skills/okstra-convergence/SKILL.md` (Convergence Algorithm section)
+
+- [ ] **Step 1: Round 0 본문 보강 — queue 입력 규칙을 명시**
+
+기존 `### Round 0: Parse worker results` 섹션의 항목 3 (line 48~52 부근) 끝에 아래 한 줄을 추가한다(기존 4단계 grouping 규칙은 유지).
+
+```markdown
+6. After grouping, the verification queue contains EXACTLY the `unique`-marked findings (Step 3 case "Only one worker confirms"). `full-consensus` findings reached in Step 3 are recorded immediately in the convergence state with `classification: "full-consensus"` and DO NOT enter the queue.
+```
+
+- [ ] **Step 2: Round 1-N 의사코드 교체**
+
+기존 `### Round 1-N: Re-verification Loop` 코드 블록 (line 56~77) 전체를 다음으로 교체.
+
+````markdown
+### Round 1-N: Re-verification Loop (queue-pruned)
+
+The verification queue holds only findings that are not yet classified. Confirmed items are *removed* from the queue and never re-sent.
+
+```text
+roundIndex = 0
+WHILE roundIndex < effectiveMaxRounds AND queue is non-empty:
+  roundIndex += 1
+
+  # Round 2 gate (only evaluated when entering round 2 or higher)
+  IF roundIndex > 1 AND NOT round_gate_open(queue, last_round_dispatch_outcomes):
+    record round_skipped_reason in convergence state
+    BREAK
+
+  inputQueueSize = len(queue)
+  dispatches = []
+  skippedWorkers = []
+
+  FOR each analysis worker W (excluding report-writer-worker):
+    items_for_W = [f for f in queue if W != f.originWorker]
+    IF items_for_W is empty:
+      skippedWorkers.append({worker: W, reason: "no items to verify"})
+      CONTINUE
+    dispatch = send_reverify_request(W, items_for_W, roundIndex)
+    dispatches.append(dispatch)
+
+  IF all dispatches in this round are terminal non-result (timeout/error/no-result-file):
+    # Per "Worker failure handling in reverify" below — do NOT treat as DISAGREE.
+    record verification-error evidence on each finding in the queue for this round
+    record round_skipped_reason = "all-reverify-non-result" for any subsequent round
+    BREAK
+
+  resolvedCount = 0
+  carriedForwardCount = 0
+
+  FOR each finding F in queue (snapshot):
+    votes = aggregate_votes(F, dispatches)   # AGREE / DISAGREE / SUPPLEMENT / verification-error
+    IF all non-error votes are AGREE or SUPPLEMENT:
+      F.classification = "full-consensus"
+      queue.remove(F);  resolvedCount += 1
+    ELIF majority non-error votes are AGREE or SUPPLEMENT:
+      F.classification = "partial-consensus"
+      queue.remove(F);  resolvedCount += 1
+    ELIF all non-error votes are DISAGREE:
+      F.classification = "worker-unique"
+      queue.remove(F);  resolvedCount += 1
+    ELSE:
+      # mixed / insufficient non-error votes → carry forward
+      carriedForwardCount += 1
+
+  record roundHistory entry { round: roundIndex, inputQueueSize, resolvedCount,
+                              carriedForwardCount, dispatches, skippedWorkers }
+
+# Final classification — runs after the WHILE loop exits (queue empty OR roundIndex == effectiveMaxRounds OR Round 2 gate closed)
+FOR each finding F still in queue:
+  IF majority AGREE-or-SUPPLEMENT across all executed rounds:
+    F.classification = "partial-consensus"
+  ELSE:
+    F.classification = "contested"
+```
+
+The lead MUST construct the per-worker reverify prompt body from `items_for_W` only — confirmed findings from earlier rounds MUST NOT appear in the prompt, even as background. The dispatch-prompt invariant (every worker gets the same prompt content modulo their own findings) continues to apply to the per-round prompt body.
+````
+
+- [ ] **Step 3: "Round 2 gate" 서브섹션 추가**
+
+위에서 추가한 의사코드 바로 아래에 다음 sub-section을 삽입.
+
+````markdown
+#### Round 2 gate (`round_gate_open` predicate)
+
+`round_gate_open(queue, last_round_dispatch_outcomes)` returns `true` iff ALL three conditions hold; otherwise the lead records `round2SkippedReason` and breaks out of the loop:
+
+| Condition | Required value | `round2SkippedReason` if not met |
+|---|---|---|
+| `effectiveMaxRounds >= 2` | true | `"max-rounds-1"` |
+| `len(queue) > 0` after round 1 | true | `"queue-empty"` |
+| At least one round-1 reverify dispatch terminated as `completed` | true | `"all-reverify-non-result"` |
+
+When all conditions hold the predicate returns `true` and `round2SkippedReason` is set to `"not-skipped"`. The field is mandatory on every convergence state artifact — write `"not-skipped"` rather than omitting the key.
+````
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add skills/okstra-convergence/SKILL.md
+git commit -m "docs(convergence): queue-pruned Round 0/1/2 algorithm with explicit gate
+
+Replaces the Round 1-N pseudocode with a queue-pruning loop: confirmed items
+exit the queue immediately and never enter the next round's reverify prompt.
+Adds a Round 2 gate predicate with three explicit conditions
+(effectiveMaxRounds>=2, queue non-empty, at least one round-1 completed
+dispatch) and a mandatory round2SkippedReason artifact field with enum
+{queue-empty, max-rounds-1, all-reverify-non-result, not-skipped}."
+```
+
+---
+
+## Task 3: Convergence SKILL — worker-failure 처리 명세
+
+**Files:**
+- Modify: `skills/okstra-convergence/SKILL.md` (new "Worker failure handling in reverify" subsection)
+
+- [ ] **Step 1: 새 서브섹션을 "Round 2 gate" 바로 아래에 삽입**
+
+````markdown
+#### Worker failure handling in reverify (BLOCKING)
+
+A reverify dispatch that returns a **terminal non-result** (`timeout`, `error`, no result file, or the wrapper records `cli-failure`) MUST NOT be aggregated as `DISAGREE`. Misclassifying a worker failure as DISAGREE biases the queue toward `contested`/`worker-unique` and produces meaningless final classifications.
+
+Rules:
+
+1. For each affected finding, append a `votes[W].verdict = "verification-error"` entry instead of `disagree`, plus the wrapper's captured exit reason in `votes[W].explanation`.
+2. Record one event per failed dispatch via `python3 scripts/okstra-error-log.py append-observed --error-type cli-failure --agent <worker> ...` (the worker wrapper does this for Codex/Gemini; for Claude worker timeouts the lead does it).
+3. Add an entry to the round's `skippedWorkers[]` with `{worker: <W>, reason: "dispatch-non-result", terminalStatus: <timeout|error|not-run>}`.
+4. If **all** reverify dispatches in a round terminate as non-result, the round is treated as gate-closed: write `round2SkippedReason: "all-reverify-non-result"` (even if the round in question is round 1 — i.e. round 2 never runs because round 1 produced no usable votes), record one `contract-violation` event per non-result dispatch, and exit the WHILE loop.
+5. Section 6 (Specialization Lens) of a worker output is OUT of convergence scope per "Convergence scope" above — its absence is NEVER a `verification-error`.
+
+The final classifier (`FOR each finding F still in queue` block) treats `verification-error` as "no usable vote" — it counts neither toward AGREE nor toward DISAGREE.
+````
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add skills/okstra-convergence/SKILL.md
+git commit -m "docs(convergence): separate worker-failure from DISAGREE in reverify
+
+Codifies a 'verification-error' verdict so a dispatch that timed out or
+returned no result file does not get aggregated as DISAGREE. Adds a
+skippedWorkers[] entry per non-result dispatch and forces
+round2SkippedReason=all-reverify-non-result when every dispatch in a round
+fails. The final classifier ignores verification-error votes when counting
+majority."
+```
+
+---
+
+## Task 4: Convergence SKILL — state artifact schema v1.1
+
+**Files:**
+- Modify: `skills/okstra-convergence/SKILL.md` (Convergence State Artifact section)
+
+- [ ] **Step 1: 기존 JSON 예제 블록(line 232~283)을 v1.1 스키마로 교체**
+
+````markdown
+## Convergence State Artifact
+
+Save it to `runs/<task-type>/state/convergence-<task-type>-<seq>.json`.
+
+Schema version `1.1` extends `1.0` (legacy fields kept as aliases for backward-compat with already-shipped reports):
+
+```json
+{
+  "schemaVersion": "1.1",
+  "taskKey": "<task-key>",
+  "config": {
+    "enabled": true,
+    "maxRounds": 2,
+    "effectiveMaxRounds": 2,
+    "verificationMode": "lightweight"
+  },
+  "findings": [
+    {
+      "findingId": "F-001",
+      "summary": "<one-line summary>",
+      "category": "<bug|risk|missing|observation|...>",
+      "ticketIds": ["TICKET-123"],
+      "originWorker": "claude-worker",
+      "originEvidence": "<evidence text>",
+      "classification": "full-consensus",
+      "rounds": [
+        {
+          "round": 1,
+          "votes": {
+            "codex-worker": { "verdict": "agree", "explanation": "<brief>" },
+            "gemini-worker": { "verdict": "supplement", "explanation": "<brief>" }
+          }
+        }
+      ],
+      "consensusWorkers": ["claude-worker", "codex-worker", "gemini-worker"],
+      "dissentingWorkers": []
+    }
+  ],
+  "roundHistory": [
+    {
+      "round": 1,
+      "inputQueueSize": 3,
+      "resolvedCount": 2,
+      "carriedForwardCount": 1,
+      "dispatches": [
+        { "worker": "codex-worker",  "status": "completed", "durationMs": 184221 },
+        { "worker": "gemini-worker", "status": "completed", "durationMs": 201337 }
+      ],
+      "skippedWorkers": [
+        { "worker": "claude-worker", "reason": "no items to verify" }
+      ],
+      "verificationsRequested": 2,
+      "verificationsCompleted": 2,
+      "newConsensus": 2,
+      "remainingInQueue": 1,
+      "earlyExit": false
+    }
+  ],
+  "round2SkippedReason": "not-skipped",
+  "finalState": "converged",
+  "totalRounds": 2,
+  "finalClassificationCounts": {
+    "fullConsensus": 5,
+    "partialConsensus": 1,
+    "contested": 0,
+    "workerUnique": 1
+  },
+  "summary": {
+    "fullConsensus": 5,
+    "partialConsensus": 1,
+    "contested": 0,
+    "workerUnique": 1
+  }
+}
+```
+
+Schema rules:
+
+- `schemaVersion`: literal string `"1.1"` for new runs. Readers MUST accept `"1.0"` for historical artifacts and treat any missing v1.1 field as `null`.
+- `config.effectiveMaxRounds`: the integer the lead actually used after resolving the phase-aware default (`1` for `requirements-discovery`, `2` otherwise). MUST equal `config.maxRounds` when the manifest explicitly set it.
+- `roundHistory[].inputQueueSize`: queue size at the start of this round.
+- `roundHistory[].resolvedCount`: number of findings that exited the queue this round (sum of full+partial+worker-unique classifications produced this round).
+- `roundHistory[].carriedForwardCount`: queue size at the END of this round (must equal `inputQueueSize - resolvedCount` when there are no in-round queue insertions; in-round insertions are forbidden).
+- `roundHistory[].dispatches[]`: one entry per worker that was actually dispatched in this round. `status ∈ {completed, timeout, error, not-run}`.
+- `roundHistory[].skippedWorkers[]`: per-worker `{worker, reason}` for workers with no items to verify OR with a non-result dispatch.
+- `roundHistory[].verificationsRequested|verificationsCompleted|newConsensus|remainingInQueue|earlyExit`: legacy v1.0 aliases. New runs SHOULD populate them so existing parsers keep working: `verificationsRequested == len(dispatches)`, `verificationsCompleted == len(d for d in dispatches if d.status == "completed")`, `newConsensus == resolvedCount`, `remainingInQueue == carriedForwardCount`, `earlyExit == (round < effectiveMaxRounds AND carriedForwardCount == 0)`.
+- `round2SkippedReason`: literal enum `queue-empty | max-rounds-1 | all-reverify-non-result | not-skipped`. Always present (use `"not-skipped"` when Round 2 ran or wasn't reached for the loop-exit-not-skip reason of `effectiveMaxRounds == 1`. For the `effectiveMaxRounds == 1` case the value is `"max-rounds-1"`).
+- `finalClassificationCounts`: post-loop counts. New required field — must equal `summary` 1:1. `summary` is retained as the v1.0 alias.
+- `finalState ∈ {converged, max-rounds-reached, aborted-non-result}`. `aborted-non-result` is the new value for the case all reverify dispatches in a round fail.
+- `totalRounds`: count of rounds actually executed (not `effectiveMaxRounds`). May be `0` when Round 0 produced no queue items (all findings reached consensus during grouping).
+````
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add skills/okstra-convergence/SKILL.md
+git commit -m "docs(convergence): schema v1.1 with effectiveMaxRounds and skip reason
+
+Adds inputQueueSize, resolvedCount, carriedForwardCount, dispatches[], and
+skippedWorkers[] per round; finalClassificationCounts, round2SkippedReason,
+and config.effectiveMaxRounds at the top level. v1.0 fields are kept as
+aliases so existing report parsers keep working until they migrate."
+```
+
+---
+
+## Task 5: agents/SKILL.md — Phase 5.5 설명 정합
+
+**Files:**
+- Modify: `agents/SKILL.md` (Phase 5.5 section at line 198~212 area)
+
+- [ ] **Step 1: Phase 5.5 본문 보강**
+
+기존 (line 200~210 부근, "Convergence is enabled by default..." 블록)을 다음으로 교체:
+
+````markdown
+Convergence is enabled by default. Configure via task-manifest.json:
+
+- `convergence.enabled`: true/false (default: true)
+- `convergence.maxRounds`: 1–3 — **phase-aware default**: `1` for `requirements-discovery`, `2` for all other task types
+- `convergence.verificationMode`: `"lightweight"` | `"full-reanalysis"` (default: `"lightweight"`)
+
+When `task-manifest.json` does not set `convergence.maxRounds`, lead MUST resolve the effective value via the phase-aware default above before entering Phase 5.5, and record the resolved value in the convergence state artifact at `config.effectiveMaxRounds`.
+
+**Round 2 is gated, not unconditional.** Even when `effectiveMaxRounds == 2`, Round 2 runs only when (a) the verification queue is non-empty after Round 1, AND (b) at least one Round 1 reverify dispatch terminated as `completed`. Otherwise lead writes `round2SkippedReason` to the convergence state and proceeds to final classification. See [okstra-convergence](./skills/okstra-convergence/SKILL.md) "Round 2 gate" for the predicate.
+
+**Confirmed findings are pruned from the queue.** Findings classified as `full-consensus`, `partial-consensus`, or `worker-unique` MUST NOT appear in any subsequent round's reverify prompt for any worker. `contested` is a final classification assigned only when the last executed round completes and the queue is still non-empty — it is NEVER an intermediate queue label.
+
+If any re-verification batch yields a `verification-error` terminal status, or a worker result fails the contract, Lead MUST record one event per violation via `python3 scripts/okstra-error-log.py append-observed --error-type contract-violation --agent <offending-agent> ...`. Use `agent: "claude-lead"` only when the violation is detected internally without a specific worker.
+
+If convergence is disabled, proceed directly to Phase 6 with the raw worker results.
+````
+
+- [ ] **Step 2: "Common Mistakes" 표(line 264~286 부근)에 신규 행 2개 추가**
+
+기존 표의 마지막 행(`Skipping --substitute-final-report ...`) 바로 위에 다음 두 행을 추가한다.
+
+```markdown
+| Re-sending confirmed findings (`full-consensus`/`partial-consensus`/`worker-unique`) to a worker in Round 2 | Queue pruning rule — see [okstra-convergence](./skills/okstra-convergence/SKILL.md) "Round 1-N: Re-verification Loop (queue-pruned)" |
+| Aggregating a `timeout`/`error` reverify dispatch as `DISAGREE` | Worker failure handling — record as `verification-error` and add to `skippedWorkers[]`. See [okstra-convergence](./skills/okstra-convergence/SKILL.md) "Worker failure handling in reverify" |
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add agents/SKILL.md
+git commit -m "docs(agents): Phase 5.5 Round 2 gate and queue-pruning callouts
+
+Spells out the Round 2 gate conditions (effectiveMaxRounds>=2, queue
+non-empty, at least one round-1 completed dispatch), records the
+queue-pruning invariant, and adds two new Common Mistakes rows for
+re-sending confirmed findings and mis-aggregating worker-failure dispatches."
+```
+
+---
+
+## Task 6: report-writer SKILL — round history & skipped-reason 반영
+
+**Files:**
+- Modify: `skills/okstra-report-writer/SKILL.md` (Phase 6 dispatch template + Main Body Section)
+
+- [ ] **Step 1: Phase 6 dispatch template 항목 9 보강**
+
+기존 (line 49 부근):
+
+```markdown
+9. The convergence classifications (Full/Partial/Contested/Worker-Unique) and pointers to all worker result files under `worker-results/`.
+```
+
+다음으로 교체:
+
+```markdown
+9. The convergence classifications (Full/Partial/Contested/Worker-Unique), the round history table (`roundHistory[]`), the `round2SkippedReason` value, and pointers to all worker result files under `worker-results/`. The report-writer worker must reproduce a Round History sub-table in Section 1 of the final report so the reader can see which rounds executed, queue sizes, and why Round 2 was (or was not) skipped.
+```
+
+- [ ] **Step 2: Main Body Section 2 ("Cross Verification Results") description 보강**
+
+기존 (line 228~233 부근):
+
+```markdown
+2. **Cross Verification Results** (Use 4 categories when convergence is enabled, per `okstra-convergence`)
+   - Full Consensus: Findings agreed upon by all workers
+   - Partial Consensus: Agreed upon by a majority of workers; dissenting opinions are specified
+   - Contested: No consensus after max rounds; each worker's position specified
+   - Worker-Unique: Verified only by the discoverer; verification history specified
+   - In runs with convergence disabled, maintain the existing Consensus/Differences format
+```
+
+다음으로 교체:
+
+```markdown
+2. **Cross Verification Results** (Use 4 categories when convergence is enabled, per `okstra-convergence`)
+   - Round History sub-table (convergence-enabled runs only): one row per executed round with columns `Round | inputQueueSize | resolvedCount | carriedForwardCount | dispatches (worker:status:durationMs) | skippedWorkers (worker:reason)`. Add a one-line note immediately under the table with `round2SkippedReason: <value>` (always present, even when `"not-skipped"`). Pull all values verbatim from `convergence-<task-type>-<seq>.json`.
+   - Full Consensus: Findings agreed upon by all workers
+   - Partial Consensus: Agreed upon by a majority of workers; dissenting opinions are specified
+   - Contested: No consensus after the last executed round; each worker's position specified. Empty contested list is shown as the literal line `- 합의 미달 항목 없음.`
+   - Worker-Unique: Verified only by the discoverer; verification history specified
+   - In runs with convergence disabled, maintain the existing Consensus/Differences format and omit the Round History sub-table.
+```
+
+- [ ] **Step 3: Writing Guidelines 항목 강화**
+
+기존 "Include the convergence round history and a summary of votes by worker for each finding" 라인을 다음 두 줄로 교체:
+
+```markdown
+- Include the convergence round history sub-table (Section 1) so the reader can audit which rounds executed and why Round 2 was skipped. Pull values verbatim from `convergence-<task-type>-<seq>.json`; do NOT recompute.
+- For each finding, include a brief summary of votes per worker across executed rounds. `verification-error` votes are listed as such — never as `DISAGREE`.
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add skills/okstra-report-writer/SKILL.md
+git commit -m "docs(report-writer): require Round History sub-table in final report
+
+The report-writer prompt template now demands a Round History sub-table with
+queue sizes, dispatches, and skippedWorkers, plus an explicit
+round2SkippedReason line. Writing guidelines mandate verbatim copy from the
+convergence state and distinguish verification-error votes from DISAGREE."
+```
+
+---
+
+## Task 7: report-writer-worker agent — required-reading + authoring contract
+
+**Files:**
+- Modify: `agents/workers/report-writer-worker.md`
+
+- [ ] **Step 1: "Required Reading Before Authoring" 섹션에 명시적 의무 추가**
+
+기존 (line 44~52 부근의 첫 단락 다음)에 아래 bullet 추가:
+
+```markdown
+- When the convergence-state file is present, read it fully and reproduce the `roundHistory[]` array, `round2SkippedReason`, and `finalClassificationCounts` in the final report's Section 1 Round History sub-table. Do not derive these values from worker results alone — they live in `state/convergence-<task-type>-<seq>.json`.
+```
+
+- [ ] **Step 2: Authoring Contract Hard rules 보강**
+
+기존 "Include all four convergence categories (Full Consensus, Partial Consensus, Contested, Worker-Unique)..." 행을 그대로 두고, 그 다음 줄에 추가:
+
+```markdown
+- Include a Round History sub-table in Section 1 (one row per executed round) and a `round2SkippedReason` line below it. When convergence is disabled, omit both. The values are quoted verbatim from `state/convergence-<task-type>-<seq>.json` — do not recompute.
+- Treat `verification-error` votes as their own verdict. They are listed in vote summaries as `verification-error`, not folded into AGREE/DISAGREE counts.
+```
+
+- [ ] **Step 3: Notes 섹션 보강**
+
+기존 "If the analysis workers disagree and convergence ended with `Contested` items..." 행 바로 아래에 추가:
+
+```markdown
+- `Contested` is a final-only classification. If you see findings labeled `Contested` in the convergence state, the lead has already exhausted re-verification — do not invent a synthesizing answer; surface each worker's position verbatim.
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add agents/workers/report-writer-worker.md
+git commit -m "docs(report-writer-worker): require Round History reproduction
+
+Forces the report-writer subagent to read the convergence state file
+end-to-end, reproduce roundHistory[]/round2SkippedReason/finalClassificationCounts
+in Section 1, and treat verification-error as its own verdict (not DISAGREE)."
+```
+
+---
+
+## Task 8: final-report 템플릿에 Round History sub-section 추가
+
+**Files:**
+- Modify: `templates/reports/final-report.template.md` (Section 1 Cross Verification Results 영역)
+
+- [ ] **Step 1: 현재 Section 1 구조 확인**
+
+Run: `grep -n "^## 1\|^### 1\." /Volumes/Workspaces/workspace/projects/Okstra/templates/reports/final-report.template.md`
+Expected: lines `## 1. Cross Verification Results`, `### 1.1 Consensus`, `### 1.2 Differences`.
+
+- [ ] **Step 2: `## 1. Cross Verification Results` 헤더 바로 아래(즉 `### 1.1 Consensus` 위)에 신규 `### 1.0 Round History (convergence-enabled runs only)` 서브섹션을 삽입**
+
+```markdown
+### 1.0 Round History (convergence-enabled runs only)
+
+`state/convergence-<task-type>-<seq>.json` 의 값을 그대로 옮긴다. convergence가 비활성화된 run에서는 이 섹션 전체를 삭제한다.
+
+| Round | inputQueueSize | resolvedCount | carriedForwardCount | dispatches (worker:status:durationMs) | skippedWorkers (worker:reason) |
+|-------|----------------|---------------|----------------------|----------------------------------------|---------------------------------|
+| 1     | 3              | 2             | 1                    | codex-worker:completed:184221, gemini-worker:completed:201337 | claude-worker:no-items |
+| 2     | 1              | 1             | 0                    | claude-worker:completed:92110         | --                              |
+
+- `round2SkippedReason`: `not-skipped`  ← 값은 `queue-empty | max-rounds-1 | all-reverify-non-result | not-skipped` 중 하나.
+- 실행된 round 수가 0 (Round 0에서 모든 finding이 곧장 full-consensus 가 된 경우) 이면 표 대신 한 줄로 적는다 — `- Round 0 grouping에서 모든 finding이 합의되어 재검증 라운드가 실행되지 않았습니다.`
+
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add templates/reports/final-report.template.md
+git commit -m "docs(template): Section 1.0 Round History sub-table for convergence runs
+
+Adds a 1.0 Round History table with queue sizes, dispatches, and
+skippedWorkers, plus an explicit round2SkippedReason line. The block is
+omitted when convergence is disabled. Aligns the template with the
+queue-pruning algorithm contract."
+```
+
+---
+
+## Task 9: Fixture 1 — early convergence (Round 1 exit)
+
+**Files:**
+- Create: `tests/fixtures/convergence/early-exit.json`
+
+- [ ] **Step 1: 디렉터리 준비**
+
+```bash
+mkdir -p /Volumes/Workspaces/workspace/projects/Okstra/tests/fixtures/convergence
+```
+
+- [ ] **Step 2: 파일 작성**
+
+`tests/fixtures/convergence/early-exit.json`:
+
+```json
+{
+  "schemaVersion": "1.1",
+  "taskKey": "fixture/early-exit",
+  "config": {
+    "enabled": true,
+    "maxRounds": 2,
+    "effectiveMaxRounds": 2,
+    "verificationMode": "lightweight"
+  },
+  "findings": [
+    {
+      "findingId": "F-001",
+      "summary": "Missing input validation on /api/login",
+      "category": "bug",
+      "ticketIds": ["EX-100"],
+      "originWorker": "codex-worker",
+      "originEvidence": "src/auth/login.ts:42",
+      "classification": "full-consensus",
+      "rounds": [
+        {
+          "round": 1,
+          "votes": {
+            "claude-worker": {"verdict": "agree", "explanation": "confirmed"},
+            "gemini-worker": {"verdict": "supplement", "explanation": "also missing CSRF check"}
+          }
+        }
+      ],
+      "consensusWorkers": ["codex-worker", "claude-worker", "gemini-worker"],
+      "dissentingWorkers": []
+    },
+    {
+      "findingId": "F-002",
+      "summary": "Stale dependency lockfile",
+      "category": "risk",
+      "ticketIds": ["EX-101"],
+      "originWorker": "claude-worker",
+      "originEvidence": "package-lock.json:1",
+      "classification": "full-consensus",
+      "rounds": [
+        {
+          "round": 1,
+          "votes": {
+            "codex-worker": {"verdict": "agree", "explanation": "confirmed"},
+            "gemini-worker": {"verdict": "agree", "explanation": "confirmed"}
+          }
+        }
+      ],
+      "consensusWorkers": ["claude-worker", "codex-worker", "gemini-worker"],
+      "dissentingWorkers": []
+    }
+  ],
+  "roundHistory": [
+    {
+      "round": 1,
+      "inputQueueSize": 2,
+      "resolvedCount": 2,
+      "carriedForwardCount": 0,
+      "dispatches": [
+        {"worker": "claude-worker", "status": "completed", "durationMs": 92110},
+        {"worker": "codex-worker",  "status": "completed", "durationMs": 184221},
+        {"worker": "gemini-worker", "status": "completed", "durationMs": 201337}
+      ],
+      "skippedWorkers": [],
+      "verificationsRequested": 3,
+      "verificationsCompleted": 3,
+      "newConsensus": 2,
+      "remainingInQueue": 0,
+      "earlyExit": true
+    }
+  ],
+  "round2SkippedReason": "queue-empty",
+  "finalState": "converged",
+  "totalRounds": 1,
+  "finalClassificationCounts": {
+    "fullConsensus": 2,
+    "partialConsensus": 0,
+    "contested": 0,
+    "workerUnique": 0
+  },
+  "summary": {
+    "fullConsensus": 2,
+    "partialConsensus": 0,
+    "contested": 0,
+    "workerUnique": 0
+  }
+}
+```
+
+- [ ] **Step 3: JSON 유효성 즉시 검증**
+
+Run: `python3 -c "import json; json.load(open('tests/fixtures/convergence/early-exit.json'))"`
+Expected: 종료 코드 0, 출력 없음.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add tests/fixtures/convergence/early-exit.json
+git commit -m "test(convergence): fixture for Round 1 early-exit (queue-empty)
+
+Two findings reach full-consensus in Round 1; queue empties so Round 2 is
+skipped with round2SkippedReason=queue-empty. effectiveMaxRounds=2,
+totalRounds=1."
+```
+
+---
+
+## Task 10: Fixture 2 — mixed/unresolved Round 2
+
+**Files:**
+- Create: `tests/fixtures/convergence/mixed-round2.json`
+
+- [ ] **Step 1: 파일 작성**
+
+`tests/fixtures/convergence/mixed-round2.json`:
+
+```json
+{
+  "schemaVersion": "1.1",
+  "taskKey": "fixture/mixed-round2",
+  "config": {
+    "enabled": true,
+    "maxRounds": 2,
+    "effectiveMaxRounds": 2,
+    "verificationMode": "lightweight"
+  },
+  "findings": [
+    {
+      "findingId": "F-010",
+      "summary": "Race condition in session refresh",
+      "category": "bug",
+      "ticketIds": ["EX-200"],
+      "originWorker": "codex-worker",
+      "originEvidence": "src/session/refresh.ts:88",
+      "classification": "full-consensus",
+      "rounds": [
+        {
+          "round": 1,
+          "votes": {
+            "claude-worker": {"verdict": "agree", "explanation": "confirmed"},
+            "gemini-worker": {"verdict": "supplement", "explanation": "additional repro path"}
+          }
+        }
+      ],
+      "consensusWorkers": ["codex-worker", "claude-worker", "gemini-worker"],
+      "dissentingWorkers": []
+    },
+    {
+      "findingId": "F-011",
+      "summary": "Inconsistent error message on 401",
+      "category": "observation",
+      "ticketIds": ["EX-201"],
+      "originWorker": "claude-worker",
+      "originEvidence": "src/api/auth.ts:120",
+      "classification": "contested",
+      "rounds": [
+        {
+          "round": 1,
+          "votes": {
+            "codex-worker":  {"verdict": "agree",    "explanation": "confirmed"},
+            "gemini-worker": {"verdict": "disagree", "explanation": "expected behavior per spec"}
+          }
+        },
+        {
+          "round": 2,
+          "votes": {
+            "codex-worker":  {"verdict": "agree",    "explanation": "still confirmed"},
+            "gemini-worker": {"verdict": "disagree", "explanation": "see RFC 7235"}
+          }
+        }
+      ],
+      "consensusWorkers": ["claude-worker", "codex-worker"],
+      "dissentingWorkers": ["gemini-worker"]
+    }
+  ],
+  "roundHistory": [
+    {
+      "round": 1,
+      "inputQueueSize": 2,
+      "resolvedCount": 1,
+      "carriedForwardCount": 1,
+      "dispatches": [
+        {"worker": "claude-worker", "status": "completed", "durationMs": 88012},
+        {"worker": "codex-worker",  "status": "completed", "durationMs": 175044},
+        {"worker": "gemini-worker", "status": "completed", "durationMs": 199820}
+      ],
+      "skippedWorkers": [],
+      "verificationsRequested": 3,
+      "verificationsCompleted": 3,
+      "newConsensus": 1,
+      "remainingInQueue": 1,
+      "earlyExit": false
+    },
+    {
+      "round": 2,
+      "inputQueueSize": 1,
+      "resolvedCount": 0,
+      "carriedForwardCount": 1,
+      "dispatches": [
+        {"worker": "codex-worker",  "status": "completed", "durationMs": 110002},
+        {"worker": "gemini-worker", "status": "completed", "durationMs": 125110}
+      ],
+      "skippedWorkers": [
+        {"worker": "claude-worker", "reason": "no items to verify"}
+      ],
+      "verificationsRequested": 2,
+      "verificationsCompleted": 2,
+      "newConsensus": 0,
+      "remainingInQueue": 1,
+      "earlyExit": false
+    }
+  ],
+  "round2SkippedReason": "not-skipped",
+  "finalState": "max-rounds-reached",
+  "totalRounds": 2,
+  "finalClassificationCounts": {
+    "fullConsensus": 1,
+    "partialConsensus": 0,
+    "contested": 1,
+    "workerUnique": 0
+  },
+  "summary": {
+    "fullConsensus": 1,
+    "partialConsensus": 0,
+    "contested": 1,
+    "workerUnique": 0
+  }
+}
+```
+
+- [ ] **Step 2: JSON 유효성 검증**
+
+Run: `python3 -c "import json; json.load(open('tests/fixtures/convergence/mixed-round2.json'))"`
+Expected: 종료 코드 0.
+
+- [ ] **Step 3: 핵심 invariant 수기 검증**
+
+Round 2 입력 큐(`inputQueueSize=1`) 는 Round 1 출력 큐(`carriedForwardCount=1`)와 일치해야 한다. 그리고 `F-010` (Round 1에서 full-consensus 확정) 의 `rounds` 배열에 round 2 항목이 없어야 한다 — confirmed finding은 다시 prompt에 들어가지 않는다는 invariant 가 fixture에 반영되었는지 확인.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add tests/fixtures/convergence/mixed-round2.json
+git commit -m "test(convergence): fixture for mixed Round 1 → unresolved Round 2
+
+F-010 resolves in Round 1; F-011 remains in queue (claude+codex agree,
+gemini disagrees), enters Round 2 which still cannot resolve it →
+classified as contested. claude-worker is skipped in Round 2 because the
+only queued item is its own. round2SkippedReason=not-skipped."
+```
+
+---
+
+## Task 11: Fixture 3 — worker-failure (all reverify non-result)
+
+**Files:**
+- Create: `tests/fixtures/convergence/reverify-all-failed.json`
+
+- [ ] **Step 1: 파일 작성**
+
+`tests/fixtures/convergence/reverify-all-failed.json`:
+
+```json
+{
+  "schemaVersion": "1.1",
+  "taskKey": "fixture/reverify-all-failed",
+  "config": {
+    "enabled": true,
+    "maxRounds": 2,
+    "effectiveMaxRounds": 2,
+    "verificationMode": "lightweight"
+  },
+  "findings": [
+    {
+      "findingId": "F-020",
+      "summary": "Possible memory leak in long-running session",
+      "category": "risk",
+      "ticketIds": ["EX-300"],
+      "originWorker": "codex-worker",
+      "originEvidence": "src/session/cache.ts:200",
+      "classification": "contested",
+      "rounds": [
+        {
+          "round": 1,
+          "votes": {
+            "claude-worker": {"verdict": "verification-error", "explanation": "dispatch timeout after 900s"},
+            "gemini-worker": {"verdict": "verification-error", "explanation": "CLI exit 137 (OOM)"}
+          }
+        }
+      ],
+      "consensusWorkers": ["codex-worker"],
+      "dissentingWorkers": []
+    }
+  ],
+  "roundHistory": [
+    {
+      "round": 1,
+      "inputQueueSize": 1,
+      "resolvedCount": 0,
+      "carriedForwardCount": 1,
+      "dispatches": [
+        {"worker": "claude-worker", "status": "timeout", "durationMs": 900000},
+        {"worker": "gemini-worker", "status": "error",   "durationMs": 14210}
+      ],
+      "skippedWorkers": [
+        {"worker": "claude-worker", "reason": "dispatch-non-result", "terminalStatus": "timeout"},
+        {"worker": "gemini-worker", "reason": "dispatch-non-result", "terminalStatus": "error"}
+      ],
+      "verificationsRequested": 2,
+      "verificationsCompleted": 0,
+      "newConsensus": 0,
+      "remainingInQueue": 1,
+      "earlyExit": false
+    }
+  ],
+  "round2SkippedReason": "all-reverify-non-result",
+  "finalState": "aborted-non-result",
+  "totalRounds": 1,
+  "finalClassificationCounts": {
+    "fullConsensus": 0,
+    "partialConsensus": 0,
+    "contested": 1,
+    "workerUnique": 0
+  },
+  "summary": {
+    "fullConsensus": 0,
+    "partialConsensus": 0,
+    "contested": 1,
+    "workerUnique": 0
+  }
+}
+```
+
+- [ ] **Step 2: JSON 유효성 검증**
+
+Run: `python3 -c "import json; json.load(open('tests/fixtures/convergence/reverify-all-failed.json'))"`
+Expected: 종료 코드 0.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tests/fixtures/convergence/reverify-all-failed.json
+git commit -m "test(convergence): fixture for all-reverify-non-result Round 1 abort
+
+Single finding remains unresolved because both reverify dispatches return
+terminal non-result (timeout + error). Round 2 is suppressed with
+round2SkippedReason=all-reverify-non-result; finalState=aborted-non-result.
+Verdicts are recorded as verification-error, not DISAGREE."
+```
+
+---
+
+## Task 12: Convergence schema contract test (pytest)
+
+**Files:**
+- Create: `tests/test_convergence_state_contract.py`
+
+이 task는 코드를 작성하므로 TDD로 진행한다. 픽스처는 이미 Tasks 9~11에서 존재한다고 가정한다.
+
+- [ ] **Step 1: 실패하는 첫 테스트 — schemaVersion 검사**
+
+`tests/test_convergence_state_contract.py`:
+
+```python
+"""Contract tests for convergence-<task-type>-<seq>.json (schema v1.1).
+
+Convergence state is a documentation contract — no production code reads it.
+These tests check that fixtures shipped under tests/fixtures/convergence/
+respect the v1.1 invariants documented in
+skills/okstra-convergence/SKILL.md "Convergence State Artifact".
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+FIXTURE_DIR = Path(__file__).parent / "fixtures" / "convergence"
+ALL_FIXTURES = sorted(FIXTURE_DIR.glob("*.json"))
+
+VALID_ROUND2_SKIP_REASONS = {
+    "queue-empty",
+    "max-rounds-1",
+    "all-reverify-non-result",
+    "not-skipped",
+}
+VALID_FINAL_STATES = {"converged", "max-rounds-reached", "aborted-non-result"}
+VALID_CLASSIFICATIONS = {
+    "full-consensus",
+    "partial-consensus",
+    "contested",
+    "worker-unique",
+}
+VALID_DISPATCH_STATUSES = {"completed", "timeout", "error", "not-run"}
+VALID_VERDICTS = {"agree", "disagree", "supplement", "verification-error"}
+
+
+@pytest.fixture(params=ALL_FIXTURES, ids=lambda p: p.stem)
+def fixture(request) -> dict:
+    return json.loads(request.param.read_text())
+
+
+def test_schema_version_is_1_1(fixture):
+    assert fixture["schemaVersion"] == "1.1"
+```
+
+- [ ] **Step 2: 첫 테스트 실행 (이 단계의 fail/pass 둘 다 진행에 유효)**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && pytest tests/test_convergence_state_contract.py -v`
+Expected: 3 fixtures × 1 test = 3 PASS (이미 Task 9~11에서 `"schemaVersion": "1.1"`로 작성했기 때문). 그렇지 않다면 픽스처 오류 — 픽스처를 먼저 고친다.
+
+- [ ] **Step 3: config / round2SkippedReason / finalState 테스트 추가**
+
+`tests/test_convergence_state_contract.py` 끝에 다음을 추가:
+
+```python
+def test_effective_max_rounds_is_one_to_three(fixture):
+    e = fixture["config"]["effectiveMaxRounds"]
+    assert isinstance(e, int) and 1 <= e <= 3
+
+
+def test_round2_skipped_reason_is_enum(fixture):
+    assert fixture["round2SkippedReason"] in VALID_ROUND2_SKIP_REASONS
+
+
+def test_final_state_is_enum(fixture):
+    assert fixture["finalState"] in VALID_FINAL_STATES
+
+
+def test_final_classification_counts_keys_present(fixture):
+    counts = fixture["finalClassificationCounts"]
+    assert set(counts.keys()) == {
+        "fullConsensus",
+        "partialConsensus",
+        "contested",
+        "workerUnique",
+    }
+    for v in counts.values():
+        assert isinstance(v, int) and v >= 0
+```
+
+- [ ] **Step 4: 라운드별 invariant 테스트 추가**
+
+```python
+def test_round_arithmetic_consistent(fixture):
+    """inputQueueSize == resolvedCount + carriedForwardCount."""
+    for r in fixture["roundHistory"]:
+        assert r["inputQueueSize"] == r["resolvedCount"] + r["carriedForwardCount"], (
+            f"round {r['round']}: {r['inputQueueSize']} != {r['resolvedCount']} + {r['carriedForwardCount']}"
+        )
+
+
+def test_round_input_matches_previous_carry_forward(fixture):
+    """Round N+1 inputQueueSize equals Round N carriedForwardCount."""
+    rounds = fixture["roundHistory"]
+    for prev, curr in zip(rounds, rounds[1:]):
+        assert curr["inputQueueSize"] == prev["carriedForwardCount"], (
+            f"round {curr['round']} input {curr['inputQueueSize']} "
+            f"!= round {prev['round']} carry {prev['carriedForwardCount']}"
+        )
+
+
+def test_dispatch_statuses_are_terminal(fixture):
+    for r in fixture["roundHistory"]:
+        for d in r["dispatches"]:
+            assert d["status"] in VALID_DISPATCH_STATUSES
+            assert isinstance(d["durationMs"], int) and d["durationMs"] >= 0
+
+
+def test_total_rounds_matches_round_history(fixture):
+    assert fixture["totalRounds"] == len(fixture["roundHistory"])
+```
+
+- [ ] **Step 5: classification / queue pruning invariant 테스트 추가**
+
+```python
+def test_findings_classifications_are_enum(fixture):
+    for f in fixture["findings"]:
+        assert f["classification"] in VALID_CLASSIFICATIONS
+
+
+def test_confirmed_findings_dont_reappear_after_classification_round(fixture):
+    """A finding classified as full/partial/worker-unique must not have a
+    `rounds` entry after the round in which it was resolved.
+
+    The fixture's `rounds[]` array is the per-finding vote ledger. A
+    re-prompt that re-included a confirmed item would surface as extra
+    rounds in this ledger. `contested` items may legitimately appear in
+    every round (queue carry-forward).
+    """
+    for f in fixture["findings"]:
+        if f["classification"] == "contested":
+            continue
+        if not f["rounds"]:
+            continue
+        # The last round in `rounds[]` is the resolution round. There must
+        # be no entries beyond it. Equivalent to: every classification
+        # other than contested resolves in its last recorded round.
+        resolution_round = f["rounds"][-1]["round"]
+        for r in f["rounds"]:
+            assert r["round"] <= resolution_round
+
+
+def test_contested_only_when_last_executed_round_done(fixture):
+    """A finding labeled `contested` must have a `rounds[]` entry whose
+    round index equals `totalRounds` (the last executed round)."""
+    for f in fixture["findings"]:
+        if f["classification"] != "contested":
+            continue
+        last_voted = max(r["round"] for r in f["rounds"])
+        assert last_voted == fixture["totalRounds"], (
+            f"{f['findingId']} contested but last vote in round "
+            f"{last_voted}, while totalRounds={fixture['totalRounds']}"
+        )
+
+
+def test_verdicts_are_enum(fixture):
+    for f in fixture["findings"]:
+        for r in f["rounds"]:
+            for vote in r["votes"].values():
+                assert vote["verdict"] in VALID_VERDICTS
+
+
+def test_classification_counts_match_findings(fixture):
+    counts = {"fullConsensus": 0, "partialConsensus": 0, "contested": 0, "workerUnique": 0}
+    mapping = {
+        "full-consensus": "fullConsensus",
+        "partial-consensus": "partialConsensus",
+        "contested": "contested",
+        "worker-unique": "workerUnique",
+    }
+    for f in fixture["findings"]:
+        counts[mapping[f["classification"]]] += 1
+    assert counts == fixture["finalClassificationCounts"]
+    assert counts == fixture["summary"]  # legacy alias parity
+```
+
+- [ ] **Step 6: round2SkippedReason 의미적 일관성 테스트 추가**
+
+```python
+def test_skip_reason_consistent_with_round_history(fixture):
+    reason = fixture["round2SkippedReason"]
+    rounds = fixture["roundHistory"]
+    effective_max = fixture["config"]["effectiveMaxRounds"]
+    last_round = rounds[-1]
+
+    if reason == "queue-empty":
+        assert last_round["carriedForwardCount"] == 0
+        assert last_round["round"] < effective_max
+    elif reason == "max-rounds-1":
+        assert effective_max == 1
+    elif reason == "all-reverify-non-result":
+        # every dispatch in the last round was non-completed
+        assert all(d["status"] != "completed" for d in last_round["dispatches"])
+        assert fixture["finalState"] == "aborted-non-result"
+    elif reason == "not-skipped":
+        # round 2 executed (or effective_max == 2 and last round was 2)
+        # AND finalState is converged or max-rounds-reached
+        assert fixture["finalState"] in {"converged", "max-rounds-reached"}
+```
+
+- [ ] **Step 7: 전체 테스트 실행**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && pytest tests/test_convergence_state_contract.py -v`
+Expected: 3 fixtures × 10 tests = **30 PASS**. 실패가 있으면 fixture 또는 test의 invariant가 잘못된 것 — fixture가 schema v1.1 contract를 정확히 모델링하지 못한 부분이므로 fixture를 먼저 의심한다.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add tests/test_convergence_state_contract.py
+git commit -m "test(convergence): contract tests for schema v1.1 invariants
+
+Parametrized over the three convergence fixtures. Asserts: schemaVersion,
+effectiveMaxRounds range, round2SkippedReason enum, finalState enum,
+finalClassificationCounts shape, per-round arithmetic
+(inputQueueSize == resolvedCount + carriedForwardCount), round carry-forward
+chain, dispatch statuses, verdict enum, contested-only-at-last-round, and
+skip-reason / round-history consistency."
+```
+
+---
+
+## Task 13: Baseline 계측 helper (`scripts/okstra-convergence-stats.py`)
+
+**Files:**
+- Create: `scripts/okstra-convergence-stats.py`
+- Test: `tests/test_okstra_convergence_stats.py`
+
+P1 효과(전후 비교) 측정용 helper. TDD로 작성.
+
+- [ ] **Step 1: 실패하는 첫 테스트 작성**
+
+`tests/test_okstra_convergence_stats.py`:
+
+```python
+"""Tests for scripts/okstra-convergence-stats.py — baseline metrics helper."""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[1]
+SCRIPT = REPO / "scripts" / "okstra-convergence-stats.py"
+
+
+def run_stats(*args: str) -> dict:
+    """Invoke the script with --json and return parsed stdout."""
+    proc = subprocess.run(
+        [sys.executable, str(SCRIPT), *args, "--json"],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return json.loads(proc.stdout)
+
+
+def test_reads_convergence_only(tmp_path):
+    """When team-state is omitted, the script still reports convergence-side metrics."""
+    fx = REPO / "tests" / "fixtures" / "convergence" / "early-exit.json"
+    out = run_stats("--convergence-state", str(fx))
+    assert out["roundCount"] == 1
+    assert out["dispatchCount"] == 3
+    assert out["dispatchDurationMsTotal"] == 92110 + 184221 + 201337
+    assert out["round2SkippedReason"] == "queue-empty"
+    assert out["finalClassificationCounts"]["fullConsensus"] == 2
+```
+
+- [ ] **Step 2: 테스트 실행 — 실패 확인**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && pytest tests/test_okstra_convergence_stats.py -v`
+Expected: FAIL — `scripts/okstra-convergence-stats.py` 가 아직 없음.
+
+- [ ] **Step 3: 최소 구현 — convergence-state 단독 모드**
+
+`scripts/okstra-convergence-stats.py`:
+
+```python
+#!/usr/bin/env python3
+"""Baseline metrics for okstra Phase 5.5 convergence.
+
+Aggregates dispatch counts, wall-clock totals, and (when team-state is
+supplied) worker token usage filtered to reverify dispatches. Reads:
+
+- convergence-<task-type>-<seq>.json  (required)
+- team-state-<task-type>-<seq>.json   (optional; for token deltas)
+
+Output: human-readable table by default, JSON when --json is passed. Used
+to record before/after numbers for the P1 convergence queue-pruning change.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def collect(convergence_path: Path, team_state_path: Path | None) -> dict:
+    convergence = json.loads(convergence_path.read_text())
+
+    dispatch_count = 0
+    duration_total = 0
+    for r in convergence["roundHistory"]:
+        for d in r["dispatches"]:
+            dispatch_count += 1
+            duration_total += int(d.get("durationMs", 0))
+
+    out = {
+        "schemaVersion": convergence.get("schemaVersion"),
+        "taskKey": convergence.get("taskKey"),
+        "effectiveMaxRounds": convergence["config"]["effectiveMaxRounds"],
+        "roundCount": len(convergence["roundHistory"]),
+        "dispatchCount": dispatch_count,
+        "dispatchDurationMsTotal": duration_total,
+        "round2SkippedReason": convergence.get("round2SkippedReason"),
+        "finalState": convergence.get("finalState"),
+        "finalClassificationCounts": convergence.get(
+            "finalClassificationCounts", convergence.get("summary", {})
+        ),
+        "reverifyTokenTotal": None,
+        "reverifyCostUsdTotal": None,
+    }
+
+    if team_state_path is not None and team_state_path.exists():
+        team = json.loads(team_state_path.read_text())
+        reverify_tokens = 0
+        reverify_cost = 0.0
+        for w in team.get("workers", []):
+            usage = w.get("usage", {})
+            agent_name = (w.get("agentName") or "")
+            # Reverify dispatches use the `-reverify-r<N>-` slug per
+            # okstra-convergence "Re-verification Agent Dispatch".
+            if "-reverify-r" not in agent_name:
+                continue
+            reverify_tokens += int(usage.get("totalTokens", 0) or 0)
+            reverify_cost += float(usage.get("estimatedCostUsd", 0) or 0)
+        out["reverifyTokenTotal"] = reverify_tokens
+        out["reverifyCostUsdTotal"] = round(reverify_cost, 4)
+
+    return out
+
+
+def format_human(stats: dict) -> str:
+    lines = [
+        f"taskKey                : {stats.get('taskKey')}",
+        f"schemaVersion          : {stats.get('schemaVersion')}",
+        f"effectiveMaxRounds     : {stats['effectiveMaxRounds']}",
+        f"roundCount             : {stats['roundCount']}",
+        f"dispatchCount          : {stats['dispatchCount']}",
+        f"dispatchDurationMsTotal: {stats['dispatchDurationMsTotal']}",
+        f"round2SkippedReason    : {stats['round2SkippedReason']}",
+        f"finalState             : {stats['finalState']}",
+        f"finalClassificationCounts: {stats['finalClassificationCounts']}",
+    ]
+    if stats["reverifyTokenTotal"] is not None:
+        lines.append(f"reverifyTokenTotal     : {stats['reverifyTokenTotal']}")
+        lines.append(f"reverifyCostUsdTotal   : ${stats['reverifyCostUsdTotal']:.4f}")
+    return "\n".join(lines)
+
+
+def main(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--convergence-state", required=True, type=Path)
+    p.add_argument("--team-state", type=Path, default=None)
+    p.add_argument("--json", action="store_true", help="emit JSON to stdout")
+    args = p.parse_args(argv)
+
+    if not args.convergence_state.exists():
+        print(f"error: convergence state not found: {args.convergence_state}", file=sys.stderr)
+        return 2
+
+    stats = collect(args.convergence_state, args.team_state)
+
+    if args.json:
+        print(json.dumps(stats, ensure_ascii=False, indent=2))
+    else:
+        print(format_human(stats))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
+```
+
+- [ ] **Step 4: 실행 권한 부여**
+
+Run: `chmod +x /Volumes/Workspaces/workspace/projects/Okstra/scripts/okstra-convergence-stats.py`
+Expected: 출력 없음.
+
+- [ ] **Step 5: 테스트 재실행 — PASS 확인**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && pytest tests/test_okstra_convergence_stats.py -v`
+Expected: 1 passed.
+
+- [ ] **Step 6: 두 번째 테스트 — team-state 포함 시 reverify 토큰 집계**
+
+`tests/test_okstra_convergence_stats.py` 끝에 추가:
+
+```python
+def test_reverify_token_aggregation(tmp_path):
+    convergence = tmp_path / "convergence.json"
+    convergence.write_text(json.dumps({
+        "schemaVersion": "1.1",
+        "taskKey": "fixture/tokens",
+        "config": {"enabled": True, "maxRounds": 2, "effectiveMaxRounds": 2, "verificationMode": "lightweight"},
+        "findings": [],
+        "roundHistory": [
+            {
+                "round": 1,
+                "inputQueueSize": 0,
+                "resolvedCount": 0,
+                "carriedForwardCount": 0,
+                "dispatches": [
+                    {"worker": "codex-worker", "status": "completed", "durationMs": 1000}
+                ],
+                "skippedWorkers": [],
+                "verificationsRequested": 1,
+                "verificationsCompleted": 1,
+                "newConsensus": 0,
+                "remainingInQueue": 0,
+                "earlyExit": True
+            }
+        ],
+        "round2SkippedReason": "queue-empty",
+        "finalState": "converged",
+        "totalRounds": 1,
+        "finalClassificationCounts": {"fullConsensus": 0, "partialConsensus": 0, "contested": 0, "workerUnique": 0},
+        "summary": {"fullConsensus": 0, "partialConsensus": 0, "contested": 0, "workerUnique": 0}
+    }))
+
+    team = tmp_path / "team-state.json"
+    team.write_text(json.dumps({
+        "workers": [
+            {"agentName": "codex-worker-error-analysis-001", "usage": {"totalTokens": 9999, "estimatedCostUsd": 0.10}},
+            {"agentName": "codex-worker-reverify-r1-error-analysis-001", "usage": {"totalTokens": 5000, "estimatedCostUsd": 0.06}},
+            {"agentName": "gemini-worker-reverify-r1-error-analysis-001", "usage": {"totalTokens": 3000, "estimatedCostUsd": 0.04}}
+        ]
+    }))
+
+    out = run_stats("--convergence-state", str(convergence), "--team-state", str(team))
+    assert out["reverifyTokenTotal"] == 8000
+    assert out["reverifyCostUsdTotal"] == 0.10
+```
+
+- [ ] **Step 7: 테스트 재실행**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && pytest tests/test_okstra_convergence_stats.py -v`
+Expected: 2 passed.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add scripts/okstra-convergence-stats.py tests/test_okstra_convergence_stats.py
+git commit -m "feat(scripts): okstra-convergence-stats.py baseline metrics helper
+
+Reads convergence-<task-type>-<seq>.json and (optionally) team-state to
+aggregate dispatch count, wall-clock total, and worker token/cost for
+reverify dispatches (filter on agentName containing '-reverify-r'). Used to
+record before/after numbers for the P1 queue-pruning change. Emits JSON
+when --json is passed."
+```
+
+---
+
+## Task 14: docs/kr/performance-improvement-plan-v2.md — Section 9 결론 갱신
+
+**Files:**
+- Modify: `docs/kr/performance-improvement-plan-v2.md`
+
+- [ ] **Step 1: Section 9 본문 갱신**
+
+기존 (line 318~326):
+
+```markdown
+## 9. 이번 계획의 결론
+
+현재 작업 계획은 P1을 최우선으로 둔 방향은 맞지만, 기존 표현의 "7-phase lifecycle"과 "contested-only 2라운드"는 코드와 맞지 않았다. 개선된 계획은 다음처럼 재정렬한다.
+
+1. P0로 용어와 측정 기준을 고정한다.
+2. P1에서 convergence queue pruning을 구현한다.
+3. P3 fast-track과 P4 prompt caching은 별도 설계/검증이 필요한 후속 작업으로 둔다.
+4. prepare render 병렬화와 token usage 증분화는 효과가 작거나 종료 단계 비용이므로 P1 이후 병렬 보조 작업으로 처리한다.
+```
+
+다음으로 교체:
+
+```markdown
+## 9. 이번 계획의 결론
+
+현재 작업 계획은 P1을 최우선으로 둔 방향은 맞지만, 기존 표현의 "7-phase lifecycle"과 "contested-only 2라운드"는 코드와 맞지 않았다. 개선된 계획은 다음처럼 재정렬한다.
+
+1. P0로 용어와 측정 기준을 고정한다.
+2. P1에서 convergence queue pruning을 구현한다.
+3. P3 fast-track과 P4 prompt caching은 별도 설계/검증이 필요한 후속 작업으로 둔다.
+4. prepare render 병렬화와 token usage 증분화는 효과가 작거나 종료 단계 비용이므로 P1 이후 병렬 보조 작업으로 처리한다.
+
+### 구현 plan 링크
+
+- P0 + P1: `docs/superpowers/plans/2026-05-14-convergence-queue-pruning.md`
+- P2 / P3 / P4 / P5 / P6: 미작성 (각 트랙별로 별도 plan 작성 필요)
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add docs/kr/performance-improvement-plan-v2.md
+git commit -m "docs(kr): link P0+P1 implementation plan from improvement-plan v2
+
+Section 9 conclusion now points to docs/superpowers/plans/2026-05-14-
+convergence-queue-pruning.md as the concrete plan that operationalizes the
+P0 terminology cleanup and P1 queue-pruning changes."
+```
+
+---
+
+## Final Verification
+
+전체 plan 적용 후 다음 명령으로 회귀 없음을 확인한다.
+
+- [ ] **Step A: 전체 pytest 회귀**
+
+Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && pytest -q`
+Expected: 신규 추가 분(`test_convergence_state_contract.py` + `test_okstra_convergence_stats.py`) PASS, 기존 테스트 회귀 없음.
+
+- [ ] **Step B: 모든 fixture JSON 유효성 일괄 확인**
+
+Run:
+```bash
+for f in /Volumes/Workspaces/workspace/projects/Okstra/tests/fixtures/convergence/*.json; do
+  python3 -c "import json; json.load(open('$f'))" && echo "OK $f"
+done
+```
+Expected: 3 줄 모두 `OK`.
+
+- [ ] **Step C: Schema doc / fixture 정합성 spot-check**
+
+Run: `grep -c "schemaVersion.*1.1" /Volumes/Workspaces/workspace/projects/Okstra/skills/okstra-convergence/SKILL.md`
+Expected: `>= 1`.
+
+Run: `grep -c "round2SkippedReason" /Volumes/Workspaces/workspace/projects/Okstra/skills/okstra-convergence/SKILL.md /Volumes/Workspaces/workspace/projects/Okstra/agents/SKILL.md`
+Expected: 양쪽 파일에서 각각 `>= 1`.
+
+- [ ] **Step D: Baseline 측정 한 번 실행 (사전 fixture에 대해)**
+
+Run:
+```bash
+python3 /Volumes/Workspaces/workspace/projects/Okstra/scripts/okstra-convergence-stats.py \
+  --convergence-state /Volumes/Workspaces/workspace/projects/Okstra/tests/fixtures/convergence/mixed-round2.json
+```
+Expected:
+```
+taskKey                : fixture/mixed-round2
+schemaVersion          : 1.1
+effectiveMaxRounds     : 2
+roundCount             : 2
+dispatchCount          : 5
+dispatchDurationMsTotal: 698988
+round2SkippedReason    : not-skipped
+finalState             : max-rounds-reached
+finalClassificationCounts: {'fullConsensus': 1, 'partialConsensus': 0, 'contested': 1, 'workerUnique': 0}
+```
+
+---
+
+## Out of Scope (별도 plan 필요)
+
+본 plan은 의도적으로 다음을 포함하지 않는다 — `docs/kr/performance-improvement-plan-v2.md` Section 9의 후속 항목으로 처리한다.
+
+- P2 (Prompt diet): worker definitions의 `[Required reading]` audience scope 축소. `agents/workers/_common.md` 추출은 install/packaging 호환성 검증이 선행 필요.
+- P3 (Fast-track routing): `requirements-discovery`가 `route=lite-implementation-planning` 등의 routing token을 남기는 설계. 승인 게이트 정책 결정 필요.
+- P4 (Prompt caching): Codex/Gemini wrapper에서 cache hint가 의미를 갖는지 spike 선행 필요.
+- P5 (Prepare render 병렬화): `scripts/okstra_ctl/run.py` instruction-set 독립 write 병렬화.
+- P6 (Token usage 증분화): `scripts/okstra_token_usage/` jsonl 선형 스캔 캐싱.
+
+---
+
+## Self-Review
+
+**Spec coverage:** Section 7 P1 구현 체크리스트 6개 항목 매핑
+
+1. Round 1-N pseudocode를 queue pruning으로 수정 → Task 2
+2. `contested`를 중간 상태로 쓰지 않음 → Task 1
+3. convergence state artifact 신규 필드 8개 → Task 4 + Tasks 9~11(fixture로 검증) + Task 12(contract 강제)
+4. report-writer가 round history와 final classification counts를 반영 → Tasks 6, 7, 8
+5. 단순 early convergence / mixed unresolved fixture + contract test → Tasks 9~12
+6. token usage collector로 dispatch/token/wall-clock 전후 기록 → Task 13
+
+Section 5 P0 항목 매핑
+
+- 문서가 task-type lifecycle과 lead 운영 단계를 혼동하지 않게 함 → Task 1 Step 2 ("Scope and Terminology" 블록)
+- convergence state 신규 필드 baseline 명시 → Task 4
+
+**Placeholder scan:** 모든 step에 실제 markdown/JSON/Python 코드가 포함되어 있고 TBD/TODO/"add appropriate error handling" 류 표현 없음.
+
+**Type consistency:**
+- `effectiveMaxRounds` (Tasks 4, 5, 9~12, 13): integer, 1..3, `config.` 하위 — 일관.
+- `round2SkippedReason` (Tasks 2, 4, 5, 7, 8, 9~12): top-level string enum `queue-empty | max-rounds-1 | all-reverify-non-result | not-skipped` — 일관.
+- `finalClassificationCounts` (Tasks 4, 7, 8, 9~12, 13): keys `fullConsensus | partialConsensus | contested | workerUnique` — 일관.
+- `roundHistory[].dispatches[]` shape `{worker, status, durationMs}` (Tasks 4, 9~12, 13) — 일관.
+- `roundHistory[].skippedWorkers[]` shape `{worker, reason}` 또는 dispatch 실패 시 `{worker, reason, terminalStatus}` (Tasks 4, 11, 12) — 일관 (terminalStatus는 optional).
+- Verdict enum `agree | disagree | supplement | verification-error` (Tasks 3, 11, 12) — 일관.
+
+**Execution order constraint:** Task 12(contract test)는 Tasks 9~11(fixture 생성) 이후에 실행되어야 한다. Task 13(stats helper)은 Tasks 9~11에 의존(fixture 사용)하므로 9~11 이후. 그 외는 독립적이며 임의 순서 가능.