okstra 0.36.2 → 0.37.0

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

@@ -45,7 +45,7 @@ Trigger phrases: "okstra status", "task status", "current phase", "next phase",
 
 ### status.1 — Overall project status
 
-Read `.project-docs/okstra/discovery/task-catalog.json`. The catalog is the authoritative source — every field listed below (including `workStatus`, `workStatusUpdatedAt`, `workStatusNote`) is projected directly from each `task-manifest.json` by `scripts/okstra_ctl/render.py :: render_task_catalog_discovery`. Do NOT re-open individual manifests for the overview.
+Read `.okstra/discovery/task-catalog.json`. The catalog is the authoritative source — every field listed below (including `workStatus`, `workStatusUpdatedAt`, `workStatusNote`) is projected directly from each `task-manifest.json` by `scripts/okstra_ctl/render.py :: render_task_catalog_discovery`. Do NOT re-open individual manifests for the overview.
 
 | Field | Description |
 |------|------|
@@ -86,7 +86,7 @@ If `awaitingApproval` is true OR `routingStatus == "pending"`, append a `*` to t
 Given a specific `task-key` or `task-group + task-id`:
 
 1. If possible, quickly look it up in `task-catalog.json`.
-2. If necessary, read `.project-docs/okstra/tasks/<task-group>/<task-id>/task-manifest.json` directly.
+2. If necessary, read `.okstra/tasks/<task-group>/<task-id>/task-manifest.json` directly.
 3. If you need the latest run information, read `history/timeline.json` along with the latest run manifest.
 
 Required fields: `taskKey`, `taskType`, `workCategory`, `currentStatus`, `latestRunStatus`, `workflow.{currentPhase, currentPhaseState, phaseStates, lastCompletedPhase, nextRecommendedPhase, awaitingApproval, routingStatus, lastSafeCheckpoint}`, `workStatus`, `workStatusUpdatedAt`, `workStatusNote`, `latestReportPath`, `latestResumeCommandPath`, `historyTimelinePath`.
@@ -155,10 +155,10 @@ Accepted `<status>` values: `todo`, `in-progress`, `blocked`, `done`.
 **Procedure:**
 
 1. **Validate status value.** If not in the enum, output an error and the allowed values list. Do not modify any file.
-2. **Look up the task** in `.project-docs/okstra/discovery/task-catalog.json` by `task-id` (case-insensitive on both `task-id` and `task-group`).
+2. **Look up the task** in `.okstra/discovery/task-catalog.json` by `task-id` (case-insensitive on both `task-id` and `task-group`).
    - If the user provided `<task-group>` explicitly, scope the lookup to that group (case-insensitive).
    - Single match → proceed. Multiple matches across different groups → list and ask user to retry with explicit form (`okstra status set <task-group> <TASK-ID> <status>`). No match → `<TASK-ID>를 찾을 수 없습니다.` and stop.
-3. **Open the matching `task-manifest.json`** at `.project-docs/okstra/tasks/<task-group-segment>/<task-id-segment>/task-manifest.json`. Assemble the path from the catalog entry's `taskGroupPathSegment` and `taskIdPathSegment` fields (filesystem-safe segments emitted by the renderer) — NOT from the raw user-supplied strings, which may differ in case or contain characters normalized when the manifest was created. Prefer the `taskManifestPath` field directly when present.
+3. **Open the matching `task-manifest.json`** at `.okstra/tasks/<task-group-segment>/<task-id-segment>/task-manifest.json`. Assemble the path from the catalog entry's `taskGroupPathSegment` and `taskIdPathSegment` fields (filesystem-safe segments emitted by the renderer) — NOT from the raw user-supplied strings, which may differ in case or contain characters normalized when the manifest was created. Prefer the `taskManifestPath` field directly when present.
 4. **Update fields at the manifest root:**
    - `workStatus` ← new status value
    - `workStatusUpdatedAt` ← current ISO-8601 UTC timestamp (`2026-05-01T10:23:45Z`)
@@ -199,7 +199,7 @@ Trigger phrases: "okstra history", "past runs", "run history", "re-run", "list t
 
 ### history.1 — Read the task catalog
 
-1. Read `.project-docs/okstra/discovery/task-catalog.json`.
+1. Read `.okstra/discovery/task-catalog.json`.
 2. Apply filters from user input (all optional, AND-combined):
    - `--task-type <type>` → keep entries whose `taskType` matches.
    - `--latest-run-status <status>` → keep entries whose `latestRunStatus` matches (`completed`, `contract-violated`, `error`).
@@ -219,7 +219,7 @@ Trigger phrases: "okstra history", "past runs", "run history", "re-run", "list t
 
 **Catalog absent — fallback.** Do NOT bail out. Manifests on disk are the source of truth.
 
-1. Glob `<projectRoot>/.project-docs/okstra/tasks/*/*/task-manifest.json`.
+1. Glob `<projectRoot>/.okstra/tasks/*/*/task-manifest.json`.
 2. For each manifest, read the same fields as above.
 3. Apply the same filters/sort/limit and print the same table, prefixed with: `note: task-catalog.json missing; reconstructed from task manifests on disk.`
 4. Only if the glob yields zero manifests: `There is no okstra execution history yet.`
@@ -292,13 +292,13 @@ task-key format: `<project-id>:<task-group>:<task-id>`.
 
 Lookup methods (in priority order):
 
-A. **`task-catalog.json` (fast):** read `.project-docs/okstra/discovery/task-catalog.json`, match `taskKey` lowercase. `latestReportPath` is task-type-agnostic "most recent report".
+A. **`task-catalog.json` (fast):** read `.okstra/discovery/task-catalog.json`, match `taskKey` lowercase. `latestReportPath` is task-type-agnostic "most recent report".
 
-B. **`task-manifest.json` (direct):** if catalog missing, slugify task-group / task-id, read `.project-docs/okstra/tasks/<group-segment>/<id-segment>/task-manifest.json`, use `latestReportPath` (task-type-agnostic).
+B. **`task-manifest.json` (direct):** if catalog missing, slugify task-group / task-id, read `.okstra/tasks/<group-segment>/<id-segment>/task-manifest.json`, use `latestReportPath` (task-type-agnostic).
 
-C. **`timeline.json` (specific run):** for a specific date or run, read `.project-docs/okstra/tasks/<group-segment>/<id-segment>/history/timeline.json`, filter `runs[]` by `runTimestamp` / `status` / `taskType`, use `runs[].reportPath`.
+C. **`timeline.json` (specific run):** for a specific date or run, read `.okstra/tasks/<group-segment>/<id-segment>/history/timeline.json`, filter `runs[]` by `runTimestamp` / `status` / `taskType`, use `runs[].reportPath`.
 
-D. **Specific task-type (fallback):** `latestReportPath` is task-type-agnostic. For a specific task-type's latest report, look under `.project-docs/okstra/tasks/<group-segment>/<id-segment>/runs/<task-type-segment>/reports/`, filename pattern `final-report-<task-type-segment>-<NNN>.md` per `scripts/okstra_ctl/sequence.py:31`. Highest seq is latest. Cross-verify with `timeline.json`'s `runs[].taskType` filter.
+D. **Specific task-type (fallback):** `latestReportPath` is task-type-agnostic. For a specific task-type's latest report, look under `.okstra/tasks/<group-segment>/<id-segment>/runs/<task-type-segment>/reports/`, filename pattern `final-report-<task-type-segment>-<NNN>.md` per `scripts/okstra_ctl/sequence.py:31`. Highest seq is latest. Cross-verify with `timeline.json`'s `runs[].taskType` filter.
 
 ### report.2 — Confirm existence
 
@@ -347,7 +347,7 @@ Aggregate elapsed work time for a given task, grouped by **task type** and broke
 
 **Data sources** (both collected by okstra):
 
-1. `.project-docs/okstra/tasks/<task-group>/<task-id>/history/timeline.json` — `runs` array with `runTimestamp`, `taskType`, `status`, `teamStatePath`, `taskRootPath`. Both path fields may be either project-root-relative or task-root-relative depending on which `render.py` version wrote the manifest.
+1. `.okstra/tasks/<task-group>/<task-id>/history/timeline.json` — `runs` array with `runTimestamp`, `taskType`, `status`, `teamStatePath`, `taskRootPath`. Both path fields may be either project-root-relative or task-root-relative depending on which `render.py` version wrote the manifest.
 2. Each run's `.../runs/<task-type>/state/team-state-<suffix>.json` — populated by `scripts/okstra-token-usage.py` at Phase 7. Contains `leadUsage.{startedAt, endedAt, durationMs}` and `workers[].{workerId, agent, usage.{startedAt, endedAt, durationMs}}`.
 
 If a run never reached Phase 7, its `team-state` lacks `durationMs`. Mark such runs as `unavailable` rather than guessing.
@@ -355,7 +355,7 @@ If a run never reached Phase 7, its `team-state` lacks `durationMs`. Mark such r
 ### time.1 — Resolve task-id → timeline path
 
 1. If the user gave a full `task-key`, use it directly.
-2. Otherwise read `.project-docs/okstra/discovery/task-catalog.json` and find the entry whose `taskId` matches.
+2. Otherwise read `.okstra/discovery/task-catalog.json` and find the entry whose `taskId` matches.
 3. Multiple matches → list candidates (`taskKey`, `taskType`, `updatedAt`) and ask the user to pick.
 4. Read `historyTimelinePath` from the chosen entry.
 
@@ -476,7 +476,7 @@ Read-only inventory of codex/gemini wrapper log files written next to each promp
 **Background:** codex/gemini wrappers (`okstra-codex-exec.sh`, `okstra-gemini-exec.sh`) write a sidecar log next to each prompt history file:
 
 ```
-.project-docs/okstra/tasks/<task-group>/<task-id>/runs/<phase>/prompts/
+.okstra/tasks/<task-group>/<task-id>/runs/<phase>/prompts/
   <worker>-prompt-<phase>-<seq>.md    <-- prompt (git-tracked)
   <worker>-prompt-<phase>-<seq>.log   <-- live stdout+stderr mirror
 ```
@@ -485,7 +485,7 @@ The log is truncated at each dispatch (`: > "$log_path"`) — only the latest ru
 
 ### logs.1 — Inventory
 
-Construct the logs root by appending `/.project-docs/okstra/tasks` to the literal `projectRoot` value parsed in Step 0; paste as a literal absolute path in place of `<LOGS_ROOT>` below (no shell variables, no `$(...)`):
+Construct the logs root by appending `/.okstra/tasks` to the literal `projectRoot` value parsed in Step 0; paste as a literal absolute path in place of `<LOGS_ROOT>` below (no shell variables, no `$(...)`):
 
 ```bash
 find <LOGS_ROOT> -type f -path '*/runs/*/prompts/*.log' \
@@ -529,33 +529,33 @@ Emit a fenced bash block the user can copy-paste. Do NOT execute. Each block pai
 ## Cleanup options (manual)
 
 # 7일 이상 된 로그만 삭제
-find <PROJECT_ROOT>/.project-docs/okstra/tasks \
+find <PROJECT_ROOT>/.okstra/tasks \
   -type f -path '*/runs/*/prompts/*.log' -mtime +7 -print    # dry-run
-find <PROJECT_ROOT>/.project-docs/okstra/tasks \
+find <PROJECT_ROOT>/.okstra/tasks \
   -type f -path '*/runs/*/prompts/*.log' -mtime +7 -delete
 
 # 30일 이상 된 로그만 삭제
-find <PROJECT_ROOT>/.project-docs/okstra/tasks \
+find <PROJECT_ROOT>/.okstra/tasks \
   -type f -path '*/runs/*/prompts/*.log' -mtime +30 -print   # dry-run
-find <PROJECT_ROOT>/.project-docs/okstra/tasks \
+find <PROJECT_ROOT>/.okstra/tasks \
   -type f -path '*/runs/*/prompts/*.log' -mtime +30 -delete
 
 # 특정 task-group 의 로그 일괄 삭제 (예: dev-9388)
-find <PROJECT_ROOT>/.project-docs/okstra/tasks/dev-9388 \
+find <PROJECT_ROOT>/.okstra/tasks/dev-9388 \
   -type f -name '*.log' -print    # dry-run
-find <PROJECT_ROOT>/.project-docs/okstra/tasks/dev-9388 \
+find <PROJECT_ROOT>/.okstra/tasks/dev-9388 \
   -type f -name '*.log' -delete
 
 # 특정 task-id 의 로그 일괄 삭제 (예: dev-9428)
-find <PROJECT_ROOT>/.project-docs/okstra/tasks/*/dev-9428 \
+find <PROJECT_ROOT>/.okstra/tasks/*/dev-9428 \
   -type f -name '*.log' -print    # dry-run
-find <PROJECT_ROOT>/.project-docs/okstra/tasks/*/dev-9428 \
+find <PROJECT_ROOT>/.okstra/tasks/*/dev-9428 \
   -type f -name '*.log' -delete
 
 # 전체 일괄 삭제 (주의)
-find <PROJECT_ROOT>/.project-docs/okstra/tasks \
+find <PROJECT_ROOT>/.okstra/tasks \
   -type f -path '*/runs/*/prompts/*.log' -print    # dry-run
-find <PROJECT_ROOT>/.project-docs/okstra/tasks \
+find <PROJECT_ROOT>/.okstra/tasks \
   -type f -path '*/runs/*/prompts/*.log' -delete
 ```
 
@@ -566,7 +566,7 @@ Substitute the literal `<PROJECT_ROOT>` with the resolved absolute path so the c
 - Logs are truncated on each re-dispatch of the same `seq`, so deleting an in-flight run's log will cause the wrapper to recreate an empty file on the next dispatch — no data loss beyond the current trace.
 - **If a dispatch is currently running, check the `status` sub-command first** and avoid deleting logs for tasks in `in-progress` state — you will lose the live trace for the active run.
 - Prompt history files (`.md`) are separate and are NOT touched by these commands — only `.log` sidecars.
-- This sub-command **does not modify any external files itself**, including `.gitignore`. If the project commits `.project-docs/okstra/`, the user may want to add `.project-docs/okstra/tasks/**/runs/**/prompts/*.log` to `.gitignore` manually to keep large logs out of git.
+- This sub-command **does not modify any external files itself**, including `.gitignore`. If the project commits `.okstra/`, the user may want to add `.okstra/tasks/**/runs/**/prompts/*.log` to `.gitignore` manually to keep large logs out of git.
 
 ---
 

package/runtime/skills/okstra-run/templates/pr-body.template.md

@@ -3,7 +3,7 @@ okstra release-handoff 기본 PR 본문 템플릿.
 
 이 파일은 사용자 정의 PR 템플릿이 없을 때 사용됩니다. 우선순위:
   1. okstra-run Step 6 에서 입력한 per-run override 경로
-  2. <project-root>/.project-docs/okstra/project.json 의 `prTemplatePath`
+  2. <project-root>/.okstra/project.json 의 `prTemplatePath`
   3. ~/.okstra/config.json 의 `prTemplatePath`
   4. 이 디폴트 파일
 

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

@@ -8,7 +8,7 @@ model: opus
 
 ## Overview
 
-Generate a consolidated work schedule for all non-done tasks in a given `task-group`. The skill reads each task's `task-manifest.json` and `latestReport`, classifies tasks into phases by priority and risk, and writes a single Markdown plan file under `.project-docs/okstra/tasks/<task-group>/schedule/`.
+Generate a consolidated work schedule for all non-done tasks in a given `task-group`. The skill reads each task's `task-manifest.json` and `latestReport`, classifies tasks into phases by priority and risk, and writes a single Markdown plan file under `.okstra/tasks/<task-group>/schedule/`.
 
 The skill runs as a single Claude lead synthesis (lightweight mode). A `--cross-verify` multi-agent variant was previously sketched here but never specified end-to-end; it has been dropped pre-1.0 and is tracked as a follow-up if multi-agent schedule verification is needed later.
 
@@ -16,7 +16,7 @@ The skill runs as a single Claude lead synthesis (lightweight mode). A `--cross-
 
 - User asks to generate a work schedule / plan / "일정" for an entire `task-group`
 - User wants a single document that summarizes all non-done tasks with effort, risk, and dependencies
-- A `task-group` exists in `.project-docs/okstra/discovery/task-catalog.json` with at least one task whose `workStatus` is not `done`
+- A `task-group` exists in `.okstra/discovery/task-catalog.json` with at least one task whose `workStatus` is not `done`
 
 **Do NOT use** for single-task analysis (use `okstra-inspect status` instead) or when the user wants to actually execute one task (use the parent `okstra` skill).
 
@@ -46,7 +46,7 @@ Before anything else in this skill, run each of the following commands as a **se
    Reads the project from the current working directory. Parse the JSON from stdout. The shape is `{ok, projectRoot, projectJsonPath, projectId}`.
 
    - `ok: false` → tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
-   - `ok: true` → carry `projectRoot` as a literal string and use it to locate `.project-docs/okstra/discovery/task-catalog.json` and the task-group directory.
+   - `ok: true` → carry `projectRoot` as a literal string and use it to locate `.okstra/discovery/task-catalog.json` and the task-group directory.
 
 Subsequent `okstra <subcmd>` calls self-bootstrap their Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
 
@@ -68,10 +68,10 @@ This skill performs cross-task synthesis (multi-task classification, dependency
 
 ### Step 1: Resolve task-group and collect tasks
 
-1. Read `.project-docs/okstra/discovery/task-catalog.json`.
+1. Read `.okstra/discovery/task-catalog.json`.
 2. **Normalise the user-supplied `<task-group>` argument:** lowercase it, then strip every character that is not `[a-z0-9]` (drop spaces, hyphens, underscores, dots, etc.). Apply the same transform to each entry's `taskGroupPathSegment`. Match when the two normalised forms are equal. This is the single comparison rule — do NOT also fall back to the raw `taskGroup` field.
 3. If no tasks found, output `해당 task-group을 찾을 수 없습니다.` and stop.
-4. For each matched task, read `.project-docs/okstra/tasks/<task-group-segment>/<task-id-segment>/task-manifest.json` directly. Catalog data may be stale; the manifest is authoritative.
+4. For each matched task, read `.okstra/tasks/<task-group-segment>/<task-id-segment>/task-manifest.json` directly. Catalog data may be stale; the manifest is authoritative.
 5. **Derive `<project-id>`** for the schedule header: prefer `task-catalog.json`'s top-level `projectId` field if present, otherwise use the first matched manifest's `projectId` field. Do not invent a value.
 
 ### Step 2: Filter by workStatus
@@ -157,7 +157,7 @@ When the classification is genuinely ambiguous after applying the table + priori
 
 Output path:
 ```
-.project-docs/okstra/tasks/<task-group-segment>/schedule/<task-group-segment>-plan-<YYYY-MM-DD_HH-MM-SS>.md
+.okstra/tasks/<task-group-segment>/schedule/<task-group-segment>-plan-<YYYY-MM-DD_HH-MM-SS>.md
 ```
 
 - `<task-group-segment>`: from manifest's `taskGroupPathSegment` (lowercase, hyphenated).
@@ -322,7 +322,7 @@ Before applying the heuristics above, **check the schedule-level directive sourc
 **Resolution order (first hit wins):**
 
 1. Absolute path passed via the `--directive-file <abs-path>` argument when invoking the skill.
-2. `<PROJECT_ROOT>/.project-docs/okstra/tasks/<task-group-segment>/schedule/instruction-set/analysis-material.md` (the canonical schedule-level instruction-set location — okstra writes here when a schedule run is dispatched with `--directive`).
+2. `<PROJECT_ROOT>/.okstra/tasks/<task-group-segment>/schedule/instruction-set/analysis-material.md` (the canonical schedule-level instruction-set location — okstra writes here when a schedule run is dispatched with `--directive`).
 3. **No directive file** — fall through and apply the default heuristic without any override. This is the normal case; do not warn, do not block.
 
 If a directive source is found and contains a `## Directive` section that affects Gantt rendering — e.g. "render a Gantt even with single XL task", "no Gantt needed" — that directive **overrides the heuristic and the skip-reason rule** for the affected section. When following a Directive override that contradicts the default heuristic, append a one-line note inside the rendered (or skipped) section: `> _Per Directive directive: <verbatim short excerpt>._` so the reader can trace why the section appeared/disappeared against the default. The Directive may also pre-supply day allocations, phase weights, or sub-task decompositions — use those verbatim as bar lengths in the Gantt.

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

@@ -1,6 +1,6 @@
 ---
 name: okstra-setup
-description: One-time bootstrap for okstra in a new project or on a new machine — installs the okstra runtime via npx and creates the project's .project-docs/okstra/project.json. Trigger words include "okstra setup", "setup okstra", "initialize okstra", "okstra init", "first time okstra setup", "configure okstra here".
+description: One-time bootstrap for okstra in a new project or on a new machine — installs the okstra runtime via npx and creates the project's .okstra/project.json. Trigger words include "okstra setup", "setup okstra", "initialize okstra", "okstra init", "first time okstra setup", "configure okstra here".
 ---
 
 # okstra-setup
@@ -11,7 +11,7 @@ machine, or when adopting okstra in a new project.
 ## When to use
 
 - `~/.okstra/version` is missing or stale → okstra runtime is not installed yet.
-- The current project has no `.project-docs/okstra/project.json` yet.
+- The current project has no `.okstra/project.json` yet.
 - The user says "set up okstra here", "first time", "okstra init", etc.
 
 ## When NOT to use
@@ -76,7 +76,7 @@ Parse the JSON from stdout. The shape is `{ok, projectRoot, projectJsonPath, pro
 
 ## Step 4: Inspect or create `project.json`
 
-Use the `Read` tool on the literal absolute path `<projectRoot>/.project-docs/okstra/project.json` (substitute the literal `projectRoot` value parsed in Step 3). If `Read` errors with "file does not exist", treat that as the "create" branch below; otherwise the file exists and you can inspect its contents inline.
+Use the `Read` tool on the literal absolute path `<projectRoot>/.okstra/project.json` (substitute the literal `projectRoot` value parsed in Step 3). If `Read` errors with "file does not exist", treat that as the "create" branch below; otherwise the file exists and you can inspect its contents inline.
 
 If the file exists, surface its `projectId`/`projectRoot` and ask whether to
 keep or overwrite. Default is to keep — okstra refuses to change `projectId`
@@ -112,7 +112,7 @@ directories is symlinked from the main checkout into that worktree so
 every task sees the shared state. The built-in default is
 `.project-docs`, `.scratch`, `graphify-out`, `.claude`.
 Syncing a directory does not make it okstra memory; okstra-owned context
-and writes still stay under `<PROJECT_ROOT>/.project-docs/okstra/**`
+and writes still stay under `<PROJECT_ROOT>/.okstra/**`
 unless the task brief explicitly authorizes a non-okstra path.
 
 To override per-project, add a `worktreeSyncDirs` array to
@@ -231,7 +231,7 @@ okstra-run prompt convention):
 
 - **Question**: `"이 프로젝트에서 release-handoff 가 사용할 PR 본문 템플릿을 등록할까요?"`
 - **Options**:
-  1. `이번 프로젝트만 (project scope)` — write to `<PROJECT_ROOT>/.project-docs/okstra/project.json` `prTemplatePath`.
+  1. `이번 프로젝트만 (project scope)` — write to `<PROJECT_ROOT>/.okstra/project.json` `prTemplatePath`.
   2. `전역 (global scope)` — write to `~/.okstra/config.json` `prTemplatePath`.
   3. `나중에` — skip.
 
@@ -292,7 +292,7 @@ the output and let the user decide whether to re-run install or skip.
 Inform the user with a short summary:
 
 > okstra is ready. Runtime: `~/.okstra` (version stamp). Project metadata:
-> `<PROJECT_ROOT>/.project-docs/okstra/project.json` (`projectId`). Run
+> `<PROJECT_ROOT>/.okstra/project.json` (`projectId`). Run
 > `/okstra-run` to start your first task.
 
 ## Failure modes
@@ -302,7 +302,7 @@ Inform the user with a short summary:
 | `command not found: npx` | Node missing | Install node 18+. |
 | `okstra ensure-installed` keeps reinstalling | `~/.okstra/version` write fails (permissions) | Check `~/.okstra` ownership and writability. |
 | `error: --project-id is required (no existing project.json, not a TTY)` | `okstra setup --yes` invoked without `--project-id`, or with empty answer to Step 4 prompt | Re-ask Step 4 and pass a non-empty id via `--project-id`. |
-| `projectId mismatch` / `projectId 불일치` | `project.json` already exists with a different id | Decide which id is canonical; manually delete `<PROJECT_ROOT>/.project-docs/okstra/project.json` to re-register, or re-run with the existing id. |
-| `EACCES` writing under `.project-docs/okstra/` | directory owned by another user (e.g. created by a previous root-shell run) | `chown -R "$USER" <PROJECT_ROOT>/.project-docs` or delete and let setup recreate. |
+| `projectId mismatch` / `projectId 불일치` | `project.json` already exists with a different id | Decide which id is canonical; manually delete `<PROJECT_ROOT>/.okstra/project.json` to re-register, or re-run with the existing id. |
+| `EACCES` writing under `.okstra/` | directory owned by another user (e.g. created by a previous root-shell run) | `chown -R "$USER" <PROJECT_ROOT>/.project-docs` or delete and let setup recreate. |
 | `warning: failed to provision .claude/settings.local.json symlink` | a non-symlink `.claude/settings.local.json` already exists and the backup-and-replace step failed | Inspect `<PROJECT_ROOT>/.claude/settings.local.json{,.bak.*}`; manually merge project-specific rules, then re-run setup. |
 | `npx okstra@latest install` succeeds but `doctor` shows FAIL | runtime/{python,bin,skills} sync not yet performed (pre-release package) | Use dev install: clone the repo and run `node bin/okstra install --link <repo>`. |

package/runtime/templates/okstra.CLAUDE.md

@@ -3,7 +3,7 @@
 This file is shipped by `okstra install` and surfaced into the active project
 through two channels by `okstra setup`:
 
-- **Claude Code**: `<PROJECT>/CLAUDE.md` gets an `@.project-docs/okstra/CLAUDE.md`
+- **Claude Code**: `<PROJECT>/CLAUDE.md` gets an `@.okstra/CLAUDE.md`
   import block (per-project symlink to this template). Existing user content
   in `CLAUDE.md` is preserved — the block lives between
   `<!-- okstra:claude-md:begin ... -->` markers.
@@ -14,7 +14,7 @@ through two channels by `okstra setup`:
 It is **owned by the okstra package**: every `okstra install` overwrites
 `~/.okstra/templates/okstra.CLAUDE.md` from the version currently on disk in
 the npm package. Edits made directly to this file (or to the per-project
-`<PROJECT>/.project-docs/okstra/CLAUDE.md` / `<PROJECT>/AGENTS.md` symlinks)
+`<PROJECT>/.okstra/CLAUDE.md` / `<PROJECT>/AGENTS.md` symlinks)
 will be lost on the next install. Put project-specific overrides outside the
 managed block in `<PROJECT>/CLAUDE.md` instead (or replace `AGENTS.md` with
 your own file — okstra will respect it).
@@ -30,7 +30,7 @@ through slash commands inside a Claude Code session.
 
 | Command | When to use |
 | --- | --- |
-| `/okstra-setup` | First-time bootstrap in a new project — writes `.project-docs/okstra/project.json`, provisions `.claude/settings.local.json` and `.project-docs/okstra/CLAUDE.md`. |
+| `/okstra-setup` | First-time bootstrap in a new project — writes `.okstra/project.json`, provisions `.claude/settings.local.json` and `.okstra/CLAUDE.md`. |
 | `/okstra-brief` | Turn a requirements doc / ticket / link / conversation into the markdown task brief consumed by `okstra-run`. |
 | `/okstra-run` | Start a cross-verification task in the current session. Drives the interactive wizard. |
 | `/okstra-status` | Inspect overall okstra task status, current phase, blockers, next recommended phase. Also flips a task's workStatus (todo / in-progress / blocked / done). |
@@ -55,7 +55,7 @@ Type the slash command — do not paraphrase the trigger words into prose.
   duplicate those permissions in the user's global `~/.claude/settings.json`.
 - Each okstra run provisions a task-scoped git worktree under
   `~/.okstra/worktrees/`. Files synced from the main checkout are governed by
-  `worktreeSyncDirs` in `.project-docs/okstra/project.json` (default:
+  `worktreeSyncDirs` in `.okstra/project.json` (default:
   `.project-docs`, `.scratch`, `graphify-out`, `.claude`).
 - QA gating is configured via `qaCommands` in the same `project.json`.
   Verifiers reject mutation-style commands (`--fix`, `--write`, `cargo update`,

package/runtime/templates/reports/brief.template.md

@@ -105,14 +105,14 @@ handle it. Free-form rows are allowed only as `general:`.
 Allowed signals:
 - `general: <unresolved question the user flagged>`
 - `terminology: <reporter word> — needs canonical resolution against
-  <PROJECT_ROOT>/.project-docs/okstra/glossary.md`
+  <PROJECT_ROOT>/.okstra/glossary.md`
 - `intent-check: <restated inference> — confirm with reporter`
   (auto-paired with every `intent-inference` augmentation)
 - `conversion-block: <reporter statement> — could not be mapped to project
   vocabulary; reporter query required`
 - `adr-candidate: <topic>` — signal only; `implementation-planning`
   evaluates and, if accepted, drafts a decision file at
-  `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`.
+  `<PROJECT_ROOT>/.okstra/decisions/<NNNN>-<slug>.md`.
 
 Use `_(none)_` only if every signal is empty. `intent-check:` and
 `conversion-block:` rows that are answered in Step 6.5 are NOT removed
@@ -156,17 +156,17 @@ Every entry below must start with one of the four labels:
 <!-- author guidance — strip out at fill-in time:
 Observations from Step 3b and the outcome of Step 4.5 (glossary applied
 vs. skipped). The actual glossary edits live in
-`<PROJECT_ROOT>/.project-docs/okstra/glossary.md` when applied; this
+`<PROJECT_ROOT>/.okstra/glossary.md` when applied; this
 section records what happened. Decision candidates are NOT recorded here —
 they flow through `Open Questions` as `adr-candidate:` rows for
 `implementation-planning` to evaluate (and, if accepted, draft into
-`<PROJECT_ROOT>/.project-docs/okstra/decisions/`).
+`<PROJECT_ROOT>/.okstra/decisions/`).
 
 Allowed entry shapes:
 - `terminology-mapping: <reporter word> → <okstra glossary canonical>` —
   routine glossary alignment, paired with `terminology:` in Open Questions
   when unresolved.
-- `terminology-mapping: applied glossary: <term> → <PROJECT_ROOT>/.project-docs/okstra/glossary.md`
+- `terminology-mapping: applied glossary: <term> → <PROJECT_ROOT>/.okstra/glossary.md`
 - `terminology-mapping: skipped glossary: <term> = <definition>` —
   Step 4.5 outcomes.
 Use `_(none)_` if every alignment entry is empty.

package/runtime/templates/reports/task-brief.template.md

@@ -145,7 +145,7 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Available MCP Servers
 
-The MCP servers available to this run are declared in `.project-docs/okstra/project.json`'s `mcpServers` array and rendered into the Claude lead's launch prompt under `## Available MCP Servers`. They may be invoked **as needed** by Claude lead, Claude worker, and Report writer worker. The lead is responsible for forwarding the rendered list verbatim into the worker prompts (Phase 2) so workers know which tools they are allowed to call.
+The MCP servers available to this run are declared in `.okstra/project.json`'s `mcpServers` array and rendered into the Claude lead's launch prompt under `## Available MCP Servers`. They may be invoked **as needed** by Claude lead, Claude worker, and Report writer worker. The lead is responsible for forwarding the rendered list verbatim into the worker prompts (Phase 2) so workers know which tools they are allowed to call.
 
 To declare servers, add entries shaped `{ "name": "<server>", "description": "...", "tools": ["..."], "notes": "..." }` to that array. If the array is empty or absent, treat MCP as unavailable for this run.
 

package/runtime/validators/lib/fixtures.sh

@@ -52,11 +52,11 @@ write_validation_brief() {
 - Config file: \`.claude/settings.json\`
   - Expected values:
     - installed okstra Claude assets must remain discoverable under \`~/.claude/skills/\` and \`~/.claude/agents/\` (managed by \`okstra install\`)
-- Config file: \`.project-docs/okstra/discovery/latest-task.json\`
+- Config file: \`.okstra/discovery/latest-task.json\`
   - Expected values:
     - latest prepared task pointer must include the current task key
     - task catalog path must be present
-- Config file: \`.project-docs/okstra/discovery/task-catalog.json\`
+- Config file: \`.okstra/discovery/task-catalog.json\`
   - Expected values:
     - task catalog must preserve prepared task bundles by task key
     - task catalog must allow task-group and task-id level distinction

package/runtime/validators/lib/paths.sh

@@ -1,5 +1,11 @@
 # shellcheck shell=bash
 
+# Single source of truth for the okstra-relative directory name in shell code.
+# Python (okstra_project/dirs.py) 와 Node (src/okstra-dirs.mjs) 와 같은 값을
+# 유지해야 한다. 디렉토리 이름을 바꾸려면 세 곳의 한 줄씩만 수정.
+OKSTRA_DIR="${OKSTRA_DIR:-.okstra}"
+LEGACY_OKSTRA_DIR=".project-docs/okstra"
+
 validate_project_root_safety() {
   if [[ -z "${PROJECT_ROOT:-}" ]]; then
     fail "PROJECT_ROOT is not defined"
@@ -26,19 +32,19 @@ task_root() {
   local task_group="$1"
   local task_id="$2"
 
-  printf '%s/.project-docs/okstra/tasks/%s/%s\n' "$PROJECT_ROOT" "$task_group" "$task_id"
+  printf '%s/%s/tasks/%s/%s\n' "$PROJECT_ROOT" "$OKSTRA_DIR" "$task_group" "$task_id"
 }
 
 task_manifest_relative_path() {
   local task_group="$1"
   local task_id="$2"
 
-  printf '.project-docs/okstra/tasks/%s/%s/task-manifest.json\n' "$task_group" "$task_id"
+  printf '%s/tasks/%s/%s/task-manifest.json\n' "$OKSTRA_DIR" "$task_group" "$task_id"
 }
 
 reference_expectations_relative_path() {
   local task_group="$1"
   local task_id="$2"
 
-  printf '.project-docs/okstra/tasks/%s/%s/instruction-set/reference-expectations.md\n' "$task_group" "$task_id"
+  printf '%s/tasks/%s/%s/instruction-set/reference-expectations.md\n' "$OKSTRA_DIR" "$task_group" "$task_id"
 }

package/runtime/validators/validate-brief.py

@@ -10,7 +10,7 @@ Checks performed per brief file:
 4. Every Open Questions row starts with one of the five signal prefixes
    (general | terminology | intent-check | conversion-block | adr-candidate).
    `adr-candidate:` targets okstra-internal
-   `<PROJECT_ROOT>/.project-docs/okstra/decisions/`, not external `docs/adr/`.
+   `<PROJECT_ROOT>/.okstra/decisions/`, not external `docs/adr/`.
 5. Every Augmentation entry (inline `> augmented: <label>` blockquotes and
    `Augmentation` section bullets) carries one of the four labels
    (evidence-link | format-conversion | terminology-mapping | intent-inference).
@@ -342,7 +342,7 @@ def main(argv: list[str] | None = None) -> int:
         default=None,
         help=(
             "Root used for depth computation (defaults to briefs_dir). "
-            "Usually `<PROJECT_ROOT>/.project-docs/okstra/briefs`."
+            "Usually `<PROJECT_ROOT>/.okstra/briefs`."
         ),
     )
     args = parser.parse_args(argv)

package/runtime/validators/validate-brief.sh

@@ -6,7 +6,7 @@
 #   validators/validate-brief.sh <briefs-dir> [--briefs-root <dir>]
 #
 # Typical invocation (inside a project that has run okstra-setup):
-#   validators/validate-brief.sh "$PROJECT_ROOT/.project-docs/okstra/briefs"
+#   validators/validate-brief.sh "$PROJECT_ROOT/.okstra/briefs"
 #
 # Thin bash entrypoint — delegates to validate-brief.py for content checks.
 

package/runtime/validators/validate-run.py

@@ -29,6 +29,8 @@ except ImportError:  # pragma: no cover — runtime guarantees this import
     load_schema = None  # type: ignore[assignment]
     schema_validate = None  # type: ignore[assignment]
 
+from okstra_project.dirs import tasks_root as _okstra_tasks_root  # noqa: E402
+
 TERMINAL_STATUSES = {"completed", "timeout", "error", "not-run"}
 ATTEMPTED_STATUSES = {"completed", "timeout", "error"}
 
@@ -1317,7 +1319,7 @@ def _refresh_task_catalog(project_root: Path, task_manifest: dict) -> tuple[bool
     except Exception as exc:  # noqa: BLE001
         return False, f"okstra_ctl import failed: {exc}"
 
-    tasks_root = (project_root / ".project-docs" / "okstra" / "tasks").resolve()
+    tasks_root = _okstra_tasks_root(project_root).resolve()
     catalog_path = (project_root / catalog_relative).resolve()
     ctx = {
         "PROJECT_ROOT": str(project_root),

package/runtime/validators/validate-workflow.sh

@@ -24,13 +24,13 @@ PRIMARY_BRIEF_FILENAME="validation-brief-primary.md"
 SECONDARY_TASK_GROUP="discovery"
 SECONDARY_TASK_ID="task-catalog"
 SECONDARY_BRIEF_FILENAME="validation-brief-secondary.md"
-LATEST_TASK_RELATIVE_PATH=".project-docs/okstra/discovery/latest-task.json"
-TASK_CATALOG_RELATIVE_PATH=".project-docs/okstra/discovery/task-catalog.json"
 
 # shellcheck source=lib/common.sh
 source "$SCRIPT_DIR/lib/common.sh"
 # shellcheck source=lib/paths.sh
 source "$SCRIPT_DIR/lib/paths.sh"
+LATEST_TASK_RELATIVE_PATH="$OKSTRA_DIR/discovery/latest-task.json"
+TASK_CATALOG_RELATIVE_PATH="$OKSTRA_DIR/discovery/task-catalog.json"
 # shellcheck source=lib/fixtures.sh
 source "$SCRIPT_DIR/lib/fixtures.sh"
 # shellcheck source=lib/runners.sh

package/src/check-project.mjs

@@ -1,13 +1,13 @@
 import { promises as fs } from "node:fs";
 import { spawn } from "node:child_process";
 import { join } from "node:path";
-import { resolvePaths } from "./paths.mjs";
+import { buildPythonpath, resolvePaths } from "./paths.mjs";
 
 const USAGE = `okstra check-project — verify that the current project has okstra setup
 
 Usage:
   okstra check-project              Resolve PROJECT_ROOT from cwd, look for
-                                    .project-docs/okstra/project.json,
+                                    .okstra/project.json,
                                     print JSON status to stdout.
   okstra check-project --cwd <dir>  Use <dir> as the search starting point
                                     instead of process cwd.
@@ -99,7 +99,7 @@ export async function run(args) {
       ].join("\n"),
       opts.cwd,
     ],
-    { PYTHONPATH: paths.pythonpath },
+    { PYTHONPATH: buildPythonpath(paths) },
   );
 
   if (probe.code !== 0) {

package/src/config.mjs

@@ -2,12 +2,13 @@ import { promises as fs } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve, isAbsolute } from "node:path";
 import { spawn } from "node:child_process";
-import { resolvePaths } from "./paths.mjs";
+import { buildPythonpath, resolvePaths } from "./paths.mjs";
+import { OKSTRA_DIR, projectJsonPath } from "./okstra-dirs.mjs";
 
 const USAGE = `okstra config — read / write okstra settings (project + global scopes)
 
 Settings are persisted as JSON keys in one of two files:
-  project: <project-root>/.project-docs/okstra/project.json
+  project: <project-root>/${OKSTRA_DIR}/project.json
   global:  ~/.okstra/config.json
 
 Supported keys (CLI alias -> JSON field):
@@ -132,7 +133,7 @@ function globalConfigPath() {
 }
 
 function projectConfigPath(projectRoot) {
-  return join(projectRoot, ".project-docs", "okstra", "project.json");
+  return projectJsonPath(projectRoot);
 }
 
 async function fileExists(p) {
@@ -193,7 +194,7 @@ async function resolveProjectRoot(cwd) {
       ].join("\n"),
       cwd,
     ],
-    { PYTHONPATH: paths.pythonpath },
+    { PYTHONPATH: buildPythonpath(paths) },
   );
   if (result.code === 0) return result.stdout.trim();
   return null;
@@ -229,7 +230,7 @@ async function effectivePrTemplatePath(projectRoot) {
       ].join("\n"),
       projectRoot ?? process.cwd(),
     ],
-    { PYTHONPATH: paths.pythonpath },
+    { PYTHONPATH: buildPythonpath(paths) },
   );
   if (result.code !== 0) return null;
   try {

package/src/install.mjs

@@ -15,8 +15,8 @@ const SETTINGS_TEMPLATE_SRC_REL = ["templates", "reports", "settings.template.js
 // Destination under ~/.okstra/. Project-local .claude/settings.local.json symlinks here.
 const SETTINGS_TEMPLATE_DST_REL = ["templates", "settings.local.json"];
 
-// okstra-managed CLAUDE.md template. Per-project <PROJECT>/.project-docs/okstra/CLAUDE.md
-// symlinks here; <PROJECT>/CLAUDE.md gets an `@.project-docs/okstra/CLAUDE.md` import line.
+// okstra-managed CLAUDE.md template. Per-project <PROJECT>/.okstra/CLAUDE.md
+// symlinks here; <PROJECT>/CLAUDE.md gets an `@.okstra/CLAUDE.md` import line.
 const CLAUDE_MD_TEMPLATE_REL = ["templates", "okstra.CLAUDE.md"];
 
 const PYTHON_PACKAGES = ["okstra_project", "okstra_ctl", "okstra_token_usage", "okstra_vendor", "lib"];
@@ -70,8 +70,8 @@ provisions, granting per-project Claude Code permissions for okstra
 worker wrapper scripts without modifying the user's global settings.
 
 The okstra.CLAUDE.md file is the symlink target referenced by every
-project-local <project>/.project-docs/okstra/CLAUDE.md that okstra-setup provisions;
-<project>/CLAUDE.md gets an "@.project-docs/okstra/CLAUDE.md" import block so Claude
+project-local <project>/.okstra/CLAUDE.md that okstra-setup provisions;
+<project>/CLAUDE.md gets an "@.okstra/CLAUDE.md" import block so Claude
 Code automatically picks up the okstra runtime guidance.
 
 Worker agent definitions are installed into ${"$HOME"}/.claude/agents/ so
@@ -579,7 +579,7 @@ export async function runInstall(args) {
   );
   // templates/ tree — report.css / report.js / *.template.md / okstra.CLAUDE.md
   // are consumed at runtime by okstra-render-report-views.py, final-report
-  // assembly, and the per-project .project-docs/okstra/CLAUDE.md symlink provisioned by
+  // assembly, and the per-project .okstra/CLAUDE.md symlink provisioned by
   // setup. They are NOT covered by installNamedTemplate (which only handles
   // the renamed settings.local.json sidecar), so without this step copy-mode
   // installs miss every asset other than that single file. See