# 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.md`](../../prompts/duties/direction-selection-worker.md)
- [`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)