okstra 0.113.0 → 0.115.0

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/wizard.py

@@ -209,7 +209,7 @@ def _brief_suggestions(path: Path) -> tuple[str, str]:
 
     - ``task_group`` ← frontmatter ``task-group``.
     - ``task_id``    ← frontmatter ``brief-id`` (which matches the
-                       filename stem in okstra-brief output and is the
+                       filename stem in okstra-brief-gen output and is the
                        strongest single identifier of the task).
 
     A brief without frontmatter, or with placeholder values, yields two
@@ -1261,9 +1261,9 @@ def _recently_used_brief_times(state: WizardState) -> dict[str, float]:
 
 
 def _suggest_group_briefs(state: WizardState, limit: int = 6) -> list[str]:
-    """Return recent okstra-brief outputs for the selected task-group.
+    """Return recent okstra-brief-gen outputs for the selected task-group.
 
-    ``okstra-brief`` writes to ``.okstra/briefs/<task-group>/**/*.md``. The
+    ``okstra-brief-gen`` writes to ``.okstra/briefs/<task-group>/**/*.md``. The
     wizard exposes those paths after task-group selection so users can pick a
     generated brief instead of typing its path. Paths are project-relative.
     """

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

package/runtime/python/okstra_token_usage/claude.py

@@ -83,6 +83,28 @@ def _session_meta_from_record(rec: dict) -> tuple[str | None, str | None]:
     return agent, model
 
 
+_SUBAGENT_FILENAME_RE = re.compile(r"^agent-a(?P<agent>.+)-[0-9a-f]{8,}$")
+
+
+def _agent_name_from_subagent_path(jsonl_path: Path) -> str | None:
+    if jsonl_path.parent.name != "subagents":
+        return None
+    match = _SUBAGENT_FILENAME_RE.match(jsonl_path.stem)
+    return match.group("agent") if match else None
+
+
+def _iter_claude_session_jsonls(
+    proj_dir: Path,
+    subagent_parent_sids: list[str] | None = None,
+):
+    yield from sorted(proj_dir.glob("*.jsonl"))
+    if subagent_parent_sids is None:
+        yield from sorted(proj_dir.glob("*/subagents/*.jsonl"))
+        return
+    for sid in sorted({sid for sid in subagent_parent_sids if sid}):
+        yield from sorted((proj_dir / sid / "subagents").glob("*.jsonl"))
+
+
 def _advance_usage_scan(jsonl_path: Path, usage_state: dict) -> dict:
     """`usage_state['offset']` 이후의 완결 라인을 읽어 이벤트를 커밋하고,
     개행 없는 마지막 라인은 transient 로만 반영한 view 를 돌려준다.
@@ -230,7 +252,8 @@ def claude_session_totals(
         save_cache(jsonl_path, cache)
     else:
         view = _advance_usage_scan(jsonl_path, fresh_cache()["usage"])
-    return _totals_from_events(view["events"], view["agentName"],
+    agent_name = view["agentName"] or _agent_name_from_subagent_path(jsonl_path)
+    return _totals_from_events(view["events"], agent_name,
                                view["model"], since, until)
 
 
@@ -312,7 +335,7 @@ def find_claude_team_sessions(
     if not proj_dir.is_dir():
         return out
     needles_lower = [f'"teamname":"{n.lower()}"' for n in team_needles if n]
-    for p in proj_dir.glob("*.jsonl"):
+    for p in _iter_claude_session_jsonls(proj_dir):
         for needle_lower in needles_lower:
             if incremental:
                 cache = load_cache(p)
@@ -333,26 +356,33 @@ def find_claude_team_sessions(
 _TEAM_TAG_NEEDLE = '"teamname":"'
 
 
+def _agent_name_matches(agent_name: str | None, prefixes: list[str]) -> bool:
+    if not agent_name:
+        return False
+    for prefix in prefixes:
+        if agent_name == prefix or agent_name.startswith(f"{prefix}-"):
+            return True
+    return False
+
+
 def find_claude_agent_sessions(
     cwd: Path,
     agent_prefixes: list[str],
     projects_root: Path | None = None,
     *,
     incremental: bool = False,
+    subagent_parent_sids: list[str] | None = None,
 ) -> dict[str, Path]:
-    """Map sessionId -> jsonl path for non-team sessions whose recorded
-    `agentName` matches one of ``agent_prefixes``.
-
-    no-team run(teamCreate `skipped`(concurrent-run) / `error` fallback)의
-    worker 세션은 team 태그가 없어 teamName needle 로는 발견되지 않는다. 대신
-    하네스가 dispatch `name` 인자로 기록하는 `agentName` 을 needle 로 찾되,
-    team 태그가 있는 세션은 제외한다 — 그것은 동시 team-mode run 의 worker 다.
-
-    같은 agentName 을 쓰는 다른 run 의 세션도 걸릴 수 있으므로, 호출자는 반드시
-    run 윈도우로 totals 를 스코핑하고 in-window 이벤트가 없는 세션을 버려야
-    한다. 윈도우가 겹치는 두 no-team run 이 같은 role 을 dispatch 한 경우의
-    교차 귀속은 구조적으로 분리 불가 — usage 블록의 sessionId 목록으로만
-    추적 가능하다.
+    """Map worker-like Claude jsonls by agent name or nested subagent filename.
+
+    Legacy top-level worker jsonls record `agentName` in the JSONL body. Newer
+    in-process subagents can instead live under
+    `<lead-session>/subagents/agent-a<name>-<hash>.jsonl` with no body
+    `agentName`, so this finder also matches that filename form.
+
+    Callers can pass `subagent_parent_sids` to limit nested subagents to the
+    current lead session directory. Top-level fallback discovery remains broad
+    and must still be filtered by the run window after totals are read.
     """
     proj_dir = claude_project_dir(cwd, projects_root)
     out: dict[str, Path] = {}
@@ -361,20 +391,29 @@ def find_claude_agent_sessions(
     agent_needles = [f'"agentname":"{p.lower()}' for p in agent_prefixes if p]
     if not agent_needles:
         return out
-    for p in proj_dir.glob("*.jsonl"):
+    for p in _iter_claude_session_jsonls(proj_dir, subagent_parent_sids):
+        path_agent = _agent_name_from_subagent_path(p)
+        filename_matched = _agent_name_matches(path_agent, agent_prefixes)
+        scoped_subagent = (
+            filename_matched
+            and path_agent is not None
+            and subagent_parent_sids is not None
+        )
         if incremental:
             cache = load_cache(p)
-            matched = any(_cached_needle_scan(p, cache, n) for n in agent_needles)
+            matched = filename_matched or any(
+                _cached_needle_scan(p, cache, n) for n in agent_needles
+            )
             team_tagged = matched and _cached_needle_scan(p, cache, _TEAM_TAG_NEEDLE)
             save_cache(p, cache)
         else:
-            matched = any(
+            matched = filename_matched or any(
                 _needle_scan(p, {"offset": 0, "found": False}, n)
                 for n in agent_needles
             )
             team_tagged = matched and _needle_scan(
                 p, {"offset": 0, "found": False}, _TEAM_TAG_NEEDLE
             )
-        if matched and not team_tagged:
+        if matched and (scoped_subagent or not team_tagged):
             out[p.stem] = p
     return out

package/runtime/python/okstra_token_usage/collect.py

@@ -653,8 +653,10 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
             for w in state.get("workers", [])
             for prefix in match_prefixes(w.get("workerId") or "")
         ]
+        subagent_parent_sids = [lead_sid] if lead_sid else []
         agent_sessions = find_claude_agent_sessions(
-            cwd, worker_prefix_pool, incremental=incremental
+            cwd, worker_prefix_pool, incremental=incremental,
+            subagent_parent_sids=subagent_parent_sids,
         )
         for sid, path in agent_sessions.items():
             if sid == lead_sid or sid in claude_sessions:

package/runtime/python/okstra_vendor/__init__.py

@@ -12,6 +12,9 @@ Currently vendored:
     (`_speedups.c` / `_speedups.pyi`) is stripped; the pure-python
     `_native` fallback is used at import time.
   - networkx (BSD-3-Clause) — graph model + community detection for okstra-graphify.
+    Per-package `tests/` suites and the top-level `conftest.py` are stripped;
+    okstra never runs networkx's own test suite. On re-vendor, drop every
+    `**/tests/` directory and `conftest.py` again.
   - graphify 0.4.23 (MIT) — knowledge-graph pipeline for okstra-graphify. tree-sitter
     native bindings are NOT vendored; okstra-graphify only indexes .okstra/ docs.
 

package/runtime/schemas/final-report-v1.0.schema.json

@@ -154,6 +154,26 @@
       }
     },
 
+    "readerSummary": {
+      "type": "object",
+      "description": "Optional reader-first summary rendered near the top of the Markdown report and reused by the HTML reader dashboard. Existing v1.0 data.json files may omit it; new report-writer output should populate it to keep the first-read path short.",
+      "required": [
+        "decision",
+        "humanActionRequired",
+        "blockingItems",
+        "safeToSkip",
+        "recommendedCommand"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "decision": { "type": "string", "minLength": 1 },
+        "humanActionRequired": { "type": "string", "minLength": 1 },
+        "blockingItems": { "type": "string", "minLength": 1 },
+        "safeToSkip": { "type": "string", "minLength": 1 },
+        "recommendedCommand": { "type": "string", "minLength": 1 }
+      }
+    },
+
     "rationale": {
       "type": "object",
       "description": "## 작업 배경과 근거 — reviewer-facing narrative answering the four questions in order. Each field is prose (not a table) and MUST carry at least one evidence reference (path:line, a report ID such as C-001/F-013/§5.4, or another cited source) OR an explicit insufficiency marker (e.g. '근거 불충분'). validate-run.py fails a field with neither. Required for every task-type.",

package/runtime/skills/{okstra-brief → okstra-brief-gen}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: okstra-brief
+name: okstra-brief-gen
 description: Use when the user wants to generate a task brief file for okstra from a requirements document, an existing markdown file, an issue-tracker ticket (Linear / Jira / GitHub / Notion), a link URL, conversation context, or short user input. Produces the markdown brief consumed by `okstra-run` Step 5 (task-brief). Trigger words include "okstra brief", "make a brief", "brief 생성", "요구사항 brief 만들어", "okstra 입력 만들어", "task brief 작성", "이 티켓으로 brief", "이 링크로 brief".
 ---
 
-# okstra-brief
+# okstra-brief-gen
 
 Generate a single `task brief` markdown file under the okstra project domain
 (`.okstra/briefs/<task-group>/<task-id>.md`) so it can be fed to
@@ -41,21 +41,21 @@ cross-verification and would conflict with anything decided here.
 ## Intended chain
 
 ```
-okstra-brief (reporter-input variant)
+okstra-brief-gen (reporter-input variant)
   → okstra-run (requirements-discovery | error-analysis)
     → okstra-run (implementation-planning)
       → okstra-run (implementation)
         → okstra-run (final-verification)
           → okstra-run (release-handoff)
 
-okstra-brief (codebase-scan variant)
+okstra-brief-gen (codebase-scan variant)
   → okstra-run (improvement-discovery)
     → okstra-run (implementation-planning)
       → okstra-run (implementation)
         → okstra-run (final-verification)
           → okstra-run (release-handoff)
 
-okstra-brief (error-feedback variant)
+okstra-brief-gen (error-feedback variant)
   → okstra-run (error-analysis)
     → okstra-run (implementation-planning)
       → okstra-run (implementation)
@@ -737,7 +737,7 @@ The installed template `~/.okstra/templates/reports/brief.template.md` is the by
   notion | url | user-input`).
 - `task-group` echoes the Step 2a value.
 - `created` is the brief's creation date (`YYYY-MM-DD`).
-- `generator: okstra-brief` is a fixed value.
+- `generator: okstra-brief-gen` is a fixed value.
 - `reporter-confirmations` is set by Step 6.5 (`complete | partial | pending |
   skipped`).
 - `scope` is `codebase` for the codebase-scan variant; omit it (⇒

package/runtime/skills/{okstra-brief → okstra-brief-gen}/references/reporter-confirmations.md

@@ -18,7 +18,7 @@ rows, sort by priority and ask only the top 12 this round:
 
 Any rows beyond the cap are left unanswered in this run; set
 `reporter-confirmations: partial` in the frontmatter and tell the user which
-rows remain. The next `okstra-brief` re-run (or the downstream phase that
+rows remain. The next `okstra-brief-gen` re-run (or the downstream phase that
 consumes `Blocks=next-phase`) handles the remainder.
 
 Each question carries:

package/runtime/skills/{okstra-brief → okstra-brief-gen}/references/tracker-recursion.md

@@ -1,7 +1,7 @@
 # Sub-ticket / child-issue recursion (tracker sources)
 
 Read this only when a fetched tracker ticket shows one or more child references
-(okstra-brief Step 1b sub-step 6). It defines how the child tree is discovered,
+(okstra-brief-gen Step 1b sub-step 6). It defines how the child tree is discovered,
 which briefs are emitted, and how re-runs stay idempotent.
 
 ## 1. Discover child references per tracker