okstra 0.116.0 → 0.118.0

package/docs/project-structure-overview.md

@@ -1,6 +1,6 @@
 # Okstra — 폴더 구조 및 기능 요약
 
-> 현재 저장소 기준의 living map입니다. 빠른 사용법은 [`README.kr.md`](../README.kr.md), 내부 실행 계약은 [`docs/kr/architecture.md`](kr/architecture.md), CLI 세부 옵션은 [`docs/kr/cli.md`](kr/cli.md)를 함께 보세요.
+> 현재 저장소 기준의 living map입니다. 빠른 사용법은 [`README.md`](../README.md), 내부 실행 계약은 [`docs/architecture.md`](architecture.md), 저장 구조는 [`docs/architecture/storage-model.md`](architecture/storage-model.md), CLI 세부 옵션은 [`docs/cli.md`](cli.md)를 함께 보세요.
 
 ---
 
@@ -54,19 +54,21 @@ okstra/
 │   ├── okstra_vendor/               vendored Jinja2 / MarkupSafe + graphify / networkx (okstra-graphify skill)
 │   ├── lib/okstra/                  Bash helpers for okstra.sh
 │   └── lib/okstra-ctl/              Bash control-center subcommands
-├── skills/                          Claude Code skills (10)
+├── skills/                          Claude Code skills (11)
 ├── agents/                          lead SKILL.md + worker agent specs
 ├── prompts/                         launch template, phase profiles, wizard prompt JSON
 ├── schemas/                         JSON schema for final-report data.json
 ├── templates/                       report, setup, PR, project-doc templates/assets
 ├── validators/                      run / brief / schedule / view validators
 ├── tools/build.mjs                  source → runtime sync
+├── tools/docs_publication/          public-manual publication pipeline (build-time only; not shipped)
+├── config/docs-publication.json     publication inventory: every tracked Markdown path + classification
 ├── runtime/                         generated install payload; do not edit directly
 ├── tests/                           pytest unit suite
 ├── tests-e2e/                       Bash end-to-end scenarios
 ├── docs/                            architecture, CLI, plans/specs
 ├── package.json                     npm metadata and published file list
-├── README.md / README.kr.md         user manuals
+├── README.md                        public user manual
 ├── CHANGES.md / CHANGELOG.md        human-authored and generated changelogs
 └── RELEASING.md                     release process
 ```
@@ -84,9 +86,13 @@ okstra/
 - `bin/`
 - `src/`
 - `runtime/`
-- `docs/`
+- `docs/architecture.md`
+- `docs/architecture/`
+- `docs/cli.md`
+- `docs/container.md`
+- `docs/performance-improvement-plan-v2.md`
+- selected contributor, follow-up, AI, and task-process documentation paths
 - `README.md`
-- `README.kr.md`
 
 So `runtime/` is not the only npm-published content. It is the install payload copied into `~/.okstra`.
 
@@ -142,7 +148,7 @@ Runtime/install asset changes follow this checklist:
 
 `bin/okstra` is a thin dynamic-import router. Every command module exports `run(args) -> Promise<number>` or a named install/uninstall runner.
 
-`src/` is layered: the dispatch table (`src/cli-registry.mjs`) stays at the root, shared infrastructure with no command export lives under `src/lib/`, and command modules are grouped by domain under `src/commands/{lifecycle,execute,inspect,report,memory}/`.
+`src/` is layered: the dispatch table (`src/cli-registry.mjs`) stays at the root, shared infrastructure with no command export lives under `src/lib/`, and command modules are grouped by domain under `src/commands/{lifecycle,execute,inspect,report,memory,pr}/`.
 
 | Command | Module | Role |
 |---|---|---|
@@ -175,6 +181,7 @@ Runtime/install asset changes follow this checklist:
 | `token-usage` | `src/commands/execute/token-usage.mjs` | Wrap installed Python token usage CLI |
 | `spawn-followups`, `error-log` | `src/commands/execute/*.mjs` | Follow-up task bundle creation and run error-log append helpers |
 | `memory` | `src/commands/memory/memory.mjs` | Store/find global conversation memory under `~/.okstra/memory-book` |
+| `pr` | `src/commands/pr/pr.mjs` | `okstra pr <template\|branches\|gen>` — PR body template store under `~/.okstra/template/pr/` (bundled fallback `src/commands/pr/default.md`), base-branch recommendation, and the `gen` JSON bundle (template + `<base>..HEAD` commits + `<base>...HEAD` diffstat) backing the okstra-pr-gen skill. Git-only; no project registration required |
 | `recap` | `src/commands/inspect/recap.mjs` | `okstra recap <assemble\|record>` Node wrapper backing the okstra-inspect `recap` facet |
 | `rollup` | `src/commands/inspect/rollup.mjs` | `okstra rollup` thin shim into `scripts/okstra_ctl/rollup.py` — read-only cross-task roll-up backing the okstra-rollup skill |
 | `container` | `src/commands/inspect/container.mjs` | `bin okstra container` thin shim into `scripts/okstra_ctl/container.py` for the okstra-container-build skill |
@@ -211,6 +218,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 +300,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 |
@@ -306,7 +320,7 @@ Token/cost accounting:
 
 ### 4.10 `skills/`
 
-9 user-facing skills (the only skills `okstra install` copies):
+11 user-facing skills (the only skills `okstra install` copies). The list SSOT is `USER_SKILL_NAMES` in `src/lib/skill-catalog.mjs`; the Claude plugin manifest and the installer both derive from it:
 
 | Skill | User-invocable | Role |
 |---|---:|---|
@@ -317,6 +331,8 @@ Token/cost accounting:
 | `okstra-rollup` | yes | Cross-task roll-up — aggregate runs/time/errors across a task-group (or whole project) and synthesize a digest from the report files |
 | `okstra-schedule` | yes | Generate task-group schedule |
 | `okstra-container-build` | yes | Non-linear deploy tool — deploy a verified task's code as a docker compose group and watch each container (sub-commands `up` / `status` / `logs` / `stop-watcher` / `down`) |
+| `okstra-graphify` | yes | Knowledge graph over the project's own `.okstra/` memory — final reports, `decisions/*.md`, `glossary.md`; scope restricted to `.okstra/`, output under `.okstra/graph/` (sub-commands `build` / `query` / `path` / `explain` / `mcp` / `wiki`) |
+| `okstra-pr-gen` | yes | Register PR body templates under `~/.okstra/template/pr/` and generate a PR description from a branch diff (drives `okstra pr template` / `branches` / `gen`). **Global skill** — needs a Git repo, not `<PROJECT_ROOT>/.okstra/project.json` |
 | `okstra-manager` | yes | Coordinate cross-project okstra tasks through manager-owned plans, assignments, sync snapshots, status, and child launch context packets |
 | `okstra-setup` | yes | Install/check runtime and register project |
 
@@ -481,11 +497,13 @@ Final report artifacts live under `runs/<task-type>/reports/`. Human responses f
 
 When changing code, keep these docs in sync:
 
-- New Node command: update `bin/okstra` usage, `README*`, this file, and `docs/kr/cli.md`.
+- New Node command: update `bin/okstra` usage, `README.md`, this file, and `docs/cli.md`.
 - New runtime source copied to users: update `tools/build.mjs`, install/uninstall manifests if applicable, and this file.
-- New skill/agent: update `README*`, this file, install/uninstall fallback lists, and `CHANGES.md`.
+- New skill/agent: update `README.md`, this file, install/uninstall fallback lists, and `CHANGES.md`.
 - New report field/section: update schema, template, report-writer worker, validator tests, this file's report model if user-visible.
-- New phase/profile behavior: update `prompts/profiles/*`, `docs/kr/architecture.md`, `docs/kr/cli.md`, and `README*` if user-facing.
+- New phase/profile behavior: update `prompts/profiles/*`, `docs/architecture.md`, `docs/cli.md`, and `README.md` if user-facing.
+
+`README.md`, `docs/cli.md`, `docs/architecture.md`, `docs/architecture/storage-model.md`, `docs/container.md`, and `docs/performance-improvement-plan-v2.md` are `translated` outputs in `config/docs-publication.json` — do **not** hand-edit them. Author the Korean source under the maintainer's Git-ignored `.project-docs/ko-source/`, then run the publication pipeline (`python3 -m tools.docs_publication prepare|validate|apply|record`), which keeps the source/output hashes in `.project-docs/doc-publishing/state.json` in step. Files classified `pending` — including this one, `CHANGES.md`, and `CHANGELOG.md` — are edited directly.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.116.0",
+  "version": "0.118.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",
@@ -16,14 +16,18 @@
     "bin/",
     "src/",
     "runtime/",
+    "docs/architecture.md",
+    "docs/architecture/",
+    "docs/cli.md",
+    "docs/container.md",
     "docs/contributor-change-matrix.md",
+    "docs/follow-ups/2026-07-10-final-report-option-3.md",
     "docs/for-ai/",
-    "docs/kr/",
+    "docs/performance-improvement-plan-v2.md",
     "docs/pr-template-usage.md",
     "docs/project-structure-overview.md",
     "docs/task-process/",
-    "README.md",
-    "README.kr.md"
+    "README.md"
   ],
   "engines": {
     "node": ">=18"
@@ -31,9 +35,10 @@
   "scripts": {
     "build": "node tools/build.mjs",
     "prepack": "node tools/build.mjs",
+    "docs:validate": "python3 -m tools.docs_publication validate --repo .",
     "test:js": "node --test tests-js/*.test.mjs",
     "test:py": "python3 -m pytest tests/",
     "test:workflow": "bash validators/validate-workflow.sh",
-    "check": "npm run build && npm run test:js && npm run test:py && npm run test:workflow"
+    "check": "npm run docs:validate && npm run build && npm run test:js && npm run test:py && npm run test:workflow"
   }
 }

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.116.0",
-  "builtAt": "2026-07-09T17:28:22.971Z",
+  "package": "0.118.0",
+  "builtAt": "2026-07-15T06:18:58.589Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/recap.py

@@ -1,6 +1,7 @@
-"""Read-side recap for a task: assemble run-to-run phase transitions and
-append a recap Q&A log. Mutates only <task-root>/recap/recap-log.jsonl;
-never touches task-manifest / catalog / timeline.
+"""Read-side recap for a task: assemble run-to-run phase transitions, append a
+recap Q&A log, and write agent-authored notes. Writes only under
+<task-root>/recap/recap-log.jsonl and <task-root>/notes/; never touches
+task-manifest / catalog / timeline.
 """
 from __future__ import annotations
 
@@ -10,9 +11,12 @@ import json
 import sys
 from pathlib import Path
 
+from okstra_ctl.ids import slugify_task_segment
 from okstra_ctl.run_context import dir_flock
 from okstra_ctl.task_target import resolve_task_root, project_rel
 
+NOTE_KINDS = ("verification-evidence", "decision-draft", "analysis-note")
+
 
 def _load_timeline(task_root: Path) -> list[dict]:
     path = task_root / "history" / "timeline.json"
@@ -91,6 +95,56 @@ def append_recap_entry(task_root, project_root, *, kind, mode, question,
     return {"logPath": project_rel(log_path, project_root), "entry": entry}
 
 
+def _note_path(notes_dir: Path, slug: str, date: str) -> Path:
+    # 같은 날 같은 slug 로 노트를 여러 개 남기면 덮어쓰지 않도록 -2, -3 을 붙인다.
+    base = notes_dir / f"{slug}-{date}.md"
+    if not base.exists():
+        return base
+    seq = 2
+    while (candidate := notes_dir / f"{slug}-{date}-{seq}.md").exists():
+        seq += 1
+    return candidate
+
+
+def _note_frontmatter(*, task_key, kind, created_at, purpose, scope_note) -> str:
+    return (
+        "---\n"
+        f"task-key: {task_key}\n"
+        f"kind: {kind}\n"
+        "author: agent\n"
+        f"created-at: {created_at}\n"
+        f"purpose: {purpose}\n"
+        f"scope-note: {scope_note}\n"
+        "---\n\n"
+    )
+
+
+def write_note(task_root, project_root, *, kind, slug, purpose, scope_note,
+               body, now) -> dict:
+    notes_dir = task_root / "notes"
+    notes_dir.mkdir(parents=True, exist_ok=True)
+    created_at = now.date().isoformat()
+    slug_seg = slugify_task_segment(slug)
+    if not slug_seg:
+        raise ValueError("slug must contain at least one alphanumeric character")
+    path = _note_path(notes_dir, slug_seg, created_at)
+    task_key = _task_key(task_root)
+    frontmatter = _note_frontmatter(
+        task_key=task_key, kind=kind, created_at=created_at,
+        purpose=purpose, scope_note=scope_note)
+    path.write_text(frontmatter + body.rstrip("\n") + "\n", encoding="utf-8")
+    note_rel = project_rel(path, project_root)
+    return {
+        "notePath": note_rel,
+        "taskKey": task_key,
+        "kind": kind,
+        "createdAt": created_at,
+        # 노트는 inert — 다음 run 이 자동으로 읽지 않는다. 이 인자를 그대로
+        # `okstra run ...` 에 붙여야만 instruction-set 에 주입된다.
+        "clarificationResponseArg": f"--clarification-response {note_rel}",
+    }
+
+
 def _add_common(sp) -> None:
     # skill 이 쓰는 `<verb> <target> --project-root <root>` 형태를 받으려면
     # 공통 옵션을 부모가 아닌 각 서브파서에 등록해야 한다.
@@ -115,12 +169,35 @@ def main(argv: list[str] | None = None) -> int:
     p_rec.add_argument("--answer", required=True)
     p_rec.add_argument("--citation", action="append", default=[])
 
+    p_note = sub.add_parser(
+        "note", help="write an agent-authored note into <task-root>/notes/")
+    p_note.add_argument("target", help="task root path or task-key")
+    _add_common(p_note)
+    p_note.add_argument("--kind", choices=NOTE_KINDS, required=True)
+    p_note.add_argument("--slug", required=True,
+                        help="short topic slug for the filename")
+    p_note.add_argument("--purpose", required=True,
+                        help="one line — what it is and which run/decision it feeds")
+    p_note.add_argument("--scope-note", required=True, dest="scope_note",
+                        help="one line — what it is NOT (e.g. not a user decision)")
+    body_src = p_note.add_mutually_exclusive_group(required=True)
+    body_src.add_argument("--body", help="inline markdown body")
+    body_src.add_argument("--body-file", dest="body_file",
+                          help="path to a file holding the markdown body")
+
     args = parser.parse_args(argv)
     task_root, project_root = resolve_task_root(
         args.target, args.project_root, args.cwd)
 
     if args.command == "assemble":
         result = assemble_recap(task_root, project_root)
+    elif args.command == "note":
+        body = (Path(args.body_file).read_text(encoding="utf-8")
+                if args.body_file else args.body)
+        result = write_note(
+            task_root, project_root, kind=args.kind, slug=args.slug,
+            purpose=args.purpose, scope_note=args.scope_note, body=body,
+            now=dt.datetime.now(dt.timezone.utc))
     else:
         result = append_recap_entry(
             task_root, project_root, kind=args.kind, mode=args.mode,

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-inspect/SKILL.md

@@ -18,7 +18,7 @@ Single read-side entry point for okstra runtime inspection plus the one status m
 | `cost` | Estimate file/read context cost for a task bundle. |
 | `errors` | Aggregate okstra-run error logs for a task into a timestamped markdown report; print a summary. |
 | `error-zip` | Collect cross-project okstra error logs into an anonymized zip (report + raw) and summarize clusters. |
-| `recap` | Summarize a task's run-to-run phase transitions, then answer free-form questions over its `.okstra` artifacts. Appends each summary/Q&A to `recap/recap-log.jsonl`. |
+| `recap` | Summarize a task's run-to-run phase transitions, then answer free-form questions over its `.okstra` artifacts. Appends each summary/Q&A to `recap/recap-log.jsonl`, and writes agent-authored notes to `notes/` for feeding into later runs. |
 
 ## Step 0: Preflight (shared)
 
@@ -690,7 +690,7 @@ stdout JSON 을 파싱해 보고:
 
 Trigger phrases: "okstra recap", "recap", "작업 요약", "이 task 요약", "전후 요약", "이 작업 설명해줘", "task 질문".
 
-task-id 하나에 쌓인 `.okstra` 산출물 위에서 (a) 처리 전/후 요약을 내고, (b) 그 작업에 대한 자유 질문에 답한다. 기본은 `.okstra/` 서브트리만 읽는다(artifact 모드). 사용자가 명시적으로 코드 변경까지 봐 달라고 요청할 때만 code 모드로 확장한다. 이 sub-command 는 `recap/recap-log.jsonl` 만 append 하고 `task-manifest.json` / catalog / timeline 은 절대 mutate 하지 않는다.
+task-id 하나에 쌓인 `.okstra` 산출물 위에서 (a) 처리 전/후 요약을 내고, (b) 그 작업에 대한 자유 질문에 답한다. 기본은 `.okstra/` 서브트리만 읽는다(artifact 모드). 사용자가 명시적으로 코드 변경까지 봐 달라고 요청할 때만 code 모드로 확장한다. 이 sub-command 는 `recap/recap-log.jsonl` append 와 `notes/` 노트 작성(recap.5)만 수행하고 `task-manifest.json` / catalog / timeline 은 절대 mutate 하지 않는다.
 
 ### recap.1 — Resolve target
 
@@ -748,6 +748,41 @@ okstra recap record <resolved-target> --project-root <projectRoot> \
 <이후 자유 질문을 받습니다. 코드 변경까지 보려면 "diff 까지 봐줘" 라고 요청하세요.>
 ```
 
+### recap.5 — Agent 저작 노트 (`notes/`)
+
+recap 중에 네가 **okstra task 를 위해** 만든 산출물 — 검증 증거, 설계·decision 초안, 분석 노트 — 이 앞으로의 run 에 근거로 쓰일 수 있고, 그 내용이 **렌더된 report 도 아니고 사용자 결정도 아닐 때**만 `notes/` 에 남긴다.
+
+**소유권으로 라우팅한다.** 지금 쓰려는 것이 아래 어디에 해당하는지 먼저 판별한다:
+
+| 내용 | 레인(경로) | 저작 주체 |
+|---|---|---|
+| final report 본문 | `runs/<type>/reports/*.md` (`*.data.json` 에서 렌더) | okstra 렌더러 — 절대 수기 편집 금지 |
+| clarification 에 대한 사용자 답변 | `runs/<type>/user-responses/*.md` (`created-by: user`) | 사용자만 |
+| 확정된 ADR | `.okstra/decisions/NNNN-*.md` | 승격·관리됨 |
+| **Agent 증거 / 설계 초안 / 분석** | **`.okstra/tasks/<group>/<id>/notes/`** | 너(AI) |
+
+렌더 산출물도, 사용자 결정도 아닌 **너 자신의 근거·초안**이면 `notes/` 로 간다. 노트는 손으로 찍지 말고 CLI 로 쓴다 — 경로·frontmatter·날짜를 코드가 보장하고, 다음 run 에 넘길 인자를 출력해 준다:
+
+```bash
+okstra recap note <resolved-target> --project-root <projectRoot> \
+  --kind <verification-evidence|decision-draft|analysis-note> \
+  --slug <short-topic-slug> \
+  --purpose "<한 줄 — 무엇이며 어느 run/decision 에 투입되는지>" \
+  --scope-note "<한 줄 — 무엇이 아닌지, 예: C-00x 에 대한 사용자 결정이 아님>" \
+  --body-file <노트 본문 마크다운 경로>
+```
+
+본문은 먼저 scratchpad 에 마크다운으로 쓴 뒤 `--body-file` 로 넘긴다(짧으면 `--body "<md>"` 인라인도 가능). CLI 는 `.okstra/tasks/<group>/<id>/notes/<slug>-<YYYY-MM-DD>.md` 를 생성하고 stdout JSON 으로 `notePath` 와 `clarificationResponseArg` 를 돌려준다.
+
+**self-check 규칙 (validator 가 없으니 스스로 지킨다):**
+
+1. **렌더된 report 를 수기 편집하지 않는다** (`runs/*/reports/` 아래 `*.md` / `*.data.json` / `*.html`). `data.json` 에서 재생성되므로 편집은 덮어써지고 SSOT 와 어긋난다. 발견 내용은 `notes/` 에 쓴다.
+2. **`user-responses/` 파일을 작성하거나 `created-by: user` 를 달지 않는다.** 그건 사용자의 결정이며, 대신 쓰면 사용자가 내리지 않은 결정을 위조하는 것이다. 네 증거가 특정 답을 뒷받침하면 `notes/` 에 그렇게 적고 결정은 사용자에게 맡긴다.
+3. **okstra 관리 디렉토리에 쓰지 않는다** (`runs/`, `instruction-set/`, `history/`, `recap/`, `.okstra/decisions/`). `notes/` 만이 agent 소유 레인이다. `recap/recap-log.jsonl` 은 예외적으로 쓰되 손으로 편집하지 말고 `okstra recap record` CLI 로만 남긴다.
+4. **`notes/` 는 okstra 에 inert 하다** — 어떤 run 도 자동으로 읽지 않는다. 작성 후 CLI 가 출력한 `clarificationResponseArg`(예: `--clarification-response <notePath>`)를 사용자에게 그대로 알려, 다음 run 을 그 인자와 함께 실행해야만 반영된다는 것을 전한다.
+
+**Guardrail:** `.okstra/` 는 gitignored 다 — `notes/` 는 로컬 scratch 로 취급하고 절대 `git add` 하지 않는다. 새 노트 생성은 되돌리기 쉬우니(파일 삭제), 생성물이나 사용자 소유 파일을 편집하는 것보다 항상 이쪽을 택한다.
+
 ---
 
 ## Output Rules (shared)

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

@@ -0,0 +1,108 @@
+---
+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", "register PR template", "generate PR body", "generate PR message", "generate PR", "pr gen", and "register template".
+---
+
+# 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. `Generate PR` — generate a PR body from a branch diff.
+2. `Register template` — save a new PR body template.
+3. `Enter manually` — always the last option (okstra picker convention).
+
+## Mode A — Generate 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 `Default template` (the bundled default), plus `Enter manually`
+  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 `Enter manually`
+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 — Register template
+
+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/inspect/recap.mjs

@@ -1,15 +1,20 @@
 import { runPythonModule } from "../../lib/python-helper.mjs";
 
-const USAGE = `okstra recap — assemble a task's run-to-run phase recap, or append a recap log entry
+const USAGE = `okstra recap — assemble a task's run-to-run phase recap, append a recap log entry, or write an agent note
 
 Usage:
   okstra recap assemble <task-root|task-key> [--project-root <dir>] [--cwd <dir>]
   okstra recap record <task-root|task-key> --kind <summary|qa> --mode <artifact|code> \\
     [--question <text>] --answer <text> [--citation <path:line> ...]
+  okstra recap note <task-root|task-key> \\
+    --kind <verification-evidence|decision-draft|analysis-note> --slug <topic> \\
+    --purpose <text> --scope-note <text> (--body <markdown> | --body-file <path>)
 
 \`assemble\` is read-only and prints a JSON summary of phase transitions across runs.
 \`record\` appends one line to <task-root>/recap/recap-log.jsonl; it never mutates
 other task artifacts.
+\`note\` writes an agent-authored markdown note to <task-root>/notes/ and prints its
+path plus the \`--clarification-response\` argument for feeding it into a later run.
 `;
 
 export async function run(args) {

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>