okstra 0.205.1 → 0.206.1

package/runtime/validators/validate_analysis_report.py

@@ -15,6 +15,16 @@ for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "
         sys.path.insert(0, str(_ssot_dir))
 
 from okstra_ctl.analysis_inputs import ANALYSIS_TASK_TYPES
+from okstra_ctl.phases.change_impact_analysis.validation import (
+    EVIDENCE_COLLECTIONS as CHANGE_IMPACT_EVIDENCE_COLLECTIONS,
+    validate_change_impact_semantics,
+)
+from okstra_ctl.phases.feature_analysis.validation import (
+    EVIDENCE_COLLECTIONS as FEATURE_EVIDENCE_COLLECTIONS,
+    _validate_feature_semantics,
+)
+from okstra_ctl.analysis_scope import _normalized_project_path, _path_is_included
+from okstra_ctl.phases.project_analysis.validation import validate_project_semantics
 from okstra_ctl.final_report_paths import final_report_data_path
 from okstra_ctl.paths import RunRef
 from okstra_ctl.report_views import analysis_review_context
@@ -35,19 +45,8 @@ _EVIDENCE_COLLECTIONS = {
         "externalSystems",
         "featureIndex",
     ),
-    "feature-analysis": (
-        "flows",
-        "domainRules",
-        "stateChanges",
-        "externalInteractions",
-    ),
-    "change-impact-analysis": (
-        "preservedBehaviors",
-        "impactItems",
-        "dependencyBlastRadius",
-        "testImpact",
-        "operationalImpact",
-    ),
+    "feature-analysis": FEATURE_EVIDENCE_COLLECTIONS,
+    "change-impact-analysis": CHANGE_IMPACT_EVIDENCE_COLLECTIONS,
 }
 _ANALYSIS_PARENT_KEYS = {
     "project-analysis": "projectAnalysis",
@@ -111,33 +110,6 @@ def validate_analysis_snapshot(
         )
 
 
-def _normalized_project_path(path: object) -> PurePosixPath | None:
-    if not isinstance(path, str):
-        return None
-    raw = path.strip().rstrip("/")
-    if not raw or raw == "." or raw.startswith("/"):
-        return None
-    if any(part in {"", ".", ".."} for part in raw.split("/")):
-        return None
-    normalized = PurePosixPath(raw)
-    if normalized.is_absolute():
-        return None
-    return normalized
-
-
-def _path_is_included(path: object, included_paths: list[object]) -> bool:
-    candidate = _normalized_project_path(path)
-    if candidate is None:
-        return False
-    for raw in included_paths:
-        included = _normalized_project_path(raw)
-        if included is not None and (
-            candidate == included or included in candidate.parents
-        ):
-            return True
-    return False
-
-
 def _validate_included_paths(included_paths: list[object], errors: list[str]) -> None:
     for index, path in enumerate(included_paths):
         if _normalized_project_path(path) is None:
@@ -201,90 +173,6 @@ def _validate_all_current_code_evidence(
         )
 
 
-def _validate_project_semantics(data: dict, errors: list[str]) -> None:
-    common = data.get("analysisCommon") or {}
-    included = ((common.get("scope") or {}).get("includedPaths") or [])
-    analysis = data.get("projectAnalysis") or {}
-    for row in analysis.get("featureIndex") or []:
-        if not isinstance(row, dict):
-            continue
-        entry = row.get("representativeEntryPoint") or {}
-        if not _path_is_included(entry.get("path"), included):
-            errors.append(
-                f"projectAnalysis.featureIndex `{row.get('id') or '?'}` representative "
-                "entry point must be inside analysisCommon.scope.includedPaths"
-            )
-    _validate_component_references(analysis, errors)
-
-
-def _validate_component_references(analysis: dict, errors: list[str]) -> None:
-    """Every componentId a row names has to be a component this report declares.
-
-    The reader clicks these — they render as links to the component's row — so
-    a reference to a component that was never listed is a dead anchor, and one
-    to a component that exists under a different id is worse: it reads as a
-    relationship the analysis never found.
-    """
-    declared = {
-        row.get("id")
-        for row in analysis.get("components") or []
-        if isinstance(row, dict) and row.get("id")
-    }
-    if not declared:
-        return
-
-    def check(component_id: object, where: str) -> None:
-        if isinstance(component_id, str) and component_id and component_id not in declared:
-            errors.append(f"{where} names component `{component_id}`, which is not declared")
-
-    for row in analysis.get("internalInterfaces") or []:
-        if not isinstance(row, dict):
-            continue
-        where = f"projectAnalysis.internalInterfaces `{row.get('id') or '?'}`"
-        check(row.get("ownerComponentId"), where)
-        for consumer in row.get("consumers") or []:
-            check(consumer, where)
-    for row in analysis.get("workflows") or []:
-        if not isinstance(row, dict):
-            continue
-        for step in row.get("steps") or []:
-            if isinstance(step, dict):
-                check(step.get("componentId"), f"projectAnalysis.workflows `{row.get('id') or '?'}`")
-
-
-def _validate_feature_semantics(data: dict, errors: list[str]) -> None:
-    analysis = data.get("featureAnalysis") or {}
-    common_target = (((data.get("analysisCommon") or {}).get("scope") or {}).get(
-        "resolvedTarget"
-    ) or {})
-    feature_target = analysis.get("target") or {}
-    for field in ("inputMode", "requestedValue"):
-        if feature_target.get(field) != common_target.get(field):
-            errors.append(
-                f"featureAnalysis.target.{field} must match "
-                f"analysisCommon.scope.resolvedTarget.{field}"
-            )
-    resolved_feature = common_target.get("feature") or {}
-    if common_target.get("inputMode") == "feature-index" and (
-        feature_target.get("featureId") != resolved_feature.get("id")
-    ):
-        errors.append(
-            "featureAnalysis.target.featureId must match the resolved feature id"
-        )
-
-
-def _validate_change_impact_semantics(data: dict, errors: list[str]) -> None:
-    analysis = data.get("changeImpactAnalysis") or {}
-    allowed = {"constraint", "unknown"}
-    for index, row in enumerate(analysis.get("planningInputs") or []):
-        if not isinstance(row, dict):
-            continue
-        for field in sorted(set(row) - allowed):
-            errors.append(
-                f"changeImpactAnalysis.planningInputs[{index}] forbids `{field}`; "
-                "planning inputs may contain constraints and unknowns only"
-            )
-
 
 def _required_worker_roles(
     run_manifest: dict, errors: list[str]
@@ -475,11 +363,11 @@ def validate_analysis_semantics(
     )
     _validate_all_current_code_evidence(task_type, data, errors)
     if task_type == "project-analysis":
-        _validate_project_semantics(data, errors)
+        validate_project_semantics(data, errors)
     elif task_type == "feature-analysis":
         _validate_feature_semantics(data, errors)
     elif task_type == "change-impact-analysis":
-        _validate_change_impact_semantics(data, errors)
+        validate_change_impact_semantics(data, errors)
     _validate_scope_before_dispatch(
         data, analysis_worker_roles, reporter_confirmation, errors
     )

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/runtime/python/okstra_ctl/report_html/view_models/implementation_planning.py

@@ -1,147 +0,0 @@
-"""Human-first implementation-planning view and approval state."""
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-
-from ..common import evidence_index
-from ..models import HumanReportView, VisualEdge, VisualNode
-from ..visualizations import stage_map_figure
-
-
-@dataclass(frozen=True)
-class PlanApprovalState:
-    option_names: tuple[str, ...]
-    recommended_option: str
-    disabled_reason: str
-    blocker_ids: tuple[str, ...]
-    show_option_selector: bool = True
-    reentry_command: str = ""
-
-
-def resolve_recommended_option(rec_name: str, names: tuple[str, ...]) -> str:
-    if rec_name in names:
-        return rec_name
-    matches = [
-        name
-        for name in names
-        if rec_name and (name.startswith(rec_name) or rec_name.startswith(name))
-    ]
-    return matches[0] if len(matches) == 1 else names[0]
-
-
-def plan_approval_state(data: dict) -> PlanApprovalState | None:
-    planning = data.get("implementationPlanning")
-    if not isinstance(planning, dict):
-        return None
-    blockers = tuple(
-        row["id"]
-        for row in data.get("clarificationItems", [])
-        if row.get("blocks") == "approval"
-        and row.get("status") in {"open", "answered"}
-    )
-    reason = f"{len(blockers)} approval blocker(s) unresolved" if blockers else ""
-    if planning.get("planningContract") == "selected-direction":
-        if planning.get("outcome") == "direction-invalidated" and not reason:
-            reason = "selected direction invalidated"
-        task_key = (data.get("header") or {}).get("taskKey", "")
-        reentry_command = (
-            f"/okstra-run task-key={task_key} "
-            "task-type=implementation-option-selection"
-            if planning.get("outcome") == "direction-invalidated" and task_key
-            else ""
-        )
-        return PlanApprovalState(
-            (), "", reason, blockers, False, reentry_command
-        )
-    names = tuple(
-        row["name"]
-        for row in planning.get("optionCandidates", [])
-        if isinstance(row, dict) and row.get("name")
-    )
-    if not names:
-        return None
-    recommended = planning.get("recommendedOption", {}).get("name", "")
-    return PlanApprovalState(
-        names,
-        resolve_recommended_option(recommended, names),
-        reason,
-        blockers,
-    )
-
-
-def _stage_figure(planning: dict):
-    nodes = tuple(
-        VisualNode(
-            f"stage-{row['stage']}",
-            f"Stage {row['stage']} · {row['title']}",
-            "stage",
-            "planned",
-            row["exitContractSummary"],
-        )
-        for row in planning["stageMap"]
-    )
-    edges = tuple(
-        VisualEdge(f"stage-{dependency}", f"stage-{row['stage']}", "precedes", "dependency")
-        for row in planning["stageMap"]
-        for dependency in re.findall(r"\d+", row["dependsOn"])
-    )
-    return stage_map_figure(nodes=nodes, edges=edges, title="Implementation stage dependencies")
-
-
-# Record fields this template anchors as `id-<row id>` (see
-# `HumanReportView.anchored_fields`). The implementer-facing tables the
-# approver does not read — validation checklist, cross-project dependencies,
-# migration risk, rollback — are not drawn, so their rows land in the ledger.
-ANCHORED_FIELDS = (
-    "implementationPlanning.directionRealization.fileStructure",
-    "implementationPlanning.directionRealization.planningInvariants",
-    "implementationPlanning.optionCandidates.fileStructure",
-    "implementationPlanning.designPreparation.items",
-    "implementationPlanning.requirementCoverage",
-    "implementationPlanning.planBodyVerification.planItems",
-    "implementationPlanning.supersessionLedger",
-)
-
-
-def build_implementation_planning_view(data: dict) -> HumanReportView:
-    planning = data["implementationPlanning"]
-    figure = _stage_figure(planning) if planning.get("stageMap") else None
-    approval = plan_approval_state(data)
-    activities = tuple(
-        row for row in data.get("agentActivity", []) if isinstance(row, dict)
-    )
-    decision_cards = tuple(
-        row
-        for row in data.get("clarificationItems", [])
-        if isinstance(row, dict)
-        and row.get("blocks") == "approval"
-        and isinstance(row.get("approvalContext"), dict)
-    )
-    context = {
-        "humanSummary": data["humanSummary"],
-        "planning": planning,
-        "narrative": planning.get("userNarrative", {}),
-        "stageFigure": figure,
-        "approval": approval,
-        "openDecisions": [
-            row
-            for row in data.get("clarificationItems", [])
-            if isinstance(row, dict)
-            and row.get("blocks") == "approval"
-            and row.get("status") in {"open", "answered"}
-        ],
-        "agentActivities": activities,
-        "activityById": {
-            row["activityId"]: row for row in activities if row.get("activityId")
-        },
-        "decisionCards": decision_cards,
-        "evidenceIndex": evidence_index(data, ANCHORED_FIELDS),
-    }
-    return HumanReportView(
-        "implementation-planning",
-        "html/tasks/implementation-planning.template.html",
-        context,
-        (figure,) if figure is not None else (),
-        anchored_fields=ANCHORED_FIELDS,
-    )