okstra 0.20.1 → 0.21.1

package/runtime/skills/okstra-convergence/SKILL.md

@@ -6,6 +6,14 @@ user-invocable: false
 
 # OKSTRA Convergence
 
+## 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 [okstra/SKILL.md](../../SKILL.md) "Lifecycle Phase Boundaries") are unchanged by this skill. The lead operating phases (Phase 1 Intake → Phase 7 Persist, see [okstra/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.
+
 ## When to Use
 
 - When the okstra skill Phase 5.5 (convergence loop) begins
@@ -28,7 +36,7 @@ Configure this in the `convergence` block of `task-manifest.json`. If the block
 |------|------|------------|
 | `full-consensus` | All participating workers agree | Required |
 | `partial-consensus` | Majority of workers agree; dissenting opinions are recorded | Required |
-| `contested` | No consensus reached even after max rounds; each worker's position is recorded | Required |
+| `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 |
 | `worker-unique` | Only the discoverer confirms; others oppose or remain unverified | Required |
 
 ## Convergence Algorithm
@@ -51,37 +59,104 @@ Read the worker result files generated in Phase 4/5 and extract individual findi
   - Only one worker confirms a finding → `unique`, enter the verification queue.
 4. When grouping is ambiguous, prefer splitting over merging (avoid over-merging).
 5. Persist each finding's ticket set in the convergence state artifact under a `ticketIds` field on the finding record. Re-verification rounds carry the same field forward.
+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.
 
-### Round 1-N: Re-verification Loop
+### 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, roundHistory[-1].dispatches):
+    record round2SkippedReason 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 len(dispatches) > 0 AND 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 round2SkippedReason = "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, or all-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"
 ```
-FOR round = 1 to convergence.maxRounds:
-  IF the verification queue is empty:
-    BREAK (early convergence)
-
-  FOR each worker W (excluding the report writer):
-    List of findings W must verify = items in the verification queue for which W is not the discoverer
-    IF the list is empty:
-      SKIP
-    Send a re-verification request to W (batch: spawn once per worker)
-    Collect responses: AGREE / DISAGREE / SUPPLEMENT for each finding
-
-  FOR each finding F in the verification queue:
-    Vote aggregation:
-      - All AGREE or SUPPLEMENT → full consensus
-      - Majority AGREE or SUPPLEMENT → partial consensus
-      - All DISAGREE → worker-unique
-      - Mixed results → Carry over to next round (or marked as contested if this is the final round)
-
-  Update convergence state (record current round results)
-```
+
+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.
+
+#### Round 2 gate (`round_gate_open` predicate)
+
+`round_gate_open(queue, previous_dispatches)` returns `true` iff ALL three conditions hold (here `previous_dispatches` is the most recent entry's `dispatches` array in `roundHistory`); 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.
+
+#### 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 at least one dispatch was issued AND all reverify dispatches in a round terminate as non-result (mirroring the pseudocode's `len(dispatches) > 0` guard), 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.
 
 ### Convergence Test
 
-- 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`
+- 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.
 
 ## Verification Mode
 
@@ -229,13 +304,16 @@ For each finding:
 
 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.0",
+  "schemaVersion": "1.1",
   "taskKey": "<task-key>",
   "config": {
     "enabled": true,
     "maxRounds": 2,
+    "effectiveMaxRounds": 2,
     "verificationMode": "lightweight"
   },
   "findings": [
@@ -243,36 +321,52 @@ Save it to `runs/<task-type>/state/convergence-<task-type>-<seq>.json`.
       "findingId": "F-001",
       "summary": "<one-line summary>",
       "category": "<bug|risk|missing|observation|...>",
-      "originWorker": "<worker-id>",
+      "ticketIds": ["TICKET-123"],
+      "originWorker": "claude-worker",
       "originEvidence": "<evidence text>",
       "classification": "full-consensus",
       "rounds": [
         {
           "round": 1,
           "votes": {
-            "<worker-id>": {
-              "verdict": "agree",
-              "explanation": "<brief>"
-            }
+            "codex-worker": { "verdict": "agree", "explanation": "<brief>" },
+            "gemini-worker": { "verdict": "supplement", "explanation": "<brief>" }
           }
         }
       ],
-      "consensusWorkers": ["worker-a", "worker-b", "worker-c"],
+      "consensusWorkers": ["claude-worker", "codex-worker", "gemini-worker"],
       "dissentingWorkers": []
     }
   ],
   "roundHistory": [
     {
       "round": 1,
-      "verificationsRequested": 4,
-      "verificationsCompleted": 4,
-      "newConsensus": 2,
-      "remainingInQueue": 1,
-      "earlyExit": false
+      "inputQueueSize": 3,
+      "resolvedCount": 3,
+      "carriedForwardCount": 0,
+      "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": 3,
+      "remainingInQueue": 0,
+      "earlyExit": true
     }
   ],
+  "round2SkippedReason": "queue-empty",
   "finalState": "converged",
   "totalRounds": 1,
+  "finalClassificationCounts": {
+    "fullConsensus": 5,
+    "partialConsensus": 1,
+    "contested": 0,
+    "workerUnique": 1
+  },
   "summary": {
     "fullConsensus": 5,
     "partialConsensus": 1,
@@ -282,6 +376,24 @@ Save it to `runs/<task-type>/state/convergence-<task-type>-<seq>.json`.
 }
 ```
 
+> The example above shows an abbreviated artifact: the `findings[]` array contains only `F-001` even though `finalClassificationCounts` totals 7 — a real artifact has one `findings[]` entry per finding. The example uses a clean one-round queue-drained run for clarity; runs that hit Round 2 add a second `roundHistory[]` entry with the same shape.
+
+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.
+- `findings[].ticketIds`: array of ticket keys from Phase 4 grouping (parsed per the Round 0 step 5 rule). MAY be empty when the discovering worker tagged the finding `unknown`.
+- `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. Each entry is `{worker, status, durationMs}`. `status ∈ {completed, timeout, error, not-run}`. `durationMs` is integer milliseconds and is always present, even for terminal-non-result dispatches (use the elapsed time before the wrapper gave up).
+- `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 actually ran. Use `"max-rounds-1"` when `effectiveMaxRounds == 1` (Round 2 was never attempted). Use `"queue-empty"` when Round 1 fully drained the queue. Use `"all-reverify-non-result"` when all Round 1 dispatches terminated as non-result.
+- `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}`. Assigned by the lead at WHILE-loop exit: `converged` when the queue is empty at the end of any round; `max-rounds-reached` when the loop exits because `roundIndex == effectiveMaxRounds` with the queue still non-empty; `aborted-non-result` when the loop exits via the Worker-failure BREAK (Task 3's "Worker failure handling in reverify" rule 4). `aborted-non-result` is the new v1.1 value.
+- `totalRounds`: count of rounds actually executed (not `effectiveMaxRounds`). May be `0` when Round 0 produced no queue items (all findings reached consensus during grouping).
+
 ## Output
 
 Information to be passed to Phase 6 after executing this skill:

package/runtime/skills/okstra-report-writer/SKILL.md

@@ -46,7 +46,7 @@ The prompt MUST include, in this order at the top:
 6. `**Model:** Report writer worker, <modelExecutionValue>` (resolved per Phase 5.5 anchor-header rules)
 7. The full `[Required reading]` clause (see [okstra-team-contract](../okstra-team-contract/SKILL.md)) including `final-report-template.md`.
 8. The verbatim `## Available MCP Servers` block from the task brief, if present.
-9. The convergence classifications (Full/Partial/Contested/Worker-Unique) and pointers to all worker result files under `worker-results/`.
+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.
 10. For implementation-planning runs: a literal block listing the 8 required English section headings the validator scans for (`Option Candidates`, `Trade-off`, `Recommended Option`, `Stepwise Execution Order`, `Dependency`, `Validation Checklist`, `Rollback`, `User Approval Request`). The writer must use these exact substrings as section headings (Korean translation in parentheses is allowed).
 11. An explicit instruction: `You are the author of TWO files: (a) the final-report file at <Result Path>, (b) the worker-results file at <Worker Result Path>. Write both directly using your Write tool. Do not return the report inline. The validator fails the run when (b) is missing.`
 
@@ -199,7 +199,7 @@ The final-report template `okstra-final-report.template.md` Section 4.5 already
 
 ### Release-handoff section contract (release-handoff runs only)
 
-When the run's `task-type` is `release-handoff`, the final report MUST include Section `## 4.6 Release Handoff Deliverables` with all seven sub-sections (`4.6.1` Source Verification Report, `4.6.2` Feature Branch & Working-Tree State, `4.6.3` User Selections, `4.6.4` Executed Commands, `4.6.5` Commit List, `4.6.6` Pull Request Outcome, `4.6.7` Routing Recommendation). Every entry is dictated by the lead's recorded git/gh command log and the user's verbatim answers to the H1/H2/H3 menu prompts. If the user picked `skip` (H1) or `cancel` (H3), keep 4.6.3 populated but leave 4.6.4–4.6.6 explicitly empty per the template's empty-state lines.
+When the run's `task-type` is `release-handoff`, the final report MUST include Section `## 4.6 Release Handoff Deliverables` with all seven sub-sections (`4.6.1` Source Verification Report, `4.6.2` Feature Branch & Working-Tree State, `4.6.3` User Selections, `4.6.4` Executed Commands, `4.6.5` Commit List, `4.6.6` Pull Request Outcome, `4.6.7` Routing Recommendation). Every entry is dictated by the lead's recorded git/gh command log and the user's verbatim answers to the H1/H2/H3 menu prompts. H1 choices are `local only`, `push + PR`, or `skip`; release-handoff records existing implementation commits and MUST NOT create new commits. If the user picked `skip` (H1) or `cancel` (H3), keep 4.6.3 populated but leave 4.6.4–4.6.6 explicitly empty per the template's empty-state lines.
 
 **Single-lead authorship (release-handoff only):** release-handoff has no worker roster (no `Report writer worker`, no `Claude worker` drafter). The Claude lead authors the final-report file directly — there is no `Report writer worker` dispatch to perform in Phase 6, no resume-safe dispatch concern, and no mandatory worker-results file for a report-writer role. The rest of this skill's dispatch / resume / fallback machinery applies ONLY when `Report writer worker` is in the roster (i.e. every task-type other than `release-handoff`).
 
@@ -226,12 +226,13 @@ Section numbering matches `okstra-final-report.template.md`. Section 0 is the ca
 0. **Clarification Response Carried In** - if `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}` is non-empty, read `instruction-set/clarification-response.md`, reconcile every prior `Q*` row, and record the outcome (`resolved`/`obsolete`) plus the new evidence in this section before drafting the verdict
 1. **Problem or Verification Summary** - Key summary based on the brief and data (3–5 bullet points)
 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 max rounds; each worker’s position 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
-3. **Final Verdict** - Conclusion based on comprehensive evidence; direction provided
+   - In runs with convergence disabled, maintain the existing Consensus/Differences format and omit the Round History sub-table.
+3. **Final Verdict** - Conclusion based on comprehensive evidence; direction provided. For `final-verification`, include a `Verdict Token` field whose value is exactly `accepted`, `conditional-accept`, or `blocked`; `release-handoff` uses that field as its entry gate.
 4. **Evidence and Detailed Analysis**
    - Key Evidence: File path, line number, actual evidence
    - If explicit expected values are present in `reference-expectations.md`, specify whether they match or differ from the expected values in config files / deployment manifests
@@ -257,7 +258,8 @@ Section numbering matches `okstra-final-report.template.md`. Section 0 is the ca
 - Write the actual analysis text instead of a meta-description
 - Do not make unfounded assertions
 - Include findings from all four categories. Do not omit "contested" or "worker-unique" findings
-- Include the convergence round history and a summary of votes by worker for each finding
+- Include the convergence round history sub-table (Section 1) so the reader can audit which rounds executed and what `round2SkippedReason` indicates (e.g. `"not-skipped"` when Round 2 ran, or one of the three skip reasons). 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`.
 - The report writer worker does not participate in the re-verification vote. It is responsible only for drafting the final report
 
 ## Artifact Persistence Checklist

package/runtime/templates/prd/brief.template.md

@@ -1,3 +1,15 @@
+---
+title: OKSTRA PRD Brief - {{TASK_KEY}}
+id: {{FM_ID}}
+tags: {{FM_TAGS}}
+status: new
+aliases: {{FM_ALIASES}}
+date: {{TASK_DATE}}
+task-id: "{{TASK_ID}}"
+task-group: "{{TASK_GROUP}}"
+project-id: "{{PROJECT_ID}}"
+---
+
 # OKSTRA Task Brief
 
 <!--

package/runtime/templates/project-docs/task-index.template.md

@@ -1,3 +1,15 @@
+---
+title: OKSTRA Task Index - {{TASK_KEY}}
+id: {{FM_ID}}
+tags: {{FM_TAGS}}
+status: "{{CURRENT_TASK_STATUS}}"
+aliases: {{FM_ALIASES}}
+date: {{TASK_DATE}}
+task-id: "{{TASK_ID}}"
+task-group: "{{TASK_GROUP}}"
+project-id: "{{PROJECT_ID}}"
+---
+
 # OKSTRA Task Summary
 
 ## Current Snapshot

package/runtime/templates/reports/error-analysis-input.template.md

@@ -1,3 +1,15 @@
+---
+title: OKSTRA Error Analysis Input - {{TASK_KEY}}
+id: {{FM_ID}}
+tags: {{FM_TAGS}}
+status: ready-for-agent
+aliases: {{FM_ALIASES}}
+date: {{TASK_DATE}}
+task-id: "{{TASK_ID}}"
+task-group: "{{TASK_GROUP}}"
+project-id: "{{PROJECT_ID}}"
+---
+
 # OKSTRA Error Analysis Input
 
 ## Identity

package/runtime/templates/reports/final-report.template.md

@@ -1,3 +1,15 @@
+---
+title: OKSTRA Final Report - {{TASK_KEY}}
+id: {{FM_ID}}
+tags: {{FM_TAGS}}
+status: in-progress
+aliases: {{FM_ALIASES}}
+date: {{TASK_DATE}}
+task-id: "{{TASK_ID}}"
+task-group: "{{TASK_GROUP}}"
+project-id: "{{PROJECT_ID}}"
+---
+
 # {{TASK_KEY}} - Multi-Agent Cross Verification Final Report
 - Created at: {{RUN_TIMESTAMP_ISO}}
 - Task Key: {{TASK_KEY}}
@@ -71,6 +83,19 @@
 > 처리 토큰 = input + output + cache_creation + cache_read (raw). 환산 토큰 = cache_read×0.1 + cache_creation×1.25 + output×5 + input (input-등가). 비용은 공시 가격 기준 추정치.
 
 ## 1. Cross Verification Results
+
+### 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이 합의되어 재검증 라운드가 실행되지 않았습니다.`
+
 ### 1.1 Consensus
 
 | ID | Ticket ID | Statement | Supporting workers | Evidence (path:line / log / worker report) |
@@ -89,11 +114,12 @@
 
 ## 2. Final Verdict
 
-최종 결론과 권장 방향을 한 표로 명시합니다. `Direction`은 다음 중 하나입니다 — `continue-investigation`, `begin-implementation`, `approve`, `reject`, `hold`.
+최종 결론과 권장 방향을 한 표로 명시합니다. `Direction`은 다음 중 하나입니다 — `continue-investigation`, `begin-implementation`, `approve`, `reject`, `hold`. `task-type`이 `final-verification`이면 `Verdict Token` 값은 반드시 `accepted` / `conditional-accept` / `blocked` 중 정확히 하나여야 하며, `release-handoff`는 이 값을 진입 게이트로 사용합니다. 다른 task-type에서는 `Verdict Token`에 `not-applicable`을 적습니다.
 
 | 항목 | 값 |
 |------|----|
 | Final Conclusion | <한 줄 결론> |
+| Verdict Token | `<accepted / conditional-accept / blocked / not-applicable>` |
 | Direction | `<continue-investigation / begin-implementation / approve / reject / hold>` |
 | 근거 요약 | <`1.1`, `3.1` 등 본 보고서 행 ID를 콤마로> |
 | 다음 단계 | <Section 6 또는 7 중 어디로 이어지는지> |
@@ -168,10 +194,10 @@
 
 ### 4.5.5 Dependency / Migration Risk (의존성·마이그레이션 위험)
 
-순서 제약, 데이터 백필, feature-flag 선행 조건, 팀 간 조율 등을 표로 정리합니다. 해당 없음 시: `- 의존성·마이그레이션 위험 없음.` 한 줄.
+순서 제약, 데이터 백필, feature-flag 선행 조건, repo-internal sequencing 등을 표로 정리합니다. 외부 승인·권한 확인·vendor 또는 외부 팀 조율은 공통 권한 규칙상 위험/일정 항목으로 추가하지 않습니다. 해당 없음 시: `- 의존성·마이그레이션 위험 없음.` 한 줄.
 
-| ID | Kind (order / backfill / flag-precondition / coordination / other) | Item | 영향 | 완화 / 선행 작업 |
-|----|--------------------------------------------------------------------|------|------|------------------|
+| ID | Kind (order / backfill / flag-precondition / repo-sequencing / other) | Item | 영향 | 완화 / 선행 작업 |
+|----|------------------------------------------------------------------------|------|------|------------------|
 | DM-001 | <kind> | <한 줄 요약> | <영향 범위> | <대응 방안> |
 
 ### 4.5.6 Validation Checklist (검증 체크리스트)
@@ -212,9 +238,9 @@ pre-planning에서 발견된 모호점을 표로 남깁니다. 사용자가 승
 
 ### 4.6.1 Source Verification Report (선행 final-verification 인용)
 - Path (project-relative): `<runs/final-verification/.../reports/final-report-final-verification-<seq>.md>`
-- Quoted final verdict line (정확히 `accepted` 토큰을 포함해야 함):
+- Quoted `Verdict Token` row from that report's `## 2. Final Verdict` table (값이 정확히 `accepted`여야 함):
   > <원문 인용>
-- 만약 원본 verdict 가 `accepted` 가 아니라면 본 run 은 **실행되지 않아야 했습니다**. self-review 단계에서 contract-violated 로 처리하고 routing 을 `final-verification` 으로 되돌립니다.
+- 만약 원본 `Verdict Token` 값이 `accepted` 가 아니라면 본 run 은 **실행되지 않아야 했습니다**. self-review 단계에서 contract-violated 로 처리하고 routing 을 `final-verification` 으로 되돌립니다.
 
 ### 4.6.2 Feature Branch & Working-Tree State (run 시작 시점)
 - Feature branch (`git rev-parse --abbrev-ref HEAD`): `<branch-name>`
@@ -227,9 +253,9 @@ pre-planning에서 발견된 모호점을 표로 남깁니다. 사용자가 승
 ### 4.6.3 User Selections (메뉴 응답 기록)
 | 질문 ID | 질문 본문 | 사용자 응답 (원문) | 응답이 가능한 보기 |
 |---------|-----------|--------------------|--------------------|
-| H1 | 어떤 작업을 실행할까요? | <`commit only` / `commit + PR` / `skip`> | `commit only` / `commit + PR` / `skip` |
-| H2 | PR base 브랜치를 골라주세요. (H1=`commit + PR` 인 경우에만 묻습니다) | <`staging` / `preprod` / `prod` / `main` / `dev` / 사용자가 입력한 브랜치명> | `staging` / `preprod` / `prod` / `main` / `dev` / 직접 입력 |
-| H3 | 워커가 작성한 commit 메시지 / PR 본문 초안을 어떻게 처리할까요? | <`use as-is` / `edit then proceed` / `cancel`> | `use as-is` / `edit then proceed` / `cancel` |
+| H1 | 어떤 작업을 실행할까요? | <`local only` / `push + PR` / `skip`> | `local only` / `push + PR` / `skip` |
+| H2 | PR base 브랜치를 골라주세요. (H1=`push + PR` 인 경우에만 묻습니다) | <`staging` / `preprod` / `prod` / `main` / `dev` / 사용자가 입력한 브랜치명> | `staging` / `preprod` / `prod` / `main` / `dev` / 직접 입력 |
+| H3 | lead가 작성한 PR title / PR body 초안을 어떻게 처리할까요? | <`use as-is` / `edit then proceed` / `cancel`> | `use as-is` / `edit then proceed` / `cancel` |
 
 H1 이 `skip` 이거나 H3 가 `cancel` 인 경우, 본 섹션 다음의 4.6.4 ~ 4.6.6 은 빈 결과로 채우고 (mutating 명령 미실행) 4.6.7 routing 만 채웁니다.
 
@@ -242,13 +268,14 @@ H1 이 `skip` 이거나 H3 가 `cancel` 인 경우, 본 섹션 다음의 4.6.4 ~
 | 1 | `<예: git add path/to/file.py>` | `0` | `<요약>` |
 
 ### 4.6.5 Commit List (생성된 commit)
+- `implementation` phase에서 이미 생성된 commit 범위(`git log <base>..HEAD`)를 기록합니다. release-handoff는 새 commit을 만들지 않습니다.
 - 각 commit 의 short SHA / full SHA / subject / 영향 파일 목록을 한 항목씩 기록합니다.
-- staged 변경이 없어 commit 이 만들어지지 않았다면 다음 한 줄만 적습니다.
-  > `- No commit was produced (working tree had no staged changes).`
+- commit 범위가 비어 있으면 release-handoff가 실행되면 안 됩니다. 다음 한 줄을 적고 routing을 `implementation`으로 되돌립니다.
+  > `- No implementation commits found; release-handoff is blocked.`
 
 ### 4.6.6 Pull Request Outcome (PR 결과)
 - 다음 네 가지 중 정확히 하나의 형식으로 한 줄을 적습니다.
-  - `- No PR action requested.` (H1=`commit only` 또는 `skip` 인 경우)
+  - `- No PR action requested.` (H1=`local only` 또는 `skip` 인 경우)
   - `- PR created: <url>` + 타이틀 + base 브랜치
   - `- PR reused: <url>` (run 시작 시점에 같은 head 의 open PR 이 이미 존재해 `gh pr create` 를 생략한 경우)
   - `- PR creation skipped: <reason>` (H3=`cancel`, 또는 push/PR 생성 도중 사용자가 중단 지시한 경우. reason 은 풀어 쓴 한 문장)

package/runtime/templates/reports/final-verification-input.template.md

@@ -1,3 +1,15 @@
+---
+title: OKSTRA Final Verification Input - {{TASK_KEY}}
+id: {{FM_ID}}
+tags: {{FM_TAGS}}
+status: ready-for-agent
+aliases: {{FM_ALIASES}}
+date: {{TASK_DATE}}
+task-id: "{{TASK_ID}}"
+task-group: "{{TASK_GROUP}}"
+project-id: "{{PROJECT_ID}}"
+---
+
 # OKSTRA Final Verification Input
 
 ## Identity
@@ -16,6 +28,16 @@
 - What was supposed to be delivered?
 - What is the intended acceptance decision?
 
+## Source Implementation Report
+
+- Path (project-relative) to the originating `implementation` final-report:
+- Worktree / checkout path that final-verification must inspect:
+- Implementation base ref (`<base>` for `git diff --stat <base>..HEAD`):
+- Implementation head SHA expected at verification start:
+- Quoted `Commit list` / `Diff summary` excerpt from the implementation report:
+
+> If this section is empty, points to a missing report, or names a checkout that does not match the implementation report's commit list / diff summary, final-verification MUST end with status `blocked` and route back to `implementation` or `implementation-planning`. Do not verify an ambiguous target.
+
 ## Verification Evidence
 
 - PR or change summary:

package/runtime/templates/reports/implementation-input.template.md

@@ -1,3 +1,15 @@
+---
+title: OKSTRA Implementation Input - {{TASK_KEY}}
+id: {{FM_ID}}
+tags: {{FM_TAGS}}
+status: ready-for-agent
+aliases: {{FM_ALIASES}}
+date: {{TASK_DATE}}
+task-id: "{{TASK_ID}}"
+task-group: "{{TASK_GROUP}}"
+project-id: "{{PROJECT_ID}}"
+---
+
 # OKSTRA Implementation Input
 
 ## Identity

package/runtime/templates/reports/implementation-planning-input.template.md

@@ -1,3 +1,15 @@
+---
+title: OKSTRA Implementation Planning Input - {{TASK_KEY}}
+id: {{FM_ID}}
+tags: {{FM_TAGS}}
+status: ready-for-agent
+aliases: {{FM_ALIASES}}
+date: {{TASK_DATE}}
+task-id: "{{TASK_ID}}"
+task-group: "{{TASK_GROUP}}"
+project-id: "{{PROJECT_ID}}"
+---
+
 # OKSTRA Implementation Planning Input
 
 ## Identity

package/runtime/templates/reports/quick-input.template.md

@@ -1,3 +1,15 @@
+---
+title: OKSTRA Quick Input - {{TASK_KEY}}
+id: {{FM_ID}}
+tags: {{FM_TAGS}}
+status: ready-for-agent
+aliases: {{FM_ALIASES}}
+date: {{TASK_DATE}}
+task-id: "{{TASK_ID}}"
+task-group: "{{TASK_GROUP}}"
+project-id: "{{PROJECT_ID}}"
+---
+
 # OKSTRA Quick Input
 
 ## Basic Identity

package/runtime/templates/reports/release-handoff-input.template.md

@@ -1,3 +1,15 @@
+---
+title: OKSTRA Release Handoff Input - {{TASK_KEY}}
+id: {{FM_ID}}
+tags: {{FM_TAGS}}
+status: ready-for-agent
+aliases: {{FM_ALIASES}}
+date: {{TASK_DATE}}
+task-id: "{{TASK_ID}}"
+task-group: "{{TASK_GROUP}}"
+project-id: "{{PROJECT_ID}}"
+---
+
 # OKSTRA Release Handoff Input
 
 ## Identity
@@ -13,15 +25,16 @@
 ## Source Verification Report
 
 - Path (project-relative) to the `final-verification` final-report whose verdict authorises this handoff:
-- Verbatim quoted line from that report's `## 2. Final Verdict` (MUST read exactly `accepted`):
+- Verbatim quoted `Verdict Token` row from that report's `## 2. Final Verdict` table (MUST have value `accepted`):
 - Run timestamp of that final-verification run:
 
-> If this section is empty or cites a verdict other than `accepted`, the lead MUST end the run immediately and route back to `final-verification`. Release-handoff never operates on `conditional-accept` or `blocked` outcomes.
+> If this section is empty or cites a `Verdict Token` value other than `accepted`, the lead MUST end the run immediately and route back to `final-verification`. Release-handoff never operates on `conditional-accept` or `blocked` outcomes.
 
 ## Working-Tree Snapshot (filled at run start)
 
 - Feature branch (`git rev-parse --abbrev-ref HEAD`):
 - `git status --short` output at run start:
+- Existing implementation commits (`git log --oneline <base>..HEAD`):
 - Existing PR for this head, if any (`gh pr list --head <branch> --state open --json url --jq '.[0].url'`):
 
 ## Candidate PR Base Branches
@@ -30,10 +43,10 @@
 - Repo-specific preference, if known (e.g. `main` is the integration branch):
 - Branches that MUST NOT be used as a base in this repo (security / freeze rules):
 
-## Commit Message Drafter Inputs
+## PR Draft Inputs
 
-- Commit type convention this repo follows (`release-please` types, plain conventional commits, free-form):
-- `git diff <base>..HEAD --stat` (or equivalent change summary) for the drafter to ground its message on:
+- PR title convention this repo follows (`release-please` types, plain conventional commits, free-form):
+- `git log --oneline <base>..HEAD` and `git diff <base>..HEAD --stat` for the lead to ground its PR draft on:
 - Files known to be part of the prior `implementation` run's approved plan:
 - Files appearing in the diff that were in the prior run's `Out-of-plan edits` block:
 
@@ -45,7 +58,7 @@
 
 ## User-Selection Defaults (advisory only — the user still chooses interactively)
 
-- Suggested action (Q1): `commit only` | `commit + PR` | `skip`
+- Suggested action (Q1): `local only` | `push + PR` | `skip`
 - Suggested base (Q2): one of the candidate base branches above
 - Suggested message handling (Q3): `use as-is` | `edit then proceed`
 
@@ -59,12 +72,12 @@
 
 > The lead MUST NOT extend handoff actions into items listed here. If an excluded item should ship in this PR, edit this section before the run starts — do not silently fold it in.
 
-## Questions for Drafter Worker
+## Questions for Lead Drafting
 
-1. What commit type and scope best describe the cumulative diff?
-2. What single subject line summarises the change in under 72 characters?
+1. What PR title best describes the cumulative committed diff?
+2. Which implementation commits should be highlighted in the PR body?
 3. What changed at a behavioural level (not just file-level) that reviewers need to know?
-4. Which prior commits in this feature branch should be referenced or amended by this commit?
+4. Which prior commits in this feature branch should be referenced in the PR?
 5. Does the diff include any change that requires a follow-up PR (migration squash, config split, etc.) — and if so, should that be noted in the PR body's `## Follow-ups` block?
 
 ## Conversion Note