okstra 0.102.2 → 0.102.3

package/runtime/python/okstra_ctl/codex_dispatch.py

@@ -18,6 +18,10 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Mapping, Sequence
 
+from .final_report_paths import (
+    final_report_data_path as _final_report_data_path,
+    final_report_markdown_path as _final_report_markdown_path,
+)
 from .lead_events import LeadEvent, append_lead_event
 from .wrapper_status import status_path_for_prompt
 from .paths import task_dir
@@ -1450,18 +1454,6 @@ def _failure_reason(exit_code: int, missing_paths: Sequence[Path]) -> str:
     return "worker dispatch failed"
 
 
-def _final_report_data_path(markdown_path: Path) -> Path:
-    if markdown_path.name.endswith(".md"):
-        return markdown_path.with_name(markdown_path.name[:-3] + ".data.json")
-    return markdown_path.with_suffix(".data.json")
-
-
-def _final_report_markdown_path(data_json_path: Path) -> Path:
-    if data_json_path.name.endswith(".data.json"):
-        return data_json_path.with_name(data_json_path.name[:-10] + ".md")
-    return data_json_path.with_suffix(".md")
-
-
 def _replace_report_writer_model_line(
     prompt_path: Path,
     model_execution_value: str,

package/runtime/python/okstra_ctl/consumers.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import json
 import re
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
@@ -17,6 +18,17 @@ from .run_context import consumers_mutex
 CONSUMERS_FILENAME = "consumers.jsonl"
 
 
+@dataclass(frozen=True)
+class StageConsumerState:
+    rows: List[Dict[str, Any]]
+    done_rows: List[Dict[str, Any]]
+    done_by_stage: Dict[int, Dict[str, Any]]
+    done_stages: set[int]
+    started_stages: set[int]
+    verified_accepted_stages: set[int]
+    pr_covered_stages: set[int]
+
+
 def _path(plan_run_root: Path) -> Path:
     return plan_run_root / CONSUMERS_FILENAME
 
@@ -50,6 +62,29 @@ def latest_done_by_stage(rows: List[Dict[str, Any]]) -> Dict[int, Dict[str, Any]
     return out
 
 
+def read_stage_consumer_state(
+    plan_run_root: Path, *, recover_from_carry: bool = False,
+) -> StageConsumerState:
+    if recover_from_carry:
+        backfill_done_from_carry(plan_run_root)
+    rows = read_consumers(plan_run_root)
+    done_rows = [r for r in rows if r.get("status") == "done"]
+    done_by_stage = latest_done_by_stage(rows)
+    started = {
+        r["stage"] for r in rows
+        if r.get("status") == "started" and isinstance(r.get("stage"), int)
+    }
+    return StageConsumerState(
+        rows=rows,
+        done_rows=done_rows,
+        done_by_stage=done_by_stage,
+        done_stages=set(done_by_stage.keys()),
+        started_stages=started,
+        verified_accepted_stages=verified_accepted_stages(rows),
+        pr_covered_stages=pr_covered_stages(rows),
+    )
+
+
 def append_consumer(plan_run_root: Path, *, impl_task_key: str, stage: int,
                     status: str, force_reappend: bool = False,
                     **fields: Any) -> None:

package/runtime/python/okstra_ctl/container.py

@@ -506,7 +506,7 @@ def _split_task_key(task_key: str) -> tuple[str, str, str]:
 def _resolve_up_inputs(project_root: Path, task_key: str) -> dict:
     """task-key 로 up 에 필요한 입력(worktree/stage_map/done_rows/anchor)을 모은다."""
     from . import worktree_registry as _reg
-    from .consumers import read_consumers, backfill_done_from_carry
+    from .consumers import read_stage_consumer_state
     from .plan_run_root import resolve_plan_run_root_by_task_key
 
     project_id, group, task_id = _split_task_key(task_key)
@@ -517,11 +517,9 @@ def _resolve_up_inputs(project_root: Path, task_key: str) -> dict:
             "없습니다. 먼저 해당 task 의 phase 를 한 번 실행해 worktree 를 만드세요.")
     plan = resolve_plan_run_root_by_task_key(
         project_root=project_root, task_group=group, task_id=task_id)
-    # carry sidecar 가 stage 완료의 SSOT 다 — final-verification 과 동일하게 누락된
-    # done 행을 carry 에서 복구한 뒤 읽어, 두 경로가 같은 디스크 상태에서 갈라지지
-    # 않게 한다(crash/부분쓰기로 consumers.jsonl done 행만 유실된 경우 대비).
-    backfill_done_from_carry(plan.run_root)
-    done_rows = [r for r in read_consumers(plan.run_root) if r.get("status") == "done"]
+    done_rows = read_stage_consumer_state(
+        plan.run_root, recover_from_carry=True,
+    ).done_rows
     stage_map = _plan_stage_map(plan.approved_plan_path)
     anchor = _reg.get_implementation_base(project_id, group, task_id) or ""
     return {

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -11,6 +11,10 @@ from pathlib import Path
 from typing import Any, Mapping, Sequence
 
 from . import tmux
+from .final_report_paths import (
+    final_report_data_path as _final_report_data_path,
+    final_report_markdown_path as _final_report_markdown_path,
+)
 from .lead_events import LeadEvent, append_lead_event
 from .worker_prompt_headers import WorkerPromptHeaderError, worker_prompt_headers
 from .wrapper_status import read_wrapper_status, status_path_for_prompt
@@ -823,18 +827,6 @@ def _completion_paths(worker_id: str, result_path: Path, manifest: Mapping[str,
     return (data_json, _final_report_markdown_path(data_json), result_path)
 
 
-def _final_report_data_path(markdown_path: Path) -> Path:
-    if markdown_path.name.endswith(".md"):
-        return markdown_path.with_name(markdown_path.name[:-3] + ".data.json")
-    return markdown_path.with_suffix(".data.json")
-
-
-def _final_report_markdown_path(data_json_path: Path) -> Path:
-    if data_json_path.name.endswith(".data.json"):
-        return data_json_path.with_name(data_json_path.name[:-10] + ".md")
-    return data_json_path.with_suffix(".md")
-
-
 def _run_dir(plan: DispatchPlan) -> Path:
     value = _string_value(plan.manifest.get("runDirectoryPath"))
     return _resolve_project_path(plan.project_root, value) if value else plan.team_state_path.parent.parent

package/runtime/python/okstra_ctl/final_report_paths.py

@@ -0,0 +1,24 @@
+"""Path helpers for the final-report markdown/data.json pair."""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+DATA_JSON_SUFFIX = ".data.json"
+MARKDOWN_SUFFIX = ".md"
+
+
+def final_report_data_path(report_path: Path) -> Path:
+    """Return the data.json sibling for a final-report markdown path."""
+    name = report_path.name
+    if name.endswith(MARKDOWN_SUFFIX):
+        return report_path.with_name(name[: -len(MARKDOWN_SUFFIX)] + DATA_JSON_SUFFIX)
+    return report_path.with_suffix(DATA_JSON_SUFFIX)
+
+
+def final_report_markdown_path(data_path: Path) -> Path:
+    """Return the markdown sibling for a final-report data.json path."""
+    name = data_path.name
+    if name.endswith(DATA_JSON_SUFFIX):
+        return data_path.with_name(name[: -len(DATA_JSON_SUFFIX)] + MARKDOWN_SUFFIX)
+    return data_path.with_suffix(MARKDOWN_SUFFIX)

package/runtime/python/okstra_ctl/handoff.py

@@ -13,6 +13,7 @@ from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Tuple
 
 from . import consumers, worktree_registry
+from .final_report_paths import final_report_markdown_path
 from .worktree import (compute_branch_name, compute_worktree_path,
                        main_worktree_path, is_dirty_excluding_okstra,
                        nested_worktree_excludes, is_ancestor, merge_branch,
@@ -91,7 +92,7 @@ def latest_whole_task_fv_accepted(project_root, project_id: str,
         if ((data.get("header") or {}).get("taskType") == "final-verification"
                 and data.get("verificationScope") == "whole-task"
                 and token == "accepted"):
-            md = dj.with_name(dj.name[:-len(".data.json")] + ".md")
+            md = final_report_markdown_path(dj)
             return str(md if md.is_file() else dj)
     return ""
 

package/runtime/python/okstra_ctl/implementation_stage.py

@@ -66,16 +66,14 @@ def select_and_provision_implementation_stage(
     """
     del task_key  # The registry uses the split identity fields.
 
-    from .consumers import read_consumers, backfill_done_from_carry
+    from .consumers import backfill_done_from_carry, read_stage_consumer_state
     from . import worktree as _worktree
     from . import worktree_registry as _reg
 
     plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
     backfill_done_from_carry(plan_run_root)
     auto_reconcile_best_effort(inp, plan_run_root)
-    consumed = read_consumers(plan_run_root)
-    done_stages = {r["stage"] for r in consumed if r.get("status") == "done"}
-    started_stages = {r["stage"] for r in consumed if r.get("status") == "started"}
+    consumers = read_stage_consumer_state(plan_run_root)
     reserved_stages = _reg.list_active_stage_numbers(
         inp.project_id,
         inp.task_group,
@@ -83,18 +81,17 @@ def select_and_provision_implementation_stage(
     )
 
     try:
-        batch = stage_targets.resolve_effective_stages(
+        selected = stage_targets.resolve_implementation_stage(
             ctx_stage_map,
-            done_stages,
+            consumers.done_stages,
             inp.stage,
-            started_stages=started_stages,
+            started_stages=consumers.started_stages,
             reserved_stages=reserved_stages,
         )
     except stage_targets.StageTargetError as exc:
         raise _as_implementation_stage_error(exc) from exc
 
-    selected = batch[0]
-    concurrent_stages = sorted(reserved_stages - done_stages - {selected})
+    concurrent_stages = sorted(reserved_stages - consumers.done_stages - {selected})
 
     if executor_worktree_status.startswith("skipped"):
         head = _git_out(inp.project_root, "rev-parse", "HEAD")
@@ -133,11 +130,10 @@ def select_and_provision_implementation_stage(
     selected_stage = next(
         s for s in ctx_stage_map if s["stage_number"] == selected
     )
-    consumer_done_rows = [r for r in consumed if r.get("status") == "done"]
     try:
         stage_base = stage_targets.resolve_stage_base_commit(
             selected_stage,
-            consumer_done_rows,
+            consumers.done_rows,
             anchor_base_commit=anchor,
             candidate_base=head_sha,
             project_root=Path(task_worktree_path),

package/runtime/python/okstra_ctl/report_view_artifacts.py

@@ -0,0 +1,14 @@
+"""Path helpers for generated final-report view artifacts."""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def html_view_path(report_path: Path) -> Path:
+    """Return the self-contained HTML view path for a final-report markdown."""
+    return report_path.with_suffix(".html")
+
+
+def user_responses_dir_for_report(report_path: Path) -> Path:
+    """Return the sidecar directory used by the report's exported responses."""
+    return report_path.parent.parent / "user-responses"

package/runtime/python/okstra_ctl/report_views.py

@@ -28,6 +28,9 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Iterable, Optional
 
+from .final_report_paths import final_report_data_path
+from .report_view_artifacts import html_view_path, user_responses_dir_for_report
+
 
 def source_digest(src_md: str) -> str:
     """Stable identifier for a final-report markdown body. The HTML
@@ -904,7 +907,7 @@ def plan_approval_context(
     validator 가 같은 판정을 공유한다. recommendedOption 이 비거나 후보에 없으면
     첫 후보로 폴백한다 — 항상 정확히 한 옵션이 selected 가 되어 브라우저 자동선택분의
     묵시 Export 를 차단한다."""
-    data_path = src_md_path.with_name(src_md_path.stem + ".data.json")
+    data_path = final_report_data_path(src_md_path)
     if not data_path.is_file():
         return None
     try:
@@ -1020,14 +1023,14 @@ def render_html_view(
     css: str,
     js: str,
 ) -> Path | None:
-    """Write ``<stem>.html`` next to ``src_md_path`` and return its path,
+    """Write the HTML view artifact for ``src_md_path`` and return its path,
     or return ``None`` when the report needs no interactive view — §1
     clarification rows 도 없고 Plan Approval 위젯 대상도 아닐 때
     (``report_has_clarification_items`` / ``plan_approval_context``).
     Idempotent — overwrites an existing html sibling, and removes a stale
     one when the report no longer needs a view."""
     src_text = src_md_path.read_text(encoding="utf-8")
-    html_path = src_md_path.with_name(src_md_path.stem + ".html")
+    html_path = html_view_path(src_md_path)
     # Fail-closed on §1 heading drift: when a `## 1. Clarification Items`
     # heading exists but its strict form does not parse,
     # `report_has_clarification_items` returns False (lenient parse), so a
@@ -1052,5 +1055,5 @@ def render_html_view(
     html_path.write_text(html_text, encoding="utf-8")
     # 사용자 확인(폼/승인)이 필요한 보고서 — Export 파일의 저장 위치를 미리
     # 만들어 사용자가 디렉토리를 만들 필요가 없게 한다 (reports/ 의 sibling).
-    (src_md_path.parent.parent / "user-responses").mkdir(parents=True, exist_ok=True)
+    user_responses_dir_for_report(src_md_path).mkdir(parents=True, exist_ok=True)
     return html_path

package/runtime/python/okstra_ctl/run.py

@@ -43,6 +43,7 @@ from .material import (
     resolve_related_tasks,
 )
 from .final_report_schema import load_schema
+from .final_report_paths import final_report_data_path as _final_report_data_path
 from .lead_events import LeadEvent, append_lead_event
 from .lead_runtime import ALLOWED_LEAD_RUNTIMES
 from .models import ModelAssignment, resolve_model_metadata
@@ -146,13 +147,6 @@ def _extract_frontmatter_block(body: str) -> str | None:
     return m.group(1) if m else None
 
 
-def _final_report_data_path(report_path: Path) -> Path:
-    name = report_path.name
-    if name.endswith(".md"):
-        return report_path.with_name(name[:-3] + ".data.json")
-    return report_path.with_suffix(".data.json")
-
-
 def _load_final_report_data_if_present(report_path: Path) -> tuple[Path, dict] | None:
     data_path = _final_report_data_path(report_path)
     if not data_path.is_file():
@@ -1514,7 +1508,7 @@ def _reserve_final_verification_target(
     """final-verification 의 검증 target 을 registry/consumers/git 에서
     해소하고 gate 를 강제한다. 위반 시 PrepareError. 결과를 ctx 의
     VERIFICATION_* 키로 주입한다."""
-    from .consumers import read_consumers, backfill_done_from_carry
+    from .consumers import backfill_done_from_carry, read_stage_consumer_state
     from . import worktree_registry as _reg
 
     plan_run_root = plan_run_root_from_approved_plan(inp.approved_plan_path)
@@ -1522,8 +1516,7 @@ def _reserve_final_verification_target(
     # rows before the whole-task gate checks every stage.
     backfill_done_from_carry(plan_run_root)
     _auto_reconcile_best_effort(inp, plan_run_root)
-    done_rows = [r for r in read_consumers(plan_run_root)
-                 if r.get("status") == "done"]
+    done_rows = read_stage_consumer_state(plan_run_root).done_rows
 
     if inp.stage and inp.stage != "auto":
         n = int(inp.stage)

package/runtime/python/okstra_ctl/stage_targets.py

@@ -98,6 +98,24 @@ def resolve_effective_stages(
     return batch
 
 
+def resolve_implementation_stage(
+    stages: list[dict[str, Any]],
+    done_stages: set[int],
+    requested: str,
+    *,
+    started_stages: set[int] | None = None,
+    reserved_stages: set[int] | None = None,
+) -> int:
+    """Return the single Stage Map stage selected for one implementation run."""
+    return resolve_effective_stages(
+        stages,
+        done_stages,
+        requested,
+        started_stages=started_stages,
+        reserved_stages=reserved_stages,
+    )[0]
+
+
 def order_stage_closure(
     stages, selected: set[int], done: set[int],
 ) -> list[int]:

package/runtime/python/okstra_ctl/wizard.py

@@ -34,6 +34,7 @@ from okstra_ctl.models import (
     resolve_model_metadata,
 )
 from okstra_ctl.clarification_items import scan_approval_gate, user_response_sidecars
+from okstra_ctl.final_report_paths import final_report_data_path
 from okstra_ctl.pr_template import PrTemplateError, resolve_pr_template_path
 from okstra_ctl.run import (
     APPROVED_FRONTMATTER_PATTERN,
@@ -60,6 +61,12 @@ from okstra_ctl.workers import (
     validate_workers_against_profile,
 )
 from okstra_ctl.workflow import PHASE_SEQUENCE
+from okstra_ctl.wizard_stage_intent import (
+    WHOLE_TASK_STAGE,
+    WizardStageIntentError,
+    resolve_wizard_stage_intent,
+    wizard_stage_confirmation_label,
+)
 from okstra_ctl import fix_cycles, worktree_registry
 from okstra_ctl.worktree import (
     compute_worktree_path,
@@ -607,7 +614,7 @@ def _find_html_approval_sidecar(
 def _validate_sidecar_option(plan_path: Path, option_name: str, errors_t: dict) -> None:
     """sidecar 의 옵션 이름이 plan data.json 의 optionCandidates 에 있는지
     검증한다. 없으면 유효 후보를 나열하며 거부한다 (fail-closed)."""
-    data_path = plan_path.with_name(plan_path.name[: -len(".md")] + ".data.json")
+    data_path = final_report_data_path(plan_path)
     candidates: list[str] = []
     if data_path.is_file():
         try:
@@ -1652,7 +1659,6 @@ _REUSE_LAST_TOKEN = "__reuse_last__"
 _SIBLINGS_TOKEN = "__siblings__"
 _LATEST_REPORT_TOKEN = "__latest_report__"
 _PROJECT_DEFAULT_TOKEN = "__project_default__"
-WHOLE_TASK_STAGE = "__whole_task__"
 ALL_STAGES = "__all_stages__"
 
 
@@ -3488,21 +3494,14 @@ def render_args(state: WizardState) -> dict[str, str]:
         if state.reuse_worktree or state.task_type == "final-verification"
         else state.base_ref
     )
-    chain_stages = ""
-    if state.task_type == "implementation":
-        stage = state.selected_stage or "auto"
-        chain_stages = state.selected_stages or stage
-    elif state.task_type == "final-verification":
-        if state.selected_stage == WHOLE_TASK_STAGE:
-            stage = ""  # prepare 가 빈 stage 를 whole-task 로 해석
-        elif not state.selected_stage or state.selected_stage == "auto":
-            raise WizardError(
-                "final-verification requires an explicit stage number"
-            )
-        else:
-            stage = state.selected_stage
-    else:
-        stage = ""
+    try:
+        stage_intent = resolve_wizard_stage_intent(
+            task_type=state.task_type,
+            selected_stage=state.selected_stage,
+            selected_stages=state.selected_stages,
+        )
+    except WizardStageIntentError as exc:
+        raise WizardError(str(exc)) from exc
     pr_template = (
         state.pr_template_path
         if state.task_type == "release-handoff"
@@ -3518,9 +3517,9 @@ def render_args(state: WizardState) -> dict[str, str]:
         "executor": state.executor,
         "critic": state.critic,
         "approved-plan": state.approved_plan_path,
-        "stage": stage,
+        "stage": stage_intent.stage,
         "stages": state.handoff_stages,
-        "chain-stages": chain_stages,
+        "chain-stages": stage_intent.chain_stages,
         "base-ref": base_ref,
         "workers": workers,
         "directive": state.directive,
@@ -3581,12 +3580,12 @@ def confirmation_block(state: WizardState) -> str:
         lines.append(f"  critic        : {state.critic or '(off)'}")
     if state.task_type in _STAGE_SCOPED_TASK_TYPES:
         lines.append(f"  approved-plan : {state.approved_plan_path}")
-        stage = (
-            _msg(state.workspace_root, "confirmation", "stage_whole_task")
-            if state.selected_stage == WHOLE_TASK_STAGE
-            else (state.selected_stage
-                  or ("auto" if state.task_type == "implementation"
-                      else "(not selected)"))
+        stage = wizard_stage_confirmation_label(
+            task_type=state.task_type,
+            selected_stage=state.selected_stage,
+            whole_task_label=_msg(
+                state.workspace_root, "confirmation", "stage_whole_task"
+            ),
         )
         lines.append(f"  stage         : {stage}")
     if state.clarification_response_path:

package/runtime/python/okstra_ctl/wizard_stage_intent.py

@@ -0,0 +1,54 @@
+"""Stage-related intent projection for okstra-run wizard output."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+WHOLE_TASK_STAGE = "__whole_task__"
+
+
+class WizardStageIntentError(ValueError):
+    """Raised when wizard state cannot produce stage-related render args."""
+
+
+@dataclass(frozen=True)
+class WizardStageIntent:
+    stage: str
+    chain_stages: str
+
+
+def resolve_wizard_stage_intent(
+    *,
+    task_type: str,
+    selected_stage: str,
+    selected_stages: str,
+) -> WizardStageIntent:
+    """Return the stage-related ``okstra render-bundle`` arguments."""
+    if task_type == "implementation":
+        stage = selected_stage or "auto"
+        return WizardStageIntent(stage=stage, chain_stages=selected_stages or stage)
+
+    if task_type == "final-verification":
+        if selected_stage == WHOLE_TASK_STAGE:
+            return WizardStageIntent(stage="", chain_stages="")
+        if not selected_stage or selected_stage == "auto":
+            raise WizardStageIntentError(
+                "final-verification requires an explicit stage number"
+            )
+        return WizardStageIntent(stage=selected_stage, chain_stages="")
+
+    return WizardStageIntent(stage="", chain_stages="")
+
+
+def wizard_stage_confirmation_label(
+    *,
+    task_type: str,
+    selected_stage: str,
+    whole_task_label: str,
+) -> str:
+    """Return the human-readable stage value for the confirmation block."""
+    if selected_stage == WHOLE_TASK_STAGE:
+        return whole_task_label
+    if selected_stage:
+        return selected_stage
+    return "auto" if task_type == "implementation" else "(not selected)"

package/runtime/python/okstra_token_usage/report.py

@@ -14,6 +14,7 @@ _HERE = Path(__file__).resolve().parent.parent
 if str(_HERE) not in sys.path:
     sys.path.insert(0, str(_HERE))
 
+from okstra_ctl.final_report_paths import final_report_markdown_path  # noqa: E402
 from okstra_ctl.render_final_report import (  # noqa: E402
     FinalReportRenderError,
     render_to_file,
@@ -209,11 +210,7 @@ def populate_and_render(
     changes = populate_data_token_cells(data_path, team_state)
 
     if output_path is None:
-        name = data_path.name
-        if name.endswith(".data.json"):
-            output_path = data_path.with_name(name[: -len(".data.json")] + ".md")
-        else:
-            output_path = data_path.with_suffix(".md")
+        output_path = final_report_markdown_path(data_path)
 
     try:
         bytes_written = render_to_file(data_path, output_path)

package/runtime/validators/validate-report-views.py

@@ -38,6 +38,7 @@ from okstra_ctl.report_views import (  # noqa: E402
     plan_approval_context,
     source_digest,
 )
+from okstra_ctl.report_view_artifacts import html_view_path  # noqa: E402
 
 
 _EXTERNAL_URL_RE = re.compile(
@@ -83,7 +84,7 @@ def validate(report_path: Path) -> list[str]:
         return [f"final-report not found: {report_path}"]
 
     md = report_path.read_text(encoding="utf-8")
-    html_path = report_path.with_name(report_path.stem + ".html")
+    html_path = html_view_path(report_path)
     # §1 헤딩이 있는데 파싱이 실패하면 md_ids 가 빈 []이 되어 "clarification 없음
     # → skip" 으로 흘러 HTML form parity 게이트가 조용히 열린다. fail-closed.
     if section_1_present_but_unparsed(md):

package/runtime/validators/validate-run.py

@@ -44,6 +44,7 @@ from okstra_ctl.md_table import (  # noqa: E402
     is_separator_row as _is_markdown_separator,
     split_pipe_row as _split_pipe_row,
 )
+from okstra_ctl.final_report_paths import final_report_data_path as _data_path_for  # noqa: E402
 
 TERMINAL_STATUSES = {"completed", "timeout", "error", "not-run"}
 ATTEMPTED_STATUSES = {"completed", "timeout", "error"}
@@ -1414,17 +1415,6 @@ def _validate_verdict_card_consistency(content: str, failures: list[str]) -> Non
         )
 
 
-def _data_path_for(report_path: Path) -> Path:
-    """Derive the final-report data.json sibling from the markdown path.
-    ``foo.md`` → ``foo.data.json``. The data.json is the canonical JSON
-    SSOT; the markdown is rendered from it.
-    """
-    name = report_path.name
-    if name.endswith(".md"):
-        return report_path.with_name(name[:-3] + ".data.json")
-    return report_path.with_suffix(".data.json")
-
-
 def _load_final_report_data(report_path: Path) -> dict:
     """Best-effort parse of the final-report data.json sibling. Returns {} when
     absent or unparseable — those conditions are already surfaced as failures by

package/src/commands/lifecycle/install.mjs

@@ -13,9 +13,9 @@ const SKILLS_MANIFEST_REL = "installed-skills.json";
 const AGENTS_MANIFEST_REL = "installed-agents.json";
 const USER_HOME = homedir();
 const CLAUDE_HOME = join(USER_HOME, ".claude");
-const AGENT_HOME = join(USER_HOME, ".agent");
+const AGENTS_HOME = join(USER_HOME, ".agents");
 const CLAUDE_SKILLS_DIR = join(CLAUDE_HOME, "skills");
-const AGENT_SKILLS_DIR = join(AGENT_HOME, "skills");
+const AGENTS_SKILLS_DIR = join(AGENTS_HOME, "skills");
 const CLAUDE_AGENTS_DIR = join(CLAUDE_HOME, "agents");
 
 // Source template (relative to runtime root in copy mode, or repo root in link mode).
@@ -80,7 +80,7 @@ Effect (copy mode):
   ${"$HOME"}/.okstra/prompts       <- runtime/prompts  (lead contracts + coding-preflight pack)
   ${"$HOME"}/.okstra/templates/settings.local.json <- runtime/templates/reports/settings.template.json
   ${"$HOME"}/.claude/skills/<name> <- skills when ${"$HOME"}/.claude exists
-  ${"$HOME"}/.agent/skills/<name>  <- skills (created when needed)
+  ${"$HOME"}/.agents/skills/<name> <- skills (created when needed)
   ${"$HOME"}/.claude/agents/<worker>.md <- worker agents when ${"$HOME"}/.claude exists
   ${"$HOME"}/.okstra/installed-runtimes.json <- install request/resolution manifest
   ${"$HOME"}/.okstra/installed-skills.json   <- target-aware manifest of installed skills
@@ -93,7 +93,7 @@ Effect (link mode):
   ${"$HOME"}/.okstra/prompts          -> <repo>/prompts
   ${"$HOME"}/.okstra/templates/settings.local.json -> <repo>/templates/reports/settings.template.json
   ${"$HOME"}/.claude/skills/<name>    -> <repo>/skills/<name> when ${"$HOME"}/.claude exists
-  ${"$HOME"}/.agent/skills/<name>     -> <repo>/skills/<name> (created when needed)
+  ${"$HOME"}/.agents/skills/<name>    -> <repo>/skills/<name> (created when needed)
   ${"$HOME"}/.claude/agents/<worker>.md -> <repo>/agents/workers/<worker>.md when ${"$HOME"}/.claude exists
   ${"$HOME"}/.okstra/dev-link         <- <repo> path stamp
   ${"$HOME"}/.okstra/version          <- installed package version stamp
@@ -401,7 +401,7 @@ async function detectSkillTargets() {
   if (hasClaude) {
     targets.push({ provider: "claude", home: CLAUDE_HOME, skillsDir: CLAUDE_SKILLS_DIR });
   }
-  targets.push({ provider: "agent", home: AGENT_HOME, skillsDir: AGENT_SKILLS_DIR });
+  targets.push({ provider: "agent", home: AGENTS_HOME, skillsDir: AGENTS_SKILLS_DIR });
   return targets;
 }
 

package/src/commands/lifecycle/uninstall.mjs

@@ -40,13 +40,13 @@ const FALLBACK_AGENT_NAMES = [
 
 const USER_HOME = homedir();
 const CLAUDE_HOME = join(USER_HOME, ".claude");
-const AGENT_HOME = join(USER_HOME, ".agent");
+const AGENTS_HOME = join(USER_HOME, ".agents");
 const CLAUDE_SKILLS_DIR = join(CLAUDE_HOME, "skills");
-const AGENT_SKILLS_DIR = join(AGENT_HOME, "skills");
+const AGENTS_SKILLS_DIR = join(AGENTS_HOME, "skills");
 const CLAUDE_AGENTS_DIR = join(CLAUDE_HOME, "agents");
 const FALLBACK_SKILL_ROOTS = [
   CLAUDE_SKILLS_DIR,
-  AGENT_SKILLS_DIR,
+  AGENTS_SKILLS_DIR,
 ];
 const SKILLS_MANIFEST_REL = "installed-skills.json";
 const AGENTS_MANIFEST_REL = "installed-agents.json";
@@ -60,7 +60,7 @@ Usage:
                                 installed-skills.json, installed-agents.json} AND
                                 every skill target recorded in
                                 installed-skills.json
-                                (~/.claude/skills or ~/.agent/skills).
+                                (~/.claude/skills or ~/.agents/skills).
                                 Claude worker agents are
                                 removed from ~/.claude/agents when installed.
                                 Missing manifests fall back to hard-coded