okstra 0.114.0 → 0.115.0

package/docs/kr/architecture.md

@@ -235,7 +235,7 @@ per-process 환경 변수에 task 정체성·경로·workflow 상태를 보관
 - standard workflow의 기본 worker role은 `Claude worker`, `Codex worker`, `Report writer worker`이며, `Antigravity worker`는 `--workers` 또는 프로필에서 명시할 때만 포함되는 옵션입니다.
 - worker 역할 분담과 최종 판단은 Claude가 task bundle을 읽고 수행합니다.
 - 사용자 홈에 설치된 okstra Claude assets(`~/.claude/skills`, `~/.claude/agents`) 는 `Agent(name: ...)` 로 워커를 dispatch 하도록 Claude 를 유도합니다 — 워커는 세션의 implicit team 에 자동 합류합니다.
-- **팀 lifecycle (Claude Code v2.1.178+)**: v2.1.178 이 `TeamCreate` / `TeamDelete` 도구와 `Agent(...)` 의 `team_name` 파라미터를 제거했습니다. `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`(`okstra install` 이 `settings.json` 에 시드) 이면 세션마다 implicit team 1개가 시작 시점에 자동 생성됩니다. lead 는 Phase 3 에서 팀을 만드는 도구를 호출하지 않고, `teamName` audit 라벨과 `teamCreate: { attempted: false, status: "implicit", splitPane: <$TMUX 유무> }` 만 기록한 뒤 워커를 `Agent(name: "<role>-worker", run_in_background: true)`(team_name 없음)로 dispatch 합니다. split-pane teammate 는 `$TMUX` 가 설정돼 있고 `teammateMode: auto` 일 때 나타나며, tmux 밖이면 in-process 로 돕니다(둘 다 정상). run 종료 시 Phase 7 토큰 집계 이후 잔여 tmux pane 정리를 확인하고, split-pane run 에서만 worker teammate 를 정리할지 확인합니다. 승인 시 `okstra-team-reconcile.sh` 로 dead-pane stale-active 멤버를 inactive 로 정리하고 각 완료 teammate 에 `SendMessage` shutdown_request 를 보냅니다 — implicit team 자체를 지우는 도구는 없으며, 팀은 세션 종료와 함께 사라집니다. 사용자가 유지하면 teammate 는 FleetView roster 에 남고, lead 는 Teams/FleetView 에서 제거하라고 안내합니다 (`prompts/profiles/_common-contract.md` 의 *Run-end teammate teardown*). Phase 7 토큰 집계는 `teamCreate.status` 가 `implicit`/`skipped`/`error` 일 때 `agentName` 기반으로 워커 세션을 찾습니다(implicit team 은 jsonl 을 `session-<leadSid>` 로 태깅하므로 okstra 의 `teamName` 라벨 needle 만으로는 lead 만 잡힘).
+- **팀 lifecycle (Claude Code v2.1.178+)**: v2.1.178 이 `TeamCreate` / `TeamDelete` 도구와 `Agent(...)` 의 `team_name` 파라미터를 제거했습니다. `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`(`okstra install` 이 `settings.json` 에 시드) 이면 세션마다 implicit team 1개가 시작 시점에 자동 생성됩니다. lead 는 Phase 3 에서 팀을 만드는 도구를 호출하지 않고, `teamName` audit 라벨과 `teamCreate: { attempted: false, status: "implicit", splitPane: <$TMUX 유무> }` 만 기록한 뒤 워커를 `Agent(name: "<role>-worker", run_in_background: true)`(team_name 없음)로 dispatch 합니다. split-pane teammate 는 `$TMUX` 가 설정돼 있고 `teammateMode: auto` 일 때 나타나며, tmux 밖이면 in-process 로 돕니다(둘 다 정상). run 종료 시 Phase 7 토큰 집계 이후 잔여 tmux pane 정리를 확인하고, split-pane run 에서만 worker teammate 를 정리할지 확인합니다. 승인 시 `okstra-team-reconcile.sh` 로 dead-pane stale-active 멤버를 inactive 로 정리하고 각 완료 teammate 에 `SendMessage` shutdown_request 를 보냅니다 — implicit team 자체를 지우는 도구는 없으며, 팀은 세션 종료와 함께 사라집니다. 사용자가 유지하면 teammate 는 FleetView roster 에 남고, lead 는 Teams/FleetView 에서 제거하라고 안내합니다 (`prompts/profiles/_common-contract.md` 의 *Run-end teammate teardown*). Phase 7 토큰 집계는 `teamCreate.status` 가 `implicit`/`skipped`/`error` 일 때 top-level `agentName` 또는 nested `subagents/agent-a<name>-<hash>.jsonl` 파일명 기반으로 워커 세션을 찾습니다.
 
 ## Claude prompt contract
 
@@ -698,7 +698,7 @@ Phase 7 step 1.5 가 final-report MD 한 본을 입력으로 self-contained HTML
 
 - Helper CLI: `scripts/okstra-token-usage.py`
 - 수집 소스:
-  - Claude lead/workers: `~/.claude/projects/<cwd-as-dashes>/<sessionId>.jsonl`의 per-message `message.usage`
+  - Claude lead/workers: `~/.claude/projects/<cwd-as-dashes>/<sessionId>.jsonl` 또는 `~/.claude/projects/<cwd-as-dashes>/<lead-session>/subagents/agent-a<worker-name>-<hash>.jsonl` 의 per-message `message.usage`. nested subagent 파일은 파일명에서 worker name 을 복원하고, 현재 run 의 `team-state.lead.sessionId` 디렉터리 아래만 집계합니다.
   - Codex CLI: `~/.agent/sessions/Y/M/D/rollout-*.jsonl`의 마지막 `total_token_usage.total_tokens`
   - Antigravity CLI: `~/.antigravity/tmp/*/chats/session-*.json`의 per-message `tokens.total`
 - billable-equivalent token math와 USD cost estimation을 함께 기록합니다. Anthropic billing ratio(`cache_creation_5m=1.25x`, `cache_creation_1h=2.0x`, `cache_read=0.1x`, `output=5x`)를 반영합니다. transcript 의 `usage.cache_creation.ephemeral_5m_input_tokens` / `ephemeral_1h_input_tokens` 분해가 있으면 분리 집계합니다.

package/docs/kr/follow-ups/2026-07-10-final-report-option-3.md

@@ -0,0 +1,51 @@
+# Final Report 가독성 후속: 3안 재검토
+
+상태: 보류
+작성일: 2026-07-10
+
+## 배경
+
+이번 1차 가독성 개선은 범위를 좁게 유지했다.
+
+- `readerSummary`로 Markdown final-report 앞부분에 사람이 먼저 읽을 요약 진입점을 둔다.
+- HTML report view에 Reader Summary dashboard와 reader mode를 추가한다.
+- 기존 `final-report` data는 `verdictCard` fallback으로 계속 호환한다.
+
+이 문서는 더 큰 3안을 현재 변경에 섞지 않고, 나중에 별도 판단할 재검토 후보로 남긴다.
+
+## 보류한 3안
+
+`final-report` 산출물 자체를 목적별로 분리할지 재검토한다.
+
+현재 구조는 하나의 canonical Markdown 문서와 그 문서에서 생성되는 view를 유지한다. 3안은 요약 블록이나 HTML 필터링만으로 충분한지, 아니면 report를 목적별 artifact로 나누는 편이 더 나은지 비교하는 작업이다.
+
+비교 후보:
+
+- 짧은 human handoff report와 별도 audit appendix.
+- 같은 `data.json`에서 생성되는 `summary` view와 `audit` view.
+- 사람이 먼저 행동하는 섹션만 남기는 phase별 slim report template.
+- reporter handoff, implementer handoff, verifier audit, release handoff 같은 role별 view set.
+
+## 재검토 트리거
+
+아래 중 하나가 반복되면 이 문서를 다시 연다.
+
+- `readerSummary`와 HTML reader mode 배포 후에도 사용자가 `final-report`를 읽기 어렵다고 말한다.
+- 리뷰어가 항상 같은 audit 섹션을 건너뛰거나 더 작은 handoff artifact를 요구한다.
+- `final-report` 생성에서 같은 evidence가 여러 섹션에 반복된다.
+- 향후 schema migration에서 report artifact 계약을 어차피 건드려야 한다.
+
+## 결정할 질문
+
+- Markdown이 계속 primary human artifact인가, 아니면 `data.json`만 canonical source로 두고 view를 생성할 것인가?
+- follow-up task에 기본 첨부할 artifact는 무엇인가?
+- 어떤 섹션이 human-action material이고, 어떤 섹션이 audit-only material인가?
+- 분리를 validator가 강제해야 하는가, renderer convention으로 둘 것인가?
+- 분리가 기존 `render-views`, follow-up spawning, approval sidecar에 어떤 영향을 주는가?
+
+## 참조
+
+- 현재 schema: `schemas/final-report-v1.0.schema.json`
+- 현재 Markdown template: `templates/reports/final-report.template.md`
+- 현재 HTML renderer: `scripts/okstra_ctl/report_views.py`
+- 현재 report UI assets: `templates/reports/report.css`, `templates/reports/report.js`

package/package.json

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

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.114.0",
-  "builtAt": "2026-07-08T17:31:16.739Z",
+  "package": "0.115.0",
+  "builtAt": "2026-07-09T15:25:58.950Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -88,6 +88,7 @@ Rules (the schema enforces most of these — they are listed here so you know *w
 - `header.reportAuthor` is `"Report writer worker"`; `header.reportOwner` is `"Claude lead"`. Set author to `"Claude lead"` only for `release-handoff` runs (single-lead by design) or a recorded report-writer dispatch failure fallback.
 - **Source items (worker:item) preservation.** Every `consensus[].sourceItems`, `differences[].workersPosition[].itemId`, and `evidence.primary[].sourceItems` entry MUST carry the worker:item-id pair (e.g. `claude:F-001`, `codex:1.1`, `antigravity:F-3`, or `lead:mcp-1` for lead-only evidence). The schema enforces this via the `SourceItem` regex; bare worker-name lists no longer parse.
 - **Verdict Card consistency.** `verdictCard.verdictToken` / `.direction` / `.nextStep` MUST byte-match `finalVerdict.verdictToken` / `.direction` / `.nextStep` and `recommendedNextSteps[0].text`. The renderer pulls both from the same data structure — duplicating values across `verdictCard` and `finalVerdict` is intentional so the validator can diff them.
+- **Reader Summary.** Populate `readerSummary` when the schema excerpt exposes it. It is the human-first entrypoint for both Markdown and HTML: one sentence for the decision, one for the human action required, one for blockers, one for audit sections safe to skip on first read, and one runnable recommended command. Do not duplicate raw evidence tables here.
 - **§7 phase-continuation row (mandatory for non-terminal task-types).** When `header.taskType` is one of `requirements-discovery` / `implementation-planning` / `error-analysis` / `implementation` / `final-verification`, `followUpTasks` MUST contain at least one row whose `origin` is `phase-continuation`, `suggestedTaskType` equals the next phase (byte-identical to `finalVerdict.nextStep`'s referenced phase), `newTaskId` reuses the current task-id, `autoSpawn` is `"no"`, and `priority` is `"P0"`. For `release-handoff` runs, omit the phase-continuation row. Schema `allOf` clause enforces this via `contains`.
 - **No deprecated sections.** The schema has no `4.5.8 User Approval Request` body field, no `4.5.9 Open Questions`, no `5.1 추가 자료 요청`, no `5.2 사용자 확인 질문` — clarifications go under the unified `clarificationItems[]` array.
 - **Optional Section 0.** Include `clarificationCarryIn` ONLY when the lead's prompt provides a non-empty carry-in path. Omit the key entirely otherwise (do NOT set it to `null` or an empty object).

package/runtime/prompts/lead/okstra-lead-contract.md

@@ -366,7 +366,7 @@ jq -s 'group_by(.errorType) | map({type: .[0].errorType, count: length})' <runDi
 
 The errors log is informational. Its presence/absence does not affect the final verdict. Do not block report writing on it.
 
-After persistence, reply briefly in the resolved Report Language with: completion status, final report path, team-state path, validator result, resume command path, any remaining blocker.
+After persistence, reply briefly in the resolved Report Language with: completion status, final report path, team-state path, validator result, resume command path, any remaining blocker. **Lead this reply with the run's task identity** — state `<task-group>/<task-id>` (or the full `taskKey`) first, so the reader knows which task the reply is about. **Every run-artifact path in this reply MUST be task-qualified** — report the final report as `.okstra/tasks/<task-group>/<task-id>/runs/<task-type>/reports/final-report-<task-type>-<seq>.md` (the full path rooted at the task bundle), NOT the bare `runs/<task-type>/reports/...` form. The bare `runs/...` prefix is byte-for-byte identical across every task-group / task-id of the same task-type, so it cannot tell one task's report from another's — always emit the `.okstra/tasks/<task-group>/<task-id>/` prefix. The same task-qualified rule applies to the team-state path, resume command path, and any other run-artifact path this reply cites.
 
 ## Run-scoped pane & teammate lifecycle
 

package/runtime/python/okstra_ctl/implementation_stage.py

@@ -1,8 +1,8 @@
 """Implementation stage run orchestration.
 
-This module owns the lifecycle for one ``implementation`` stage run: recover
-consumer state, select an available Stage Map entry, provision the isolated
-stage worktree, and publish the selected stage into run context.
+This module owns the Stage Run Claim for one ``implementation`` stage run:
+recover consumer state, select an available Stage Map entry, provision the
+isolated stage worktree, and record the started event.
 """
 from __future__ import annotations
 
@@ -18,12 +18,12 @@ from .stage_reconcile import auto_reconcile_best_effort
 
 
 class ImplementationStageError(Exception):
-    """Implementation stage selection or provisioning failed."""
+    """Implementation stage claim or provisioning failed."""
 
 
 @dataclass
-class StageSelection:
-    """Resolved implementation stage and its isolated worktree coordinates."""
+class StageRunClaim:
+    """Claim over one Stage Map stage and its isolated worktree coordinates."""
 
     stage: int
     worktree_path: str
@@ -50,22 +50,20 @@ def _as_implementation_stage_error(exc: Exception) -> ImplementationStageError:
     return ImplementationStageError(str(exc))
 
 
-def select_and_provision_implementation_stage(
+def claim_implementation_stage_run(
     inp: Any,
     ctx_stage_map: list[dict[str, Any]],
     task_group_segment: str,
     task_id_segment: str,
     task_key: str,
     executor_worktree_status: str,
-) -> StageSelection:
-    """Select a ready implementation stage and provision its stage worktree.
+) -> StageRunClaim:
+    """Claim a ready implementation stage for one run.
 
-    The returned selection is path-independent with respect to run artifacts:
+    The returned claim is path-independent with respect to run artifacts:
     callers can compute stage-specific run paths after this function resolves
     the selected stage.
     """
-    del task_key  # The registry uses the split identity fields.
-
     from .consumers import backfill_done_from_carry
     from . import worktree as _worktree
     from . import worktree_registry as _reg
@@ -95,7 +93,7 @@ def select_and_provision_implementation_stage(
 
     if executor_worktree_status.startswith("skipped"):
         head = _git_out(inp.project_root, "rev-parse", "HEAD")
-        return StageSelection(
+        claim = StageRunClaim(
             stage=selected,
             worktree_path="",
             worktree_branch="",
@@ -105,6 +103,8 @@ def select_and_provision_implementation_stage(
             started_head_commit=head,
             concurrent_stages=concurrent_stages,
         )
+        _record_stage_run_claim_started(task_key, plan_run_root, claim)
+        return claim
 
     # The anchor and multi-dep candidate base must come from the task-key
     # worktree HEAD (where stage work accumulates), not from inp.project_root
@@ -166,7 +166,7 @@ def select_and_provision_implementation_stage(
             f"stage worktree provisioning failed: {exc}\n{hint}"
         ) from exc
 
-    return StageSelection(
+    claim = StageRunClaim(
         stage=selected,
         worktree_path=prov.path,
         worktree_branch=prov.branch,
@@ -176,22 +176,40 @@ def select_and_provision_implementation_stage(
         started_head_commit=prov.base_ref,
         concurrent_stages=concurrent_stages,
     )
+    _record_stage_run_claim_started(task_key, plan_run_root, claim)
+    return claim
+
+
+def _record_stage_run_claim_started(
+    task_key: str,
+    plan_run_root: Path,
+    claim: StageRunClaim,
+) -> None:
+    from .consumers import append_consumer
 
+    now = _dt.datetime.now(_dt.timezone.utc).isoformat()
+    append_consumer(
+        plan_run_root,
+        impl_task_key=task_key,
+        stage=claim.stage,
+        status="started",
+        started_at=now,
+        head_commit=claim.started_head_commit,
+    )
 
-def apply_implementation_stage(
+
+def publish_stage_run_claim(
     inp: Any,
     ctx: dict[str, Any],
     ctx_stage_map: list[dict[str, Any]],
-    sel: StageSelection,
+    claim: StageRunClaim,
 ) -> None:
-    """Publish a selected stage into run context and ``consumers.jsonl``."""
-    from .consumers import append_consumer
-
+    """Publish a Stage Run Claim into run context."""
     ctx["parsed_stage_map"] = ctx_stage_map
-    ctx["effective_stages"] = [sel.stage]
-    csv = str(sel.stage)
+    ctx["effective_stages"] = [claim.stage]
+    csv = str(claim.stage)
     ctx["EFFECTIVE_STAGES"] = csv
-    ctx["CONCURRENT_RUN_STAGES"] = ",".join(str(s) for s in sel.concurrent_stages)
+    ctx["CONCURRENT_RUN_STAGES"] = ",".join(str(s) for s in claim.concurrent_stages)
     ctx["STAGE_BATCH_DIRECTIVE"] = (
         f"- **Stage for this implementation run:** `{csv}`. "
         "Execute exactly this Stage Map stage — this is the authoritative scope. "
@@ -201,20 +219,9 @@ def apply_implementation_stage(
     inp.stage = csv
     print(f"selected stages: {csv}", file=sys.stdout)
 
-    if sel.worktree_status and not sel.worktree_status.startswith("skipped"):
-        ctx["EXECUTOR_WORKTREE_PATH"] = sel.worktree_path
-        ctx["EXECUTOR_WORKTREE_BRANCH"] = sel.worktree_branch
-        ctx["EXECUTOR_WORKTREE_BASE_REF"] = sel.worktree_base_ref
-        ctx["EXECUTOR_WORKTREE_STATUS"] = sel.worktree_status
-        ctx["EXECUTOR_WORKTREE_NOTE"] = sel.worktree_note
-
-    now = _dt.datetime.now(_dt.timezone.utc).isoformat()
-    plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
-    append_consumer(
-        plan_run_root,
-        impl_task_key=ctx["TASK_KEY"],
-        stage=sel.stage,
-        status="started",
-        started_at=now,
-        head_commit=sel.started_head_commit,
-    )
+    if claim.worktree_status and not claim.worktree_status.startswith("skipped"):
+        ctx["EXECUTOR_WORKTREE_PATH"] = claim.worktree_path
+        ctx["EXECUTOR_WORKTREE_BRANCH"] = claim.worktree_branch
+        ctx["EXECUTOR_WORKTREE_BASE_REF"] = claim.worktree_base_ref
+        ctx["EXECUTOR_WORKTREE_STATUS"] = claim.worktree_status
+        ctx["EXECUTOR_WORKTREE_NOTE"] = claim.worktree_note

package/runtime/python/okstra_ctl/report_views.py

@@ -67,6 +67,7 @@ def _strip_leading_frontmatter(text: str) -> str:
 
 from .clarification_items import (
     _CELL_ANCHOR_RE,
+    UNRESOLVED_STATUSES,
     _section_1_slice,
     _split_pipe_row,
     parse_clarification_items,
@@ -117,6 +118,19 @@ class ReportViewModel:
     sidecar_name: str
     sidecar_dir: str
     approval_ctx: PlanApprovalContext | None = None
+    reader_ctx: ReaderDashboardContext | None = None
+
+
+@dataclass(frozen=True)
+class ReaderDashboardContext:
+    decision: str
+    human_action_required: str
+    blocking_items: str
+    safe_to_skip: str
+    recommended_command: str
+    open_clarifications: int
+    approval: str
+    recommended_option: str
 
 
 def build_report_view_model(
@@ -124,6 +138,7 @@ def build_report_view_model(
     *,
     run_meta: RunMeta,
     approval_ctx: PlanApprovalContext | None = None,
+    reader_ctx: ReaderDashboardContext | None = None,
 ) -> ReportViewModel:
     digest = source_digest(src_md)
     body_md = _strip_leading_frontmatter(src_md)
@@ -141,6 +156,36 @@ def build_report_view_model(
         sidecar_name=f"user-response-{run_meta.task_type}-{run_meta.seq}.md",
         sidecar_dir=f"runs/{run_meta.task_type}/user-responses/",
         approval_ctx=approval_ctx,
+        reader_ctx=reader_ctx,
+    )
+
+
+def _reader_dashboard(ctx: ReaderDashboardContext | None) -> str:
+    if ctx is None:
+        return ""
+    rows = (
+        ("Decision", html.escape(ctx.decision)),
+        ("Human action required", html.escape(ctx.human_action_required)),
+        ("Blocking items", html.escape(ctx.blocking_items)),
+        ("Safe to skip", html.escape(ctx.safe_to_skip)),
+        ("Open clarifications", str(ctx.open_clarifications)),
+        ("Approval", html.escape(ctx.approval)),
+        ("Recommended option", html.escape(ctx.recommended_option or "--")),
+        ("Recommended command", f"<code>{html.escape(ctx.recommended_command or '--')}</code>"),
+    )
+    summary = "".join(f"<dt>{label}</dt><dd>{value}</dd>" for label, value in rows)
+    return (
+        '<section class="reader-dashboard" aria-label="Reader summary" data-reader-section="action">\n'
+        '  <div class="reader-dashboard-head">\n'
+        "    <h2>Reader Summary</h2>\n"
+        '    <div class="reader-mode-controls" aria-label="Reading mode">\n'
+        '      <button type="button" data-action="set-reader-mode" data-reader-mode="action" aria-pressed="true">Action</button>\n'
+        '      <button type="button" data-action="set-reader-mode" data-reader-mode="audit" aria-pressed="false">Audit</button>\n'
+        '      <button type="button" data-action="set-reader-mode" data-reader-mode="full" aria-pressed="false">Full</button>\n'
+        "    </div>\n"
+        "  </div>\n"
+        f'  <dl class="reader-summary-grid">{summary}</dl>\n'
+        "</section>\n"
     )
 
 
@@ -171,7 +216,7 @@ def render_report_view_model(
         f"  <div>{title}</div>\n"
         f"  <button type=\"button\" data-action=\"export-user-response\">Export user response</button>\n"
         f"</header>\n"
-        f"<main>{model.body_html}</main>\n"
+        f"<main>{_reader_dashboard(model.reader_ctx)}{model.body_html}</main>\n"
         f"{_plan_approval_section(model.approval_ctx, run_meta) if model.approval_ctx else ''}"
         f"<footer class=\"report-footer\">\n"
         f"  <button type=\"button\" data-action=\"export-user-response\">Export user response</button>\n"
@@ -202,6 +247,7 @@ def render_html(
     css: str,
     js: str,
     approval_ctx: PlanApprovalContext | None = None,
+    reader_ctx: ReaderDashboardContext | None = None,
 ) -> str:
     """Return a single self-contained HTML document for ``src_md``.
 
@@ -213,6 +259,7 @@ def render_html(
         src_md,
         run_meta=run_meta,
         approval_ctx=approval_ctx,
+        reader_ctx=reader_ctx,
     )
     return render_report_view_model(model, css=css, js=js)
 
@@ -948,6 +995,17 @@ class PlanApprovalContext:
     blocker_ids: tuple[str, ...]
 
 
+def _load_report_data(src_md_path: Path) -> dict | None:
+    data_path = final_report_data_path(src_md_path)
+    if not data_path.is_file():
+        return None
+    try:
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
 def plan_approval_context(
     src_md_path: Path, src_text: str
 ) -> PlanApprovalContext | None:
@@ -957,12 +1015,8 @@ def plan_approval_context(
     validator 가 같은 판정을 공유한다. recommendedOption 이 비거나 후보에 없으면
     첫 후보로 폴백한다 — 항상 정확히 한 옵션이 selected 가 되어 브라우저 자동선택분의
     묵시 Export 를 차단한다."""
-    data_path = final_report_data_path(src_md_path)
-    if not data_path.is_file():
-        return None
-    try:
-        data = json.loads(data_path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
+    data = _load_report_data(src_md_path)
+    if data is None:
         return None
     planning = data.get("implementationPlanning")
     if not isinstance(planning, dict):
@@ -994,6 +1048,83 @@ def plan_approval_context(
     )
 
 
+def reader_dashboard_context(
+    src_md_path: Path,
+    src_text: str,
+    approval_ctx: PlanApprovalContext | None,
+) -> ReaderDashboardContext | None:
+    data = _load_report_data(src_md_path)
+    if data is None:
+        return None
+    reader = data.get("readerSummary")
+    if not isinstance(reader, dict):
+        reader = {}
+    verdict = data.get("verdictCard")
+    if not isinstance(verdict, dict):
+        verdict = {}
+    clarifications = parse_clarification_items(src_text) or []
+    open_count = sum(
+        1 for item in clarifications
+        if re.fullmatch(r"C-\d+", item.row_id) and item.status in UNRESOLVED_STATUSES
+    )
+    recommended_option = ""
+    planning = data.get("implementationPlanning")
+    if isinstance(planning, dict):
+        rec = planning.get("recommendedOption")
+        recommended_option = rec.get("name") or "" if isinstance(rec, dict) else ""
+        if approval_ctx is not None:
+            recommended_option = approval_ctx.recommended_option
+    return ReaderDashboardContext(
+        decision=_reader_text(reader.get("decision")) or _reader_text(verdict.get("finalConclusion")),
+        human_action_required=(
+            _reader_text(reader.get("humanActionRequired"))
+            or _reader_text(verdict.get("nextStep"))
+            or "Review the report sections below."
+        ),
+        blocking_items=(
+            _reader_text(reader.get("blockingItems"))
+            or _fallback_blocking_items(open_count, approval_ctx)
+        ),
+        safe_to_skip=(
+            _reader_text(reader.get("safeToSkip"))
+            or "Audit sections can wait until a deeper review."
+        ),
+        recommended_command=(
+            _reader_text(reader.get("recommendedCommand"))
+            or _reader_text(verdict.get("nextStep"))
+        ),
+        open_clarifications=open_count,
+        approval=_approval_label(data, approval_ctx),
+        recommended_option=recommended_option,
+    )
+
+
+def _reader_text(value: object) -> str:
+    return value.strip() if isinstance(value, str) else ""
+
+
+def _fallback_blocking_items(
+    open_count: int, approval_ctx: PlanApprovalContext | None
+) -> str:
+    if approval_ctx is not None and approval_ctx.blocker_ids:
+        return ", ".join(approval_ctx.blocker_ids)
+    if open_count:
+        return f"{open_count} open clarification item(s)."
+    return "No open clarification items."
+
+
+def _approval_label(data: dict, approval_ctx: PlanApprovalContext | None) -> str:
+    frontmatter = data.get("frontmatter")
+    approved = frontmatter.get("approved") if isinstance(frontmatter, dict) else False
+    if approved is True:
+        return "approved"
+    if approval_ctx is not None:
+        return "blocked" if approval_ctx.disabled_reason else "ready"
+    verdict = data.get("verdictCard")
+    required = verdict.get("approvalRequired") if isinstance(verdict, dict) else False
+    return "required" if required else "not required"
+
+
 def _resolve_recommended_option(rec_name: str, names: tuple[str, ...]) -> str:
     """``recommendedOption.name`` 을 후보 이름에 맞춘다. 정확 일치가 없으면
     접두 일치(후보가 ``(RECOMMENDED)`` 같은 표식 접미를 더 달고 있는 흔한 경우)를
@@ -1095,15 +1226,23 @@ def render_html_view(
             "the HTML view."
         )
     approval_ctx = plan_approval_context(src_md_path, src_text)
-    if not report_has_clarification_items(src_text) and approval_ctx is None:
+    reader_ctx = reader_dashboard_context(src_md_path, src_text, approval_ctx)
+    has_clarifications = report_has_clarification_items(src_text)
+    if not has_clarifications and approval_ctx is None and reader_ctx is None:
         if html_path.is_file():
             html_path.unlink()
         return None
     html_text = render_html(
-        src_text, run_meta=run_meta, css=css, js=js, approval_ctx=approval_ctx
+        src_text,
+        run_meta=run_meta,
+        css=css,
+        js=js,
+        approval_ctx=approval_ctx,
+        reader_ctx=reader_ctx,
     )
     html_path.write_text(html_text, encoding="utf-8")
-    # 사용자 확인(폼/승인)이 필요한 보고서 — Export 파일의 저장 위치를 미리
-    # 만들어 사용자가 디렉토리를 만들 필요가 없게 한다 (reports/ 의 sibling).
-    user_responses_dir_for_report(src_md_path).mkdir(parents=True, exist_ok=True)
+    if has_clarifications or approval_ctx is not None:
+        # 사용자 확인(폼/승인)이 필요한 보고서 — Export 파일의 저장 위치를 미리
+        # 만들어 사용자가 디렉토리를 만들 필요가 없게 한다 (reports/ 의 sibling).
+        user_responses_dir_for_report(src_md_path).mkdir(parents=True, exist_ok=True)
     return html_path

package/runtime/python/okstra_ctl/run.py

@@ -1412,7 +1412,7 @@ def _resolve_model_bindings(inp: PrepareInputs, workers: list[str]) -> _ModelBin
     )
 
 
-StageSelection = _implementation_stage.StageSelection
+StageRunClaim = _implementation_stage.StageRunClaim
 
 
 def _implementation_stage_prepare_error(
@@ -1421,17 +1421,17 @@ def _implementation_stage_prepare_error(
     return PrepareError(str(exc))
 
 
-def _select_and_provision_implementation_stage(
+def _claim_implementation_stage_run(
     inp: PrepareInputs,
     ctx_stage_map: list,
     task_group_segment: str,
     task_id_segment: str,
     task_key: str,
     executor_worktree_status: str,
-) -> StageSelection:
-    """Compatibility wrapper for implementation stage selection."""
+) -> StageRunClaim:
+    """Compatibility wrapper for claiming an implementation stage run."""
     try:
-        return _implementation_stage.select_and_provision_implementation_stage(
+        return _implementation_stage.claim_implementation_stage_run(
             inp,
             ctx_stage_map,
             task_group_segment,
@@ -1443,14 +1443,14 @@ def _select_and_provision_implementation_stage(
         raise _implementation_stage_prepare_error(exc) from exc
 
 
-def _apply_implementation_stage(
+def _publish_stage_run_claim(
     inp: PrepareInputs,
     ctx: dict,
     ctx_stage_map: list,
-    sel: StageSelection,
+    claim: StageRunClaim,
 ) -> None:
-    """Compatibility wrapper for publishing implementation stage selection."""
-    _implementation_stage.apply_implementation_stage(inp, ctx, ctx_stage_map, sel)
+    """Compatibility wrapper for publishing a Stage Run Claim."""
+    _implementation_stage.publish_stage_run_claim(inp, ctx, ctx_stage_map, claim)
 
 
 def _git_out(cwd, *args) -> str:
@@ -1898,7 +1898,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     # Identity segments derived with the SAME slugify rule compute_run_paths
     # uses, so they match ctx["TASK_GROUP_SEGMENT"]/["TASK_ID_SEGMENT"]
     # byte-for-byte. We need them BEFORE run-path compute because
-    # implementation stage selection depends on the task-worktree degrade
+    # implementation Stage Run Claim depends on the task-worktree degrade
     # status, and the run path itself is stage-namespaced.
     task_group_segment = slugify(inp.task_group)
     task_id_segment = slugify(inp.task_id)
@@ -1908,7 +1908,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     # One worktree per task-key: requirements-discovery, error-analysis,
     # implementation-planning and implementation phases of the same task
     # all share this directory and branch. Runs BEFORE run-path compute: its
-    # degrade status (skipped-*) feeds implementation stage selection, and
+    # degrade status (skipped-*) feeds implementation Stage Run Claim, and
     # the resolved stage namespaces the run path.
     #
     # The whole check→select→`git worktree add`→reserve sequence (task
@@ -1944,26 +1944,26 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
                     f"task worktree provisioning failed: {exc}"
                 ) from exc
 
-        # ---- implementation stage selection (path-independent) ----
+        # ---- implementation Stage Run Claim (path-independent) ----
         # Resolve + provision the stage BEFORE run-path compute so RUN_DIR
         # lands in runs/implementation/stage-<N>. The registry stage-key is
         # reserved exactly once here (inside provision_stage_worktree), and
-        # the surrounding mutex makes the registry read in stage selection
-        # and that reserve atomic. Other task-types skip this selection;
+        # the surrounding mutex makes the registry read in the claim
+        # and that reserve atomic. Other task-types skip this claim;
         # single-stage final-verification threads its explicit stage via
         # fv_stage_arg, everything else keeps stage_arg=None (flat paths).
         if inp.task_type == "implementation":
-            impl_stage_selection = _select_and_provision_implementation_stage(
+            stage_run_claim = _claim_implementation_stage_run(
                 inp, ctx_stage_map, task_group_segment, task_id_segment,
                 task_key, worktree.status,
             )
-            stage_arg = impl_stage_selection.stage
+            stage_arg = stage_run_claim.stage
             # Drop any stale waiver on this stage so the run actually verifies
             # conformance (kept inside the per-task-key mutex so concurrent
             # same-task runs don't race the manifest write).
-            _clear_stale_stage_waiver(inp, project_root, impl_stage_selection.stage)
+            _clear_stale_stage_waiver(inp, project_root, stage_run_claim.stage)
         else:
-            impl_stage_selection = None
+            stage_run_claim = None
             stage_arg = fv_stage_arg
 
     ctx = compute_and_write_run_context(
@@ -1988,13 +1988,13 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         ),
     })
 
-    # implementation: override the task-worktree fields with the resolved
-    # STAGE worktree and append the consumers.jsonl started row. Must run
+    # implementation: override the task-worktree fields with the claimed
+    # STAGE worktree. Must run
     # AFTER the task-worktree fields above (mirrors the original ordering
     # where stage reservation overrode them post task-provision).
     if inp.task_type == "implementation":
-        _apply_implementation_stage(
-            inp, ctx, ctx_stage_map, impl_stage_selection,
+        _publish_stage_run_claim(
+            inp, ctx, ctx_stage_map, stage_run_claim,
         )
 
     if inp.render_only:
@@ -2166,10 +2166,10 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         _provision_settings_symlink(inp)
 
     concurrent_run: dict = {}
-    if impl_stage_selection is not None and impl_stage_selection.concurrent_stages:
+    if stage_run_claim is not None and stage_run_claim.concurrent_stages:
         concurrent_run = {
             "detected": True,
-            "active_stages": impl_stage_selection.concurrent_stages,
+            "active_stages": stage_run_claim.concurrent_stages,
         }
     return PrepareOutputs(
         ctx=ctx,

package/runtime/python/okstra_ctl/worktree.py

@@ -881,7 +881,7 @@ def provision_stage_worktree(
     before re-raising so a retry is not blocked.
 
     Concurrency: callers must hold ``locks.worktree_provision_mutex`` for
-    the task-key, acquired BEFORE stage selection reads the registry
+    the task-key, acquired BEFORE the Stage Run Claim reads the registry
     (run.py does) — otherwise two `--stage auto` runs can select the same
     stage and the loser silently enters the winner's worktree via the
     "reused" path. flock is non-reentrant, hence the lock lives at the