okstra 0.174.0 → 0.176.0

package/docs/task-process/final-verification.md

@@ -24,16 +24,16 @@ flowchart TD
     Type --> PlanPick[approved plan pick]
     PlanPick --> Approved[approval marker confirm]
     Approved --> Stage[stage pick<br/>whole-task or stage number]
-    Stage --> Defaults[Use defaults / Customize]
-    Defaults -->|defaults| Workers[worker roster pick<br/>claude/codex/report-writer default]
-    Defaults -->|customize| Models[lead + worker model prompts]
-    Models --> Extras[directive, related tasks, clarification]
-    Extras --> Workers
-    Workers --> Confirm[confirmation]
+    Stage --> Leader[leader session read-only]
+    Leader --> RoleCount[role-count min..max<br/>omit uses recommended; skip if min==max]
+    RoleCount --> RoleModel[role-model provider/model per slot]
+    RoleModel --> RoleAdd[min=0 roles via role-add only<br/>default skip]
+    RoleAdd --> Extras[directive, related tasks, clarification]
+    Extras --> Confirm[confirmation]
     Confirm --> Render[render-bundle]
 ```
 
-`final-verification` is a non-implementation phase that has an analyser roster. So even if you pick `Use defaults`, the worker roster prompt still appears. The default required workers are `claude`, `codex`, and `report-writer`, and `antigravity` is opt-in.
+Launch selection uses role slots and model refs only: leader is the current session (read-only), 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.
 
 This phase does not ask for `base-ref` directly. The wizard selects whole-task or a single stage from the approved plan's Stage Map, and prepare resolves `VERIFICATION_TARGET` from the registry / `consumers.jsonl` / git state.
 

package/docs/task-process/implementation-planning.md

@@ -27,19 +27,17 @@ flowchart TD
     Input -->|rerun| Prior[prior planning report via clarification-response]
     Direction --> Worktree{active task worktree?}
     Prior --> Worktree
-    Worktree -->|yes| Defaults[Use defaults / Customize]
+    Worktree -->|yes| Leader[leader session read-only]
     Worktree -->|no| BaseRef[base-ref pick/text]
-    BaseRef --> Defaults
-    Defaults --> Workers[worker multi-pick<br/>claude/codex + optional antigravity]
-    Workers --> Branch{customize?}
-    Branch -->|no| Confirm
-    Branch -->|yes| Models[lead, claude, codex, antigravity if selected, report-writer models]
-    Models --> Extras[directive, related tasks, clarification]
+    BaseRef --> Leader
+    Leader --> RoleCount[role-count min..max<br/>omit uses recommended]
+    RoleCount --> RoleModel[role-model provider/model per slot]
+    RoleModel --> Extras[directive, related tasks, clarification]
     Extras --> Confirm
     Confirm --> Render[render-bundle]
 ```
 
-For a new plan, the wizard asks for a validated option-selection report and passes it as `--selected-direction`. A planning clarification rerun passes its own prior report through `--clarification-response`. The wizard currently does not ask about `--no-plan-verification`; on the okstra-run path, plan-body verification is prepared as enabled by default.
+For a new plan, the wizard asks for a validated option-selection report and passes it as `--selected-direction`. A planning clarification rerun passes its own prior report through `--clarification-response`. Launch selection uses role slots and model refs only: planner count in `min..max` (default recommended), then one `provider/model` per slot. Duplicate model refs in the same role are rejected. There is no provider roster multi-pick. The wizard currently does not ask about `--no-plan-verification`; on the okstra-run path, plan-body verification is prepared as enabled by default.
 
 ## 3. prepare_task_bundle handling
 
@@ -59,12 +57,14 @@ sequenceDiagram
     P->>P: provision/reuse task worktree
     P->>R: _build_convergence_block()
     R-->>M: convergence.planBodyVerification.enabled=true
-    P->>M: workflow nextRecommendedPhase=implementation
+    P->>M: workflow nextRecommendedPhase inherited, ready lowered to pending
     P-->>W: prepared lead prompt
 ```
 
 Prepare rejects a new plan without a selected-direction report. Comparison mode requires a valid `DIRECTION SELECTION` sidecar, while preselected-validation mode uses the confirmed upstream direction without one. The normalized snapshot binds the source report, source-data digest, option ID, direction body, requirements, and invariants.
 
+Prepare does not name the next phase. It carries the inherited `workflow.nextRecommendedPhase` forward and lowers a `ready` pointer to `pending`, because this run has not finished and a `ready` pointer would read as an invitation to start the following phase. The pointer becomes `ready` at `implementation` only when Phase 7 projects it from this run's `implementationPlanning.outcome` of `plan-ready`.
+
 ## 4. lead execution flow
 
 ```mermaid

package/docs/task-process/implementation.md

@@ -31,16 +31,16 @@ flowchart TD
     Approved -->|no| Retry[re-prompt same step]
     Approved -->|yes| Stage[stage multi-pick<br/>ready/active markers]
     Stage --> Chain[render-args<br/>stage + chain-stages]
-    Chain --> Executor[executor pick<br/>claude/codex/antigravity]
-    Executor --> Defaults[Use defaults / Customize]
-    Defaults -->|defaults| Confirm
-    Defaults -->|customize| Models[lead + executor model + report-writer model]
-    Models --> Extras[directive, related tasks, clarification]
+    Chain --> Leader[leader session read-only]
+    Leader --> RoleCount[role-count min..max<br/>omit uses recommended; skip if min==max]
+    RoleCount --> RoleModel[role-model provider/model per slot]
+    RoleModel --> RoleAdd[min=0 roles via role-add only<br/>default skip]
+    RoleAdd --> Extras[directive, related tasks, clarification]
     Extras --> Confirm
     Confirm --> Render[render-bundle]
 ```
 
-`implementation` has no worker override question. The wizard `render_args()` emits `workers` as an empty string, and the runtime uses the profile default roster. `stage_pick` is a multi-pick that shows done/in-progress/ready/waiting status. The selected stage set goes through dependency closure and topological sort into a `chain-stages` CSV, and each actual run executes only one of those stages.
+Launch selection uses role slots and model refs only: leader is the current session (read-only), then each static role's count in `min..max` (default **recommended**; the count step is skipped when `min == max`), then one `provider/model` per slot. Roles with `min = 0` stay closed unless the user opens them with role-add (default skip). Duplicate model refs in the same role are rejected. There is no provider roster multi-pick and no defaults-vs-customize fork. `executor` is only a compatibility alias for `implementer` in model refs; implementer slots are chosen through role-count / role-model. Dynamic verifiers are not chosen at launch. `--workers` is a CLI compatibility input only, not a launch picker. `stage_pick` is a multi-pick that shows done/in-progress/ready/waiting status. The selected stage set goes through dependency closure and topological sort into a `chain-stages` CSV, and each actual run executes only one of those stages.
 
 The current okstra-run wizard path does not expose `--approve` that directly flips the approval checkbox. The plan file must already have a recognized approval marker.
 

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

@@ -27,19 +27,20 @@ flowchart TD
     Type --> Plan[approved plan auto/pick]
     Plan --> Scope[handoff stage pick<br/>whole-task or eligible stages]
     Scope --> Worktree{active task worktree?}
-    Worktree -->|yes| Defaults[Use defaults / Customize]
+    Worktree -->|yes| Leader[leader session read-only]
     Worktree -->|no| BaseRef[base-ref pick/text]
-    BaseRef --> Defaults
-    Defaults -->|defaults| Confirm[confirmation]
-    Defaults -->|customize| Models[lead model prompt]
-    Models --> Extras[directive, related tasks, clarification]
+    BaseRef --> Leader
+    Leader --> RoleCount[role-count min..max<br/>omit uses recommended; skip if min==max]
+    RoleCount --> RoleModel[role-model provider/model per slot]
+    RoleModel --> RoleAdd[min=0 roles via role-add only<br/>default skip]
+    RoleAdd --> Extras[directive, related tasks, clarification]
     Extras --> Template[PR template override?]
     Template --> TemplateScope[save template to project/global?]
-    TemplateScope --> Confirm
+    TemplateScope --> Confirm[confirmation]
     Confirm --> Render[render-bundle]
 ```
 
-`release-handoff` has no worker roster prompt. The wizard outcome's `renderArgs` includes `pr-template-path` only for release-handoff, and the runtime forces the worker list to empty. 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[]`. whole-task requires an accepted whole-task verification report, and for stage-group only the stages that were marked `verified` by an accepted single-stage verification in the Stage Lifecycle Snapshot but not yet covered by a `pr` become candidates.
+`release-handoff` has no analysis-worker dispatch. Launch selection still shows the leader session (read-only) and any applicable role-count / role-model steps; 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[]`. whole-task requires an accepted whole-task verification report, and for stage-group only the stages that were marked `verified` by an accepted single-stage verification in the Stage Lifecycle Snapshot but not yet covered by a `pr` become candidates.
 
 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.
 

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

@@ -31,18 +31,18 @@ flowchart TD
     Keep -->|keep| Base
     Keep -->|change/no brief| Brief
     Type --> Base{active task worktree?}
-    Base -->|yes| Defaults[Use defaults / Customize]
+    Base -->|yes| Leader[leader session read-only]
     Base -->|no| BaseRef[base-ref pick/text]
-    BaseRef --> Defaults
-    Defaults --> Workers[worker multi-pick<br/>still asked even on defaults]
-    Workers --> Custom{customize?}
-    Custom -->|yes| ModelsAndExtras[models, directive, related tasks, clarification]
-    Custom -->|no| Confirm
-    ModelsAndExtras --> Confirm
+    BaseRef --> Leader
+    Leader --> RoleCount[role-count min..max<br/>omit uses recommended; skip if min==max]
+    RoleCount --> RoleModel[role-model provider/model per slot]
+    RoleModel --> RoleAdd[min=0 roles via role-add only<br/>default skip]
+    RoleAdd --> Extras[directive, related tasks, clarification]
+    Extras --> Confirm
     Confirm --> Render[render-bundle]
 ```
 
-In the worker multi-pick, the picker does not show `report-writer` as an option. Even if the user selects only `claude`, the wizard force-appends `report-writer`. The optional `antigravity` is included only when the user selects it.
+Launch selection uses role slots and model refs only: leader is the current session (read-only), 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.174.0",
+  "version": "0.176.0",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",
@@ -14,7 +14,7 @@
   },
   "files": [
     "bin/",
-    "src/",
+    "dist/",
     "runtime/",
     "docs/architecture.md",
     "docs/architecture/",
@@ -30,15 +30,21 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "scripts": {
-    "build": "node tools/build.mjs",
-    "prepack": "node tools/build.mjs",
+    "build:ts": "tsc --project tsconfig.json",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "build": "npm run build:ts && node tools/build.mjs",
+    "prepack": "npm run build",
     "test:js": "node --test tests-js/*.test.mjs",
     "test:py": "python3 -m pytest tests/",
     "test:workflow": "bash validators/validate-workflow.sh",
     "test:e2e": "bash tests-e2e/run-all.sh",
     "check": "npm run build && npm run test:js && npm run test:py && npm run test:workflow && npm run test:e2e"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2"
   }
 }

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.174.0",
-  "builtAt": "2026-08-17T05:25:03.210Z",
+  "package": "0.176.0",
+  "builtAt": "2026-08-18T08:36:47.903Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/claude-worker.md

@@ -26,7 +26,8 @@ invocation. The final prompt's duty contract owns the role boundary,
 responsibility, and prohibited actions. This file owns Claude tool usage,
 artifact persistence, and liveness procedure only. Do not shell out to another
 model CLI, and refuse a dispatch whose prompt has no adjacent verified
-invocation metadata.
+invocation metadata. Consume the stored `executionLabel`; do not infer a role
+from the provider name. `lead` is a compatibility alias for `leader`.
 
 ## Execution Rules
 

package/runtime/agents/workers/report-writer-worker.md

@@ -18,7 +18,9 @@ This is the Claude host execution adapter for a materialized Okstra invocation.
 The final prompt's `report-writer` duty contract owns the role boundary,
 required responsibility, and prohibited actions. This file owns only how that
 contract is executed with Claude host tools. Refuse a dispatch whose prompt has
-no adjacent verified invocation metadata.
+no adjacent verified invocation metadata. Consume the stored `executionLabel`.
+The final-report `executionRoles[]` set must equal the execution-manifest
+`roleExecutions[]` set.
 
 - The `**Report Language:**` header in your dispatch prompt is already
   resolved to `en` or `ko` by the lead. Copy it verbatim into

package/runtime/agents/workers/translator-worker.md

@@ -18,7 +18,9 @@ This is the Claude host execution adapter for a materialized Okstra invocation.
 The final prompt's `translator` duty contract owns the role boundary,
 responsibility, and prohibited actions. This file owns only the extraction,
 translation-sidecar, and verification tool procedure. Refuse a dispatch whose
-prompt has no adjacent verified invocation metadata.
+prompt has no adjacent verified invocation metadata. Consume the stored
+`executionLabel`; the translator role remains `translator` even without a team
+roster.
 
 ## Procedure
 

package/runtime/bin/lib/okstra/cli.sh

@@ -67,6 +67,18 @@ while [[ $# -gt 0 ]]; do
       WORKERS_OVERRIDE="$(require_option_value --workers "${2-}")"
       shift 2
       ;;
+    --role-count)
+      ROLE_COUNTS+=("$(require_option_value --role-count "${2-}")")
+      shift 2
+      ;;
+    --role-model)
+      ROLE_MODELS+=("$(require_option_value --role-model "${2-}")")
+      shift 2
+      ;;
+    --host-session-context-json)
+      HOST_SESSION_CONTEXT_JSON="$(require_option_value --host-session-context-json "${2-}")"
+      shift 2
+      ;;
     --lead-model)
       LEAD_MODEL_OVERRIDE="$(require_option_value --lead-model "${2-}")"
       shift 2

package/runtime/bin/lib/okstra/globals.sh

@@ -19,6 +19,9 @@ RESUME_CLARIFICATION_MODE="false"
 RESUME_SESSION_MODE="false"
 RESUME_SESSION_ID=""
 WORKERS_OVERRIDE=""
+ROLE_COUNTS=()
+ROLE_MODELS=()
+HOST_SESSION_CONTEXT_JSON=""
 LEAD_MODEL_OVERRIDE=""
 LEAD_PROVIDER_OVERRIDE=""
 CLAUDE_MODEL_OVERRIDE=""

package/runtime/bin/lib/okstra/interactive.sh

@@ -192,8 +192,15 @@ PY
   need_brief_val="$([[ -z "$BRIEF_PATH" ]] && printf '1' || printf '0')"
   need_type_val="$([[ -z "$TASK_TYPE" ]] && printf '1' || printf '0')"
   local autofill_output=""
-  autofill_output="$(python3 - "$manifest_path" "$need_brief_val" "$need_type_val" <<'PY'
+  # autofill 은 편의 기능이라 실패해도 run 을 끊으면 안 된다. heredoc 이
+  # okstra_ctl 을 import 하므로 설치가 깨지면 non-zero 로 끝나는데, okstra.sh 는
+  # `set -euo pipefail` 이라 이 평범한 대입 하나가 run 을 통째로 중단시킨다.
+  # 위 reconcile 호출(:189)이 같은 이유로 `|| true` 를 달고 있다.
+  autofill_output="$(PYTHONPATH="$OKSTRA_PYTHONPATH:${PYTHONPATH-}" python3 - "$manifest_path" "$need_brief_val" "$need_type_val" <<'PY'
 import json, sys
+
+from okstra_ctl import next_phase
+
 path = sys.argv[1]
 need_brief = sys.argv[2] == "1"
 need_type = sys.argv[3] == "1"
@@ -208,15 +215,14 @@ task_type = ""
 if need_brief:
     brief = (data.get("taskBriefPath") or "").strip()
 if need_type:
-    workflow = data.get("workflow") or {}
-    task_type = (workflow.get("nextRecommendedPhase") or "").strip()
-    if task_type in ("", "pending-routing-decision", "done-or-follow-up"):
-        task_type = ""
+    # 포인터 판정은 Python SSOT 가 갖는다 — `ready` 가 아니면 빈 문자열이라
+    # 셸이 센티널 목록을 따로 들고 있을 이유가 없다.
+    task_type = next_phase.autofill_task_type(data)
 
 print(f"BRIEF={brief}")
 print(f"TYPE={task_type}")
 PY
-)"
+)" || true
 
   local manifest_brief=""
   local manifest_type=""

package/runtime/bin/lib/okstra/usage.sh

@@ -74,8 +74,9 @@ optional arguments:
                        plans.
   --task-key <project-id:task-group:task-id>
                        Shorthand for --project-id/--task-group/--task-id. When the matching task-manifest.json
-                       exists, brief-path and task-type are auto-filled from it (taskBriefPath and
-                       workflow.nextRecommendedPhase). Explicit flags always win.
+                       exists, brief-path and task-type are auto-filled from it (taskBriefPath, and
+                       workflow.nextRecommendedPhase.phase only while its status is \`ready\`).
+                       Explicit flags always win.
 
 options:
   --render-only        Render the host-neutral lead handoff prompt only. Do not launch a session.
@@ -104,8 +105,8 @@ options:
   --lead-runtime      Registered host ID or alias. Default: claude-code. In-host runs
                       use current-session; terminal launch uses spawn-process readiness.
   --executor           Provider that performs the Executor role during --task-type=implementation.
-                      One of: claude | codex | antigravity. Default: OKSTRA_DEFAULT_EXECUTOR or claude.
-                      The Executor is the only worker allowed to mutate project files; the other two
+                      One of: claude | codex | antigravity | grok | kimi. Default: OKSTRA_DEFAULT_EXECUTOR or claude.
+                      The Executor is the only worker allowed to mutate project files; the other
                       providers are dispatched as read-only verifiers regardless of this selection.
                       Has no effect on other task types.
   --critic             Provider for the opt-in Phase 5.6 critic pass (coverage gaps /
@@ -132,9 +133,9 @@ model defaults:
   Claude worker: OKSTRA_DEFAULT_CLAUDE_MODEL or opus
   Codex worker: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.6-sol
   Antigravity worker: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or gemini-3.1-pro
-  Grok worker: grok-build-0.1 (analyser) or grok-4.5 (critic)
+  Grok worker: grok-4.6
   Kimi worker: kimi-k2.7-code (analyser) or kimi-k3 (critic)
-  Implementation executor: OKSTRA_DEFAULT_EXECUTOR or claude (one of: claude | codex | antigravity)
+  Implementation executor: OKSTRA_DEFAULT_EXECUTOR or claude (one of: claude | codex | antigravity | grok | kimi)
 
 output:
   Stable task bundles are stored under:

package/runtime/bin/okstra-error-log.py

@@ -72,6 +72,7 @@ def _build_parser():
     grp.add_argument("--stderr-excerpt-file", default=None)
     obs.add_argument("--context-json", default=None,
                      help="JSON object string for context")
+    _add_identity_flags(obs)
 
     dump = sub.add_parser("append-from-worker",
                           help="Dump worker sidecar errors[] into errors.jsonl")
@@ -81,9 +82,33 @@ def _build_parser():
     dump.add_argument("--agent", required=True, choices=sorted(ALLOWED_AGENTS))
     dump.add_argument("--agent-role", required=True, choices=sorted(ALLOWED_AGENT_ROLES))
     dump.add_argument("--model", required=True)
+    _add_identity_flags(dump)
     return p
 
 
+def _add_identity_flags(parser):
+    parser.add_argument("--participant-ref", default="")
+    parser.add_argument("--role-execution-ref", default="")
+    parser.add_argument("--invocation-ref", default="")
+    parser.add_argument("--attempt", type=int, default=None)
+    parser.add_argument("--execution-label", default="")
+
+
+def _identity_from_args(args):
+    payload = {}
+    if args.participant_ref:
+        payload["participantRef"] = args.participant_ref
+    if args.role_execution_ref:
+        payload["roleExecutionRef"] = args.role_execution_ref
+    if args.invocation_ref:
+        payload["invocationRef"] = args.invocation_ref
+    if args.attempt is not None:
+        payload["attempt"] = args.attempt
+    if args.execution_label:
+        payload["executionLabel"] = args.execution_label
+    return payload or None
+
+
 def _read_stderr(args):
     if args.stderr_excerpt_file:
         return Path(args.stderr_excerpt_file).read_text()
@@ -114,6 +139,7 @@ def main(argv=None):
             message=args.message,
             stderr_excerpt=_read_stderr(args),
             context=_read_context(args),
+            identity=_identity_from_args(args),
         )
         return 0
     if args.cmd == "append-from-worker":
@@ -124,6 +150,7 @@ def main(argv=None):
             agent=args.agent,
             agent_role=args.agent_role,
             model=args.model,
+            identity=_identity_from_args(args),
         )
         print(n)
         return 0