okstra 0.36.1 → 0.37.0

package/runtime/python/okstra_ctl/worktree.py

@@ -41,6 +41,8 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Optional
 
+from okstra_project.dirs import project_json_path
+
 from .ids import _safe_fs_segment
 from . import worktree_registry
 from .seeding import (
@@ -60,13 +62,13 @@ from .seeding import (
 # live shared state and disk/CPU cost stays near zero; the trade-off is
 # that any write through the link reaches the main worktree, which is
 # acceptable because okstra only writes inside its own task-scoped
-# subdirectory (e.g. `.project-docs/okstra/tasks/<task-id>/runs/...`).
+# subdirectory (e.g. `.okstra/tasks/<task-id>/runs/...`).
 #
 # Override precedence (most-specific first):
 #   1. `OKSTRA_WORKTREE_SYNC_DIRS` env var — colon-separated list, REPLACES
 #      defaults. Empty string disables the feature entirely. One-off
 #      operator override.
-#   2. `worktreeSyncDirs` array in `.project-docs/okstra/project.json` —
+#   2. `worktreeSyncDirs` array in `.okstra/project.json` —
 #      project-level config, persists across runs. Same semantics: array
 #      REPLACES defaults, empty array disables.
 #   3. The built-in `DEFAULT_WORKTREE_SYNC_DIRS` below.
@@ -88,7 +90,7 @@ DEFAULT_WORKTREE_SYNC_DIRS: tuple[str, ...] = (
 #
 # Override precedence mirrors `DEFAULT_WORKTREE_SYNC_DIRS`:
 #   1. `OKSTRA_WORKTREE_SYNC_FILES` env var (colon-separated, REPLACES).
-#   2. `worktreeSyncFiles` array in `.project-docs/okstra/project.json`.
+#   2. `worktreeSyncFiles` array in `.okstra/project.json`.
 #   3. The built-in `DEFAULT_WORKTREE_SYNC_FILES` below.
 DEFAULT_WORKTREE_SYNC_FILES: tuple[str, ...] = (
     ".env",
@@ -227,7 +229,7 @@ def _main_worktree_path(project_root: Path) -> Path:
 
 
 def _read_project_json_field(project_root: Path, field: str) -> Optional[tuple[str, ...]]:
-    """Read a string-array field from `.project-docs/okstra/project.json`.
+    """Read a string-array field from the project's okstra project.json.
 
     Returns None if the field is absent or the file cannot be parsed (so
     the caller falls back to defaults). Returns an empty tuple if the
@@ -235,7 +237,7 @@ def _read_project_json_field(project_root: Path, field: str) -> Optional[tuple[s
     A non-list value is treated as missing — we do not raise here because
     field resolution must never block worktree provisioning.
     """
-    target = project_root / ".project-docs" / "okstra" / "project.json"
+    target = project_json_path(project_root)
     if not target.is_file():
         return None
     try:
@@ -398,7 +400,7 @@ def _seed_worktree_settings_symlink(worktree_path: Path) -> None:
 
 
 def _seed_worktree_claude_md(worktree_path: Path) -> None:
-    """Seed `.project-docs/okstra/CLAUDE.md` symlink + `<worktree>/CLAUDE.md`
+    """Seed `.okstra/CLAUDE.md` symlink + `<worktree>/CLAUDE.md`
     import block in the worker worktree so dispatched Claude sessions auto-load
     okstra's runtime guidance. Mirrors `_seed_worktree_settings_symlink` —
     needed because the worktree's `CLAUDE.md` comes from the git checkout (no

package/runtime/python/okstra_project/__init__.py

@@ -1,14 +1,31 @@
 """Project root self-registration model.
 
-`<PROJECT_ROOT>/.project-docs/okstra/project.json` 을 권위 소스로 삼아
+`<PROJECT_ROOT>/<OKSTRA_DIR_NAME>/project.json` 을 권위 소스로 삼아
 PROJECT_ROOT 를 해석하고, 실행 시점에 upsert 한다. 과거 모델
 (`examples/projects/<id>.conf.sh`) 는 폐기되었다.
+
+`OKSTRA_DIR_NAME` 및 자주 쓰는 path 헬퍼는 `.dirs` 모듈이 SSOT.
 """
 from __future__ import annotations
 
+from .dirs import (
+    CLAUDE_MD_IMPORT_LINE,
+    CLAUDE_MD_SYMLINK_RELATIVE,
+    DISCOVERY_RELATIVE,
+    LATEST_TASK_RELATIVE,
+    OKSTRA_DIR_NAME,
+    OKSTRA_RELATIVE,
+    PROJECT_JSON_RELATIVE,
+    TASK_CATALOG_RELATIVE,
+    TASKS_RELATIVE,
+    claude_md_symlink_path,
+    discovery_dir,
+    okstra_root,
+    project_json_path,
+    tasks_root,
+)
 from .resolver import (
     ResolverError,
-    project_json_path,
     resolve_project_root,
     upsert_project_json,
 )
@@ -25,17 +42,30 @@ from .state import (
 )
 
 __all__ = [
+    "CLAUDE_MD_IMPORT_LINE",
+    "CLAUDE_MD_SYMLINK_RELATIVE",
+    "DISCOVERY_RELATIVE",
+    "LATEST_TASK_RELATIVE",
+    "OKSTRA_DIR_NAME",
+    "OKSTRA_RELATIVE",
+    "PROJECT_JSON_RELATIVE",
     "ResolverError",
     "StateError",
-    "project_json_path",
-    "resolve_project_root",
-    "upsert_project_json",
+    "TASKS_RELATIVE",
+    "TASK_CATALOG_RELATIVE",
+    "claude_md_symlink_path",
+    "discovery_dir",
     "find_task_root",
     "list_project_tasks",
+    "okstra_root",
     "parse_task_key",
+    "project_json_path",
     "read_latest_task",
     "read_task_catalog",
     "read_task_manifest",
+    "resolve_project_root",
     "resolve_task_identity",
     "slugify",
+    "tasks_root",
+    "upsert_project_json",
 ]

package/runtime/python/okstra_project/dirs.py

@@ -0,0 +1,67 @@
+"""Single source of truth for the okstra-relative directory name.
+
+okstra 가 한 프로젝트 안에 만드는 모든 산출물은 `<PROJECT_ROOT>/.okstra/`
+한 디렉토리 아래 모인다. 이 모듈은 그 디렉토리 이름과 자주 쓰이는 하위 path 조합을
+한 곳에서 export 한다. 호출자는 절대 path 문자열을 직접 만들지 말고 여기의 상수 /
+헬퍼를 사용해야 한다.
+
+DRY 위반의 비용: 이전에는 동일 path 문자열이 50+ Python·Shell·markdown 파일에
+중복으로 박혀 있었고, 디렉토리 이름을 바꾸려면 60+ 파일을 동시에 수정해야 했다.
+이 모듈은 그 비용을 한 줄 수정으로 줄인다.
+
+의존성 0 (Path only). `paths.py` 와 `state.py` 양쪽에서 import 되므로 순환 위험을
+피하기 위해 다른 okstra 모듈을 import 하지 않는다.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+OKSTRA_DIR_NAME = ".okstra"
+"""Project-relative directory name where okstra stores all per-project state.
+
+CLI / docs / message 문자열도 모두 이 값과 일치해야 한다. 값 자체를 import 해 쓰는
+대신 path 합성에는 `OKSTRA_RELATIVE` / `okstra_root()` 등을 권장.
+"""
+
+LEGACY_OKSTRA_DIR_NAME = ".project-docs/okstra"
+"""Pre-v0.37 layout. ``okstra migrate`` reads this to find unmigrated projects.
+
+코드 path 빌드에는 절대 사용 금지 — `OKSTRA_DIR_NAME` / `OKSTRA_RELATIVE` 만.
+오로지 migration 탐지/안내 메시지 용도.
+"""
+
+OKSTRA_RELATIVE = Path(OKSTRA_DIR_NAME)
+LEGACY_OKSTRA_RELATIVE = Path(LEGACY_OKSTRA_DIR_NAME)
+PROJECT_JSON_RELATIVE = OKSTRA_RELATIVE / "project.json"
+TASKS_RELATIVE = OKSTRA_RELATIVE / "tasks"
+DISCOVERY_RELATIVE = OKSTRA_RELATIVE / "discovery"
+TASK_CATALOG_RELATIVE = DISCOVERY_RELATIVE / "task-catalog.json"
+LATEST_TASK_RELATIVE = DISCOVERY_RELATIVE / "latest-task.json"
+CLAUDE_MD_SYMLINK_RELATIVE = OKSTRA_RELATIVE / "CLAUDE.md"
+CLAUDE_MD_IMPORT_LINE = f"@{OKSTRA_DIR_NAME}/CLAUDE.md"
+LEGACY_CLAUDE_MD_IMPORT_LINE = f"@{LEGACY_OKSTRA_DIR_NAME}/CLAUDE.md"
+
+
+def okstra_root(project_root: Path) -> Path:
+    """`<project_root>/.okstra` 절대 path."""
+    return Path(project_root) / OKSTRA_RELATIVE
+
+
+def project_json_path(project_root: Path) -> Path:
+    """`<project_root>/.okstra/project.json` 절대 path."""
+    return Path(project_root) / PROJECT_JSON_RELATIVE
+
+
+def tasks_root(project_root: Path) -> Path:
+    """`<project_root>/.okstra/tasks` 절대 path."""
+    return Path(project_root) / TASKS_RELATIVE
+
+
+def discovery_dir(project_root: Path) -> Path:
+    """`<project_root>/.okstra/discovery` 절대 path."""
+    return Path(project_root) / DISCOVERY_RELATIVE
+
+
+def claude_md_symlink_path(project_root: Path) -> Path:
+    """`<project_root>/.okstra/CLAUDE.md` 절대 path."""
+    return Path(project_root) / CLAUDE_MD_SYMLINK_RELATIVE

package/runtime/python/okstra_project/resolver.py

@@ -8,23 +8,23 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
-PROJECT_JSON_RELATIVE = Path(".project-docs/okstra/project.json")
+from .dirs import (
+    OKSTRA_DIR_NAME,
+    PROJECT_JSON_RELATIVE,
+    project_json_path,
+)
 
 
 class ResolverError(Exception):
     """PROJECT_ROOT 해석 또는 project.json 충돌 실패."""
 
 
-def project_json_path(project_root: Path) -> Path:
-    return Path(project_root) / PROJECT_JSON_RELATIVE
-
-
 def _now_iso() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
 def _ancestor_with_project_json(start: Path) -> Optional[Path]:
-    """start 부터 위로 올라가며 `.project-docs/okstra/project.json` 보유 디렉터리를 찾는다."""
+    """start 부터 위로 올라가며 okstra `project.json` 보유 디렉터리를 찾는다."""
     cur = Path(start).resolve()
     while True:
         if (cur / PROJECT_JSON_RELATIVE).is_file():
@@ -57,7 +57,7 @@ def resolve_project_root(*, explicit_root: str = "",
 
     우선순위:
       1. explicit_root (CLI `--project-root`) — 비어있지 않으면 그대로 절대화.
-      2. cwd 또는 그 조상 중 `.project-docs/okstra/project.json` 보유 디렉터리.
+      2. cwd 또는 그 조상 중 `<dir>/project.json` 보유 디렉터리 (dir = OKSTRA_DIR_NAME).
       3. cwd 의 `git rev-parse --show-toplevel`.
     셋 다 실패하면 ResolverError.
     """
@@ -77,7 +77,7 @@ def resolve_project_root(*, explicit_root: str = "",
     raise ResolverError(
         "could not resolve PROJECT_ROOT from cwd. "
         "Pass --project-root <abs-path>, "
-        "run from inside a project (a directory with .project-docs/okstra/project.json at or above cwd), "
+        f"run from inside a project (a directory with {OKSTRA_DIR_NAME}/project.json at or above cwd), "
         "or run from inside a git working tree. "
         "(PROJECT_ROOT 를 해석할 수 없습니다 — --project-root 를 명시하거나, "
         "프로젝트 루트 또는 그 하위에서 실행하거나, git 작업 트리 안에서 실행해 주십시오.)")

package/runtime/python/okstra_project/state.py

@@ -6,12 +6,12 @@ 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.
 
-권위 파일 매핑:
-  - <PROJECT_ROOT>/.project-docs/okstra/project.json
+권위 파일 매핑 (okstra root = <PROJECT_ROOT>/<OKSTRA_DIR_NAME>):
+  - <okstra root>/project.json
       -> {projectId, projectRoot, ...}
-  - <PROJECT_ROOT>/.project-docs/okstra/discovery/task-catalog.json
+  - <okstra root>/discovery/task-catalog.json
       -> tasks[]: 각 task 의 stable identity 와 phase pointer
-  - <PROJECT_ROOT>/.project-docs/okstra/discovery/latest-task.json
+  - <okstra root>/discovery/latest-task.json
       -> 가장 최근에 prepare/run 된 task 의 포인터
   - <task-root>/task-manifest.json
       -> 한 task 의 manifest (workflow.* phase 정보 포함)
@@ -23,10 +23,12 @@ import re
 from pathlib import Path
 from typing import Optional
 
-DISCOVERY_RELATIVE = Path(".project-docs/okstra/discovery")
-TASK_CATALOG_RELATIVE = DISCOVERY_RELATIVE / "task-catalog.json"
-LATEST_TASK_RELATIVE = DISCOVERY_RELATIVE / "latest-task.json"
-TASKS_RELATIVE = Path(".project-docs/okstra/tasks")
+from .dirs import (
+    DISCOVERY_RELATIVE,
+    LATEST_TASK_RELATIVE,
+    TASK_CATALOG_RELATIVE,
+    TASKS_RELATIVE,
+)
 
 
 class StateError(Exception):
@@ -93,7 +95,7 @@ def find_task_root(project_root: Path, task_key: str) -> Optional[Path]:
 
     해석 우선순위:
       1. task-catalog.json 의 같은 taskKey 항목의 taskRootPath
-      2. <PROJECT_ROOT>/.project-docs/okstra/tasks/<slug-group>/<slug-id>/
+      2. <PROJECT_ROOT>/<OKSTRA_DIR_NAME>/tasks/<slug-group>/<slug-id>/
 
     어느 쪽도 디렉터리로 존재하지 않으면 None.
     """

package/runtime/python/okstra_token_usage/collect.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 import json
 from datetime import datetime
 from pathlib import Path
+from okstra_project.dirs import OKSTRA_RELATIVE
+
 from .blocks import na_block, usage_block
 from .claude import claude_session_totals, find_claude_team_sessions
 from .codex import codex_session_total, find_codex_session
@@ -255,7 +257,7 @@ def _infer_project_root(team_state_path: Path, state: dict) -> Path:
     while p != p.parent:
         if rel and (p / rel).is_dir():
             return p
-        if (p / ".project-docs").is_dir():
+        if (p / OKSTRA_RELATIVE).is_dir():
             return p
         p = p.parent
     raise SystemExit(f"could not infer project root from {team_state_path}")

package/runtime/python/okstra_token_usage/report.py

@@ -125,13 +125,17 @@ def populate_data_token_cells(data_path: Path, team_state: dict) -> int:
     changes += 4
 
     # Execution Status by Agent — per-row token / cost / duration.
-    lead_entry = team_state.get("lead") or {}
+    # `collect.py` writes lead usage to `team_state["leadUsage"]` (flat
+    # usage_block), while worker usage lives at `worker["usage"]`. Wrap
+    # the lead block so `_populate_execution_row` can read both shapes
+    # via the same `source["usage"]` path.
+    lead_source = {"usage": team_state.get("leadUsage") or {}}
     workers = team_state.get("workers") or []
     rows = data.get("executionStatus") or []
     for row in rows:
         role = row.get("role", "")
         if "lead" in role.lower():
-            _populate_execution_row(row, lead_entry)
+            _populate_execution_row(row, lead_source)
             changes += 1
             continue
         for worker in workers:

package/runtime/skills/okstra-brief/SKILL.md

@@ -6,7 +6,7 @@ description: Use when the user wants to generate a task brief file for okstra fr
 # okstra-brief
 
 Generate a single `task brief` markdown file under the okstra project domain
-(`.project-docs/okstra/briefs/<task-group>/<task-id>.md`) so it can be fed to
+(`.okstra/briefs/<task-group>/<task-id>.md`) so it can be fed to
 [`okstra-run`](../okstra-run/SKILL.md) as `--task-brief`.
 
 **Purpose — pre-discovery artifact.** A brief is the **pre-discovery** stage
@@ -75,40 +75,40 @@ okstra-brief (codebase-scan variant)
 
 ## Artifact-home rule (okstra-wide)
 
-**All okstra-generated artifacts live under `<PROJECT_ROOT>/.project-docs/okstra/`.**
+**All okstra-generated artifacts live under `<PROJECT_ROOT>/.okstra/`.**
 This includes briefs, run manifests, reports, worker results, status,
 sessions, and any other run output.
 
-All writes by this skill stay inside `.project-docs/okstra/`. When domain
+All writes by this skill stay inside `.okstra/`. When domain
 alignment (Step 3b / Step 4.5) yields a glossary change that the user
 approves inline, the change is written to:
 
-- `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` — okstra's internal
+- `<PROJECT_ROOT>/.okstra/glossary.md` — okstra's internal
   glossary. Created if absent; appended to a `## Glossary` section
   otherwise.
 
-Paths outside `<PROJECT_ROOT>/.project-docs/okstra/**` are not okstra
+Paths outside `<PROJECT_ROOT>/.okstra/**` are not okstra
 memory. This skill reads them only when the reporter explicitly cited them
 as source material, and never writes them. Decision files (when raised by
 `implementation-planning`) also live inside okstra's subtree at
-`<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`.
+`<PROJECT_ROOT>/.okstra/decisions/<NNNN>-<slug>.md`.
 
 ## Authority files
 
-- `<PROJECT_ROOT>/.project-docs/okstra/project.json` — must exist; if not,
+- `<PROJECT_ROOT>/.okstra/project.json` — must exist; if not,
   ask the user to run `okstra-setup` first.
-- `<PROJECT_ROOT>/.project-docs/okstra/briefs/<task-group>/<ticket-id>-<file-title>.md`
+- `<PROJECT_ROOT>/.okstra/briefs/<task-group>/<ticket-id>-<file-title>.md`
   (single / parent) or
-  `<PROJECT_ROOT>/.project-docs/okstra/briefs/<task-group>/sub/<ticket-id>-<file-title>.md`
+  `<PROJECT_ROOT>/.okstra/briefs/<task-group>/sub/<ticket-id>-<file-title>.md`
   (tracker child ticket; at depth N, `sub/` is nested N times) — output
   location for this skill. `<ticket-id>` is the raw issue-id when the source
   is a tracker, otherwise free-text supplied by the user. `<file-title>` is
   auto-slugified from the tracker title, otherwise from user input.
 - okstra-internal glossary (write target of Step 4.5):
-  `<PROJECT_ROOT>/.project-docs/okstra/glossary.md`. Created if absent.
+  `<PROJECT_ROOT>/.okstra/glossary.md`. Created if absent.
 - okstra-internal decisions (write target of `implementation-planning`
   via `implementation`):
-  `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`.
+  `<PROJECT_ROOT>/.okstra/decisions/<NNNN>-<slug>.md`.
 
 ## Step 0: Resolve project root
 
@@ -255,7 +255,7 @@ Order of operations:
      visited set is per-run and disappears between invocations. When this
      skill runs again over a tree that already has briefs on disk, it MUST
      reseed the visited set by scanning
-     `<PROJECT_ROOT>/.project-docs/okstra/briefs/<task-group>/` recursively
+     `<PROJECT_ROOT>/.okstra/briefs/<task-group>/` recursively
      and reading each brief's frontmatter `ticket-id` + `source-type`.
      Reseed precedence:
      1. On-disk frontmatter (`ticket-id` ≠ "") populates visited entries
@@ -356,10 +356,10 @@ preflight), reuse that value silently — do NOT ask again.
 Final brief path rule (fixed; one extra `sub/` per depth):
 
 ```
-depth 0 (parent / single) :  <PROJECT_ROOT>/.project-docs/okstra/briefs/<task-group>/<ticket-id>-<file-title>.md
-depth 1 (child)           :  <PROJECT_ROOT>/.project-docs/okstra/briefs/<task-group>/sub/<ticket-id>-<file-title>.md
-depth 2 (grandchild)      :  <PROJECT_ROOT>/.project-docs/okstra/briefs/<task-group>/sub/sub/<ticket-id>-<file-title>.md
-depth N                   :  <PROJECT_ROOT>/.project-docs/okstra/briefs/<task-group>/<sub/ nested N times>/<ticket-id>-<file-title>.md
+depth 0 (parent / single) :  <PROJECT_ROOT>/.okstra/briefs/<task-group>/<ticket-id>-<file-title>.md
+depth 1 (child)           :  <PROJECT_ROOT>/.okstra/briefs/<task-group>/sub/<ticket-id>-<file-title>.md
+depth 2 (grandchild)      :  <PROJECT_ROOT>/.okstra/briefs/<task-group>/sub/sub/<ticket-id>-<file-title>.md
+depth N                   :  <PROJECT_ROOT>/.okstra/briefs/<task-group>/<sub/ nested N times>/<ticket-id>-<file-title>.md
 ```
 
 `<sub/ nested N times>` is a meta-notation; the actual path concatenates
@@ -429,8 +429,8 @@ Read in this order — absent files are the normal state; skip silently and
 never error:
 
 1. **okstra-internal (authoritative)** — always check first:
-   - `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` if present
-   - `<PROJECT_ROOT>/.project-docs/okstra/decisions/` titles if present
+   - `<PROJECT_ROOT>/.okstra/glossary.md` if present
+   - `<PROJECT_ROOT>/.okstra/decisions/` titles if present
 2. **Explicit source material only** — if the reporter cited a path outside
    okstra's subtree, read it as source evidence only; do not treat it as
    okstra memory.
@@ -477,7 +477,7 @@ on a project-internal concrete object whenever possible.
   knows to query the reporter directly rather than infer.
 - See Step 4.5 for the approval-gated path to actually write the
   okstra-internal glossary at
-  `<PROJECT_ROOT>/.project-docs/okstra/glossary.md`.
+  `<PROJECT_ROOT>/.okstra/glossary.md`.
 
 Skip 3b/3c for purely external request material with no overlap to the
 project's domain.
@@ -560,7 +560,7 @@ labels. Unlabelled augmentation is rejected as half-formed translation.
 |---|---|---|
 | `evidence-link` | Cross-reference / file path / symbol resolved from the source against the actual codebase. Pure fact, verified by `Read` / `Grep`. | Trust without verification. |
 | `format-conversion` | Format-only transform (Jira ADF → Markdown, HTML → Markdown, etc.). Semantics unchanged. | Trust without verification. |
-| `terminology-mapping` | Reporter's word mapped to an okstra-canonical term from Step 3b. | Verify against `.project-docs/okstra/glossary.md`; if mismatch, treat as a clarification candidate. |
+| `terminology-mapping` | Reporter's word mapped to an okstra-canonical term from Step 3b. | Verify against `.okstra/glossary.md`; if mismatch, treat as a clarification candidate. |
 | `intent-inference` | Reporter did NOT literally state this — the skill inferred meaning from context (e.g. classifying "가끔 안 됨" as "intermittent failure on a specific path"). Qualitative only — **never** invent quantitative thresholds (numbers, latencies, percentages, counts). | **Verify with the reporter before acting.** Auto-mirrored into `Open Questions`. |
 
 **Inline form** — `> augmented: intent-inference — <one line>`.
@@ -617,7 +617,7 @@ Those belong to later okstra phases.
 For each `conflict` / `fuzzy` term collected in Step 3b that *was not*
 resolved by a budgeted Step 4 question, draft a glossary proposal and
 offer it to the user. This step writes to the **okstra-internal
-glossary** at `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` only —
+glossary** at `<PROJECT_ROOT>/.okstra/glossary.md` only —
 the skill does not write outside okstra's subtree.
 
 > **Decision scope**: this skill does NOT evaluate decision candidates
@@ -627,12 +627,12 @@ the skill does not write outside okstra's subtree.
 > goes to `Open Questions` with the `adr-candidate:` prefix and is
 > evaluated by `implementation-planning` against the three-criteria
 > gate. Approved decision files land at
-> `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`.
+> `<PROJECT_ROOT>/.okstra/decisions/<NNNN>-<slug>.md`.
 
 ### 4.5a. Draft glossary proposals
 
 - **Glossary entry**: `proposed glossary entry: <term> = <one-line definition>`
-  — destined for `<PROJECT_ROOT>/.project-docs/okstra/glossary.md`.
+  — destined for `<PROJECT_ROOT>/.okstra/glossary.md`.
 
 ### 4.5b. Approval flow (per entry)
 
@@ -652,7 +652,7 @@ the user sees the exact file that will be written), then `AskUserQuestion`:
 Ask once per entry. Never batch. If the user picks `Apply`:
 
 - Append the entry to
-  `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` under an existing
+  `<PROJECT_ROOT>/.okstra/glossary.md` under an existing
   relevant heading, or create a `## Glossary` section if none exists. If
   the file does not exist, create it with a `## Glossary` heading and
   the entry. Preserve all existing content byte-for-byte.
@@ -662,12 +662,12 @@ Ask once per entry. Never batch. If the user picks `Apply`:
 Regardless of Apply / Skip, record the outcome under `Augmentation >
 Domain alignment`:
 
-- `terminology-mapping: applied glossary: <term> → <PROJECT_ROOT>/.project-docs/okstra/glossary.md` or
+- `terminology-mapping: applied glossary: <term> → <PROJECT_ROOT>/.okstra/glossary.md` or
 - `terminology-mapping: skipped glossary: <term> = <definition>`
 
 Decision candidates are recorded under `Open Questions` as
 `adr-candidate: <topic>` (targeting
-`<PROJECT_ROOT>/.project-docs/okstra/decisions/`) — not here. This keeps
+`<PROJECT_ROOT>/.okstra/decisions/`) — not here. This keeps
 the brief itself self-documenting about what side effects it caused.
 
 ## Step 5: Write the brief(s)
@@ -865,10 +865,10 @@ started.
 ## Output Rules
 
 - All okstra-generated artifacts live under
-  `<PROJECT_ROOT>/.project-docs/okstra/`. This skill's brief files go
-  under `.project-docs/okstra/briefs/`; its glossary writes go to
-  `.project-docs/okstra/glossary.md` (Step 4.5 approval flow).
-- Paths outside `<PROJECT_ROOT>/.project-docs/okstra/**` are read-only
+  `<PROJECT_ROOT>/.okstra/`. This skill's brief files go
+  under `.okstra/briefs/`; its glossary writes go to
+  `.okstra/glossary.md` (Step 4.5 approval flow).
+- Paths outside `<PROJECT_ROOT>/.okstra/**` are read-only
   source material only when explicitly cited by the reporter. This skill
   never writes outside okstra's subtree.
 - **Verbatim source**: never paraphrase, summarize, restructure, or reorder

package/runtime/skills/okstra-context-loader/SKILL.md

@@ -19,19 +19,19 @@ user-invocable: false
 ### Default Location Rules
 
 - AI documentation root: `.project-docs/`
-- Project-level latest-task pointer: `.project-docs/okstra/discovery/latest-task.json`
-- Project-level task catalog: `.project-docs/okstra/discovery/task-catalog.json`
-- okstra task root: `.project-docs/okstra/tasks/`
-- Task path pattern: `.project-docs/okstra/tasks/<task-group>/<task-id>/`
+- Project-level latest-task pointer: `.okstra/discovery/latest-task.json`
+- Project-level task catalog: `.okstra/discovery/task-catalog.json`
+- okstra task root: `.okstra/tasks/`
+- Task path pattern: `.okstra/tasks/<task-group>/<task-id>/`
 
 ### Task Identification
 1. If the user specifies the `task-manifest.json` path or the task root path, that path is used.
 2. If the user specifies only the task key, the expected task root is calculated by converting the `task-group` and `task-id` to lowercase and applying the slug rule (`[^a-z0-9]+` → `-`), and the corresponding `task-manifest.json` is opened.
-3. If the user attempts to find a task based on `task-group` + `task-id` or `task-id`, `.project-docs/okstra/discovery/task-catalog.json` is read to find candidates.
+3. If the user attempts to find a task based on `task-group` + `task-id` or `task-id`, `.okstra/discovery/task-catalog.json` is read to find candidates.
 4. If multiple candidates are found based on `task-id` alone, the situation is ambiguous, so `task-group` or the full `taskKey` is required.
-5. If the user has not provided an explicit task key/path, first read `.project-docs/okstra/discovery/latest-task.json` using the current-task convenience pointer.
+5. If the user has not provided an explicit task key/path, first read `.okstra/discovery/latest-task.json` using the current-task convenience pointer.
 6. If the latest-task pointer is missing or corrupted but the task catalog exists, list candidates from the catalog. Do not use the legacy `CLAUDE.md`, project guide, or task scan fallback.
-7. If **neither** `latest-task.json` **nor** `task-catalog.json` exists, ABORT Phase 1 with `OKSTRA_CONTEXT_NOT_INITIALIZED`. Suggest the user run `/okstra-setup` and `/okstra-brief` to bootstrap the project. Do NOT crawl `.project-docs/okstra/tasks/` directly — discovery pointers are the only supported entry path.
+7. If **neither** `latest-task.json` **nor** `task-catalog.json` exists, ABORT Phase 1 with `OKSTRA_CONTEXT_NOT_INITIALIZED`. Suggest the user run `/okstra-setup` and `/okstra-brief` to bootstrap the project. Do NOT crawl `.okstra/tasks/` directly — discovery pointers are the only supported entry path.
 
 ## Step 2: Open and Parse task-manifest.json