okstra 0.20.1 → 0.21.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.20.1",
+  "version": "0.21.1",
   "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.1",
-  "builtAt": "2026-05-14T01:49:53.274Z",
+  "package": "0.21.1",
+  "builtAt": "2026-05-14T12:50:20.728Z",
   "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/claude-worker.md

@@ -44,7 +44,9 @@ Unlike the Codex / Gemini workers, you are an in-process Claude subagent — you
    - If the parent directory does not exist yet, create it before writing.
 
 4. Anchor all file operations to the absolute `Project Root` from the lead prompt. Use absolute paths — do NOT rely on inherited cwd. Never use `cd` to change directory.
-   - **Executor exception (implementation phase only):** when this worker is dispatched as the `Executor` and the lead prompt provides an `EXECUTOR_WORKTREE_PATH` that differs from the session's inherited cwd, cwd-sensitive Bash commands (`cargo *`, `npm *`, `pnpm *`, `bun *`, `pytest`, `make *`, `go *`, language-toolchain test/build commands) MUST be prefixed with `cd <EXECUTOR_WORKTREE_PATH> && ` in the same Bash invocation — e.g. `cd /Users/.../worktrees/foo && cargo test -p bar`. Do NOT wrap the whole thing in `bash -lc "..."` or `bash -c "..."`; pass the chained command directly to the Bash tool so the leading `cd` token remains visible to the permission layer. The `cd` is scoped to the single Bash subshell and does not mutate the session's shell state, so this does not conflict with the "never use cd" rule above (which prevents the worker from drifting the session cwd across calls). Verifier roles do NOT use this exception — they read with absolute paths only.
+   - **Executor exception (implementation phase only):** when this worker is dispatched as the `Executor` and the lead prompt provides an `EXECUTOR_WORKTREE_PATH` that differs from the session's inherited cwd, cwd-sensitive Bash commands (`cargo *`, `npm *`, `pnpm *`, `bun *`, `pytest`, `make *`, `go *`, language-toolchain test/build commands) MUST be prefixed with `cd <EXECUTOR_WORKTREE_PATH> && ` in the same Bash invocation — e.g. `cd /Users/.../worktrees/foo && cargo test -p bar`. Do NOT wrap the whole thing in `bash -lc "..."` or `bash -c "..."`; pass the chained command directly to the Bash tool so the leading `cd` token remains visible to the permission layer. The `cd` is scoped to the single Bash subshell and does not mutate the session's shell state, so this does not conflict with the "never use cd" rule above (which prevents the worker from drifting the session cwd across calls).
+   - **Verifier QA-gate exception:** verifier roles MAY use the same `cd <WORKTREE> && <cmd>` shape when executing project-declared `qaCommands` (lint / format / typecheck / test) from `project.json`, since those commands are cwd-sensitive by nature. Outside the QA gate, verifiers still read with absolute paths only — do NOT use `cd` for file inspection.
+   - **No extra chaining beyond `cd && cmd`:** the permission matcher only allows the exact two-segment shape `cd <PATH> && <single-command>`. Do NOT append additional pipes, semicolons, redirects, or `&&` chains — e.g. `cd ... && cargo test ... 2>&1 | tail -20; echo "exit:$?"` will trigger a permission prompt every dispatch because the trailing `| tail`, `; echo`, and `2>&1` tokens disqualify the prefix match against `Bash(cargo:*)`. Let Claude Code capture the full stdout/stderr and exit code natively — do not post-process with `tail`, `head`, or `echo "exit:$?"`. If output truncation is genuinely needed, run the command first and read the result in a separate tool call.
 
 5. **MCP usage**: The canonical list of MCP servers and tools available for this run lives in the lead prompt's `## Available MCP Servers` section (sourced from `.project-docs/okstra/project.json`'s `mcpServers` array). When the task requires inspection of an external system covered by one of those servers, call the listed tool directly by name (e.g. `mcp__<server>__<tool>`). Do NOT shell out via `claude --mcp-cli call ...` or run the tool name as a Bash command — those are not valid invocation paths. If a server you need is not listed, record `MCP not available for this run` in your worker output rather than guessing a tool name.
 

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
@@ -107,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
@@ -141,6 +172,17 @@ if [[ -n "${TMUX:-}" ]]; then
   if [[ -n "$trace_pane" ]]; then
     tmux select-pane -t "$trace_pane" -T "codex-${role}-trace" 2>/dev/null || true
     tmux last-pane 2>/dev/null || true
+    # Register the spawned pane so the `SessionEnd` hook (see
+    # `okstra-trace-cleanup.sh`) can kill it when the caller's Claude
+    # session exits. Scope by caller `$TMUX_PANE` — the pane Claude itself
+    # is attached to — so concurrent Claude instances in the same tmux
+    # session do not stomp each other's trace panes.
+    if [[ -n "${TMUX_PANE:-}" ]]; then
+      registry_dir="${TMPDIR:-/tmp}/okstra-trace-panes"
+      mkdir -p "$registry_dir" 2>/dev/null || true
+      safe_pane="${TMUX_PANE//[^A-Za-z0-9]/_}"
+      printf '%s\n' "$trace_pane" >> "$registry_dir/${safe_pane}.list" 2>/dev/null || true
+    fi
   fi
 fi
 

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

@@ -121,6 +121,13 @@ if [[ -n "${TMUX:-}" ]]; then
   if [[ -n "$trace_pane" ]]; then
     tmux select-pane -t "$trace_pane" -T "gemini-${role}-trace" 2>/dev/null || true
     tmux last-pane 2>/dev/null || true
+    # See `okstra-codex-exec.sh` for the registry rationale — kept in lock-step.
+    if [[ -n "${TMUX_PANE:-}" ]]; then
+      registry_dir="${TMPDIR:-/tmp}/okstra-trace-panes"
+      mkdir -p "$registry_dir" 2>/dev/null || true
+      safe_pane="${TMUX_PANE//[^A-Za-z0-9]/_}"
+      printf '%s\n' "$trace_pane" >> "$registry_dir/${safe_pane}.list" 2>/dev/null || true
+    fi
   fi
 fi
 

package/runtime/bin/okstra-trace-cleanup.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+#
+# okstra-trace-cleanup.sh — kill tmux trace panes spawned by okstra worker
+# wrappers (`okstra-codex-exec.sh`, `okstra-gemini-exec.sh`) for the current
+# Claude Code session.
+#
+# Invoked from the `SessionEnd` hook in
+# `templates/reports/settings.template.json`. The wrappers register every
+# pane they split into a registry file keyed by the caller's `$TMUX_PANE`
+# (i.e. the pane Claude itself is attached to). On Claude `/exit`, the hook
+# runs in that same pane's env, reads its own registry file, and kills each
+# registered pane.
+#
+# Scoping by caller `$TMUX_PANE` (not by tmux session) lets multiple Claude
+# instances coexist in the same tmux session without stomping each other's
+# trace panes.
+#
+# Failures are tolerated silently — a stale pane id, missing $TMUX, or a
+# locked tmux client must never prevent Claude from exiting cleanly.
+
+set -u
+
+# No tmux pane context → nothing to clean.
+if [[ -z "${TMUX_PANE:-}" ]]; then
+  exit 0
+fi
+
+registry_dir="${TMPDIR:-/tmp}/okstra-trace-panes"
+safe_pane="${TMUX_PANE//[^A-Za-z0-9]/_}"
+registry_file="$registry_dir/${safe_pane}.list"
+
+if [[ ! -f "$registry_file" ]]; then
+  exit 0
+fi
+
+while IFS= read -r pane_id; do
+  [[ -n "$pane_id" ]] || continue
+  tmux kill-pane -t "$pane_id" 2>/dev/null || true
+done < "$registry_file"
+
+rm -f "$registry_file" 2>/dev/null || true
+exit 0

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_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"])

package/runtime/python/okstra_ctl/workflow.py

@@ -124,23 +124,24 @@ PHASE_RULES: dict[str, dict[str, str]] = {
     },
     "release-handoff": {
         "allowed": (
-            "  - entering this phase only when the cited final-verification report's verdict is exactly `accepted`\n"
-            "  - asking the user (via `AskUserQuestion` / interactive prompt) which delivery action to take: `commit only`, `commit + PR`, or `skip` (end the run)\n"
+            "  - entering this phase only when the cited final-verification report's `Verdict Token` is exactly `accepted`\n"
+            "  - asking the user (via `AskUserQuestion` / interactive prompt) which delivery action to take: `local only`, `push + PR`, or `skip` (end the run)\n"
             "  - asking the user to pick a PR base branch from `staging` | `preprod` | `prod` | `main` | `dev` | a user-supplied branch name\n"
-            "  - drafting commit message(s) and PR body **inline as the Claude lead** (no drafter worker, no `Agent` dispatch); the lead reviews its own draft with the user before any git command runs\n"
-            "  - local git operations: `git status`, `git diff`, `git log`, `git add`, `git commit -m`\n"
+            "  - drafting PR title and PR body **inline as the Claude lead** (no drafter worker, no `Agent` dispatch); the lead reviews its own draft with the user before any mutating git / gh command runs\n"
+            "  - read-only git inspection: `git status`, `git diff`, `git log`, `git rev-parse`\n"
             "  - pushing the current feature branch to its origin remote via `git push -u origin <current-branch>` (the feature branch only — NEVER the base branch)\n"
             "  - creating a pull request via `gh pr create --base <chosen-base> --head <current-branch>`; if a PR with the same head already exists, surface its URL and skip creation\n"
             "  - the lead writes the final report directly (no `Report writer worker` dispatch); the report still conforms to the standard final-report template"
         ),
         "forbidden": (
-            "  - entering this phase when the cited final-verification verdict is `conditional-accept` or `blocked`, or when no final-verification report is cited\n"
-            "  - any source-code edit, refactor, or scope expansion beyond what is strictly needed to author commit messages / PR descriptions (the changes themselves are inherited from prior `implementation` runs)\n"
+            "  - entering this phase when the cited final-verification `Verdict Token` is `conditional-accept` or `blocked`, or when no final-verification report is cited\n"
+            "  - any source-code edit, refactor, or scope expansion beyond what is strictly needed to author PR descriptions (the changes themselves are inherited from prior `implementation` runs)\n"
+            "  - local commit commands (`git add`, `git commit`, `git stash`, `git restore --staged`); commits are produced by `implementation`, not release-handoff\n"
             "  - `git push --force`, `git push --force-with-lease`, or any rewriting of remote history\n"
             "  - pushing directly to a base branch (`main`, `master`, `prod`, `preprod`, `staging`, `dev`, or any branch the user named as the PR base)\n"
             "  - bypassing git hooks (`--no-verify`, `-n`), bypassing GPG signing, or otherwise disabling repo-configured safeguards\n"
             "  - release-publishing commands: `gh release`, `npm publish`, `cargo publish`, `pip publish`, `docker push`, `terraform apply`, `kubectl apply` against non-local clusters\n"
-            "  - executing any command the user did NOT select (e.g. if the user picked `commit only`, opening a PR is forbidden; if the user picked `skip`, the run ends without git commands)\n"
+            "  - executing any command the user did NOT select (e.g. if the user picked `local only`, opening a PR is forbidden; if the user picked `skip`, the run ends without git commands)\n"
             "  - `TeamCreate`, `Agent(...)` worker dispatch, parallel sub-agent fan-out, or any team-mode orchestration — this phase runs single-lead\n"
             "  - silently retrying a failed git/gh command with weaker flags (e.g. retrying `git push` with `--force` after a non-fast-forward rejection)"
         ),