okstra 0.175.1 → 0.176.0

package/runtime/prompts/profiles/final-verification.md

@@ -3,16 +3,19 @@
 ```yaml
 roles:
   - role: verifier
-    count: 2
-    optionalCount: 3
+    min: 2
+    recommended: 2
+    max: 5
     duty: acceptance-verifier
-    minDistinctProviders: 2
   - role: critic
-    count: 0
-    optionalCount: 1
+    min: 0
+    recommended: 0
+    max: 1
     duty: acceptance-critic
   - role: report-writer
-    count: 1
+    min: 1
+    recommended: 1
+    max: 1
     duty: report-writer
 ```
 
@@ -79,7 +82,7 @@ roles:
   - **Validation Evidence**: for every requirement in the originating plan or task brief, cite the artifact (commit SHA, test output, log line, MCP SELECT result) that demonstrates coverage. Paraphrased "verified" claims without an artifact are rejected.
   - **Read-only command log**: any pre-existing test/validation command touched during this run MUST be listed with its exact command line and one honest status — `executed` (ran; carries its exit code) / `advisory` (external Tier 3 did not PASS; carries observed/expected results and remains user-owned) / `env-unavailable` (should run but cannot in this environment — missing replica DB, container, or service; carries the reason, never a faked pass) / `not-configured` (no such qa-command tier) / `rejected` (a mutating/denied token — skipped, carries the denied token). A check that could not run locally is recorded as `env-unavailable` or `advisory` according to the external QA policy — never silently dropped and never reported as `executed` with an invented exit code. Mutating-command prohibition is the shared read-only boundary (see Non-goals); it is not restated per row.
   - **Could-not-verify roll-up (§5.8.9)**: the template mechanically aggregates every not-confirmed check into one scannable list — `gap` requirement-coverage rows, `advisory` / `not-configured` / `env-unavailable` / `rejected` command rows, and `blocked` manual tests. You do not hand-author it, but you MUST give those rows their honest status so nothing unverified hides across sections: a check silently recorded as `executed`/`covered` will not surface in the roll-up. This is okstra's answer to "say what could not be verified this run."
-  - **Routing recommendation**: the next safe phase — one of `release-handoff`, `done`, `error-analysis`, `implementation-option-selection`, `implementation-planning` — tied to the verdict and blocker list. `release-handoff` is allowed ONLY when the Verdict Token is `accepted`. `release-handoff` is additionally allowed ONLY when the verification scope (the `Verification scope:` line of the injected `VERIFICATION_TARGET` block, recorded as the report's `verificationScope` field) is `whole-task`; a `single-stage` accepted run routes to `release-handoff(stage-group)` (or `implementation` / `done`); plain `release-handoff` remains whole-task-only. Enforcement: `validators/validate-run.py` rejects a `single-stage` report whose routing cites plain `release-handoff`.
+  - **Routing recommendation**: `finalVerification.routingRecommendation` is an **object** with exactly two fields — `target`, one value of the enum below, and `rationale`, the sentence tying that choice to the verdict and the blocker list. Free routing prose is not the field; a target named only in the prose does not route the task, because Phase 7 projects `workflow.nextRecommendedPhase` from `target` alone. The seven allowed targets are `release-handoff`, `release-handoff(stage-group)`, `error-analysis`, `implementation-option-selection`, `implementation-planning`, `implementation`, and `done`. Both `release-handoff` forms are allowed ONLY when the Verdict Token is `accepted`. Plain `release-handoff` is additionally allowed ONLY when the verification scope (the `Verification scope:` line of the injected `VERIFICATION_TARGET` block, recorded as the report's `verificationScope` field) is `whole-task`; a `single-stage` accepted run routes to `release-handoff(stage-group)` (or `implementation` / `done`) instead. `done` ends the lifecycle here. Enforcement: `schemas/final-report-v2.0.schema.json` rejects a `target` outside the enum, a missing `rationale`, and a string in place of the object; `validators/validate-run.py` rejects a missing `target`, a non-`accepted` verdict routed to either `release-handoff` form, and a `single-stage` report whose routing cites plain `release-handoff`.
   - **Verified-row recording** (single-stage scope only): when the Verdict Token is `accepted`, the lead MUST run `okstra handoff record-verified --plan-run-root <plan-run-root> --stage <N> --report-path <final-report.md path> --data-json <final-report data.json path>` and quote the command + exit code in the report. The helper re-validates taskType/scope/verdict from data.json, so a non-accepted or whole-task report is rejected at the tool layer. **Enforced:** `validators/validate-run.py` `_validate_verified_row_recorded` requires a `verified` row in `runs/implementation-planning/consumers.jsonl` for every accepted stage — the helper validated its own inputs but nothing checked it had ever run, leaving reports that said `accepted` while the registry said unverified, so the stage was never offered for a stage-group PR.
 - Clarification request policy (phase-specific addendum — shared policy is in `_common-contract.md`):
   - populate `## 1. Clarification Items` only when a blocker hinges on information only the user can supply (deployment intent, intended target environment, business-rule interpretation); use `Blocks=next-phase` for items that gate continuing to release-handoff

package/runtime/prompts/profiles/implementation-option-selection.md

@@ -3,15 +3,19 @@
 ```yaml
 roles:
   - role: designer
-    count: 3
-    optionalCount: 2
+    min: 3
+    recommended: 3
+    max: 5
     duty: direction-selection-worker
-    minDistinctProviders: 3
   - role: report-writer
-    count: 1
+    min: 1
+    recommended: 1
+    max: 1
     duty: report-writer
   - role: verifier
-    count: 0
+    min: 0
+    recommended: 0
+    max: 0
     duty: reverification-worker
     dynamic: true
 ```

package/runtime/prompts/profiles/implementation-planning.md

@@ -3,19 +3,24 @@
 ```yaml
 roles:
   - role: planner
-    count: 2
-    optionalCount: 3
+    min: 2
+    recommended: 2
+    max: 5
     duty: planning-worker
-    minDistinctProviders: 2
   - role: critic
-    count: 0
-    optionalCount: 1
+    min: 0
+    recommended: 0
+    max: 1
     duty: acceptance-critic
   - role: report-writer
-    count: 1
+    min: 1
+    recommended: 1
+    max: 1
     duty: report-writer
   - role: verifier
-    count: 0
+    min: 0
+    recommended: 0
+    max: 0
     duty: reverification-worker
     dynamic: true
 ```
@@ -36,6 +41,7 @@ roles:
   - never plan around an unconfirmed `intent-inference` augmentation as if it were a settled requirement. Treat the inference as settled ONLY when a `[CONFIRMED …]` marker sits on the matching `intent-check:` row after the precondition runs; absent the marker it stays a `Blocks=approval` clarification item per the precondition's `skipped` branch.
   - `conversion-block:` rows are handled by the precondition; planning around an untranslated reporter phrase is forbidden until it is resolved.
 - Worker planning procedure:
+  - **Ticket Tagging.** Tag every section 1–5 item with its related ticket. Use `Issue / Ticket`, fall back to Task ID, then `unknown`; comma-separate multiple tickets.
   - route by the planning input contract before analysis. A run carrying `selected-direction.json` uses the selected-direction procedure. Only a legacy rerun without that snapshot uses candidate comparison.
   - **Selected-direction planning procedure** — perform these steps in order and no others:
     1. Read `selected-direction.json` and the original requirements ledger end-to-end.

package/runtime/prompts/profiles/implementation.md

@@ -3,15 +3,19 @@
 ```yaml
 roles:
   - role: implementer
-    count: 1
+    min: 1
+    recommended: 1
+    max: 1
     duty: implementation-executor
   - role: verifier
-    count: 2
-    optionalCount: 1
+    min: 2
+    recommended: 2
+    max: 3
     duty: implementation-verifier
-    minDistinctProviders: 2
   - role: report-writer
-    count: 1
+    min: 1
+    recommended: 1
+    max: 1
     duty: report-writer
 ```
 

package/runtime/prompts/profiles/improvement-discovery.md

@@ -3,15 +3,19 @@
 ```yaml
 roles:
   - role: analyser
-    count: 3
-    optionalCount: 2
+    min: 3
+    recommended: 3
+    max: 5
     duty: discovery-worker
-    minDistinctProviders: 3
   - role: report-writer
-    count: 1
+    min: 1
+    recommended: 1
+    max: 1
     duty: report-writer
   - role: verifier
-    count: 0
+    min: 0
+    recommended: 0
+    max: 0
     duty: reverification-worker
     dynamic: true
 ```
@@ -57,7 +61,7 @@ roles:
   - Stop conditions (OR): all questions resolved / budget exhausted / user signals proceed.
   - Lead persists the round at `<RUN_DIR>/state/phase-1.5-grilling.md` with one section per question (question / recommended / user answer) and a closing `Resolved scope` / `Resolved lenses` block. Worker prompts use this resolved block as the authoritative scope and lens definition.
   - The same log includes `## Primary Pass Assignments` with a `Worker ID | Primary lens` table. It contains every selected analyser exactly once in `requiredWorkerRoles` order; the lead derives it from the resolved roster and lenses rather than provider catalog order.
-  - After writing the log and before Phase 4 dispatch, the lead injects its **absolute path** into every analyser prompt as the `**Phase 1.5 Grilling Log:** <absolute-path>` anchor header (see `templates/worker-prompt-preamble.md` §"Anchor headers"). This is the improvement-discovery counterpart to the `**Worktree:**` / `**Verification …:**` anchors that implementation / final-verification inject: workers read the log from this explicit path rather than re-deriving `<RUN_DIR>`. The path is byte-identical across all analysers, so it does not break the dispatch-prompt invariant.
+  - After writing the log and before Phase 4 dispatch, the lead injects its **absolute path** into every analyser prompt as the `**Phase 1.5 Grilling Log:** <absolute-path>` anchor header (see `okstra_ctl.worker_prompt_headers.worker_prompt_headers()`). This is the improvement-discovery counterpart to the `**Worktree:**` / `**Verification …:**` anchors that implementation / final-verification inject: workers read the log from this explicit path rather than re-deriving `<RUN_DIR>`. The path is byte-identical across all analysers, so it does not break the dispatch-prompt invariant.
 - Decision-tree walk (bounded):
   - When candidates branch on a structural question (e.g. "is module X meant to own this responsibility?"), resolve via `Read` / `Grep` first. Only escalate to the user inside the Phase 1.5 budget.
 - Expected output emphasis:

package/runtime/prompts/profiles/project-analysis.md

@@ -3,15 +3,19 @@
 ```yaml
 roles:
   - role: analyser
-    count: 2
-    optionalCount: 3
+    min: 2
+    recommended: 2
+    max: 5
     duty: analysis-worker
-    minDistinctProviders: 2
   - role: report-writer
-    count: 1
+    min: 1
+    recommended: 1
+    max: 1
     duty: report-writer
   - role: verifier
-    count: 0
+    min: 0
+    recommended: 0
+    max: 0
     duty: reverification-worker
     dynamic: true
 ```

package/runtime/prompts/profiles/requirements-discovery.md

@@ -3,19 +3,24 @@
 ```yaml
 roles:
   - role: analyser
-    count: 2
-    optionalCount: 3
-    duty: analysis-worker
-    minDistinctProviders: 2
+    min: 2
+    recommended: 2
+    max: 5
+    duty: discovery-worker
   - role: critic
-    count: 0
-    optionalCount: 1
+    min: 0
+    recommended: 0
+    max: 1
     duty: scope-critic
   - role: report-writer
-    count: 1
+    min: 1
+    recommended: 1
+    max: 1
     duty: report-writer
   - role: verifier
-    count: 0
+    min: 0
+    recommended: 0
+    max: 0
     duty: reverification-worker
     dynamic: true
 ```
@@ -37,7 +42,8 @@ roles:
   - `intent-inference` augmentations whose paired `intent-check:` row carries `[CONFIRMED …]` are treated as **confirmed**; trust the confirmation text in `## Reporter Confirmations` over the original inference if they differ. Unconfirmed `intent-inference` rows under `reporter-confirmations: skipped` follow the precondition's `skipped` branch above.
   - `conversion-block:` rows are explicit "translation failed" signals — never attempt to resolve them by inference here; the precondition above already handled them.
 - Worker discovery procedure:
-  - classify the request and cite the evidence that determines both its work category and safest next phase
+  - **Ticket Tagging.** Tag every section 1–5 item with its related ticket. Use `Issue / Ticket`, fall back to Task ID, then `unknown`; comma-separate multiple tickets.
+  - classify the request and cite the evidence that supports a recommended work category and safest next phase. The lead's Phase Routing settles the next phase.
   - identify independently startable decomposition candidates without publishing or rendering fan-out artifacts; preserve every directed dependency from `Related Task Graph`
   - resolve codebase-answerable ambiguity by inspection and record file:line evidence; return only human-owned decisions as clarification candidates with the evidence already checked
   - state the reporter's rejection criteria, missing routing inputs, and the evidence boundary behind each recommendation

package/runtime/prompts/wizard/prompts.ko.json

@@ -480,11 +480,28 @@
         "no": "아니오 — 단계별로 다시 입력"
       }
     },
+    "leader_session": {
+      "label": "리더는 현재 세션 모델을 씁니다 (읽기 전용): {model_ref}{effort_suffix}",
+      "echo_template": "leader-session: {value}",
+      "options": {
+        "continue": "계속"
+      },
+      "effort_suffix": " · effort {effort}"
+    },
     "role_count": {
-      "label": "{role} 역할 인스턴스 수를 선택하세요 ({minimum}..{maximum}, 기본 {default})",
+      "label": "{role} 역할 인스턴스 수를 선택하세요 ({minimum}..{maximum}, 적정 {default})",
       "echo_template": "role-count: {value}",
       "options": {
         "count": "{count}개{default_suffix}",
+        "default_suffix": " (적정)"
+      }
+    },
+    "role_add": {
+      "label": "선택 역할 {role} 을(를) 이번 run 에 추가할까요? (최대 {maximum}개, 기본: 추가 안 함)",
+      "echo_template": "role-add: {value}",
+      "options": {
+        "skip": "추가 안 함{default_suffix}",
+        "add": "{count}개 추가",
         "default_suffix": " (기본)"
       }
     },

package/runtime/python/okstra_ctl/adapters/runtime/__init__.py

@@ -0,0 +1 @@
+"""Execution-surface adapters."""

package/runtime/python/okstra_ctl/adapters/runtime/assembly.py

@@ -0,0 +1,27 @@
+"""Build the injected execution-surface chain for one planned surface."""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from ...domain.worker_runtime import SURFACE_CLI_WRAPPER, SURFACE_CMUX_PANE
+from ...ports.worker_runtime import WorkerRuntimePort
+from .cli_wrapper import CliWrapperRuntime
+from .cmux import CmuxRuntime
+
+
+def runtime_chain(planned_surface: str) -> tuple[WorkerRuntimePort, ...]:
+    cli = CliWrapperRuntime()
+    if planned_surface == SURFACE_CLI_WRAPPER:
+        return (cli,)
+    if planned_surface == SURFACE_CMUX_PANE:
+        return (CmuxRuntime(), cli)
+    raise ValueError(f"unknown execution surface: {planned_surface}")
+
+
+def port_for(
+    chain: Sequence[WorkerRuntimePort], surface: str
+) -> WorkerRuntimePort:
+    for port in chain:
+        if port.surface == surface:
+            return port
+    raise KeyError(surface)

package/runtime/python/okstra_ctl/adapters/runtime/cli_wrapper.py

@@ -0,0 +1,49 @@
+"""Run a worker as a lead-owned subprocess."""
+from __future__ import annotations
+
+import subprocess
+import uuid
+
+from ...domain.worker_runtime import (
+    SURFACE_CLI_WRAPPER,
+    ProgressEvent,
+    RuntimeHandle,
+    WorkerSpawnRequest,
+)
+
+
+class CliWrapperRuntime:
+    surface = SURFACE_CLI_WRAPPER
+
+    def __init__(self) -> None:
+        self._children: dict[str, subprocess.Popen[str]] = {}
+
+    def spawn(self, request: WorkerSpawnRequest) -> RuntimeHandle:
+        process = subprocess.Popen(
+            list(request.command), cwd=request.cwd, text=True
+        )
+        identifier = uuid.uuid4().hex
+        self._children[identifier] = process
+        return RuntimeHandle(
+            surface=self.surface,
+            identifier=identifier,
+            waitable=True,
+        )
+
+    def close(self, handle: RuntimeHandle) -> None:
+        return None
+
+    def wait(self, handle: RuntimeHandle) -> int:
+        process = self._children[handle.identifier]
+        return process.wait()
+
+    def terminate(self, handle: RuntimeHandle) -> None:
+        process = self._children[handle.identifier]
+        if process.poll() is None:
+            process.terminate()
+
+    def notify(self, event: ProgressEvent) -> None:
+        return None
+
+    def restore_lead(self) -> None:
+        return None

package/runtime/python/okstra_ctl/adapters/runtime/cmux.py

@@ -0,0 +1,74 @@
+"""Open and signal workers on a cmux pane surface."""
+from __future__ import annotations
+
+import subprocess
+
+from ... import cmux
+from ...domain.worker_runtime import (
+    SURFACE_CMUX_PANE,
+    EnvironmentBlocked,
+    ProgressEvent,
+    RuntimeHandle,
+    SurfaceUnavailable,
+    WorkerSpawnRequest,
+)
+
+
+class CmuxRuntime:
+    surface = SURFACE_CMUX_PANE
+
+    def spawn(self, request: WorkerSpawnRequest) -> RuntimeHandle:
+        workspace = cmux.resolve_lead_workspace()
+        if not workspace:
+            reason = cmux.unreachable_reason()
+            if reason in (cmux.LOST_ENVIRONMENT, cmux.LOST_DENIED):
+                observed = (
+                    "this process has no cmux environment left — a sandbox sanitized it"
+                    if reason == cmux.LOST_ENVIRONMENT
+                    else "cmux is running but this process may not connect to its socket"
+                )
+                raise EnvironmentBlocked(
+                    "this run was prepared for cmux panes, but "
+                    f"{observed}. The same sandbox blocks worker CLIs from "
+                    "their own config, so falling back to blocking workers "
+                    "would fail too. Relaunch the lead outside a sandbox "
+                    "(use a full-access lead sandbox)."
+                )
+            raise SurfaceUnavailable("cmux lead workspace is gone")
+        try:
+            surface_id = cmux.spawn_worker_surface(
+                workspace=workspace,
+                cwd=request.cwd,
+                command=request.command,
+                title=request.title,
+                owned_surface_ids=request.owned_surface_ids,
+            )
+        except (RuntimeError, OSError, subprocess.SubprocessError) as exc:
+            raise SurfaceUnavailable(str(exc)) from exc
+        return RuntimeHandle(
+            surface=self.surface,
+            identifier=surface_id,
+            waitable=False,
+        )
+
+    def close(self, handle: RuntimeHandle) -> None:
+        cmux.close_surface(handle.identifier)
+
+    def wait(self, handle: RuntimeHandle) -> int:
+        raise RuntimeError("cmux-pane handles are not waitable")
+
+    def terminate(self, handle: RuntimeHandle) -> None:
+        self.close(handle)
+
+    def notify(self, event: ProgressEvent) -> None:
+        workspace = cmux.resolve_lead_workspace()
+        cmux.sidebar_log(workspace, event.message, level=event.level)
+        if event.notify_title is not None:
+            cmux.sidebar_notify(
+                workspace,
+                title=event.notify_title,
+                body=event.notify_body or "",
+            )
+
+    def restore_lead(self) -> None:
+        cmux.restore_lead_width()

package/runtime/python/okstra_ctl/application/open_worker.py

@@ -0,0 +1,29 @@
+"""Choose an execution surface from an injected port chain."""
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+
+from ..domain.worker_runtime import (
+    EnvironmentBlocked,
+    RuntimeHandle,
+    SurfaceUnavailable,
+    WorkerSpawnRequest,
+)
+from ..ports.worker_runtime import WorkerRuntimePort
+
+
+def open_worker(
+    chain: Sequence[WorkerRuntimePort],
+    request_for: Callable[[str], WorkerSpawnRequest],
+) -> RuntimeHandle:
+    last_unavailable: SurfaceUnavailable | None = None
+    for port in chain:
+        try:
+            return port.spawn(request_for(port.surface))
+        except EnvironmentBlocked:
+            raise
+        except SurfaceUnavailable as exc:
+            last_unavailable = exc
+    if last_unavailable is None:
+        raise SurfaceUnavailable("runtime chain is empty")
+    raise last_unavailable

package/runtime/python/okstra_ctl/assignment_resolver.py

@@ -339,7 +339,7 @@ def resolve_model_selection(
 
 
 def _static_requirements(profile: RoleProfile) -> tuple[RoleRequirement, ...]:
-    leader = RoleRequirement("leader", 1, "lead")
+    leader = RoleRequirement("leader", 1, 1, 1, "lead")
     return (leader, *(row for row in profile.roles if not row.dynamic))
 
 
@@ -355,17 +355,17 @@ def _role_instances(
         )
     instances: list[RoleInstance] = []
     for requirement in requirements:
-        if requirement.role in role_counts and requirement.optional_count == 0:
+        fixed = requirement.min_count == requirement.max_count
+        if requirement.role in role_counts and fixed:
             raise AssignmentResolutionError(
                 f"role {requirement.role!r} has a fixed quantity and cannot "
                 "receive an explicit count"
             )
-        count = role_counts.get(requirement.role, requirement.count)
-        maximum = requirement.count + requirement.optional_count
-        if count < requirement.count or count > maximum:
+        count = role_counts.get(requirement.role, requirement.recommended_count)
+        if count < requirement.min_count or count > requirement.max_count:
             raise AssignmentResolutionError(
                 f"role {requirement.role!r} count must be in "
-                f"{requirement.count}..{maximum}: {count}"
+                f"{requirement.min_count}..{requirement.max_count}: {count}"
             )
         instances.extend(
             RoleInstance(requirement.role, requirement.duty, ordinal)
@@ -747,20 +747,16 @@ def _constraint_failures(
 ) -> tuple[UnsatisfiedConstraint, ...]:
     failures: list[UnsatisfiedConstraint] = []
     for requirement in requirements:
-        required = requirement.min_distinct_providers
-        if required is None:
+        role_rows = [row for row in assignments if row.role == requirement.role]
+        if not role_rows:
             continue
-        providers = {
-            row.provider_id
-            for row in assignments
-            if row.role == requirement.role and row.ordinal <= requirement.count
-        }
-        if len(providers) < required:
+        refs = {row.model_ref for row in role_rows}
+        if len(refs) < len(role_rows):
             failures.append(UnsatisfiedConstraint(
                 requirement.role,
-                "minDistinctProviders",
-                required,
-                len(providers),
+                "uniqueModelRefs",
+                len(role_rows),
+                len(refs),
             ))
     return tuple(failures)
 
@@ -771,20 +767,24 @@ def _unmet_constraints(
 ) -> tuple[UnsatisfiedConstraint, ...]:
     failures: list[UnsatisfiedConstraint] = []
     for requirement in requirements:
-        required = requirement.min_distinct_providers
-        if required is None:
-            continue
-        providers = {
-            row.provider_id
+        role_groups = [
+            candidates
             for candidates in options
+            if candidates and candidates[0].role == requirement.role
+        ]
+        if not role_groups:
+            continue
+        worker_count = len(role_groups)
+        unique_refs = {
+            row.model_ref
+            for candidates in role_groups
             for row in candidates
-            if row.role == requirement.role and row.ordinal <= requirement.count
         }
-        if len(providers) < required:
+        if len(unique_refs) < worker_count:
             failures.append(UnsatisfiedConstraint(
                 requirement.role,
-                "minDistinctProviders",
-                required,
-                len(providers),
+                "uniqueModelRefs",
+                worker_count,
+                len(unique_refs),
             ))
     return tuple(failures)