okstra 0.122.0 → 0.124.0

package/README.md

@@ -137,7 +137,7 @@ okstra install          # same as 'npx -y okstra@latest install'
 
 The global install only registers the Node CLI on PATH. The runtime (`~/.okstra/`) and host skill directories (`~/.claude/skills/` or `~/.agents/skills/`) are still created by `okstra install`; they are not included in `npm i -g`. To upgrade later, run `npm i -g okstra@latest && okstra install`. To remove the global binary, run `npm uninstall -g okstra` (this leaves `~/.okstra/` intact; remove that with `okstra uninstall`).
 
-**Skill behavior with a global install.** Every okstra skill detects a PATH-resolved `okstra` command and prefers it over `npx -y okstra@latest`. A global install therefore removes the npx fetch/version-check cost from every skill invocation (Step 0 of `okstra-run`, `okstra-inspect`, `okstra-schedule`, and Step 0 of `okstra-setup` Step 2). Because each skill uses the installed version directly, **you control when upgrades happen**; `@latest` is no longer forced on every call. Run `npm i -g okstra@latest && okstra install` whenever you want a new release. If `okstra` is not on PATH, the skills automatically fall back to npx, so environments without a global install continue to work unchanged.
+**Skill behavior with a global install.** Every okstra skill detects a PATH-resolved `okstra` command and prefers it over `npx -y okstra@latest`. A global install therefore removes the npx fetch/version-check cost from every skill invocation (Step 0 of `okstra-run`, `okstra-inspect`, `okstra-schedule-gen`, and Step 0 of `okstra-setup` Step 2). Because each skill uses the installed version directly, **you control when upgrades happen**; `@latest` is no longer forced on every call. Run `npm i -g okstra@latest && okstra install` whenever you want a new release. If `okstra` is not on PATH, the skills automatically fall back to npx, so environments without a global install continue to work unchanged.
 
 <a id="register-a-project"></a>
 ### 3.2 Register a project (once per project)
@@ -170,10 +170,12 @@ Use these slash commands inside a Claude Code session:
 | `/okstra-inspect` | Unified read side. Subcommands: `status` (phase/state and workStatus updates), `history` (past tasks, reruns, resumes), `report` (find/read final reports), `time` (elapsed-time breakdown), `logs` (wrapper log sidecar inventory and cleanup suggestions), `cost` (task bundle context/read cost), `errors` (aggregate run error logs into a report), `error-zip` (collect cross-project error logs into an anonymized zip and summarize clusters), and `recap` (run-to-run before/after summary plus free-form Q&A over a task's `.okstra` artifacts) |
 | `/okstra-rollup` | Aggregate every task run in a task group or project, including per-task run counts, duration, errors, group totals, and a cross-task report digest |
 | `/okstra-usage` | Show the current project's recent run coverage, raw and billable-equivalent tokens, known USD cost, CPU time, and wall-clock time grouped by task type (default: last 30 days) |
-| `/okstra-schedule` | Generate a work schedule for an entire task group |
+| `/okstra-schedule-gen` | Generate a work schedule for an entire task group. Stages are sourced from each non-done task's `implementation-planning` final-report **Stage Map**; you pick which stages to include, and the final file is written only after an independent verifier subagent confirms the draft covers exactly the selected stages |
 | `/okstra-container-build` | Deploy a verified task's code as a local Docker Compose group and monitor per-container logs (subcommands: `up` / `status` / `logs` / `stop-watcher` / `down`) |
 | `/okstra-graphify` | Build and query a knowledge graph over the project's own `.okstra/` memory—final reports, `decisions/*.md`, and `glossary.md`—with scope restricted to `.okstra/` and output under `.okstra/graph/` (subcommands: `build` / `query` / `path` / `explain` / `mcp` / `wiki`) |
 | `/okstra-manager` | Coordinate cross-project okstra tasks through manager-owned plans, assignments, one-way project sync snapshots, status, and child launch context packets |
+| `/okstra-pr-gen` | Register PR body templates under `~/.okstra/template/pr/` and generate a PR description from a branch diff (subcommands: `template` / `branches` / `gen`). Global skill—needs a Git repo, not a registered okstra project |
+| `/okstra-user-response` | Answer a task's open clarification questions in-session and write the response sidecar. Each answer is dispositioned as `answer` or `reframe`; a `reframe` is carried into the next run as a re-scoped brief |
 | `/okstra-setup` | Bootstrap a project as described in §3.2 |
 
 The lead operating contract and support contracts—context loader, team contract, convergence, report writer, and the coding-preflight pack—are no longer installed as agent skills. They are installed as okstra runtime resources under `~/.okstra/prompts/` (`prompts/lead/*.md`, `prompts/coding-preflight/*`), and the generated launch prompt gives the lead their absolute paths. Reinstallation prunes legacy copies from agent skill homes, so they are not exposed as slash commands.
@@ -209,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
 
@@ -39,6 +39,8 @@ The task manifest, task index, instruction set, runs, and history are collected
 │       │   └── report-writer-worker-prompt-<task-type>-<seq>.md
 │       ├── reports/
 │       │   └── final-report-<task-type>-<seq>.md
+│       ├── design-prep-requests/       # implementation-planning only; deterministic Okstra-owned drafts
+│       ├── design-prep-inputs/         # implementation-planning only; append-only user/wizard responses
 │       ├── status/
 │       │   └── final-<task-type>-<seq>.status
 │       ├── sessions/
@@ -78,11 +80,23 @@ Unless `--render-only` is used, the handed-off Claude session typically adds the
 - `sessions/claude-resume-<task-type>-<seq>.sh`
 - `reports/final-report-<task-type>-<seq>.md`
 - `reports/final-report-<task-type>-<seq>.html`     *(Phase 7 deterministic post-processing: self-contained HTML for human reviewers, with inline CSS/JS)*
+- `design-prep-requests/design-prep-request-<seq>-PREP-<NNN>.md` *(implementation-planning only: deterministic AI-prepared request for a `provisional` or `blocked` design item)*
+- `design-prep-inputs/design-prep-input-<seq>-PREP-<NNN>-r<revision>-<uuid>.md` *(implementation-planning only: append-only confirmed user/wizard response)*
 - `user-responses/user-response-<task-type>-<seq>.md` *(A sidecar downloaded under the same name by the HTML `Export user response` button; storing it here lets `--resume-clarification` automatically attach it to `clarification-response.md` in the instruction set — `clarification_items.clarification_response_with_sidecars`)*
 - `worker-results/<worker>-audit-<task-type>-<seq>.md` *(Per-worker Reading Confirmation sidecar; for auditing rather than report content)*
 - `status/final-<task-type>-<seq>.status`
 - `runs/implementation/stage-<N>/carry/stage-<N>.json` *(implementation only: execution evidence sidecar beneath stage N's resolved run directory; automatically carried into the next stage)*
 - `consumers.jsonl` *(implementation-planning only: backlinks to the impl-run that consumed each stage in this plan; append-only)*
+
+Design-preparation storage has three separate authorities:
+
+| Artifact | Owner | Mutation contract |
+|---|---|---|
+| `reports/final-report-implementation-planning-<seq>.data.json` | report writer / approved planning snapshot | Immutable after approval. Phase 7 may populate report-owned cells before approval, but a later CLI or wizard response never edits this snapshot. |
+| `design-prep-requests/design-prep-request-<seq>-PREP-<NNN>.md` | Okstra | Deterministic from the snapshot, report language, and request-template version. Re-materialization is idempotent; different existing content is never overwritten. |
+| `design-prep-inputs/design-prep-input-<seq>-PREP-<NNN>-r<revision>-<uuid>.md` | user or wizard | Append-only and written only after semantic confirmation. Existing revisions are never edited or reserved before confirmation. |
+
+The resolver selects the highest unique revision whose assessment fingerprint still matches the approved snapshot. Duplicate revision numbers and stale fingerprints are skipped with warnings rather than granted authority. A markerless legacy plan has no sidecars to migrate: it proceeds with the `legacy-unassessed` warning. This compatibility path does not rewrite its report.
 The final result files (`final-report` MD / status) are not files that `okstra` creates by saving stdout.
 They are results written directly into the current run by Claude, based on the task bundle prepared by `okstra`.
 The self-contained HTML view is generated deterministically from a single final-report MD input by `okstra render-views <final-report.md>` (Phase 7 step 1.5). Generating the view does not modify the original MD.

package/docs/architecture.md

@@ -117,6 +117,7 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
 - [`okstra_ctl.run_context`](../scripts/okstra_ctl/run_context.py) — `compute_and_write_run_context()`, `write_run_inputs()`, and the per-task mutex.
 - [`okstra_ctl.render`](../scripts/okstra_ctl/render.py) — task-manifest / run-manifest / timeline / task-index / team-state / launch.template / reference-expectations / discovery render functions + `python3 -m okstra_ctl.render <subcommand>` dispatcher (**PYTHONPATH must be configured—see the invocation contract above**).
 - [`okstra_ctl.workers`](../scripts/okstra_ctl/workers.py) · [`okstra_ctl.models`](../scripts/okstra_ctl/models.py) — worker / model resolution.
+- [`okstra_ctl.design_prep`](../scripts/okstra_ctl/design_prep.py) — implementation-planning design assessment fingerprints, deterministic request materialization, append-only confirmed inputs, and stage-scoped resolution. The Node `okstra design-prep` command is a thin caller of this module.
 - [`okstra_ctl.workflow`](../scripts/okstra_ctl/workflow.py) — phase rules (PHASE_ALLOWED_OUTPUTS / PHASE_FORBIDDEN_ACTIONS).
 - [`okstra_ctl.material`](../scripts/okstra_ctl/material.py) — `analysis-material.md` body + related-tasks builder.
 - [`okstra_ctl.session`](../scripts/okstra_ctl/session.py) · [`okstra_ctl.seeding`](../scripts/okstra_ctl/seeding.py) — Claude session ID / resume command / installation validation / runtime settings.
@@ -149,9 +150,9 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
 - Runtime selection and worker-provider assignment remain independent. Milestone 1 keeps `claude-execution-prompt.md`, existing manifest role labels, model defaults, and worker rosters for compatibility; provider registry and front-door separation are later milestones.
 - [`skills/okstra-setup/SKILL.md`](../skills/okstra-setup/SKILL.md) — **first-run bootstrap**. Runs `okstra install` and creates `project.json`.
 - [`skills/okstra-run/SKILL.md`](../skills/okstra-run/SKILL.md) — in-session entry point that **starts an okstra task in the current Claude session**. Calls `prepare_task_bundle` directly.
-- Thirteen skills are user-invocable: `skills/okstra-setup/SKILL.md`, `skills/okstra-brief-gen/SKILL.md`, `skills/okstra-run/SKILL.md`, `skills/okstra-manager/SKILL.md`, `skills/okstra-memory/SKILL.md`, `skills/okstra-inspect/SKILL.md`, `skills/okstra-rollup/SKILL.md`, `skills/okstra-usage/SKILL.md`, `skills/okstra-schedule/SKILL.md`, `skills/okstra-container-build/SKILL.md`, `skills/okstra-graphify/SKILL.md`, `skills/okstra-pr-gen/SKILL.md`, and `skills/okstra-user-response/SKILL.md`. Only these are copied into the agent skill home. They cover brief authoring, phase execution, cross-project manager task coordination, global Memory Book storage/search, read-side status/history/report/time/logs/cost/errors/recap, task-group-level aggregation of run results (rollup), project-wide historical resource usage, schedule support, local container deployment, `.okstra` knowledge graphs, PR description generation, and clarification-response submission. `okstra-manager` uses `okstra manager` CLI JSON/launch packets as the source of truth, and stores manager-owned plans, assignments, directives, snapshots, and events under `~/.okstra/managers/<manager-id>/`. `okstra-rollup` is a read-side layer that fans the single-task aggregators from `okstra-inspect` (time/errors/recap) out to a task group or the whole project catalog. The `okstra rollup` CLI owns deterministic aggregation, while the skill (LLM) writes only the synthesized report summary. `okstra-usage` is a separate read-only resource snapshot grouped by lifecycle task type; it does not replace single-task `okstra-inspect` detail or the status/report digest from `okstra-rollup`. The canonical definition of `okstra-inspect` read-side facets is the subcommand table in `skills/okstra-inspect/SKILL.md`. `okstra-inspect logs` provides a read-only inventory and cleanup guidance for the live-log sidecars that the Codex/Antigravity wrappers write on every dispatch at the resolved `<run-dir>/prompts/<worker>-prompt-<phase>-<seq>.log`; for stage executions, the stage-qualified `run_dir` includes `stage-<N>/`. `okstra-inspect cost` summarizes `okstra context-cost`; `okstra-inspect errors` collects a task's okstra-run error logs into a timestamped Markdown error report and prints a summary; and `okstra-inspect recap` answers free-form questions about `.okstra` artifacts in addition to summarizing phases before and after each task run.
+- Thirteen skills are user-invocable: `skills/okstra-setup/SKILL.md`, `skills/okstra-brief-gen/SKILL.md`, `skills/okstra-run/SKILL.md`, `skills/okstra-manager/SKILL.md`, `skills/okstra-memory/SKILL.md`, `skills/okstra-inspect/SKILL.md`, `skills/okstra-rollup/SKILL.md`, `skills/okstra-usage/SKILL.md`, `skills/okstra-schedule-gen/SKILL.md`, `skills/okstra-container-build/SKILL.md`, `skills/okstra-graphify/SKILL.md`, `skills/okstra-pr-gen/SKILL.md`, and `skills/okstra-user-response/SKILL.md`. Only these are copied into the agent skill home. They cover brief authoring, phase execution, cross-project manager task coordination, global Memory Book storage/search, read-side status/history/report/time/logs/cost/errors/recap, task-group-level aggregation of run results (rollup), project-wide historical resource usage, schedule support, local container deployment, `.okstra` knowledge graphs, PR description generation, and clarification-response submission. `okstra-manager` uses `okstra manager` CLI JSON/launch packets as the source of truth, and stores manager-owned plans, assignments, directives, snapshots, and events under `~/.okstra/managers/<manager-id>/`. `okstra-rollup` is a read-side layer that fans the single-task aggregators from `okstra-inspect` (time/errors/recap) out to a task group or the whole project catalog. The `okstra rollup` CLI owns deterministic aggregation, while the skill (LLM) writes only the synthesized report summary. `okstra-usage` is a separate read-only resource snapshot grouped by lifecycle task type; it does not replace single-task `okstra-inspect` detail or the status/report digest from `okstra-rollup`. The canonical definition of `okstra-inspect` read-side facets is the subcommand table in `skills/okstra-inspect/SKILL.md`. `okstra-inspect logs` provides a read-only inventory and cleanup guidance for the live-log sidecars that the Codex/Antigravity wrappers write on every dispatch at the resolved `<run-dir>/prompts/<worker>-prompt-<phase>-<seq>.log`; for stage executions, the stage-qualified `run_dir` includes `stage-<N>/`. `okstra-inspect cost` summarizes `okstra context-cost`; `okstra-inspect errors` collects a task's okstra-run error logs into a timestamped Markdown error report and prints a summary; and `okstra-inspect recap` answers free-form questions about `.okstra` artifacts in addition to summarizing phases before and after each task run.
 - Internal operating contracts—`context-loader` / `team-contract` / `convergence` / `report-writer` and the lead contract—have moved to `prompts/lead/*.md`. Language-specific coding preflight for implementation/verification workers has moved to `prompts/coding-preflight/*` (overview router + clean-code + three-stage language/framework/architecture selection). All are runtime resources installed under `~/.okstra/prompts/` and are not discoverable as skills. The generated launch prompt provides the lead with absolute paths, and reinstalling prunes the legacy exact-name skill directories `okstra-context-loader` / `okstra-team-contract` / `okstra-convergence` / `okstra-report-writer` / `okstra-coding-preflight` / `okstra`.
-- Plugin manifest: [`../../.claude-plugin/plugin.json`](../.claude-plugin/plugin.json) — referenced by the supplementary `npx skills@latest add Devonshin/okstra` channel. Use `npx okstra@latest install` for normal setup. The plugin manifest exposes only the thirteen user entry points (`okstra-setup`, `okstra-brief-gen`, `okstra-run`, `okstra-manager`, `okstra-memory`, `okstra-inspect`, `okstra-rollup`, `okstra-usage`, `okstra-schedule`, `okstra-container-build`, `okstra-graphify`, `okstra-pr-gen`, `okstra-user-response`).
+- Plugin manifest: [`../../.claude-plugin/plugin.json`](../.claude-plugin/plugin.json) — referenced by the supplementary `npx skills@latest add Devonshin/okstra` channel. Use `npx okstra@latest install` for normal setup. The plugin manifest exposes only the thirteen user entry points (`okstra-setup`, `okstra-brief-gen`, `okstra-run`, `okstra-manager`, `okstra-memory`, `okstra-inspect`, `okstra-rollup`, `okstra-usage`, `okstra-schedule-gen`, `okstra-container-build`, `okstra-graphify`, `okstra-pr-gen`, `okstra-user-response`).
 - Installation location: `~/.claude/skills/<name>/SKILL.md` or `~/.agents/skills/<name>/SKILL.md`.
 - Release procedure: [`../../RELEASING.md`](../RELEASING.md) — npm publish flow and release-please / manual fallback.
 
@@ -194,9 +195,46 @@ Task identity, paths, and workflow state are not stored in per-process environme
 | latest task pointer | `<PROJECT_ROOT>/.okstra/discovery/latest-task.json` |
 | run inputs | `<run-dir>/manifests/run-inputs-<task-type>-<seq>.json` |
 | run path hints / seq | `<run-dir>/manifests/run-context-<task-type>-<seq>.json` |
+| approved implementation design assessment | `<implementation-planning-run>/reports/final-report-implementation-planning-<seq>.data.json` |
+| AI-prepared design request | `<implementation-planning-run>/design-prep-requests/design-prep-request-<seq>-PREP-<NNN>.md` |
+| confirmed design input | `<implementation-planning-run>/design-prep-inputs/design-prep-input-<seq>-PREP-<NNN>-r<revision>-<uuid>.md` |
 | run history | `<task-root>/history/timeline.json` |
 | global indexes | `~/.okstra/{active,recent}.jsonl`, `~/.okstra/projects/<id>/{index.jsonl, meta.json}` |
 
+### Implementation design-preparation flow
+
+Planning owns the immutable assessment, while Okstra and the user own separate sidecars. This separation lets the AI prepare a concrete proposal before asking for input without turning a later response into an edit of the approved report.
+
+```text
+implementation-planning Phase 6
+  └─ final-report *.data.json
+       ├─ ready / provisional / blocked / not-applicable
+       └─ mode=no-design-inputs for a plan with no detected design surface
+                    │
+                    ▼ Phase 7
+       design-prep-requests/ (Okstra-owned, deterministic)
+                    │
+                    ▼ okstra design-prep or wizard confirmation
+       design-prep-inputs/ (user-owned, append-only)
+                    │
+                    ▼ implementation stage preflight
+       proceed ── inject effective proposal and working assumptions
+       wait_for_input ── stop before stage worktree and consumer creation
+       replan ── stop before stage worktree and rerun planning
+```
+
+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.
+
+### 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.
@@ -256,7 +294,7 @@ The standard `okstra` workflow applies the following team contract consistently
 - The main Claude is always the `Claude lead` and operates in synthesis-only mode.
 - The default required worker roles are `Claude worker`, `Codex worker`, and `Report writer worker`. `Antigravity worker` is optional and is included as required only when explicitly named by `--workers` or the profile's `- Workers:` section.
 - `Report writer worker` focuses on report structure and evidence organization, but `Claude lead` remains the final synthesis owner.
-- The default model contract is computed from central defaults. Fallbacks are `Claude lead`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.6`, and `Antigravity worker`=`auto` (when opted in). Without a separate override, `Report writer worker` follows the `Claude lead` model (therefore `opus` by default).
+- The default model contract is computed from central defaults. Fallbacks are `Claude lead`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.6-sol`, and `Antigravity worker`=`auto` (when opted in). Without a separate override, `Report writer worker` follows the `Claude lead` model (therefore `opus` by default).
 - Because `Antigravity worker` is optional, it is attempted only in runs where it is explicitly included.
 - Before the final judgment, each required role in the current run's worker roster must have either a result or an explicit terminal status (`completed`, `timeout`, `error`, `not-run`).
 - Every attempted worker (`completed`, `timeout`, `error`) must have an assigned worker prompt history file under the current run's `prompts/` directory.
@@ -354,7 +392,7 @@ Common constraints:
 - **Isolation of single-stage final-verification run artifacts (concurrent parallelism)**: Single-stage `final-verification` (`--stage <N>`) also isolates run artifacts under `runs/final-verification/stage-<N>/`, like implementation, with independent sequences per stage, and appends `-fv-s<N>` to the team name. The `-fv-` delimiter prevents collisions with the same stage's implementation team (`-s<N>`) and with the default whole-task verification name. Thus, final-verification for multiple stages can run concurrently without mixing state, worker results, reports, or teams. It does not create a new worktree; it reuses the corresponding implementation stage worktree from the registry read-only and therefore does not reserve a registry stage key. The `-fv-s<N>` suffix on the `teamName` label is only for audit/display distinction. The actual team is the per-session implicit team (`session-<leadSid>`), so the pre-v2.1.178 hard failure caused by a `TeamCreate` name collision no longer occurs. Whole-task verification (empty stage value) retains the existing flat `runs/final-verification/` structure.
 - Every phase except `implementation` and `release-handoff` prohibits source-code edits, builds, migrations, deployments, and other state-mutating commands (`final-verification` permits read-only test commands only). `implementation` allows edits/commits only within the approved plan's file list; `git push`, publish, deploy, real migration, and third-party write APIs remain prohibited. `release-handoff` does not modify source code and executes only the commit / push / PR commands selected by the user in the menu (force push, direct push to the base branch, hook bypass, and release publication remain prohibited).
 - Even if the user says something like "continue to the next step," that statement alone does not automatically begin the next phase. The next phase begins only with a new `okstra.sh` execution.
-- **Authority & permissions assumption (shared by every task type and `okstra-schedule`)**: Assume that the user and team have full authority and approval authority for every anticipated action. Do not include external approvals, third-party access, role/IAM permissions, organizational sign-off, legal/security review, vendor coordination, or questions about whether permission is held in routing decisions, missing inputs, clarification questions, risks, dependencies, open questions, or effort/day estimates. Internal okstra phase handoffs such as the `approved:` frontmatter in `implementation-planning` are gates the user can approve immediately and are unaffected. Forbidden `implementation` actions such as `git push`, production deployment, and shared-DB migration also remain prohibited for **safety reasons**, not permission reasons.
+- **Authority & permissions assumption (shared by every task type and `okstra-schedule-gen`)**: Assume that the user and team have full authority and approval authority for every anticipated action. Do not include external approvals, third-party access, role/IAM permissions, organizational sign-off, legal/security review, vendor coordination, or questions about whether permission is held in routing decisions, missing inputs, clarification questions, risks, dependencies, open questions, or effort/day estimates. Internal okstra phase handoffs such as the `approved:` frontmatter in `implementation-planning` are gates the user can approve immediately and are unaffected. Forbidden `implementation` actions such as `git push`, production deployment, and shared-DB migration also remain prohibited for **safety reasons**, not permission reasons.
 - Detailed phase rules are defined in `prompts/profiles/<task-type>.md`, whose body is rendered unchanged into `instruction-set/analysis-profile.md`.
 
 ### Information transfer between phases
@@ -403,7 +441,7 @@ A sidetrack entry point that is not a formal member of `PHASE_SEQUENCE`. It supp
 
 ### requirements-discovery fan-out
 
-For mixed or multi-item requests, requirements-discovery splits the request into packets by domain (the five-value work-category enum) and publishes them to `runs/requirements-discovery/fan-out/unit-*.md`. Each packet becomes a new task key through `okstra-run --task-brief <path>`. The dependency topological order is recorded in `index.md`, and okstra-schedule owns the integrated schedule after task creation. okstra-brief-gen is not involved in this path. Validation: `validators/validate_fanout.py` (validate-run hook).
+For mixed or multi-item requests, requirements-discovery splits the request into packets by domain (the five-value work-category enum) and publishes them to `runs/requirements-discovery/fan-out/unit-*.md`. Each packet becomes a new task key through `okstra-run --task-brief <path>`. The dependency topological order is recorded in `index.md`, and okstra-schedule-gen owns the integrated schedule after task creation. okstra-brief-gen is not involved in this path. Validation: `validators/validate_fanout.py` (validate-run hook).
 
 ### Worktree preview at the confirm step
 
@@ -568,7 +606,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>
@@ -744,7 +782,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`, 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`/`Report writer worker`=`opus`, `Claude worker`=`opus`, `Codex worker`=`gpt-5.6-sol`, 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

@@ -46,6 +46,7 @@
   - [Installation (global wrapper)](#install-global-wrapper)
   - [Common commands](#common-commands)
   - [`okstra` Node CLI — introspection subcommands](#okstra-node-cli--introspection-subcommands)
+    - [`okstra design-prep`](#okstra-design-prep)
   - [Live-log sidecar](#live-log-sidecar)
 
 ---
@@ -284,7 +285,7 @@ Use it to:
 Interpretation rules:
 
 - The lead and analysis workers read the compact intake (`active-run-context`, `analysis-packet.md`) first, so the directive propagates without separate work. `analysis-material.md` is a fallback when the packet is insufficient or source citations must be verified.
-- A skill must give the user prompt **precedence** over its own contract—for example, the "Directive override (highest priority)" section of the `okstra-schedule` skill. When a heuristic is overridden, the result document states that fact in one line.
+- A skill must give the user prompt **precedence** over its own contract—for example, the "Directive override (highest priority)" section of the `okstra-schedule-gen` skill. When a heuristic is overridden, the result document states that fact in one line.
 
 Example:
 
@@ -342,7 +343,7 @@ The Codex worker (`--workers codex`, `--codex-model`) and Codex lead runtime are
 
 > Every `--*-model` flag accepts only aliases registered in the provider mappings in `scripts/okstra_ctl/models.py`. An unregistered value is immediately rejected with `UnknownModelError`, preventing a contract violation where the manifest's `modelExecutionValue` differs from the actual execution value. Allowed values:
 > - Claude (`--lead-model` / `--claude-model` / `--report-writer-model`): `fable`, `fable-5`, `claude-fable-5`, `opus`, `opus-4-8`, `claude-opus-4-8`, `opus-4-7`, `claude-opus-4-7`, `opus-4-6`, `claude-opus-4-6`, `sonnet`, `sonnet-4-6`, `claude-sonnet-4-6`, `haiku`, `haiku-4-5`, `claude-haiku-4-5`, `claude-haiku-4-5-20251001`
-> - Codex (`--codex-model`): `gpt-5.6`, `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex`, `gpt-5.2`, `codex-auto-review`
+> - Codex (`--codex-model`): `gpt-5.6-sol`, `gpt-5.6`, `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex`, `gpt-5.2`, `codex-auto-review`
 > - Antigravity (`--antigravity-model`): `gemini-3.1-pro` (default), `gemini-3.5-flash`, and the space-separated aliases `gemini 3.1 pro` / `gemini 3.5 flash`. The antigravity worker uses the `agy` CLI to run Gemini-family models, so model IDs retain the `gemini-*` form.
 
 ### `--claude-model`
@@ -358,7 +359,7 @@ When omitted, it uses the central default `OKSTRA_DEFAULT_LEAD_MODEL`, falling b
 ### `--codex-model`
 
 Selects the model used by the `Codex worker`.
-When omitted, it uses the central default `OKSTRA_DEFAULT_CODEX_MODEL`, falling back to `gpt-5.6`.
+When omitted, it uses the central default `OKSTRA_DEFAULT_CODEX_MODEL`, falling back to `gpt-5.6-sol`.
 
 ### `--antigravity-model`
 
@@ -384,7 +385,7 @@ Fallback defaults are:
 - `Claude lead`: `opus`
 - `Report writer worker`: `opus`
 - `Claude worker`: `opus`
-- `Codex worker`: `gpt-5.6`
+- `Codex worker`: `gpt-5.6-sol`
 - `Antigravity worker`: `auto`
 - Implementation executor: `claude`, so the default is `Claude executor`.
 
@@ -394,7 +395,7 @@ Selects the provider that performs the Executor role for `--task-type implementa
 
 - Default: `OKSTRA_DEFAULT_EXECUTOR` → fallback `claude`.
 - The Executor is the **only worker allowed to mutate project files** in this run. The other two providers are dispatched as strict read-only verifiers in the same run.
-- The Executor reuses the provider's worker model flag. With `--executor codex`, its model comes from `--codex-model`, default `gpt-5.6`; with `--executor antigravity`, it comes from `--antigravity-model`, default `auto`.
+- The Executor reuses the provider's worker model flag. With `--executor codex`, its model comes from `--codex-model`, default `gpt-5.6-sol`; with `--executor antigravity`, it comes from `--antigravity-model`, default `auto`.
 - All three Claude, Codex, and Antigravity verifiers are always dispatched regardless of the Executor provider. Even the verifier using the same provider runs in a separate CLI session with isolated context, preserving the self-review safeguard.
 - Codex and Antigravity mutate files through each CLI's auto-edit mode, for example `codex exec --sandbox workspace-write`, without passing through Claude-side Edit/Write tools. Mutations occur in the task worktree described below. Both wrappers—`scripts/okstra-codex-exec.sh` and `scripts/okstra-antigravity-exec.sh`—receive the worktree path as their fourth positional argument and forward it through `--add-dir` for Codex or `--include-directories` for Antigravity. Without it, the Codex `workspace-write` sandbox rejects worktree writes with EPERM.
 - **Claude Executor cwd handling**: Claude's Bash tool has no per-call cwd argument and inherits the lead session cwd. To run cwd-sensitive toolchains such as `cargo`, `npm`, `pnpm`, `bun`, `pytest`, `make`, or `go` inside the worktree, prefix the invocation with `cd {{EXECUTOR_WORKTREE_PATH}} && <cmd>`. Keep `cd` as the leading token in a single Bash call so Claude Code permission auto-allow works; do not wrap it in `bash -lc "..."` or `bash -c "..."`, which hides `cd` and causes a permission prompt on every call. Prefer a tool's working-directory option—such as `git -C <path>`, `cargo --manifest-path`, or `pytest --rootdir`—over a `cd && ` chain. Edit/Write/Read tools already use absolute paths and need no cwd handling. This rule applies only to the Claude Executor; the Codex and Antigravity wrappers inject cwd.
@@ -638,9 +639,15 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra manager <init\|discover-projects\|new\|task>` | Public CLI for grouping cross-project okstra tasks into manager-owned context. `new project`, `new task-group`, and `new task` create manager plans; `task assign`, `task note`, `task sync`, `task status`, and `task run` manage per-project assignments and snapshots. `new project --project-root` accepts only existing directories and performs setup-equivalent registration only if `.okstra/project.json` is absent. Public documentation uses the full `project-id:task-group:task-id` child task key; when child task IDs differ within the same manager task, select the exact child with `--child-task-id`. `task run` does not execute the child lead directly; it returns `prepared` launch metadata/event and a child launch-context packet as JSON |
 | `okstra rollup [--task-group <group>] [--project-root <dir>] [--cwd <dir>]` | Read-only backend for the okstra-rollup skill. For every catalog task, or one task group, it emits JSON with per-task run counts, raw duration in ms, error counts, latest report paths, group totals, and status/category/phase distributions. Omitting `--task-group` targets the whole project catalog. The caller skill formats raw ms as HH:MM:SS and synthesizes report prose. Use the `okstra inspect` family for a single-task drill-down |
 | `okstra usage-report [--days <positive-int>] [--project-root <dir>] [--cwd <dir>] [--json]` | Read-only backend for the okstra-usage skill. Defaults to the whole current project's last 30 days and emits task-type run coverage, raw/billable tokens, known USD cost, CPU-sum milliseconds, wall-clock milliseconds, unavailable reason counts, and unmatched pricing models |
+| `okstra recap <assemble\|record\|note> <task-root\|task-key> …` | Backend for the okstra-inspect `recap` facet. `assemble` is read-only and prints a JSON summary of phase transitions across a task's runs. `record --kind <summary\|qa> --mode <artifact\|code> --answer <text> [--question <text>] [--citation <path:line> …]` appends one line to `<task-root>/recap/recap-log.jsonl` and never mutates other artifacts. `note --kind <verification-evidence\|decision-draft\|analysis-note> --slug <topic> --purpose <text> --scope-note <text> (--body <markdown>\|--body-file <path>)` writes an agent-authored note to `<task-root>/notes/` and prints its path plus the `--clarification-response` argument for feeding it into a later run |
+| `okstra user-response <list\|show\|write> …` | Backend for the `/okstra-user-response` skill: answer a task's open clarification questions in-session and write the response sidecar. `list --home <dir> --project <id> [--limit <n>]` finds reports with open questions; `show --report <md>` reads one report's questions; `write --report <md> --answers <json> [--approval <json>] [--task-key <key>]` writes the sidecar. Each answer carries a `disposition` of `answer` or `reframe`; a `reframe` is carried into the next run as a re-scoped brief. JSON output; exit 0 ok / 1 error |
+| `okstra pr <template\|branches\|gen> …` | Backend for the okstra-pr-gen skill. Git-only—no project registration required. `template list\|show <name\|default>\|add --name <name> (--content <text>\|--file <path>)\|path` manages PR body templates under `~/.okstra/template/pr/` (bundled fallback `src/commands/pr/default.md`); `branches` recommends a base branch; `gen --base <ref> [--template <name\|default>]` emits a JSON bundle of the template plus `<base>..HEAD` commits and `<base>...HEAD` diffstat |
 | `okstra migrate [--apply] [--cwd <dir>] [--quiet]` | One-time migration of the project artifact root from `.project-docs/okstra/` to `.okstra/`. It is a dry run by default; `--apply` performs the move with `git mv` in a Git worktree, removes an empty `.project-docs/`, and synchronizes the `<PROJECT>/CLAUDE.md` import line, `.gitignore`, the project's rows in `~/.okstra/{recent,active}.jsonl`, and `~/.okstra/worktrees/registry.json`. It exits 1 if `.okstra/` already exists or the legacy directory is absent. Scheduled for removal by the end of v0.x |
 | `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 |
@@ -649,11 +656,46 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra codex-dispatch --project-root <dir> --run-manifest <path> [--workers codex,antigravity,report-writer]` | Read a run manifest prepared by `codex-run` and execute the Codex-side supported worker subset. Without `--workers`, unsupported roster members such as `claude` are skipped; explicitly requesting one fails. The report writer requires opt-in with `--enable-codex-report-writer --report-writer-codex-model <model>`. On success, it automatically performs token-usage substitution, HTML view rendering, follow-up task-stub generation, and run validation |
 | `okstra team dispatch --project-root <dir> --run-manifest <path> [--workers <csv>] [--jobs-file <path>] [--dry-run]` / `okstra team await --project-root <dir> --run-manifest <path> [--json]` / `okstra team teardown --project-root <dir> --run-manifest <path> [--dry-run] [--json]` | Read a `leadRuntime=external` run manifest and dispatch, await, or tear down tmux-pane workers. If a tmux pane cannot be created, gracefully degrade to the CLI wrapper and record the fallback in `workerDispatches[].degradedFrom` |
 | `okstra render-views <final-report.md>` | Phase 7 step 1.5: deterministically create a human-facing self-contained sibling `*.html` view from one final-report Markdown file after token substitution. The source Markdown is unchanged. The Node delegation wrapper calls `scripts/okstra-render-report-views.py`; `validators/validate-report-views.py` verifies form-control placement, absence of external URLs, stale source digests, and Response ID parity |
+| `okstra design-prep <list\|show\|write>` | Review AI-prepared implementation design requests, inspect their effective confirmed response, or append a confirmed user/wizard response without editing the planning report |
 | `okstra wizard <init\|step\|render-args\|confirmation\|outcome> --state-file <path>` | Interactive input state machine for okstra-run, implemented by `okstra_ctl.wizard`. Seed a state file with `init`, then repeatedly call `step --answer <val>` to receive the next `Prompt` JSON. `--answer` is **required**; use `--no-submit` to peek at the next prompt without submitting a response. `render-args` returns the final `render-bundle` argument map, and `confirmation` returns the user echo block. On a completed wizard, `outcome` returns `renderArgs`, `persistActions`, and `confirmationText` together; project/global release-handoff PR-template persistence appears as `persistActions[].command == "config.set"`. For an `implementation` task type, `stage_pick` follows `approved_plan_pick` and selects the stage before `executor_pick`. The brief step appears only for entry task types—requirements-discovery, error-analysis, and improvement-discovery. Downstream phases automatically carry the manifest brief, with a three-option `brief_carry` fallback when none is registered; `release-handoff` has no brief and enters multi-select `handoff_stage_pick` for eligible stage groups or the whole task |
 | `okstra token-usage ...` | Wrap the installed `okstra-token-usage.py` to collect and substitute run token usage. Session JSONL is incrementally scanned by default through a byte-cursor cache at `$OKSTRA_HOME/cache/token-usage/`; `--no-cache` bypasses the cache and forces a full rescan as an accuracy fallback |
 
 > Every subcommand is wired to `PYTHONPATH` and `~/.okstra/lib/python` by the Python helper (`src/lib/python-helper.mjs`) spawned by `bin/okstra`. When invoking `python3 -m okstra_ctl.*` directly, you must configure `PYTHONPATH` yourself.
 
+#### `okstra design-prep`
+
+Use these commands after an `implementation-planning` report has prepared concrete domain, schema, interface, lifecycle, rollout, or manual-test input. `show` and `write` accept the Markdown report path or its `.data.json` sibling.
+
+```bash
+okstra design-prep list [--project-root <path>] [--report <path>]
+okstra design-prep show --report <path> [--item PREP-001]
+okstra design-prep write --report <path> --item PREP-001 \
+  --decision <accept-draft|modify-draft|reject-draft|defer> \
+  [--overrides '<json-object>'] [--notes <text>] --confirmed
+```
+
+- `list` returns `{"reports": [<snapshot-summary>, ...]}`. With `--report`, it reads only that report; otherwise it discovers planning reports below the resolved project root.
+- `show` without `--item` returns `report`, `outcome`, `reason`, `warnings`, and all item views. With `--item`, it returns `report`, the full AI-prepared `item`, `effectiveInput`, `assessmentFingerprint`, and `requestPath`.
+- `write` returns `path`, `revision`, `inputId`, and `assessmentFingerprint`. The path is a new `design-prep-inputs/...-r<revision>-<uuid>.md` sidecar; it never mutates the report or an earlier response.
+- `--overrides` must be a JSON object and is accepted only with `modify-draft`. `reject-draft` requires a non-empty note.
+- `--confirmed` is required for every write. Without it, no revision, UUID, timestamp, or file is allocated.
+
+Successful commands and `--help` exit `0`. Contract, path, JSON, or confirmation errors exit `1` and write a `design-prep:` message to stderr. Argument-parser errors such as a missing required flag or unknown decision exit `2`. Successful command stdout is JSON.
+
+The selected implementation stage resolves only items that cite it in `stageRefs`:
+
+| Effective state or response | Preflight result |
+|---|---|
+| `ready`, `not-applicable`, or `no-design-inputs` | `proceed` |
+| `provisional` with no response, `defer`, `accept-draft`, or a non-triggering `modify-draft` | `proceed`; inject the effective proposal and working assumption into the executor prompt |
+| `provisional` with `reject-draft` | `wait_for_input` |
+| `provisional` with a modified `replanTriggerFields` path | `replan` |
+| `blocked` with no response, `defer`, or `reject-draft` | `wait_for_input` |
+| `blocked` with `accept-draft` or `modify-draft` | `replan`, because the approved plan must incorporate the newly authorized decision |
+| markerless legacy plan | `proceed` with `legacy-unassessed` warning; no report rewrite |
+
+Both `wait_for_input` and `replan` stop before a stage worktree is provisioned and before a `status:"started"` consumer row is appended. Other stages whose `stageRefs` do not include the unresolved item remain eligible.
+
 ### Live-log sidecar
 
 For every dispatch, the Codex and Antigravity wrappers create a `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` sidecar and mirror stdout and stderr into it. When the lead runs inside tmux, the wrapper automatically splits a `tail -F` pane. The trace pane title is `<cli>-<role>-<pid>-tail`, and the caller/worker pane title is `<cli>-<role>-<pid>`; the wrapper PID distinguishes concurrent dispatches with the same role. Split trace panes are tagged with the `@okstra_trace_run=<RUN_DIR>` pane user option, and tmux-pane backend worker-compute panes with `@okstra_worker_run=<RUN_DIR>`. When Claude receives `/exit`, the `SessionEnd` hook automatically cleans them up within `$CLAUDE_PROJECT_DIR/.okstra/` scope by running `okstra-trace-cleanup.sh --reap`. When the lead calls the same script with `--run-dir <RUN_DIR>`, it removes the run's trace panes, worker-compute panes, and dispatched worker-agent panes within the lead-session scope, while excluding the lead's own pane. Worker-agent titles include `claude-worker`, `codex-worker`, `antigravity-worker`, `report-writer-worker`, implementation role titles, and FleetView teammate prefixes `✳ ` / `⠂ `. Before entering a new phase, the lead runs `okstra-trace-cleanup.sh --run-dir <RUN_DIR>` once to clear stale panes.

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` | [`skills/okstra-schedule.md`](skills/okstra-schedule.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`
@@ -56,5 +59,8 @@
 - `okstra-inspect`
 - `okstra-rollup`
 - `okstra-usage`
-- `okstra-schedule`
+- `okstra-schedule-gen`
 - `okstra-container-build`
+- `okstra-user-response`
+- `okstra-graphify`
+- `okstra-pr-gen`