okstra 0.205.0 → 0.206.0

package/docs/task-process/README.md

@@ -1,82 +0,0 @@
-# okstra-run task process
-
-## Index
-
-- [1. Reading order](#1-reading-order)
-- [2. Big picture](#2-big-picture)
-- [3. task-type documents](#3-task-type-documents)
-- [4. Key code locations](#4-key-code-locations)
-- [5. Quick comparison table](#5-quick-comparison-table)
-
-## 1. Reading order
-
-`okstra-run` is the path that starts a task inside a supported Claude Code, Codex, or Antigravity host session. This folder organizes that execution flow into two layers.
-
-1. First read [common-flow.md](common-flow.md). It is the wizard, render-bundle, lead phase, and artifact flow shared by every task-type.
-2. Then read the document for the task-type you want to run.
-3. Check the per-task-type differences across three places: "what the wizard additionally asks", "what `prepare_task_bundle()` blocks in the runtime", and "what the lead profile enforces within the phase".
-
-## 2. Big picture
-
-```mermaid
-flowchart TD
-    U[User in supported host] --> S[okstra-run skill]
-    S --> R[Step 1<br/>ensure-installed / paths / check-project]
-    R --> W[okstra wizard<br/>state machine]
-    W --> A[render-args]
-    A --> B[okstra render-bundle<br/>--render-only]
-    B --> P[prepare_task_bundle()]
-    P --> I["runs/task-type/prompts<br/>lead-execution-prompt-*.md"]
-    I --> L[Current host session<br/>takes over as Okstra lead]
-    L --> F[Phase 1-7 lead workflow]
-    F --> O[final-report + manifests + status]
-```
-
-`okstra-run` does not call `scripts/okstra.sh`. Instead it goes through `okstra wizard` and `okstra render-bundle` and converges on the same single Python entrypoint, `prepare_task_bundle()`.
-
-Launch selection is role slots and model refs, not a provider roster. The wizard asks one screen per static role: a checkbox of candidate models for a role that runs several instances (the number checked is the instance count, rendered as `--role-count <role>=<N>` plus one `--role-model <role>=<provider>/<model>` per checked model; the label states the profile range and recommended count), a single pick for a fixed single-instance role. current-session lead is this session and is listed on the confirmation summary. Roles with `min = 0` stay closed unless the user adds them. There is no provider multi-pick and no `Use defaults / Customize` fork for worker selection. `--workers` is compatibility-only. `lead` is a compatibility alias for `leader`. `executor` is a compatibility alias for `implementer`. New records write `leader` and `implementer`.
-
-## 3. task-type documents
-
-| task-type | Document | One-line purpose |
-|---|---|---|
-| `requirements-discovery` | [requirements-discovery.md](requirements-discovery.md) | Classify the request and choose the next safe phase. |
-| `error-analysis` | [error-analysis.md](error-analysis.md) | Find cause candidates and validation paths from symptoms and evidence. |
-| `implementation-option-selection` | [implementation-option-selection.md](implementation-option-selection.md) | Compare or validate exact-coverage directions before detailed planning. |
-| `implementation-planning` | [implementation-planning.md](implementation-planning.md) | Realize one selected direction as an exact-coverage plan with a separate approval gate. |
-| `implementation` | [implementation.md](implementation.md) | The executor implements the approved plan and the verifier verifies it independently. |
-| `final-verification` | [final-verification.md](final-verification.md) | Judge whole-task or single-stage acceptance of the implementation result. |
-| `release-handoff` | [release-handoff.md](release-handoff.md) | Perform the push/PR handoff lead-only after an accepted verdict. |
-
-## 4. Key code locations
-
-| Concern | Source of truth |
-|---|---|
-| okstra-run skill procedure | [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md) |
-| wizard state machine | [`scripts/okstra_ctl/wizard/`](../../scripts/okstra_ctl/wizard/) |
-| wizard prompt text | [`prompts/wizard/prompts.ko.json`](../../prompts/wizard/prompts.ko.json) |
-| render-bundle Node shim | [`src/commands/execute/render-bundle.mts`](../../src/commands/execute/render-bundle.mts) |
-| single entrypoint for bundle creation | [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py) |
-| implementation stage selection/provisioning | [`scripts/okstra_ctl/implementation_stage.py`](../../scripts/okstra_ctl/implementation_stage.py) |
-| Stage Lifecycle Snapshot + stage target/base/verification policy | [`scripts/okstra_ctl/stage_targets.py`](../../scripts/okstra_ctl/stage_targets.py) |
-| phase boundary | [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py) |
-| task worktree | [`scripts/okstra_ctl/worktree/`](../../scripts/okstra_ctl/worktree/) |
-| stage-group handoff | [`scripts/okstra_ctl/handoff.py`](../../scripts/okstra_ctl/handoff.py) |
-| worker roster parser | [`scripts/okstra_ctl/workers.py`](../../scripts/okstra_ctl/workers.py) |
-| lead operating contract | [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md) |
-| phase profiles | [`prompts/profiles/`](../../prompts/profiles/) |
-| final report shape / HTML view | [`templates/reports/final-report-v2.template.md`](../../templates/reports/final-report-v2.template.md), [`scripts/okstra_ctl/report_views.py`](../../scripts/okstra_ctl/report_views.py) |
-
-## 5. Quick comparison table
-
-The last column is the `workflow.nextRecommendedPhase` pointer Phase 7 leaves behind — an object `{phase, status, rationale}`, projected from the report's own routing field. There is no static default: a run that settles no route ends `pending` with no phase. The routing field's `rationale` is carried into the pointer, and the lead's closeout quotes it. The rule for authoring that field is stated once, in the Phase 6 checklist of [`prompts/lead/report-writer.md`](../../prompts/lead/report-writer.md).
-
-| task-type | wizard special question | runtime prepare gate | lead/worker mode | next-phase pointer |
-|---|---|---|---|---|
-| `requirements-discovery` | common questions only | profile/brief/base-ref exist | multi-worker analysis, convergence 1 round default | `ready` at `error-analysis` or `implementation-option-selection`; `pending` when neither is settled |
-| `error-analysis` | common questions only | profile/brief/base-ref exist | multi-worker analysis, convergence 2 rounds default | `ready` at `implementation-option-selection`, or at `error-analysis` while the investigation continues |
-| `implementation-option-selection` | comparison or preselected-validation context | stable brief IDs and at least three analysers | read-only candidate validation, exact coverage, separate direction confirmation | `ready` at `implementation-planning` (a confirmed direction, or ranked candidates the planning wizard lets the user pick from), `pending` when no candidate was ranked, or `blocked` |
-| `implementation-planning` | selected-direction report for a new plan | selection report/sidecar/digest or same-task planning rerun | one-direction realization + Phase 6 plan-body verification | `ready` at `implementation` on approvable `plan-ready` (`awaitingApproval` until the user flips `approved`); `blocked` when the gate is blocking or a `Blocks=approval` row is open; `ready` at `implementation-option-selection` on `direction-invalidated` |
-| `implementation` | approved plan, stage multi-pick, executor | approved marker, Stage Lifecycle Snapshot, stage-key reservation, QA command deny-list | one run = one stage; executor writes in isolated stage worktree, verifiers read-only | `ready` at the stage report's `routingRecommendation.target` — `final-verification` on a clean stage |
-| `final-verification` | approved plan, stage pick (whole-task or single-stage) | `VERIFICATION_TARGET` resolved; whole-task auto integration/teardown or single-stage worktree reuse | whole-task may integrate stages first; analyser verification itself is read-only | `ready` at `release-handoff` on an `accepted` verdict, otherwise at the phase owning the defect; `terminal` on `done` |
-| `release-handoff` | handoff scope (stage-group or whole-task), PR template override/scope | Stage Lifecycle Snapshot eligibility, generated `release-handoff-input.md`, empty worker roster | single-lead; whole-task PR or stage-group collector branch/PR | always `terminal` |

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)