okstra 0.50.0 → 0.51.0

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

@@ -142,6 +142,13 @@ while [[ $# -gt 0 ]]; do
       APPROVE_PLAN_ACK="true"
       shift
       ;;
+    --implementation-option)
+      # 유저가 implementation-planning final-report 에서 고른 Option Candidate
+      # 이름. 런타임이 approved-plan frontmatter 의 implementation-option 라인을
+      # 이 값으로 채운다. 빈 값이면 implementation 이 Recommended Option 으로 폴백.
+      IMPLEMENTATION_OPTION="$(require_option_value --implementation-option "${2-}")"
+      shift 2
+      ;;
     --no-plan-verification)
       # implementation-planning 의 Phase 6 plan-body verification 라운드를
       # 끈다. 기본값은 활성화. 비활성 시 final-report 상단의 User Approval
@@ -178,7 +185,7 @@ while [[ $# -gt 0 ]]; do
           printf '  hint: did you mean --task-id?\n' >&2
           ;;
       esac
-      printf '  valid options: --render-only --resume-clarification --yes --workers --lead-model --claude-model --codex-model --gemini-model --report-writer-model --related-tasks --task-type --project-id --project-root --task-group --task-id --task-brief --directive --clarification-response --approved-plan --approve --no-plan-verification -h|--help\n' >&2
+      printf '  valid options: --render-only --resume-clarification --yes --workers --lead-model --claude-model --codex-model --gemini-model --report-writer-model --related-tasks --task-type --project-id --project-root --task-group --task-id --task-brief --directive --clarification-response --approved-plan --approve --implementation-option --no-plan-verification -h|--help\n' >&2
       usage
       exit 1
       ;;

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

@@ -39,6 +39,9 @@ DIRECTIVE=""
 CLARIFICATION_RESPONSE_PATH=""
 APPROVED_PLAN_PATH=""
 APPROVE_PLAN_ACK="false"
+# implementation 전용: 유저가 고른 Option Candidate 이름. 빈 값이면 implementation
+# 이 plan 의 Recommended Option 으로 폴백한다. --implementation-option 으로 설정.
+IMPLEMENTATION_OPTION=""
 # Phase 6 plan-body verification toggle. Default "true" (round runs).
 # Flipped to "false" by --no-plan-verification on the CLI.
 PLAN_VERIFICATION_ENABLED="true"

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

@@ -59,23 +59,25 @@ resolve_task_root_for_shortcut() {
   local task_id="$4"
 
   local resolved=""
-  resolved="$(python3 - "$project_root" "$project_id" "$task_group" "$task_id" <<'PY'
-import json, os, re, sys
+  resolved="$(python3 - "$WORKSPACE_ROOT/scripts" "$project_root" "$project_id" "$task_group" "$task_id" <<'PY'
+import json, os, sys
 from pathlib import Path
 
-project_root = Path(sys.argv[1])
-project_id = sys.argv[2]
-task_group = sys.argv[3]
-task_id = sys.argv[4]
+# task root 의 slug 경로 구성은 okstra_ctl.paths.task_dir(SSOT) 에 위임한다.
+# 과거 이 heredoc 은 slugify 와 `.okstra/tasks/<slug>/<slug>` 구조를 자체
+# 재구현해 규칙 변경 시 silent drift 위험이 있었다. project-resolver.sh 와
+# 동일하게 $WORKSPACE_ROOT/scripts 를 sys.path 에 올려 패키지를 import 한다.
+sys.path.insert(0, sys.argv[1])
+from okstra_ctl.paths import task_dir
+
+project_root = Path(sys.argv[2])
+project_id = sys.argv[3]
+task_group = sys.argv[4]
+task_id = sys.argv[5]
 
 requested_key = f"{project_id}:{task_group}:{task_id}"
 requested_key_ci = requested_key.lower()
 
-def slugify(value: str) -> str:
-    value = value.lower()
-    value = re.sub(r"[^a-z0-9]+", "-", value).strip("-")
-    return value
-
 candidates = []
 
 catalog_path = project_root / ".okstra" / "discovery" / "task-catalog.json"
@@ -111,7 +113,7 @@ if catalog_path.is_file():
                         sys.exit(0)
                     candidates.append(str(abs_path))
 
-slug_path = project_root / ".okstra" / "tasks" / slugify(task_group) / slugify(task_id)
+slug_path = task_dir(project_root, task_group, task_id)
 if slug_path.is_dir():
     print(f"OK\t{slug_path}")
     sys.exit(0)

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

@@ -46,6 +46,12 @@ optional arguments:
                        \`- [ ] Approved\` to \`- [x] Approved\` and appends an approval audit line
                        (timestamp + "CLI --approve"). Use this for scripted/CI flows or when you want a
                        single command to both approve and launch the next phase.
+  --implementation-option <name>
+                       Name of the Option Candidate the user chose from the implementation-planning
+                       final-report. Only meaningful together with --approved-plan and
+                       --task-type=implementation. The runtime fills the approved-plan frontmatter
+                       \`implementation-option:\` line with <name>. When omitted, the implementation run
+                       falls back to the plan's \`Recommended Option\`.
   --no-plan-verification
                        Disable the Phase 6 plan-body verification round that runs after the report-writer
                        authors the implementation-planning draft. Default: enabled. Only meaningful with

package/runtime/bin/okstra-team-reconcile.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+#
+# okstra-team-reconcile.sh — flip dead-pane stale-active team members to
+# inactive so the lead's `TeamDelete()` can disband the team in one shot.
+#
+# A Claude Code team member clears its own `isActive` flag in
+# `~/.claude/teams/<team>/config.json` when its `Agent()` dispatch returns. A
+# member whose tmux pane died WITHOUT that flip stays `isActive: true`, and
+# `TeamDelete` then refuses the whole team ("active members remain") — an error
+# no re-sent `shutdown_request` can clear, since the addressee is already gone.
+# This reconciles exactly that case; it never touches a live-pane member, the
+# lead, or a member with no recorded pane (those are left for graceful
+# shutdown). It no-ops when tmux is unavailable or nothing is stale.
+#
+# Usage: okstra-team-reconcile.sh [--list] <team-name>
+#   --list   report what WOULD be deactivated; do not write (alias --dry-run).
+#
+# Failures are non-fatal to the run — teardown must never block on this.
+set -u
+
+_dir="$(cd -P "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Logic lives in okstra_ctl.team_reconcile. In the repo layout the package is a
+# bin-sibling (scripts/okstra_ctl); in the installed layout it is under
+# $OKSTRA_HOME/lib/python. Put both on PYTHONPATH so either resolves.
+home="${OKSTRA_HOME:-$HOME/.okstra}"
+export PYTHONPATH="${_dir}:${home}/lib/python${PYTHONPATH:+:$PYTHONPATH}"
+
+exec python3 -c 'import sys; from okstra_ctl.team_reconcile import main; sys.exit(main(sys.argv[1:]))' "$@"

package/runtime/bin/okstra.sh

@@ -80,6 +80,7 @@ okstra execution summary:
   executor (implementation only): ${EXECUTOR_OVERRIDE:-default(claude)}
   approved plan: ${APPROVED_PLAN_PATH:-None}
   approve ack (CLI 승인 의사): ${APPROVE_PLAN_ACK}
+  implementation option (선택 옵션): ${IMPLEMENTATION_OPTION:-None(fallback to Recommended Option)}
   related tasks: ${RELATED_TASKS_RAW:-None}
 CONFIRM_EOF
   printf 'Continue? [y/yes]: ' >&2
@@ -117,6 +118,7 @@ PY_ARGS=(
 [[ -n "${RELATED_TASKS_RAW-}" ]] && PY_ARGS+=(--related-tasks "$RELATED_TASKS_RAW")
 [[ -n "${APPROVED_PLAN_PATH-}" ]] && PY_ARGS+=(--approved-plan "$APPROVED_PLAN_PATH")
 [[ "$APPROVE_PLAN_ACK" == "true" ]] && PY_ARGS+=(--approve)
+[[ -n "${IMPLEMENTATION_OPTION-}" ]] && PY_ARGS+=(--implementation-option "$IMPLEMENTATION_OPTION")
 [[ -n "${CLARIFICATION_RESPONSE_PATH-}" ]] && PY_ARGS+=(--clarification-response "$CLARIFICATION_RESPONSE_PATH")
 [[ -n "${WORK_CATEGORY-}" ]] && PY_ARGS+=(--work-category "$WORK_CATEGORY")
 [[ -n "${BASE_REF-}" ]] && PY_ARGS+=(--base-ref "$BASE_REF")

package/runtime/prompts/launch.template.md

@@ -39,6 +39,8 @@ Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at
 
 - Task manifest: `{{TASK_MANIFEST_RELATIVE_PATH}}`
 - Run manifest: `{{RUN_MANIFEST_RELATIVE_PATH}}`
+- Active run context: `{{ACTIVE_RUN_CONTEXT_RELATIVE_PATH}}`
+- Analysis packet: `{{ANALYSIS_PACKET_RELATIVE_PATH}}`
 
 ## Session
 
@@ -82,7 +84,7 @@ Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at
 ## Available MCP Servers
 
 {{AVAILABLE_MCP_SERVERS}}
-- The full usage policy and per-phase rules live in the task brief's `## Available MCP Servers` section. Read them there before dispatching workers and inject only the one-line pointer below into each worker prompt (the brief is already in every worker's [Required reading], so verbatim copy is redundant): `**MCP servers:** follow the task brief's "## Available MCP Servers" section (already in your Required reading).`
+- The full usage policy and per-phase rules live in the analysis packet's `Available MCP Servers` extract. Inject only the one-line pointer below into each analysis-worker prompt: `**MCP servers:** follow the analysis packet's "Available MCP Servers" section (already in your Required reading).`
 - **Invocation rule (forward to every worker prompt)**: MCP tools are addressed by their tool name through the host's tool interface — **never via `Bash`**. Claude-side workers call the tool directly (e.g. `mcp__<server>__<tool>`). Codex/Gemini workers call through their CLI's own MCP transport (e.g. `codex mcp call ...`). Running the tool name as a shell command is a contract violation and will always fail regardless of permission grants.
 - Codex worker and Gemini worker run external CLIs; they can only use these MCP servers if their own CLI configs mirror them. If not, instruct the worker to record `MCP not available in this CLI` in its `Missing Information or Assumptions` block rather than guessing or shell-falling-back.
 - MCP queries are evidence-grade. Cite server, table, and the SELECT used in worker output. MCP must NOT be used as a write path in any phase, including `implementation`.

package/runtime/prompts/profiles/_common-contract.md

@@ -39,11 +39,11 @@ profile document.
 - Run-end team teardown (shared — runs AFTER Phase 7 persistence/token collection, BEFORE the pane disposition step below):
   - The lead created the worker team in Phase 3 (`TeamCreate(team_name: "okstra-<task-key>")`). Worker teammates are NOT reclaimed on their own — without an explicit teardown they linger in the FleetView roster across this and later runs in the session. The lead MUST release them once the run's work is done.
   - This step is **automatic and silent** — NO user prompt (workers are idle sessions that have already delivered their results; there is nothing for the user to preserve). It runs only when team-state's `teamCreate.status == "ok"` (Teams mode was actually used); in the no-`team_name` fallback there is no team to delete, so silent-skip.
+  - Why a reconcile step exists: each worker clears its own `isActive` flag in `~/.claude/teams/<team>/config.json` when its `Agent()` dispatch returns, so by Phase 7 every worker is normally already inactive and `TeamDelete()` succeeds immediately. The one failure mode is a worker whose tmux pane died WITHOUT clearing the flag (e.g. killed mid-turn): it stays `isActive: true`, and `TeamDelete` then refuses the entire team with an "active members" error that no amount of re-sending `shutdown_request` can clear — the addressee is already gone. `okstra-team-reconcile.sh` deterministically flips exactly those dead-pane stale-active members to inactive (never a live-pane member, never the lead).
   - Sequence (token-usage collection MUST already be complete — `TeamDelete` removes `~/.claude/teams/<team>/` + `~/.claude/tasks/<team>/` but NOT the `~/.claude/projects/` jsonls Phase 7 reads, yet the read MUST precede teardown):
-    1. Read `~/.claude/teams/okstra-<task-key>/config.json` and, for every `members` entry whose name is not the lead, `SendMessage(to: <name>, message: { type: "shutdown_request" })` to terminate it gracefully.
-    2. These workers already delivered their results and terminated when their `Agent()` dispatch returned (the lead's completion evidence is the returned output + the existing result/final-report file, not a teardown ack) — a terminated session emits NO shutdown confirmation. Treat `shutdown_request` as best-effort (fire-and-forget); the lead MUST NOT block waiting for acks from addressed teammates. Proceed immediately to step 3.
-    3. Call `TeamDelete()` — the single synchronization point for teardown. If it errors with an active-members message, one teammate is genuinely still shutting down: wait briefly, retry `TeamDelete()` once, then proceed regardless of the result. NEVER loop or re-send `shutdown_request`; teardown must never block run completion once the work and final report already exist.
-  - Report it in one short line (e.g. `worker 6명 종료 + 팀 해제`) and proceed. Emit `PROGRESS: phase-7-teardown disbanding team` immediately before step 1.
+    1. Run `$HOME/.okstra/bin/okstra-team-reconcile.sh "okstra-<task-key>"` exactly once. It flips dead-pane stale-active members to inactive, and no-ops when tmux is unavailable or nothing is stale. Do NOT loop it.
+    2. Call `TeamDelete()` — the single synchronization point for teardown. If it STILL errors with an active-members message, one worker pane is genuinely still live (rare at Phase 7, since every `Agent()` dispatch has already returned): send that one member a structured `SendMessage(to: <name>, message: { type: "shutdown_request" })` — the `message` MUST be the object literal shown, NEVER a JSON string stuffed into a text field (a stringified payload is delivered as a plain message and the shutdown protocol never fires) — wait briefly, then retry `TeamDelete()` once and proceed regardless of the result. NEVER loop, never use `TaskStop` (teammates are not background tasks — `TaskStop` 404s on a member address), and never let teardown block run completion once the work and final report already exist.
+  - Report it in one short line (e.g. `stale 멤버 1명 정리 + 팀 해제`, or just `worker 팀 해제` when nothing was stale) and proceed. Emit `PROGRESS: phase-7-teardown disbanding team` immediately before step 1.
 - Phase wrap-up — okstra pane disposition (shared, MUST be the *last* step before returning control to the user):
   - At run end the only residual okstra panes are the LAST phase's (e.g. the `report-writer-worker` agent pane and any codex/gemini trace pane). `okstra-trace-cleanup.sh --list --run-dir "<RUN_DIR>"` returns one tab-separated `<pane_id>\t<pane_title>` line per residual okstra pane (worker-agent + trace) for this run.
   - When `<RUN_DIR>/state/lead-pane.id` is non-empty, after the final-report file has been written and the routing recommendation has been issued, the lead MUST run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list --run-dir "<RUN_DIR>"` exactly once. The output lists every residual okstra pane (worker-agent + trace) for this run, never the lead's own pane.

package/runtime/prompts/profiles/_implementation-executor.md

@@ -19,9 +19,9 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
 ## Pre-implementation context exploration (executor before first edit)
 
 - **Coding-conventions preflight (BLOCKING — runs before the first `Edit` / `Write`, and binds the TDD loop below):** load the applicable coding conventions for every language the diff will touch, then state in ONE line which conventions apply (e.g. `Applying TS + hexagonal overlay; domain at src/domains/*/domain/`). Lint/test green is necessary but NOT sufficient — self-mocked tests, interaction-only assertions, and untruthful names all pass a green pipeline; this gate is what keeps them out of the diff.
-  - **Language-specific rules load per situation — never inline them here.** Detect each touched file's language (extension / project manifest) and load the matching reference from the project's coding-conventions skill: `coding-preflight`, when installed, routes `languages/<lang>.md` (mock/spy API, idioms, test framework) + `clean-code.md` + any `architecture/*` overlay. For a ports-and-adapters / NestJS-hex layout (`domain/` + `ports/` + `adapters/`, `*.port.*`), load the hexagonal overlay too. This per-language split is the skill's job — the executor does not carry a multi-language block in context.
+  - **Language-specific rules load per situation — never inline them here.** Detect each touched file's language (extension / project manifest) and load the matching reference by reading okstra's installed coding-conventions files directly at `~/.claude/skills/okstra-coding-preflight/` (placed there by `okstra install`): read `languages/<lang>.md` (mock/spy API, idioms, test framework) + `clean-code.md` + any `architecture/*` overlay via the Read tool by absolute path. The skill is `user-invocable: false`, so do NOT rely on Skill-tool auto-invocation — read the files directly. For a ports-and-adapters / NestJS-hex layout (`domain/` + `ports/` + `adapters/`, `*.port.*`), load the hexagonal overlay too. This per-language split is the skill's job — the executor does not carry a multi-language block in context.
   - **Language-agnostic principles that ALWAYS bind (the TDD loop below MUST satisfy them):** (1) no self-mocking of the SUT — stub/spy only injected collaborators, never the subject's own methods; (2) behavioral assertions on outcomes (return value, state, persisted rows, events, boundary calls) — never `toHaveBeenCalled*` on an internal helper as the only/primary assertion; (3) truthful names — a `get*` / `find*` that writes/inserts, or a name encoding the caller's use-case (`*ForInit`) or hiding a domain rule (`findValid*`), is a defect; (4) single-purpose functions ≤50 effective lines, plain-English readability.
-  - **Graceful degradation (end-user, or codex / gemini executor runtimes where no coding-conventions skill is reachable):** do NOT skip the gate — apply the agnostic principles above plus the project's own `CLAUDE.md` / `CONTRIBUTING` / formatter+lint config, and record `coding-conventions: skill-unavailable → applied <project rules + agnostic principles>` in the final report. Never claim a skill read that did not happen.
+  - **Graceful degradation (codex / gemini executor runtimes, or any runtime where the `~/.claude/skills/okstra-coding-preflight/` files are absent or unreadable):** do NOT skip the gate — apply the agnostic principles above plus the project's own `CLAUDE.md` / `CONTRIBUTING` / formatter+lint config, and record `coding-conventions: skill-unavailable → applied <project rules + agnostic principles>` in the final report. Never claim a skill read that did not happen.
 - **Mandatory TDD loop**: BEFORE the first `Edit` or `Write` call, the executor MUST apply a red-green-refactor loop for every code change in this run. This is required; skipping it is a `contract-violated` outcome. This governs HOW each step is executed (failing test first → minimal implementation → refactor); it does not override the approved plan's WHAT/file scope.
   - Order of operations per plan step: (1) write/extend the test that captures the step's acceptance criterion and confirm it fails for the right reason, (2) commit the failing test (`test(<scope>): ...`), (3) implement the minimum change to make it pass, (4) commit the implementation (`feat|fix(<scope>): ...`), (5) refactor without changing behaviour and commit separately if any cleanup is made (`refactor(<scope>): ...`). The failing-then-passing transition between steps (2) and (4) is the `TDD evidence` required by the final report.
   - Doc-only / config-only / pure-rename steps that have no observable runtime behaviour are exempt from the failing-test requirement, but the executor MUST cite the exemption per step in the final report (`TDD exemption: <reason>`).

package/runtime/prompts/profiles/_implementation-verifier.md

@@ -66,7 +66,7 @@ The final report keeps both — executor's `Validation evidence` AND each verifi
 Re-running commands proves the diff *builds and passes*; it does NOT prove the diff is *well-designed*. Lint/test green is necessary but not sufficient — self-mocked tests, interaction-only assertions, and untruthful names all survive a green pipeline. This gate is the filter for exactly those defects, so the executor's design errors are caught here instead of in post-merge PR review. It is a real gate, not a checklist: it enumerates the full diff and a blocking hit forces `FAIL`.
 
 - **Scope (no silent sampling).** Enumerate every changed source/test file via `git diff --name-only <base>...HEAD` and review each one. Skipping a changed file silently is a `contract-violated` outcome. If a file's language has no reference and is not covered by the agnostic checks below, record `design-review skipped: <file> (language=<x> no reference)` — never pass it silently.
-- **Load the same conventions the executor used, per language.** For each touched language load the coding-conventions reference (`coding-preflight` `languages/<lang>.md` + `clean-code.md` + the hexagonal overlay when the layout matches); degrade to the agnostic checks below when no skill is reachable. The verifier does NOT inline language rules — it loads them per situation, identical to the executor preflight.
+- **Load the same conventions the executor used, per language.** For each touched language load the coding-conventions reference by reading `~/.claude/skills/okstra-coding-preflight/languages/<lang>.md` + `clean-code.md` + the `architecture/hexagonal.md` overlay when the layout matches; degrade to the agnostic checks below when those files are not readable. The verifier does NOT inline language rules — it loads them per situation, identical to the executor preflight.
 - **Blocking checks (any hit → verdict `FAIL`, cited `path:line` + rule name, recommended fix recorded — the verifier does NOT apply it):**
   - **Self-mocking:** a test for `Foo` stubs/spies a method on the `Foo` instance under test (`jest.spyOn(sut, ...)`, `spyOn(FooService.prototype, ...)` in `foo.*.spec.*`, `vi.mocked(sut)` + stub). Mocking injected collaborators is fine.
   - **Interaction-only assertion:** a test whose only/primary assertion is `toHaveBeenCalled*` / `toHaveBeenCalledTimes` on an internal helper or a non-side-effecting collaborator, with no assertion on the returned value / resulting state / persisted row / emitted event.

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

@@ -76,6 +76,7 @@
   - validation checklist (pre / mid / post) — each item is an exact command or observable outcome
   - rollback strategy — exact revert path (commits, flags, migrations) and the signal that triggers rollback
   - the YAML frontmatter MUST include the line `approved: false` (report-writer always emits the unflipped value). The user authorises the next `implementation` run by flipping it to `approved: true` (manual edit or `--approve` CLI). Do NOT recreate any `User Approval Request` body block — the validator fails reports that contain one (see `validators/validate-run.py` deprecated patterns).
+  - the YAML frontmatter MUST include the line `implementation-option:` directly under `approved:` (report-writer always emits it with an **empty value**). The user selects which Option Candidate the next `implementation` run executes by filling this line with that option's name (manual edit or `--implementation-option <name>` CLI). When left empty, the `implementation` run falls back to the `Recommended Option`.
   - **the frontmatter `approved: false` line is rendered unconditionally; if the plan-body verification gate (§5.5.9) returns `blocked-by-disagreement` or `aborted-non-result`, the writer MUST keep `approved: false` and the validator refuses any report that ships with `approved: true` under such a gate result.**
   - every ambiguity flagged during pre-planning that the user must resolve before approval registered as a `Blocks=approval` row in the `## 1. Clarification Items` table (do NOT create a separate `Open Questions` block under `4.5.x` — the unified table is the single home)
   - **§5.5.9 Plan Body Verification (BLOCKING).** After report-writer finishes the draft, the lead MUST run a worker peer-review round on the consolidated plan body (sections 4.5.1 – 4.5.7) and populate `### 5.5.9 Plan Body Verification` in the final report. The round protocol, plan-item ID scheme (`P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*`), verdict semantics, gate-result classification, and dissent log format are defined in `skills/okstra-convergence/SKILL.md` "Plan-body verification mode". The four gate-result values are `passed`, `passed-with-dissent`, `blocked-by-disagreement`, `aborted-non-result`. When the gate would have been `blocked-by-disagreement` or `aborted-non-result`, the lead MUST NOT silently flip it to one of the passing values to "unblock" the run — that is a contract violation. When `convergence.adversarial=true` (the default for this phase), this round uses the adversarial posture — verifiers confirm cited paths/commands and the burden of proof is on the plan — but the gate threshold stays `majority-disagree` (see that skill's §"Adversarial plan-body posture").

package/runtime/prompts/profiles/implementation.md

@@ -19,7 +19,7 @@
   - the run brief MUST cite `--approved-plan <path>` pointing to a `final-report.md` produced by a prior `implementation-planning` run located under `runs/implementation-planning/.../reports/final-report.md`
   - that file's YAML frontmatter MUST carry `approved: true`. report-writer emits `approved: false` by default; the user flips it to `true` to authorise this run. Free-form approvals such as "lgtm" / "go ahead" / paraphrased confirmations are NOT accepted; re-edit the plan file's frontmatter to `approved: true` before invoking implementation, or pass `--approve` so the CLI flips it on the user's behalf (`okstra_ctl.run._apply_cli_approval`).
   - The `--approve` flag is meaningful ONLY with `--task-type implementation` and `--approved-plan <path>`; any other use raises `PrepareError`. Idempotent — re-running with `approved: true` already set appends an audit line but does NOT re-toggle.
-  - the file's `Recommended option` and its bite-sized step list become the authoritative scope for this run; deviations must be justified in the final report and routed back to a new `implementation-planning` run rather than silently expanded.
+  - the authoritative scope for this run is the Option Candidate named by the YAML frontmatter `implementation-option:` field. **If `implementation-option:` is empty, fall back to the plan's `Recommended Option`** (this is a soft fallback, not a hard block). The chosen option's bite-sized step list becomes the authoritative scope; deviations must be justified in the final report and routed back to a new `implementation-planning` run rather than silently expanded. If the chosen option name does not match any heading under `Option Candidates`, record it as a deviation.
 - Task worktree (provisioned by `okstra-ctl` at the first phase's run-prep time, reused for every subsequent phase of this task-key):
   - Status: `{{EXECUTOR_WORKTREE_STATUS}}` (one of: `created` | `reused` | `skipped-in-worktree` | `skipped-not-git`)
   - Working tree path: `{{EXECUTOR_WORKTREE_PATH}}` — when status is `created` or `reused`, this is the task's `git worktree` rooted at `~/.okstra/worktrees/<project>/<task-group>/<task-id>/`. When skipped, this is the caller's `project_root`.

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -0,0 +1,259 @@
+"""Build the compact analysis-worker input packet for a task run."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+BRIEF_SECTIONS = (
+    "Identity",
+    "Request Summary",
+    "Current Context",
+    "Evidence and Source Materials",
+    "Task-Type Focus",
+    "Constraints and Risks",
+    "Out of Scope",
+    "Configuration References and Expected Values",
+    "Deployment Manifests and Expected Values",
+    "Questions for Workers",
+    "Expected Outputs",
+    "Task Continuity Notes",
+    "Available MCP Servers",
+)
+PROFILE_SECTIONS = (
+    "Primary focus areas",
+    "Expected output emphasis",
+    "Non-goals",
+    "Clarification request policy",
+)
+CLARIFICATION_SECTIONS = (
+    "Clarification Items",
+    "Clarification Response Carried In From Previous Run",
+)
+_FRONTMATTER_RE = re.compile(r"\A---\n(?P<body>.*?)\n---\n", re.DOTALL)
+
+
+def build_analysis_packet(
+    *,
+    task_key: str,
+    task_type: str,
+    task_brief_path: Path,
+    analysis_profile_path: Path,
+    reference_expectations_path: Path,
+    clarification_response_path: Path | None,
+    directive: str,
+    instruction_set_relative_path: str,
+) -> str:
+    """Return the primary compact input for Claude/Codex/Gemini analysers."""
+    brief_text = task_brief_path.read_text(encoding="utf-8")
+    profile_text = analysis_profile_path.read_text(encoding="utf-8")
+    reference_text = _read_optional(reference_expectations_path)
+    clarification_text = (
+        _read_optional(clarification_response_path)
+        if clarification_response_path else ""
+    )
+    parts = [_packet_frontmatter(brief_text, task_key)]
+    parts.extend(
+        _intro_block(
+            task_key,
+            instruction_set_relative_path,
+            bool(clarification_response_path),
+        )
+    )
+    parts.extend(_brief_block(brief_text))
+    parts.extend(_profile_block(task_type, profile_text))
+    parts.extend(_reference_block(reference_text))
+    parts.extend(_clarification_block(clarification_text))
+    parts.extend(_directive_block(directive))
+    return "\n".join(part.rstrip() for part in parts).rstrip() + "\n"
+
+
+def _packet_frontmatter(brief_text: str, task_key: str) -> str:
+    frontmatter = _extract_frontmatter(brief_text)
+    if frontmatter:
+        return (
+            f"---\n{frontmatter}\n"
+            'packetVersion: "1.0"\n'
+            "packetRole: analysis-worker-primary\n---"
+        )
+    return (
+        "---\n"
+        f'title: OKSTRA Analysis Packet - {task_key}\n'
+        'packetVersion: "1.0"\n'
+        "packetRole: analysis-worker-primary\n"
+        "---"
+    )
+
+
+def _intro_block(
+    task_key: str,
+    instruction_set: str,
+    has_clarification: bool,
+) -> list[str]:
+    lines = [
+        f"# OKSTRA Analysis Packet - {task_key}",
+        "",
+        "## Packet Role",
+        "",
+        "- This packet is the primary required reading for analysis workers.",
+        "- It extracts task-specific material from the source files listed below.",
+        "- Read source files only for evidence verification or missing detail.",
+        "",
+        "## Source Files",
+        "",
+        f"- Task brief: `{instruction_set}/task-brief.md`",
+        f"- Analysis profile: `{instruction_set}/analysis-profile.md`",
+        f"- Analysis material: `{instruction_set}/analysis-material.md`",
+        f"- Reference expectations: `{instruction_set}/reference-expectations.md`",
+    ]
+    if has_clarification:
+        lines.append(
+            f"- Clarification response: `{instruction_set}/clarification-response.md`"
+        )
+    return lines
+
+
+def _brief_block(brief_text: str) -> list[str]:
+    return [
+        "",
+        "## Task-Specific Brief Extract",
+        "",
+        _extract_sections(brief_text, BRIEF_SECTIONS),
+    ]
+
+
+def _profile_block(task_type: str, profile_text: str) -> list[str]:
+    profile_sections = _extract_sections(profile_text, PROFILE_SECTIONS)
+    profile_bullets = _extract_bullet_sections(profile_text, PROFILE_SECTIONS)
+    profile_focus = "\n\n".join(
+        part for part in (profile_sections, profile_bullets)
+        if part and not part.startswith("- No matching")
+    )
+    return [
+        "",
+        "## Phase Focus Extract",
+        "",
+        f"- Task Type: `{task_type}`",
+        "",
+        _extract_profile_prelude(profile_text),
+        "",
+        profile_focus or "- No matching source sections were available.",
+    ]
+
+
+def _reference_block(reference_text: str) -> list[str]:
+    body = reference_text.strip() or "- No reference expectations content was available."
+    return ["", "## Reference Expectations", "", body]
+
+
+def _clarification_block(clarification_text: str) -> list[str]:
+    if not clarification_text.strip():
+        return []
+    return [
+        "",
+        "## Clarification Carry-In Extract",
+        "",
+        _extract_sections(clarification_text, CLARIFICATION_SECTIONS),
+    ]
+
+
+def _directive_block(directive: str) -> list[str]:
+    if not directive:
+        return []
+    return ["", "## Directive", "", directive.strip()]
+
+
+def _extract_frontmatter(text: str) -> str:
+    match = _FRONTMATTER_RE.match(text)
+    return match.group("body").rstrip() if match else ""
+
+
+def _extract_profile_prelude(text: str) -> str:
+    lines = []
+    for line in text.splitlines():
+        if line.startswith(("{{INCLUDE:", "## ", "<!--", "- Team contract")):
+            break
+        if _top_level_bullet_heading(line) in PROFILE_SECTIONS:
+            break
+        if line.strip():
+            lines.append(line)
+    return "\n".join(lines).strip() or "- No profile prelude was available."
+
+
+def _extract_sections(text: str, headings: tuple[str, ...]) -> str:
+    sections = _section_map(text)
+    out = []
+    for heading in headings:
+        body = sections.get(heading, "").strip()
+        if body:
+            out.append(f"### {heading}\n\n{body}")
+    return "\n\n".join(out) or "- No matching source sections were available."
+
+
+def _extract_bullet_sections(text: str, headings: tuple[str, ...]) -> str:
+    heading_set = set(headings)
+    captured: list[tuple[str, list[str]]] = []
+    current_heading = ""
+    current_lines: list[str] = []
+
+    def flush_current() -> None:
+        nonlocal current_heading, current_lines
+        if current_heading and current_lines:
+            captured.append((current_heading, current_lines))
+        current_heading = ""
+        current_lines = []
+
+    for line in _strip_frontmatter(text).splitlines():
+        bullet_heading = _top_level_bullet_heading(line)
+        if bullet_heading:
+            if bullet_heading in heading_set:
+                flush_current()
+                current_heading = bullet_heading
+                current_lines = [line]
+                continue
+            flush_current()
+            continue
+        if current_heading:
+            if line.startswith("  ") or not line.strip():
+                current_lines.append(line)
+            else:
+                flush_current()
+    flush_current()
+
+    out = []
+    for heading, lines in captured:
+        body = "\n".join(lines).strip()
+        if body:
+            out.append(f"### {heading}\n\n{body}")
+    return "\n\n".join(out)
+
+
+def _top_level_bullet_heading(line: str) -> str:
+    if not line.startswith("- ") or ":" not in line:
+        return ""
+    label = line[2:].split(":", 1)[0].strip().strip("*")
+    return label
+
+
+def _section_map(text: str) -> dict[str, str]:
+    result: dict[str, list[str]] = {}
+    current = ""
+    for line in _strip_frontmatter(text).splitlines():
+        if line.startswith("## "):
+            current = line[3:].strip()
+            result.setdefault(current, [])
+            continue
+        if current:
+            result[current].append(line)
+    return {key: "\n".join(lines).strip() for key, lines in result.items()}
+
+
+def _strip_frontmatter(text: str) -> str:
+    match = _FRONTMATTER_RE.match(text)
+    return text[match.end():] if match else text
+
+
+def _read_optional(path: Path | None) -> str:
+    if path and path.is_file():
+        return path.read_text(encoding="utf-8")
+    return ""