okstra 0.205.1 → 0.206.0

package/docs/task-process/implementation.md

@@ -1,226 +0,0 @@
-# implementation process
-
-## Index
-
-- [1. Purpose](#1-purpose)
-- [2. okstra-run wizard flow](#2-okstra-run-wizard-flow)
-- [Carry-in](#carry-in)
-- [3. runtime gate](#3-runtime-gate)
-  - [3.1 design-preparation preflight](#31-design-preparation-preflight)
-- [4. executor and verifier](#4-executor-and-verifier)
-- [5. stage and consumers](#5-stage-and-consumers)
-- [6. Deliverables](#6-deliverables)
-- [7. Forbidden actions](#7-forbidden-actions)
-- [8. Verified code](#8-verified-code)
-
-## 1. Purpose
-
-`implementation` executes an approved `implementation-planning` final report into actual code changes and local commits. Source edit is allowed only in this phase, but scope is limited to the approved plan and recorded out-of-plan justification.
-
-## 2. okstra-run wizard flow
-
-```mermaid
-flowchart TD
-    Start[/okstra-run/] --> Common[common task identity flow]
-    Common --> Type[task-type = implementation]
-    Type --> Worktree{active task worktree?}
-    Worktree -->|yes| PlanPick[approved plan pick/text]
-    Worktree -->|no| BaseRef[base-ref pick/text]
-    BaseRef --> PlanPick
-    PlanPick --> Approved{APPROVED marker present?}
-    Approved -->|no| Retry[re-prompt same step]
-    Approved -->|yes| Stage[stage multi-pick<br/>ready/active markers]
-    Stage --> Chain[render-args<br/>stage + chain-stages]
-    Chain --> RoleCount[role-count min..max<br/>omit uses recommended; skip if min==max]
-    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]
-```
-
-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 defaults-vs-customize fork. `executor` is only a compatibility alias for `implementer` in model refs; implementer slots are chosen through role-count / role-model. Dynamic verifiers are not chosen at launch. `--workers` is a CLI compatibility input only, not a launch picker. `stage_pick` is a multi-pick that shows done/in-progress/ready/waiting status. The selected stage set goes through dependency closure and topological sort into a `chain-stages` CSV, and each actual run executes only one of those stages.
-
-The current okstra-run wizard path does not expose `--approve` that directly flips the approval checkbox. The plan file must already have a recognized approval marker.
-
-## Carry-in
-
-Three facts about what reaches an implementation run from its approved plan, gathered
-here because they were previously readable only by tracing the runtime sources.
-
-- **What is attached automatically.** The user's answers to the approved plan's `## 1.
-  Clarification Items` rows — the `user-response-*.md` sidecars under
-  `runs/implementation-planning/user-responses/`, a sibling of the directory holding the
-  plan itself — are collected into `instruction-set/clarification-response.md`. Those
-  sidecars are written by the user, not by the report renderer. The report HTML's `Export
-  user response` button downloads a file the user then saves there. The in-session flow
-  reads `user-response list-view` and `user-response show-view --report <path>
-  --project-root <root>`, then uses `user-response begin`, typed `user-response answer`
-  and decision commands, and `user-response finalize` to publish the sidecar. The
-  renderer at most pre-creates that directory empty so the user does not
-  have to; it never puts a sidecar in it.
-  The plan document is *not* copied: it reaches the run as the `--approved-plan` path and
-  the executor re-reads it there. An explicit `--clarification-response` wins when given;
-  the automatic attachment is the fallback for an implementation run that supplies none
-  (`scripts/okstra_ctl/run.py`, the `implementation` carry-in branch).
-- **Who reads it, and when.** The executor, before its first edit
-  (`prompts/profiles/_implementation-executor.md`). A CLI executor (codex/antigravity)
-  cannot reach that path from inside its sandbox, so the lead transcribes the file's body
-  into the dispatched executor prompt — a path reference alone never arrives.
-- **What happens when an answer contradicts the plan.** Each answer is an authoritative
-  refinement of its matching row's scope, but an answer that contradicts the approved plan
-  or expands scope beyond it is a re-plan trigger: it routes to a new
-  `implementation-planning` run rather than being absorbed silently mid-run. Quietly
-  widening scope inside an implementation run is what this branch exists to prevent.
-
-## 3. runtime gate
-
-```mermaid
-sequenceDiagram
-    participant W as okstra-run
-    participant P as prepare_task_bundle
-    participant Plan as approved final-report
-    participant QA as project.json qaCommands
-    participant Stage as stage target policy
-    participant Reg as worktree registry
-    participant WT as stage worktree
-
-    W->>P: task-type=implementation, approved-plan, stage, executor
-    P->>Plan: file exists?
-    P->>Plan: approval marker regex matches?
-    P->>Plan: unresolved Blocks=approval rows?
-    P->>Stage: build Stage Lifecycle Snapshot
-    P->>Reg: read active stage-key reservations
-    P->>Stage: select exactly one ready stage
-    P->>Plan: resolve selected stage design preparation
-    P->>WT: provision stage-N worktree + branch
-    P->>QA: validate qaCommands deny-list
-    P->>P: executor provider in resolved roster?
-    P->>P: namespace run artifacts under stage-N
-    P-->>W: prepared implementation prompt or PrepareError
-```
-
-`--approve` exists in the Python runtime, but the okstra-run wizard does not emit it as args. On the shell path, `--approve` sets the report record `frontmatter.approved` to `true` and then follows the same validation path.
-
-### 3.1 design-preparation preflight
-
-Right after stage selection, before worktree provisioning and appending `status:"started"` to `consumers.jsonl`, it resolves the design preparation of the approved plan. The resolver reads only items whose `stageRefs` includes the selected stage, so an undecided decision in another stage does not block the current run.
-
-| outcome | runtime behavior |
-|---|---|
-| `proceed` | Inject the effective AI proposal, confirmed override, guardrail, and provisional working assumption into the executor prompt as `DESIGN_PREP_CONTEXT`, and create the worktree. |
-| `wait_for_input` | Stop with `stage <N> waits for design input: ...; <request paths>`. Do not create the worktree or the started consumer row. |
-| `replan` | Stop with `stage <N> requires implementation-planning rerun: ...`. Let a newly approved/edited decision change the planning snapshot or the Stage Map. |
-
-`ready`, `not-applicable`, and `no-design-inputs` proceed. `provisional` can proceed even without a response because there is a safe working assumption, and a non-triggering approval/edit states that assumption and override in the prompt. A `blocked` non-response makes only that stage wait, and when a blocked draft is approved/edited, it replans so that authorization is reflected into the approved plan. A markerless legacy plan proceeds with a `legacy-unassessed` warning without modifying the report.
-
-`manual-user-test` input uses the same flexible status. The planning draft is a seed for implementation to concretize the verification method against the actual diff, and the SSOT of the final execution method is the implementation report's `implementation.manualUserTest`. final-verification does not directly execute the planning sidecar.
-
-Tier 3 conformance uses the same ownership boundary during execution and
-verification.
-
-| 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`.
-
-## 4. executor and verifier
-
-```mermaid
-flowchart TD
-    Lead[Okstra lead<br/>host native] --> Exec[Executor<br/>selected provider]
-    Lead --> CV[Claude verifier<br/>read-only]
-    Lead --> XV[Codex verifier<br/>read-only]
-    Lead --> GV{Antigravity in roster?}
-    GV -->|yes| Gem[Antigravity verifier<br/>read-only]
-    Exec --> Diff[Source edits + local commits]
-    CV --> QA[Independent QA rerun]
-    XV --> QA
-    Gem --> QA
-    QA --> External{External Tier 3<br/>non-PASS?}
-    External -->|yes| Advisory[ADVISORY<br/>user-owned rerun]
-    External -->|no| Verdict[PASS / CONCERNS / FAIL]
-    Advisory --> Report
-    Verdict --> Report[Final report preserves dissent]
-```
-
-Only the executor may mutate project files. The verifier independently re-runs the diff and validation command read-only in the same worktree. Even a verifier with the same provider as the executor runs again in a separate fresh CLI session. This is to prevent a structure where the same session approves a diff the same session wrote.
-
-## 5. stage and consumers
-
-```mermaid
-flowchart LR
-    Plan[approved plan<br/>Stage Map] --> Parse[parse stage map]
-    Parse --> Snapshot[Stage Lifecycle Snapshot<br/>carry + consumers + reservations]
-    Snapshot --> Resolve{stage arg}
-    Resolve -->|auto| Next[lowest ready<br/>not done/started/reserved]
-    Resolve -->|number| Forced[selected stage]
-    Next --> Prep{selected-stage<br/>design preflight}
-    Forced --> Prep
-    Prep -->|proceed| Base[resolve stage base commit]
-    Prep -->|wait / replan| Stop[stop before worktree<br/>and started consumer]
-    Base --> WT[create/reuse stage worktree]
-    WT --> Started[append consumer status=started]
-    Started --> Run[implementation executes one selected stage]
-```
-
-Stage selection is `auto` or a number. If `--stage` comes from another task-type, it is a `PrepareError`. The runtime reads `done`/`started` of `consumers.jsonl`, carry sidecar backfill, and the active stage-key of the registry together in the Stage Lifecycle Snapshot, and excludes occupied stages. The Snapshot is not a new stored file but a read-side view of `stage_targets.py`.
-
-The stage worktree base is decided by dependency shape. An independent stage uses the task-key worktree HEAD fixed at first implementation entry as its anchor, and a single-dependency stage branches from the predecessor stage's done `head_commit`. A multi-dependency stage branches from a commit holding exactly its predecessors: the predecessor commit that already contains the others, or else an integration branch merging them (`<work-category-namespace>/<task-id-segment>-g<n1>-<n2>`). okstra creates that branch itself, so a predecessor that has not been merged into the task branch no longer blocks the stage; release-handoff later reuses the same branch as that stage's PR base.
-
-## 6. Deliverables
-
-```mermaid
-flowchart TD
-    Code[Commits] --> Report[implementation final report]
-    Diff[git diff --stat base..HEAD] --> Report
-    TDD[TDD evidence] --> Report
-    Validation[Validation evidence<br/>actual output + exit code] --> Report
-    Verifiers[Verifier results<br/>command logs + verdicts] --> Report
-    Rollback[Rollback verification] --> Report
-    Report --> Next[Routing recommendation<br/>final-verification or loop back]
-```
-
-The final report requires at least the following.
-
-- approved plan path and quoted approval marker
-- selected stage, isolated stage worktree path, run artifact path (`runs/implementation/stage-<N>/`)
-- commit SHA, message, plan step mapping
-- diff summary and per-file summary
-- out-of-plan edits block
-- actual stdout/stderr and exit code of the plan validation command
-- TDD failing-then-passing evidence
-- per-verifier independent validation rerun result
-- `carry/stage-<N>.json` evidence sidecar and `consumers.jsonl` started/done row
-- rollback verification
-- `implementation.manualUserTest` finalized against the actual diff and whether it is executable
-- follow-up tasks table
-
-## 7. Forbidden actions
-
-```mermaid
-flowchart TD
-    Impl[implementation] --> Allowed[local edit/write/build/test/git add/git commit]
-    Impl -. forbidden .-> Push[git push]
-    Impl -. forbidden .-> Publish[publish/release/deploy]
-    Impl -. forbidden .-> RealDB[source migration or<br/>shared/staging/prod datastore write]
-    Impl -. forbidden .-> VerifierWrite[verifier edit/write]
-    Impl -. forbidden .-> Scope[silent scope expansion]
-    Impl -. forbidden .-> Acceptance[declaring final acceptance]
-```
-
-This phase does not declare final acceptance. It says only ready for final-verification or needs new loop.
-
-## 8. Verified code
-
-- [`prompts/profiles/implementation.md`](../../prompts/profiles/implementation.md)
-- [`templates/reports/implementation-input.template.md`](../../templates/reports/implementation-input.template.md)
-- [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py)
-- [`scripts/okstra_ctl/wizard/`](../../scripts/okstra_ctl/wizard/)
-- [`validators/validate-implementation-plan-stages.py`](../../validators/validate-implementation-plan-stages.py)
-- [`scripts/okstra_ctl/qa_commands.py`](../../scripts/okstra_ctl/qa_commands.py)
-- [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)

package/docs/task-process/release-handoff.md

@@ -1,220 +0,0 @@
-# release-handoff process
-
-## Index
-
-- [1. Purpose](#1-purpose)
-- [2. okstra-run wizard flow](#2-okstra-run-wizard-flow)
-- [3. prepare stage](#3-prepare-stage)
-- [4. entry gate](#4-entry-gate)
-- [5. lead-only execution flow](#5-lead-only-execution-flow)
-- [6. PR template resolution](#6-pr-template-resolution)
-- [7. Deliverables](#7-deliverables)
-- [8. Forbidden actions](#8-forbidden-actions)
-- [9. Verified code](#9-verified-code)
-
-## 1. Purpose
-
-`release-handoff` is the terminal phase that pushes already-committed implementation stages with a release-ready verdict, or hands them off as pull requests. **One stage is one PR.** The PR head is that stage's stack branch; the base comes from its `depends-on` — the release base for a stage with no live dependency, the predecessor's branch for a stage with one (a stacked PR), and a branch merging the predecessors for a stage with several. The only commits this phase may create are the merge commits `okstra handoff pr-plan` makes on such a merge-base branch.
-
-Because the PRs are a stack, they must be merged in ascending stage order with a merge commit or a rebase-merge. A squash replaces the commits the next PR's base points at, so the stack breaks — every PR body states this, and the lead never merges.
-
-This phase has no worker dispatch. It does not use a provider or report-writer roster; the host-native Okstra lead performs git/gh inspection, user questions, the PR draft, and the final report inline.
-
-## 2. okstra-run wizard flow
-
-```mermaid
-flowchart TD
-    Start[/okstra-run/] --> Common[common task identity flow]
-    Common --> Type[task-type = release-handoff]
-    Type --> Plan[approved plan auto/pick]
-    Plan --> Scope[handoff stage pick<br/>eligible stages, one PR each]
-    Scope --> Worktree{active task worktree?}
-    Worktree -->|yes| RoleCount[role-count min..max<br/>omit uses recommended; skip if min==max]
-    Worktree -->|no| BaseRef[base-ref pick/text]
-    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 --> Template[PR template override?]
-    Template --> TemplateScope[save template to project/global?]
-    TemplateScope --> Confirm[confirmation]
-    Confirm --> Render[render-bundle]
-```
-
-`release-handoff` has no analysis-worker dispatch. Launch selection still shows any applicable role-count / role-model steps; current-session lead is this session and is listed on the confirmation summary. There is no provider roster multi-pick and no `Use defaults / Customize` fork. Dynamic verifiers are not chosen at launch. `--workers` is not a launch picker, and the runtime forces the worker list to empty. The wizard outcome's `renderArgs` includes `pr-template-path` only for release-handoff. Scope selection finishes before prepare, and the project/global save runs before `render-bundle` via the `config.set pr-template-path` action of `outcome.persistActions[]`. Only the stages that were marked `verified` by a release-ready verification in the Stage Lifecycle Snapshot and are not yet covered by a `pr` become candidates; leaving `--stages` empty takes all of them, and the wizard picker offers an all-stages option beside the individual ones. Both verification scopes mark a stage: a single-stage report marks its own stage, and a whole-task report marks every stage in its `stageReports` whose completed commit the verified head contains.
-
-Note that this phase is also a target of task worktree provisioning. The normal flow reuses the implementation/final-verification result of the same task-key. Starting a new task may create a new branch, and it is likely to be blocked at the entry gate's "implementation commit exists" condition.
-
-## 3. prepare stage
-
-```mermaid
-sequenceDiagram
-    participant W as okstra-run
-    participant P as prepare_task_bundle
-    participant T as PR template resolver
-    participant WT as worktree registry
-    participant FS as task artifacts
-
-    W->>P: task-type=release-handoff, approved-plan, stages csv, optional pr-template-path
-    P->>P: enforce stage eligibility (Stage Lifecycle Snapshot)
-    P->>FS: generate release-handoff-input.md (cited verification reports)
-    P->>P: force workers=[]
-    P->>T: resolve PR template
-    P->>WT: reuse or provision task worktree
-    P->>FS: write manifests with empty roster
-    P->>FS: expose PR_TEMPLATE_PATH and PR_TEMPLATE_SOURCE
-    P-->>W: lead prompt for current session
-```
-
-The profile has no `Required workers:` block, and `run.py` also empties the worker override for `release-handoff`. So not going through the general TeamCreate / convergence / report-writer flow of `prompts/lead/okstra-lead-contract.md` is the intended behavior.
-
-## 4. entry gate
-
-```mermaid
-flowchart TD
-    Brief[release-handoff-input.md<br/>generated by prepare] --> Source{Source Verification Report present?}
-    Source -->|no| Block[blocked<br/>route final-verification]
-    Source -->|yes| Verdict{Verdict Token == accepted?}
-    Verdict -->|no| Block
-    Verdict -->|yes| Eligible[each selected stage<br/>verified and not in PR]
-    Eligible --> Status{git status --short clean?}
-    Status -->|no| Dirty[blocked<br/>dirty tree]
-    Status -->|yes| Commits{each stage has commits<br/>over its own base?}
-    Commits -->|no| ImplBlock[blocked<br/>route implementation]
-    Commits -->|yes| Ready[handoff questions may begin]
-```
-
-Before asking the user whether to push/PR, the lead confirms the following.
-
-- The `## Source Verification Report` of the input document (`release-handoff-input.md`) generated by prepare lists the selected stages (`HANDOFF_STAGES`) and the cited report table. The brief is the input of the entry phase, so it does not exist in release-handoff — the user's stage selection finishes before prepare via the wizard `handoff_stage_pick` or the CLI `--stages` (empty takes every eligible stage).
-- Each cited report must be the latest validated execution for the run it belongs to — the stage's own run for a single-stage report, the task's run for a whole-task one — and must match the recorded implementation commit. A newer unfinished, broken, or blocked execution prevents fallback to an older success. Prepare and `okstra handoff pr-plan` re-check this evidence. A new implementation start or completion invalidates the earlier approval.
-- The working tree is clean.
-- The current branch is recorded as evidence, not used as a PR head: every head comes from `okstra handoff pr-plan`. A release base branch such as `main`, `master`, `prod`, `preprod`, `staging`, or `dev` is never pushed.
-- Each stage's `<base_commit>..<head_commit>` range is non-empty.
-
-`accepted` is release-ready. `conditional-accept` is release-ready only when its non-empty condition list explicitly sets every `blocksReleaseHandoff` to `false`; those conditions remain in the generated input and PR body. `blocked`, missing conditions, and ambiguous verdicts stop delivery. `okstra_ctl.release_gate.release_handoff_allowed` owns this rule.
-
-Verification targets are preserved per execution under the run's state directory. Old records without provable task/stage/commit evidence require re-verification; they are not rewritten. The checks are enforced by `okstra_ctl.handoff_verification`, `consumers.verified_accepted_stages`, and the handoff regression tests.
-
-## 5. lead-only execution flow
-
-```mermaid
-stateDiagram-v2
-    [*] --> Gate: entry gate
-    Gate --> Q1: action selection
-    Q1 --> LocalCheckout: local checkout
-    Q1 --> Skip: skip
-    Q1 --> Q2: push + PR
-    state "okstra handoff pr-plan (head/base per stage)" as Plan
-    Q2 --> Plan: choose release base
-    Plan --> Probe: rows ready
-    Probe --> Q3: no conflict
-    Probe --> Conflict: conflict detected
-    Conflict --> Q2: change base branch
-    Conflict --> Q3: proceed anyway
-    Conflict --> Cancel: cancel
-    Q3 --> Push: use as-is or edit then proceed
-    Q3 --> Cancel: cancel
-    Push --> ReuseOrCreate: push each branch in stage order
-    ReuseOrCreate --> FinalReport: gh pr list / gh pr create per stage
-    LocalCheckout --> FinalReport
-    Skip --> FinalReport
-    Cancel --> FinalReport
-    FinalReport --> [*]
-```
-
-User interaction is exactly three steps.
-
-1. Q1 action: `local checkout`, `push + PR`, `skip`
-2. Q2 release base: a branch from the profile menu such as `staging`, `preprod`, `main`, or Enter directly
-3. Q3 PR title/body: every stage's draft in one question — `use as-is`, `edit then proceed`, `cancel`
-
-The merge-conflict probe happens only for `push + PR`, once per stage against that stage's own base.
-
-`local checkout` takes one stage and hands that stage's branch to the main worktree; there is no whole-task target.
-
-```mermaid
-flowchart TD
-    PushPR[push + PR selected] --> Fetch[git fetch origin chosen-base]
-    Fetch --> MergeTree[git merge-tree --write-tree<br/>stage head vs its own PR base]
-    MergeTree --> Conflict{any stage conflicts?}
-    Conflict -->|no| Draft[show PR draft]
-    Conflict -->|yes| Ask[ask proceed/change base/cancel]
-    Ask -->|proceed anyway| Draft
-    Ask -->|change base branch| Base[return to Q2]
-    Ask -->|cancel| Report[final report without push/PR]
-```
-
-The probe must not change the working tree. `git merge`, `git rebase`, and `git pull` are not part of this probe.
-
-## 6. PR template resolution
-
-```mermaid
-flowchart TD
-    Override[--pr-template-path from wizard] --> Chosen{exists?}
-    Chosen -->|yes| UseOverride[use override]
-    Chosen -->|no| Project[project config template]
-    Project -->|exists| UseProject[use project template]
-    Project -->|missing| Global[global config template]
-    Global -->|exists| UseGlobal[use global template]
-    Global -->|missing| Default[okstra skill default template]
-```
-
-When the user picks a template on the customize path, the okstra-run skill performs the project/global scope save before render-bundle. The runtime puts the resolved `PR_TEMPLATE_PATH` and `PR_TEMPLATE_SOURCE` into the run context, and the lead reads this file as-is, removes the HTML comments, and fills the placeholders. The section structure must not be hard-coded.
-
-## 7. Deliverables
-
-```mermaid
-flowchart TD
-    Verdict[Source Verification Report<br/>accepted token] --> Report[release-handoff final report]
-    State[feature branch + clean status] --> Report
-    User[Q1/Q2/Q2b/Q3 user selections] --> Report
-    Commands[git/gh commands + exit codes] --> Report
-    Commits[git log base..HEAD commit list] --> Report
-    Probe[Merge Conflict Probe] --> Report
-    PR[one PR row per stage:<br/>created / reused / skipped] --> Report
-    Report --> Done[routing recommendation: done]
-```
-
-The final report requires at least the following.
-
-- per selected stage, the originating final-verification report path and its quoted verdict row
-- the selected stages and the chosen release base
-- the pr-plan rows: stage, head branch, base kind, base branch — the merge order of the stack
-- the run's current branch and run start `git status --short`
-- record of user selections
-- all executed git/gh commands and exit codes
-- the implementation commit list, attributed per stage
-- merge-conflict probe result
-- one PR outcome row per stage: created, reused, or skipped
-- routing recommendation `done`
-
-## 8. Forbidden actions
-
-```mermaid
-flowchart TD
-    RH[release-handoff] --> Allowed[read git/gh, fetch base, merge-tree probe,<br/>push feature branch, create/reuse PR]
-    RH -. forbidden .-> Commit[git add / commit / stash]
-    RH -. forbidden .-> Force[force push or +refspec]
-    RH -. forbidden .-> BasePush[push directly to a release base branch]
-    RH -. forbidden .-> NoVerify[--no-verify / -n]
-    RH -. forbidden .-> Publish[release publish / deploy]
-    RH -. forbidden .-> Edit[source edit]
-    RH -. forbidden .-> Team[TeamCreate or Agent dispatch]
-    RH -. forbidden .-> Merge[gh pr merge or squash-merge]
-    RH -. forbidden .-> Rewrite[rebase / amend / cherry-pick a stage branch]
-```
-
-A failed `git push` must not be retried with weaker safeguards. When a failure such as non-fast-forward occurs, stop and take the user's instruction, and `--force`-family flags are forbidden even if the user requests them.
-
-## 9. Verified code
-
-- [`prompts/profiles/release-handoff.md`](../../prompts/profiles/release-handoff.md)
-- [`templates/reports/release-handoff-input.template.md`](../../templates/reports/release-handoff-input.template.md)
-- [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md)
-- [`scripts/okstra_ctl/wizard/`](../../scripts/okstra_ctl/wizard/)
-- [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py)
-- [`scripts/okstra_ctl/pr_template.py`](../../scripts/okstra_ctl/pr_template.py)
-- [`src/commands/lifecycle/config.mts`](../../src/commands/lifecycle/config.mts)
-- [`scripts/okstra_ctl/handoff.py`](../../scripts/okstra_ctl/handoff.py)
-- [`scripts/okstra_ctl/worktree/`](../../scripts/okstra_ctl/worktree/)

package/docs/task-process/requirements-discovery.md

@@ -1,113 +0,0 @@
-# requirements-discovery 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 routing](#5-deliverables-and-routing)
-- [6. Code reviewed](#6-code-reviewed)
-
-## 1. Purpose
-
-`requirements-discovery` classifies the request before implementation. It determines which of bugfix, feature, improvement, refactor, or ops it is, and chooses whether the next safe phase is `error-analysis` or `implementation-option-selection`. Going directly to planning or implementation is not valid for a new direction. Implementation can only start once a selected direction has been expanded into a separately approved `implementation-planning` report.
-
-## 2. okstra-run wizard flow
-
-```mermaid
-flowchart TD
-    Start[/okstra-run/] --> Check[ensure-installed / paths / check-project]
-    Check --> Pick{new task or existing task?}
-    Pick -->|new| Brief[brief path]
-    Brief --> Suggest{brief frontmatter suggestions?}
-    Suggest -->|yes| GroupPick[task-group pick]
-    Suggest -->|no| GroupText[task-group text]
-    GroupPick --> Id
-    GroupText --> Id
-    Id[task-id pick/text] --> Type[task-type = requirements-discovery]
-    Pick -->|existing| Type
-    Type --> Keep{existing brief?}
-    Keep -->|keep| Base
-    Keep -->|change/no brief| Brief
-    Type --> Base{active task worktree?}
-    Base -->|yes| RoleCount[role-count min..max<br/>omit uses recommended; skip if min==max]
-    Base -->|no| BaseRef[base-ref pick/text]
-    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]
-```
-
-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 W as wizard/render-bundle
-    participant P as prepare_task_bundle
-    participant Prof as requirements-discovery.md
-    participant Git as worktree registry
-    participant FS as task artifacts
-
-    W->>P: task-type=requirements-discovery, brief, base-ref, workers
-    P->>Prof: profile exists, Required workers parsed
-    P->>P: verify installation, upsert project.json
-    P->>P: resolve workers from profile + override
-    P->>Git: create or reuse task worktree
-    P->>P: expand _common-contract include
-    P->>FS: write instruction-set and manifests
-    P->>FS: render workflow currentPhase=requirements-discovery
-    P-->>W: prepared lead prompt
-```
-
-There is no additional hard gate in the runtime for this phase alone. The important gates are: the profile file exists, the brief file exists, the worktree gate requiring base-ref to be resolvable at the first phase, and the gate requiring worker overrides to stay within the profile roster range.
-
-## 4. lead execution flow
-
-```mermaid
-flowchart TD
-    P1[Phase 1 intake<br/>manifest, brief, profile, run manifest, team-state] --> P2[Phase 2 prompts]
-    P2 --> P3[Phase 3 TeamCreate]
-    P3 --> P4[Phase 4/5 dispatch analysers<br/>claude/codex + optional antigravity]
-    P4 --> C[Phase 5.5 convergence<br/>default maxRounds = 1]
-    C --> R[Phase 6 report-writer authors final report]
-    R --> P7[Phase 7 token usage, validate, persist]
-```
-
-`requirements-discovery` has a convergence default of 1 round. This exception is stated in both `render._build_convergence_block()` and `prompts/lead/okstra-lead-contract.md`.
-
-## 5. Deliverables and routing
-
-```mermaid
-flowchart LR
-    RD[requirements-discovery final report] --> Class[work-category classification]
-    RD --> Missing[missing materials / clarification items]
-    RD --> Domain[Domain Alignment<br/>terminology resolution]
-    RD --> Route{next safe phase}
-    Route --> EA[error-analysis]
-    Route --> IOS[implementation-option-selection]
-    Route -. invalid .-> Impl[implementation<br/>not allowed directly]
-```
-
-The final report emphasizes the following in particular.
-
-- evidence-backed routing decision
-- missing input and uncertainty boundary
-- the next phase and safe resume guidance
-- canonical term resolution for `terminology:*` brief items
-- if there is blocking input, `Blocks=next-phase` in the `## 1. Clarification Items` unified table
-
-Non-goals are source edit, plan authoring, build, and deployment.
-
-## 6. Code reviewed
-
-- [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md)
-- [`scripts/okstra_ctl/wizard/`](../../scripts/okstra_ctl/wizard/)
-- [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py)
-- [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py)
-- [`prompts/profiles/requirements-discovery.md`](../../prompts/profiles/requirements-discovery.md)
-- [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)