okstra 0.34.1 → 0.36.0

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

@@ -187,19 +187,35 @@ python3 "$script_dir/okstra-wrapper-status.py" \
   init "$status_path" "$(basename "$0")" "$role" "$$" "$started_ts" "$log_path" \
   >>"$log_path" 2>&1 || true
 
+# Resolve caller pane id robustly. tmux normally exports both `$TMUX` and
+# `$TMUX_PANE` to processes started inside a pane, but Claude Code's Bash
+# tool can drop `$TMUX_PANE` while preserving `$TMUX` — which would
+# silently skip the caller-pane rename below AND let `tmux split-window`
+# attach the trace pane to whatever tmux currently considers active
+# (not necessarily Claude's pane). When the wrapper is launched from
+# Claude Code, the Claude session's pane IS the active pane at this
+# moment, so falling back to `display-message -p '#{pane_id}'` recovers
+# the correct id.
+caller_pane="${TMUX_PANE:-}"
+if [[ -z "$caller_pane" && -n "${TMUX:-}" ]]; then
+  caller_pane=$(tmux display-message -p '#{pane_id}' 2>/dev/null || true)
+fi
+
 # Pane titles: worker (caller) pane gets `codex-<role>-<pid>`; the sibling
-# trace pane appends `-trace`. The wrapper PID disambiguates concurrent
-# dispatches of the same role (e.g. two `codex-worker` panes spawned in
-# parallel) so the operator can match worker ↔ trace at a glance.
+# trace pane appends `-trace[from=<caller-pane-id>]`. The wrapper PID
+# disambiguates concurrent dispatches of the same role; the embedded
+# caller pane id keeps the trace ↔ worker mapping visible even if the
+# worker pane's title is later overwritten by the parent process (e.g.
+# Claude Code's TUI emitting OSC 2 escape sequences on its own pane).
 pane_label="codex-${role}-$$"
-trace_label="${pane_label}-trace"
+trace_label="${pane_label}-trace[from=${caller_pane:-?}]"
 
 # Capture the caller pane's current title so the EXIT trap can restore it
 # once the wrapper returns. Empty when not in tmux or capture fails — the
 # restore step degrades to a no-op in that case.
 original_caller_title=""
-if [[ -n "${TMUX_PANE:-}" ]]; then
-  original_caller_title=$(tmux display-message -p -t "$TMUX_PANE" '#{pane_title}' 2>/dev/null || true)
+if [[ -n "$caller_pane" ]]; then
+  original_caller_title=$(tmux display-message -p -t "$caller_pane" '#{pane_title}' 2>/dev/null || true)
 fi
 
 _okstra_status_finish() {
@@ -210,16 +226,16 @@ _okstra_status_finish() {
   python3 "$script_dir/okstra-wrapper-status.py" \
     finish "$status_path" "$exit_code" "$ended_ts" "$duration_ms" \
     >>"$log_path" 2>&1 || true
-  if [[ -n "${TMUX_PANE:-}" && -n "$original_caller_title" ]]; then
-    tmux select-pane -t "$TMUX_PANE" -T "$original_caller_title" 2>/dev/null || true
+  if [[ -n "$caller_pane" && -n "$original_caller_title" ]]; then
+    tmux select-pane -t "$caller_pane" -T "$original_caller_title" 2>/dev/null || true
   fi
 }
 trap _okstra_status_finish EXIT
 
 # Label the caller (worker) pane now that the restore trap is armed. Any
 # failure after this point still rewinds the title to its prior value.
-if [[ -n "${TMUX_PANE:-}" ]]; then
-  tmux select-pane -t "$TMUX_PANE" -T "$pane_label" 2>/dev/null || true
+if [[ -n "$caller_pane" ]]; then
+  tmux select-pane -t "$caller_pane" -T "$pane_label" 2>/dev/null || true
 fi
 
 # When a tmux session is reachable, split a sibling pane that tails the live
@@ -227,35 +243,40 @@ fi
 # 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>-<pid>-trace` (matching the
-# caller pane's `codex-<role>-<pid>` label so worker ↔ trace pairs are
-# greppable); `role` is the optional 5th positional arg (defaults to
-# `worker`); callers that dispatch a different role (e.g. `executor`) must
-# pass it explicitly. The `<pid>` suffix is the wrapper's PID and
-# disambiguates concurrent dispatches of the same role. 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
+# new pane carries the title `codex-<role>-<pid>-trace[from=<caller-pane>]`
+# so the operator can map trace ↔ worker by pane id even when the worker
+# pane title is later overwritten by Claude Code. The split is explicitly
+# anchored to the caller pane (`-t "$caller_pane"`) to avoid attaching to
+# tmux's idle active pane when `$TMUX_PANE` was missing. `role` is the
+# optional 5th positional arg (defaults to `worker`); callers that
+# dispatch a different role (e.g. `executor`) must pass it explicitly.
+# The `<pid>` suffix is the wrapper's PID and disambiguates concurrent
+# dispatches of the same role. 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
 # all degrade to "log file is still on disk; the operator can tail it
-# manually from any terminal." The wrapper does NOT switch focus to the new
-# pane — control returns to the caller's pane via `tmux last-pane`.
+# manually from any terminal." The wrapper does NOT switch focus to the
+# new pane — control returns to the caller's pane via `tmux last-pane`.
 if [[ -n "${TMUX:-}" ]]; then
-  trace_pane=$(tmux split-window -h -P -F '#{pane_id}' \
-    -c "$(dirname "$log_path")" \
+  split_args=(-h -P -F '#{pane_id}' -c "$(dirname "$log_path")")
+  if [[ -n "$caller_pane" ]]; then
+    split_args+=(-t "$caller_pane")
+  fi
+  trace_pane=$(tmux split-window "${split_args[@]}" \
     "tail -F $(printf '%q' "$log_path")" 2>/dev/null || true)
   if [[ -n "$trace_pane" ]]; then
     tmux select-pane -t "$trace_pane" -T "$trace_label" 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 exits. Scope by `$caller_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
+    if [[ -n "$caller_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]/_}"
+      safe_pane="${caller_pane//[^A-Za-z0-9]/_}"
       printf '%s\n' "$trace_pane" >> "$registry_dir/${safe_pane}.list" 2>/dev/null || true
     fi
   fi

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

@@ -136,19 +136,31 @@ python3 "$script_dir/okstra-wrapper-status.py" \
   init "$status_path" "$(basename "$0")" "$role" "$$" "$started_ts" "$log_path" \
   >>"$log_path" 2>&1 || true
 
+# Resolve caller pane id robustly. See `okstra-codex-exec.sh` for the full
+# rationale — kept in lock-step: tmux normally exports both `$TMUX` and
+# `$TMUX_PANE`, but Claude Code's Bash tool can drop `$TMUX_PANE` while
+# preserving `$TMUX`, which silently skips the caller-pane rename and
+# lets `tmux split-window` attach to whatever tmux considers active.
+caller_pane="${TMUX_PANE:-}"
+if [[ -z "$caller_pane" && -n "${TMUX:-}" ]]; then
+  caller_pane=$(tmux display-message -p '#{pane_id}' 2>/dev/null || true)
+fi
+
 # Pane titles: worker (caller) pane gets `gemini-<role>-<pid>`; the sibling
-# trace pane appends `-trace`. The wrapper PID disambiguates concurrent
-# dispatches of the same role (e.g. two `gemini-worker` panes spawned in
-# parallel) so the operator can match worker ↔ trace at a glance.
+# trace pane appends `-trace[from=<caller-pane-id>]`. The wrapper PID
+# disambiguates concurrent dispatches of the same role; the embedded
+# caller pane id keeps the trace ↔ worker mapping visible even if the
+# worker pane's title is later overwritten by the parent process (e.g.
+# Claude Code's TUI emitting OSC 2 escape sequences on its own pane).
 pane_label="gemini-${role}-$$"
-trace_label="${pane_label}-trace"
+trace_label="${pane_label}-trace[from=${caller_pane:-?}]"
 
 # Capture the caller pane's current title so the EXIT trap can restore it
 # once the wrapper returns. Empty when not in tmux or capture fails — the
 # restore step degrades to a no-op in that case.
 original_caller_title=""
-if [[ -n "${TMUX_PANE:-}" ]]; then
-  original_caller_title=$(tmux display-message -p -t "$TMUX_PANE" '#{pane_title}' 2>/dev/null || true)
+if [[ -n "$caller_pane" ]]; then
+  original_caller_title=$(tmux display-message -p -t "$caller_pane" '#{pane_title}' 2>/dev/null || true)
 fi
 
 _okstra_status_finish() {
@@ -159,40 +171,46 @@ _okstra_status_finish() {
   python3 "$script_dir/okstra-wrapper-status.py" \
     finish "$status_path" "$exit_code" "$ended_ts" "$duration_ms" \
     >>"$log_path" 2>&1 || true
-  if [[ -n "${TMUX_PANE:-}" && -n "$original_caller_title" ]]; then
-    tmux select-pane -t "$TMUX_PANE" -T "$original_caller_title" 2>/dev/null || true
+  if [[ -n "$caller_pane" && -n "$original_caller_title" ]]; then
+    tmux select-pane -t "$caller_pane" -T "$original_caller_title" 2>/dev/null || true
   fi
 }
 trap _okstra_status_finish EXIT
 
 # Label the caller (worker) pane now that the restore trap is armed. Any
 # failure after this point still rewinds the title to its prior value.
-if [[ -n "${TMUX_PANE:-}" ]]; then
-  tmux select-pane -t "$TMUX_PANE" -T "$pane_label" 2>/dev/null || true
+if [[ -n "$caller_pane" ]]; then
+  tmux select-pane -t "$caller_pane" -T "$pane_label" 2>/dev/null || true
 fi
 
 # 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>-<pid>-trace` (matching the
-# caller pane's `gemini-<role>-<pid>` label so worker ↔ trace pairs are
-# greppable). `role` is the optional 5th positional arg (defaults to
-# `worker`); callers that dispatch a different role must pass it
-# explicitly. The `<pid>` suffix is the wrapper's PID and disambiguates
-# concurrent dispatches of the same role. See the codex wrapper for the
-# full design rationale and the silent-degrade failure model.
+# implementation-specific. Title `gemini-<role>-<pid>-trace[from=<caller-pane>]`
+# so the operator can map trace ↔ worker by pane id even when the worker
+# pane title is later overwritten by Claude Code. The split is explicitly
+# anchored to the caller pane to avoid attaching to tmux's idle active
+# pane when `$TMUX_PANE` was missing. `role` is the optional 5th
+# positional arg (defaults to `worker`); callers that dispatch a
+# different role must pass it explicitly. The `<pid>` suffix is the
+# wrapper's PID and disambiguates concurrent dispatches of the same role.
+# 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")" \
+  split_args=(-h -P -F '#{pane_id}' -c "$(dirname "$log_path")")
+  if [[ -n "$caller_pane" ]]; then
+    split_args+=(-t "$caller_pane")
+  fi
+  trace_pane=$(tmux split-window "${split_args[@]}" \
     "tail -F $(printf '%q' "$log_path")" 2>/dev/null || true)
   if [[ -n "$trace_pane" ]]; then
     tmux select-pane -t "$trace_pane" -T "$trace_label" 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
+    if [[ -n "$caller_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]/_}"
+      safe_pane="${caller_pane//[^A-Za-z0-9]/_}"
       printf '%s\n' "$trace_pane" >> "$registry_dir/${safe_pane}.list" 2>/dev/null || true
     fi
   fi

package/runtime/bin/okstra-render-final-report.py

@@ -26,8 +26,9 @@ _HERE = Path(__file__).resolve().parent
 # scripts; for in-repo invocation we add ``scripts/`` explicitly.
 sys.path.insert(0, str(_HERE))
 
+from okstra_ctl.i18n import SUPPORTED_LANGS  # noqa: E402
 from okstra_ctl.render_final_report import (  # noqa: E402
-    RenderError,
+    FinalReportRenderError,
     render_to_file,
 )
 
@@ -68,6 +69,15 @@ def main(argv: list[str]) -> int:
             "the repo-local copy."
         ),
     )
+    parser.add_argument(
+        "--report-language",
+        choices=list(SUPPORTED_LANGS),
+        default=None,
+        help=(
+            "Override the language passed into the renderer. When omitted, "
+            "the renderer reads data.json.meta.reportLanguage (fallback 'en')."
+        ),
+    )
     parser.add_argument(
         "--force",
         action="store_true",
@@ -88,8 +98,9 @@ def main(argv: list[str]) -> int:
             args.data,
             output,
             template_path=args.template,
+            report_language=args.report_language,
         )
-    except RenderError as exc:
+    except FinalReportRenderError as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 1
 

package/runtime/bin/okstra-wrapper-status.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""okstra-wrapper-status.py — heartbeat sidecar writer for codex/gemini wrappers.
+
+The codex/gemini wrappers (`okstra-codex-exec.sh`, `okstra-gemini-exec.sh`)
+dispatch a long-running CLI under `Bash(run_in_background: true)` and rely on
+`BashOutput` polling for liveness. That polling stream only carries stdout
+plus a binary `running`/`completed` state. Several recovery decisions need
+more — specifically, "did this wrapper start at all, when, and how did it
+finish?" — so the wrappers write a small JSON sidecar at
+`<prompt-path>.status.json` that survives independent of the polling channel.
+
+Consumers:
+
+* `codex-worker` / `gemini-worker` step 8c: read `log_path` to capture a
+  diagnostic tail when `exit_code == 0` but the canonical Result file is
+  absent.
+* Lead: cross-check `started_ts` / `ended_ts` to distinguish "wrapper hung
+  before CLI launched" from "CLI finished but never wrote artifact" when
+  applying the redispatch policy (see okstra-team-contract "Lead Redispatch
+  Policy on Result-Missing").
+
+Failures are deliberately non-fatal for the caller — the wrapper's main
+job is to run the underlying CLI; a missing sidecar must not break that.
+On any error the script prints a one-line diagnostic to stderr and exits 0.
+
+Schema (schemaVersion 1):
+
+    {
+      "schemaVersion": 1,
+      "wrapper": "<basename of caller>",
+      "role":    "<worker|executor|verifier|...>",
+      "pid":     <int — wrapper process pid at init time>,
+      "started_ts": <epoch seconds>,
+      "log_path":   "<absolute path to the wrapper live log>",
+      "stage":      "started" | "exited",
+      "exit_code":   <int, only when stage=exited>,
+      "ended_ts":    <epoch seconds, only when stage=exited>,
+      "duration_ms": <int, only when stage=exited>,
+      "timeout":       <bool, only when killed by idle-watchdog>,
+      "idle_at_ts":    <epoch seconds, only when timeout>,
+      "idle_seconds":  <int, only when timeout>,
+      "terminated_by": "idle-watchdog" (only when timeout)
+    }
+
+CLI:
+
+    okstra-wrapper-status.py init    <status-path> <wrapper> <role> <pid> <started-ts> <log-path>
+    okstra-wrapper-status.py finish  <status-path> <exit-code> <ended-ts> <duration-ms>
+    okstra-wrapper-status.py timeout <status-path> <idle-at-ts> <idle-seconds>
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+
+def warn(msg: str) -> None:
+    print(f"okstra-wrapper-status: {msg}", file=sys.stderr)
+
+
+def atomic_write(path: str, doc: dict) -> None:
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(doc, f, ensure_ascii=False, indent=2)
+        f.write("\n")
+    os.replace(tmp, path)
+
+
+def cmd_init(argv: list[str]) -> None:
+    if len(argv) != 6:
+        warn("init expects: <status-path> <wrapper> <role> <pid> <started-ts> <log-path>")
+        return
+    status_path, wrapper, role, pid, started_ts, log_path = argv
+    doc = {
+        "schemaVersion": 1,
+        "wrapper": wrapper,
+        "role": role,
+        "pid": int(pid),
+        "started_ts": int(started_ts),
+        "log_path": log_path,
+        "stage": "started",
+    }
+    try:
+        atomic_write(status_path, doc)
+    except OSError as exc:
+        warn(f"init: failed to write {status_path}: {exc}")
+
+
+def cmd_finish(argv: list[str]) -> None:
+    if len(argv) != 4:
+        warn("finish expects: <status-path> <exit-code> <ended-ts> <duration-ms>")
+        return
+    status_path, exit_code, ended_ts, duration_ms = argv
+    try:
+        with open(status_path, "r", encoding="utf-8") as f:
+            doc = json.load(f)
+    except FileNotFoundError:
+        warn(f"finish: sidecar absent at {status_path}; skipping")
+        return
+    except (OSError, json.JSONDecodeError) as exc:
+        warn(f"finish: failed to read {status_path}: {exc}")
+        return
+    doc["stage"] = "exited"
+    doc["exit_code"] = int(exit_code)
+    doc["ended_ts"] = int(ended_ts)
+    doc["duration_ms"] = int(duration_ms)
+    try:
+        atomic_write(status_path, doc)
+    except OSError as exc:
+        warn(f"finish: failed to write {status_path}: {exc}")
+
+
+def cmd_timeout(argv: list[str]) -> None:
+    if len(argv) != 3:
+        warn("timeout expects: <status-path> <idle-at-ts> <idle-seconds>")
+        return
+    status_path, idle_at, idle_seconds = argv
+    try:
+        with open(status_path, "r", encoding="utf-8") as f:
+            doc = json.load(f)
+    except FileNotFoundError:
+        warn(f"timeout: sidecar absent at {status_path}; skipping")
+        return
+    except (OSError, json.JSONDecodeError) as exc:
+        warn(f"timeout: failed to read {status_path}: {exc}")
+        return
+    doc["timeout"] = True
+    doc["idle_at_ts"] = int(idle_at)
+    doc["idle_seconds"] = int(idle_seconds)
+    doc["terminated_by"] = "idle-watchdog"
+    try:
+        atomic_write(status_path, doc)
+    except OSError as exc:
+        warn(f"timeout: failed to write {status_path}: {exc}")
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 2:
+        warn("missing subcommand (init|finish|timeout)")
+        return 0
+    sub = argv[1]
+    if sub == "init":
+        cmd_init(argv[2:])
+    elif sub == "finish":
+        cmd_finish(argv[2:])
+    elif sub == "timeout":
+        cmd_timeout(argv[2:])
+    else:
+        warn(f"unknown subcommand: {sub}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/runtime/bin/okstra.sh

@@ -68,7 +68,7 @@ if [[ "$ASSUME_YES" != "true" ]] && [[ -t 0 ]] && [[ -t 1 ]]; then
   cat >&2 <<CONFIRM_EOF
 okstra execution summary:
   render only: ${RENDER_ONLY}
-  task type: ${ANALYSIS_TYPE}
+  task type: ${TASK_TYPE}
   project id: ${PROJECT_ID}
   project root: ${PROJECT_ROOT}
   task group: ${TASK_GROUP}
@@ -103,7 +103,7 @@ PY_ARGS=(
   --project-id "$PROJECT_ID"
   --task-group "$TASK_GROUP"
   --task-id "$TASK_ID"
-  --task-type "$ANALYSIS_TYPE"
+  --task-type "$TASK_TYPE"
   --task-brief "$BRIEF_PATH"
 )
 [[ -n "${DIRECTIVE-}" ]] && PY_ARGS+=(--directive "$DIRECTIVE")

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

@@ -17,8 +17,12 @@ profile document.
   - **Phase 5.5 (convergence — peer review by workers)**: the lead replays each analyser's findings to the *other* analysers and collects `AGREE` / `DISAGREE` / `SUPPLEMENT` verdicts across up to `effectiveMaxRounds` rounds. Workers act as peer reviewers of each other's findings in this phase; the lead mediates but does not vote. See `skills/okstra-convergence/SKILL.md` for the round protocol, queue invariants, and final classification (`full-consensus` / `partial-consensus` / `contested` / `worker-unique`).
   - Do NOT conclude "no peer review happens" from the roster alone — every profile that lists ≥2 analyser workers runs convergence by default (`convergence.enabled=true` in `task-manifest.json`).
 - Tooling — read-only MCP availability (shared):
-  - the read-only MCP servers declared in the task brief's `## Available MCP Servers` section may be queried as a read-only cross-check; that section is the canonical source of which servers and tools exist for this run, and any MCP-derived finding MUST cite server, table, and the SELECT used. MCP MUST NEVER be used as a write path — schema/data mutations go through repository migration files reviewed by humans.
-- Authority & permissions assumption (HARD RULE — applies to every okstra task-type):
+  - MCP is not implicit okstra context. Query an MCP server only when the task brief explicitly lists it as source material for this run. Any MCP-derived finding MUST cite server, table, and the SELECT used. MCP MUST NEVER be used as a write path — schema/data mutations go through repository migration files reviewed by humans.
+- Resource boundary (shared — artifact-home rule):
+  - Okstra-owned project artifacts live only under `<PROJECT_ROOT>/.project-docs/okstra/**`. Treat `project.json`, task bundles, run artifacts, `glossary.md`, and `decisions/` under that subtree as the canonical okstra memory.
+  - Treat paths outside `<PROJECT_ROOT>/.project-docs/okstra/**` as source material only when the task brief's `Source Material` or `Reporter Confirmations` explicitly cites them; they never become okstra memory.
+  - Create, modify, or delete only inside `<PROJECT_ROOT>/.project-docs/okstra/**` unless the brief verbatim requests a specific non-okstra edit. The phase performing that edit must quote the user instruction in its report. Implementation source edits also require the approved implementation plan.
+- Authority & permissions assumption (applies to every okstra task-type):
   - **Assume the user (and their team) holds full authority and every permission required for the anticipated, in-flight, or follow-up work.** Treat external approvals, third-party access grants, role/IAM permissions, organisational sign-off, legal/compliance review, vendor coordination, and "verify access exists" steps as already satisfied unless the task brief explicitly states otherwise.
   - Do NOT add such items to routing decisions, missing-materials lists, clarification questions, option trade-offs, dependency/migration risk, validation checklists, rollout plans, acceptance blockers, residual risks, release recommendations, the `## 5. Clarification Items` table, or any day/effort estimate. They are not legitimate sources of schedule extension.
   - Internal okstra phase handoffs (e.g. the `User Approval Request` block in `implementation-planning`) are unaffected — those are the user themselves approving and proceed without external coordination.
@@ -54,7 +58,7 @@ profile document.
     - `intent-check:` → `Kind=decision`, recommended answer = reporter confirmation. NEVER silently resolve an `intent-check:` by inference at this layer.
     - `terminology:` → `Kind=decision`, recommended answer = canonical term from `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` (or "extend okstra glossary via brief Step 4.5").
     - `conversion-block:` → `Kind=decision`, recommended answer = "보고자에게 직접 확인". The brief is explicitly signalling that translation failed; further inference is forbidden until the reporter clarifies.
-    - `adr-candidate:` → handled by `implementation-planning`; carry forward without modification. Approved decision files land at `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md` (okstra-internal), never at external `<PROJECT_ROOT>/docs/adr/`.
+    - `adr-candidate:` → handled by `implementation-planning`; carry forward without modification. Approved decision files land only at `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`.
     - `general:` → free-form; classify per the standard `Clarification Items` rules.
   - Any decision in this run that contradicts the brief's `Source Material` must be raised back to the reporter via a `Clarification Items` row; it must NOT be silently overridden. Disagreement with the reporter is allowed only after the row is resolved.
   - This contract is the single authority on brief consumption. Phase-specific addenda may *tighten* these rules but may not relax them.
@@ -65,7 +69,8 @@ profile document.
   - section 5 is a **single unified table** per `final-report-template.md`. Every clarification item — whether the user must attach a file, choose between options, or supply a single number/path — is one row of that table. Do not split it into sub-sections (`5.1 추가 자료 요청` / `5.2 사용자 확인 질문` / `4.5.9 Open Questions` are removed and the validator fails reports that reintroduce them), do not create a parallel table elsewhere in the report, and do not duplicate the same item into the top-of-report `User Approval Request (사용자 승인 게이트)` block or any other section.
   - each row's `Kind` column picks one of `{material, decision, data-point}`: `material` for files / snapshots / logs / screenshots the user must attach (the `User input` cell will hold a path or URL); `decision` for choices and yes/no confirmations only the user can make; `data-point` for a single number, ID, date, or short string the user can answer inline. Items that mix "yes/no + file path if yes" are one row of `Kind=material` with the combined expectation written into `Expected form`.
   - each row's `Blocks` column picks one of `{approval, next-phase, none}`. `approval` is reserved for items that gate an approval action, especially the `implementation-planning` User Approval Request; outside `implementation-planning`, unresolved brief reporter-confirmation rows use `next-phase` instead. `next-phase` blocks the next run from starting cleanly. `none` is informational/audit-only.
-  - write every entry in full, descriptive sentences that a non-developer can act on without further context. Avoid abbreviations and internal jargon. The `Statement` cell must state *what* is needed, *why* the answer / attachment changes the next step, and (for `material`) *where* the user can find it and *where* to place it. The `Expected form` cell must state the shape of the answer (예/아니오, 보기 중 하나, 숫자/날짜, 파일 경로, 짧은 서술 등); supply concrete option choices when applicable.
+  - write every entry in full, descriptive sentences that a non-developer can act on without further context. Avoid abbreviations and internal jargon. The `Statement` cell must state *what* is needed, *why* the answer / attachment changes the next step, and (for `material`) *where* the user can find it and *where* to place it. The `Expected form` cell must state the answer shape (예/아니오, 보기 중 하나, 숫자/날짜, 파일 경로, 짧은 서술 등); supply concrete option choices when applicable.
+  - if a phase requires a recommended answer, alternatives, or an evidence-check note, encode it inside the existing 8-column schema: put evidence notes in `Statement` as `Evidence checked: <path:line>` or `Evidence checked: none — <human-only reason>`, and put recommendations/options in `Expected form` as `Recommended: <answer> — <rationale>; Alternatives: <options>`. Do not add `Recommended`, `Evidence`, `Alternatives`, or `evidence-checked` columns.
   - the same `final-report.md` file is the canonical artifact carried into the next run; the user appends answers inline before rerunning. The preferred turn-around is `scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<task-id>` (opens the latest report in `$EDITOR`, then auto-reruns the same phase with `--clarification-response` carry-in). The lower-level form `--clarification-response <path>` remains available for scripted runs.
   - if a clarification response was carried in for this run, render the conditional `## 0. Clarification Response Carried In From Previous Run` section (the template's `RENDER_IF` guard activates it), walk every `C-*` row of the prior report's `## 5. Clarification Items` table, reconcile each one against new evidence, and update its `Status` to `resolved` or `obsolete` before issuing the next decision/verdict. When no carry-in path was provided, omit the `## 0.` heading entirely — the validator fails reports that emit an empty Section 0 stub (e.g. "No prior clarification response was provided for this run.").
 - Verdict Card (shared — applies to every final-report regardless of profile):
@@ -78,8 +83,8 @@ profile document.
   - Reading Confirmation lines (one short line per input file confirming end-to-end reading) live in the **worker audit sidecar** at `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md`, NOT in the worker's main worker-results file. The worker-results body starts at section 1 (Findings). The validator fails worker-results files that contain a `## 0. Reading Confirmation` heading.
   - The audit sidecar carries any other meta the worker wants to log (tool-call counts, MCP query summaries, timing notes). The lead's final-report does NOT duplicate this content — it is consumed by the validator and by post-run audit tooling, not by end-user readers.
 
-- Markdown authoring (shared — applies to every markdown document produced by the lead or any worker, including final-reports, worker-results, briefs, and ad-hoc notes):
-  - every document must begin with an `Index` section.
+- Markdown authoring (shared — applies to markdown documents not already governed by an okstra template/schema):
+  - ad-hoc markdown documents should begin with an `Index` section. Template-governed artifacts such as final-reports, worker-results, and briefs follow their own schema first.
   - include only information necessary to fulfill the user's stated purpose and directly related requirements.
   - follow only the sections, format, tone, and scope specified by the user, plus the required `Index` section.
   - when writing task instructions or work orders, define the scope of work clearly and specifically, including deliverables, acceptance criteria, and verification steps when relevant.

package/runtime/prompts/profiles/error-analysis.md

@@ -9,11 +9,7 @@
   - gemini — when added to the roster it joins the analyser set; omitted by default
 {{INCLUDE:_common-contract.md}}
 - Brief consumption (phase-specific addendum — shared rules live in `_common-contract.md` under "Brief handoff contract"):
-  - **Precondition check (BLOCKING — runs before any analysis)**: read the brief's frontmatter `reporter-confirmations:` field and inspect every `Open Questions` row prefixed `intent-check:` / `conversion-block:` for the `[CONFIRMED …]` marker.
-    - `reporter-confirmations: complete` → proceed normally.
-    - `reporter-confirmations: partial` → proceed; treat still-unmarked `intent-check:` / `conversion-block:` rows per the `skipped` branch below.
-    - `reporter-confirmations: skipped` (or `partial` with remainder) → do NOT silently infer the missing answers. Promote each unmarked `intent-check:` / `conversion-block:` row into this run's `## 5. Clarification Items` as `Kind=decision, Blocks=next-phase`, with the recommended answer drawn from the brief's matching `intent-inference` / `conversion-block:` text and clearly labelled `보고자 직접 확인 권장`. Then proceed with the root-cause analysis using the inference as a *hypothesis* only.
-    - `reporter-confirmations: pending` (or field missing) → ABORT analysis. Write only `## 0. Reporter Confirmation Required` summarising which rows are pending and stop. The final report carries `Blocks=next-phase`.
+  - Apply the shared reporter-confirmation precondition exactly as written. In this phase, unresolved `intent-check:` / `conversion-block:` rows use `Blocks=next-phase`; any unconfirmed inference may be used as a labelled hypothesis only.
   - the reporter's symptom description in `Source Material` is the ground truth for what to reproduce. Do not paraphrase it when stating the symptom in the report; quote it.
   - any `intent-inference` augmentation that re-characterises the symptom (e.g. classifying "가끔 안 됨" as "intermittent failure on a specific code path") is a **hypothesis**, not a confirmed symptom. If `[CONFIRMED …]` appears on the matching `intent-check:` row, treat the confirmation as the symptom; otherwise, follow the precondition's `skipped` branch above and keep the inference labelled as hypothesis in the root-cause analysis.
   - `conversion-block:` rows mean the brief could not map a reporter statement to project vocabulary; never attempt to invent the missing mapping in this phase — the precondition above already handled them.
@@ -31,9 +27,9 @@
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
   - if any blocking uncertainty remains at the time of writing the final report, populate `## 5. Clarification Items` in `final-report-template.md` (a single unified table; `Blocks=next-phase` for items the next run cannot start without)
   - prefer plain Korean over abbreviations (e.g. write "초당 평균 요청 수" instead of "QPS", "재현 절차" instead of "repro")
-  - every clarification row carries a `Recommended` answer + one-line rationale; rows that lack a recommendation are rejected as half-formed.
+  - every clarification row carries a recommended answer + one-line rationale inside the `Expected form` cell; rows that lack a recommendation are rejected as half-formed.
   - **Codebase-first ambiguity resolution (defect rule)**: any ambiguity about repro, file behavior, or symbol semantics that can be answered by `Read` / `Grep` / log inspection MUST be resolved that way and recorded with file:line (or log-line) evidence. Writing a clarification row for something the codebase or shipped logs already answer is a defect of this phase.
-  - **`evidence-checked:` cell required**: every clarification row carries an `evidence-checked: <path:line> | none` cell. `evidence-checked: <path:line>` means the codebase / log / reproducer was inspected and the row records what was found. `evidence-checked: none` is allowed ONLY when the row's nature is "only the reporter can answer this" (reporter-side data, business priority, environment they observed); the row body must state which one in one line. A row with `evidence-checked: none` that *could* have been answered by code or logs is a defect.
+  - **Evidence note required inside `Statement`**: every clarification row includes `Evidence checked: <path:line>` or `Evidence checked: none — <reporter-only reason>` in the `Statement` cell. `none` is allowed ONLY when the row's nature is "only the reporter can answer this" (reporter-side data, business priority, environment they observed). A row with `none` that *could* have been answered by code or logs is a defect.
 - Non-goals:
   - implementation details unless they are necessary to validate the cause
   - **source code edits, builds, migrations, or deployments** — this run produces evidence and cause analysis only; the fix belongs to a later `implementation-planning` run followed by an `implementation` run