okstra 0.114.0 → 0.116.0

package/docs/kr/architecture.md

@@ -235,7 +235,7 @@ per-process 환경 변수에 task 정체성·경로·workflow 상태를 보관
 - standard workflow의 기본 worker role은 `Claude worker`, `Codex worker`, `Report writer worker`이며, `Antigravity worker`는 `--workers` 또는 프로필에서 명시할 때만 포함되는 옵션입니다.
 - worker 역할 분담과 최종 판단은 Claude가 task bundle을 읽고 수행합니다.
 - 사용자 홈에 설치된 okstra Claude assets(`~/.claude/skills`, `~/.claude/agents`) 는 `Agent(name: ...)` 로 워커를 dispatch 하도록 Claude 를 유도합니다 — 워커는 세션의 implicit team 에 자동 합류합니다.
-- **팀 lifecycle (Claude Code v2.1.178+)**: v2.1.178 이 `TeamCreate` / `TeamDelete` 도구와 `Agent(...)` 의 `team_name` 파라미터를 제거했습니다. `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`(`okstra install` 이 `settings.json` 에 시드) 이면 세션마다 implicit team 1개가 시작 시점에 자동 생성됩니다. lead 는 Phase 3 에서 팀을 만드는 도구를 호출하지 않고, `teamName` audit 라벨과 `teamCreate: { attempted: false, status: "implicit", splitPane: <$TMUX 유무> }` 만 기록한 뒤 워커를 `Agent(name: "<role>-worker", run_in_background: true)`(team_name 없음)로 dispatch 합니다. split-pane teammate 는 `$TMUX` 가 설정돼 있고 `teammateMode: auto` 일 때 나타나며, tmux 밖이면 in-process 로 돕니다(둘 다 정상). run 종료 시 Phase 7 토큰 집계 이후 잔여 tmux pane 정리를 확인하고, split-pane run 에서만 worker teammate 를 정리할지 확인합니다. 승인 시 `okstra-team-reconcile.sh` 로 dead-pane stale-active 멤버를 inactive 로 정리하고 각 완료 teammate 에 `SendMessage` shutdown_request 를 보냅니다 — implicit team 자체를 지우는 도구는 없으며, 팀은 세션 종료와 함께 사라집니다. 사용자가 유지하면 teammate 는 FleetView roster 에 남고, lead 는 Teams/FleetView 에서 제거하라고 안내합니다 (`prompts/profiles/_common-contract.md` 의 *Run-end teammate teardown*). Phase 7 토큰 집계는 `teamCreate.status` 가 `implicit`/`skipped`/`error` 일 때 `agentName` 기반으로 워커 세션을 찾습니다(implicit team 은 jsonl 을 `session-<leadSid>` 로 태깅하므로 okstra 의 `teamName` 라벨 needle 만으로는 lead 만 잡힘).
+- **팀 lifecycle (Claude Code v2.1.178+)**: v2.1.178 이 `TeamCreate` / `TeamDelete` 도구와 `Agent(...)` 의 `team_name` 파라미터를 제거했습니다. `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`(`okstra install` 이 `settings.json` 에 시드) 이면 세션마다 implicit team 1개가 시작 시점에 자동 생성됩니다. lead 는 Phase 3 에서 팀을 만드는 도구를 호출하지 않고, `teamName` audit 라벨과 `teamCreate: { attempted: false, status: "implicit", splitPane: <$TMUX 유무> }` 만 기록한 뒤 워커를 `Agent(name: "<role>-worker", run_in_background: true)`(team_name 없음)로 dispatch 합니다. split-pane teammate 는 `$TMUX` 가 설정돼 있고 `teammateMode: auto` 일 때 나타나며, tmux 밖이면 in-process 로 돕니다(둘 다 정상). run 종료 시 Phase 7 토큰 집계 이후 잔여 tmux pane 정리를 확인하고, split-pane run 에서만 worker teammate 를 정리할지 확인합니다. 승인 시 `okstra-team-reconcile.sh` 로 dead-pane stale-active 멤버를 inactive 로 정리하고 각 완료 teammate 에 `SendMessage` shutdown_request 를 보냅니다 — implicit team 자체를 지우는 도구는 없으며, 팀은 세션 종료와 함께 사라집니다. 사용자가 유지하면 teammate 는 FleetView roster 에 남고, lead 는 Teams/FleetView 에서 제거하라고 안내합니다 (`prompts/profiles/_common-contract.md` 의 *Run-end teammate teardown*). Phase 7 토큰 집계는 `teamCreate.status` 가 `implicit`/`skipped`/`error` 일 때 top-level `agentName` 또는 nested `subagents/agent-a<name>-<hash>.jsonl` 파일명 기반으로 워커 세션을 찾습니다.
 
 ## Claude prompt contract
 
@@ -698,7 +698,7 @@ Phase 7 step 1.5 가 final-report MD 한 본을 입력으로 self-contained HTML
 
 - Helper CLI: `scripts/okstra-token-usage.py`
 - 수집 소스:
-  - Claude lead/workers: `~/.claude/projects/<cwd-as-dashes>/<sessionId>.jsonl`의 per-message `message.usage`
+  - Claude lead/workers: `~/.claude/projects/<cwd-as-dashes>/<sessionId>.jsonl` 또는 `~/.claude/projects/<cwd-as-dashes>/<lead-session>/subagents/agent-a<worker-name>-<hash>.jsonl` 의 per-message `message.usage`. nested subagent 파일은 파일명에서 worker name 을 복원하고, 현재 run 의 `team-state.lead.sessionId` 디렉터리 아래만 집계합니다.
   - Codex CLI: `~/.agent/sessions/Y/M/D/rollout-*.jsonl`의 마지막 `total_token_usage.total_tokens`
   - Antigravity CLI: `~/.antigravity/tmp/*/chats/session-*.json`의 per-message `tokens.total`
 - billable-equivalent token math와 USD cost estimation을 함께 기록합니다. Anthropic billing ratio(`cache_creation_5m=1.25x`, `cache_creation_1h=2.0x`, `cache_read=0.1x`, `output=5x`)를 반영합니다. transcript 의 `usage.cache_creation.ephemeral_5m_input_tokens` / `ephemeral_1h_input_tokens` 분해가 있으면 분리 집계합니다.

package/docs/kr/follow-ups/2026-07-10-final-report-option-3.md

@@ -0,0 +1,51 @@
+# Final Report 가독성 후속: 3안 재검토
+
+상태: 보류
+작성일: 2026-07-10
+
+## 배경
+
+이번 1차 가독성 개선은 범위를 좁게 유지했다.
+
+- `readerSummary`로 Markdown final-report 앞부분에 사람이 먼저 읽을 요약 진입점을 둔다.
+- HTML report view에 Reader Summary dashboard와 reader mode를 추가한다.
+- 기존 `final-report` data는 `verdictCard` fallback으로 계속 호환한다.
+
+이 문서는 더 큰 3안을 현재 변경에 섞지 않고, 나중에 별도 판단할 재검토 후보로 남긴다.
+
+## 보류한 3안
+
+`final-report` 산출물 자체를 목적별로 분리할지 재검토한다.
+
+현재 구조는 하나의 canonical Markdown 문서와 그 문서에서 생성되는 view를 유지한다. 3안은 요약 블록이나 HTML 필터링만으로 충분한지, 아니면 report를 목적별 artifact로 나누는 편이 더 나은지 비교하는 작업이다.
+
+비교 후보:
+
+- 짧은 human handoff report와 별도 audit appendix.
+- 같은 `data.json`에서 생성되는 `summary` view와 `audit` view.
+- 사람이 먼저 행동하는 섹션만 남기는 phase별 slim report template.
+- reporter handoff, implementer handoff, verifier audit, release handoff 같은 role별 view set.
+
+## 재검토 트리거
+
+아래 중 하나가 반복되면 이 문서를 다시 연다.
+
+- `readerSummary`와 HTML reader mode 배포 후에도 사용자가 `final-report`를 읽기 어렵다고 말한다.
+- 리뷰어가 항상 같은 audit 섹션을 건너뛰거나 더 작은 handoff artifact를 요구한다.
+- `final-report` 생성에서 같은 evidence가 여러 섹션에 반복된다.
+- 향후 schema migration에서 report artifact 계약을 어차피 건드려야 한다.
+
+## 결정할 질문
+
+- Markdown이 계속 primary human artifact인가, 아니면 `data.json`만 canonical source로 두고 view를 생성할 것인가?
+- follow-up task에 기본 첨부할 artifact는 무엇인가?
+- 어떤 섹션이 human-action material이고, 어떤 섹션이 audit-only material인가?
+- 분리를 validator가 강제해야 하는가, renderer convention으로 둘 것인가?
+- 분리가 기존 `render-views`, follow-up spawning, approval sidecar에 어떤 영향을 주는가?
+
+## 참조
+
+- 현재 schema: `schemas/final-report-v1.0.schema.json`
+- 현재 Markdown template: `templates/reports/final-report.template.md`
+- 현재 HTML renderer: `scripts/okstra_ctl/report_views.py`
+- 현재 report UI assets: `templates/reports/report.css`, `templates/reports/report.js`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.114.0",
+  "version": "0.116.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.114.0",
-  "builtAt": "2026-07-08T17:31:16.739Z",
+  "package": "0.116.0",
+  "builtAt": "2026-07-09T17:28:22.971Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/report-writer-worker.md

@@ -88,6 +88,7 @@ Rules (the schema enforces most of these — they are listed here so you know *w
 - `header.reportAuthor` is `"Report writer worker"`; `header.reportOwner` is `"Claude lead"`. Set author to `"Claude lead"` only for `release-handoff` runs (single-lead by design) or a recorded report-writer dispatch failure fallback.
 - **Source items (worker:item) preservation.** Every `consensus[].sourceItems`, `differences[].workersPosition[].itemId`, and `evidence.primary[].sourceItems` entry MUST carry the worker:item-id pair (e.g. `claude:F-001`, `codex:1.1`, `antigravity:F-3`, or `lead:mcp-1` for lead-only evidence). The schema enforces this via the `SourceItem` regex; bare worker-name lists no longer parse.
 - **Verdict Card consistency.** `verdictCard.verdictToken` / `.direction` / `.nextStep` MUST byte-match `finalVerdict.verdictToken` / `.direction` / `.nextStep` and `recommendedNextSteps[0].text`. The renderer pulls both from the same data structure — duplicating values across `verdictCard` and `finalVerdict` is intentional so the validator can diff them.
+- **Reader Summary.** Populate `readerSummary` when the schema excerpt exposes it. It is the human-first entrypoint for both Markdown and HTML: one sentence for the decision, one for the human action required, one for blockers, one for audit sections safe to skip on first read, and one runnable recommended command. Do not duplicate raw evidence tables here.
 - **§7 phase-continuation row (mandatory for non-terminal task-types).** When `header.taskType` is one of `requirements-discovery` / `implementation-planning` / `error-analysis` / `implementation` / `final-verification`, `followUpTasks` MUST contain at least one row whose `origin` is `phase-continuation`, `suggestedTaskType` equals the next phase (byte-identical to `finalVerdict.nextStep`'s referenced phase), `newTaskId` reuses the current task-id, `autoSpawn` is `"no"`, and `priority` is `"P0"`. For `release-handoff` runs, omit the phase-continuation row. Schema `allOf` clause enforces this via `contains`.
 - **No deprecated sections.** The schema has no `4.5.8 User Approval Request` body field, no `4.5.9 Open Questions`, no `5.1 추가 자료 요청`, no `5.2 사용자 확인 질문` — clarifications go under the unified `clarificationItems[]` array.
 - **Optional Section 0.** Include `clarificationCarryIn` ONLY when the lead's prompt provides a non-empty carry-in path. Omit the key entirely otherwise (do NOT set it to `null` or an empty object).

package/runtime/prompts/launch.template.md

@@ -85,3 +85,37 @@ Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at
 - Source path: `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}`
 - If the source path above is empty, no prior clarification response was attached to this run.
 - If the source path is set, a copy is staged at `{{INSTRUCTION_SET_RELATIVE_PATH}}/clarification-response.md`. Read it before running workers; reconcile each `C-*` row in section 1 (`## 1. Clarification Items`) of the prior report against new evidence and record the outcome in the conditional `## 0. Clarification Response Carried In From Previous Run` section of this run's final report (render that heading only when carry-in is non-empty — the validator fails empty Section 0 stubs).
+
+### Incremental re-verification (implementation-planning clarification re-runs only)
+
+The **default is full re-verification**. Only narrow this re-run to the impacted stages when the deterministic `okstra incremental-scope` CLI returns `mode == "incremental"`; on any doubt, stay full. This procedure fires ONLY when this run's task-type is `implementation-planning` AND a prior final report exists for this task-key (its data.json at `runs/implementation-planning/reports/final-report-implementation-planning-<prev-seq>.data.json`, where `<prev-seq>` is the most recent prior implementation-planning run's seq). For every other task-type, ignore this block and re-verify normally. This branches on the CLI's `mode` output only — it does NOT re-implement the safety logic in the prompt.
+
+1. **Resolve the impacted stage set (safety condition C2 — your discretionary judgement).** For each answered `C-*` row you reconciled in §1, decide which **Stage Map stage numbers** (from the prior plan's `## 5.5 Stage Map`) the answer touches. Rules:
+   - Pass ONLY stage numbers that appear in that Stage Map. Never invent or guess a stage number — a number absent from the graph must never enter `--impacted` (it would leak into `reverify_stages`).
+   - If you cannot map a touched item to a real stage with confidence, leave the impacted set **EMPTY** — an empty set forces `mode == "full"`. Widening to full is always the safe choice; guessing is not.
+   - If any answer overturns the selected Option, restructures the stages, or changes the recommended approach (rather than a localized detail), also leave the impacted set **EMPTY**.
+2. **Resolve the two base SHAs (safety condition C1 — code-unchanged, decided by the CLI, not by you).**
+   - Current base SHA: `{{EXECUTOR_WORKTREE_BASE_REF}}` (this run's resolved worktree base commit).
+   - Prior base SHA: read the prior run's active-run-context at `runs/implementation-planning/state/active-run-context-implementation-planning-<prev-seq>.json`, field `executorWorktree.baseRef` (a resolved commit SHA). The run-manifest does NOT carry this field — use the active-run-context. If that file or field cannot be located, treat the run as **full** and skip the rest of this procedure.
+3. **Call the CLI** (it is pure — same inputs always yield the same decision):
+   ```
+   okstra incremental-scope \
+     --prev-data runs/implementation-planning/reports/final-report-implementation-planning-<prev-seq>.data.json \
+     --cur-base-sha {{EXECUTOR_WORKTREE_BASE_REF}} \
+     --prev-base-sha <prior baseRef from step 2> \
+     --impacted <csv of impacted stage numbers, empty for full>
+   ```
+   The CLI reads the plan's dependency graph from the top-level `## 5.5 Stage Map` (`implementationPlanning.stageMap`), which is authoritative for the impacted stage numbers — there is no per-option stage graph. The CLI prints JSON `{mode, reverify_stages, carry_stages, reason}`. Instruct the report-writer to record this JSON verbatim into this run's data.json as `implementationPlanning.incrementalDecision` (keys `mode`, `reverifyStages`, `carryStages`, `reason`) — the renderer turns it into the `### 0.1 Incremental Re-Verification Scope` audit block, and the validator fails an `incremental`-mode run whose Section 0 omits that block.
+4. **`mode == "full"`** → run the existing full re-verification path unchanged; ignore `reverify_stages` / `carry_stages`.
+5. **`mode == "incremental"`** → scope every worker dispatch prompt to `reverify_stages` only (the downstream closure of the impacted stages). Do NOT re-analyze `carry_stages` — their prior plan-item verdicts are carried forward verbatim (see `prompts/profiles/implementation-planning.md` "Cross-verification mode" and `prompts/lead/convergence.md` "Convergence scope").
+6. **Merge carried-forward verdicts.** In `incremental` mode, after this run's report-writer authors its data.json, instruct it to merge the prior plan-item verdicts for `carry_stages` into it:
+   ```
+   okstra incremental-carry \
+     --prev-data runs/implementation-planning/reports/final-report-implementation-planning-<prev-seq>.data.json \
+     --cur-data <this run's data.json> \
+     --prev-seq <prev-seq> \
+     --out <this run's data.json>
+   ```
+   A non-zero exit (`CarryError` — schema drift between the two runs) means the carry is unsafe: fall back to **full** — discard the incremental result and re-verify every stage. Note: `verdictCard` / `finalVerdict` are NEVER carried — this run re-computes them from the re-verified plus carried plan items.
+
+   **Carry completeness (BLOCKING).** In incremental mode, this run's `planItems` MUST contain every plan-item id from the re-verified stages, each carried forward with its updated verdict. If re-verification concludes a plan item should be REMOVED, that is a signal the answer's blast radius is NOT local — abandon incremental and re-route to a FULL re-verification. The carry merge only ever ADDS prior items whose id is absent from this run; it cannot distinguish a legitimate deletion from an untouched carry, so it would resurrect a stale verdict.

package/runtime/prompts/lead/convergence.md

@@ -66,6 +66,8 @@ Read the worker result files generated in Phase 4/5 and extract individual findi
 
 **Convergence scope.** Convergence operates on sections 1–5 of the worker output (the common core, see `team-contract` "Worker Output Contract"). Section 6 ("Specialization Lens") is additive worker-specific depth and MUST NOT be fed into the consensus grouping, the verification queue, or the round-N reverify prompts. Carry Section 6 forward into the final report verbatim through the report-writer worker — do not let it inflate `unique` counts or trigger spurious `verification-error` statuses.
 
+**Incremental re-verification scope (implementation-planning clarification re-runs).** When the lead's `okstra incremental-scope` decision is `mode == "incremental"` (procedure in `prompts/launch.template.md` §"Clarification Response Carried In"), only findings the lead attributes to a stage in `reverify_stages` enter the verification queue. Findings and plan-item verdicts carried forward for `carry_stages` are NOT re-queued — they skip the re-verification rounds entirely and are merged verbatim into this run's data.json via `okstra incremental-carry`. When the decision is `mode == "full"` (the default), every finding enters the queue as usual.
+
 1. In the "Findings" section of each worker's results, identify individual items by number (F-001, F-002, ...) and parse the ticket identifier attached to each item:
    - For table-form findings, read the `Ticket ID` column.
    - For bullet/numbered findings, parse `[TICKETID: <id>]` from the item title.

package/runtime/prompts/lead/okstra-lead-contract.md

@@ -366,7 +366,7 @@ jq -s 'group_by(.errorType) | map({type: .[0].errorType, count: length})' <runDi
 
 The errors log is informational. Its presence/absence does not affect the final verdict. Do not block report writing on it.
 
-After persistence, reply briefly in the resolved Report Language with: completion status, final report path, team-state path, validator result, resume command path, any remaining blocker.
+After persistence, reply briefly in the resolved Report Language with: completion status, final report path, team-state path, validator result, resume command path, any remaining blocker. **Lead this reply with the run's task identity** — state `<task-group>/<task-id>` (or the full `taskKey`) first, so the reader knows which task the reply is about. **Every run-artifact path in this reply MUST be task-qualified** — report the final report as `.okstra/tasks/<task-group>/<task-id>/runs/<task-type>/reports/final-report-<task-type>-<seq>.md` (the full path rooted at the task bundle), NOT the bare `runs/<task-type>/reports/...` form. The bare `runs/...` prefix is byte-for-byte identical across every task-group / task-id of the same task-type, so it cannot tell one task's report from another's — always emit the `.okstra/tasks/<task-group>/<task-id>/` prefix. The same task-qualified rule applies to the team-state path, resume command path, and any other run-artifact path this reply cites.
 
 ## Run-scoped pane & teammate lifecycle
 

package/runtime/prompts/lead/report-writer.md

@@ -281,7 +281,7 @@ Every field MUST anchor its claim with at least one evidence reference — a `pa
 
 **Reader-facing prose MUST NOT cite a bare brief/worker-internal ID that this report never surfaces** — `RC-*` (reporter confirmations, defined in the brief), `RF-*` / `F-*` (findings, defined in worker-results) have no anchor in the final report, so a reader hits an opaque token with nothing to click. Either expand it inline (`the confirmed version target 1.27.47→1.27.48`) or, for an audit trail, namespace it (`claude:F-005`). **Enforced:** `_validate_no_opaque_id_references` fails a bare `RC-*` / `RF-*` / non-namespaced `F-*` appearing in `verdictCard` / `finalVerdict` / `rationale` / `clarificationItems[].statement`. (The renderer anchors + links in-report IDs of any digit width, so a surfaced `RC-4`-style id does resolve.) Do NOT restate the Verdict Card or the §5.4 trade-off matrix verbatim — this section is the *why*, in connected prose, that those tables compress.
 
-0. **Clarification Response Carried In** — render this `## 0.` heading ONLY when `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}` is non-empty. Walk every `C-*` row of the prior report's `## 1. Clarification Items` table, reconcile against new evidence, and record the outcome (`resolved` / `obsolete`) with citation before drafting the verdict. When no carry-in path was provided, OMIT the `## 0.` heading entirely — the validator fails an empty Section 0 stub.
+0. **Clarification Response Carried In** — render this `## 0.` heading ONLY when `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}` is non-empty. Walk every `C-*` row of the prior report's `## 1. Clarification Items` table, reconcile against new evidence, and record the outcome (`resolved` / `obsolete`) with citation before drafting the verdict. When no carry-in path was provided, OMIT the `## 0.` heading entirely — the validator fails an empty Section 0 stub. When the lead ran `okstra incremental-scope` for this re-run, record its JSON verbatim into `implementationPlanning.incrementalDecision` (`mode`, `reverifyStages`, `carryStages`, `reason`); the renderer emits the `### 0.1 Incremental Re-Verification Scope` audit block from it, and the validator fails an `incremental`-mode run whose Section 0 omits that block. In `incremental` mode this run's `planItems` MUST carry every plan-item id from the re-verified stages forward with its updated verdict; if re-verification concludes a plan item should be REMOVED, that is a signal the answer's blast radius is not local — do not drop it here, tell the lead to abandon incremental and re-route to a FULL re-verification, because the carry merge only adds prior items and would resurrect the removed item's stale verdict.
 1. **Cross Verification Results** — 4 categories (Full / Partial / Contested / Worker-Unique) when convergence is enabled, per `convergence`. Prepend the Round History sub-table (columns: `Round | inputQueueSize | resolvedCount | carriedForwardCount | dispatches | skippedWorkers`) plus a `round2SkippedReason: <value>` note, pulled verbatim from `convergence-<task-type>-<seq>.json`. Empty contested list renders as `- 합의 미달 항목 없음.`. Convergence-disabled runs use the legacy Consensus/Differences format and omit the round table.
 2. **Final Verdict** — `Direction` ∈ `continue-investigation` / `begin-implementation` / `approve` / `reject` / `hold`. **Verdict Token** is `not-applicable` for every task-type except `final-verification` — see "Final-verification verdict token contract" below for that case.
 3. **Evidence and Detailed Analysis** — primary evidence rows (file path, line, snippet); secondary evidence / alternate interpretations. If `reference-expectations.md` lists explicit expected values, record match/gap per row.

package/runtime/prompts/profiles/implementation-planning.md

@@ -43,6 +43,7 @@
 - Cross-verification mode:
   - Phase 5.5 finding convergence runs in **adversarial mode** for this phase (`convergence.adversarial=true`). Verifiers actively try to refute each worker finding (requirement gap / risk / option) by re-inspecting its cited evidence; the burden of proof sits on the claim. See `prompts/lead/convergence.md` §"Adversarial Verification Mode".
   - §5.5.9 plan-body verification runs with an **adversarial posture** (`prompts/lead/plan-body-verification.md` §"Adversarial plan-body posture"): verifiers open and confirm every cited path / command and put the burden of proof on the plan. The gate threshold is majority-based for kinds `b`/`c`/`e`, but a single `DISAGREE` blocks on its own for the concrete, safety-critical kinds `a` (path/symbol mismatch) / `d` (rollback order) — and `f` on `P-Req-*` items. A majority also needs ≥2 participating votes, so a lone dissent whose peer returned a non-result does not block on a majority-gated kind (see that contract's §"Adversarial plan-body posture").
+  - **Incremental re-verification scope (clarification re-runs):** when the lead's `okstra incremental-scope` decision is `mode == "incremental"` (procedure in `prompts/launch.template.md` §"Clarification Response Carried In"), workers re-analyze ONLY the stages listed in `reverify_stages` (the downstream closure of the impacted stages). Workers MUST NOT re-open, re-score, or re-judge any stage in `carry_stages` — those stages' prior plan-item verdicts are carried forward verbatim, and a worker never overwrites a carried verdict with its own judgement. When the decision is `mode == "full"` (the default), every stage is re-analyzed as usual.
 {{INCLUDE:_coverage-critic.md}}
 - Non-goals:
   - code-level micro-optimization unless it changes the implementation approach

package/runtime/python/okstra_ctl/implementation_stage.py

@@ -1,8 +1,8 @@
 """Implementation stage run orchestration.
 
-This module owns the lifecycle for one ``implementation`` stage run: recover
-consumer state, select an available Stage Map entry, provision the isolated
-stage worktree, and publish the selected stage into run context.
+This module owns the Stage Run Claim for one ``implementation`` stage run:
+recover consumer state, select an available Stage Map entry, provision the
+isolated stage worktree, and record the started event.
 """
 from __future__ import annotations
 
@@ -18,12 +18,12 @@ from .stage_reconcile import auto_reconcile_best_effort
 
 
 class ImplementationStageError(Exception):
-    """Implementation stage selection or provisioning failed."""
+    """Implementation stage claim or provisioning failed."""
 
 
 @dataclass
-class StageSelection:
-    """Resolved implementation stage and its isolated worktree coordinates."""
+class StageRunClaim:
+    """Claim over one Stage Map stage and its isolated worktree coordinates."""
 
     stage: int
     worktree_path: str
@@ -50,22 +50,20 @@ def _as_implementation_stage_error(exc: Exception) -> ImplementationStageError:
     return ImplementationStageError(str(exc))
 
 
-def select_and_provision_implementation_stage(
+def claim_implementation_stage_run(
     inp: Any,
     ctx_stage_map: list[dict[str, Any]],
     task_group_segment: str,
     task_id_segment: str,
     task_key: str,
     executor_worktree_status: str,
-) -> StageSelection:
-    """Select a ready implementation stage and provision its stage worktree.
+) -> StageRunClaim:
+    """Claim a ready implementation stage for one run.
 
-    The returned selection is path-independent with respect to run artifacts:
+    The returned claim is path-independent with respect to run artifacts:
     callers can compute stage-specific run paths after this function resolves
     the selected stage.
     """
-    del task_key  # The registry uses the split identity fields.
-
     from .consumers import backfill_done_from_carry
     from . import worktree as _worktree
     from . import worktree_registry as _reg
@@ -95,7 +93,7 @@ def select_and_provision_implementation_stage(
 
     if executor_worktree_status.startswith("skipped"):
         head = _git_out(inp.project_root, "rev-parse", "HEAD")
-        return StageSelection(
+        claim = StageRunClaim(
             stage=selected,
             worktree_path="",
             worktree_branch="",
@@ -105,6 +103,8 @@ def select_and_provision_implementation_stage(
             started_head_commit=head,
             concurrent_stages=concurrent_stages,
         )
+        _record_stage_run_claim_started(task_key, plan_run_root, claim)
+        return claim
 
     # The anchor and multi-dep candidate base must come from the task-key
     # worktree HEAD (where stage work accumulates), not from inp.project_root
@@ -166,7 +166,7 @@ def select_and_provision_implementation_stage(
             f"stage worktree provisioning failed: {exc}\n{hint}"
         ) from exc
 
-    return StageSelection(
+    claim = StageRunClaim(
         stage=selected,
         worktree_path=prov.path,
         worktree_branch=prov.branch,
@@ -176,22 +176,40 @@ def select_and_provision_implementation_stage(
         started_head_commit=prov.base_ref,
         concurrent_stages=concurrent_stages,
     )
+    _record_stage_run_claim_started(task_key, plan_run_root, claim)
+    return claim
+
+
+def _record_stage_run_claim_started(
+    task_key: str,
+    plan_run_root: Path,
+    claim: StageRunClaim,
+) -> None:
+    from .consumers import append_consumer
 
+    now = _dt.datetime.now(_dt.timezone.utc).isoformat()
+    append_consumer(
+        plan_run_root,
+        impl_task_key=task_key,
+        stage=claim.stage,
+        status="started",
+        started_at=now,
+        head_commit=claim.started_head_commit,
+    )
 
-def apply_implementation_stage(
+
+def publish_stage_run_claim(
     inp: Any,
     ctx: dict[str, Any],
     ctx_stage_map: list[dict[str, Any]],
-    sel: StageSelection,
+    claim: StageRunClaim,
 ) -> None:
-    """Publish a selected stage into run context and ``consumers.jsonl``."""
-    from .consumers import append_consumer
-
+    """Publish a Stage Run Claim into run context."""
     ctx["parsed_stage_map"] = ctx_stage_map
-    ctx["effective_stages"] = [sel.stage]
-    csv = str(sel.stage)
+    ctx["effective_stages"] = [claim.stage]
+    csv = str(claim.stage)
     ctx["EFFECTIVE_STAGES"] = csv
-    ctx["CONCURRENT_RUN_STAGES"] = ",".join(str(s) for s in sel.concurrent_stages)
+    ctx["CONCURRENT_RUN_STAGES"] = ",".join(str(s) for s in claim.concurrent_stages)
     ctx["STAGE_BATCH_DIRECTIVE"] = (
         f"- **Stage for this implementation run:** `{csv}`. "
         "Execute exactly this Stage Map stage — this is the authoritative scope. "
@@ -201,20 +219,9 @@ def apply_implementation_stage(
     inp.stage = csv
     print(f"selected stages: {csv}", file=sys.stdout)
 
-    if sel.worktree_status and not sel.worktree_status.startswith("skipped"):
-        ctx["EXECUTOR_WORKTREE_PATH"] = sel.worktree_path
-        ctx["EXECUTOR_WORKTREE_BRANCH"] = sel.worktree_branch
-        ctx["EXECUTOR_WORKTREE_BASE_REF"] = sel.worktree_base_ref
-        ctx["EXECUTOR_WORKTREE_STATUS"] = sel.worktree_status
-        ctx["EXECUTOR_WORKTREE_NOTE"] = sel.worktree_note
-
-    now = _dt.datetime.now(_dt.timezone.utc).isoformat()
-    plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
-    append_consumer(
-        plan_run_root,
-        impl_task_key=ctx["TASK_KEY"],
-        stage=sel.stage,
-        status="started",
-        started_at=now,
-        head_commit=sel.started_head_commit,
-    )
+    if claim.worktree_status and not claim.worktree_status.startswith("skipped"):
+        ctx["EXECUTOR_WORKTREE_PATH"] = claim.worktree_path
+        ctx["EXECUTOR_WORKTREE_BRANCH"] = claim.worktree_branch
+        ctx["EXECUTOR_WORKTREE_BASE_REF"] = claim.worktree_base_ref
+        ctx["EXECUTOR_WORKTREE_STATUS"] = claim.worktree_status
+        ctx["EXECUTOR_WORKTREE_NOTE"] = claim.worktree_note

package/runtime/python/okstra_ctl/incremental_carry.py

@@ -0,0 +1,70 @@
+"""Merge carried-forward plan-item verdicts from the prior run into the
+current incremental re-run's data.json. Plan items the current run did not
+re-verify keep their prior verdict, tagged so the report shows they are
+carried forward and unchanged.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+class CarryError(Exception):
+    """Carry merge refused — schema drift or structural mismatch."""
+
+
+def merge_carried_forward(prev: dict, cur: dict, prev_seq: str = "previous") -> dict:
+    if prev.get("schemaVersion") != cur.get("schemaVersion"):
+        raise CarryError(
+            f"schemaVersion drift {prev.get('schemaVersion')!r} != {cur.get('schemaVersion')!r}; "
+            "cannot carry forward — caller must fall back to full"
+        )
+    prev_pbv = prev.get("implementationPlanning", {}).get("planBodyVerification", {})
+    cur_ip = cur.setdefault("implementationPlanning", {})
+    cur_pbv = cur_ip.setdefault("planBodyVerification", {})
+    cur_items = cur_pbv.setdefault("planItems", [])
+    reverified_ids = {i["id"] for i in cur_items}
+    for item in prev_pbv.get("planItems", []):
+        if item["id"] in reverified_ids:
+            continue
+        carried = dict(item)
+        carried["carriedForwardFromSeq"] = str(prev_seq)
+        cur_items.append(carried)
+    cur_items.sort(key=lambda i: i["id"])
+    return cur
+
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(prog="okstra incremental-carry")
+    ap.add_argument("--prev-data", required=True, help="prior run final-report data.json")
+    ap.add_argument("--cur-data", required=True, help="current incremental re-run data.json")
+    ap.add_argument("--prev-seq", required=True, help="prior run seq, tagged onto carried items")
+    ap.add_argument("--out", required=True, help="path to write the merged data.json")
+    args = ap.parse_args(argv)
+
+    prev = json.loads(Path(args.prev_data).read_text(encoding="utf-8"))
+    cur = json.loads(Path(args.cur_data).read_text(encoding="utf-8"))
+    try:
+        merged = merge_carried_forward(prev, cur, prev_seq=args.prev_seq)
+    except CarryError as exc:
+        print(f"carry refused: {exc}", file=sys.stderr)
+        return 1
+
+    Path(args.out).write_text(
+        json.dumps(merged, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+    )
+    carried = sum(
+        1
+        for i in merged.get("implementationPlanning", {})
+        .get("planBodyVerification", {})
+        .get("planItems", [])
+        if i.get("carriedForwardFromSeq") == str(args.prev_seq)
+    )
+    print(f"merged {carried} carried-forward plan item(s) from seq {args.prev_seq} -> {args.out}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/incremental_scope.py

@@ -0,0 +1,89 @@
+"""Decide whether an implementation-planning clarification re-run can be
+incremental, and if so which stages to re-verify vs carry forward.
+
+Deterministic half of the incremental-reverification feature: the lead
+prompt supplies the impacted-stage set (its discretionary C2 judgement) and
+the base SHAs; everything here is pure so the same inputs always yield the
+same decision. See docs/superpowers/specs/2026-07-09-incremental-clarification-reverification-design.md.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from okstra_ctl.stage_targets import downstream_stage_closure
+
+CUTOFF_RATIO = 0.5
+
+
+@dataclass
+class IncrementalDecision:
+    mode: str  # "incremental" | "full"
+    reverify_stages: list[int]
+    carry_stages: list[int]
+    reason: str
+
+
+def _parse_depends_on(cell: str) -> list[int]:
+    text = (cell or "").strip()
+    if not text or text == "(none)":
+        return []
+    return [int(tok.strip()) for tok in text.split(",") if tok.strip()]
+
+
+def parse_stage_graph(data: dict) -> list[tuple[int, list[int]]]:
+    stage_map = data.get("implementationPlanning", {}).get("stageMap", [])
+    return [(int(row["stage"]), _parse_depends_on(row.get("dependsOn", ""))) for row in stage_map]
+
+
+def decide_scope(
+    *,
+    stages: list[tuple[int, list[int]]],
+    impacted_stages: set[int],
+    prev_base_sha: str,
+    cur_base_sha: str,
+    cutoff_ratio: float = CUTOFF_RATIO,
+) -> IncrementalDecision:
+    if not prev_base_sha or prev_base_sha != cur_base_sha:
+        return IncrementalDecision(
+            "full", [], [],
+            f"base-ref changed ({prev_base_sha!r} -> {cur_base_sha!r}); prior analysis invalid",
+        )
+    if not impacted_stages:
+        return IncrementalDecision("full", [], [], "no impacted stages resolved; falling back to full")
+    all_stages = {num for num, _ in stages}
+    closure = downstream_stage_closure(stages, set(impacted_stages))
+    if len(closure) * 2 > len(all_stages):
+        return IncrementalDecision(
+            "full", [], [],
+            f"closure {len(closure)}/{len(all_stages)} exceeds {int(cutoff_ratio * 100)}% cutoff",
+        )
+    reverify = sorted(closure)
+    carry = sorted(all_stages - closure)
+    return IncrementalDecision("incremental", reverify, carry, f"closure {reverify} within cutoff")
+
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(prog="okstra incremental-scope")
+    ap.add_argument("--prev-data", required=True, help="prior run final-report data.json")
+    ap.add_argument("--cur-base-sha", required=True)
+    ap.add_argument("--prev-base-sha", required=True)
+    ap.add_argument("--impacted", default="", help="comma-separated impacted stage numbers")
+    args = ap.parse_args(argv)
+
+    data = json.loads(Path(args.prev_data).read_text(encoding="utf-8"))
+    stages = parse_stage_graph(data)
+    impacted = {int(t.strip()) for t in args.impacted.split(",") if t.strip()}
+    decision = decide_scope(
+        stages=stages, impacted_stages=impacted,
+        prev_base_sha=args.prev_base_sha, cur_base_sha=args.cur_base_sha,
+    )
+    print(json.dumps(asdict(decision), ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))