okstra 0.116.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.116.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.116.0",
-  "builtAt": "2026-07-09T17:28:22.971Z",
+  "package": "0.117.0",
+  "builtAt": "2026-07-14T11:54:12.876Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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/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/src/cli-registry.mjs

@@ -329,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/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