okstra 0.75.0 → 0.76.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.75.0",
+  "version": "0.76.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.75.0",
-  "builtAt": "2026-06-11T19:32:02.652Z",
+  "package": "0.76.0",
+  "builtAt": "2026-06-11T20:04:51.254Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -135,7 +135,7 @@ This wrapper does NOT invoke MCP tools directly. MCP availability inside the Cod
 - Treat the prompt-history path as the canonical worker prompt history artifact for the current run, resolved to absolute against `Project Root` if given as relative.
 - The assigned model execution value is canonical for CLI execution. Do not substitute a different Codex model unless the task bundle explicitly changes it.
 - Pass the prompt received from Lead directly to codex after persisting the exact prompt to the assigned path.
-- **Executor preflight forwarding check (implementation runs only).** When the lead prompt assigns this dispatch the `Executor` role for an `implementation` run, the persisted prompt body MUST contain the literal heading `Coding-conventions preflight` (transcribed by the lead from `prompts/profiles/_implementation-executor.md` → "Pre-implementation context exploration") — the Codex CLI does not share the lead's context, so an untranscribed gate never reaches the process that writes the code. If the heading is absent, return `CODEX_PREFLIGHT_MISSING: executor dispatch prompt lacks the coding-conventions preflight block` instead of invoking the CLI; the lead is responsible for re-dispatching with the block included. This check does NOT apply to verifier or analysis dispatches.
+- **Executor preflight forwarding check (implementation runs only).** When the lead prompt assigns this dispatch the `Executor` role for an `implementation` run, the persisted prompt body MUST contain the literal heading `Coding-conventions preflight` (the lead appends the body of `prompts/profiles/_coding-conventions-preflight.md` into the dispatch prompt — see `prompts/profiles/_implementation-executor.md` → "Pre-implementation context exploration") — the Codex CLI does not share the lead's context, so an unforwarded gate never reaches the process that writes the code. If the heading is absent, return `CODEX_PREFLIGHT_MISSING: executor dispatch prompt lacks the coding-conventions preflight block` instead of invoking the CLI; the lead is responsible for re-dispatching with the block included. This check does NOT apply to verifier or analysis dispatches.
 - Include context (code, diff, file paths) if provided.
 - For long prompts, dispatch through the wrapper with literal absolute paths (plus the worktree path for implementation phase):
   ```bash

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

@@ -135,7 +135,7 @@ This wrapper does NOT invoke MCP tools directly. MCP availability inside the Gem
 - Treat the prompt-history path as the canonical worker prompt history artifact for the current run, resolved to absolute against `Project Root` if given as relative.
 - The assigned model execution value is canonical for CLI execution. Do not substitute a different Gemini model unless the task bundle explicitly changes it.
 - Pass the prompt received from Lead directly to gemini after persisting the exact prompt to the assigned path.
-- **Executor preflight forwarding check (implementation runs only).** When the lead prompt assigns this dispatch the `Executor` role for an `implementation` run, the persisted prompt body MUST contain the literal heading `Coding-conventions preflight` (transcribed by the lead from `prompts/profiles/_implementation-executor.md` → "Pre-implementation context exploration") — the Gemini CLI does not share the lead's context, so an untranscribed gate never reaches the process that writes the code. If the heading is absent, return `GEMINI_PREFLIGHT_MISSING: executor dispatch prompt lacks the coding-conventions preflight block` instead of invoking the CLI; the lead is responsible for re-dispatching with the block included. This check does NOT apply to verifier or analysis dispatches.
+- **Executor preflight forwarding check (implementation runs only).** When the lead prompt assigns this dispatch the `Executor` role for an `implementation` run, the persisted prompt body MUST contain the literal heading `Coding-conventions preflight` (the lead appends the body of `prompts/profiles/_coding-conventions-preflight.md` into the dispatch prompt — see `prompts/profiles/_implementation-executor.md` → "Pre-implementation context exploration") — the Gemini CLI does not share the lead's context, so an unforwarded gate never reaches the process that writes the code. If the heading is absent, return `GEMINI_PREFLIGHT_MISSING: executor dispatch prompt lacks the coding-conventions preflight block` instead of invoking the CLI; the lead is responsible for re-dispatching with the block included. This check does NOT apply to verifier or analysis dispatches.
 - Include context (code, diff, file paths) if provided.
 - For long prompts, dispatch through the wrapper with literal absolute paths (plus the worktree path for implementation phase):
   ```bash

package/runtime/prompts/profiles/_coding-conventions-preflight.md

@@ -0,0 +1,21 @@
+<!--
+Single source for the executor's Coding-conventions preflight gate. Two delivery
+paths converge here (see _implementation-executor.md "Pre-implementation context
+exploration"):
+  - Claude executor reads this file directly before its first Edit / Write.
+  - codex / gemini executor cannot read this path (it sits outside the CLI
+    sandbox and the CLI only sees its stdin prompt), so the lead appends this
+    file's body into the persisted executor prompt at dispatch time.
+The `Coding-conventions preflight` heading below is the literal string the CLI
+wrapper's "Executor preflight forwarding check" greps for in the persisted
+prompt (agents/workers/_cli-wrapper-template.md → Prompt Composition).
+-->
+
+# Coding-conventions preflight (BLOCKING — runs before the first `Edit` / `Write`, and binds the TDD loop)
+
+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 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.
+- **Project review rule packs:** also look for project-local review skills in `<PROJECT_ROOT>/skills/*review*`, `<PROJECT_ROOT>/.claude/skills/*review*`, and up to two parent directories' `skills/*review*/SKILL.md`. Read the relevant `SKILL.md` plus referenced `references/*.md` files and apply their rules during implementation. This is a prevention pass, not a PR-comment generation workflow: do not dispatch reviewer subagents from the executor. For Fonts Ninja-style PR review packs, the executor must avoid newly introduced duplicate helper stacks, tautological tests that merely re-call the delegated helper, self-mocking, domain rules in adapters/ports, domain objects outside `domain/`, dead APIs, weak public names, and functions that fail the plain-English read.
+- **Language-agnostic principles that ALWAYS bind (the TDD loop 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 (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.

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

@@ -19,12 +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 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.
-  - **Project review rule packs:** also look for project-local review skills in `<PROJECT_ROOT>/skills/*review*`, `<PROJECT_ROOT>/.claude/skills/*review*`, and up to two parent directories' `skills/*review*/SKILL.md`. Read the relevant `SKILL.md` plus referenced `references/*.md` files and apply their rules during implementation. This is a prevention pass, not a PR-comment generation workflow: do not dispatch reviewer subagents from the executor. For Fonts Ninja-style PR review packs, the executor must avoid newly introduced duplicate helper stacks, tautological tests that merely re-call the delegated helper, self-mocking, domain rules in adapters/ports, domain objects outside `domain/`, dead APIs, weak public names, and functions that fail the plain-English read.
-  - **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 (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.
-  - **CLI executor transcription (BLOCKING when the executor provider is `codex` or `gemini`):** the executor CLI process does NOT share the lead's context — a gate that stays in lead memory never reaches it. The lead MUST copy this entire "Coding-conventions preflight" bullet tree (file-read instructions, project review rule packs, agnostic principles, graceful degradation) verbatim into the dispatched executor prompt body. Enforcement: the CLI wrapper agents refuse an implementation-Executor dispatch whose persisted prompt lacks the literal heading `Coding-conventions preflight`, returning `<SENTINEL_PREFIX>_PREFLIGHT_MISSING` (see `agents/workers/_cli-wrapper-template.md` → Prompt Composition).
+- **Coding-conventions preflight (BLOCKING — runs before the first `Edit` / `Write`, and binds the TDD loop below).** The gate body is a single source at `prompts/profiles/_coding-conventions-preflight.md` (sibling of this sidecar): skill-file pointers (`~/.claude/skills/okstra-coding-preflight/`), project review rule packs, the always-binding language-agnostic principles, and graceful degradation. Do NOT re-type that content from memory — deliver it by file so it cannot drift or be dropped:
+  - **Claude executor:** Read `_coding-conventions-preflight.md` end-to-end before the first `Edit` / `Write`, then state in ONE line which conventions apply (e.g. `Applying TS + hexagonal overlay; domain at src/domains/*/domain/`).
+  - **CLI executor (BLOCKING when the executor provider is `codex` or `gemini`):** the executor CLI process does NOT share the lead's context, and it cannot Read this sidecar's directory — that path sits outside the CLI sandbox and the CLI only sees its stdin prompt, so a file reference never reaches it. The lead MUST physically append the **body** of `_coding-conventions-preflight.md` into the persisted executor prompt at dispatch time: Read the file from the same absolute directory you read this sidecar from, then `Write`/`cat` its body into the persisted prompt. Never hand-retype it. Enforcement: the CLI wrapper agents refuse an implementation-Executor dispatch whose persisted prompt lacks the literal heading `Coding-conventions preflight`, returning `<SENTINEL_PREFIX>_PREFLIGHT_MISSING` (see `agents/workers/_cli-wrapper-template.md` → Prompt Composition).
 - **Stage discipline transcription (when a preceding stage is `done`):** the lead MUST transcribe the `Stage discipline` rule (from this run's rendered profile — the INCLUDEd `_stage-discipline.md` body) verbatim into the dispatched CLI executor prompt, so a codex/gemini executor honors the prior-stage behavior-freeze. Declaration-level — no wrapper sentinel.
 - **Non-interactive auto-execution (BLOCKING when the executor provider is `codex` or `gemini`).** A CLI executor runs head-less (`codex exec` / gemini equivalent) — there is no human at the keyboard. Skills loaded during the run (tdd, coding-preflight, and others) contain "get user approval", "state your plan to the user and wait", or "ask before proceeding" gates written for interactive sessions; in this run those gates are **already satisfied** by the upstream `implementation-planning` approval (the plan this stage executes was human-approved). The executor MUST NOT stop to request approval, MUST NOT end its turn after only producing a plan, and MUST carry the stage through end-to-end — RED → GREEN → refactor → per-step commits → `### Stage Carry Evidence`. The ONLY skill step to skip is the interactive user-approval prompt itself; every other skill rule (TDD discipline, conventions, real-IO isolation) still binds. The lead MUST transcribe this bullet verbatim into the dispatched CLI executor prompt (same reason as the preflight transcription rule above — the CLI process does not share lead context). Stopping early for approval in a head-less run is the observed empty-exit failure (exit 0, no diff): treat it as `contract-violated`.
 - **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.

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

@@ -196,6 +196,7 @@
     },
     "approved_plan_pick": {
       "label": "approved final-report 경로 (기본: {default})",
+      "label_final_verification": "검증 기준이 될 승인된 plan(approved final-report) 을 선택하세요 (기본: {default})",
       "echo_template": "approved-plan(pick): {value}",
       "options": {
         "__use_default__": "기본 경로 사용: {default}",
@@ -216,12 +217,17 @@
       "echo_template": "approved-plan: {value}"
     },
     "approve_plan_confirm": {
-      "label": "이 플랜으로 진행할까요?\n  {path}\n· 예 — 진행합니다. 플랜이 아직 승인 전이면 지금 data.json(정본) + 리포트를 함께 approved 로 처리한 뒤 진행합니다. (markdown 만 손으로 고치면 일관성 검증에서 거부되므로 이 경로로 승인하세요.)\n· 아니오 — 진행하지 않습니다.",
+      "label": "이 플랜으로 구현을 진행할까요?\n  {path}\n· 예 — 이 plan 대로 구현을 실행합니다. 플랜이 아직 승인 전이면 지금 data.json(정본) + 리포트를 함께 approved 로 처리한 뒤 진행합니다. (markdown 만 손으로 고치면 일관성 검증에서 거부되므로 이 경로로 승인하세요.)\n· 아니오 — 진행하지 않습니다.",
+      "label_final_verification": "이 plan 을 검증 기준으로 삼아 진행할까요?\n  {path}\n· 예 — 선택한 stage 의 구현 결과를 위 plan 기준으로 검증합니다. (plan 이 아직 승인 전이면 data.json(정본) + 리포트를 함께 approved 로 처리한 뒤 검증합니다.)\n· 아니오 — 진행하지 않습니다.",
       "html_approval_note": "\nHTML 승인 기록 발견: {sidecar}\n  선택 옵션: {option}\n· 예(기록 적용) — 승인과 함께 위 옵션을 frontmatter 에 기록합니다.",
       "html_approval_note_default_option": "(추천 옵션 그대로)",
       "echo_template": "approve-plan: {value}",
       "options": {
-        "yes": "예 — 승인하고 진행",
+        "yes": "예 — 승인하고 구현 진행",
+        "no": "아니오 — 진행하지 않음"
+      },
+      "options_final_verification": {
+        "yes": "예 — 이 plan 기준으로 검증 진행",
         "no": "아니오 — 진행하지 않음"
       },
       "options_html_approval": {
@@ -230,8 +236,10 @@
         "no": "아니오 — 진행하지 않음"
       },
       "echo_variants": {
-        "selected": "plan 선택: {path} — 다음 단계에서 승인·진행 여부를 확인합니다",
-        "approved": "approved-plan: {path} (승인·진행 확인됨)",
+        "selected": "plan 선택: {path} — 다음 단계에서 승인·구현 진행 여부를 확인합니다",
+        "selected_final_verification": "검증 기준 plan 선택: {path} — 다음 단계에서 검증 진행 여부를 확인합니다",
+        "approved": "approved-plan: {path} (승인·구현 진행 확인됨)",
+        "approved_final_verification": "검증 기준 plan 확정: {path} (검증 진행 확인됨)",
         "approved_with_option": "approved-plan: {path} (승인 + 옵션 `{option}` 적용됨)"
       },
       "errors": {

package/runtime/python/okstra_ctl/wizard.py

@@ -635,7 +635,12 @@ def _stage_plan_for_confirmation(
         state.html_approval_sidecar = str(sidecar_path)
         state.html_approval_option = record.implementation_option
     t = _p(state.workspace_root, "approve_plan_confirm", path=str(p))
-    msg = t["echo_variants"]["selected"].format(path=p)
+    variants = t["echo_variants"]
+    key = ("selected_final_verification"
+           if state.task_type == "final-verification"
+           and variants.get("selected_final_verification")
+           else "selected")
+    msg = variants[key].format(path=p)
     return f"{msg} {suffix}".rstrip() if suffix else msg
 
 
@@ -770,8 +775,10 @@ def _p(workspace_root: str, step_id: str, **vars: str) -> dict:
     if raw is None:
         raise WizardError(f"unknown wizard step_id: {step_id!r}")
     label_template = raw.get("label", "")
+    fv_label_template = raw.get("label_final_verification", "")
     try:
         label = label_template.format(**vars)
+        label_final_verification = fv_label_template.format(**vars)
     except KeyError as exc:
         missing = exc.args[0] if exc.args else "<unknown>"
         raise WizardError(
@@ -779,8 +786,10 @@ def _p(workspace_root: str, step_id: str, **vars: str) -> dict:
         ) from exc
     return {
         "label": label,
+        "label_final_verification": label_final_verification,
         "echo_template": raw.get("echo_template", ""),
         "options": raw.get("options", {}),
+        "options_final_verification": raw.get("options_final_verification", {}),
         "options_html_approval": raw.get("options_html_approval", {}),
         "html_approval_note": raw.get("html_approval_note", ""),
         "html_approval_note_default_option": raw.get(
@@ -1626,6 +1635,8 @@ def _build_approved_plan_pick(state: WizardState) -> Prompt:
     default = reports[0] if reports else None
     t = _p(state.workspace_root, "approved_plan_pick",
            default=str(default) if default is not None else "")
+    is_fv = state.task_type == "final-verification"
+    label = (t["label_final_verification"] or t["label"]) if is_fv else t["label"]
     other_report_label = t["labels"]["other_report"]
     options: list[Option] = []
     if default is not None:
@@ -1637,7 +1648,7 @@ def _build_approved_plan_pick(state: WizardState) -> Prompt:
     options.append(_opt(PICK_OTHER, t["options"][PICK_OTHER]))
     return Prompt(
         step=S_APPROVED_PLAN_PICK, kind="pick",
-        label=t["label"], options=options,
+        label=label, options=options,
         echo_template=t["echo_template"],
     )
 
@@ -1679,8 +1690,9 @@ def _submit_approved_plan(state: WizardState, value: str) -> Optional[str]:
 def _build_approve_plan_confirm(state: WizardState) -> Prompt:
     t = _p(state.workspace_root, "approve_plan_confirm",
            path=state.approve_plan_candidate)
-    label = t["label"]
-    options_map = t["options"]
+    is_fv = state.task_type == "final-verification"
+    label = (t["label_final_verification"] or t["label"]) if is_fv else t["label"]
+    options_map = (t["options_final_verification"] or t["options"]) if is_fv else t["options"]
     if state.html_approval_sidecar:
         label += t["html_approval_note"].format(
             sidecar=state.html_approval_sidecar,
@@ -1728,7 +1740,12 @@ def _submit_approve_plan_confirm(state: WizardState, value: str) -> Optional[str
             if not fully_approved:
                 raise WizardError(
                     t["errors"]["still_unapproved"].format(path=resolved))
-        echo = t["echo_variants"]["approved"].format(path=resolved)
+        variants = t["echo_variants"]
+        approved_key = ("approved_final_verification"
+                        if state.task_type == "final-verification"
+                        and variants.get("approved_final_verification")
+                        else "approved")
+        echo = variants[approved_key].format(path=resolved)
         if apply_option:
             _apply_cli_implementation_option(
                 str(resolved), state.html_approval_option)
@@ -1748,10 +1765,7 @@ def _build_stage_pick(state: WizardState) -> Prompt:
     t = _p(state.workspace_root, "stage_pick")
     stages = _parse_stage_objects(state)
     is_fv = state.task_type == "final-verification"
-    label = (
-        t.get("label_final_verification", t["label"])
-        if is_fv else t["label"]
-    )
+    label = (t["label_final_verification"] or t["label"]) if is_fv else t["label"]
     done = _done_stage_numbers(state) if is_fv else set()
     options = []
     if _stage_auto_allowed(state):