okstra 0.33.0 → 0.34.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.33.0",
+  "version": "0.34.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.33.0",
-  "builtAt": "2026-05-19T16:04:42.528Z",
+  "package": "0.34.1",
+  "builtAt": "2026-05-19T16:34:08.806Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -82,6 +82,27 @@ User-utterance interpretation rule:
 - If the current phase's outputs are already complete and the user clearly wants to advance, reply with the phase-transition checklist above and the exact next-run command. Wait for explicit user confirmation before any action that belongs to the next phase.
 - If `nextRecommendedPhase` is `implementation-planning`, the next run produces a **plan**, not code. The next run after that is `implementation`.
 
+## Progress reporting (BLOCKING)
+
+A single okstra run frequently spans 30–120 minutes of wall-clock time with multi-minute silent windows while workers run. Without explicit progress signals the user cannot distinguish "still working" from "hung", so Lead MUST emit a single short progress line at each of the checkpoints below — as plain user-facing text in a separate brief message (not buried inside a tool call). One line per checkpoint, format: `PROGRESS: <phase-id> <verb-phrase>`.
+
+Required checkpoints:
+
+- `PROGRESS: phase-1-intake reading task bundle` — at the start of Phase 1, before issuing parallel Read calls.
+- `PROGRESS: phase-1-intake complete` — after all intake reads return.
+- `PROGRESS: phase-2-prompts preparing <N> worker prompts` — at the start of Phase 2, before any `Write` to the assigned prompt paths.
+- `PROGRESS: phase-3-team-create attempting TeamCreate` — immediately before the `TeamCreate` call.
+- `PROGRESS: phase-4-dispatch worker=<role> model=<model>` — once per worker, immediately before the `Agent` / wrapper call.
+- `PROGRESS: phase-5-collect worker=<role> status=<terminal-status>` — once per worker, immediately after the result file is verified.
+- `PROGRESS: phase-5.5-convergence round=<N> queue=<count>` — at the start of each convergence round (Phase 5.5).
+- `PROGRESS: phase-6-synthesis dispatching report-writer-worker` — at the start of Phase 6.
+- `PROGRESS: phase-7-persist updating manifests` — at the start of Phase 7.
+- `PROGRESS: complete final-report=<relative-path>` — final summary line, after all persistence.
+
+These lines are the only structured signal the user has during a long run. Do NOT replace them with prose ("Now I'm starting Phase 2..."), do NOT skip a checkpoint because "the previous message already said that", and do NOT batch multiple checkpoints into one. Each line stands alone so the user (or any operator scraping stdout) can timestamp it externally.
+
+`okstra-run` (in-session) surfaces these lines to the user directly; the bash-spawned path leaves them in the session jsonl for post-hoc retrieval. Neither path requires any additional formatting from Lead — emit the literal `PROGRESS:` prefix and the rest of the line as plain text.
+
 ## Default model assignments
 
 Unless the task bundle overrides:
@@ -129,21 +150,27 @@ Executor is chosen at run-prep time via `--executor <claude|codex|gemini>` (or `
 
 Treat cross verify input as a task bundle, not as a single file. If the user did not specify an explicit task key or task path, use `.project-docs/okstra/discovery/latest-task.json` as the current-task convenience pointer. If task browsing, task-id disambiguation, or project-level task inventory is needed, inspect `.project-docs/okstra/discovery/task-catalog.json` first.
 
-After context-loader completes, read the following files. The ordering below reflects logical priority for synthesis; for execution, lead MUST issue all Read calls **in a single message (parallel reads)** — these files are independent and serial reads waste several seconds per run with no benefit.
+After context-loader completes, read **only the five mandatory files below** in a single parallel-Read message at the start of Phase 1. The other instruction-set files are loaded lazily at the phase that actually needs them — see "Lazy reading discipline" below. This split came from observed lead-token bloat: in `fontsninja-classifier-v2:dev-9461:dev-9495` RD-001 the lead burned 71 M tokens (97 % cache_read) largely because every phase entry re-absorbed a 93 KB instruction-set baseline that included files only one downstream phase ever actually used.
+
+**Mandatory at Phase 1 start (parallel Read, one message):**
 
 1. `task-manifest.json` (found by context-loader)
-2. `task-index.md` only if a quick human summary is useful
-3. `instruction-set/analysis-profile.md`
-4. `instruction-set/analysis-material.md`
-5. `instruction-set/reference-expectations.md`
-6. `instruction-set/task-brief.md`
-7. `instruction-set/final-report-template.md`
-8. the current run manifest under `runs/<task-type>/manifests/`
-9. the current run team-state artifact
+2. `instruction-set/task-brief.md` — needed to compose every worker prompt
+3. `instruction-set/analysis-profile.md` — needed to compose worker prompts and pick the right `Required workers:` block
+4. the current run manifest under `runs/<task-type>/manifests/`
+5. the current run team-state artifact
+
+**Lazy reading discipline (do NOT read at Phase 1):**
+
+- `task-index.md` — only when the user explicitly asks for a human summary or when history disambiguation is required.
+- `instruction-set/analysis-material.md` — read at Phase 2 only if it is referenced by `analysis-profile.md` or by the brief. Many task bundles have no material file (the placeholder `> 자료가 제공되지 않았습니다` is canonical); in that case skip.
+- `instruction-set/reference-expectations.md` — read at Phase 6 synthesis (or whenever the report-writer worker is dispatched) — it informs the match/gap assessment, not worker dispatch.
+- `instruction-set/final-report-template.md` — never read by Lead. The Report writer worker reads it as part of its own [Required reading]; Lead only references its path when dispatching.
+- `history/timeline.json` — read only on user request or when carry-in resolution requires it.
 
-Extract: task key, task type, work category, workflow lifecycle snapshot, selected worker roster, assigned models, worker result paths, worker prompt history paths, current run prompt directory, final report path, final status path, validator path, resume helper path, config-file references, deployment-manifest references, and their expected values or invariants.
+Extract from the five mandatory files: task key, task type, work category, workflow lifecycle snapshot, selected worker roster, assigned models, worker result paths, worker prompt history paths, current run prompt directory, final report path, final status path, validator path, resume helper path, config-file references, deployment-manifest references, and their expected values or invariants.
 
-If previous run reports exist, use as historical context only. If `history/timeline.json` exists, use it to review past runs. If discovery metadata or current artifacts conflict with a newer user instruction, prefer the user instruction. If `reference-expectations.md` explicitly says expectations were not provided, treat that as missing information and say `I don't know` rather than inventing expected states.
+If previous run reports exist, use as historical context only. If discovery metadata or current artifacts conflict with a newer user instruction, prefer the user instruction. If `reference-expectations.md` explicitly says expectations were not provided (you can confirm this without reading the file if the brief's "Expected state" section is empty), treat that as missing information and say `I don't know` rather than inventing expected states.
 
 ## Phase 2 — Phase 5: Prompt preparation, team creation, execution, fallback
 
@@ -316,6 +343,7 @@ 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" |
+| Waiting silently while the dispatched `claude-worker` Agent call returns nothing for many minutes (the dev-9495 pattern: two 28+25-minute hangs before lead manually `tmux kill-pane`d) | The claude-worker MUST append a `- PROGRESS: <stage> <ISO-UTC>` line to its audit sidecar (`runs/<task-type>/worker-results/claude-worker-audit-<task-type>-<seq>.md`) at least every 5 minutes (see `agents/workers/claude-worker.md` "Heartbeat" rule). If the sidecar is absent or its mtime is >5 minutes stale, treat the dispatch as `timeout` and redispatch once with a byte-identical prompt; after a second silent hang, record terminal status `timeout` with the missing-sidecar reason in team-state. Lead cannot poll mid-Agent-call but MUST inspect the audit sidecar immediately when the Agent call finally returns — a missing sidecar after `completed` is itself a contract violation per the heartbeat rule |
 | 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-data` 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

@@ -59,6 +59,7 @@ Before producing any output, you MUST read every input file enumerated in the `[
 - Use a single `Read` call per file with no `offset` and no `limit`. If a file is genuinely too large for one read, page through it with explicit `offset` / `limit` calls that together cover the entire file, and record the page boundaries in your Findings.
 - For the carry-in clarification response, walk every row of `## 5. Clarification Items` (`C-001`, `C-002`, ...) in full, including rows whose `User input` cell is blank — a blank `User input` with `Status=open` is itself a signal you must surface, not skip. Skimming these rows is the most common failure mode here; the fact that the file you will eventually contribute to has a structurally similar section 5 is NOT a license to skim.
 - Before listing any Findings, write a Reading Confirmation block to your **audit sidecar** at `runs/<task-type>/worker-results/claude-worker-audit-<task-type>-<seq>.md` (sibling to your main worker-results file — substitute `claude-worker-<task-type>-<seq>.md` → `claude-worker-audit-<task-type>-<seq>.md`). The sidecar's body begins with `# Claude Worker Audit — <task-key>` followed by one short line per input file confirming end-to-end reading (e.g. `- Read task-brief.md end-to-end (147 lines).`). Do NOT include a `## 0. Reading Confirmation` heading in the main worker-results file — the validator now fails worker-results that contain one. If you cannot truthfully confirm a file end-to-end, record a `tool-failure` in the errors sidecar instead of fabricating Findings.
+- **Heartbeat — write the audit sidecar EARLY and APPEND per stage (BLOCKING).** Because this worker runs as an in-process Agent or a fresh-session tmux pane, the lead has no `BashOutput`-style liveness signal while waiting for your return. The audit sidecar is the only signal that survives a silent hang. Write the sidecar immediately after extracting `Project Root` and the assigned paths — BEFORE the per-file end-to-end reads — with just the heading line (`# Claude Worker Audit — <task-key>`) and one `- PROGRESS: started <ISO-8601-UTC>` line. Then APPEND one short progress line per stage as you advance: `read-<filename>`, `analysis-start`, `findings-draft-start`, `findings-draft-complete`, `write-result-start`. Each line: `- PROGRESS: <stage> <ISO-8601-UTC>`. The append cadence MUST NOT exceed 5 minutes — if a single analysis stage is taking longer, emit a `- PROGRESS: in-stage:<stage> <ISO-8601-UTC>` heartbeat. A 5-minute stale sidecar mtime is the canonical "this worker has hung" signal for the operator (the lead is blocked on the Agent call and cannot detect this itself, but a human watching via `tail -F <audit-sidecar>` from another terminal can). Sidecar write/append uses `Write` (for the initial creation) and `Edit` / heredoc `>>` for the per-stage append — heredoc append is the lighter option once the file exists.
 - Do not skip a file because its name suggests its content is already familiar from a prior run. Each file is canonical for the current run only.
 
 ## Worker Output Structure

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

@@ -13,10 +13,21 @@
 #   Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)
 #
 # Usage:
-#   okstra-codex-exec.sh <project-root> <model-execution-value> <prompt-path> [worktree-path] [role]
+#   okstra-codex-exec.sh <project-root> <model-execution-value> <prompt-path> [worktree-path] [role] [idle-timeout-seconds]
 #
 # project-root / model-execution-value / prompt-path are required.
 #
+# idle-timeout-seconds is optional (default 600 = 10 minutes). When > 0, an
+# in-process watchdog polls the live-log mtime; if no stdout/stderr write
+# occurs for that many seconds, the underlying `codex exec` is SIGTERM'd
+# (then SIGKILL'd after a 5-second grace), the status sidecar gets a
+# `{timeout: true, idle_seconds, idle_at_ts, terminated_by: "idle-watchdog"}`
+# marker, and the wrapper exits non-zero. Pass `0` to disable. Default
+# exists because silent worker hangs are the dominant lead-time waste —
+# observed 28+25 minutes on hung claude-worker dispatches before manual
+# kill; a 10-minute cap costs ≤10m per hang while leaving long but live
+# runs untouched.
+#
 # worktree-path is optional and used for okstra implementation phase, where the
 # executor must mutate files inside a git worktree that lives outside
 # project-root. When supplied (non-empty), it is forwarded to codex as
@@ -56,8 +67,8 @@
 # The wrapper exits non-zero on any preflight failure.
 set -euo pipefail
 
-if [[ $# -lt 3 || $# -gt 5 ]]; then
-  printf 'usage: %s <project-root> <model-execution-value> <prompt-path> [worktree-path] [role]\n' "$(basename "$0")" >&2
+if [[ $# -lt 3 || $# -gt 6 ]]; then
+  printf 'usage: %s <project-root> <model-execution-value> <prompt-path> [worktree-path] [role] [idle-timeout-seconds]\n' "$(basename "$0")" >&2
   exit 64
 fi
 
@@ -66,6 +77,12 @@ model="$2"
 prompt_path="$3"
 worktree_path="${4-}"
 role="${5:-worker}"
+idle_timeout_secs="${6:-600}"
+
+if ! [[ "$idle_timeout_secs" =~ ^[0-9]+$ ]]; then
+  printf 'okstra-codex-exec: idle-timeout-seconds must be a non-negative integer: %q\n' "$idle_timeout_secs" >&2
+  exit 69
+fi
 
 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
@@ -247,14 +264,64 @@ fi
 # stdin redirect, stderr capture, and pipeline mirroring are intentionally
 # inside the wrapper — this is the entire reason this script exists.
 #
-# stdout: tee'd to both the log file (for `tail -f`) AND the wrapper's own
+# stdout: tee'd to both the live log (for `tail -f`) AND the wrapper's own
 #         stdout (so the subagent's `BashOutput` still captures the final
-#         text verbatim for Phase 5 synthesis).
-# stderr: appended to the log file only — mirrors the prior `2>/dev/null`
+#         text verbatim for Phase 5 synthesis). Implemented via process
+#         substitution so codex itself stays a single addressable PID we
+#         can SIGTERM from the watchdog.
+# stderr: appended to the live log only — mirrors the prior `2>/dev/null`
 #         contract of keeping the wrapper's stderr stream clean.
-# exit:   `PIPESTATUS[0]` preserves codex's own exit code (tee always 0).
-{
-  codex exec -C "$project_root" ${extra_args[@]+"${extra_args[@]}"} --model "$model" --sandbox workspace-write - \
-    < "$prompt_path" 2>> "$log_path"
-} | tee -a "$log_path"
-exit "${PIPESTATUS[0]}"
+# exit:   codex's own exit code is preserved by `wait`.
+codex exec -C "$project_root" ${extra_args[@]+"${extra_args[@]}"} --model "$model" --sandbox workspace-write - \
+  < "$prompt_path" \
+  2>> "$log_path" \
+  > >(tee -a "$log_path") &
+codex_pid=$!
+
+# Idle watchdog: poll the live log's mtime; if no write (stdout or stderr)
+# arrives for $idle_timeout_secs, SIGTERM codex, give it a 5-second grace,
+# then SIGKILL. Record the termination cause in the status sidecar so the
+# caller (lead) can distinguish "ran to completion with non-zero exit" from
+# "killed because it went silent". Set 0 to disable entirely.
+watchdog_pid=""
+if (( idle_timeout_secs > 0 )); then
+  poll_interval=$(( idle_timeout_secs / 20 ))
+  (( poll_interval < 5 )) && poll_interval=5
+  (( poll_interval > 30 )) && poll_interval=30
+  (
+    while kill -0 "$codex_pid" 2>/dev/null; do
+      sleep "$poll_interval"
+      kill -0 "$codex_pid" 2>/dev/null || exit 0
+      last_mtime=$(stat -f %m "$log_path" 2>/dev/null || stat -c %Y "$log_path" 2>/dev/null || printf '0')
+      now=$(date +%s)
+      idle=$(( now - last_mtime ))
+      if (( idle >= idle_timeout_secs )); then
+        printf '\n[okstra wrapper] idle-watchdog: %ds without stdout — terminating codex (pid=%d)\n' \
+          "$idle" "$codex_pid" >> "$log_path" 2>&1 || true
+        python3 "$script_dir/okstra-wrapper-status.py" \
+          timeout "$status_path" "$now" "$idle" >>"$log_path" 2>&1 || true
+        kill -TERM "$codex_pid" 2>/dev/null || true
+        sleep 5
+        kill -KILL "$codex_pid" 2>/dev/null || true
+        exit 0
+      fi
+    done
+  ) &
+  watchdog_pid=$!
+fi
+
+set +e
+wait "$codex_pid"
+codex_exit=$?
+set -e
+
+if [[ -n "$watchdog_pid" ]]; then
+  kill "$watchdog_pid" 2>/dev/null || true
+  wait "$watchdog_pid" 2>/dev/null || true
+fi
+
+# Drain the process-substitution tee so the final lines reach the live log
+# and the caller's stdout before exit.
+wait 2>/dev/null || true
+
+exit "$codex_exit"

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

@@ -13,10 +13,19 @@
 #   Bash($HOME/.okstra/bin/okstra-gemini-exec.sh:*)
 #
 # Usage:
-#   okstra-gemini-exec.sh <project-root> <model-execution-value> <prompt-path> [worktree-path] [role]
+#   okstra-gemini-exec.sh <project-root> <model-execution-value> <prompt-path> [worktree-path] [role] [idle-timeout-seconds]
 #
 # project-root / model-execution-value / prompt-path are required.
 #
+# idle-timeout-seconds is optional (default 600 = 10 minutes). When > 0, an
+# in-process watchdog polls the live-log mtime; if no stdout/stderr write
+# occurs for that many seconds, the underlying `gemini` is SIGTERM'd (then
+# SIGKILL'd after a 5-second grace), the status sidecar gets a
+# `{timeout: true, idle_seconds, idle_at_ts, terminated_by: "idle-watchdog"}`
+# marker, and the wrapper exits non-zero. Pass `0` to disable. Kept in
+# lock-step with `okstra-codex-exec.sh` — see that wrapper for the full
+# design rationale.
+#
 # worktree-path is optional and used for okstra implementation phase, where the
 # executor must mutate files inside a git worktree that lives outside
 # project-root. When supplied (non-empty), it is appended to gemini's
@@ -36,8 +45,8 @@
 # The wrapper exits non-zero on any preflight failure.
 set -euo pipefail
 
-if [[ $# -lt 3 || $# -gt 5 ]]; then
-  printf 'usage: %s <project-root> <model-execution-value> <prompt-path> [worktree-path] [role]\n' "$(basename "$0")" >&2
+if [[ $# -lt 3 || $# -gt 6 ]]; then
+  printf 'usage: %s <project-root> <model-execution-value> <prompt-path> [worktree-path] [role] [idle-timeout-seconds]\n' "$(basename "$0")" >&2
   exit 64
 fi
 
@@ -46,6 +55,12 @@ model="$2"
 prompt_path="$3"
 worktree_path="${4-}"
 role="${5:-worker}"
+idle_timeout_secs="${6:-600}"
+
+if ! [[ "$idle_timeout_secs" =~ ^[0-9]+$ ]]; then
+  printf 'okstra-gemini-exec: idle-timeout-seconds must be a non-negative integer: %q\n' "$idle_timeout_secs" >&2
+  exit 69
+fi
 
 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
@@ -189,14 +204,58 @@ fi
 # `--include-directories` plus the Project Root referenced in the prompt
 # body itself.
 #
-# stdout: tee'd to both the log file (for `tail -f`) AND the wrapper's own
+# stdout: tee'd to both the live log (for `tail -f`) AND the wrapper's own
 #         stdout (so the subagent's `BashOutput` still captures the final
-#         text verbatim for Phase 5 synthesis).
-# stderr: appended to the log file only — mirrors the prior `2>/dev/null`
+#         text verbatim for Phase 5 synthesis). Implemented via process
+#         substitution so gemini itself stays a single addressable PID we
+#         can SIGTERM from the watchdog.
+# stderr: appended to the live log only — mirrors the prior `2>/dev/null`
 #         contract of keeping the wrapper's stderr stream clean.
-# exit:   `PIPESTATUS[0]` preserves gemini's own exit code (tee always 0).
-{
-  gemini -p - -m "$model" -o text --include-directories "$include_dirs" \
-    < "$prompt_path" 2>> "$log_path"
-} | tee -a "$log_path"
-exit "${PIPESTATUS[0]}"
+# exit:   gemini's own exit code is preserved by `wait`.
+gemini -p - -m "$model" -o text --include-directories "$include_dirs" \
+  < "$prompt_path" \
+  2>> "$log_path" \
+  > >(tee -a "$log_path") &
+gemini_pid=$!
+
+# Idle watchdog — see `okstra-codex-exec.sh` for the full rationale.
+watchdog_pid=""
+if (( idle_timeout_secs > 0 )); then
+  poll_interval=$(( idle_timeout_secs / 20 ))
+  (( poll_interval < 5 )) && poll_interval=5
+  (( poll_interval > 30 )) && poll_interval=30
+  (
+    while kill -0 "$gemini_pid" 2>/dev/null; do
+      sleep "$poll_interval"
+      kill -0 "$gemini_pid" 2>/dev/null || exit 0
+      last_mtime=$(stat -f %m "$log_path" 2>/dev/null || stat -c %Y "$log_path" 2>/dev/null || printf '0')
+      now=$(date +%s)
+      idle=$(( now - last_mtime ))
+      if (( idle >= idle_timeout_secs )); then
+        printf '\n[okstra wrapper] idle-watchdog: %ds without stdout — terminating gemini (pid=%d)\n' \
+          "$idle" "$gemini_pid" >> "$log_path" 2>&1 || true
+        python3 "$script_dir/okstra-wrapper-status.py" \
+          timeout "$status_path" "$now" "$idle" >>"$log_path" 2>&1 || true
+        kill -TERM "$gemini_pid" 2>/dev/null || true
+        sleep 5
+        kill -KILL "$gemini_pid" 2>/dev/null || true
+        exit 0
+      fi
+    done
+  ) &
+  watchdog_pid=$!
+fi
+
+set +e
+wait "$gemini_pid"
+gemini_exit=$?
+set -e
+
+if [[ -n "$watchdog_pid" ]]; then
+  kill "$watchdog_pid" 2>/dev/null || true
+  wait "$watchdog_pid" 2>/dev/null || true
+fi
+
+wait 2>/dev/null || true
+
+exit "$gemini_exit"

package/runtime/prompts/launch.template.md

@@ -3,6 +3,10 @@
 You are `Claude lead` for project `{{PROJECT_ID}}`.
 Invoke the `okstra` skill now. Read the manifests below for all task metadata, paths, model assignments, and worker roster.
 
+## Progress reporting (BLOCKING)
+
+Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at every checkpoint enumerated in `agents/SKILL.md` "Progress reporting (BLOCKING)" — phase-1-intake start/complete, phase-2-prompts, phase-3-team-create, phase-4-dispatch (per worker), phase-5-collect (per worker), phase-5.5-convergence (per round), phase-6-synthesis, phase-7-persist, and final `complete`. One line per checkpoint, never batched, never replaced with prose. This is the only signal the user has during multi-minute silent windows.
+
 ## Current Phase Boundary
 
 - Current lifecycle phase: `{{WORKFLOW_CURRENT_PHASE}}`

package/runtime/python/okstra_ctl/render.py

@@ -18,6 +18,7 @@ session id 등) 를 덧붙여 전달한다.
 from __future__ import annotations
 
 import json
+import re
 import sys
 from pathlib import Path
 
@@ -47,6 +48,44 @@ def _write_json(path: Path, payload: dict) -> None:
     _write_text(path, json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
 
 
+_PHASE_BLOCK_RE = re.compile(
+    r"\{% if header\.taskType == '(implementation-planning|release-handoff|implementation|final-verification)' %\}\n(.*?)\{% endif %\}\n",
+    re.DOTALL,
+)
+
+
+def _strip_phase_blocks(text: str, current_phase: str) -> str:
+    """Resolve phase-conditional blocks (`{% if header.taskType == 'X' %}
+    ... {% endif %}`) against *current_phase*.
+
+    Blocks whose target equals *current_phase* keep their body (jinja
+    markers dropped); blocks targeting a different phase are removed
+    entirely. When *current_phase* is empty or not one of the four
+    block-targetable phases (e.g. `requirements-discovery`,
+    `error-analysis`), every block is dropped — correct because none of
+    the `## 4.5` / `4.6` / `4.7` / `4.8` deliverable sections apply
+    there.
+
+    Observed (fontsninja-classifier-v2 RD run): the raw final-report
+    template copied into instruction-set/final-report-template.md was
+    43 KB / 631 lines; ~30 KB / ~330 lines belonged to the four other
+    phases' deliverables and was never relevant to that run. Stripping
+    at copy time cuts the lead/report-writer's baseline by ~7 K tokens
+    per phase entry.
+
+    Inline conditionals (those that begin and end on the same line) are
+    intentionally untouched — the regex only matches block-form
+    `{% if ... %}\\n ... \\n{% endif %}\\n`.
+    """
+
+    def repl(m: "re.Match[str]") -> str:
+        target_phase = m.group(1)
+        body = m.group(2)
+        return body if target_phase == current_phase else ""
+
+    return _PHASE_BLOCK_RE.sub(repl, text)
+
+
 _FM_DEFAULT = "no-classification"
 
 _FM_TAGS_BASE = []
@@ -1252,6 +1291,7 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
     rendered = template
     for k, v in mapping.items():
         rendered = rendered.replace(k, v)
+    rendered = _strip_phase_blocks(rendered, ctx.get("ANALYSIS_TYPE", ""))
     _write_text(Path(output_path), rendered.rstrip() + "\n")
 
 
@@ -1591,6 +1631,7 @@ def render_template_file(template_path: str, output_path: str, ctx: dict) -> Non
     rendered = template
     for k, v in mapping.items():
         rendered = rendered.replace(k, v)
+    rendered = _strip_phase_blocks(rendered, ctx.get("ANALYSIS_TYPE", ""))
     _write_text(Path(output_path), rendered.rstrip() + "\n")