# 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.

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-ready` outcome; `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)