okstra 0.205.1 → 0.206.0

package/docs/task-process/common-flow.md

@@ -1,173 +0,0 @@
-# okstra-run common flow
-
-## Index
-
-- [1. One-line summary](#1-one-line-summary)
-- [2. Where the two entrypoints meet](#2-where-the-two-entrypoints-meet)
-- [3. wizard input collection flow](#3-wizard-input-collection-flow)
-- [4. render-bundle and prepare_task_bundle](#4-render-bundle-and-prepare_task_bundle)
-- [5. Okstra lead phase 1-7](#5-okstra-lead-phase-1-7)
-- [6. artifact layout](#6-artifact-layout)
-- [7. Common branching rules](#7-common-branching-rules)
-- [8. Inconsistencies to watch for](#8-inconsistencies-to-watch-for)
-
-## 1. One-line summary
-
-`okstra-run` is not a "skill that decides questions on its own" but a thin loop that relays the `okstra wizard` JSON state machine to the user. Once input collection finishes, it calls `okstra render-bundle`, and that command builds the task bundle through `python3 -m okstra_ctl.run --render-only`. After that, the current Claude Code, Codex, or Antigravity session switches over to the host-native `Okstra lead`.
-
-## 2. Where the two entrypoints meet
-
-```mermaid
-flowchart LR
-    subgraph InSession["supported host session"]
-        A[okstra-run skill] --> B[okstra wizard]
-        B --> C[okstra render-bundle<br/>forces --render-only]
-    end
-
-    subgraph Terminal["terminal path"]
-        D[scripts/okstra.sh] --> E[CLI parse / prompt / confirm]
-    end
-
-    C --> P[prepare_task_bundle()]
-    E --> P
-    P --> G[task bundle artifacts]
-    G --> H{launch mode}
-    H -->|render-only| I[current host reads lead prompt]
-    H -->|non-render-only| J[exec claude --session-id ...]
-```
-
-The common principle is that `prepare_task_bundle()` is the single authority for task bundle creation. Neither the wizard nor the shell wrapper duplicates the path computation, manifest creation, or worktree creation logic.
-
-## 3. wizard input collection flow
-
-```mermaid
-stateDiagram-v2
-    [*] --> VerifyRuntime: okstra ensure-installed / paths / check-project
-    VerifyRuntime --> NewState: okstra wizard new-state-file
-    NewState --> TaskPick: wizard init
-    TaskPick --> BriefPath: brand-new task
-    TaskPick --> TaskType: existing task
-    BriefPath --> TaskGroup: new task, brief accepted
-    TaskGroup --> TaskId
-    TaskId --> TaskType
-    TaskType --> BriefKeep: existing task with existing brief
-    BriefKeep --> BriefPath: change
-    BriefKeep --> BaseRef: keep
-    TaskType --> BaseRef: no active worktree
-    TaskType --> ImplementationExtras: implementation only
-    BaseRef --> ImplementationExtras: implementation only
-    BaseRef --> LeaderSession: non-implementation
-    ImplementationExtras --> LeaderSession
-    LeaderSession --> RoleSlots: one model screen per role
-    RoleSlots --> OptionalInputs: directive / related / clarification
-    OptionalInputs --> Confirm
-    Confirm --> EditTarget: Edit
-    EditTarget --> TaskType: rewind selected step
-    Confirm --> Done: Proceed
-```
-
-A new task receives its brief first. If the brief frontmatter has `task-group:` and `brief-id:`, the wizard shows the task group/id as recommended picks. An existing task shows the manifest's `workflow.nextRecommendedPhase.phase` as the recommended task-type, but only while that pointer's `status` is `ready`. Under any other status the recommended slot stays empty and the list falls back to rerunning `workflow.currentPhase` plus the full task-type choices. If an existing brief path exists it asks whether to keep or change it.
-
-## 4. render-bundle and prepare_task_bundle
-
-```mermaid
-sequenceDiagram
-    participant Skill as okstra-run skill
-    participant Node as okstra CLI
-    participant Py as okstra_ctl.run
-    participant FS as .okstra
-    participant Home as ~/.okstra
-
-    Skill->>Node: okstra wizard outcome
-    Node-->>Skill: { renderArgs: ..., persistActions: ... }
-    opt persistActions present
-        Skill->>Node: okstra config set ...
-    end
-    Skill->>Node: okstra render-bundle --... --render-only
-    Node->>Py: python3 -m okstra_ctl.run --render-only --...
-    Py->>Py: validate profile, brief, task-type gates
-    Py->>Home: reserve/reuse task worktree registry
-    Py->>FS: write run-context and instruction-set
-    Py->>FS: write task/run manifests, team-state, timeline, discovery
-    Py->>Home: record_start status=prepared
-    Py-->>Node: task root, instruction-set, rendered lead prompt
-    Node-->>Skill: stdout
-    Skill->>FS: read lead-execution-prompt.md
-```
-
-The Node shim for `render-bundle` is [`src/commands/execute/render-bundle.mts`](../../src/commands/execute/render-bundle.mts). This shim attaches the `--workspace-root`, `--render-only`, and runtime resolution arguments directly. As a result, on the okstra-run path the initial run status starts at `prepared` and the task status starts at `ready-for-lead`.
-
-## 5. Okstra lead phase 1-7
-
-```mermaid
-flowchart TD
-    P1[Phase 1<br/>task bundle intake] --> P2[Phase 2<br/>worker prompt preparation]
-    P2 --> P3[Phase 3<br/>resolve persisted runners]
-    P3 -->|native session| P4[Phase 4<br/>host-native dispatch]
-    P3 -->|CLI wrapper| P5[Phase 4<br/>provider CLI dispatch]
-    P4 --> C[Phase 5.5<br/>convergence]
-    P5 --> C
-    C --> P6[Phase 6<br/>report-writer synthesis]
-    P6 --> PV{implementation-planning?}
-    PV -->|yes| PBV[Plan-body verification]
-    PV -->|no| P7[Phase 7<br/>persist + validate]
-    PBV --> P7
-    P7 --> Done[final report + manifests updated]
-```
-
-The roles of the analysis workers and the report-writer are separated. `report-writer` is not a Phase 4/5 analysis worker but the Phase 6 final report author. Note, however, that `release-handoff` is a single-lead phase, so it deliberately does not follow this phase graph.
-
-## 6. artifact layout
-
-```mermaid
-flowchart TD
-    Root["<PROJECT_ROOT>/.okstra/tasks/<group>/<task>/"] --> IS[instruction-set/]
-    Root --> Runs[runs/<task-type>/]
-    Root --> Hist[history/timeline.json]
-    IS --> Profile[analysis-profile.md]
-    IS --> Brief[task-brief.md]
-    Runs --> Lead["prompts/lead-execution-prompt-*.md"]
-    Runs --> Man[manifests/run-manifest-*.json]
-    Runs --> Prompts[prompts/*-worker-prompt-*.md]
-    Runs --> Results[worker-results/*.md]
-    Runs --> Reports[reports/final-report-*.md<br/>reports/*.data.json<br/>reports/final-report-*.html]
-    Runs --> State[state/*.json]
-    Runs --> Status[status/final-status-*.json]
-    Runs --> ImplStage[implementation/stage-N/...]
-    Runs --> FvStage[final-verification/stage-N/...]
-    Runs --> Carry[implementation/carry/stage-N.json]
-    Runs --> Consumers[implementation-planning/consumers.jsonl]
-    Root --> Handoff[release-handoff-input.md]
-```
-
-`implementation` and single-stage `final-verification` isolate their run deliverables under `stage-<N>/`. The `implementation` carry sidecar and `consumers.jsonl` are cross-stage coordination ledgers, so they remain at the phase root. The runtime reads this ledger and the registry reservations as a Stage Lifecycle Snapshot to compute stage selection and handoff eligibility. `release-handoff` does not receive a brief; prepare generates `release-handoff-input.md`.
-
-`runtime/` is build output, so when you fix this flow you edit the sources `scripts/`, `skills/`, `agents/`, `prompts/`, `templates/`, `validators/` and refresh with `npm run build`.
-
-## 7. Common branching rules
-
-```mermaid
-flowchart TD
-    T[task-type selected] --> W{active worktree in registry?}
-    W -->|yes| Reuse[reuse existing worktree<br/>base-ref prompt skipped]
-    W -->|no| Base[ask base-ref<br/>validate with git rev-parse]
-    Base --> M[one screen per static role<br/>checkbox: models checked = instances<br/>single pick: fixed single role]
-    Reuse --> M
-    M --> O[directive / related / clarification]
-    O --> Special{release-handoff?}
-    Special -->|yes| PR[PR template override/scope]
-    Special -->|no| Confirm
-    PR --> Confirm
-```
-
-Launch selection is role slots and model refs. The wizard does not show a provider roster multi-pick and does not fork on `Use defaults / Customize` for workers. A multi-instance role is one checkbox screen whose checked models become the instances (the wizard renders `--role-count` from that number); on the CLI, omitting `--role-count` keeps each static role at its profile **recommended** count within `min..max`. Duplicate model refs in the same role are rejected. `--workers` remains a CLI compatibility input only.
-
-Worktree rules differ per phase. From `requirements-discovery` through `implementation-planning`, the task-key worktree is reused. `implementation` uses the task-key worktree as an anchor but does the actual execution isolated one stage at a time in a stage-key (`stage-<N>`) worktree and the `runs/implementation/stage-<N>/` deliverables. `final-verification --stage N` reuses that implementation stage worktree as a read target, and whole-task mode auto-integrates the stage commits into the task-key worktree and then builds the verification target. The Stage Lifecycle Snapshot is a read-side view that does not change this storage structure.
-
-## 8. Inconsistencies to watch for
-
-- The `okstra-run` wizard path passes only if the implementation approved plan already has an approval marker. `scripts/okstra.sh` has `--approve`, which can flip the checkbox with a CLI ack, but the current wizard `render_args()` has no `approve` flag.
-- `release-handoff` has no brief. Prepare cites the accepted final-verification report to build `release-handoff-input.md`, and the wizard's `handoff_stage_pick` or the CLI `--stages` fixes the whole-task/stage-group scope.
-- `release-handoff` is also a target for task worktree provisioning. A healthy handoff is safest when it reuses the implementation/final-verification results of the same task-key. Starting a new task creates a new worktree, which may be blocked at the profile's "an implementation commit must exist" entry gate.
-- `release-handoff` has no `Required workers:` block in its profile. The runtime also forces the worker roster to be empty.
-- No task-type starts the next lifecycle phase within a single run. "Proceed to the next step" is interpreted only as wrapping up the current phase's output.

package/docs/task-process/error-analysis.md

@@ -1,103 +0,0 @@
-# error-analysis process
-
-## Index
-
-- [1. Purpose](#1-purpose)
-- [2. okstra-run wizard flow](#2-okstra-run-wizard-flow)
-- [3. prepare_task_bundle handling](#3-prepare_task_bundle-handling)
-- [4. lead execution flow](#4-lead-execution-flow)
-- [5. Deliverables and prohibitions](#5-deliverables-and-prohibitions)
-- [6. Code reviewed](#6-code-reviewed)
-
-## 1. Purpose
-
-`error-analysis` analyzes a reported error or incident to organize the symptom, trigger, root-cause candidate, reproduction gap, and validation path. It is not the phase that produces the fix itself or an implementation design.
-
-## 2. okstra-run wizard flow
-
-```mermaid
-flowchart TD
-    Start[/okstra-run/] --> Common[common task identity flow]
-    Common --> Type[task-type = error-analysis]
-    Type --> Worktree{active worktree exists?}
-    Worktree -->|yes| RoleCount[role-count min..max<br/>omit uses recommended; skip if min==max]
-    Worktree -->|no| BaseRef[base-ref pick/text<br/>main recommended]
-    BaseRef --> RoleCount
-    RoleCount --> RoleModel[role-model provider/model per slot]
-    RoleModel --> RoleAdd[min=0 roles via role-add only<br/>default skip]
-    RoleAdd --> Extras[directive, related tasks, clarification]
-    Extras --> Confirm
-    Confirm --> Render[render-bundle --render-only]
-```
-
-Launch selection uses role slots and model refs only: current-session lead is this session (listed on the confirmation summary), then each static role's count in `min..max` (default **recommended**; the count step is skipped when `min == max`), then one `provider/model` per slot. Roles with `min = 0` stay closed unless the user opens them with role-add (default skip). Duplicate model refs in the same role are rejected. There is no provider roster multi-pick and no `Use defaults / Customize` fork. Dynamic verifiers are not chosen at launch. `--workers` is a CLI compatibility input only, not a launch picker.
-
-## 3. prepare_task_bundle handling
-
-```mermaid
-sequenceDiagram
-    participant Skill as okstra-run
-    participant Wizard as okstra_ctl.wizard
-    participant Run as prepare_task_bundle
-    participant WT as worktree/provision.py
-    participant Art as artifacts
-
-    Skill->>Wizard: task-type error-analysis selected
-    Wizard-->>Skill: workers/base-ref/model args
-    Skill->>Run: render-bundle --render-only
-    Run->>Run: canonical brief preflight
-    Run->>Run: validate brief/profile
-    Run->>Run: resolve worker roster
-    Run->>WT: provision/reuse worktree
-    Run->>Art: analysis-profile.md includes common contract
-    Run->>Art: task-manifest workflow next=validated report route
-```
-
-For canonical briefs, preflight runs before worker resolution, worktree provisioning, or report creation. A brief whose `reporter-confirmations` status is `pending` stops at this point; legacy briefs keep the compatibility path.
-
-The final report records its next phase in `errorAnalysis.routing.nextTaskType`. A credible cause uses `implementation-option-selection`; continued investigation uses `error-analysis`. When report validation passes, Phase 7 projects `workflow.nextRecommendedPhase` from that one field (`scripts/okstra_ctl/next_phase.py::project`) — a `ready` pointer naming it. A report that leaves the field empty leaves the pointer `pending`; there is no static fallback that supplies a phase the report did not author.
-
-## 4. lead execution flow
-
-```mermaid
-flowchart TD
-    Intake[Phase 1 intake] --> Prompts[Phase 2 worker prompts]
-    Prompts --> Team[Phase 3 TeamCreate]
-    Team --> Dispatch[Phase 4/5 dispatch analysers]
-    Dispatch --> Evidence[worker outputs<br/>root-cause hypotheses]
-    Evidence --> Conv[Phase 5.5 convergence<br/>default maxRounds = 2]
-    Conv --> Report[Phase 6 report-writer final report]
-    Report --> Persist[Phase 7 persist + validate]
-```
-
-The workers analyze the symptom and evidence independently. A finding two distinct role executions derived on their own is recorded as full consensus at Round 0 in both modes — independent co-derivation is already cross-verification, so the adversarial burden of proof applies to single-source claims. Evidence-backed counter-evidence classifies a finding `contested` in the round it lands and takes it out of the verification queue; later agreement can neither erase it nor cost another round. The report-writer does not analyze during Phase 4/5 but writes the final report in Phase 6.
-
-## 5. Deliverables and prohibitions
-
-```mermaid
-flowchart LR
-    Symptom[Symptom] --> Hyp[Root-cause candidates]
-    Hyp --> Gap[Reproduction gaps]
-    Gap --> Validate[Validation path]
-    Validate --> Next[Recommended next diagnostic/planning step]
-    Hyp -. forbidden .-> Fix[Code fix in this run]
-```
-
-The expected final-report content is:
-
-- evidence-backed cause analysis
-- uncertainty boundary
-- practical next diagnostic steps
-- if there is blocking uncertainty, `## 1. Clarification Items`, usually `Blocks=next-phase`
-
-For `error-analysis`, the structured `errorAnalysis` object is the source of truth for the verbatim symptom, reproduction status, `EA-NNN` cause candidates and their counter-evidence, the next diagnostic, and routing. Its shape is enforced by the final-report schema; `validators/validate-run.py::_validate_error_analysis_consistency` enforces the cross-field values — the routing target, a `leadingCauseId` naming a real cause candidate, the two `direction` fields agreeing with that target, and the single matching `phase-continuation` follow-up row. A route to `implementation-option-selection` needs a credible referenced leading cause and `begin-option-selection`. A route back to `error-analysis` needs the sharp next diagnostic and `continue-investigation`.
-
-What is prohibited is source edit, refactor, fix attempt, implementation design artifact, and running build/migration/deploy. Deferring ambiguity that could be answered from code or logs to a user question is also a defect per the profile.
-
-## 6. Code reviewed
-
-- [`prompts/profiles/error-analysis.md`](../../prompts/profiles/error-analysis.md)
-- [`templates/reports/error-analysis-input.template.md`](../../templates/reports/error-analysis-input.template.md)
-- [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py)
-- [`scripts/okstra_ctl/wizard/`](../../scripts/okstra_ctl/wizard/)
-- [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)

package/docs/task-process/implementation-option-selection.md

@@ -1,70 +0,0 @@
-# implementation-option-selection process
-
-## Index
-
-- [1. Purpose](#1-purpose)
-- [2. Execution modes](#2-execution-modes)
-- [3. Prepare gates](#3-prepare-gates)
-- [4. Candidate validation and ranking](#4-candidate-validation-and-ranking)
-- [5. Direction confirmation and planning handoff](#5-direction-confirmation-and-planning-handoff)
-- [6. Forbidden actions](#6-forbidden-actions)
-- [7. Verified code](#7-verified-code)
-
-## 1. Purpose
-
-`implementation-option-selection` is the read-only lifecycle phase between cause analysis and detailed planning. It decides which implementation mechanism and architecture boundary planning may realize. It does not name the exact file list, split stages, or prescribe test commands.
-
-Direction confirmation and detailed plan approval are independent user decisions. Confirming a direction permits planning to begin. It does not approve the plan or permit implementation.
-
-## 2. Execution modes
-
-| Mode | Input | Output |
-|---|---|---|
-| `candidate-comparison` | Requirement ledger, cause evidence, code evidence, independently proposed raw candidates | At most three ranked valid directions and a separate user selection |
-| `preselected-validation` | A direction already fixed by upstream evidence or an explicit user instruction | One normalized and validated direction, or `blocked`; no alternative is generated |
-
-The normal analyser roster contains at least three analyser workers plus the report writer. Each analyser may propose at most three raw candidates. All analysers reassess the merged candidate set before ranking.
-
-## 3. Prepare gates
-
-Prepare rejects the phase when the brief has no stable `EB-NNN`, `PB-NNN`, or `EO-NNN` requirement IDs. External Gates are not part of that denominator. Prepare also rejects a roster with fewer than three analysers.
-
-The phase reuses the task-key worktree and may inspect the code and prior task artifacts. It does not obtain a writable implementation-stage worktree.
-
-## 4. Candidate validation and ranking
-
-Every displayed candidate has all of the following properties:
-
-- `coveragePercent == 100`
-- `scopePrecisionPercent == 100`
-- `coverageVerdict == exact`
-- no `unmappedCommitments`
-- no `contradictedRequirements`
-- supporting code or upstream evidence
-- at least two feasibility votes
-- no safety blocker or unresolved implementation-critical external fact
-
-The final report can display one, two, or three valid candidates. Rejected candidates remain in `candidateAudit` with their rejection reasons and cannot be selected. If no candidate is valid, the report uses `blocked` and planning cannot start.
-
-Ranking uses eight fixed criteria with per-run weights: requirement fit, architecture fit, change locality, implementation complexity, correctness risk, reversibility, verification cost, and rollout cost. Safety and exact-coverage failures override the weighted score.
-
-## 5. Direction confirmation and planning handoff
-
-Comparison mode exports a `DIRECTION SELECTION` block in the user-response sidecar. Prepare validates the selected ID against the displayed candidates and binds the response to the report's sibling data JSON through its SHA-256 digest.
-
-A new planning run receives the selection report through `--selected-direction`. Prepare normalizes the validated choice into `instruction-set/selected-direction.json`. Planning cites that snapshot through `selectedDirectionRef` and writes `approved: false` until the user separately approves the detailed plan.
-
-If planning proves that the mechanism or architecture boundary cannot satisfy exact coverage, it emits `direction-invalidated` and routes back to `implementation-option-selection`. It never picks the next ranked direction automatically.
-
-## 6. Forbidden actions
-
-This phase does not edit source code, run builds or tests, execute migrations, deploy, or call a write API. Candidate details do not contain exact file lists, stage maps, or test commands. Those details belong to `implementation-planning` after direction confirmation.
-
-## 7. Verified code
-
-- [`prompts/profiles/implementation-option-selection.md`](../../prompts/profiles/implementation-option-selection.md)
-- [`prompts/duties/direction-selection-worker.json`](../../prompts/duties/direction-selection-worker.json)
-- [`scripts/okstra_ctl/implementation_options.py`](../../scripts/okstra_ctl/implementation_options.py)
-- [`scripts/okstra_ctl/implementation_direction.py`](../../scripts/okstra_ctl/implementation_direction.py)
-- [`scripts/okstra_ctl/exact_coverage.py`](../../scripts/okstra_ctl/exact_coverage.py)
-- [`validators/validate-run.py`](../../validators/validate-run.py)

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

@@ -1,180 +0,0 @@
-# implementation-planning process
-
-## Index
-
-- [1. Purpose](#1-purpose)
-- [2. okstra-run wizard flow](#2-okstra-run-wizard-flow)
-- [3. prepare_task_bundle handling](#3-prepare_task_bundle-handling)
-- [4. lead execution flow](#4-lead-execution-flow)
-- [5. design preparation and final report gate](#5-design-preparation-and-final-report-gate)
-- [6. Forbidden actions](#6-forbidden-actions)
-- [7. Verified code](#7-verified-code)
-
-## 1. Purpose
-
-`implementation-planning` realizes one direction that was already confirmed by `implementation-option-selection`. It turns that mechanism and architecture boundary into a file-level Stage Map, validation checklist, rollback strategy, and exact requirement-coverage map. The resulting detailed plan has its own approval gate; direction confirmation does not approve it.
-
-An existing plan without `planningContract: selected-direction` remains on the legacy candidate-plan contract for compatibility. A new planning run uses the selected-direction contract and does not generate or rank alternatives.
-
-## 2. okstra-run wizard flow
-
-```mermaid
-flowchart TD
-    Start[/okstra-run/] --> Common[common task identity flow]
-    Common --> Type[task-type = implementation-planning]
-    Type --> Input{new plan or planning rerun?}
-    Input -->|new| Direction[selected-direction report pick]
-    Input -->|rerun| Prior[prior planning report via clarification-response]
-    Direction --> Worktree{active task worktree?}
-    Prior --> Worktree
-    Worktree -->|yes| RoleCount[role-count min..max<br/>omit uses recommended]
-    Worktree -->|no| BaseRef[base-ref pick/text]
-    BaseRef --> RoleCount
-    RoleCount --> RoleModel[role-model provider/model per slot]
-    RoleModel --> Extras[directive, related tasks, clarification]
-    Extras --> Confirm
-    Confirm --> Render[render-bundle]
-```
-
-For a new plan, the wizard asks for a validated option-selection report and passes it as `--selected-direction`. A planning clarification rerun passes its own prior report through `--clarification-response`. Launch selection uses role slots and model refs only: planner count in `min..max` (default recommended), then one `provider/model` per slot. Duplicate model refs in the same role are rejected. There is no provider roster multi-pick. The wizard currently does not ask about `--no-plan-verification`; on the okstra-run path, plan-body verification is prepared as enabled by default.
-
-## 3. prepare_task_bundle handling
-
-```mermaid
-sequenceDiagram
-    participant W as wizard/render-bundle
-    participant P as prepare_task_bundle
-    participant R as render.py
-    participant M as manifests
-
-    W->>P: task-type=implementation-planning + selected-direction or prior planning report
-    P->>P: validate profile/brief/base-ref
-    P->>P: validate selection report, data digest, response, and selected option
-    P->>M: write instruction-set/selected-direction.json
-    P->>P: resolve profile workers + optional override
-    P->>P: resolve model metadata
-    P->>P: provision/reuse task worktree
-    P->>R: _build_convergence_block()
-    R-->>M: convergence.planBodyVerification.enabled=true
-    P->>M: workflow nextRecommendedPhase inherited, ready lowered to pending
-    P-->>W: prepared lead prompt
-```
-
-Prepare rejects a new plan without a selected-direction report. Comparison mode requires a valid `DIRECTION SELECTION` sidecar, while preselected-validation mode uses the confirmed upstream direction without one. The normalized snapshot binds the source report, source-data digest, option ID, direction body, requirements, and invariants.
-
-The snapshot carries the selected direction, not the rest of that sidecar. The `C-NNN` rows the user answered on the option-selection report reach this run separately: prepare attaches the sidecars beside the selected-direction report as the run's `clarification-response.md`, the same attachment implementation gets from its approved plan.
-
-Prepare does not name the next phase. It carries the inherited `workflow.nextRecommendedPhase` forward and lowers a `ready` pointer to `pending`, because this run has not finished and a `ready` pointer would read as an invitation to start the following phase. The pointer becomes `ready` at `implementation` when Phase 7 projects an approvable plan (`outcome: plan-ready`, or a candidate-comparison plan with no `outcome`) and no approval blocker remains; `workflow.awaitingApproval` is then true until the user flips `frontmatter.approved`. A blocking plan-body gate or an open `Blocks=approval` row projects `blocked` instead, so inspect and the wizard ask the user to answer those rows rather than start implementation or loop planning.
-
-## 4. lead execution flow
-
-```mermaid
-flowchart TD
-    P1[Phase 1 intake] --> P2[Phase 2 prompts]
-    P2 --> P3[Phase 3 TeamCreate]
-    P3 --> P4[Phase 4/5 analyser dispatch]
-    P4 --> A[Worker results + Audit sidecar path]
-    A --> G[Round 0 grouping]
-    G --> C[Reducer queue + analyser-instance re-verification]
-    C --> Critic[Optional critic gap reducer transition]
-    Critic --> RW[Phase 6 report-writer narrative]
-    RW --> Extract[Deterministic plan-item extraction]
-    Extract --> PBV[Phase 6 sub-step<br/>Plan-body verifier round]
-    PBV --> Gate{gate result}
-    Gate -->|passed / passed-with-dissent| Approval[render plan decision approval control]
-    Gate -->|blocked-by-disagreement / aborted-non-result| NoApproval[render blocked plan decision]
-    Approval --> P7[Phase 7 persistence/finalization<br/>canonical Markdown render<br/>HTML render + validate-run<br/>via okstra report-finalize]
-    NoApproval --> P7
-```
-
-The artifact sequence is worker results and `Audit sidecar path` → Round 0 grouping → reducer-owned finding queue → analyser-instance re-verification → optional critic transition → report-writer narrative → deterministic plan-item extraction → plan-body verifier round → single report assembly → Phase 7 rendering and validation. Phase 7 calls `okstra report-finalize`; it collects usage into team state, assembles `data.json`, renders Markdown and HTML, materializes follow-ups, and runs `validate-run`. The reducer queues only non-consensus findings; it does not send every complete worker result to every other worker.
-
-Plan-body verification uses a different queue from Phase 5.5. Phase 5.5 verifies worker findings, and the Phase 6 sub-step re-verifies the consolidated plan body produced by the report-writer at the `P-*` plan-item level. The lead must create that queue through `okstra plan-items extract` and prove it is complete with `okstra plan-items validate` before dispatch.
-
-## 5. design preparation and final report gate
-
-The lead deterministically detects domain contract, persistence schema, external interface, transaction/consistency, transformation mapping, lifecycle state machine, rollout/observability, and manual user test surface from the Stage Map. The report-writer does not ask the user starting from blanks; instead it first writes a concrete AI draft for each surface using known facts and evidence.
-
-The status of `designPreparation.items[]` does not forcibly pin completeness to a single stage.
-
-| Status | Meaning | Handling on implementation entry |
-|---|---|---|
-| `ready` | The implementation contract is sufficiently finalized within the planning snapshot | Proceed with that stage |
-| `provisional` | There is a reversible working assumption and guardrail, so it is safe to proceed now | Proceed with that stage, inject the assumption into the executor prompt, and re-confirm at the designated review point |
-| `blocked` | There is no safe default and it needs an external authorization, business policy, or destructive-change decision | Only the stage in this item's `stageRefs` waits for input or is replanned |
-| `not-applicable` | The surface found by the detector does not require a separate contract in this stage | Record a concrete reason and proceed |
-
-If there is no detected surface and no manual test input that changes the interface/acceptance, write `mode: no-design-inputs` with a concrete reason. So there is no need to create a formal empty document for a simple task.
-
-`manual-user-test` does not have to fully fix the execution method at planning time. If there is a safe default procedure even before seeing the actual diff, proceed with `provisional` and `ifStillOpen: follow-up`, and the implementation report finally owns the `implementation.manualUserTest` aligned to the actual change. Conversely, use `blocked` only when the stage cannot be safely completed without an acceptance method that only the user can provide.
-
-Tier 3 entries keep the following ownership and gate boundary. Planning records
-the executable check and prerequisites, but a live external verification stays
-with the user when Okstra cannot prove it in-session.
-
-| Entry policy | PASS | FAIL / MISSING / unavailable |
-|---|---|---|
-| `requires` contains `db`, `http`, or `external` | Evidence recorded | Advisory; user rerun method recorded; run continues |
-| `requires=[]` or `requires=[io]` | Evidence recorded | Blocking |
-
-These outcomes are enforced by
-`scripts/okstra_ctl/conformance.py::decide_conformance_gate` and
-`validators/validate-run.py::_validate_conformance`.
-
-Phase 7 deterministically creates a `design-prep-requests/` document filled with an AI proposal for each `provisional`/`blocked` item. When the user or wizard approves, edits, rejects, or holds the draft, only after confirmation does it append a new revision sidecar under `design-prep-inputs/`. This response does not modify the approved planning report.
-
-Plan approval and design-preparation status are independent gates. If plan-body verification passed, the plan itself can be approved even when there is a `blocked` item. The actual `implementation` preflight resolves only the items of the selected stage, and unrelated stages keep proceeding.
-
-```mermaid
-flowchart LR
-    Direction[Selected Direction Snapshot] --> Realize[Direction Realization]
-    Realize --> 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[YAML frontmatter approval]
-    Approval --> Impl[Next run: implementation]
-```
-
-The selected-direction branch verifies `P-Dir-1` before its stage, dependency, validation, rollback, requirement, preparation, and variation items. `P-Dir-1` proves that the plan preserves the selected mechanism, architecture boundary, invariants, and user constraints. The legacy branch continues to extract `P-Opt-*` from its option candidates.
-
-The detailed selected-direction plan retains these deliverable surfaces:
-
-- `Stage Map`
-- `Stage Exit Contract`
-- `Stage Validation`
-- `Dependency`
-- `Cross-Project Dependencies`
-- `Decision Drafts`
-- `Validation Checklist`
-- `Rollback`
-- `Requirement Coverage`
-- `Implementation Design Preparation`
-
-Approval is recorded as `frontmatter.approved: true` on the report record (`--approve` or the in-session wizard). A selected-direction plan has no `implementationOption` field and rejects `--implementation-option` before any approval-file mutation. If a `Blocks=approval` clarification row is unresolved, implementation prepare rejects the plan even when the record is approved. Existing candidate plans keep their legacy option field and execution behavior.
-
-`plan-ready` requires 100% requirement coverage, 100% scope precision, and no unmapped stage or file change. If the selected mechanism or boundary cannot meet those conditions, planning emits `direction-invalidated` without an executable Stage Map and routes back to `implementation-option-selection`. It does not choose another direction automatically.
-
-## 6. Forbidden actions
-
-```mermaid
-flowchart TD
-    Plan[planning output] --> OK[reports/prompts/state/manifests only]
-    Plan -. forbidden .-> Code[source code edit]
-    Plan -. forbidden .-> Build[build/test/migration/deploy execution]
-    Plan -. forbidden .-> ExternalDocs[docs/superpowers plans/specs write]
-    Plan -. forbidden .-> NextPhase[start implementation in same run]
-```
-
-This phase only produces the plan document. Code-level micro-optimization, source edit, build, migration, deployment, and any write outside the run artifact directory are forbidden.
-
-## 7. Verified code
-
-- [`prompts/profiles/implementation-planning.md`](../../prompts/profiles/implementation-planning.md)
-- [`templates/reports/implementation-planning-input.template.md`](../../templates/reports/implementation-planning-input.template.md)
-- [`templates/reports/final-report-v2.template.md`](../../templates/reports/final-report-v2.template.md)
-- [`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)