okstra 0.115.0 → 0.117.0

package/docs/kr/architecture.md

@@ -541,6 +541,23 @@ scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<t
 
 `$EDITOR`로 최신 final report가 열리고, 저장 후 같은 phase가 자동으로 `--clarification-response` carry-in 으로 재실행됩니다.
 
+#### Incremental re-verification (implementation-planning 재실행 한정)
+
+`implementation-planning` clarification 재실행은 기본이 **full 재검증**입니다. 다만 답변의 파급이 국소적이고 코드가 그대로라면, lead 가 영향 stage 의 하류 폐포만 재검증하고 나머지 stage 의 plan-item verdict 는 직전 run 에서 carry-forward 합니다. 판정은 결정적 CLI 와 lead 재량으로 나뉩니다.
+
+- **C1 (CLI 판정, 결정적)**: 직전 run 의 `state/active-run-context-implementation-planning-<prev-seq>.json` 의 `executorWorktree.baseRef` 와 이번 run 의 base-ref SHA 가 같아야 합니다. 다르면 코드가 바뀐 것이므로 즉시 `full`.
+- **C2 (lead 재량)**: 답변이 건드리는 Stage Map stage 번호 집합. Stage Map 에 없는 번호는 절대 넣지 않고, 매핑에 확신이 없거나 답변이 선택 Option/접근법을 뒤집으면 **빈 집합**을 넘겨 `full` 로 폴백합니다.
+- **폐포 컷오프**: `okstra incremental-scope` 가 `implementationPlanning.stageMap` 의 의존성 그래프에서 영향 stage 의 `downstream_stage_closure` 를 구하고, 그 크기가 전체 stage 의 **과반을 넘으면** `full`. 그 외에는 `{mode, reverify_stages, carry_stages, reason}` JSON 을 출력합니다.
+
+```bash
+okstra incremental-scope --prev-data <prev data.json> --cur-base-sha <sha> --prev-base-sha <sha> --impacted 2,3
+okstra incremental-carry --prev-data <prev data.json> --cur-data <cur data.json> --prev-seq <prev-seq> --out <cur data.json>
+```
+
+`mode == "incremental"` 이면 worker dispatch 는 `reverify_stages` 로만 범위가 좁혀지고(`prompts/profiles/implementation-planning.md` 의 *Cross-verification mode*), 워커는 `carry_stages` 를 재개봉·재판정하지 않습니다. 재실행이 끝나면 `okstra incremental-carry` 가 직전 run 의 plan-item verdict 중 이번 run 에 없는 항목을 `carriedForwardFromSeq` 태그와 함께 병합합니다. 두 run 의 `schemaVersion` 이 다르면 `CarryError` 로 비영 종료하고 full 로 폴백합니다. 재검증 stage 에서 plan item 이 **삭제**돼야 한다는 결론이 나오면 파급이 국소적이지 않다는 신호이므로 역시 full 로 재실행합니다. `verdictCard` / `finalVerdict` 는 절대 carry 되지 않고 매 run 재계산합니다.
+
+판정 결과는 report-writer 가 data.json 의 `implementationPlanning.incrementalDecision` 에 그대로 기록하고, 렌더러가 `### 0.1 Incremental Re-Verification Scope` 감사 블록으로 노출합니다. 절차 원문은 `prompts/launch.template.md` §"Incremental re-verification" 입니다.
+
 ### 6. 필요 시 구현 계획 검토
 
 ```bash
@@ -630,8 +647,10 @@ resume 판단 기준:
 Claude가 작성하는 최종 보고서는 아래 구조를 우선 사용합니다 (brief 의 augmentation 이 더 구체적인 형식을 요구할 때만 그것을 따릅니다).
 
 - `## Verdict Card` — **최상단 의무 섹션**. Final Conclusion / Verdict Token / Direction / Approval Required? / Next Step 5 행. Verdict Token / Direction / Next Step 셀은 본문 §2 (실행 현황) 와 §6 (다음 단계) 의 권위 셀과 byte-match 해야 합니다.
+- (선택) `## Reader Summary` — data.json 의 `readerSummary` 가 있을 때만 Verdict Card 바로 아래 렌더되는 5행 표: 결정(`decision`) / 사람이 해야 할 행동(`humanActionRequired`) / 차단 항목(`blockingItems`) / 건너뛰어도 되는 것(`safeToSkip`) / 추천 명령(`recommendedCommand`). 존재하면 5개 필드 전부 필수이며 (schema `required`), raw evidence table 을 반복하지 않고 요약만 담습니다. 없는 과거 data.json 도 그대로 렌더됩니다.
 - `## 작업 배경과 근거` — **모든 task-type 의무 섹션** (data.json `rationale`). 검토자용 서술로 네 질문에 순서대로 답합니다: 왜 이 작업을 하는가(`motivation`) / 왜 이게 문제인가(`problem`) / 그래서 어떤 작업이 필요한가(`approach`) / 왜 이게 합리적 선택인가(`justification`). 표가 아니라 프로즈이며, 각 필드는 `path:line` · 보고서 ID(`C-001`) · `§5.4` 같은 증거 참조나 명시적 불충분 표시(`근거 불충분`) 중 하나를 반드시 포함해야 합니다 — `validators/validate-run.py` 의 `_validate_rationale_evidence` 가 둘 다 없는 필드를 fail 합니다.
 - (선택) `## 0. Clarification Response Carried In From Previous Run` — 직전 run 에서 응답이 carry-in 된 경우에만 렌더링. 빈 carry-in 일 때는 헤딩 자체를 출력하지 않습니다.
+  - (선택) `### 0.1 Incremental Re-Verification Scope` — data.json 의 `implementationPlanning.incrementalDecision` 이 있을 때만 렌더링. `mode == "incremental"` 이면 `Re-verified stages` / `Carried-forward stages` 두 행이 반드시 포함되며, `validators/validate-run.py` 가 누락을 `contract-violated` 로 차단합니다. carry 된 plan item 은 `carriedForwardFromSeq` 태그로 어느 run 에서 검증됐는지 남깁니다.
 - `## 1. 문제 또는 검증 대상 요약` — §6.1 Consensus / §6.2 Differences 표 각각 `Source items (worker:item)` 컬럼 보존 (cross-worker traceability).
 - `## 2. 에이전트별 실행 현황`
 - `## 3. Cross Verification 결과` — §2.1 Primary Evidence 에 `Source items (worker:item)` + `Source (path:line / log)` 컬럼.
@@ -650,6 +669,8 @@ Claude가 작성하는 최종 보고서는 아래 구조를 우선 사용합니
 Phase 7 step 1.5 가 final-report MD 한 본을 입력으로 self-contained HTML view 를 결정론적으로 자동 생성합니다.
 
 - `reports/final-report-<task-type>-<seq>.html` — 사람 reviewer 용 self-contained HTML. CSS / JS 인라인 임베드 (외부 URL 0), system color 다크모드, sticky header, 인쇄 대응. §1 `C-*` 행의 의사결정 입력 (체크박스 / 셀렉트 / textarea) 을 화면에서 채우고 `Export user response` 버튼으로 사이드카 markdown 을 생성합니다.
+- **Reader Summary dashboard + reader mode**: 최상단에 `readerSummary`(없으면 `verdictCard` fallback) 기반 dashboard 를 렌더하고, `Action` / `Audit` / `Full` 세 reader mode 토글을 제공합니다. 기본은 `Action` — Reader Summary / Verdict Card / Clarification Items / Recommended Next Steps / Follow-up Tasks 만 보이고, Evidence · Cross Verification · Execution Status · Token Usage · Plan Body Verification · Round History 같은 감사용 섹션은 `Audit` / `Full` 에서 펼칩니다.
+- **`C-*` 셀렉트 옵션 순서**: `Expected form` 의 `Recommended:` 답이 항상 **첫 옵션**으로 렌더되고, 이어지는 `Alternatives:` 항목이 `(a)`, `(b)`, ... 순으로 연속 재부여됩니다 (원본 문자 라벨을 그대로 쓰지 않음).
 
 진입점:
 
@@ -711,7 +732,7 @@ Phase 7 step 1.5 가 final-report MD 한 본을 입력으로 self-contained HTML
 phase 산출물의 출고 가능 여부를 강제하는 진입점:
 
 - `validators/validate-workflow.sh` — phase contract 통합 검증.
-- `validators/validate-run.py` — run-level final-report 본문 contract (Verdict Card 존재, `rationale` 4개 필드의 증거-앵커 강제(`_validate_rationale_evidence`), deprecated §6.1/§6.2/§5.5.8/§5.5.9 Open Questions 부재, Plan Body Verification gate × Approval 마커 cross-check, Token Usage sentinel/zero 차단, 워커-결과 audit 사이드카 존재).
+- `validators/validate-run.py` — run-level final-report 본문 contract (Verdict Card 존재, `rationale` 4개 필드의 증거-앵커 강제(`_validate_rationale_evidence`), deprecated §6.1/§6.2/§5.5.8/§5.5.9 Open Questions 부재, Plan Body Verification gate × Approval 마커 cross-check, Token Usage sentinel/zero 차단, 워커-결과 audit 사이드카 존재, 증분 재검증 감사 블록 존재(`_check_incremental_audit_block` — data.json 이 `incrementalDecision.mode == "incremental"` 이면 `### 0.1 Incremental Re-Verification Scope` + `Re-verified stages` / `Carried-forward stages` 행 필수)).
 - `validators/validate-report-views.py` — self-contained HTML view 의 form-control 위치, 외부 URL 부재, stale source digest, Response ID parity(`C-*` ↔ HTML) 검사.
 - `validators/validate-brief.py` — brief schema (front-matter, `Reporter Confirmations` 섹션 존재, root parent-id self 규칙, slug 컨벤션 등) 강제. `bash validators/validate-brief.sh <brief.md>` 가 thin wrapper.
 

package/docs/project-structure-overview.md

@@ -211,6 +211,8 @@ Important modules:
 | `implementation_stage.py` | `implementation` 단일-stage run 오케스트레이션 — Stage Lifecycle Snapshot 읽기 → 가용 Stage Map entry 선택 → 격리 stage worktree provision → 선택 stage 를 run context 로 발행 (`run.py` 에서 추출) |
 | `stage_targets.py` | Stage readiness/verification 정책 SSOT — Stage Lifecycle Snapshot(`consumers.jsonl` ledger + carry sidecar backfill + active registry reservation)으로 어떤 stage 가 실행 가능한지, 어느 commit 에서 분기하는지, final-verification 이 무엇을 검사하는지 결정. `order_stage_closure` 는 wizard 멀티선택 stage 집합의 의존성 closure 를 Kahn 위상정렬해 `chain-stages` 무인 연쇄 순서를 산출 |
 | `stage_reconcile.py` | stage prepare 흐름 공용 best-effort git reconciliation (`git_reconcile.auto_reconcile` 위임; advisory — 실패는 stderr 보고만, dependency gate 가 권위 판정 유지) |
+| `incremental_scope.py` | `implementation-planning` clarification 재실행의 증분 재검증 판정 (결정적 순수 함수) — 직전 run data.json 의 `implementationPlanning.stageMap` 에서 의존성 그래프를 읽고, base-ref SHA 불변 + 영향 stage 의 `downstream_stage_closure` 가 전체 stage 의 과반 이하일 때만 `mode="incremental"` 을 반환. CLI: `okstra incremental-scope` |
+| `incremental_carry.py` | 증분 재실행의 carry 병합 — 직전 run 의 plan-item verdict 중 이번 run 이 재검증하지 않은 항목을 `carriedForwardFromSeq` 태그와 함께 현재 data.json 에 병합. `schemaVersion` drift 시 `CarryError` 로 비영 종료해 full 폴백을 유도. CLI: `okstra incremental-carry` |
 | `run_context.py` | Per-task mutex, run context and run-input persistence; `consumers_mutex` helper for atomic `consumers.jsonl` writes |
 | `path_hints.py` | Compact path-hint persistence + legacy context hydration — `run-context` / `active-run-context` 를 schemaVersion `2.0` 의 `identity` + `pathHints` compact schema 로 저장하고, host-side reader 가 읽는 순간 기존 flat path key(`RUN_MANIFEST_RELATIVE_PATH`, `TEAM_STATE_PATH` 등)를 메모리에서 hydrate |
 | `consumers.py` | Append-only `consumers.jsonl` writer + reader — records which `implementation` runs consumed which `implementation-planning` stage |
@@ -291,6 +293,11 @@ Token/cost accounting:
 
 `schemas/final-report-v1.0.schema.json` is the final-report data.json contract. The report-writer worker writes `final-report-<task-type>-<seq>.data.json`; the renderer produces Markdown from that JSON.
 
+Optional (v1.0 하위호환) 최상위 키:
+
+- `readerSummary` — 사람이 먼저 읽는 요약 블록. 존재하면 5개 필드(`decision`, `humanActionRequired`, `blockingItems`, `safeToSkip`, `recommendedCommand`)가 모두 필수. 없는 기존 data.json 도 그대로 렌더됩니다(HTML dashboard 는 `verdictCard` 로 폴백).
+- `implementationPlanning.incrementalDecision` — 증분 재검증 판정 (`mode`, `reverifyStages`, `carryStages`, `reason`). `mode == "incremental"` 이면 렌더러가 `### 0.1 Incremental Re-Verification Scope` 감사 블록을 emit 하고 `validators/validate-run.py` 가 그 부재를 차단합니다.
+
 ### 4.9 `validators/`
 
 | File | Role |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.115.0",
+  "version": "0.117.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.115.0",
-  "builtAt": "2026-07-09T15:25:58.950Z",
+  "package": "0.117.0",
+  "builtAt": "2026-07-14T11:54:12.876Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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/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/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:]))

package/runtime/python/okstra_ctl/report_views.py

@@ -599,6 +599,10 @@ _ALTERNATIVES_CUE = "Alternatives:"
 _PICK_ONE_ANNOTATION = re.compile(r"\s*\([^()]*택\s*\d+\s*\)\s*$")
 
 
+def _lettered_option(letter: str, text: str) -> str:
+    return f"({letter}) {text}"
+
+
 def _parse_expected_form_options(expected_form: str) -> list[tuple[str, str]]:
     """Parse the ``Expected form`` contract format
     (``Recommended: <answer> — <rationale>; Alternatives: <options>``,
@@ -620,17 +624,24 @@ def _parse_expected_form_options(expected_form: str) -> list[tuple[str, str]]:
     # The rationale follows " — "; the option keeps only the answer part.
     answer = rec_body.split(" — ", 1)[0].strip(" .,;—-")
     options: list[tuple[str, str]] = []
+    next_letter_idx = 0
     if answer:
-        options.append(("recommended", f"추천: {answer}"))
+        letter = _ENUM_LETTERS[next_letter_idx]
+        options.append(("recommended", _lettered_option(letter, answer)))
+        next_letter_idx += 1
     enum_alts = _parse_enum_options(alt_body)
     if enum_alts:
-        options.extend(
-            (letter, f"({letter}) {text}") for letter, text in enum_alts
-        )
+        for _original_letter, text in enum_alts:
+            if next_letter_idx >= len(_ENUM_LETTERS):
+                break
+            letter = _ENUM_LETTERS[next_letter_idx]
+            options.append((letter, _lettered_option(letter, text)))
+            next_letter_idx += 1
     else:
         alt_text = alt_body.strip(" .,;—-")
-        if alt_text:
-            options.append(("alternative", alt_text))
+        if alt_text and next_letter_idx < len(_ENUM_LETTERS):
+            letter = _ENUM_LETTERS[next_letter_idx]
+            options.append((letter, _lettered_option(letter, alt_text)))
     return options
 
 
@@ -651,15 +662,19 @@ def _match_option_value(
     cv = (current_value or "").strip()
     if not cv:
         return None
+    normalized_current = _OPTION_LABEL_PREFIX.sub("", cv).strip()
     bodies = [
         (value, _OPTION_LABEL_PREFIX.sub("", label).strip())
         for value, label in opts
     ]
     for value, body in bodies:
-        if body and (cv == body or cv == value):
+        if body and (normalized_current == body or cv == body or cv == value):
             return value
     for value, body in bodies:
-        if len(body) >= _MIN_OPTION_PREFIX_LEN and cv.startswith(body):
+        if (
+            len(body) >= _MIN_OPTION_PREFIX_LEN
+            and (normalized_current.startswith(body) or cv.startswith(body))
+        ):
             return value
     return None
 

package/runtime/python/okstra_ctl/stage_targets.py

@@ -306,6 +306,32 @@ def order_stage_closure(
     return out
 
 
+def downstream_stage_closure(
+    stages: list[tuple[int, list[int]]],
+    seed: set[int],
+) -> set[int]:
+    """Stages that (transitively) depend on any stage in ``seed``, plus ``seed``.
+
+    ``stages`` mirrors ``order_stage_closure``: ``(stage_number, [depends_on_numbers])``.
+    ``order_stage_closure`` walks dependencies (upstream); this walks dependents
+    (downstream) — the reverse edge — so an answered clarification that changes a
+    seed stage re-verifies everything built on top of it.
+    """
+    dependents: dict[int, list[int]] = {}
+    for num, deps in stages:
+        for dep in deps:
+            dependents.setdefault(dep, []).append(num)
+    result = set(seed)
+    queue = list(seed)
+    while queue:
+        cur = queue.pop()
+        for child in dependents.get(cur, []):
+            if child not in result:
+                result.add(child)
+                queue.append(child)
+    return result
+
+
 def commit_is_ancestor(project_root: Path, ancestor: str, descendant: str) -> bool:
     """True iff ``ancestor`` is an ancestor of ``descendant`` in git history."""
     from .worktree import is_ancestor

package/runtime/schemas/final-report-v1.0.schema.json

@@ -445,6 +445,24 @@
         "skippedAdrCandidates": {
           "type": "array",
           "items": { "$ref": "#/$defs/SkippedAdrCandidate" }
+        },
+        "incrementalDecision": {
+          "type": "object",
+          "description": "Verbatim `okstra incremental-scope` output for a clarification re-run. Present only when this implementation-planning run scoped itself against a prior run; drives the Section 0 incremental audit block.",
+          "required": ["mode", "reverifyStages", "carryStages", "reason"],
+          "additionalProperties": false,
+          "properties": {
+            "mode": { "type": "string", "enum": ["incremental", "full"] },
+            "reverifyStages": {
+              "type": "array",
+              "items": { "type": "integer" }
+            },
+            "carryStages": {
+              "type": "array",
+              "items": { "type": "integer" }
+            },
+            "reason": { "type": "string", "minLength": 1 }
+          }
         }
       }
     },
@@ -1500,6 +1518,7 @@
               "id": { "type": "string", "minLength": 1 },
               "subject": { "type": "string", "minLength": 1 },
               "sourceSection": { "type": "string" },
+              "carriedForwardFromSeq": { "type": "string" },
               "clarificationId": {
                 "anyOf": [
                   { "type": "null" },

package/runtime/skills/okstra-pr-gen/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: okstra-pr-gen
+description: Use when the user wants to register a PR body template or generate a PR description from a branch diff using a stored (or default) template. Manages templates under ~/.okstra/template/pr and drives okstra pr {template,branches,gen}. Trigger words include "okstra pr", "PR 템플릿 등록", "PR 본문 생성", "PR 메시지 만들어", "generate PR", "pr gen", "템플릿 등록".
+---
+
+# okstra-pr-gen
+
+Register PR body templates and generate PR descriptions. Templates live in the
+user home at `~/.okstra/template/pr/`. This skill is **global** — it does not
+require `<PROJECT_ROOT>/.okstra/project.json`. PR generation additionally
+requires the current directory to be a git repository.
+
+## Step 0: Check CLI availability
+
+Run as a separate Bash tool call with a literal leading token:
+
+```bash
+okstra pr --help
+```
+
+If `okstra` is not on PATH, tell the user:
+
+`okstra not installed — run npx okstra@latest install once, then retry this skill.`
+
+**Bash invocation rule:** every Bash command begins with the literal token
+`okstra` and passes literal argument values. Do not introduce shell variables,
+`$(...)`, leading `VAR=`, or wrap in `if`/`eval`/`||`/`&&` — that defeats the
+`Bash(okstra:*)` permission match. Paste literal values emitted by a prior call.
+
+## Step 1: Pick the mode (always first)
+
+Present a 3-option picker (`AskUserQuestion`):
+
+1. `PR 생성` — generate a PR body from a branch diff.
+2. `템플릿 등록` — save a new PR body template.
+3. `직접 입력` — always the last option (okstra picker convention).
+
+## Mode A — PR 생성
+
+### A1. Pick a template
+
+```bash
+okstra pr template list --json
+```
+
+- If `templates` is non-empty, present a picker: 1–2 recommended templates from
+  the list, plus `기본 템플릿`(the bundled default), plus `직접 입력` last.
+- If empty, tell the user the bundled default template will be used.
+
+Carry the chosen template name as `<template>` (`default` for the bundled one).
+
+### A2. Pick the base branch
+
+```bash
+okstra pr branches --json
+```
+
+Present a 3-option base picker from `recommended` (top entries) plus `직접 입력`
+last. Carry the choice as `<base>`.
+
+### A3. Build the generation bundle and fill the template
+
+```bash
+okstra pr gen --base <base> --template <template> --json
+```
+
+Parse `{base, currentBranch, templateName, template, commits, diffStat}`. Then
+read the full diff honestly — it is the source of truth:
+
+```bash
+git diff <base>...HEAD
+```
+
+For a large diff, read it in sections. Fill the `template` placeholders from the
+diff and commits: describe only what actually changed. Mark checklist boxes
+`[x]` only when the diff supports them (tests touched → tests box, docs touched →
+docs box). If `commits`/`diffStat` are empty, tell the user there is nothing to
+describe and stop. **Never** append AI trailers/footers.
+
+### A4. Output and offer to create the PR
+
+Print the filled PR body to chat as a single fenced markdown block. Then ask the
+user whether to open a real PR. Only on an explicit yes:
+
+```bash
+gh pr create --base <base> --title "<title>" --body-file <path-to-body>
+```
+
+Write the body to a temp file first and pass `--body-file`. If `gh` is missing
+or not authenticated (`gh auth status` fails), leave the text in chat and tell
+the user to create the PR manually. Do not push or create the PR without the
+user's explicit confirmation.
+
+## Mode B — 템플릿 등록
+
+1. Ask for a template name (`AskUserQuestion`, free text). It must match
+   `^[A-Za-z0-9._-]+$`; re-ask on invalid input.
+2. Ask for the template body — either pasted text or an absolute file path.
+3. Save it:
+
+   ```bash
+   okstra pr template add --name <name> --file <abs-path>
+   ```
+
+   or, for pasted text, `--content "<body>"`. Add `--yes` only if the user
+   confirmed overwriting an existing template of the same name. Report the
+   saved path (`saved: ...`) back to the user.

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

@@ -43,6 +43,19 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 {{ t("sectionIntro.clarificationCarryIn") }}
 
 - Source file: `{{ clarificationCarryIn.sourceFile }}`
+{% if implementationPlanning and implementationPlanning.incrementalDecision %}
+{% set incrementalDecision = implementationPlanning.incrementalDecision %}
+### 0.1 Incremental Re-Verification Scope
+
+- Decision mode: `{{ incrementalDecision.mode }}`
+- Reason: {{ incrementalDecision.reason }}
+{% if incrementalDecision.mode == 'incremental' %}
+- Re-verified stages: {% for s in incrementalDecision.reverifyStages %}`stage-{{ s }}`{% if not loop.last %}, {% endif %}{% else %}(none){% endfor +%}
+- Carried-forward stages: {% for s in incrementalDecision.carryStages %}`stage-{{ s }}` carried-forward (unchanged){% if not loop.last %}, {% endif %}{% else %}(none){% endfor +%}
+
+Carried-forward plan items retain their prior verdicts verbatim; each such item carries a `carriedForwardFromSeq` tag pointing at the run it was verified in.
+{% endif %}
+{% endif %}
 
 {% endif %}
 ## Summary of the Problem or Verification Target

package/runtime/validators/validate-run.py

@@ -744,6 +744,14 @@ _EMPTY_CARRY_IN_SOURCE_RE = re.compile(
     re.MULTILINE,
 )
 
+# Section 0 incremental audit sub-block. When the data.json records an
+# `implementationPlanning.incrementalDecision` with `mode == "incremental"`,
+# the rendered report MUST expose the decision so a reader can audit which
+# stages were re-verified vs carried forward unchanged.
+_INCREMENTAL_AUDIT_HEADING_RE = re.compile(
+    r"^###[ \t]+0\.1[ \t]+Incremental Re-Verification Scope\b", re.MULTILINE
+)
+
 # Deprecated section headings removed by the report-format readability
 # pass. Each entry is (regex, human-readable remedy). The regexes are
 # line-anchored to avoid false positives from inline references in prose
@@ -971,6 +979,44 @@ def _validate_conformance(report_path: Path, failures: list[str],
             )
 
 
+def _check_incremental_audit_block(
+    report_path: Path, content: str, failures: list[str]
+) -> None:
+    """Enforce the Section 0 incremental audit block.
+
+    When the data.json records an `implementationPlanning.incrementalDecision`
+    with `mode == "incremental"`, the rendered markdown MUST carry the
+    `### 0.1 Incremental Re-Verification Scope` block naming the re-verified
+    and carried-forward stages — otherwise the narrowed re-run is silently
+    un-auditable. Non-incremental (`full`) runs and reports without the
+    decision are exempt, so this never conflicts with the empty-Section-0
+    stub rule (that fires only when NO carry-in was provided at all).
+    """
+    data = _load_final_report_data(report_path)
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        return
+    decision = planning.get("incrementalDecision")
+    if not isinstance(decision, dict) or decision.get("mode") != "incremental":
+        return
+    if _INCREMENTAL_AUDIT_HEADING_RE.search(content) is None:
+        failures.append(
+            "final report data.json records an `incremental`-mode "
+            "implementationPlanning.incrementalDecision, but the markdown is "
+            "missing the `### 0.1 Incremental Re-Verification Scope` audit "
+            "block under Section 0. Re-render from the data.json so the "
+            "re-verified / carried-forward stages are visible."
+        )
+        return
+    for needle in ("Re-verified stages", "Carried-forward stages"):
+        if needle not in content:
+            failures.append(
+                f"final report's Section 0 incremental audit block is missing "
+                f"the `{needle}` line — an `incremental`-mode run must list "
+                "both the re-verified and the carried-forward stages."
+            )
+
+
 def validate_report(
     report_path: Path,
     required_agent_status_entries: list[str],
@@ -1064,6 +1110,10 @@ def validate_report(
             "and body — do NOT emit a placeholder stub."
         )
 
+    # Incremental audit block — an `incremental`-mode re-run must expose its
+    # scope decision in Section 0 so the narrowed re-verification is auditable.
+    _check_incremental_audit_block(report_path, content, failures)
+
     # Deprecated section headings — pre-1.0 hard removal.
     for pattern, remedy in _DEPRECATED_FINAL_REPORT_PATTERNS:
         if pattern.search(content) is not None:

package/src/cli-registry.mjs

@@ -305,6 +305,20 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Append run error events to the run error log"],
   },
+  {
+    name: "incremental-scope",
+    module: "./commands/execute/incremental-scope.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Decide re-verify vs carry-forward scope for a clarification re-run"],
+  },
+  {
+    name: "incremental-carry",
+    module: "./commands/execute/incremental-carry.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Merge carried-forward plan-item verdicts into an incremental re-run"],
+  },
   {
     name: "memory",
     module: "./commands/memory/memory.mjs",
@@ -315,6 +329,16 @@ export const COMMAND_REGISTRY = [
       "~/.okstra/memory-book.",
     ],
   },
+  {
+    name: "pr",
+    module: "./commands/pr/pr.mjs",
+    export: "run",
+    category: "introspection",
+    summary: [
+      "Manage PR body templates and prepare PR generation",
+      "bundles under ~/.okstra/template/pr.",
+    ],
+  },
 ];
 
 export const COMMANDS = new Map(

package/src/commands/execute/incremental-carry.mjs

@@ -0,0 +1,20 @@
+import { runInstalledScript } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra incremental-carry — merge carried-forward plan-item verdicts into an incremental re-run's data.json
+
+Wraps the python helper (\`okstra-incremental-carry.py\`) installed under
+\`~/.okstra/bin/\` so the report-writer worker calls \`okstra incremental-carry\`
+instead of emitting a \`python3 "$HOME/..."\` invocation (which breaks
+\`Bash(okstra:*)\` permission matching and prompts on every call).
+
+Usage:
+  okstra incremental-carry --prev-data <path> --cur-data <path> \\
+    --prev-seq <str> [--carry-stages <csv>] --out <path>
+
+Writes the merged data.json to --out. Exits non-zero on schema drift
+(\`CarryError\`) so the caller's shell can fall back to a full re-run.
+`;
+
+export async function run(args) {
+  return runInstalledScript({ scriptName: "okstra-incremental-carry.py", args, usage: USAGE });
+}

package/src/commands/execute/incremental-scope.mjs

@@ -0,0 +1,20 @@
+import { runInstalledScript } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra incremental-scope — decide the re-verify vs carry-forward scope for a clarification re-run
+
+Wraps the python helper (\`okstra-incremental-scope.py\`) installed under
+\`~/.okstra/bin/\` so the lead prompt calls \`okstra incremental-scope\`
+instead of emitting a \`python3 "$HOME/..."\` invocation (which breaks
+\`Bash(okstra:*)\` permission matching and prompts on every call).
+
+Usage:
+  okstra incremental-scope --prev-data <path> --cur-base-sha <sha> \\
+    --prev-base-sha <sha> [--impacted <csv>] [--option <name>]
+
+Prints a JSON decision {mode, reverify_stages, carry_stages, reason} to stdout.
+All arguments are forwarded verbatim to the python helper.
+`;
+
+export async function run(args) {
+  return runInstalledScript({ scriptName: "okstra-incremental-scope.py", args, usage: USAGE });
+}

package/src/commands/pr/default.md

@@ -0,0 +1,21 @@
+## **Please check if the PR fulfills these requirements**
+- [ ] Commits have a single intent
+- [ ] Tests for the changes have been added (for bug fixes / features)
+- [ ] I reviewed my own code
+- [ ] I tested the changes (if not, explain why in the "Other information" section)
+- [ ] Docs have been added / updated
+
+## **What kind of change does this PR introduce?** (Bug fix, feature, docs update, ...)
+<pr-kind>
+
+## **What is the current behavior?** (You can also link to an open issue here)
+<current-behavior>
+
+## **What is the new behavior (if this is a feature change)?**
+<new-behavior>
+
+## **Does this PR introduce a breaking change?** (What changes might users need to make in their application due to this PR?)
+<breaking-change>
+
+## **Other information**:
+<other-information>

package/src/commands/pr/pr.mjs

@@ -0,0 +1,261 @@
+import { promises as fs } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { resolveOkstraHome } from "../../lib/paths.mjs";
+
+const NAME_RE = /^[A-Za-z0-9._-]+$/;
+const DEFAULT_TEMPLATE_PATH = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "default.md",
+);
+
+const USAGE = `okstra pr — PR body templates and PR generation
+
+Usage:
+  okstra pr template list [--json]
+  okstra pr template show <name|default> [--json]
+  okstra pr template add --name <name> (--content <text> | --file <path>) [--yes]
+  okstra pr template path
+  okstra pr branches [--json]
+  okstra pr gen --base <ref> [--template <name|default>] [--json]
+`;
+
+export function isValidTemplateName(name) {
+  return (
+    typeof name === "string" &&
+    NAME_RE.test(name) &&
+    name !== "." &&
+    name !== ".."
+  );
+}
+
+export function templateDir(home) {
+  return join(home, "template", "pr");
+}
+
+export async function listTemplates(home) {
+  let entries;
+  try {
+    entries = await fs.readdir(templateDir(home));
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+  return entries
+    .filter((f) => f.endsWith(".md"))
+    .map((f) => f.slice(0, -3))
+    .sort();
+}
+
+async function readBundledDefault() {
+  return fs.readFile(DEFAULT_TEMPLATE_PATH, "utf8");
+}
+
+export async function readTemplate(home, name) {
+  if (!name || name === "default") return readBundledDefault();
+  if (!isValidTemplateName(name)) throw new Error(`invalid template name: ${name}`);
+  try {
+    return await fs.readFile(join(templateDir(home), `${name}.md`), "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return readBundledDefault();
+    throw err;
+  }
+}
+
+export async function addTemplate(home, name, content, opts = {}) {
+  if (!isValidTemplateName(name)) throw new Error(`invalid template name: ${name}`);
+  const dir = templateDir(home);
+  await fs.mkdir(dir, { recursive: true });
+  const target = join(dir, `${name}.md`);
+  if (!opts.force) {
+    try {
+      await fs.access(target);
+      throw new Error(`template exists: ${name} (use --yes to overwrite)`);
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+  }
+  await fs.writeFile(target, content, "utf8");
+  return target;
+}
+
+function takeValue(args, i, flag) {
+  const v = args[i + 1];
+  if (!v || v.startsWith("--")) throw new Error(`${flag} requires a value`);
+  return v;
+}
+
+async function readAddContent(opts) {
+  if (opts.content !== null) return opts.content;
+  if (opts.file !== null) return fs.readFile(resolve(opts.file), "utf8");
+  throw new Error("template add requires --content or --file");
+}
+
+async function confirm(question) {
+  const rl = createInterface({ input, output });
+  try {
+    const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+async function cmdTemplate(args, home) {
+  const sub = args[0];
+  const rest = args.slice(1);
+  const json = rest.includes("--json");
+  if (sub === "list") {
+    const names = await listTemplates(home);
+    if (json) output.write(JSON.stringify({ templates: names }) + "\n");
+    else output.write(names.length ? names.join("\n") + "\n" : "(no templates)\n");
+    return 0;
+  }
+  if (sub === "show") {
+    const name = rest.find((a) => !a.startsWith("--"));
+    if (!name) throw new Error("template show requires a name");
+    const body = await readTemplate(home, name);
+    output.write(json ? JSON.stringify({ name, body }) + "\n" : body);
+    return 0;
+  }
+  if (sub === "path") {
+    output.write(templateDir(home) + "\n");
+    return 0;
+  }
+  if (sub === "add") {
+    const opts = { name: null, content: null, file: null, yes: false };
+    for (let i = 0; i < rest.length; i++) {
+      const flag = rest[i];
+      if (flag === "--name") opts.name = takeValue(rest, i++, flag);
+      else if (flag === "--content") opts.content = takeValue(rest, i++, flag);
+      else if (flag === "--file") opts.file = takeValue(rest, i++, flag);
+      else if (flag === "--yes") opts.yes = true;
+      else throw new Error(`unknown flag ${flag}`);
+    }
+    if (!opts.name) throw new Error("template add requires --name");
+    const content = await readAddContent(opts);
+    const dir = templateDir(home);
+    const target = join(dir, `${opts.name}.md`);
+    let force = opts.yes;
+    if (!force && isValidTemplateName(opts.name)) {
+      let exists = false;
+      try {
+        await fs.access(target);
+        exists = true;
+      } catch (err) {
+        if (err.code !== "ENOENT") throw err;
+      }
+      if (exists) {
+        if (!process.stdin.isTTY) {
+          throw new Error(`template exists: ${opts.name} (use --yes to overwrite)`);
+        }
+        force = await confirm(`Overwrite existing template ${opts.name}?`);
+        if (!force) { output.write("aborted\n"); return 1; }
+      }
+    }
+    const saved = await addTemplate(home, opts.name, content, { force: true });
+    output.write(`saved: ${saved}\n`);
+    return 0;
+  }
+  throw new Error(`unknown template subcommand: ${sub ?? "(none)"}`);
+}
+
+function tryGit(cwd, args) {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function recommendBranches(cwd) {
+  const currentBranch = tryGit(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  if (currentBranch === null) return { currentBranch: null, recommended: [] };
+  const ordered = [];
+  const remoteDefault = tryGit(cwd, ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
+  if (remoteDefault) {
+    const bare = remoteDefault.replace(/^origin\//, "");
+    if (tryGit(cwd, ["rev-parse", "--verify", "--quiet", `${bare}^{commit}`]) !== null) ordered.push(bare);
+    else if (tryGit(cwd, ["rev-parse", "--verify", "--quiet", `${remoteDefault}^{commit}`]) !== null) ordered.push(remoteDefault);
+  }
+  for (const b of ["main", "master", "develop"]) {
+    const local = tryGit(cwd, ["show-ref", "--verify", "--quiet", `refs/heads/${b}`]);
+    if (local !== null) ordered.push(b);
+  }
+  const recent = tryGit(cwd, [
+    "for-each-ref", "--sort=-committerdate", "--format=%(refname:short)", "refs/heads",
+  ]);
+  if (recent) ordered.push(...recent.split("\n").filter(Boolean));
+  const recommended = [];
+  for (const b of ordered) {
+    if (b && b !== currentBranch && !recommended.includes(b)) recommended.push(b);
+  }
+  return { currentBranch, recommended };
+}
+
+function cmdBranches(args, cwd) {
+  const json = args.includes("--json");
+  const r = recommendBranches(cwd);
+  if (json) output.write(JSON.stringify(r) + "\n");
+  else output.write((r.recommended.join("\n") || "(no branches)") + "\n");
+  return 0;
+}
+
+export async function buildGenBundle({ cwd, home, base, templateName }) {
+  if (!base) throw new Error("gen requires --base");
+  const verified = tryGit(cwd, ["rev-parse", "--verify", "--quiet", `${base}^{commit}`]);
+  if (verified === null) throw new Error(`base ref not found: ${base}`);
+  const currentBranch = tryGit(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const logRaw = tryGit(cwd, [
+    "log", "--reverse", "--format=%h%x09%s", `${base}..HEAD`,
+  ]) || "";
+  const commits = logRaw
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      const tab = line.indexOf("\t");
+      return { hash: line.slice(0, tab), subject: line.slice(tab + 1) };
+    });
+  const diffStat = tryGit(cwd, ["diff", "--stat", `${base}...HEAD`]) || "";
+  const template = await readTemplate(home, templateName);
+  const resolvedName = templateName && templateName !== "default"
+    ? templateName
+    : "default";
+  return { base, currentBranch, templateName: resolvedName, template, commits, diffStat };
+}
+
+async function cmdGen(args, cwd, home) {
+  const opts = { base: null, template: "default" };
+  for (let i = 0; i < args.length; i++) {
+    const flag = args[i];
+    if (flag === "--base") opts.base = takeValue(args, i++, flag);
+    else if (flag === "--template") opts.template = takeValue(args, i++, flag);
+    else if (flag === "--json") continue;
+    else throw new Error(`unknown flag ${flag}`);
+  }
+  const bundle = await buildGenBundle({ cwd, home, base: opts.base, templateName: opts.template });
+  output.write(JSON.stringify(bundle) + "\n");
+  return 0;
+}
+
+export async function run(args) {
+  if (args.length === 0 || args.includes("--help")) {
+    output.write(USAGE);
+    return 0;
+  }
+  const home = resolveOkstraHome();
+  const sub = args[0];
+  const rest = args.slice(1);
+  try {
+    if (sub === "template") return await cmdTemplate(rest, home);
+    if (sub === "branches") return cmdBranches(rest, process.cwd());
+    if (sub === "gen") return await cmdGen(rest, process.cwd(), home);
+    throw new Error(`unknown pr subcommand: ${sub}`);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n`);
+    return 1;
+  }
+}

package/src/lib/skill-catalog.mjs

@@ -15,6 +15,7 @@ export const USER_SKILL_NAMES = Object.freeze([
   "okstra-schedule",
   "okstra-container-build",
   "okstra-graphify",
+  "okstra-pr-gen",
 ]);
 
 // Names okstra used to install as skills before they were renamed or moved