okstra 0.122.0 → 0.123.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.

package/docs/architecture/storage-model.md

@@ -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,36 @@ 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.
+
 ### Concurrency
 
 Two types of file locks handle all concurrency.
@@ -256,7 +284,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 +382,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 +431,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
 
@@ -744,7 +772,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,13 @@ 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 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 +654,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

@@ -23,7 +23,7 @@
 | 상태, 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) |
 | 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) |
+| 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) |
 
@@ -56,5 +56,5 @@
 - `okstra-inspect`
 - `okstra-rollup`
 - `okstra-usage`
-- `okstra-schedule`
+- `okstra-schedule-gen`
 - `okstra-container-build`

package/docs/for-ai/skills/okstra-rollup.md

@@ -29,7 +29,7 @@
 사용하지 않는다:
 
 - 단일 task의 report/시간/에러/recap → `okstra-inspect` (report / time / errors / recap facet).
-- 미래 작업 계획표(non-done task의 클라이언트용 일정) → `okstra-schedule`. rollup은 과거 run 결과를 모으는 **회고형**이고, schedule은 앞으로의 계획을 짜는 **전망형**이다.
+- 미래 작업 계획표(non-done task의 클라이언트용 일정) → `okstra-schedule-gen`. rollup은 과거 run 결과를 모으는 **회고형**이고, schedule은 앞으로의 계획을 짜는 **전망형**이다.
 - 실제 phase 실행 → `okstra-run`.
 
 ## Preflight

package/docs/for-ai/skills/{okstra-schedule.md → okstra-schedule-gen.md}

@@ -1,15 +1,15 @@
-# okstra-schedule AI Manual
+# okstra-schedule-gen AI Manual
 
 ## 원천
 
-- 스킬 원문: [`skills/okstra-schedule/SKILL.md`](../../../skills/okstra-schedule/SKILL.md)
+- 스킬 원문: [`skills/okstra-schedule-gen/SKILL.md`](../../../skills/okstra-schedule-gen/SKILL.md)
 - schedule 템플릿: [`templates/reports/schedule.template.md`](../../../templates/reports/schedule.template.md)
 - schedule validator: [`validators/validate-schedule.py`](../../../validators/validate-schedule.py)
 - workStatus inference 참조: [`skills/okstra-inspect/SKILL.md`](../../../skills/okstra-inspect/SKILL.md)
 
 ## 목적
 
-`okstra-schedule`은 task-group 안의 non-done task들을 모아 클라이언트용 작업 일정 Markdown을 만든다. 실행 task를 시작하는 스킬이 아니며, 단일 task 분석도 아니다.
+`okstra-schedule-gen`은 task-group 안의 non-done task들을 모아 클라이언트용 작업 일정 Markdown을 만든다. 실행 task를 시작하는 스킬이 아니며, 단일 task 분석도 아니다.
 
 출력 위치:
 

package/docs/project-structure-overview.md

@@ -182,7 +182,8 @@ Runtime/install asset changes follow this checklist:
 | `spawn-followups`, `error-log` | `src/commands/execute/*.mjs` | Follow-up task bundle creation and run error-log append helpers |
 | `memory` | `src/commands/memory/memory.mjs` | Store/find global conversation memory under `~/.okstra/memory-book` |
 | `pr` | `src/commands/pr/pr.mjs` | `okstra pr <template\|branches\|gen>` — PR body template store under `~/.okstra/template/pr/` (bundled fallback `src/commands/pr/default.md`), base-branch recommendation, and the `gen` JSON bundle (template + `<base>..HEAD` commits + `<base>...HEAD` diffstat) backing the okstra-pr-gen skill. Git-only; no project registration required |
-| `recap` | `src/commands/inspect/recap.mjs` | `okstra recap <assemble\|record>` Node wrapper backing the okstra-inspect `recap` facet |
+| `recap` | `src/commands/inspect/recap.mjs` | `okstra recap <assemble\|record\|note>` Node wrapper backing the okstra-inspect `recap` facet — `assemble` 는 read-only 위상 전이 요약, `record` 는 `recap/recap-log.jsonl` 1행 append, `note` 는 `notes/` 에 agent 작성 노트를 쓰고 후속 run 용 `--clarification-response` 인자를 출력 |
+| `stage-map` | `src/commands/inspect/stage-map.mjs` | `okstra stage-map <task-key>` — task 의 implementation-planning Stage Map 을 JSON 으로 노출 (`stages[].{stage_number,title,depends_on,step_count}` + consumer state 기반 `doneStages[]`). Stage Map 이 없으면 `stages: []`. `okstra-schedule-gen` 이 stage 단위와 의존성 폐포를 유도하는 read-side 근거 |
 | `rollup` | `src/commands/inspect/rollup.mjs` | `okstra rollup` thin shim into `scripts/okstra_ctl/rollup.py` — read-only cross-task roll-up backing the okstra-rollup skill |
 | `usage-report` | `src/commands/inspect/usage-report.mjs` | `okstra usage-report` thin shim into `scripts/okstra_ctl/usage_report.py` — read-only project usage snapshot backing the okstra-usage skill |
 | `container` | `src/commands/inspect/container.mjs` | `bin okstra container` thin shim into `scripts/okstra_ctl/container.py` for the okstra-container-build skill |
@@ -332,7 +333,7 @@ Optional (v1.0 하위호환) 최상위 키:
 | `okstra-inspect` | yes | Unified read-side — sub-commands `status` (lifecycle + workStatus), `history` (past runs / re-run / resume), `report` (find final-report), `time` (elapsed-time breakdown), `logs` (wrapper log inventory + cleanup), `cost` (task bundle context/read cost) |
 | `okstra-rollup` | yes | Cross-task roll-up — aggregate runs/time/errors across a task-group (or whole project) and synthesize a digest from the report files |
 | `okstra-usage` | yes | Read-only project usage snapshot — aggregate recent run coverage, tokens, known cost, CPU, and wall-clock time by task type (default: 30 days) |
-| `okstra-schedule` | yes | Generate task-group schedule |
+| `okstra-schedule-gen` | yes | Generate task-group schedule |
 | `okstra-container-build` | yes | Non-linear deploy tool — deploy a verified task's code as a docker compose group and watch each container (sub-commands `up` / `status` / `logs` / `stop-watcher` / `down`) |
 | `okstra-graphify` | yes | Knowledge graph over the project's own `.okstra/` memory — final reports, `decisions/*.md`, `glossary.md`; scope restricted to `.okstra/`, output under `.okstra/graph/` (sub-commands `build` / `query` / `path` / `explain` / `mcp` / `wiki`) |
 | `okstra-pr-gen` | yes | Register PR body templates under `~/.okstra/template/pr/` and generate a PR description from a branch diff (drives `okstra pr template` / `branches` / `gen`). **Global skill** — needs a Git repo, not `<PROJECT_ROOT>/.okstra/project.json` |

package/docs/task-process/implementation-planning.md

@@ -6,7 +6,7 @@
 - [2. okstra-run wizard 흐름](#2-okstra-run-wizard-흐름)
 - [3. prepare_task_bundle 처리](#3-prepare_task_bundle-처리)
 - [4. lead 실행 흐름](#4-lead-실행-흐름)
-- [5. final report gate](#5-final-report-gate)
+- [5. design preparation과 final report gate](#5-design-preparation과-final-report-gate)
 - [6. 금지선](#6-금지선)
 - [7. 확인한 코드](#7-확인한-코드)
 
@@ -76,18 +76,38 @@ flowchart TD
 
 Plan-body verification은 Phase 5.5와 다른 queue를 쓴다. Phase 5.5는 worker finding을 검증하고, Phase 6 sub-step은 report-writer가 만든 consolidated plan body를 `P-*` plan item 단위로 다시 검증한다.
 
-## 5. final report gate
+## 5. design preparation과 final report gate
+
+lead는 Stage Map에서 domain contract, persistence schema, external interface, transaction/consistency, transformation mapping, lifecycle state machine, rollout/observability, manual user test surface를 결정적으로 탐지한다. report-writer는 사용자에게 빈칸부터 묻지 않고, 알려진 사실과 근거를 사용해 각 surface의 구체적인 AI 초안을 먼저 작성한다.
+
+`designPreparation.items[]`의 상태는 완성도를 강제로 한 단계에 고정하지 않는다.
+
+| 상태 | 의미 | implementation 진입 시 처리 |
+|---|---|---|
+| `ready` | 구현 계약이 planning snapshot 안에서 충분히 확정됨 | 해당 stage 진행 |
+| `provisional` | 되돌릴 수 있는 working assumption과 guardrail이 있어 지금 진행해도 안전함 | 해당 stage 진행, assumption을 executor prompt에 주입하고 지정한 review point에서 재확인 |
+| `blocked` | 안전한 기본값이 없고 외부 권한·비즈니스 정책·파괴적 변경 결정이 필요함 | 이 item의 `stageRefs`에 속한 stage만 input 대기 또는 replan |
+| `not-applicable` | detector가 찾은 surface가 이 stage에서는 별도 계약을 요구하지 않음 | 구체적인 사유를 남기고 진행 |
+
+탐지된 surface가 없고 interface/acceptance를 바꾸는 manual test input도 없으면 `mode: no-design-inputs`와 구체적인 사유를 쓴다. 따라서 간단한 작업에 형식적인 빈 문서를 만들 필요가 없다.
+
+`manual-user-test`는 planning 시점에 실행 방법을 완전히 고정하지 않아도 된다. 실제 diff를 보기 전에도 안전한 기본 절차가 있으면 `provisional`과 `ifStillOpen: follow-up`으로 진행하고, 구현 리포트가 실제 변경에 맞춘 `implementation.manualUserTest`를 최종 소유한다. 반대로 사용자만 제공할 수 있는 acceptance 방법 없이는 해당 stage를 안전하게 완료할 수 없을 때만 `blocked`를 사용한다.
+
+Phase 7은 `provisional`/`blocked` item마다 AI proposal이 채워진 `design-prep-requests/` 문서를 결정적으로 만든다. 사용자 또는 wizard가 초안을 승인·수정·거부·보류하면, 확인 이후에만 `design-prep-inputs/` 아래 새 revision sidecar를 append한다. 이 응답은 approved planning report를 수정하지 않는다.
+
+plan approval과 design-preparation 상태는 독립된 gate다. plan-body verification이 통과했다면 `blocked` item이 있어도 계획 자체는 승인할 수 있다. 실제 `implementation` preflight가 선택한 stage의 item만 해소하며, unrelated stage는 계속 진행한다.
 
 ```mermaid
 flowchart LR
     Options[Option Candidates] --> Matrix[Trade-off Matrix]
     Matrix --> Rec[Recommended Option]
-    Rec --> Steps[Stepwise Execution Order]
-    Steps --> Dep[Dependency / Migration Risk]
+    Rec --> Stages[Stage Map + Stage Exit/Validation]
+    Stages --> Prep[Implementation Design Preparation]
+    Prep --> Dep[Dependency / Migration Risk]
     Dep --> Val[Validation Checklist]
     Val --> Rb[Rollback Strategy]
     Rb --> Verify[Plan Body Verification]
-    Verify --> Approval[User Approval Request]
+    Verify --> Approval[YAML frontmatter approval]
     Approval --> Impl[Next run: implementation]
 ```
 
@@ -96,13 +116,18 @@ validator가 section heading의 영문 substring을 찾기 때문에 다음 문
 - `Option Candidates`
 - `Trade-off`
 - `Recommended Option`
-- `Stepwise Execution Order`
+- `Stage Map`
+- `Stage Exit Contract`
+- `Stage Validation`
 - `Dependency`
+- `Cross-Project Dependencies`
+- `Decision Drafts`
 - `Validation Checklist`
 - `Rollback`
-- `User Approval Request`
+- `Requirement Coverage`
+- `Implementation Design Preparation`
 
-approval marker는 top-of-report `User Approval Request` block의 `- [ ] Approved` line이다. 사용자가 `- [x] Approved`로 바꿔야 implementation run이 시작된다. `Blocks=approval` clarification row가 unresolved이면 approved marker가 있어도 implementation prepare에서 거부된다.
+approval은 YAML frontmatter의 `approved: true`와 선택한 `implementation-option`으로 기록한다. `Blocks=approval` clarification row가 unresolved이면 frontmatter가 승인 상태여도 implementation prepare에서 거부된다. design-preparation의 `blocked` 상태 자체는 `Blocks=approval`과 같지 않으며, 해당 stage의 implementation preflight에서만 작동한다.
 
 ## 6. 금지선
 
@@ -125,4 +150,3 @@ flowchart TD
 - [`scripts/okstra_ctl/render.py`](../../scripts/okstra_ctl/render.py)
 - [`validators/validate-run.py`](../../validators/validate-run.py)
 - [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)
-

package/docs/task-process/implementation.md

@@ -5,6 +5,7 @@
 - [1. 목적](#1-목적)
 - [2. okstra-run wizard 흐름](#2-okstra-run-wizard-흐름)
 - [3. runtime gate](#3-runtime-gate)
+  - [3.1 design-preparation preflight](#31-design-preparation-preflight)
 - [4. executor와 verifier](#4-executor와-verifier)
 - [5. stage와 consumers](#5-stage와-consumers)
 - [6. 산출물](#6-산출물)
@@ -61,6 +62,7 @@ sequenceDiagram
     P->>Stage: build Stage Lifecycle Snapshot
     P->>Reg: read active stage-key reservations
     P->>Stage: select exactly one ready stage
+    P->>Plan: resolve selected stage design preparation
     P->>WT: provision stage-N worktree + branch
     P->>QA: validate qaCommands deny-list
     P->>P: executor provider in resolved roster?
@@ -70,6 +72,20 @@ sequenceDiagram
 
 `--approve`는 Python runtime에 존재하지만 okstra-run wizard가 args로 내보내지 않는다. shell path에서는 `--approve`가 unchecked approval line을 flip하고 audit line을 붙인 뒤 같은 validation path를 탄다.
 
+### 3.1 design-preparation preflight
+
+stage 선택 직후, worktree provision과 `consumers.jsonl`의 `status:"started"` append 전에 approved plan의 design preparation을 해소한다. resolver는 선택한 stage가 `stageRefs`에 포함된 item만 읽으므로 다른 stage의 미확정 결정은 현재 run을 막지 않는다.
+
+| outcome | runtime 동작 |
+|---|---|
+| `proceed` | effective AI proposal, confirmed override, guardrail, provisional working assumption을 `DESIGN_PREP_CONTEXT`로 executor prompt에 주입하고 worktree를 만든다. |
+| `wait_for_input` | `stage <N> waits for design input: ...; <request paths>`로 중단한다. worktree와 started consumer row는 만들지 않는다. |
+| `replan` | `stage <N> requires implementation-planning rerun: ...`으로 중단한다. 새로 승인·수정된 결정이 planning snapshot 또는 Stage Map을 바꾸게 한다. |
+
+`ready`, `not-applicable`, `no-design-inputs`는 진행한다. `provisional`은 안전한 working assumption이 있으므로 응답이 없어도 진행할 수 있으며, non-triggering 승인/수정은 그 assumption과 override를 prompt에 명시한다. `blocked` 무응답은 해당 stage만 대기시키고, blocked 초안을 승인·수정한 경우에는 그 권한을 approved plan에 반영하도록 replan한다. markerless legacy plan은 report를 고치지 않고 `legacy-unassessed` warning과 함께 진행한다.
+
+`manual-user-test` input도 같은 유연한 상태를 사용한다. planning의 초안은 implementation이 실제 diff에 맞춰 검증 방법을 구체화하기 위한 seed이며, 최종 실행 방법의 SSOT는 implementation report의 `implementation.manualUserTest`다. planning sidecar를 final-verification이 직접 실행하지 않는다.
+
 ## 4. executor와 verifier
 
 ```mermaid
@@ -98,8 +114,10 @@ flowchart LR
     Snapshot --> Resolve{stage arg}
     Resolve -->|auto| Next[lowest ready<br/>not done/started/reserved]
     Resolve -->|number| Forced[selected stage]
-    Next --> Base[resolve stage base commit]
-    Forced --> Base
+    Next --> Prep{selected-stage<br/>design preflight}
+    Forced --> Prep
+    Prep -->|proceed| Base[resolve stage base commit]
+    Prep -->|wait / replan| Stop[stop before worktree<br/>and started consumer]
     Base --> WT[create/reuse stage worktree]
     WT --> Started[append consumer status=started]
     Started --> Run[implementation executes one selected stage]
@@ -134,6 +152,7 @@ final report에는 최소 다음이 필요하다.
 - verifier별 independent validation rerun result
 - `carry/stage-<N>.json` evidence sidecar와 `consumers.jsonl` started/done row
 - rollback verification
+- 실제 diff에 맞춰 확정한 `implementation.manualUserTest`와 실행 가능 여부
 - follow-up tasks table
 
 ## 7. 금지선

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.122.0",
+  "version": "0.123.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.122.0",
-  "builtAt": "2026-07-16T04:13:37.510Z",
+  "package": "0.123.0",
+  "builtAt": "2026-07-17T16:03:35.624Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/bin/lib/okstra/usage.sh

@@ -29,7 +29,7 @@ optional arguments:
                        (1) ancestor of cwd that contains .okstra/project.json,
                        (2) \`git rev-parse --show-toplevel\` from cwd. Errors out if neither resolves.
   --directive        Free-form user-supplied directive carried into the run as a "## Directive" section
-                       inside instruction-set/analysis-material.md. Lead, workers, and skills (e.g. okstra-schedule)
+                       inside instruction-set/analysis-material.md. Lead, workers, and skills (e.g. okstra-schedule-gen)
                        may treat this as a hard hint that overrides default heuristics. Use to express intent
                        like "render a Gantt even with single XL task" or "emphasize rollout risk".
   --fix-cycle <yes|no> When re-entering an entry phase (requirements-discovery / error-analysis /
@@ -90,7 +90,7 @@ options:
                       (Antigravity worker is optional; add \`antigravity\` explicitly, e.g. --workers claude,codex,antigravity,report-writer)
   --lead-model         Model for Claude lead. Default: OKSTRA_DEFAULT_LEAD_MODEL or opus
   --claude-model       Model for Claude worker. Default: OKSTRA_DEFAULT_CLAUDE_MODEL or opus
-  --codex-model        Model for Codex worker. Default: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.6
+  --codex-model        Model for Codex worker. Default: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.6-sol
   --antigravity-model       Model for Antigravity worker. Default: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or gemini-3.1-pro
   --report-writer-model
                       Model for report writer worker. Default: OKSTRA_DEFAULT_REPORT_WRITER_MODEL or lead model default
@@ -124,7 +124,7 @@ model defaults:
   Claude lead: OKSTRA_DEFAULT_LEAD_MODEL or opus
   Report writer worker: OKSTRA_DEFAULT_REPORT_WRITER_MODEL or Claude lead default
   Claude worker: OKSTRA_DEFAULT_CLAUDE_MODEL or opus
-  Codex worker: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.6
+  Codex worker: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.6-sol
   Antigravity worker: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or gemini-3.1-pro
   Implementation executor: OKSTRA_DEFAULT_EXECUTOR or claude (one of: claude | codex | antigravity)