okstra 0.102.2 → 0.102.4

package/runtime/python/okstra_ctl/render.py

@@ -31,6 +31,7 @@ from okstra_project.dirs import OKSTRA_DIR_NAME, project_json_path
 from . import fix_cycles
 from .paths import okstra_home
 from .lead_runtime import lead_runtime_info
+from .path_hints import compact_active_run_context, hydrate_run_context
 from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
 
 
@@ -56,8 +57,8 @@ def _load_ctx(ctx_arg: str) -> dict:
     """
     s = ctx_arg.lstrip()
     if s.startswith("{"):
-        return json.loads(ctx_arg)
-    return json.loads(Path(ctx_arg).read_text(encoding="utf-8"))
+        return hydrate_run_context(json.loads(ctx_arg))
+    return hydrate_run_context(json.loads(Path(ctx_arg).read_text(encoding="utf-8")))
 
 
 def _write_text(path: Path, text: str) -> None:
@@ -434,7 +435,7 @@ def render_active_run_context(active_context_path: str, ctx: dict) -> None:
         "sourceArtifacts": _active_source_artifacts(ctx),
         "lazyReadPlan": _active_lazy_read_plan(),
     }
-    _write_json(Path(active_context_path), payload)
+    _write_json(Path(active_context_path), compact_active_run_context(ctx, payload))
 
 
 def render_team_state(team_state_path: str, ctx: dict) -> None:

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

@@ -25,6 +25,7 @@ from typing import Iterator, Optional
 
 from okstra_project.dirs import okstra_home
 
+from .path_hints import compact_run_context, hydrate_run_context
 from .paths import compute_run_paths, task_runs_dir
 
 
@@ -188,7 +189,7 @@ def compute_and_write_run_context(
             str(ctx_path.relative_to(project_root.resolve()))
             if ctx_path.resolve().is_relative_to(project_root.resolve())
             else str(ctx_path))
-        _atomic_write_json(ctx_path, ctx)
+        _atomic_write_json(ctx_path, compact_run_context(ctx))
     return ctx
 
 
@@ -225,7 +226,8 @@ def read_run_context(run_manifests_dir: Path, task_type_segment: str,
     path = Path(run_manifests_dir) / _run_context_filename(task_type_segment, seq)
     if not path.is_file():
         return None
-    return json.loads(path.read_text(encoding="utf-8"))
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    return hydrate_run_context(payload)
 
 
 def read_run_inputs(run_manifests_dir: Path, task_type_segment: str,

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:
@@ -1046,6 +1053,18 @@ def _opt(value: str, label: str = "", description: str = "") -> Option:
 
 # --- builders ---
 
+def _contract_outcome_suffix(entry: dict) -> str:
+    outcome = entry.get("phaseOutcome")
+    implementation = outcome.get("implementation") if isinstance(outcome, dict) else {}
+    if not isinstance(implementation, dict):
+        return ""
+    if implementation.get("state") != "completed":
+        return ""
+    if entry.get("currentStatus") == "contract-violated":
+        return " · implementation complete; contract warnings"
+    return ""
+
+
 def _build_task_pick(state: WizardState) -> Prompt:
     t = _p(state.workspace_root, "task_pick")
     project_root = Path(state.project_root)
@@ -1063,7 +1082,7 @@ def _build_task_pick(state: WizardState) -> Prompt:
         phase = entry.get("currentPhase") or ttype
         nxt = entry.get("nextRecommendedPhase") or ""
         suffix = latest_suffix if key == latest_key else ""
-        label = f"{key}  ·  {phase}  ·  next: {nxt}{suffix}"
+        label = f"{key}  ·  {phase}  ·  next: {nxt}{_contract_outcome_suffix(entry)}{suffix}"
         options.append(_opt(value=key, label=label))
     for value, label in _static_options(t):
         options.append(_opt(value=value, label=label))
@@ -1652,7 +1671,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 +3506,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 +3529,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 +3592,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_project/state.py

@@ -1,10 +1,13 @@
-"""Read-only state accessors over okstra's on-disk authority files.
+"""Read-side state accessors over okstra's on-disk authority files.
 
 Skills, okstra.sh, and okstra-ctl all read the same files through this module
 so identity / discovery values are derived from disk on every call instead of
 being passed via process environment. This keeps concurrent claude-code skill
 invocations isolated — each call reads the authoritative state at the moment
 it runs and never sees stale snapshots inherited from a parent process.
+Some accessors also run best-effort reconciliation before returning derived
+phase pointers, so stale catalog entries can be healed from authoritative
+task artifacts.
 
 권위 파일 매핑 (okstra root = <PROJECT_ROOT>/<OKSTRA_DIR_NAME>):
   - <okstra root>/project.json
@@ -78,6 +81,38 @@ def read_task_manifest(task_root: Path) -> Optional[dict]:
     return _load_json(Path(task_root) / "task-manifest.json")
 
 
+def _reconcile_task_root_best_effort(project_root: Path, task_root: Path) -> None:
+    try:
+        from okstra_ctl.implementation_outcome import reconcile_implementation_outcome
+
+        reconcile_implementation_outcome(project_root, task_root)
+    except Exception:
+        return
+
+
+def _entry_with_manifest_state(entry: dict, task_root: Path) -> dict:
+    out = {**entry}
+    manifest = read_task_manifest(task_root) or {}
+    workflow = manifest.get("workflow") if isinstance(manifest.get("workflow"), dict) else {}
+    for source, target in (
+        ("currentPhase", "currentPhase"),
+        ("currentPhaseState", "currentPhaseState"),
+        ("lastCompletedPhase", "lastCompletedPhase"),
+        ("nextRecommendedPhase", "nextRecommendedPhase"),
+    ):
+        value = workflow.get(source)
+        if isinstance(value, str):
+            out[target] = value
+    for field in ("currentStatus", "latestRunStatus", "latestReportPath"):
+        value = manifest.get(field)
+        if isinstance(value, str):
+            out[field] = value
+    phase_outcome = manifest.get("phaseOutcome")
+    if isinstance(phase_outcome, dict):
+        out["phaseOutcome"] = phase_outcome
+    return out
+
+
 def parse_task_key(task_key: str) -> tuple[str, str, str]:
     """`project-id:task-group:task-id` 를 3-tuple 로 분해.
 
@@ -111,10 +146,12 @@ def find_task_root(project_root: Path, task_key: str) -> Optional[Path]:
         if isinstance(rel, str) and rel:
             abs_path = project_root / rel if not Path(rel).is_absolute() else Path(rel)
             if abs_path.is_dir():
+                _reconcile_task_root_best_effort(project_root, abs_path)
                 return abs_path
 
     slug_path = project_root / TASKS_RELATIVE / slugify(task_group) / slugify(task_id)
     if slug_path.is_dir():
+        _reconcile_task_root_best_effort(project_root, slug_path)
         return slug_path
     return None
 
@@ -180,7 +217,8 @@ def list_project_tasks(
         root = find_task_root(project_root, entry_key)
         if root is None:
             continue
-        out.append({**entry, "_resolvedTaskRoot": str(root)})
+        reconciled_entry = _entry_with_manifest_state(entry, root)
+        out.append({**reconciled_entry, "_resolvedTaskRoot": str(root)})
     if limit is not None and limit >= 0:
         out = out[:limit]
     return out

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