okstra 0.206.0 → 0.207.0

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

@@ -0,0 +1,233 @@
+# release-handoff process
+
+This directory owns the handoff preparation, stage selection, PR planning, remote reconciliation, and report presentation. Shared verification evidence stays in `okstra_ctl.handoff_verification`; verification recording and CLI assembly stay in `okstra_ctl.handoff`. Generic Git and stage lifecycle operations stay in their common modules.
+
+Report shapes remain in `schemas/final-report-v2.0.schema.json` and `schemas/final-report-v3.0.schema.json`, under `releaseHandoff`. Routing remains in `prompts/lead/phase-routing.md`. The tests beside this specification exercise stage PR bases, origin reconciliation, checkout occupancy, conflict probes, and optional report fields. Common `tests/handoff/` tests cover verification recording and the prepare/CLI boundary.
+
+## Guarantees
+
+| ID | Guarantee | Enforcement |
+|---|---|---|
+| RH-1 | A PR carries a release-ready stage's recorded commit and dependency base | `scripts/okstra_ctl/phases/release_handoff/operations.py::pr_plan` |
+| RH-2 | Diverged origin branches are rejected without force-pushing | `scripts/okstra_ctl/phases/release_handoff/tests/test_handoff_pr_plan.py::test_pr_plan_refuses_a_branch_it_cannot_deliver` |
+| RH-3 | An actively reserved stage is not handed to the main worktree | `scripts/okstra_ctl/phases/release_handoff/tests/test_local_checkout_occupancy.py::test_an_active_stage_row_is_refused` |
+| RH-4 | Missing optional report fields do not prevent rendering | `scripts/okstra_ctl/phases/release_handoff/tests/test_release_handoff_optional_keys.py::test_the_shape_a_skipped_run_writes_renders_end_to_end` |
+
+## 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
+
+- [`profile.md`](profile.md)
+- [`report_assets/release-handoff-input.template.md`](report_assets/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/runtime/python/okstra_ctl/phases/release_handoff/wizard.py

@@ -0,0 +1,84 @@
+"""검증된 단계의 전달 선택과 PR 템플릿 저장 요청."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable, Optional
+
+if TYPE_CHECKING:
+    from okstra_ctl.wizard.state import Prompt, WizardState
+
+ALL_ELIGIBLE_STAGES = "all"
+
+
+def _handoff_msgs(state: WizardState) -> dict:
+    """handoff_stage_pick 의 JSON 텍스트 묶음 (label 미사용 조회용)."""
+    from okstra_ctl.wizard.prompts import _p
+
+    return _p(state.workspace_root, "handoff_stage_pick", blocked="")
+
+
+def build_handoff_stage_pick(state: WizardState, eligibility: list) -> Prompt:
+    from okstra_ctl.wizard.ids import S_HANDOFF_STAGE_PICK
+    from okstra_ctl.wizard.state import Option, Prompt, WizardError
+    from okstra_ctl.wizard.prompts import _opt, _p
+
+    elig = eligibility
+    eligible = [e for e in elig if e["eligible"]]
+    blocked = [e for e in elig if not e["eligible"]]
+    msgs = _handoff_msgs(state)
+    blocked_summary = ("; ".join(
+        f"stage {e['stage']} ({', '.join(e['reasons'])})" for e in blocked)
+        or msgs["labels"]["blocked_none"])
+    if not eligible:
+        raise WizardError(
+            msgs["errors"]["nothing_eligible"].format(blocked=blocked_summary))
+    t = _p(state.workspace_root, "handoff_stage_pick", blocked=blocked_summary)
+    stage_label = t["labels"]["stage"]
+    options: list[Option] = []
+    if len(eligible) > 1:
+        options.append(_opt(ALL_ELIGIBLE_STAGES, t["labels"]["all_stages"].format(
+            stages=", ".join(str(e["stage"]) for e in eligible))))
+    for e in eligible:
+        deps = ", ".join(str(d) for d in e["depends_on"]) or "-"
+        options.append(_opt(str(e["stage"]),
+                            stage_label.format(stage=e["stage"], deps=deps)))
+    return Prompt(
+        step=S_HANDOFF_STAGE_PICK, kind="pick", multi=True,
+        label=t["label"], options=options,
+        echo_template=t["echo_template"],
+    )
+
+
+def submit_handoff_stage_pick(state: WizardState, value: str, eligibility: Callable[[], list]) -> Optional[str]:
+    from okstra_ctl.wizard.state import WizardError
+
+    t = _handoff_msgs(state)
+    picks = [v.strip() for v in (value or "").split(",") if v.strip()]
+    if not picks:
+        raise WizardError(t["errors"]["none_selected"])
+    eligible = {str(e["stage"]) for e in eligibility()
+                if e["eligible"]}
+    if ALL_ELIGIBLE_STAGES in picks:
+        picks = sorted(eligible, key=int)
+    bad = [p for p in picks if p not in eligible]
+    if bad:
+        raise WizardError(t["errors"]["not_eligible"].format(
+            bad=", ".join(bad), eligible=", ".join(sorted(eligible))))
+    nums = sorted({int(p) for p in picks})
+    state.handoff_stages = ",".join(str(n) for n in nums)
+    return t["echo_variants"]["stages"].format(stages=state.handoff_stages)
+
+
+
+def pr_template_persist_actions(state: WizardState) -> list[dict[str, str]]:
+    if not state.pr_template_path:
+        return []
+    if state.pr_template_scope not in ("project", "global"):
+        return []
+    return [
+        {
+            "command": "config.set",
+            "key": "pr-template-path",
+            "scope": state.pr_template_scope,
+            "value": state.pr_template_path,
+        }
+    ]

package/runtime/python/okstra_ctl/phases/requirements_discovery/__init__.py

@@ -0,0 +1 @@
+"""요구사항 확인과 작업 분해 단계의 정책."""

package/runtime/python/okstra_ctl/phases/requirements_discovery/boundary.json

@@ -0,0 +1,9 @@
+{
+  "allowed": "  - work-category classification (bugfix / feature / refactor / ops / improvement)\n  - routing decision as the `routing` object `{nextTaskType, readyWhen, rationale}`: `nextTaskType` is `error-analysis` or `implementation-option-selection` and nothing else — this phase never hands off directly to planning or implementation. Prose alone does not route the task — Phase 7 projects `workflow.nextRecommendedPhase` from `nextTaskType`\n  - missing-input list and clarification requests\n  - approval / confirmation checkpoints recorded for the next phase\n  - one endStateCoverage row per brief end-state id (this phase authors no goal of its own)",
+  "forbidden": [
+    "source code edits of any kind",
+    "implementation planning or detailed design beyond what is required to choose the next phase",
+    "executing builds, migrations, deployments, or any state-mutating command",
+    "starting `error-analysis`, `implementation-planning`, or `implementation` inside this run (each must be a separate run, and `implementation` additionally requires an approved `implementation-planning` deliverable)"
+  ]
+}

package/runtime/{prompts/profiles/requirements-discovery.md → python/okstra_ctl/phases/requirements_discovery/profile.md}

@@ -24,7 +24,6 @@
   - state the reporter's rejection criteria, missing routing inputs, and the evidence boundary behind each recommendation
 - Primary focus areas:
   - classify the work as bugfix, feature, improvement, refactor, or ops
-  - determine whether `error-analysis` or `implementation-option-selection` is the next safe step. Direct `implementation-planning` or `implementation` handoff is never a valid routing target — implementation requires direction selection followed by an approved `implementation-planning` report
   - capture the reporter's **rejection criteria** — the delivered outcome that would make this work wrong or unacceptable — as a routing input. Consume it from the brief's `Desired Outcome` / `Out of Scope` / `Source Material` when present; when it is absent AND it would change the classification (e.g. bugfix vs feature) or the next-phase choice, raise it as one `decision` clarification row with `Evidence checked: none — reporter intent`. Never infer it — this is a reporter-intent signal, the mirror of improvement-discovery's `Anti-goals`
   - record the rejection criteria in `requirementsDiscovery.rejectionCriteria` with the
     `source` that produced it. When it was absent and would not have changed the
@@ -41,11 +40,11 @@
   - A single-item / single-domain request is not fanned out (preserving the current single-routing behaviour).
   - When a request spans two or more domains, or has two or more independently-startable work items,
     publish each item as a `runs/requirements-discovery/fan-out/unit-<NNN>.md` packet.
-    The packet follows the `templates/reports/fan-out-unit.template.md` format, and its frontmatter
+    The packet follows the `scripts/okstra_ctl/phases/requirements_discovery/report_assets/fan-out-unit.template.md` format, and its frontmatter
     `domain`(work-category 5-enum: bugfix / feature / refactor / ops / improvement),
     `depends-on`(an inline list of unit-ids within the same fan-out `[unit-001]`, or `[]` if none),
     `recommended-next-phase`(error-analysis | implementation-option-selection) are filled in.
-    Each packet MUST carry a non-empty `## Requirement Provenance` section whose every bullet is `brief:EB-001` / `brief:PB-001` / `brief:EO-001` — an end-state id the brief declares — or `contract:<rule>`. When the brief pins ids, citing a heading is rejected: every brief carries the same generic headings, so a heading cannot say WHICH reporter line demanded this unit, and a fan-out unit becomes the brief for a whole downstream task. Only a brief authored before the end-state sections existed still takes the older `brief:<heading>` form, and there the heading must literally exist in it. `derived:` is not admissible in a packet — cross-packet derivation cannot be resolved from a single packet, so each unit anchors directly on the brief. A unit you cannot source that way is not a work item: raise it as a clarification row instead of publishing a packet for it. **Enforced:** `validators/validate_fanout.py` `_check_provenance`.
+    Each packet MUST carry a non-empty `## Requirement Provenance` section whose every bullet is `brief:EB-001` / `brief:PB-001` / `brief:EO-001` — an end-state id the brief declares — or `contract:<rule>`. When the brief pins ids, citing a heading is rejected: every brief carries the same generic headings, so a heading cannot say WHICH reporter line demanded this unit, and a fan-out unit becomes the brief for a whole downstream task. Only a brief authored before the end-state sections existed still takes the older `brief:<heading>` form, and there the heading must literally exist in it. `derived:` is not admissible in a packet — cross-packet derivation cannot be resolved from a single packet, so each unit anchors directly on the brief. A unit you cannot source that way is not a work item: raise it as a clarification row instead of publishing a packet for it. **Enforced:** `scripts/okstra_ctl/phases/requirements_discovery/validation.py` `_check_provenance`.
   - in `runs/requirements-discovery/fan-out/index.md`, list the packets in depends-on topological order
     as a numbered list (`1. unit-001`) (a generated view; explicitly do not hand-edit). The depends-on graph
     must be a DAG — `validate_fanout` rejects a cycle as a validation failure, so if a cycle appears,

package/runtime/python/okstra_ctl/{report_html/view_models/requirements_discovery.py → phases/requirements_discovery/report.py}

@@ -1,9 +1,9 @@
 """Human-first requirements-discovery view model."""
 from __future__ import annotations
 
-from ..common import evidence_index
-from ..models import HumanReportView, VisualEdge, VisualNode
-from ..visualizations import decision_flow_figure
+from okstra_ctl.report_html.common import evidence_index
+from okstra_ctl.report_html.models import HumanReportView, VisualEdge, VisualNode
+from okstra_ctl.report_html.visualizations import decision_flow_figure
 
 # Record fields this template anchors as `id-<row id>` (see
 # `HumanReportView.anchored_fields`); ids elsewhere land in the ledger.

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

@@ -0,0 +1,132 @@
+# requirements-discovery process
+
+## Guarantees
+
+| ID | Guarantee | Enforcement |
+|---|---|---|
+| RD-1 | Optional fan-out absence is accepted | `scripts/okstra_ctl/phases/requirements_discovery/validation.py::validate_fanout` |
+| RD-2 | Each packet cites an admissible brief or contract source | `scripts/okstra_ctl/phases/requirements_discovery/validation.py::_check_provenance` |
+| RD-3 | Dependency cycles and unknown units are rejected | `scripts/okstra_ctl/phases/requirements_discovery/fanout.py::topological_order` |
+| RD-4 | The index lists every packet in dependency order | `scripts/okstra_ctl/phases/requirements_discovery/validation.py::validate_fanout` |
+| RD-5 | Packet destinations use the common routing contract | `scripts/okstra_ctl/report_routing.py::fanout_routing_errors` |
+| RD-6 | Human intent and terminology are resolved from inspected evidence | unenforced — worker instructions and lead review; no generic validator proves intent semantics |
+
+## 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/`](../../wizard)
+- [`scripts/okstra_ctl/run.py`](../../run.py)
+- [`scripts/okstra_ctl/workflow.py`](../../workflow.py)
+- [`scripts/okstra_ctl/phases/requirements_discovery/profile.md`](profile.md)
+- [`prompts/lead/okstra-lead-contract.md`](../../../../prompts/lead/okstra-lead-contract.md)
+
+## Phase ownership and validation
+
+`profile.md` owns request discovery and decomposition instructions; `profile.json` owns roles. `validation.py` owns fan-out packet identity, work category, requirement provenance, dependency and index checks. `fanout.py` orders dependencies and rejects cycles and unknown units. `report.py` and `report_assets/` own the report body and fan-out packet template.
+
+Common scope-provenance helpers continue to define brief end-state identifiers and citation grammar. Shared schemas remain in `schemas/final-report-v2.0.schema.json` and `schemas/final-report-v3.0.schema.json` under `requirementsDiscovery`. The common lead's `prompts/lead/phase-routing.md` owns destination selection; `report_routing.py` checks packet destinations.
+
+`tests/test_fanout.py` checks real packet files, missing and invalid provenance, dependency cycles, missing dependencies and index order. The common validator calls `validate_requirements_discovery_fanout` only for this task type, preserving the optional fan-out behavior and the `requirements-discovery:` error prefix. Source inspection and human-intent decisions remain worker instructions rather than machine-enforced semantic claims.

package/runtime/{validators/validate_fanout.py → python/okstra_ctl/phases/requirements_discovery/validation.py}

@@ -6,25 +6,19 @@ and a `fan-out/` directory exists under the run dir.
 from __future__ import annotations
 
 import re
-import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 
-_VALIDATORS_DIR = Path(__file__).resolve().parent
-for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "python"):
-    if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
-        sys.path.insert(0, str(_ssot_dir))
-
-from okstra_ctl.work_categories import WORK_CATEGORIES  # noqa: E402
-from okstra_ctl.fanout import topological_order, CycleError  # noqa: E402
-from okstra_ctl.scope_provenance import (  # noqa: E402
+from okstra_ctl.report_routing import fanout_routing_errors
+from okstra_ctl.work_categories import WORK_CATEGORIES
+from .fanout import topological_order, CycleError
+from okstra_ctl.scope_provenance import (
     brief_citation_problem,
     brief_end_state_ids,
     brief_headings,
     parse_source,
 )
 
-_NEXT_PHASES = ("error-analysis", "implementation-planning")
 _UNIT_RE = re.compile(r"unit-\d{3}")
 # index.md 번호목록 항목에서만 unit-NNN 을 추출 — 내러티브 문장 중복 방지
 _INDEX_ENTRY_RE = re.compile(r"^\s*\d+\.\s+(unit-\d{3})\b", re.MULTILINE)
@@ -138,8 +132,7 @@ def validate_fanout(run_dir: Path, brief_path: Path | None = None) -> Validation
             errors.append(f"{pkt.name}: unit-id {uid!r} != filename stem {pkt.stem!r}")
         if fm.get("domain") not in WORK_CATEGORIES:
             errors.append(f"{pkt.name}: domain {fm.get('domain')!r} not in {WORK_CATEGORIES}")
-        if fm.get("recommended-next-phase") not in _NEXT_PHASES:
-            errors.append(f"{pkt.name}: recommended-next-phase not in {_NEXT_PHASES}")
+        errors.extend(fanout_routing_errors(pkt.name, fm.get("recommended-next-phase")))
         units[pkt.stem] = _parse_deps(fm.get("depends-on", ""))
 
     if not units:
@@ -167,3 +160,9 @@ def validate_fanout(run_dir: Path, brief_path: Path | None = None) -> Validation
             errors.append(f"index.md order {listed} is not the topological order {order}")
 
     return ValidationResult(ok=not errors, errors=errors)
+
+
+def validate_requirements_discovery_fanout(run_dir, failures, brief_path=None) -> None:
+    """단계 산출물 오류를 공통 실행 검증의 오류 목록에 같은 접두로 전달한다."""
+    result = validate_fanout(Path(run_dir), brief_path)
+    failures.extend(f"requirements-discovery: {error}" for error in result.errors)

package/runtime/python/okstra_ctl/phases/technical_verification/__init__.py

@@ -0,0 +1 @@
+"""기술 검증 단계의 입력과 관측 증거 정책."""

package/runtime/python/okstra_ctl/phases/technical_verification/boundary.json

@@ -0,0 +1,9 @@
+{
+  "allowed": "  - falsifiable experiment plans for the frozen unresolved facts\n  - dependency installation, source experiments, tests and builds only in this run's experiment copies\n  - command logs, observed signals and per-fact supported/refuted/inconclusive/not-run results\n  - return to implementation-option-selection with evidence, without adoption or plan approval",
+  "forbidden": [
+    "source edits or installs in the project checkout, task worktree, or another worker's experiment copy",
+    "production credentials, remote writes, deployments, migrations, publishing, commits or merging experiments into product branches",
+    "marking candidates feasible, selecting a direction, approving a plan, or declaring task acceptance",
+    "starting another lifecycle phase inside this run; return the evidence to implementation-option-selection"
+  ]
+}