okstra 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.20.0",
+  "version": "0.21.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.20.0",
-  "builtAt": "2026-05-13T15:25:34.223Z",
+  "package": "0.21.0",
+  "builtAt": "2026-05-14T11:48:06.992Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -205,7 +205,11 @@ Convergence is enabled by default. Configure via task-manifest.json:
 - `convergence.maxRounds`: 1–3 — **phase-aware default**: `1` for `requirements-discovery`, `2` for all other task types
 - `convergence.verificationMode`: `"lightweight"` | `"full-reanalysis"` (default: `"lightweight"`)
 
-When `task-manifest.json` does not set `convergence.maxRounds`, lead MUST resolve the effective value via the phase-aware default above before entering Phase 5.5, and record the resolved value in the convergence state artifact.
+When `task-manifest.json` does not set `convergence.maxRounds`, lead MUST resolve the effective value via the phase-aware default above before entering Phase 5.5, and record the resolved value in the convergence state artifact at `config.effectiveMaxRounds`.
+
+**Round 2 is gated, not unconditional.** Even when `effectiveMaxRounds == 2`, Round 2 runs only when (a) the verification queue is non-empty after Round 1, AND (b) at least one Round 1 reverify dispatch terminated as `completed`. Otherwise lead writes `round2SkippedReason` to the convergence state and proceeds to final classification. See [okstra-convergence](./skills/okstra-convergence/SKILL.md) "Round 2 gate" for the predicate.
+
+**Confirmed findings are pruned from the queue.** Findings classified as `full-consensus`, `partial-consensus`, or `worker-unique` MUST NOT appear in any subsequent round's reverify prompt for any worker. `contested` is a final classification assigned only when the last executed round completes and the queue is still non-empty — it is NEVER an intermediate queue label.
 
 If any re-verification batch yields a `verification-error` terminal status, or a worker result fails the contract, Lead MUST record one event per violation via `python3 scripts/okstra-error-log.py append-observed --error-type contract-violation --agent <offending-agent> ...`. Use `agent: "claude-lead"` only when the violation is detected internally without a specific worker.
 
@@ -282,4 +286,6 @@ After persistence, reply briefly in Korean with: completion status, final report
 | Letting `convergence.maxRounds` default to 2 for `requirements-discovery` | Resolve effective default to `1` for discovery and record in convergence state artifact |
 | Issuing serial Read calls in Phase 1 | The intake files are independent — issue all Read calls in a single message (parallel) |
 | Flagging the claude-worker dispatch prompt as "incomplete" because it lacks `[Required reading]` / `[Error reporting]` blocks | Intentional asymmetry — see [okstra-team-contract](./skills/okstra-team-contract/SKILL.md) "Asymmetry between claude-worker and codex/gemini-worker prompts" |
+| Re-sending confirmed findings (`full-consensus`/`partial-consensus`/`worker-unique`) to a worker in Round 2 | Queue pruning rule — see [okstra-convergence](./skills/okstra-convergence/SKILL.md) "Round 1-N: Re-verification Loop (queue-pruned)" |
+| Aggregating a `timeout`/`error` reverify dispatch as `DISAGREE` | Worker failure handling — record as `verification-error` and add to `skippedWorkers[]`. See [okstra-convergence](./skills/okstra-convergence/SKILL.md) "Worker failure handling in reverify" |
 | Skipping `--substitute-final-report` in the Phase 7 collector run | Always pass the flag — see [okstra-report-writer](./skills/okstra-report-writer/SKILL.md) "Phase 7 token-usage collector" |

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

@@ -27,9 +27,11 @@ You are a Codex worker agent. Your job is to execute the OpenAI Codex CLI and re
 
 **Required form (uses the okstra wrapper to avoid redirect-triggered permission prompts):**
 ```bash
-$HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" [<absolute-worktree-path>]
+$HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" [<absolute-worktree-path>] [<role>]
 ```
 
+The fifth argument `<role>` is the trace-pane label suffix (`codex-<role>-trace`); pass the literal string `worker` for every dispatch from this subagent. The wrapper defaults to `worker` when the argument is omitted, but pass it explicitly so the dispatch is self-describing.
+
 The fourth argument is **mandatory for implementation phase** and optional otherwise. It must be the literal `EXECUTOR_WORKTREE_PATH` recorded in the run context; the wrapper forwards it to codex as `--add-dir`, which grants the codex sandbox write access to the worktree (where all implementation-phase mutations occur). Without it, codex's `workspace-write` sandbox is anchored only at `<project-root>` and rejects every Edit/Write that targets the worktree (EPERM), which is the failure pattern that originally motivated this argument.
 
 The wrapper internally runs:
@@ -73,7 +75,7 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
 
    **Dispatch (background, no foreground timeout):**
    ```bash
-   $HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" "<absolute-worktree-path>"
+   $HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" "<absolute-worktree-path>" "worker"
    ```
    Call `Bash` with `run_in_background: true`. Capture the returned `bash_id` (a.k.a. `shell_id`). Pass the positional arguments verbatim — do NOT use environment variables, `cd`, `&&` chains, or pipes from `cat`. Substitute the literal extracted Project Root, model execution value, prompt-history path, and worktree path. The fourth argument is **mandatory for implementation phase** (extract from `EXECUTOR_WORKTREE_PATH` in the lead prompt's run context or the `**Worktree:**` / `cwd for every mutating command:` line) and **may be omitted only for non-implementation analysis phases** that do not mutate the worktree. Omitting it during implementation will cause every Edit/Write to fail with EPERM. The wrapper handles `-C`, `--add-dir`, `--model`, `--sandbox workspace-write`, the stdin redirect from the prompt file, and stderr suppression internally. Calling `codex exec` directly (without the wrapper) is an error in this skill: the redirect tokens disqualify the prefix match against `Bash(codex exec:*)` and produce a permission prompt every dispatch.
 
@@ -114,7 +116,7 @@ This wrapper does NOT invoke MCP tools directly. MCP availability inside the Cod
 - Include context (code, diff, file paths) if provided.
 - For long prompts, the wrapper script reads from the saved project-local prompt history file via stdin redirect internally. The caller invokes the wrapper with three required positional args + the worktree path for implementation phase:
   ```bash
-  $HOME/.okstra/bin/okstra-codex-exec.sh "<literal-project-root>" "<assigned-model-execution-value>" "<literal-prompt-history-path>" "<literal-worktree-path>"
+  $HOME/.okstra/bin/okstra-codex-exec.sh "<literal-project-root>" "<assigned-model-execution-value>" "<literal-prompt-history-path>" "<literal-worktree-path>" "worker"
   ```
 - If the parent directory does not exist yet, create it before writing the prompt file.
 
@@ -184,7 +186,7 @@ and the run-level error log staying empty.
      --agent codex-worker --agent-role worker \
      --model "<assigned-model-execution-value>" \
      --error-type cli-failure \
-     --command "$HOME/.okstra/bin/okstra-codex-exec.sh <project-root> <m> <prompt-path> <worktree-path>" \
+     --command "$HOME/.okstra/bin/okstra-codex-exec.sh <project-root> <m> <prompt-path> <worktree-path> worker" \
      --command-kind cli-invoke \
      --exit-code <N> --duration-ms <ms> \
      --message "<one-line summary>" \

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

@@ -27,9 +27,11 @@ You are a Gemini worker agent. Your job is to execute the Google Gemini CLI and
 
 **Required form (uses the okstra wrapper to avoid redirect-triggered permission prompts):**
 ```bash
-$HOME/.okstra/bin/okstra-gemini-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" [<absolute-worktree-path>]
+$HOME/.okstra/bin/okstra-gemini-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" [<absolute-worktree-path>] [<role>]
 ```
 
+The fifth argument `<role>` is the trace-pane label suffix (`gemini-<role>-trace`); pass the literal string `worker` for every dispatch from this subagent. The wrapper defaults to `worker` when the argument is omitted, but pass it explicitly so the dispatch is self-describing.
+
 The fourth argument is **mandatory for implementation phase** and optional otherwise. It must be the literal `EXECUTOR_WORKTREE_PATH` recorded in the run context; the wrapper appends it to gemini's `--include-directories` list so the model can both read and operate on the worktree alongside project-root.
 
 The wrapper internally runs:
@@ -73,7 +75,7 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
 
    **Dispatch (background, no foreground timeout):**
    ```bash
-   $HOME/.okstra/bin/okstra-gemini-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" "<absolute-worktree-path>"
+   $HOME/.okstra/bin/okstra-gemini-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" "<absolute-worktree-path>" "worker"
    ```
    Call `Bash` with `run_in_background: true`. Capture the returned `bash_id` (a.k.a. `shell_id`). Pass the positional arguments verbatim — do NOT use environment variables, `cd`, `&&` chains, or pipes from `cat`. Substitute the literal extracted Project Root, model execution value, prompt-history path, and worktree path. The fourth argument is **mandatory for implementation phase** (extract from `EXECUTOR_WORKTREE_PATH` in the lead prompt's run context or the `**Worktree:**` / `cwd for every mutating command:` line) and **may be omitted only for non-implementation analysis phases** that do not mutate the worktree. The wrapper handles `-p -`, `-m`, `-o text`, `--include-directories`, the stdin redirect from the prompt file, and stderr suppression internally. Calling `gemini` directly (without the wrapper) is an error in this skill: the redirect tokens disqualify the prefix match against `Bash(gemini:*)` and produce a permission prompt every dispatch.
 
@@ -114,7 +116,7 @@ This wrapper does NOT invoke MCP tools directly. MCP availability inside the Gem
 - 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
-  $HOME/.okstra/bin/okstra-gemini-exec.sh "<literal-project-root>" "<assigned-model-execution-value>" "<literal-prompt-history-path>" "<literal-worktree-path>"
+  $HOME/.okstra/bin/okstra-gemini-exec.sh "<literal-project-root>" "<assigned-model-execution-value>" "<literal-prompt-history-path>" "<literal-worktree-path>" "worker"
   ```
 - If the parent directory does not exist yet, create it before writing the prompt file.
 
@@ -184,7 +186,7 @@ and the run-level error log staying empty.
      --agent gemini-worker --agent-role worker \
      --model "<assigned-model-execution-value>" \
      --error-type cli-failure \
-     --command "$HOME/.okstra/bin/okstra-gemini-exec.sh <project-root> <m> <prompt-path> <worktree-path>" \
+     --command "$HOME/.okstra/bin/okstra-gemini-exec.sh <project-root> <m> <prompt-path> <worktree-path> worker" \
      --command-kind cli-invoke \
      --exit-code <N> --duration-ms <ms> \
      --message "<one-line summary>" \

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

@@ -49,6 +49,7 @@ Before writing the final report, you MUST read every input file enumerated in th
 - For the carry-in `clarification-response.md` (if present), walk every row of sub-section 5.1 (`A1`, `A2`, ...) and 5.2 (`Q1`, `Q2`, ...) including blank-answer rows. The fact that the file you write has a structurally similar Section 5/6 is NOT an excuse to skim.
 - Open every analysis-worker result file under `worker-results/` end-to-end. Do not summarize them from convergence output alone — convergence captures classifications, not full evidence.
 - Before writing, state one sentence per input file confirming end-to-end reading. If you cannot truthfully say this for a file, record a `tool-failure` in the errors sidecar instead of fabricating the report.
+- When the convergence-state file is present, read it fully and reproduce the `roundHistory[]` array, `round2SkippedReason`, and `finalClassificationCounts` in the final report's Section 1 Round History sub-table. Do not derive these values from worker results alone — they live in `state/convergence-<task-type>-<seq>.json`.
 
 ## Authoring Contract
 
@@ -58,6 +59,8 @@ Hard rules:
 
 - The file's `Author:` header line is `Report writer worker` (your role) — NOT `Claude lead`.
 - Include all four convergence categories (Full Consensus, Partial Consensus, Contested, Worker-Unique). Do not omit Contested or Worker-Unique findings.
+- Include a Round History sub-table in Section 1 (one row per executed round) and a `round2SkippedReason` line below it. When convergence is disabled, omit both. The values are quoted verbatim from `state/convergence-<task-type>-<seq>.json` — do not recompute.
+- Treat `verification-error` votes as their own verdict. They are listed in vote summaries as `verification-error`, not folded into AGREE/DISAGREE counts.
 - Include the per-agent execution status table and the token-usage summary section. All numbers come from `team-state-<task-type>-<seq>.json` (populated by `okstra-token-usage.py` at the start of Phase 7). Do not estimate or invent.
 - If only one analysis worker produced a usable result, perform a reduced-confidence write-up and say so explicitly.
 - If evidence is missing, write `I don't know` rather than fabricating confidence.
@@ -115,3 +118,4 @@ There is NO `cli-failure` category for this worker — it has no external CLI to
 - You do NOT produce independent analysis findings — your input is the analysis workers' results plus convergence output.
 - Do NOT modify analysis worker result files. They are read-only inputs to you.
 - If the analysis workers disagree and convergence ended with `Contested` items, surface them in the final report verbatim — do not silently pick a side.
+- `Contested` is a final-only classification. If you see findings labeled `Contested` in the convergence state, the lead has already exhausted re-verification — do not invent a synthesizing answer; surface each worker's position verbatim.

package/runtime/bin/okstra-codex-exec.sh

@@ -29,6 +29,18 @@
 # if worktree-path is non-empty (the implementation-phase invariant) and
 # `worker` otherwise.
 #
+# When role == `verifier`, the wrapper additionally grants the codex
+# `workspace-write` sandbox write access to `~/.cargo` and `~/.rustup` (when
+# they exist). Cargo's package-cache flock (`~/.cargo/.package-cache`) and
+# the registry/cache trees live OUTSIDE the workspace, so without these
+# extra `--add-dir` entries any `cargo build/test/clippy` invoked by the
+# verifier fails with `Resource temporarily unavailable` on the global
+# flock — which is the documented FU-V1 verifier-harness failure. Only the
+# `verifier` role gets this extension; other roles (`worker`, `executor`,
+# any custom label) keep the prior policy. Override per-role extras via the
+# `OKSTRA_CODEX_VERIFIER_EXTRA_DIRS` env var (colon-separated absolute
+# paths; empty disables the verifier extension entirely).
+#
 # For linked worktrees (the okstra implementation default), the per-worktree
 # git metadata (index, HEAD, refs) and the shared object database live in the
 # main repository's `.git` directory — OUTSIDE the worktree-path. Without
@@ -53,10 +65,7 @@ project_root="$1"
 model="$2"
 prompt_path="$3"
 worktree_path="${4-}"
-role="${5-}"
-if [[ -z "$role" ]]; then
-  if [[ -n "$worktree_path" ]]; then role="executor"; else role="worker"; fi
-fi
+role="${5:-worker}"
 
 if [[ -z "$project_root" || ! -d "$project_root" ]]; then
   printf 'okstra-codex-exec: project-root is missing or not a directory: %q\n' "$project_root" >&2
@@ -110,6 +119,25 @@ if [[ -n "$worktree_path" ]]; then
   fi
 fi
 
+# Verifier-role sandbox extension (see header comment for rationale).
+if [[ "$role" == "verifier" ]]; then
+  if [[ -n "${OKSTRA_CODEX_VERIFIER_EXTRA_DIRS+x}" ]]; then
+    verifier_extra_raw="$OKSTRA_CODEX_VERIFIER_EXTRA_DIRS"
+  else
+    verifier_extra_raw="${HOME}/.cargo:${HOME}/.rustup"
+  fi
+  if [[ -n "$verifier_extra_raw" ]]; then
+    IFS=':' read -r -a verifier_extra_dirs <<< "$verifier_extra_raw"
+    for verifier_dir in "${verifier_extra_dirs[@]}"; do
+      [[ -z "$verifier_dir" ]] && continue
+      if [[ -d "$verifier_dir" ]]; then
+        verifier_dir_abs=$(cd "$verifier_dir" && pwd -P)
+        extra_args+=(--add-dir "$verifier_dir_abs")
+      fi
+    done
+  fi
+fi
+
 # Derive a live-progress log path next to the prompt. The codex CLI streams
 # its progress over stdout/stderr, but the caller (codex-worker subagent)
 # only polls `BashOutput` on a 60s cadence — so without a sideband, a 10–30
@@ -127,8 +155,10 @@ log_path="${prompt_path%.md}.log"
 # for the wrapper to exit. This fires in every phase the wrapper is invoked
 # from (analysis, error-analysis, implementation-planning, implementation,
 # …) — long-running codex dispatches are not implementation-specific. The
-# new pane carries the title `codex-<role>-trace` (e.g. `codex-worker-trace`
-# in analysis, `codex-executor-trace` in implementation) and uses `tail -F`
+# new pane carries the title `codex-<role>-trace` — `role` is the optional
+# 5th positional arg (defaults to `worker`); callers that dispatch a
+# different role (e.g. `executor`) must pass it explicitly. The pane uses
+# `tail -F`
 # (follow-by-name) so it survives any truncation a re-dispatch performs on
 # the same log path. Failures are tolerated silently: missing $TMUX, a tmux
 # that refuses to split (size constraints, locked client), or a stale socket

package/runtime/bin/okstra-gemini-exec.sh

@@ -45,10 +45,7 @@ project_root="$1"
 model="$2"
 prompt_path="$3"
 worktree_path="${4-}"
-role="${5-}"
-if [[ -z "$role" ]]; then
-  if [[ -n "$worktree_path" ]]; then role="executor"; else role="worker"; fi
-fi
+role="${5:-worker}"
 
 if [[ -z "$project_root" || ! -d "$project_root" ]]; then
   printf 'okstra-gemini-exec: project-root is missing or not a directory: %q\n' "$project_root" >&2
@@ -112,10 +109,11 @@ log_path="${prompt_path%.md}.log"
 # When a tmux session is reachable, split a sibling pane tailing the log so
 # the operator can watch progress live. This fires in every phase the
 # wrapper is invoked from — long-running gemini dispatches are not
-# implementation-specific. Title `gemini-<role>-trace` (e.g.
-# `gemini-worker-trace` in analysis, `gemini-executor-trace` in
-# implementation). See the codex wrapper for the full design rationale and
-# the silent-degrade failure model.
+# implementation-specific. Title `gemini-<role>-trace` — `role` is the
+# optional 5th positional arg (defaults to `worker`); callers that
+# dispatch a different role must pass it explicitly. See the codex
+# wrapper for the full design rationale and the silent-degrade failure
+# model.
 if [[ -n "${TMUX:-}" ]]; then
   trace_pane=$(tmux split-window -h -P -F '#{pane_id}' \
     -c "$(dirname "$log_path")" \

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

@@ -19,8 +19,14 @@
   - acceptance blockers
   - residual risk
   - final release recommendations
+- Pre-verification entry gate (mandatory — refuse to start if any item fails):
+  - the task brief MUST cite the originating `implementation` final-report path under `## Source Implementation Report`. The lead opens that file and confirms it includes `Plan link & approval evidence`, `Commit list`, `Diff summary`, `Validation evidence`, and `Routing recommendation for final-verification`.
+  - the task brief MUST identify the worktree / checkout under verification and the implementation base ref. If the implementation report names a task worktree, final-verification MUST inspect that same worktree rather than the caller's original checkout.
+  - the lead MUST capture `git rev-parse HEAD`, `git status --short`, and `git diff --stat <implementation-base>..HEAD` from the verification worktree before dispatching workers. These values are the verification target and must be cited in the final report.
+  - if the cited implementation report is missing, lacks commits for delivered code changes, or the current checkout does not match the implementation report's commit list / diff summary, the run MUST end with status `blocked` and route back to `implementation` or `implementation-planning` rather than verifying an ambiguous target.
 - Required deliverable shape (final report, in addition to the standard sections):
-  - **Verdict vocabulary**: Section 2 (`Final Verdict`) MUST state exactly one of `accepted`, `conditional-accept`, or `blocked`. `conditional-accept` requires an explicit, exhaustive list of conditions; ambiguous verdicts ("looks good", "mostly ready") are not allowed.
+  - **Source Implementation Report**: relative path of the originating `implementation` final-report file, the quoted commit list / diff summary used as the verification target, the worktree path inspected, and the base/head SHAs captured at run start.
+  - **Verdict vocabulary**: Section 2 (`Final Verdict`) MUST include a `Verdict Token` field whose value is exactly one of `accepted`, `conditional-accept`, or `blocked`. `conditional-accept` requires an explicit, exhaustive list of conditions; ambiguous verdicts ("looks good", "mostly ready") are not allowed.
   - **Acceptance Blockers block** (under section 4): one row per blocker with `id`, `severity` (`critical` / `major` / `minor`), evidence (file path, log excerpt, or test output), and the recommended follow-up phase (`error-analysis` or `implementation-planning`). Empty block is acceptable and preferred — render the single line `- No acceptance blockers found.`
   - **Residual Risk block** (under section 4): risks that are not blockers but should be tracked, each with mitigation owner and a trigger that would escalate them to a blocker.
   - **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.
@@ -30,7 +36,7 @@
 - Clarification request policy (phase-specific addendum — shared policy is in `_common-contract.md`):
   - populate section 5 only when a blocker hinges on information only the user can supply (deployment intent, intended target environment, business-rule interpretation)
 - Self-review pass before finalising the report (`Claude lead` runs this; do not delegate to a generic subagent):
-  1. **Verdict precision** — section 2 uses one of the three allowed verdict tokens; `conditional-accept` lists every condition as an actionable item.
+  1. **Verdict precision** — section 2 includes `Verdict Token` with one of the three allowed verdict tokens; `conditional-accept` lists every condition as an actionable item.
   2. **Blocker traceability** — every blocker cites a concrete artifact (file:line, log excerpt, test exit code, MCP SELECT). Blockers without evidence are demoted to residual risk or removed.
   3. **Coverage check** — every requirement in the originating plan/task brief is either marked covered (with artifact) or listed as a blocker. No silent omissions.
   4. **Verifier dissent preserved** — if workers reach different verdicts, the disagreement is visible in section 1.2; synthesis hides nothing.

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

@@ -53,7 +53,7 @@
     - each step is one action completable in roughly 2–5 minutes (e.g. "write the failing test for X", "run it to confirm it fails", "implement minimal code", "run test to confirm pass", "commit")
     - every step names exact file paths and exact commands; for code steps, include the actual code or the diff sketch — not a description
     - prefer TDD ordering (failing test → implementation → green → commit) when the touched area has or can have tests
-  - dependency / migration risk assessment (ordering constraints, data backfills, feature-flag prerequisites, cross-team coordination)
+  - dependency / migration risk assessment (ordering constraints, data backfills, feature-flag prerequisites, repo-internal sequencing)
   - 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
   - explicit `User Approval Request (사용자 승인 게이트)` block placed at the **top of the report** with a single canonical checkbox marker `- [ ] Approved` (user toggles to `- [x] Approved` to authorise the next `implementation` run). Section `4.5.8` is retained only as a back-pointer to this top block for validator/key-substring compatibility — it must NOT carry an independent marker.

package/runtime/prompts/profiles/release-handoff.md

@@ -1,52 +1,49 @@
 # Release Handoff Profile
 
-- Purpose: take an `accepted` final-verification verdict and turn it into a delivered commit and/or pull request, with explicit user selection at every mutating step
-- **Execution model: single-lead, no worker dispatch.** This phase is a thin orchestrator over `git` / `gh`; it does NOT run team-mode, does NOT call `TeamCreate`, does NOT dispatch analysis or drafter sub-agents, and does NOT run convergence. The Claude lead performs every step inline (drafting commit/PR text, asking the user, running git, writing the final report) — see "Lead-only contract" below.
+- Purpose: take an `accepted` final-verification verdict for an already-committed implementation branch and turn it into a delivered push and/or pull request, with explicit user selection at every mutating step
+- **Execution model: single-lead, no worker dispatch.** This phase is a thin orchestrator over `git` / `gh`; it does NOT run team-mode, does NOT call `TeamCreate`, does NOT dispatch analysis or drafter sub-agents, and does NOT run convergence. The Claude lead performs every step inline (drafting PR text, asking the user, running git / gh, writing the final report) — see "Lead-only contract" below.
 - Required workers: *(none — this profile intentionally has no `- Required workers:` block; the run is executed entirely by the Claude lead)*
 - Lead-only contract (replaces the shared team contract for this phase):
   - The Claude lead is the sole agent for this run. No `Agent(...)` worker dispatch, no `TeamCreate`, no parallel sub-agents, no convergence loop.
-  - The lead drafts the commit message and PR body **inline** by reading the run brief, the cited final-verification report, and `git diff <base>..HEAD --stat`. No drafter worker is dispatched.
+  - The lead drafts the PR title and PR body **inline** by reading the run brief, the cited final-verification report, `git log --oneline <base>..HEAD`, and `git diff <base>..HEAD --stat`. No drafter worker is dispatched.
   - The lead authors the final-report file directly (no `Report writer worker` dispatch). The report still conforms to the standard `okstra-final-report.template.md` structure, including the `## 4.6 Release Handoff Deliverables` section.
   - The shared anti-escalation rule from the common contract still applies: do not start any other lifecycle phase from inside this run.
   - The shared "authority & permissions assumption" rule from the common contract still applies: assume the user holds every permission needed; do not block on hypothetical approvals.
   - The shared "MCP read-only" rule still applies if the brief lists MCP servers, though most release-handoff runs do not use MCP.
 - Pre-handoff entry gate (mandatory — refuse to start if any item fails):
-  - the task brief MUST cite the originating `final-verification` final-report path under `## Source Verification Report`. The lead opens that file and confirms section `## 2. Final Verdict` contains exactly the token `accepted`.
-  - if the verdict is `conditional-accept`, `blocked`, or any other token (including ambiguous phrasing like "looks good"), the run MUST end immediately with status `blocked` and a routing recommendation back to `error-analysis` or `implementation-planning`. Do NOT prompt the user; do NOT run any git command.
-  - the lead MUST capture `git status --short` and confirm the working tree is clean OR contains only the files listed in the prior `implementation` run's `Out-of-plan edits` block. Unexpected dirty state aborts the run.
+  - the task brief MUST cite the originating `final-verification` final-report path under `## Source Verification Report`. The lead opens that file and confirms section `## 2. Final Verdict` contains a `Verdict Token` field whose value is exactly `accepted`.
+  - if the verdict is `conditional-accept`, `blocked`, or any other token (including ambiguous phrasing like "looks good"), the run MUST end immediately with status `blocked` and a routing recommendation back to `error-analysis` or `implementation-planning`. Do NOT prompt the user; Do NOT run any git command.
+  - the lead MUST capture `git status --short` and confirm the working tree is clean. Dirty state aborts the run; release-handoff packages the commits produced by `implementation`, it does not stage or commit changes.
   - the lead MUST capture `git rev-parse --abbrev-ref HEAD` and record it as the **feature branch**. If the current branch is itself `main`, `master`, `prod`, `preprod`, `staging`, or `dev`, the run MUST end immediately — release-handoff never operates on a base branch.
+  - the lead MUST confirm `git log --oneline <base>..HEAD` contains at least one implementation commit. If it is empty, the run MUST end with status `blocked` and route back to `implementation`.
 - User interaction protocol (Claude lead — performed in order, using `AskUserQuestion` or the equivalent interactive prompt):
   1. **Action selection** — present three choices and capture exactly one:
-     - `commit only` — stage and commit the working-tree changes locally; no push, no PR.
-     - `commit + PR` — commit, push the feature branch, then open a pull request.
+     - `local only` — record the accepted, already-committed branch and end without push or PR.
+     - `push + PR` — push the feature branch, then open or reuse a pull request.
      - `skip` — record the verified state and end the run without any git command.
      If the user picks `skip`, route directly to the final-report self-review pass.
-  2. **PR base branch** (only when the user picked `commit + PR`) — present six options and capture exactly one:
+  2. **PR base branch** (only when the user picked `push + PR`) — present six options and capture exactly one:
      - `staging`
      - `preprod`
-     - `prod`
      - `main`
-     - `dev`
      - `직접 입력` (free-form branch name; lead validates the name exists on origin via `git ls-remote --heads origin <name>` and re-asks on failure)
      The chosen base MUST NOT equal the feature branch. If it does, re-ask.
-  3. **Commit message + PR body confirmation** — show the lead's inline draft verbatim and capture one of:
+  3. **PR title + PR body confirmation** — show the lead's inline draft verbatim and capture one of:
      - `use as-is` — proceed with the drafted text.
      - `edit then proceed` — accept inline edits from the user, then proceed with the edited text.
-     - `cancel` — end the run without executing any git command; record the cancellation in the final report.
+     - `cancel` — end the run without executing push or PR commands; record the cancellation in the final report.
 - Inline drafting rules (Claude lead):
-  - read the run brief, the cited final-verification report, and `git diff <base>..HEAD --stat` to ground the drafted text in actual changes.
+  - read the run brief, the cited final-verification report, `git log --oneline <base>..HEAD`, and `git diff <base>..HEAD --stat` to ground the drafted text in actual committed changes.
   - produce **two artifacts** before showing them to the user:
-    1. **Commit message** — a single message in Conventional Commits style (`<type>(<scope>): <subject>` + optional body + optional footer). When `commit + PR` will be opened against a `release-please`-managed repo, the type MUST match a configured changelog section (`feat` / `fix` / `perf` / `revert` / `deps` / `docs` / `refactor` / `build` / `ci` / `chore` / `test`).
+    1. **PR title** — by default the subject of the most recent implementation commit, or a concise Conventional Commits-style summary of the committed range.
     2. **PR body** — markdown with sections `## Summary`, `## Changes`, `## Test plan`, `## Linked issues` (omit a section only if it is genuinely empty).
-  - if the diff is empty or no commit can be produced (working tree already matches the base), record "no staged changes; commit skipped" in the final report and skip `git commit` while still proceeding to the PR step if requested.
 - Allowed actions during the run (Claude lead only):
   - read-only inspection: `git status`, `git status --short`, `git diff`, `git log`, `git rev-parse`, `git ls-remote --heads origin <name>`, `gh pr list --head <branch>`, `gh pr view <url>`.
-  - local commit: `git add -- <path>...` (prefer explicit file paths over `git add -A` / `git add .`), `git commit -m "<message>"`. Re-use the user-confirmed message exactly.
-  - feature-branch push (only when the user picked `commit + PR`): `git push -u origin <current-branch>`. The pushed ref MUST be the feature branch — never the chosen base branch.
-  - PR creation (only when the user picked `commit + PR` AND no PR with the same head already exists on origin): `gh pr create --base <chosen-base> --head <current-branch> --title "<title>" --body "<body>"`. The title is the commit message subject by default; the body is the user-confirmed PR body.
+  - feature-branch push (only when the user picked `push + PR`): `git push -u origin <current-branch>`. The pushed ref MUST be the feature branch — never the chosen base branch.
+  - PR creation (only when the user picked `push + PR` AND no PR with the same head already exists on origin): `gh pr create --base <chosen-base> --head <current-branch> --title "<title>" --body "<body>"`. The title and body are the user-confirmed PR draft.
   - PR reuse: if `gh pr list --head <branch> --state open --json url --jq '.[0].url'` returns a URL, treat that PR as already existing — record the URL in the final report and SKIP `gh pr create`.
-  - Idempotency: if `git diff --cached` and `git diff` are both empty (nothing to commit), record "no staged changes; commit skipped" in the final report and skip `git commit` while still proceeding to the PR step if requested.
 - Forbidden actions (any occurrence → terminal status `contract-violated`):
+  - local commit commands of any kind (`git add`, `git commit`, `git restore --staged`, `git stash`). Commits belong to the prior `implementation` phase.
   - any of the following git push variants, regardless of intent or whether the user said "force it":
     - `git push --force`
     - `git push --force-with-lease`
@@ -54,36 +51,37 @@
     - `git push +<refspec>`
     - any other invocation that rewrites remote history
   - pushing directly to a base branch — i.e. `git push origin <branch>` where `<branch>` is `main`, `master`, `prod`, `preprod`, `staging`, `dev`, or the branch the user chose as the PR base in this run. The only permitted push target is the current feature branch.
-  - bypassing repo safeguards: `--no-verify` / `-n` on `git commit` or `git push`, disabling GPG signing via `-c commit.gpgsign=false` / `--no-gpg-sign`, or any equivalent flag-based hook bypass.
+  - bypassing repo safeguards: `--no-verify` / `-n` on `git push`, disabling safeguards via equivalent flags, or any hook bypass.
   - release-publishing commands: `gh release create`, `gh release edit`, `npm publish`, `cargo publish`, `pip publish`, `twine upload`, `docker push`, `terraform apply`, `kubectl apply` against any non-local cluster.
   - source-code edits, refactors, or any modification to files outside the run's own artifact directories (`reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/`). The diff being shipped MUST be exactly what the prior `implementation` run produced; release-handoff packages it, it does not re-author it.
-  - executing any mutating command the user did NOT select. Examples: opening a PR when the user picked `commit only`; running `git commit` when the user picked `skip`; switching the PR base branch silently after the user already chose one.
+  - executing any mutating command the user did NOT select. Examples: opening a PR when the user picked `local only`; pushing when the user picked `skip`; switching the PR base branch silently after the user already chose one.
   - retrying a failed git / gh command with weaker safety flags. If `git push` fails with non-fast-forward, the lead MUST stop, explain the failure to the user, and ask for instructions — it MUST NOT add `--force`.
   - `TeamCreate`, `Agent(...)` dispatch of any kind, or any other parallel sub-agent fan-out. This phase runs entirely under the Claude lead.
   - silently treating an unrecognised user reply as one of the menu options. If the user's answer does not match a presented choice, re-ask the question verbatim.
 - Required deliverable shape (final report, in addition to the standard sections):
-  - **Source Verification Report**: relative path of the originating `final-verification` final-report file plus the literal quoted `## 2. Final Verdict` line that read `accepted`.
+  - **Source Verification Report**: relative path of the originating `final-verification` final-report file plus the literal quoted `Verdict Token` row whose value is `accepted`.
   - **Feature Branch & Working-Tree State**: branch name from `git rev-parse --abbrev-ref HEAD`, output of `git status --short` at run start.
   - **User Selections**: a block recording each prompt and the user's verbatim answer.
-    - Q1 action: `commit only` | `commit + PR` | `skip`.
+    - Q1 action: `local only` | `push + PR` | `skip`.
     - Q2 PR base (if applicable): the chosen branch and how it was selected (menu pick vs free-form input).
-    - Q3 message/body: `use as-is` | `edit then proceed` (with a diff between the lead's draft and the final text) | `cancel`.
+    - Q3 title/body: `use as-is` | `edit then proceed` (with a diff between the lead's draft and the final text) | `cancel`.
   - **Executed Commands**: every git / gh command the lead actually ran, with its exit code and a one-line stdout/stderr summary. Read-only inspection commands MAY be summarised; mutating commands MUST be listed verbatim.
-  - **Commit List**: each commit SHA (short and full), its subject line, and the files it touched. If no commit was produced (idempotent no-op), state `- No commit was produced (working tree had no staged changes).`
+  - **Commit List**: each existing implementation commit in `git log <base>..HEAD`, with short/full SHA, subject line, and touched files. Release-handoff MUST NOT create new commits.
   - **Pull Request Outcome**: one of
-    - `- No PR action requested.` (user picked `commit only` or `skip`)
+    - `- No PR action requested.` (user picked `local only` or `skip`)
     - `- PR created: <url>` with title and base branch
     - `- PR reused: <url>` when an existing PR was found via `gh pr list`
     - `- PR creation skipped: <reason>` for any user-driven cancellation
   - **Routing recommendation**: explicit `done` token, since release-handoff is the terminal lifecycle phase. If the run ended in `skip` or `cancel`, the recommendation MUST also state whether re-entry into release-handoff is appropriate.
 - Self-review pass before finalising the report (`Claude lead` runs this):
-  1. **Entry-gate audit** — section 2 cites the originating final-verification report path and the literal `accepted` verdict line. If either is missing, the run is invalid and MUST be re-routed to `final-verification`.
+  1. **Entry-gate audit** — section 2 cites the originating final-verification report path and the literal `Verdict Token` row with value `accepted`. If either is missing, the run is invalid and MUST be re-routed to `final-verification`.
   2. **User-selection traceability** — every executed mutating command maps to a user selection captured in the report. Any mutating command without a corresponding user answer is a contract violation.
   3. **Forbidden-action audit** — scan the run's session transcripts (`git`, `gh` invocations) for every entry in the Forbidden actions list above. Any occurrence means the run has crossed into unsafe territory and MUST be flagged as `contract-violated`.
   4. **Push-target audit** — for every `git push` recorded, confirm the refspec resolves to the feature branch, not the base branch.
   5. **Idempotency check** — if a PR with the same head already existed at run start, confirm the report records `PR reused` rather than a fresh `gh pr create` invocation.
 - Non-goals:
   - re-litigating the final-verification verdict — release-handoff trusts the cited `accepted` verdict and does not reopen acceptance checks.
+  - creating, amending, squashing, or rewriting commits. Commit production belongs to `implementation`.
   - opening additional PRs, releases, or deployments beyond the single PR the user chose to create.
   - merging the PR. Merging is a separate, manual step performed by the user (or by repo automation) after release-handoff ends; the lead MUST NOT call `gh pr merge`.
   - escalating beyond the menu choices on user phrasing — every mutating action requires an explicit menu selection.

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

@@ -10,7 +10,7 @@
 {{INCLUDE:_common-contract.md}}
 - Primary focus areas:
   - classify the work as bugfix, feature, improvement, refactor, or ops-change
-  - determine whether `error-analysis`, `implementation-planning`, or a direct implementation handoff is the next safe step
+  - determine whether `error-analysis` or `implementation-planning` is the next safe step; direct `implementation` handoff is not a valid routing target because implementation requires an approved `implementation-planning` report
   - identify missing materials that block reliable routing
   - define task continuity expectations for long-running work under the same task key
   - capture approval or confirmation points before the next phase starts

package/runtime/python/okstra_ctl/render.py

@@ -47,6 +47,74 @@ def _write_json(path: Path, payload: dict) -> None:
     _write_text(path, json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
 
 
+_FM_DEFAULT = "no-classification"
+
+_FM_TAGS_BASE = ["obsidian", "okstra"]
+
+_FM_TAGS_CATALOG: dict[str, list[str]] = {
+    "task-brief": ["task-brief"],
+    "task-index": ["task-index"],
+    "error-analysis-input": ["error-analysis", "input"],
+    "implementation-input": ["implementation", "input"],
+    "implementation-planning-input": ["implementation-planning", "input"],
+    "final-verification-input": ["final-verification", "input"],
+    "release-handoff-input": ["release-handoff", "input"],
+    "quick-input": ["quick", "input"],
+    "final-report": ["final-report"],
+    "schedule": ["schedule"],
+    "prd-brief": ["prd", "brief"],
+}
+
+
+def _fm_scalar(value: str, default: str = _FM_DEFAULT) -> str:
+    v = (value or "").strip()
+    return v if v else default
+
+
+def _fm_array(values: list[str], extras: list[str] | None = None) -> str:
+    items = [str(v).strip() for v in values if v and str(v).strip()]
+    if extras:
+        items.extend(str(e).strip() for e in extras if str(e).strip())
+    if not items:
+        return "[]"
+    return "[" + ", ".join(f'"{v}"' for v in items) + "]"
+
+
+def _fm_tags(doc_type: str) -> str:
+    extra = _FM_TAGS_CATALOG.get((doc_type or "").strip(), [])
+    return _fm_array(_FM_TAGS_BASE + list(extra))
+
+
+def _doc_type_from_template_path(template_path: str) -> str:
+    name = Path(template_path).name
+    if name.endswith(".template.md"):
+        stem = name[: -len(".template.md")]
+    else:
+        stem = Path(name).stem
+    if stem == "brief" and "prd" in Path(template_path).parts:
+        return "prd-brief"
+    return stem
+
+
+def _frontmatter_mapping(ctx: dict) -> dict:
+    task_id = (ctx.get("TASK_ID") or "").strip()
+    project_id = (ctx.get("PROJECT_ID") or "").strip()
+    task_group = (ctx.get("TASK_GROUP") or "").strip()
+    task_key = (ctx.get("TASK_KEY") or "").strip()
+    task_date = (ctx.get("TASK_DATE") or "").strip()
+    doc_type = (ctx.get("DOC_TYPE") or "").strip()
+    return {
+        "{{TASK_KEY}}": _fm_scalar(task_key),
+        "{{TASK_ID}}": _fm_scalar(task_id),
+        "{{PROJECT_ID}}": _fm_scalar(project_id),
+        "{{TASK_GROUP}}": _fm_scalar(task_group),
+        "{{TASK_DATE}}": _fm_scalar(task_date),
+        "{{FM_ID}}": _fm_array([task_id, project_id, task_group]),
+        "{{FM_ALIASES}}": _fm_array([task_id, project_id, task_group]),
+        "{{FM_TAGS}}": _fm_tags(doc_type),
+    }
+
+
 def _resolve_workers(ctx: dict) -> list[str]:
     return [w.strip() for w in ctx.get("SELECTED_REVIEWERS", "").split(",") if w.strip()]
 
@@ -830,6 +898,10 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
     mapping = {
         "{{TASK_KEY}}": task_manifest.get("taskKey", ctx.get("TASK_KEY", "")),
         "{{TASK_TYPE}}": task_manifest.get("taskType", ctx.get("ANALYSIS_TYPE", "")),
+        "{{TASK_DATE}}": ctx.get("TASK_DATE", ""),
+        "{{PROJECT_ID}}": ctx.get("PROJECT_ID", ""),
+        "{{TASK_GROUP}}": ctx.get("TASK_GROUP", ""),
+        "{{TASK_ID}}": ctx.get("TASK_ID", ""),
         "{{CURRENT_TASK_STATUS}}": task_manifest.get("currentStatus", ctx.get("CURRENT_TASK_STATUS", "")),
         "{{CURRENT_RUN_STATUS}}": task_manifest.get("latestRunStatus", ctx.get("CURRENT_RUN_STATUS", "")),
         "{{RELATED_TASKS_INLINE}}": ctx.get("RELATED_TASKS_INLINE", "None"),
@@ -870,6 +942,9 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
         "{{WORKFLOW_PHASE_STATE_LINES}}": "\n".join(phase_state_lines),
         "{{WORKFLOW_LAST_SAFE_CHECKPOINT_LINES}}": "\n".join(checkpoint_lines),
     }
+    fm_ctx = dict(ctx)
+    fm_ctx.setdefault("DOC_TYPE", _doc_type_from_template_path(template_path))
+    mapping.update(_frontmatter_mapping(fm_ctx))
     rendered = template
     for k, v in mapping.items():
         rendered = rendered.replace(k, v)
@@ -1035,10 +1110,6 @@ def render_template_file(template_path: str, output_path: str, ctx: dict) -> Non
 
     mapping = {
         "{{TEAM_CREATION_GATE}}": team_creation_gate_block,
-        "{{PROJECT_ID}}": ctx.get("PROJECT_ID", ""),
-        "{{TASK_GROUP}}": ctx.get("TASK_GROUP", ""),
-        "{{TASK_ID}}": ctx.get("TASK_ID", ""),
-        "{{TASK_KEY}}": ctx.get("TASK_KEY", ""),
         "{{TASK_TYPE}}": ctx.get("ANALYSIS_TYPE", ""),
         "{{ANALYSIS_PROFILE}}": ctx.get("REVIEW_PROFILE", ""),
         "{{ANALYSIS_TYPE}}": ctx.get("ANALYSIS_TYPE", ""),
@@ -1143,6 +1214,9 @@ def render_template_file(template_path: str, output_path: str, ctx: dict) -> Non
         "{{EXECUTOR_WORKTREE_STATUS}}": ctx.get("EXECUTOR_WORKTREE_STATUS", ""),
         "{{EXECUTOR_WORKTREE_NOTE}}": ctx.get("EXECUTOR_WORKTREE_NOTE", ""),
     }
+    fm_ctx = dict(ctx)
+    fm_ctx.setdefault("DOC_TYPE", _doc_type_from_template_path(template_path))
+    mapping.update(_frontmatter_mapping(fm_ctx))
     rendered = template
     for k, v in mapping.items():
         rendered = rendered.replace(k, v)

package/runtime/python/okstra_ctl/run.py

@@ -19,7 +19,6 @@ import json
 import os
 import re
 import shutil
-import subprocess
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
@@ -819,11 +818,6 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     )
 
 
-def claude_is_available() -> bool:
-    """`claude` CLI 가 PATH 에 있는지 확인."""
-    return shutil.which("claude") is not None
-
-
 def main(argv: list[str]) -> int:
     """CLI dispatcher for bash thin-wrapper use. Parses a flat list of argv
     (the same flags `okstra.sh` accepts), runs prepare_task_bundle, prints

package/runtime/python/okstra_ctl/run_context.py

@@ -30,6 +30,10 @@ def _now_iso() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
+def _now_task_date() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
+
+
 def _okstra_home() -> Path:
     home = os.environ.get("OKSTRA_HOME")
     if home:
@@ -109,6 +113,7 @@ def compute_and_write_run_context(
             run_seq_override=run_seq_override,
         )
         ctx["RUN_TIMESTAMP_ISO"] = _now_iso()
+        ctx["TASK_DATE"] = _now_task_date()
         run_manifests_dir = Path(ctx["RUN_MANIFESTS_DIR"])
         ctx_path = run_manifests_dir / _run_context_filename(
             ctx["TASK_TYPE_SEGMENT"], ctx["RUN_MANIFESTS_SEQ"])