okstra 0.123.0 → 0.125.0

package/README.md

@@ -211,6 +211,7 @@ Major workflow changes added to `main` after 0.8.0:
 - **Profile worker-roster validation** — `--workers <csv>` and the okstra-run Step 6 worker prompt accept only the worker IDs declared in the selected profile's `Required workers:` block. Requesting a worker absent from the profile—for example, `codex` or `antigravity` for `release-handoff`—fails with a clear error, and the interactive prompt shows only workers accepted by that profile.
 - **Experimental Codex lead adapter** — `okstra codex-run <render-bundle args...>` prepares a `leadRuntime=codex` task bundle without launching Claude Code. `okstra codex-dispatch --project-root <dir> --run-manifest <path>` then executes the supported Codex-side roster subset: Codex and Antigravity CLI workers by default, with a Codex report writer available through `--enable-codex-report-writer --report-writer-codex-model <model>`. A successful Codex report-writer dispatch performs token/cost substitution, HTML view rendering, follow-up stub generation, and run validation in order. It shares the Claude lead path's manifest and schema and does not clone the project into a Codex-specific fork.
 - **Multi-stage `implementation-planning` / `implementation`** — `implementation-planning` always produces a Stage Map and N stage sections. Each stage has no more than six steps, and stages with `depends-on (none)` can be implemented concurrently in separate `implementation` runs. Each `implementation` invocation runs a single stage, selected with `--stage <auto|N>`, and creates an evidence sidecar at `carry/stage-<N>.json` for automatic carry-in to the next stage. The `implementation-planning` run directory accumulates `consumers.jsonl` reverse links that record which run consumed each stage.
+- **AI-prepared design preparation (implementation-planning → implementation)** — `implementation-planning` detects which stages need design input (domain contract, DB/table schema, external interface, transaction/consistency, transformation mapping, lifecycle, rollout/observability, manual user test) and has the AI draft a concrete proposal first, instead of handing the user an empty design document. Each item is assessed as `ready`, `provisional`, `blocked`, or `not-applicable`; a simple task may declare `no-design-inputs`. Phase 7 materializes an Okstra-owned request under `design-prep-requests/`, and `okstra design-prep <list|show|write>` or the okstra-run wizard records the confirmed answer as an **append-only** revision under `design-prep-inputs/`—neither path ever edits the approved planning snapshot. Before creating its worktree, `implementation` resolves only the items its selected stage cites in `stageRefs`: safe `provisional` assumptions are injected into the executor prompt so work proceeds, while an unsafe open decision makes only that stage wait or replan. A markerless legacy plan continues with a `legacy-unassessed` warning. Storage authorities: [`docs/architecture/storage-model.md`](docs/architecture/storage-model.md). CLI: [`docs/cli.md#okstra-design-prep`](docs/cli.md#okstra-design-prep).
 - **Phase 6 plan-body verification (implementation-planning only)** — Immediately after the report-writer worker drafts the final report and before the user approval gate, the lead performs one post-verification round. It extracts `P-Opt-*`, `P-Step-*`, `P-Dep-*`, `P-Val-*`, and `P-Rb-*` plan items from the synthesized `## 5.5` implementation plan deliverables and asks every analyzer worker for an `AGREE`, `DISAGREE(a-e)`, or `SUPPLEMENT` verdict. The aggregate result is `passed`, `passed-with-dissent`, `blocked-by-disagreement`, or `aborted-non-result`. The frontmatter `approved` field is always published as `false`; a blocking result keeps it false and becomes a row in `## 1. Clarification Items`. For fast iteration, opt out with `--no-plan-verification`. Contract details: the "Plan-body verification mode" section of [`prompts/lead/convergence.md`](prompts/lead/convergence.md) and [`docs/cli.md#--no-plan-verification`](docs/cli.md#--no-plan-verification).
 - **Brief as translation layer + Step 6.5 reporter batch confirmation** — `okstra-brief-gen` converts external input—an issue ticket, requirements document, or user message—verbatim and marks okstra-added content as labeled augmentation. Step 6.5 asks the user to confirm in one batch whether that conversion changed meaning and records the result in `Reporter Confirmations`. Every analysis profile requires this section before phase analysis begins; `validators/validate-brief.py` enforces the requirement.
 - **Artifact-home rule (`.okstra/`)** — `<project>/.okstra/` is the only project artifact root owned by okstra. Anything outside this root is not okstra memory and may be read only when explicitly cited in Source Material or Reporter Confirmations. Writing outside the root requires the same explicit requested path. Internal equivalents are `glossary.md` for terminology and `decisions/<NNNN>-<slug>.md` for decision records, evaluated during `implementation-planning`.

package/docs/architecture/storage-model.md

@@ -1,6 +1,6 @@
 # Storage model & on-disk contracts
 
-> Detailed storage and contract section from [`docs/kr/architecture.md`](../architecture.md). This section was split out after the main document exceeded 1,000 lines.
+> Detailed storage and contract section from [`docs/architecture.md`](../architecture.md). This section was split out after the main document exceeded 1,000 lines.
 
 ## Storage model
 
@@ -231,6 +231,8 @@ Main contents:
 This document is only a quick summary and is not the source of truth.
 Always use `task-manifest.json` when checking canonical metadata.
 
+The rendered `task-index.md` is an English-literal artifact. The headings, field labels, and `## Notes` footnote of the template (`templates/project-docs/task-index.template.md`) ship as English literals regardless of the `reportLanguage` setting, matching the okstra-schedule-gen schedule contract. The docs-publication pipeline's Hangul check (`npm run docs:validate`) enforces this contract.
+
 ## Run manifest contract
 
 Each execution records the current run contract in the resolved `<run-dir>/manifests/run-manifest-<task-type>-<seq>.json`. The non-stage or stage-qualified rule above determines `<run-dir>`.

package/docs/architecture.md

@@ -225,6 +225,20 @@ implementation-planning Phase 6
 
 Resolution is stage-scoped: only items whose `stageRefs` include the selected stage participate, so an unsafe open decision blocks that stage rather than unrelated ready stages. `no-design-inputs` resolves to `proceed`. Plans created before the `implementation-design-prep-v1` report contract also proceed with a `legacy-unassessed` warning and are not rewritten.
 
+### Fix-run incremental reverification
+
+When an implementation run is prepared on a stage whose latest final-report data.json carries one or more verifier `FAIL` verdicts, prep derives a fix-run carry (`okstra_ctl.stage_fix_carry`) — previous report path, previous run HEAD, failed verifiers, carried blocking findings, routing recommendation — and injects it into the rendered analysis profile as a "Fix-Run Carry" block via the `{{FIX_RUN_CONTEXT}}` token. Verifiers then keep the full validation-command re-run but narrow the static design/test-quality sweep to `git diff <prev-head>..HEAD` plus a mandatory re-check of each carried finding, and the report writer authors the new data.json incrementally by copying the previous one and updating only the changed blocks (`prompts/profiles/_implementation-verifier.md` § Fix-run incremental scope, `prompts/lead/report-writer.md` § Fix-run incremental authoring). A first run on a stage, or a rerun after a PASS, renders the token empty and behaves as before.
+
+### Clarification & decision-capture discipline
+
+okstra runs a single cross-phase discipline for turning open questions into resolved decisions and durable memory. It is not one module — it is enforced at three sites that share one vocabulary, deliberately split across an interactive layer and a headless layer:
+
+- **Interactive sharpening (bounded)** — `skills/okstra-brief-gen/SKILL.md` Step 4 asks one question at a time, each carrying a recommended answer, resolving facts from the codebase before asking. It is intentionally a *bounded* pass, not a decision-making interview: brief is a pre-discovery artifact, so the deep decision walk is pushed downstream.
+- **Headless decision-tree walk** — the `requirements-discovery` and `implementation-planning` profiles walk the decision tree one branch at a time, emitting a static `Clarification Items` table (recommended answer `(a)` + alternatives `(b) (c)`) rather than a live interview, because these phases are headless batch runs. Facts answerable by `Read` / `Grep` are resolved with `path:line` evidence and never escalated.
+- **Decision capture** — resolved terminology becomes okstra memory at `<PROJECT_ROOT>/.okstra/glossary.md` (approval-gated, `okstra-brief-gen` Step 4.5). A decision is recorded as `<PROJECT_ROOT>/.okstra/decisions/<NNNN>-<slug>.md` only when it is hard to reverse, surprising without context, and the result of a real trade-off; `implementation-planning` is the sole owner of that evaluation and `validators/validate-run.py` enforces materialization.
+
+When changing any one site, keep the shared vocabulary (recommended-answer, codebase-first, glossary, decision-record) aligned across all three so the discipline does not drift.
+
 ### Concurrency
 
 Two types of file locks handle all concurrency.
@@ -596,7 +610,7 @@ Approval format (code truth: `APPROVED_FRONTMATTER_PATTERN` in `scripts/okstra_c
 - Exactly one line inside the final report's leading `---` YAML fence: `approved: true` or `approved: false`
 - Case-insensitive. The report writer always publishes `approved: false`; implementation becomes available after the user toggles it to `true`
 
-To treat the CLI invocation itself as approval without editing the approval line directly, add the `--approve` flag. okstra toggles the `approved` field in the `--approved-plan` file's frontmatter to `true`, appends an audit line, and continues into the implementation phase (the former `--ack-approved` alias was removed in 0.8.0). See [`docs/kr/cli.md`](cli.md#--approve) for details.
+To treat the CLI invocation itself as approval without editing the approval line directly, add the `--approve` flag. okstra toggles the `approved` field in the `--approved-plan` file's frontmatter to `true`, appends an audit line, and continues into the implementation phase (the former `--ack-approved` alias was removed in 0.8.0). See [`docs/cli.md`](cli.md#--approve) for details.
 
 ```bash
 scripts/okstra.sh --task-type implementation --workers claude,codex,antigravity --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> --approved-plan <runs/implementation-planning/.../reports/final-report.md>
@@ -772,7 +786,7 @@ Each validator blocks the phase with a `contract-violated` exit code when a cont
 - The run directory is organized into typed subdirectories such as `manifests/`, `state/`, `prompts/`, `reports/`, `status/`, `sessions/`, and `worker-results/`; prompt snapshots are prepared under `prompts/` first.
 - Claude creates workers and collects results.
 - The standard workflow uses a `Claude lead` with default workers `Claude worker`, `Codex worker`, and `Report writer worker`; `Antigravity worker` is optional and included only when explicitly requested.
-- Worker models can be overridden with `--lead-model`, `--claude-model`, `--codex-model`, `--antigravity-model`, and `--report-writer-model`; defaults are centrally managed through `OKSTRA_DEFAULT_*` environment variables. Fallback defaults are `Claude lead`/`Report writer worker`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.6-sol`, and `Antigravity worker`=`auto`.
+- Worker models can be overridden with `--lead-model`, `--claude-model`, `--codex-model`, `--antigravity-model`, and `--report-writer-model`; defaults are centrally managed through `OKSTRA_DEFAULT_*` environment variables. Fallback defaults are `Claude lead`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.6-sol`, `Report writer worker`=`sonnet`, and `Antigravity worker`=`auto`.
 - For `--task-type implementation`, select the provider that takes the Executor role with `--executor <claude|codex|antigravity>` (or `OKSTRA_DEFAULT_EXECUTOR`, fallback `claude`). Only the Executor may mutate project files. The other two providers and the Executor's own provider are each dispatched as verifiers in separate CLI sessions (session isolation preserves the self-review safeguard). The Executor's model reuses the selected provider's worker-model flag (`--claude-model` / `--codex-model` / `--antigravity-model`). Provider / displayName / workerAgent / model are recorded in the run-manifest `teamContract.executor` block.
 - Worktree cwd injection by Executor: Codex / Antigravity executors pin cwd to the worktree at the CLI layer through wrappers (`okstra-codex-exec.sh -C` / `okstra-antigravity-exec.sh --include-directories`). Because the Bash tool has no per-call cwd argument, the Claude executor prefixes cwd-sensitive toolchain invocations (`cargo`/`npm`/`pnpm`/`bun`/`pytest`/`make`/`go`) with `cd {{EXECUTOR_WORKTREE_PATH}} && <cmd>` in the same Bash invocation. Wrapping in `bash -lc`/`bash -c` is prohibited because it hides the leading `cd` token and defeats permission auto-allow. Prefer working-directory flags such as `git -C` or `cargo --manifest-path` when available. See the *Executor Worktree* block in `prompts/profiles/implementation.md` and the Executor exception in `agents/workers/claude-worker.md` for details.
 - The project-level current-task convenience pointer is `.okstra/discovery/latest-task.json`.

package/docs/cli.md

@@ -369,7 +369,7 @@ When omitted, it uses the central default `OKSTRA_DEFAULT_ANTIGRAVITY_MODEL`, fa
 ### `--report-writer-model`
 
 Selects the model used by the `Report writer worker`.
-When omitted, it uses the central default `OKSTRA_DEFAULT_REPORT_WRITER_MODEL`, falling back to the lead default.
+When omitted, it uses the central default `OKSTRA_DEFAULT_REPORT_WRITER_MODEL`, falling back to `sonnet`. The report writer does not vote in convergence, so its default sits below the lead tier to cut report-generation wall-clock; pass `--report-writer-model opus` to restore the previous behavior.
 
 The central-default environment variables are:
 
@@ -646,6 +646,8 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra task-list [--project-root <path>]` | Combine `list_project_tasks` and `read_latest_task` into JSON containing the task catalog and latest task |
 | `okstra task-show <task-key> [--project-root <path>]` | Summarize workflow, phase, status, and artifacts from the Task Read-Side Snapshot |
 | `okstra stage-map <task-key> [--cwd <dir>\|--project <dir>]` | Dump the task's implementation-planning Stage Map as JSON: `{ ok, taskKey, taskRoot, stages:[{stage_number,title,depends_on,step_count}], doneStages:[int] }`. `stages` is `[]` when the task has no implementation-planning Stage Map. `doneStages` is read from the implementation-planning stage consumer state (with carry recovery). This is the read-side source the `okstra-schedule-gen` skill uses to derive stage units and their dependency closure |
+| `okstra incremental-scope <args…>` | Decide re-verify vs carry-forward scope for an `implementation-planning` clarification re-run. Thin shim into `scripts/okstra_ctl/incremental_scope.py` (deterministic pure function): it reads the dependency graph from the prior run `data.json`'s `implementationPlanning.stageMap` and returns `mode:"incremental"` only when the base-ref SHA is unchanged and the affected stages' `downstream_stage_closure` covers at most half of all stages; otherwise it signals a full re-run. Used to bound the cost of a clarification re-run |
+| `okstra incremental-carry <args…>` | Merge carried-forward plan-item verdicts into an incremental re-run. Thin shim into `scripts/okstra_ctl/incremental_carry.py`: it takes the prior run's plan-item verdicts that the current run does not re-verify and merges them into the current `data.json` tagged with `carriedForwardFromSeq`. A `schemaVersion` drift raises `CarryError` and exits non-zero to force a full fallback. Runs after `incremental-scope` returns `mode:"incremental"` |
 | `okstra set-work-status <token> <todo\|in-progress\|blocked\|done> [--note <text>] [--task-group <g>] [--project-root <dir>]` | Update user-managed `workStatus` in task-manifest.json, along with `workStatusUpdatedAt` and, when `--note` is supplied, `workStatusNote`. `<token>` is a full task key or bare task ID. It uses the manifest renderer's serialization rules and returns `stage:"ambiguous"` plus `matches[]` when ambiguous |
 | `okstra worktree-lookup <task-key>` | Return the `worktree_registry.lookup` result: reserved path, branch, base ref, and current status |
 | `okstra plan-validate <plan-path>` | Run `_validate_approved_plan` and report frontmatter `approved` recognition plus unresolved Blocks=approval rows |

package/docs/for-ai/README.md

@@ -1,52 +1,55 @@
 # Okstra Skills AI Manuals
 
-이 디렉터리는 AI가 okstra 공개 스킬을 빠르게 선택하고 정확히 실행하기 위한 압축 매뉴얼이다. 원문 계약은 `skills/*/SKILL.md`이고, 이 문서는 AI용 운영 가이드다. 원문 스킬, 템플릿, validator, CLI registry가 충돌하면 원문 스킬과 실제 validator/CLI 구현을 우선한다.
+This directory is a compressed manual for an AI to quickly select and precisely run okstra public skills. The authoritative contract is `skills/*/SKILL.md`; this document is the operational guide for the AI. When the source skills, templates, validators, or CLI registry conflict, prefer the source skills and the actual validator/CLI implementation.
 
-## 확인한 원천
+## Verified Sources
 
-- 공개 스킬 목록: [`src/lib/skill-catalog.mjs`](../../src/lib/skill-catalog.mjs)
-- 스킬 원문: [`skills/`](../../skills/)
-- CLI 명령 표면: [`src/cli-registry.mjs`](../../src/cli-registry.mjs)
-- brief 템플릿: [`templates/reports/brief.template.md`](../../templates/reports/brief.template.md)
-- schedule 템플릿: [`templates/reports/schedule.template.md`](../../templates/reports/schedule.template.md)
-- brief 검증기: [`validators/validate-brief.py`](../../validators/validate-brief.py)
-- schedule 검증기: [`validators/validate-schedule.py`](../../validators/validate-schedule.py)
+- Public skill list: [`src/lib/skill-catalog.mjs`](../../src/lib/skill-catalog.mjs)
+- Skill sources: [`skills/`](../../skills/)
+- CLI command surface: [`src/cli-registry.mjs`](../../src/cli-registry.mjs)
+- brief template: [`templates/reports/brief.template.md`](../../templates/reports/brief.template.md)
+- schedule template: [`templates/reports/schedule.template.md`](../../templates/reports/schedule.template.md)
+- brief validator: [`validators/validate-brief.py`](../../validators/validate-brief.py)
+- schedule validator: [`validators/validate-schedule.py`](../../validators/validate-schedule.py)
 
-## 스킬 라우팅
+## Skill Routing
 
-| 사용자 의도 | 사용할 스킬 | 매뉴얼 |
+| User intent | Skill to use | Manual |
 |---|---|---|
-| 새 프로젝트나 새 머신에서 okstra 설치/초기화 | `okstra-setup` | [`skills/okstra-setup.md`](skills/okstra-setup.md) |
-| 요구사항, 티켓, 링크, 코드베이스 스캔, error-zip을 okstra 입력 brief로 변환 | `okstra-brief-gen` | [`skills/okstra-brief-gen.md`](skills/okstra-brief-gen.md) |
-| 현재 Claude Code 세션에서 okstra run 시작 또는 다음 phase 실행 | `okstra-run` | [`skills/okstra-run.md`](skills/okstra-run.md) |
-| 여러 프로젝트에 걸친 okstra task 묶음, 할당, sync snapshot, child launch packet 관리 | `okstra-manager` | [`skills/okstra-manager.md`](skills/okstra-manager.md) |
-| 상태, history, report, time, logs, cost, errors, error-zip, recap 확인 | `okstra-inspect` | [`skills/okstra-inspect.md`](skills/okstra-inspect.md) |
-| task-group(또는 프로젝트 전체)의 여러 task run 결과를 모아 집계·종합 요약 | `okstra-rollup` | [`skills/okstra-rollup.md`](skills/okstra-rollup.md) |
+| Install/initialize okstra on a new project or a new machine | `okstra-setup` | [`skills/okstra-setup.md`](skills/okstra-setup.md) |
+| Turn requirements, tickets, links, a codebase scan, or an error-zip into an okstra input brief | `okstra-brief-gen` | [`skills/okstra-brief-gen.md`](skills/okstra-brief-gen.md) |
+| Start an okstra run or execute the next phase in the current Claude Code session | `okstra-run` | [`skills/okstra-run.md`](skills/okstra-run.md) |
+| Manage okstra tasks across multiple projects — bundling, assignment, sync snapshots, child launch packets | `okstra-manager` | [`skills/okstra-manager.md`](skills/okstra-manager.md) |
+| Check status, history, report, time, logs, cost, errors, error-zip, recap | `okstra-inspect` | [`skills/okstra-inspect.md`](skills/okstra-inspect.md) |
+| Collect and aggregate the results of multiple task runs across a task-group (or the whole project) into a synthesized summary | `okstra-rollup` | [`skills/okstra-rollup.md`](skills/okstra-rollup.md) |
 | Project-wide recent run coverage, tokens, known cost, CPU, and wall-clock usage by task type | `okstra-usage` | [`skills/okstra-usage.md`](skills/okstra-usage.md) |
-| task-group 전체의 클라이언트용 작업 일정 생성 | `okstra-schedule-gen` | [`skills/okstra-schedule-gen.md`](skills/okstra-schedule-gen.md) |
-| 대화/결정/선호/요구사항을 전역 Memory Book에 저장 또는 검색 | `okstra-memory` | [`skills/okstra-memory.md`](skills/okstra-memory.md) |
-| implementation task worktree 기반 docker compose 사용자 테스트 환경 관리 | `okstra-container-build` | [`skills/okstra-container-build.md`](skills/okstra-container-build.md) |
+| Generate a client-facing work schedule for a whole task-group | `okstra-schedule-gen` | [`skills/okstra-schedule-gen.md`](skills/okstra-schedule-gen.md) |
+| Store or search conversations/decisions/preferences/requirements in the global Memory Book | `okstra-memory` | [`skills/okstra-memory.md`](skills/okstra-memory.md) |
+| Manage the implementation-task worktree-based docker compose user-test environment | `okstra-container-build` | [`skills/okstra-container-build.md`](skills/okstra-container-build.md) |
+| Answer the unresolved clarification questions an okstra run left behind in-session and record the approval gate | `okstra-user-response` | [`skills/okstra-user-response.md`](skills/okstra-user-response.md) |
+| Build and query a knowledge graph over the project's own `.okstra` memory (reports, decision records, glossary) | `okstra-graphify` | [`skills/okstra-graphify.md`](skills/okstra-graphify.md) |
+| Register a PR body template or generate a PR description from a branch diff (global, git repository) | `okstra-pr-gen` | [`skills/okstra-pr-gen.md`](skills/okstra-pr-gen.md) |
 
-## 공통 실행 규칙
+## Shared Execution Rules
 
-1. 명령은 스킬 원문이 요구하는 경우 각각 별도의 Bash 호출로 실행한다. 특히 `okstra preflight --runtime claude-code --json`, `okstra wizard ...`, `okstra container ...` 호출을 `&&`, `||`, `$(...)`, 선행 변수 할당, `eval`, `export`로 감싸지 않는다.
-2. `okstra <subcmd>` 호출은 자체적으로 Python path를 부트스트랩한다. 스킬에서 명시하지 않는 한 `okstra paths --shell`이나 `export PYTHONPATH=...`를 만들지 않는다.
-3. `okstra-setup`을 제외한 대부분의 스킬은 `npx` fallback을 쓰지 않는다. runtime이 없으면 사용자에게 `/okstra-setup`을 실행하라고 알리고 멈춘다. 단 `unknown command: <cmd>`로 실패하면 PATH의 `okstra` 바이너리가 스킬보다 오래된 것이다 — `/okstra-setup`이 아니라 `npm i -g okstra@latest`를 안내하고 멈춘다.
-4. 프로젝트 산출물은 기본적으로 `<PROJECT_ROOT>/.okstra/` 아래에 둔다. 예외는 `okstra-memory`이며, 이 스킬은 전역 사용자 메모리 `~/.okstra/memory-book/`을 사용한다.
-5. `runtime/`은 build output이다. 스킬 원문이나 템플릿을 고칠 때는 `skills/`, `templates/`, `validators/`, `scripts/`, `src/`의 source를 수정하고 build로 반영한다.
-6. tracker, URL, 파일, report, log, zip, template, validator 내용을 추측하지 않는다. 도구로 읽거나 실행해서 확인한 내용만 사용한다.
-7. read-side 스킬도 일부 산출물을 만든다. `okstra-inspect errors`는 error report Markdown을 만들고, `okstra-inspect error-zip`은 anonymized zip을 만든다. 이런 경우에도 CLI stdout JSON을 source of truth로 둔다.
+1. Run commands as separate Bash calls whenever the source skill requires it. In particular, do not wrap `okstra preflight --runtime claude-code --json`, `okstra wizard ...`, or `okstra container ...` calls in `&&`, `||`, `$(...)`, a leading variable assignment, `eval`, or `export`.
+2. An `okstra <subcmd>` call bootstraps its own Python path. Unless a skill states otherwise, do not build `okstra paths --shell` or `export PYTHONPATH=...`.
+3. Most skills except `okstra-setup` do not use an `npx` fallback. If the runtime is missing, tell the user to run `/okstra-setup` and stop. But if it fails with `unknown command: <cmd>`, the `okstra` binary on PATH is older than the skill — point the user to `npm i -g okstra@latest` rather than `/okstra-setup`, and stop.
+4. Project artifacts go under `<PROJECT_ROOT>/.okstra/` by default. The exception is `okstra-memory`, which uses the global user memory `~/.okstra/memory-book/`.
+5. `runtime/` is build output. When fixing a source skill or template, edit the source under `skills/`, `templates/`, `validators/`, `scripts/`, `src/` and apply it via a build.
+6. Do not guess the contents of a tracker, URL, file, report, log, zip, template, or validator. Use only what you have confirmed by reading or running with a tool.
+7. Read-side skills also produce some artifacts. `okstra-inspect errors` produces an error report Markdown, and `okstra-inspect error-zip` produces an anonymized zip. Even in these cases, keep the CLI stdout JSON as the source of truth.
 
-## AI가 읽는 순서
+## The Order the AI Reads In
 
-1. 이 파일에서 스킬을 고른다.
-2. 해당 `docs/for-ai/skills/<skill>.md`만 읽는다.
-3. 스킬이 실제 실행을 요구하면 원문 [`skills/<skill>/SKILL.md`](../../skills/)에서 해당 step을 확인한다.
-4. brief나 schedule을 쓰는 경우 템플릿과 validator도 함께 확인한다.
+1. Pick a skill in this file.
+2. Read only the matching `docs/for-ai/skills/<skill>.md`.
+3. If the skill requires actual execution, confirm the relevant step in the source [`skills/<skill>/SKILL.md`](../../skills/).
+4. When writing a brief or schedule, also confirm the template and the validator.
 
-## 공개 스킬 목록
+## Public Skill List
 
-이 AI 매뉴얼에 나열된 공개 스킬은 다음 10개다.
+The public skills listed in this AI manual are the following 13:
 
 - `okstra-setup`
 - `okstra-brief-gen`
@@ -58,3 +61,6 @@
 - `okstra-usage`
 - `okstra-schedule-gen`
 - `okstra-container-build`
+- `okstra-user-response`
+- `okstra-graphify`
+- `okstra-pr-gen`

package/docs/for-ai/skills/okstra-brief-gen.md

@@ -1,72 +1,72 @@
 # okstra-brief-gen AI Manual
 
-## 원천
+## Source
 
-- 스킬 원문: [`skills/okstra-brief-gen/SKILL.md`](../../../skills/okstra-brief-gen/SKILL.md)
-- brief 템플릿: [`templates/reports/brief.template.md`](../../../templates/reports/brief.template.md)
+- Skill source: [`skills/okstra-brief-gen/SKILL.md`](../../../skills/okstra-brief-gen/SKILL.md)
+- brief template: [`templates/reports/brief.template.md`](../../../templates/reports/brief.template.md)
 - brief validator: [`validators/validate-brief.py`](../../../validators/validate-brief.py)
 - lens enum SSOT: [`scripts/okstra_ctl/improvement_lenses.py`](../../../scripts/okstra_ctl/improvement_lenses.py)
 
-## 목적
+## Purpose
 
-`okstra-brief-gen`는 okstra pipeline에 넣을 task brief를 만든다. brief는 pre-discovery 산출물이다. 요구사항을 구현 계획으로 바꾸는 문서가 아니라, reporter가 준 원문과 AI가 확인한 증거/해석을 라벨로 분리해 다음 phase가 질문 없이 출발하게 만드는 handoff 문서다.
+`okstra-brief-gen` produces a task brief to feed into the okstra pipeline. A brief is a pre-discovery artifact. It is not a document that turns requirements into an implementation plan; it is a handoff document that separates the reporter's verbatim material from the AI-verified evidence/interpretation using labels, so the next phase can start without questions.
 
-출력 위치:
+Output location:
 
 ```text
 <PROJECT_ROOT>/.okstra/briefs/<task-group>/<brief-id>.md
 <PROJECT_ROOT>/.okstra/briefs/<task-group>/sub/.../<brief-id>.md
 ```
 
-## 세 가지 variant
+## Three variants
 
-| Variant | 입력 | Recommended next phase |
+| Variant | Input | Recommended next phase |
 |---|---|---|
-| Reporter input | 파일, 티켓, URL, 대화/자유 텍스트 | `requirements-discovery` 또는 `error-analysis` |
+| Reporter input | files, tickets, URLs, conversation/free text | `requirements-discovery` or `error-analysis` |
 | Codebase scan | scan scope, priority lenses, candidate cap, context | `improvement-discovery` |
-| Error feedback | `okstra error-zip`이 만든 zip의 단일 error cluster | `error-analysis` |
+| Error feedback | a single error cluster from the zip produced by `okstra error-zip` | `error-analysis` |
 
-## 핵심 불변식
+## Core invariants
 
-1. Source Material은 원문 보존 영역이다. paraphrase, 요약, 재정렬을 하지 않는다.
-2. AI의 해석, 파일 링크, 용어 매핑, format 변환은 모두 `Augmentation` 또는 `> augmented:` blockquote에 둔다.
-3. augmentation은 네 label 중 하나를 가진다: `evidence-link`, `format-conversion`, `terminology-mapping`, `intent-inference`.
-4. `intent-inference`는 `Open Questions`의 `intent-check:`와 짝을 이룬다. 이 관계는 `validators/validate-brief.py`가 검사한다.
-5. `terminology-mapping` augmentation은 `Open Questions`의 `terminology:`와 짝을 이룬다(validator 검사). 단 Step 4.5 결과 marker `applied glossary:` / `skipped glossary:`는 예외 — 짝 row가 필요 없다.
-6. reporter만 답할 수 있는 질문은 Step 6.5에서 모아 `## Reporter Confirmations`에 verbatim으로 기록한다.
-7. 티켓 분리/연결/순서 관계는 `## Related Task Graph`의 구조화된 table에 둔다. parent-id만으로 작업 순서를 추론하지 않는다.
-8. 모든 okstra-owned write는 `<PROJECT_ROOT>/.okstra/` 안에 둔다. 외부 파일은 reporter가 source로 명시한 경우에만 읽는다.
-9. `Open Questions`의 모든 row는 다섯 prefix 중 하나로 시작한다: `general:`, `terminology:`, `intent-check:`, `conversion-block:`, `adr-candidate:` (validator 강제). `adr-candidate:`는 신호일 뿐 — decision file은 `implementation-planning`이 `<PROJECT_ROOT>/.okstra/decisions/`에 쓴다.
+1. Source Material is a verbatim-preservation area. Do not paraphrase, summarize, or reorder.
+2. The AI's interpretation, file links, terminology mapping, and format conversion all go under `Augmentation` or a `> augmented:` blockquote.
+3. An augmentation carries one of four labels: `evidence-link`, `format-conversion`, `terminology-mapping`, `intent-inference`.
+4. `intent-inference` is paired with `intent-check:` in `Open Questions`. This relationship is checked by `validators/validate-brief.py`.
+5. A `terminology-mapping` augmentation is paired with `terminology:` in `Open Questions` (validator-checked). Exception: the Step 4.5 result markers `applied glossary:` / `skipped glossary:` need no paired row.
+6. Questions only the reporter can answer are collected in Step 6.5 and recorded verbatim under `## Reporter Confirmations`.
+7. Ticket split/link/order relations go in the structured table of `## Related Task Graph`. Do not infer work order from parent-id alone.
+8. Every okstra-owned write stays inside `<PROJECT_ROOT>/.okstra/`. External files are read only when the reporter explicitly cited them as source.
+9. Every row in `Open Questions` starts with one of five prefixes: `general:`, `terminology:`, `intent-check:`, `conversion-block:`, `adr-candidate:` (validator-enforced). `adr-candidate:` is only a signal — the decision file is written by `implementation-planning` into `<PROJECT_ROOT>/.okstra/decisions/`.
 
 ## Preflight
 
-단일 호출로 실행한다.
+Run as a single call.
 
 ```bash
 okstra preflight --runtime claude-code --json
 ```
 
-runtime이나 project setup이 없으면 `/okstra-setup`을 안내하고 멈춘다. 이 스킬에서 `npx` fallback을 쓰지 않는다.
+If runtime or project setup is missing, guide the user to `/okstra-setup` and stop. This skill does not use an `npx` fallback.
 
-## 입력 수집
+## Input collection
 
 ### Reporter input
 
-소스 종류는 하나 이상 가능하지만 각 소스는 `Source Material`에 별도 block으로 저장한다.
+More than one source type is allowed, but each source is stored as a separate block under `Source Material`.
 
-- File: 전체 파일을 읽고 그대로 넣는다.
-- Issue tracker ticket: Linear/Jira/GitHub/Notion을 감지하고 MCP 또는 `gh` CLI를 사용한다. 접근 도구가 없으면 사용자에게 body paste 또는 skip을 묻는다.
-- Link URL: fetch한다. 실패/로그인 wall/본문 truncation이면 사용자에게 paste를 요청한다.
-- User input: 대화 맥락이 충분하면 conversation synthesis, 부족하면 한 번만 free-text를 받는다.
+- File: read the entire file and insert it as-is.
+- Issue tracker ticket: detect Linear/Jira/GitHub/Notion and use MCP or the `gh` CLI. If no access tool is available, ask the user to paste the body or skip.
+- Link URL: fetch it. On failure / login wall / body truncation, ask the user to paste.
+- User input: if conversation context is sufficient, use conversation synthesis; if thin, take a single free-text input.
 
-티켓에 child/sub-task가 있으면 parent에서 한 번만 tree 처리 방식을 묻는다.
+If a ticket has children/sub-tasks, ask once at the parent how to handle the tree.
 
-- Full tree: descendant별 brief 생성.
-- Parent only: child key/URL을 Related Artifacts에 두고 `Related Task Graph`에는 `parent-of` edge를 남긴다.
-- Selected: 선택한 direct child branch만 재귀 처리.
+- Full tree: generate a brief per descendant.
+- Parent only: put child keys/URLs in Related Artifacts and leave a `parent-of` edge in `Related Task Graph`.
+- Selected: recurse only into the chosen direct-child branch.
 
-재귀 시 visited set은 `<tracker>:<ticket-id>`로 관리하고, 재실행에서는 기존 brief frontmatter의 `ticket-id` + `source-type`으로 reseed한다.
-Full tree 또는 Selected로 여러 brief를 만들면 모든 생성 brief에 같은 `Related Task Graph`를 복사한다. 그래야 child brief 하나만 downstream phase에 전달돼도 split topology, 선행/후행 관계, 중복 방지 신호가 유지된다.
+During recursion, manage the visited set as `<tracker>:<ticket-id>`, and on re-run reseed from the existing brief frontmatter's `ticket-id` + `source-type`.
+When Full tree or Selected produces multiple briefs, copy the same `Related Task Graph` into every generated brief. That way, even if only one child brief is passed to a downstream phase, the split topology, predecessor/successor relations, and de-duplication signals are preserved.
 
 `Related Task Graph` table schema:
 
@@ -77,39 +77,39 @@ Full tree 또는 Selected로 여러 brief를 만들면 모든 생성 brief에
 | To | task key, brief id, tracker id, or URL |
 | Direction | `directed` or `undirected` |
 | Source | tracker linked issue, task-list checkbox, reporter statement, manual split, prior okstra task |
-| Impact | downstream phase가 보존해야 할 의미 |
+| Impact | meaning the downstream phase must preserve |
 
-`depends-on`, `blocks`, parent/child, follow-up, split 관계는 `directed`다. `duplicates`, `related-to`는 `undirected`다. source가 없는 관계는 만들지 않는다.
+`depends-on`, `blocks`, parent/child, follow-up, and split relations are `directed`. `duplicates` and `related-to` are `undirected`. Do not create a relation with no source.
 
 ### Codebase scan
 
-수집값:
+Collected values:
 
-- `scan_scope`: 프로젝트 내부 실제 경로 목록.
-- `priority_lenses`: `LENSES` enum 중 1-4개.
-- `out_of_scope`: 선택.
-- `candidate_cap`: 1-12, 기본 8.
+- `scan_scope`: a list of real paths inside the project.
+- `priority_lenses`: 1–4 of the `LENSES` enum.
+- `out_of_scope`: optional.
+- `candidate_cap`: 1–12, default 8.
 - context, desired outcome, constraints.
 
-경로 존재, lens enum subset, candidate cap 범위는 작성 전 확인한다. 최종 검증은 `validate-brief.py`가 `scope: codebase`, `Scan Scope`, `Priority Lenses`를 검사한다.
+Verify path existence, the lens enum subset, and the candidate-cap range before writing. Final validation is done by `validate-brief.py`, which checks `scope: codebase`, `Scan Scope`, and `Priority Lenses`.
 
 ### Error feedback
 
-입력은 `okstra error-zip --out <path>`가 만든 zip이다.
+The input is the zip produced by `okstra error-zip --out <path>`.
 
-처리:
+Processing:
 
-1. zip에 `report.md`, `errors/anonymized.jsonl`이 있는지 확인한다.
-2. 빈발 cluster 표에서 cluster 하나만 선택한다.
-3. 선택 cluster의 anonymized records만 Source Material에 옮긴다.
-4. 서로 다른 errorType을 한 brief에 섞지 않는다.
-5. 다음 단계 안내는 `error-analysis`로 둔다.
+1. Confirm the zip contains `report.md` and `errors/anonymized.jsonl`.
+2. Pick exactly one cluster from the frequent-cluster table.
+3. Move only the chosen cluster's anonymized records into Source Material.
+4. Do not mix different errorTypes into one brief.
+5. Set the next-step guidance to `error-analysis`.
 
-## task-group과 파일명
+## task-group and filename
 
-task-group은 기존 group 추천을 먼저 보여준다. `okstra task-list`를 호출해 `tasks[]`의 distinct `taskGroup`을 최신순으로 뽑고, 최근 2개 + 직접 입력을 제공한다. tracker recursion에서는 child path를 만들기 전에 task-group을 먼저 받아야 한다.
+For task-group, show existing-group recommendations first. Call `okstra task-list`, extract the distinct `taskGroup` values from `tasks[]` in most-recent order, and offer the 2 most recent + enter-directly. In tracker recursion, task-group must be obtained before building any child path.
 
-파일 경로 규칙:
+File path rule:
 
 ```text
 depth 0: .okstra/briefs/<task-group>/<ticket-id>-<file-title>.md
@@ -117,56 +117,56 @@ depth 1: .okstra/briefs/<task-group>/sub/<ticket-id>-<file-title>.md
 depth N: .okstra/briefs/<task-group>/<sub/ repeated N>/<ticket-id>-<file-title>.md
 ```
 
-frontmatter의 `depth`는 path의 `sub/` 개수와 같아야 한다. validator가 검사한다.
+The frontmatter's `depth` must equal the number of `sub/` segments in the path. The validator checks this.
 
-충돌 시 기본은 Skip이다. Append suffix 또는 Overwrite를 제공할 수 있다. tracker multi-generation에서 bulk overwrite를 조용히 수행하지 않는다.
+On collision, the default is Skip. You may offer Append suffix or Overwrite. Do not silently perform a bulk overwrite in tracker multi-generation.
 
 ## Domain alignment
 
-먼저 okstra 내부 memory를 본다.
+First look at okstra's internal memory.
 
 - `<PROJECT_ROOT>/.okstra/glossary.md`
 - `<PROJECT_ROOT>/.okstra/decisions/`
-- 관련 task의 `history/fix-cycles.jsonl`
+- the related task's `history/fix-cycles.jsonl`
 
-외부 domain docs는 reporter가 source material로 명시했을 때만 읽는다. 충돌/모호 용어는 `Augmentation > Domain alignment`에 `terminology-mapping`으로 기록하고, `Open Questions`에 `terminology:` row를 둔다.
+Read external domain docs only when the reporter explicitly cited them as source material. Record conflicting/ambiguous terms under `Augmentation > Domain alignment` with `terminology-mapping`, and put a `terminology:` row in `Open Questions`.
 
-파일 path나 symbol이 언급되면 `Read`/`Grep`으로 실제 in-repo reference를 찾고 `evidence-link`로 남긴다. 매핑할 수 없으면 추측하지 않고 `conversion-block:` row로 둔다.
+When a file path or symbol is mentioned, find the actual in-repo reference with `Read`/`Grep` and record it as `evidence-link`. If it cannot be mapped, do not guess — leave a `conversion-block:` row.
 
 ## Sharpening pass
 
-full interview를 하지 않는다. source와 codebase로 채울 수 없는 gap만 묻는다.
+Do not run a full interview. Ask only about gaps that source and codebase cannot fill.
 
-기본 budget:
+Default budget:
 
-- 원문 스킬이 채움 대상으로 지정한 section당 최대 1문항.
-- terminology/fuzzy disambiguation 최대 2문항.
-- 전체 최대 6문항.
-- codebase-scan은 최대 8문항.
+- at most 1 question per section the source skill designates as fill-in.
+- at most 2 questions for terminology/fuzzy disambiguation.
+- at most 6 questions overall.
+- codebase-scan up to 8 questions.
 
-질문보다 codebase-first 확인을 우선한다. 남은 gap은 `_(none)_` 또는 `Open Questions`에 둔다.
+Prefer codebase-first checks over questions. Put remaining gaps in `_(none)_` or `Open Questions`.
 
-## template 작성 규칙
+## template writing rules
 
-템플릿은 `templates/reports/brief.template.md`가 SSOT다. section 순서, frontmatter key, top blockquote shape, HTML comment guidance를 따른다.
+The template `templates/reports/brief.template.md` is the SSOT. Follow the section order, frontmatter keys, top blockquote shape, and HTML comment guidance.
 
-Reporter input과 Error feedback:
+Reporter input and Error feedback:
 
-- `## Source Material` 유지.
-- `## Problem / Symptom` 유지.
-- `## Scan Scope`, `## Priority Lenses` 생략.
+- keep `## Source Material`.
+- keep `## Problem / Symptom`.
+- omit `## Scan Scope`, `## Priority Lenses`.
 
 Codebase scan:
 
-- frontmatter에 `scope: codebase`.
-- `## Source Material`, `## Problem / Symptom` 생략.
-- `## Scan Scope`, `## Priority Lenses` 유지.
+- `scope: codebase` in frontmatter.
+- omit `## Source Material`, `## Problem / Symptom`.
+- keep `## Scan Scope`, `## Priority Lenses`.
 
-빈 섹션을 날조하지 않는다. 값이 없으면 `_(none)_`를 사용한다.
+Do not fabricate empty sections. When there is no value, use `_(none)_`.
 
 ## frontmatter key
 
-모든 brief는 다음 key를 가진다. key set은 `validate-brief.py`에서 검사한다.
+Every brief carries the following keys. The key set is checked by `validate-brief.py`.
 
 - `type`
 - `brief-id`
@@ -179,42 +179,42 @@ Codebase scan:
 - `generator`
 - `reporter-confirmations`
 
-`brief-id`는 filename stem과 같아야 한다. depth 0의 `parent-id`는 `self`, descendant의 `parent-id`는 direct parent의 `brief-id`다.
+`brief-id` must equal the filename stem. At depth 0 the `parent-id` is `self`; a descendant's `parent-id` is its direct parent's `brief-id`.
 
 ## Recommended next phase
 
-brief 본문 top blockquote의 `Recommended next phase:`에 쓴다.
+Write it into the `Recommended next phase:` of the brief body's top blockquote.
 
 - observable error, repro, stack trace, error-zip record: `error-analysis`
-- ambiguity나 Open Questions가 큰 요구사항: `requirements-discovery`
+- a requirement with ambiguity or large Open Questions: `requirements-discovery`
 - `scope: codebase`: `improvement-discovery`
-- 애매하면 `requirements-discovery`
+- if ambiguous: `requirements-discovery`
 
-`okstra-run`을 자동으로 시작하지 않는다.
+Do not auto-start `okstra-run`.
 
 ## Reporter Confirmations
 
-`Open Questions`에서 reporter만 답할 수 있는 row를 모은다.
+Collect the rows in `Open Questions` that only the reporter can answer.
 
 - `intent-check:`
 - `conversion-block:`
 
-이미 `[CONFIRMED <date> → RC-N]` marker가 있으면 pending에서 제외한다. 사용자에게 지금 답할지 묻고, 답하면 `## Reporter Confirmations`에 verbatim으로 기록한다. row는 삭제하지 않고 marker를 붙인다.
+If a `[CONFIRMED <date> → RC-N]` marker already exists, exclude it from pending. Ask the user whether to answer now; if they answer, record it verbatim under `## Reporter Confirmations`. Do not delete the row — attach a marker.
 
-한 run당 최대 12문항. pending이 12개를 넘으면 `conversion-block:` → `intent-check:` 순으로 상위 12개만 묻고, 나머지는 `partial`로 남긴 뒤 어떤 row가 남았는지 사용자에게 알린다.
+At most 12 questions per run. If pending exceeds 12, ask only the top 12 in `conversion-block:` → `intent-check:` order, leave the rest as `partial`, then tell the user which rows remain.
 
-상태값:
+Status values:
 
-- `complete`: pending reporter-only row가 모두 답변됨. validator는 모든 `intent-check:`/`conversion-block:` row에 `[CONFIRMED …]` marker가 있는지 검사한다.
-- `partial`: 일부만 답변됨. validator는 최소 1개 row에 `[CONFIRMED …]` marker가 있는지 검사한다(아무것도 못 받았으면 `skipped`).
-- `skipped`: 사용자가 downstream phase에 넘기기로 함.
-- `pending`: handoff 전 상태로 보고 진행하지 않는다.
+- `complete`: all pending reporter-only rows are answered. The validator checks that every `intent-check:`/`conversion-block:` row has a `[CONFIRMED …]` marker.
+- `partial`: only some are answered. The validator checks that at least one row has a `[CONFIRMED …]` marker (if nothing was received, `skipped`).
+- `skipped`: the user chose to defer to a downstream phase.
+- `pending`: treated as a pre-handoff state; do not proceed.
 
-## 검증
+## Validation
 
-작성 후 handoff 메시지를 내기 전에 validator를 실행한다.
+After writing, run the validator before emitting the handoff message.
 
-설치본:
+Installed copy:
 
 ```bash
 ~/.okstra/lib/validators/validate-brief.sh "<PROJECT_ROOT>/.okstra/briefs" --briefs-root "<PROJECT_ROOT>/.okstra/briefs"
@@ -226,19 +226,19 @@ repo checkout:
 validators/validate-brief.sh "<PROJECT_ROOT>/.okstra/briefs" --briefs-root "<PROJECT_ROOT>/.okstra/briefs"
 ```
 
-실패하면 cited brief를 고치고 재실행한다. validator가 없을 때만 manual checklist로 대체한다.
-validator는 `Related Task Graph`가 있으면 table header, relation enum, direction enum, directed/undirected mismatch도 검사한다.
+On failure, fix the cited brief and re-run. Fall back to a manual checklist only when the validator is absent.
+When a `Related Task Graph` is present, the validator also checks the table header, relation enum, direction enum, and directed/undirected mismatch.
 
-## 완료 메시지
+## Completion message
 
-단일 brief:
+Single brief:
 
 ```text
 brief saved: <abs-path>
 next: /okstra-run  (recommended task-type: <phase>)
 ```
 
-multi-brief:
+Multi-brief:
 
 ```text
 briefs saved (N):
@@ -247,12 +247,12 @@ briefs saved (N):
 next: /okstra-run
 ```
 
-## 금지 패턴
+## Forbidden patterns
 
-- Source Material을 요약하거나 정리해서 넣기.
-- tracker/URL 내용을 도구 확인 없이 추측하기.
-- unlabelled augmentation 작성하기.
-- `intent-inference`를 `intent-check:` 없이 남기기.
-- 외부 docs/ADR에 decision file을 쓰기. okstra decision은 `<PROJECT_ROOT>/.okstra/decisions/`에만 해당한다.
-- child tree 전체를 silent overwrite하기.
-- brief 생성 직후 자동으로 `okstra-run` 시작하기.
+- Summarizing or tidying Source Material before inserting it.
+- Guessing tracker/URL content without tool verification.
+- Writing unlabelled augmentation.
+- Leaving `intent-inference` without `intent-check:`.
+- Writing a decision file into external docs/ADR. okstra decisions belong only in `<PROJECT_ROOT>/.okstra/decisions/`.
+- Silently overwriting an entire child tree.
+- Auto-starting `okstra-run` right after brief generation.