okstra 0.206.0 → 0.206.1

package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md

@@ -0,0 +1,204 @@
+# 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
+
+- [`scripts/okstra_ctl/phases/implementation_planning/profile.md`](profile.md)
+- [`scripts/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md`](report_assets/implementation-planning-input.template.md)
+- [`templates/reports/final-report-v2.template.md`](../../../../templates/reports/final-report-v2.template.md)
+- [`scripts/okstra_ctl/render.py`](../../render.py)
+- [`validators/validate-run.py`](../../../../validators/validate-run.py)
+- [`prompts/lead/okstra-lead-contract.md`](../../../../prompts/lead/okstra-lead-contract.md)
+
+## Phase ownership
+
+`profile.md` and `profile.json` define execution and role requirements. `host-rules.md` defines the planning-only host interaction. `entry.py` validates new-plan and rerun inputs; `wizard.py` presents the direction picker without changing its order. `validation.py` validates selected-direction realization, `guidance.py` validates dependencies and approval guidance, and `plan_body.py` validates plan verification rounds and conformance declarations. The shared validator assembles these checks.
+
+`report.py` and `report_assets/` own the planning display and input templates. Approval-state reading remains in `okstra_ctl.plan_approval`, selected-direction snapshot reading remains in `okstra_ctl.implementation_direction`, and plan-item extraction remains in `okstra_ctl.plan_items`, because later phases consume those contracts. The shared final-report 2.0 and 3.0 schemas retain the `implementationPlanning` definitions.
+
+Phase-local tests exercise planning guidance and input selection. Shared tests retain report assembly, schema, and cross-phase approval contracts.
+
+## Guarantees
+
+| ID | Guarantee | Enforcement |
+|---|---|---|
+| P-1 | Direction realization preserves the selected mechanism, boundaries, planning invariants and user constraints. | `scripts/okstra_ctl/phases/implementation_planning/validation.py::_direction_realization_errors` |
+| P-2 | Phase packages do not import other phases or the common run assembler. | `tests/contract/test_phase_catalog.py::test_a_phase_package_does_not_import_another_phase_or_the_assembler` |
+| P-3 | Each planned stage traces to an explicitly enumerated requirement coverage citation. | `scripts/okstra_ctl/phases/implementation_planning/validation.py::_validate_stage_has_requirement` |
+| P-4 | Requirement sources resolve through admissible provenance and match declared brief references. | `scripts/okstra_ctl/phases/implementation_planning/validation.py::_validate_requirement_provenance` |
+| P-5 | Detector snapshot evidence matches a fresh detection over the plan and rejects duplicate stage/kind rows. | `scripts/okstra_ctl/phases/implementation_planning/report.py::project_design` |
+
+## Report finalization and scope provenance
+
+The common validator reads brief headings and end-state identifiers through `scope_provenance.py`. Planning validation uses those values to check requirement sources and reverse stage coverage. The shared source grammar remains available to fan-out and other brief consumers.
+
+`report.py` validates detector coverage against the plan, attaches design coverage to matching stages, reconciles stale unseeded wording after a passing plan-body gate, and derives absent end-state rows from requirement coverage. Input reading, owner attribution, verification-owner checks and publication remain in the common report assembler.