okstra 0.36.1 → 0.37.0

package/README.kr.md

@@ -79,7 +79,7 @@ okstra/                          npm 패키지 = repo 루트
 └── {claude,codex,gemini,report-writer}-worker.md   worker subagent 정의
                                  (multi-agent dispatch 필수)
 
-<프로젝트 루트>/.project-docs/okstra/
+<프로젝트 루트>/.okstra/
 ├── project.json                 {projectId, projectRoot, ...} (`/okstra-setup` 이 작성)
 ├── discovery/{task-catalog,latest-task}.json
 ├── glossary.md                  okstra-owned project terminology
@@ -95,7 +95,7 @@ okstra/                          npm 패키지 = repo 루트
 | agents/prompts/schemas/templates/validators | npm 패키지의 `runtime/` | `okstra` 패키지 자체 (`okstra paths` 로 해석) |
 | 스킬 마크다운 | `~/.claude/skills/<name>/SKILL.md` | `okstra install` (`installed-skills.json` 에 트래킹) |
 | 워커 에이전트 마크다운 | `~/.claude/agents/<worker>.md` | `okstra install` (`installed-agents.json` 에 트래킹) |
-| 프로젝트 메타데이터 | `<project>/.project-docs/okstra/` | `/okstra-setup` + 프로젝트 자체 |
+| 프로젝트 메타데이터 | `<project>/.okstra/` | `/okstra-setup` + 프로젝트 자체 |
 | Run 인덱스 | `~/.okstra/{recent,active}.jsonl` | `prepare_task_bundle` |
 
 ## 3. 사용 매뉴얼
@@ -145,7 +145,7 @@ npx -y okstra@latest setup --project-id <id>     # 예: INV-1234, my-app, okstra
 /okstra-setup
 ```
 
-둘 다 `<project>/.project-docs/okstra/project.json` 을 작성합니다. CLI 는 `--project-id` 가 주어지면 non-interactive 로 동작하므로 CI 에서 사용할 수 있고, 슬래시 커맨드는 `AskUserQuestion` 으로 prompt 합니다. 이 파일이 존재하기 전에는 다른 모든 사용자 스킬이 실행을 거부합니다.
+둘 다 `<project>/.okstra/project.json` 을 작성합니다. CLI 는 `--project-id` 가 주어지면 non-interactive 로 동작하므로 CI 에서 사용할 수 있고, 슬래시 커맨드는 `AskUserQuestion` 으로 prompt 합니다. 이 파일이 존재하기 전에는 다른 모든 사용자 스킬이 실행을 거부합니다.
 
 ### 3.3 일상 명령
 
@@ -187,12 +187,12 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 
 - **모든 task-type 격리 worktree 자동 provisioning** — prepare 단계에서 `okstra-ctl` 이 task-key 당 한 번 `git worktree add ~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>` 를 수행해 격리된 working tree 와 브랜치 `<work-category-prefix>-<task-id-segment>` (예: `feat-dev-9436`, `fix-dev-7311`) 를 만듭니다. base ref 는 사용자가 `--base-ref` 로 지정 (release-handoff PR base picker 와 동일한 메뉴: `main` / `dev` / `staging` / `preprod` / `prod` / 직접 입력). 첫 phase 에서는 필수이며, okstra-run skill 이 `AskUserQuestion` 으로 수집합니다 — 비대화형 호출자는 `--base-ref` 플래그를 직접 전달해야 prepare 가 통과합니다. 같은 task-key 의 모든 후속 phase(`requirements-discovery` → `error-analysis` → `implementation-planning` → `implementation` → `final-verification` → `release-handoff`)는 같은 path/branch를 재사용합니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 됩니다. 수동 cleanup: `git worktree remove <path>` → `git branch -D <branch>` + registry 항목 release/remove. 상세: [`docs/kr/architecture.md`](docs/kr/architecture.md) *Task type* 섹션, [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
 - **`release-handoff` lifecycle phase** — `final-verification` 이 `verdict=accepted` 를 반환한 직후에 실행되는 신규 phase. lead 가 Claude worker (drafter) 를 통해 commit message · PR body 후보를 만들고, `AskUserQuestion` 으로 사용자에게 (1) action (`commit only` / `commit + PR` / `skip`), (2) PR base branch (`staging` / `preprod` / `prod` / `main` / `dev` / 직접 입력), (3) message handling (`use as-is` / `edit then proceed` / `cancel`) 세 가지를 순서대로 묻습니다. 사용자가 메뉴로 선택한 git / gh 명령만 실행되고, force-push, base 브랜치 직접 push, hook bypass (`--no-verify`), release publish (`gh release`, `npm publish`, ...) 는 금지됩니다. 이 phase 에서는 소스 코드를 수정하지 않습니다. profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
-- **PR 본문 템플릿 설정** (release-handoff) — PR 본문은 마크다운 템플릿에서 채워집니다. 해석 우선순위: 1회성 override (`--pr-template-path` 또는 okstra-run Step 6 prompt) → `<project_root>/.project-docs/okstra/project.json` 의 `prTemplatePath` → `~/.okstra/config.json` 의 `prTemplatePath` → 스킬 디폴트 `~/.claude/skills/okstra-run/templates/pr-body.template.md`. 템플릿 등록 명령: `okstra config set pr-template-path <path> [--scope project|global]` (project 스코프는 project root 기준 상대경로 허용, global 스코프는 절대경로 또는 `~/` 시작 경로만 허용). 현재 설정 확인: `okstra config get pr-template-path --scope all` 은 각 스코프 값 + 실제로 우승하는 경로(effective) 까지 보여줍니다. 디폴트 템플릿은 `## Summary` / `## Changes` / `## Test plan` / `## Linked issues` 4 섹션 + HTML 주석으로 lead 작성 가이드를 포함하며, PR 생성 직전에 lead 가 주석을 제거합니다.
+- **PR 본문 템플릿 설정** (release-handoff) — PR 본문은 마크다운 템플릿에서 채워집니다. 해석 우선순위: 1회성 override (`--pr-template-path` 또는 okstra-run Step 6 prompt) → `<project_root>/.okstra/project.json` 의 `prTemplatePath` → `~/.okstra/config.json` 의 `prTemplatePath` → 스킬 디폴트 `~/.claude/skills/okstra-run/templates/pr-body.template.md`. 템플릿 등록 명령: `okstra config set pr-template-path <path> [--scope project|global]` (project 스코프는 project root 기준 상대경로 허용, global 스코프는 절대경로 또는 `~/` 시작 경로만 허용). 현재 설정 확인: `okstra config get pr-template-path --scope all` 은 각 스코프 값 + 실제로 우승하는 경로(effective) 까지 보여줍니다. 디폴트 템플릿은 `## Summary` / `## Changes` / `## Test plan` / `## Linked issues` 4 섹션 + HTML 주석으로 lead 작성 가이드를 포함하며, PR 생성 직전에 lead 가 주석을 제거합니다.
 - **프로파일 워커 로스터 검증** — `--workers <csv>` 와 okstra-run Step 6 의 워커 prompt 는 해당 프로파일의 `Required workers:` 블록에 선언된 워커 ID 만 허용합니다. 프로파일에 없는 워커 (예: `release-handoff` 에서 `codex` / `gemini`) 를 요청하면 명확한 에러로 거절되고, 인터랙티브 prompt 도 프로파일이 실제로 받는 워커만 보여줍니다.
 - **다단계 `implementation-planning` / `implementation`** — `implementation-planning` 은 항상 Stage Map + N 개 stage 섹션으로 산출합니다. 각 stage 의 step 은 ≤ 6 이며 `depends-on (none)` 인 stage 들은 별도 `implementation` run 으로 병렬 실행할 수 있습니다. 각 `implementation` 호출은 한 stage 만 실행하고 (`--stage <auto|N>`), 자동 생성되는 evidence sidecar (`carry/stage-<N>.json`) 가 다음 stage 의 carry-in 으로 흡수됩니다. `implementation-planning` run 디렉터리에 `consumers.jsonl` 역링크가 누적되어 어느 run 이 어느 stage 를 소비했는지 추적됩니다.
 - **Phase 6 plan-body verification (implementation-planning 전용)** — Report writer worker 가 final-report draft 를 작성한 직후, 사용자 승인 gate 직전에 lead 가 1 라운드의 사후 검증을 추가로 돌립니다. 합성된 `## 4.5` plan 본문에서 `P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*` plan-item 을 추출해 모든 analyser 워커에게 `AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT` 평결을 요청합니다. 집계된 gate 결과는 `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result` 중 하나. frontmatter `approved` 필드는 항상 `false` 로 발행되며, gate 가 `blocked-by-disagreement` 또는 `aborted-non-result` 일 때 writer 는 `approved: false` 를 유지해야 하고 (이런 gate 결과로 `approved: true` 로 ship 된 report 는 validator 가 거부), `majority-disagree` 항목을 `## 5. Clarification Items` 의 `Blocks=approval` row 로 변환합니다. 빠른 반복용 opt-out: `--no-plan-verification` (기본값: 활성). 자세한 라운드 프로토콜은 [`skills/okstra-convergence/SKILL.md`](skills/okstra-convergence/SKILL.md) 의 "Plan-body verification mode" 섹션과 [`docs/kr/cli.md#--no-plan-verification`](docs/kr/cli.md#--no-plan-verification).
 - **Brief = translation layer + Step 6.5 reporter batch confirmation** — `okstra-brief` 가 외부 입력 (이슈 ticket, 요구사항 문서, 사용자 메시지) 을 verbatim 으로 옮기되 okstra 가 추가한 부분은 labelled augmentation 으로 구분하는 translation layer 가 됐습니다. Step 6.5 가 brief 가 옮기는 과정에서 의미 변화가 발생했는지 사용자에게 일괄 확인받아 `Reporter Confirmations` 섹션에 기록하고, 모든 분석 profile 은 이 섹션의 존재를 phase 분석 진입 precondition 으로 강제합니다 (validator: `validators/validate-brief.py`).
-- **Artifact-home rule (`.project-docs/okstra/`)** — okstra 의 project artifact root 는 `<project>/.project-docs/okstra/` 하나뿐입니다. 이 root 밖은 okstra memory 가 아니며, Source Material 또는 Reporter Confirmations 가 명시적으로 cite 한 경우에만 read-only 로 읽습니다. 쓰기는 같은 explicit request path 를 요구합니다. okstra-internal 등가물: 용어집 `glossary.md`, 결정 기록 `decisions/<NNNN>-<slug>.md` (`implementation-planning` phase 에서 평가).
+- **Artifact-home rule (`.okstra/`)** — okstra 의 project artifact root 는 `<project>/.okstra/` 하나뿐입니다. 이 root 밖은 okstra memory 가 아니며, Source Material 또는 Reporter Confirmations 가 명시적으로 cite 한 경우에만 read-only 로 읽습니다. 쓰기는 같은 explicit request path 를 요구합니다. okstra-internal 등가물: 용어집 `glossary.md`, 결정 기록 `decisions/<NNNN>-<slug>.md` (`implementation-planning` phase 에서 평가).
 - **Dual-format final-report views** — Phase 7 가 `final-report-<task-type>-<seq>.md` 를 쓰면 `okstra render-views` 가 같은 `reports/` 폴더에 두 view 를 자동 생성합니다: AI 다음-phase 입력용 슬림 markdown, 사람 reviewer 용 self-contained HTML (CSS/JS 인라인, 외부 URL 0). HTML 의 `Export user response` 버튼은 `## 5. Clarification Items` 입력을 `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md` 사이드카로 직렬화해 다음 phase 가 소비합니다. 원본 MD 는 어떤 경우에도 view 생성으로 인해 수정되지 않습니다.
 - **`improvement-discovery` task-type (sidetrack entry-point)** — 코드베이스 범위 + 우선순위 lens 화이트리스트 안에서 multi-worker 합의 기반 개선 후보 N개 (기본 8, 절대 cap 12) 도출. `PHASE_SEQUENCE` 외부 sidetrack entry-point — 사용자가 후보를 골라 각각 새 task-id 로 `requirements-discovery` / `implementation-planning` / `error-analysis` 진입. lens enum SSOT: [`scripts/okstra_ctl/improvement_lenses.py`](scripts/okstra_ctl/improvement_lenses.py). 출력 섹션: `## 4.9 Improvement Candidates` (10-column 표). validator: [`validators/validate_improvement_report.py`](validators/validate_improvement_report.py).
 
@@ -203,7 +203,7 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 | `npx -y okstra@latest paths` | 런타임 경로 출력 (`--field <name>` 또는 `--shell`) |
 | `npx -y okstra@latest doctor` | 런타임 + 스킬 + python import 진단 |
 | `npx -y okstra@latest ensure-installed` | Idempotent 체크, stale 이면 자동 재설치 (스킬이 내부적으로 호출) |
-| `npx -y okstra@latest setup --project-id <id>` | 현재 프로젝트를 등록 (`.project-docs/okstra/project.json`) |
+| `npx -y okstra@latest setup --project-id <id>` | 현재 프로젝트를 등록 (`.okstra/project.json`) |
 | `npx -y okstra@latest check-project` | 현재 프로젝트가 `setup` 으로 등록됐는지 검증 |
 | `npx -y okstra@latest config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | okstra 설정 읽기/쓰기. 현재 지원 키: `pr-template-path` (project.json 또는 `~/.okstra/config.json` 의 `prTemplatePath` 갱신) |
 | `npx -y okstra@latest render-views <final-report.md>` | final-report MD 한 본을 입력으로 슬림 MD + HTML 두 view 를 (재)생성 (Phase 7 step 1.5; 멱등) |

package/README.md

@@ -78,7 +78,7 @@ okstra/                          npm package = repo root
 └── {claude,codex,gemini,report-writer}-worker.md   subagent definitions
                                  (required for multi-agent dispatch)
 
-<project-root>/.project-docs/okstra/
+<project-root>/.okstra/
 ├── project.json                 {projectId, projectRoot, ...} (written by /okstra-setup)
 ├── discovery/{task-catalog,latest-task}.json
 ├── glossary.md                  okstra-owned project terminology
@@ -94,7 +94,7 @@ okstra/                          npm package = repo root
 | agents/prompts/schemas/templates/validators | npm package's `runtime/` | the `okstra` package (resolved via `okstra paths`) |
 | Skill markdown | `~/.claude/skills/<name>/SKILL.md` | `okstra install` (tracked in `installed-skills.json`) |
 | Worker agent markdown | `~/.claude/agents/<worker>.md` | `okstra install` (tracked in `installed-agents.json`) |
-| Project metadata | `<project>/.project-docs/okstra/` | `/okstra-setup` + the project itself |
+| Project metadata | `<project>/.okstra/` | `/okstra-setup` + the project itself |
 | Run index | `~/.okstra/{recent,active}.jsonl` | `prepare_task_bundle` |
 
 ## 3. Manual
@@ -144,7 +144,7 @@ Or, inside a Claude Code session, invoke the equivalent slash command:
 /okstra-setup
 ```
 
-Both write `<project>/.project-docs/okstra/project.json`. The CLI is non-interactive when `--project-id` is given (use it in CI); the slash command prompts via `AskUserQuestion`. Every other user-facing skill refuses to proceed until that file exists.
+Both write `<project>/.okstra/project.json`. The CLI is non-interactive when `--project-id` is given (use it in CI); the slash command prompts via `AskUserQuestion`. Every other user-facing skill refuses to proceed until that file exists.
 
 ### 3.3 Day-to-day commands
 
@@ -186,12 +186,12 @@ Recent workflow additions (post-0.8.0, on `main`):
 
 - **Isolated task worktree for every task-type** — prepare automatically runs `git worktree add ~/.okstra/worktrees/<project>/<group>/<task>/` on a fresh branch `<work-category-prefix>-<task-id-segment>` branched from the **user-chosen base ref** (`--base-ref`, mirroring the `release-handoff` PR-base picker: `main` / `dev` / `staging` / `preprod` / `prod` / any local ref) the first time a task-key is seen. `--base-ref` is required on first phase; the okstra-run skill collects it via `AskUserQuestion`, non-interactive callers must pass the flag explicitly. Every subsequent phase of the same task-key (`requirements-discovery` → `error-analysis` → `implementation-planning` → `implementation` → `final-verification` → `release-handoff`) reuses the same path and branch, so phase N inherits the working-tree state phase N-1 left behind. A global registry at `~/.okstra/worktrees/registry.json` (flock-guarded) reserves task-keys and branches across concurrent runs; all path/branch segments are sanitised (`/`, `:`, etc. → `-`). The worktree is preserved after every run for follow-up phases, PR authoring, and rollback. Skip paths: when the caller is already inside another worktree or `project_root` is not a git repo, provisioning no-ops. Manual cleanup: `git worktree remove <path>` → `git branch -D <branch>` plus releasing/removing the task-key from the registry. Details: [`docs/kr/architecture.md`](docs/kr/architecture.md) (*Task type* section) and [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
 - **`release-handoff` lifecycle phase** — runs after `final-verification` returns `verdict=accepted`. The lead drafts a commit message and PR body via a Claude worker, then prompts the user with `AskUserQuestion` for three choices: action (`commit only` / `commit + PR` / `skip`), PR base branch (`staging` / `preprod` / `prod` / `main` / `dev` / free-form), and message handling (`use as-is` / `edit then proceed` / `cancel`). Only user-selected mutating git/gh commands run. Force-push, base-branch direct push, hook bypass (`--no-verify`), and release publishing (`gh release`, `npm publish`, ...) are forbidden. Source code is not edited in this phase. Profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
-- **Configurable PR body template** (release-handoff) — the PR body is filled from a markdown template chosen in priority order: per-run override (`--pr-template-path` or the okstra-run Step 6 prompt) → `<project_root>/.project-docs/okstra/project.json` `prTemplatePath` → `~/.okstra/config.json` `prTemplatePath` → bundled skill default at `~/.claude/skills/okstra-run/templates/pr-body.template.md`. Register a template with `okstra config set pr-template-path <path> [--scope project|global]` (project scope accepts paths relative to the project root; global scope requires absolute or `~/`-prefixed). `okstra config get pr-template-path --scope all` reports every scope plus the effective winner. The bundled default ships `## Summary` / `## Changes` / `## Test plan` / `## Linked issues` with HTML comment guidance that the lead strips before opening the PR.
+- **Configurable PR body template** (release-handoff) — the PR body is filled from a markdown template chosen in priority order: per-run override (`--pr-template-path` or the okstra-run Step 6 prompt) → `<project_root>/.okstra/project.json` `prTemplatePath` → `~/.okstra/config.json` `prTemplatePath` → bundled skill default at `~/.claude/skills/okstra-run/templates/pr-body.template.md`. Register a template with `okstra config set pr-template-path <path> [--scope project|global]` (project scope accepts paths relative to the project root; global scope requires absolute or `~/`-prefixed). `okstra config get pr-template-path --scope all` reports every scope plus the effective winner. The bundled default ships `## Summary` / `## Changes` / `## Test plan` / `## Linked issues` with HTML comment guidance that the lead strips before opening the PR.
 - **Profile-roster worker validation** — `--workers <csv>` (and the okstra-run Step 6 worker prompt) are now restricted to the worker IDs declared by the chosen profile's `Required workers:` block. Asking for `codex` / `gemini` on a profile that does not list them (e.g. `release-handoff`) is rejected with a clear error, and the interactive prompt only offers workers the profile actually accepts.
 - **Multi-stage `implementation-planning` / `implementation`** — `implementation-planning` always produces a Stage Map plus N stage sections; each stage has ≤6 steps and stages whose `depends-on (none)` can be executed in parallel by separate `implementation` runs. Each `implementation` invocation picks one stage (via `--stage <auto|N>`) and emits an evidence sidecar (`carry/stage-<N>.json`) that the next stage automatically inherits. The `implementation-planning` run directory accumulates a `consumers.jsonl` reverse-link showing which `implementation` runs consumed which stage.
 - **Phase 6 plan-body verification (implementation-planning only)** — after the Report writer worker authors the final-report draft and before the user approval gate, the lead now runs one additional verification round: it extracts `P-Opt-*` / `P-Step-*` / `P-Dep-*` / `P-Val-*` / `P-Rb-*` items from the consolidated `## 4.5` plan body and dispatches them to every analyser worker as `AGREE` / `DISAGREE(a-e)` / `SUPPLEMENT`. The aggregated gate result is one of `passed` / `passed-with-dissent` / `blocked-by-disagreement` / `aborted-non-result`. The frontmatter `approved` flag is always emitted as `false`; when the gate is `blocked-by-disagreement` or `aborted-non-result` the writer MUST keep it `false` (the validator refuses any report that publishes `approved: true` under such a gate) and convert `majority-disagree` items into `## 5. Clarification Items` rows with `Blocks=approval`. Disable for fast iteration with `--no-plan-verification` (default: enabled). Details: [`skills/okstra-convergence/SKILL.md`](skills/okstra-convergence/SKILL.md) "Plan-body verification mode" and [`docs/kr/cli.md#--no-plan-verification`](docs/kr/cli.md#--no-plan-verification).
 - **Brief as translation layer + reporter batch confirmation (Step 6.5)** — `okstra-brief` now produces the brief as a translation layer that preserves external inputs (issue ticket, requirements doc, user message) verbatim while labelling okstra augmentations. A new Step 6.5 walks the user through a single batch confirmation of any rewordings, recorded in a `Reporter Confirmations` section. Every analysis profile blocks phase entry until this section exists (validator: `validators/validate-brief.py`).
-- **Artifact-home rule (`.project-docs/okstra/`)** — okstra's project artifact root is only `<project>/.project-docs/okstra/`. Anything outside that root is not okstra memory; it may be read only when explicitly cited as Source Material or Reporter Confirmations, and writes require the same explicit request path. okstra-internal equivalents: `glossary.md` for terminology and `decisions/<NNNN>-<slug>.md` for decision records (evaluated in `implementation-planning`).
+- **Artifact-home rule (`.okstra/`)** — okstra's project artifact root is only `<project>/.okstra/`. Anything outside that root is not okstra memory; it may be read only when explicitly cited as Source Material or Reporter Confirmations, and writes require the same explicit request path. okstra-internal equivalents: `glossary.md` for terminology and `decisions/<NNNN>-<slug>.md` for decision records (evaluated in `implementation-planning`).
 - **Dual-format final-report views** — after Phase 7 writes `final-report-<task-type>-<seq>.md`, `okstra render-views` automatically emits two sibling views in the same `reports/` directory: a slim Markdown for downstream AI input and a self-contained HTML (inline CSS/JS, no external URLs) for human review. The HTML lets a reviewer fill in `## 5. Clarification Items` decisions and export them to `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md`, which the next phase consumes as input. The original MD is never modified by view generation.
 - **`improvement-discovery` task-type (sidetrack entry-point)** — Discover ranked improvement candidates within a codebase scope and lens whitelist via multi-worker consensus (default top-8, hard cap 12). Outside `PHASE_SEQUENCE`; the user selects candidates and opens each as a new task with `requirements-discovery`, `implementation-planning`, or `error-analysis`. Lens enum SSOT: [`scripts/okstra_ctl/improvement_lenses.py`](scripts/okstra_ctl/improvement_lenses.py). Output section: `## 4.9 Improvement Candidates` (10-column table). Validator: [`validators/validate_improvement_report.py`](validators/validate_improvement_report.py).
 
@@ -202,7 +202,7 @@ Recent workflow additions (post-0.8.0, on `main`):
 | `npx -y okstra@latest paths` | Print runtime paths (`--field <name>` or `--shell`) |
 | `npx -y okstra@latest doctor` | Diagnose runtime + skills + python import |
 | `npx -y okstra@latest ensure-installed` | Idempotent check, auto-reinstall if stale (skills call this internally) |
-| `npx -y okstra@latest setup --project-id <id>` | Register the current project (`.project-docs/okstra/project.json`) |
+| `npx -y okstra@latest setup --project-id <id>` | Register the current project (`.okstra/project.json`) |
 | `npx -y okstra@latest check-project` | Verify the current project has been registered with `setup` |
 | `npx -y okstra@latest config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | Read / write okstra settings; initial key `pr-template-path` (writes `prTemplatePath` to project.json or `~/.okstra/config.json`) |
 | `npx -y okstra@latest render-views <final-report.md>` | Regenerate the slim-MD + HTML sibling views from a final-report MD (Phase 7 step 1.5; idempotent) |

package/bin/okstra

@@ -10,6 +10,7 @@ const COMMANDS = new Map([
   ["setup", () => import("../src/setup.mjs").then((m) => m.run)],
   ["check-project", () => import("../src/check-project.mjs").then((m) => m.run)],
   ["config", () => import("../src/config.mjs").then((m) => m.run)],
+  ["migrate", () => import("../src/migrate.mjs").then((m) => m.run)],
   ["task-list", () => import("../src/task-list.mjs").then((m) => m.run)],
   ["task-show", () => import("../src/task-show.mjs").then((m) => m.run)],
   ["worktree-lookup", () => import("../src/worktree-lookup.mjs").then((m) => m.run)],
@@ -32,7 +33,7 @@ Quick start (CLI):
   4. open a Claude Code session and run /okstra-run     # start a task
 
 Inside a Claude Code session you can replace step 3 with /okstra-setup —
-both write the same <PROJECT_ROOT>/.project-docs/okstra/project.json.
+both write the same <PROJECT_ROOT>/.okstra/project.json.
 
 Usage:
   okstra <command> [options]
@@ -41,10 +42,11 @@ Admin commands:
   install                Install runtime to ~/.okstra and skills to ~/.claude/skills
   ensure-installed       Verify install is fresh; reinstall if stale (idempotent)
   uninstall              Remove runtime + skills (user data preserved by default)
-  setup                  Register the current project (.project-docs/okstra/project.json)
+  setup                  Register the current project (.okstra/project.json)
   doctor                 Diagnostic check of the installed runtime
   check-project          Verify the current project has been registered with setup
   config                 Read / write okstra settings (e.g. PR template path)
+  migrate                Move legacy .project-docs/okstra/ to .okstra/ (one-shot)
   paths                  Print runtime paths (workspace/agents/pythonpath/bin/home/version)
 
 Introspection commands (JSON output, used by skills to avoid python heredocs):

package/docs/kr/architecture.md

@@ -18,7 +18,7 @@
 - **Single python authority**: 모든 prepare wiring(profile/workers/model 해소, path 계산, render, central record_start)이 [`okstra_ctl.run.prepare_task_bundle()`](../../scripts/okstra_ctl/run.py) 한 함수에 모여 있습니다. `okstra.sh` 와 `okstra-run` skill 은 같은 함수를 호출하는 thin caller 이며, 환경 변수로 상태를 전달하지 않습니다 — task 정체성·경로·workflow 상태는 모두 디스크 권위 파일에서 매번 계산됩니다.
 - **Claude handoff (두 모드)**: (a) `okstra.sh` 가 새 `claude` 프로세스를 띄우는 전통 방식, (b) `okstra-run` skill 이 현재 claude 세션 안에서 prepare 후 lead 역할을 그대로 인계받는 in-session 모드. 둘 다 `prepare_task_bundle` 의 산출물(instruction-set 등)을 그대로 사용합니다.
 - **Required team contract**: 각 phase profile의 `Required workers:` 블록이 roster의 권위입니다. 일반 분석 phase는 Claude/Codex analyser + report-writer를 기본으로 하고, Gemini는 profile과 `--workers`가 허용할 때만 포함됩니다. `release-handoff`처럼 lead-only에 가까운 phase는 별도 roster를 가집니다.
-- **User-home install + project-local task bundles**: `npx okstra@latest install` 한 명령이 런타임(`~/.okstra/{lib/python, bin, templates}`), 스킬 13종(`~/.claude/skills/<name>/SKILL.md`), worker agent 4종(`~/.claude/agents/*-worker.md`)을 설치합니다. 대상 프로젝트에는 task bundle 과 discovery metadata 가 `.project-docs/okstra/` 아래 저장되고, **추가로 `<PROJECT_ROOT>/.claude/settings.local.json` 이 `~/.okstra/templates/settings.local.json` 을 가리키는 symlink 로 provisioning** 됩니다 (`okstra setup` 또는 `okstra-ctl` prepare 가 idempotent 하게 관리; 기존에 일반 파일이 있었다면 `.bak.<timestamp>` 로 백업 후 교체). 이 symlink 가 host Claude Code 세션에 자동 로드되어 codex/gemini worker wrapper 호출 권한을 부여하므로, 사용자의 글로벌 `~/.claude/settings.json` 은 건드리지 않습니다. 개발용 `okstra install --link <repo>` 는 설치 파일을 repo source로 symlink합니다.
+- **User-home install + project-local task bundles**: `npx okstra@latest install` 한 명령이 런타임(`~/.okstra/{lib/python, bin, templates}`), 스킬 13종(`~/.claude/skills/<name>/SKILL.md`), worker agent 4종(`~/.claude/agents/*-worker.md`)을 설치합니다. 대상 프로젝트에는 task bundle 과 discovery metadata 가 `.okstra/` 아래 저장되고, **추가로 `<PROJECT_ROOT>/.claude/settings.local.json` 이 `~/.okstra/templates/settings.local.json` 을 가리키는 symlink 로 provisioning** 됩니다 (`okstra setup` 또는 `okstra-ctl` prepare 가 idempotent 하게 관리; 기존에 일반 파일이 있었다면 `.bak.<timestamp>` 로 백업 후 교체). 이 symlink 가 host Claude Code 세션에 자동 로드되어 codex/gemini worker wrapper 호출 권한을 부여하므로, 사용자의 글로벌 `~/.claude/settings.json` 은 건드리지 않습니다. 개발용 `okstra install --link <repo>` 는 설치 파일을 repo source로 symlink합니다.
 - **Resume and clarification**: `--task-key`, `--resume-clarification`, `--clarification-response`로 같은 task 재개와 lead의 추가 질문 응답 흐름을 지원합니다.
 - **Derived views and telemetry**: final-report data.json → Markdown → slim MD / self-contained HTML view, worker error sidecar, wrapper log sidecar, token usage / cost accounting을 제공합니다.
 
@@ -84,7 +84,7 @@
 okstra 의 prepare 책임은 단일 python 진입점 [`okstra_ctl.run.prepare_task_bundle`](../../scripts/okstra_ctl/run.py) 에 모여 있습니다. 이 함수가 다음을 한 트랜잭션으로 수행합니다.
 
 - okstra 설치 자산(`~/.claude/skills/okstra/...`, `~/.claude/agents/...`, `~/.okstra/bin/...`) 존재 확인
-- `<PROJECT_ROOT>/.project-docs/okstra/project.json` self-registration (또는 projectId 일치 검증)
+- `<PROJECT_ROOT>/.okstra/project.json` self-registration (또는 projectId 일치 검증)
 - task type → `prompts/profiles/<task-type>.md` 로드 + 권장 workers 추출
 - 사용자 worker/model 오버라이드 정규화 (Claude/Codex/Gemini/Report-writer 각각 display ↔ execution-value 매핑)
 - task brief / clarification response 경로 해석 (cwd 우선 → PROJECT_ROOT fallback)
@@ -140,7 +140,7 @@ okstra 의 prepare 책임은 단일 python 진입점 [`okstra_ctl.run.prepare_ta
 - `prompts/launch.template.md` — lead 프롬프트 템플릿.
 - `prompts/profiles/*.md` — 6종 task-type profile (`requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff`).
 - `templates/project-docs/task-index.template.md` · `templates/reports/final-report.template.md` · `templates/reports/settings.template.json` — 런타임 렌더 입력.
-- `<PROJECT_ROOT>/.project-docs/okstra/project.json` — 프로젝트 self-registration. okstra.sh 첫 실행 시 자동 생성/검증되며, `--project-root` 미지정 시 ancestor / `git toplevel` 로 PROJECT_ROOT 해석.
+- `<PROJECT_ROOT>/.okstra/project.json` — 프로젝트 self-registration. okstra.sh 첫 실행 시 자동 생성/검증되며, `--project-root` 미지정 시 ancestor / `git toplevel` 로 PROJECT_ROOT 해석.
 
 ### Support assets (런타임 비참조)
 
@@ -190,10 +190,10 @@ per-process 환경 변수에 task 정체성·경로·workflow 상태를 보관
 
 | 데이터 | 권위 파일 |
 |---|---|
-| projectId, projectRoot | `<PROJECT_ROOT>/.project-docs/okstra/project.json` |
+| projectId, projectRoot | `<PROJECT_ROOT>/.okstra/project.json` |
 | task identity / workflow | `<task-root>/task-manifest.json` |
-| task 후보 목록 | `<PROJECT_ROOT>/.project-docs/okstra/discovery/task-catalog.json` |
-| 최신 task 포인터 | `<PROJECT_ROOT>/.project-docs/okstra/discovery/latest-task.json` |
+| task 후보 목록 | `<PROJECT_ROOT>/.okstra/discovery/task-catalog.json` |
+| 최신 task 포인터 | `<PROJECT_ROOT>/.okstra/discovery/latest-task.json` |
 | run 입력값 | `<run-dir>/manifests/run-inputs-<task-type>-<seq>.json` |
 | run paths / seq | `<run-dir>/manifests/run-context-<task-type>-<seq>.json` |
 | run 이력 | `<task-root>/history/timeline.json` |
@@ -282,17 +282,17 @@ Claude launch prompt 본문은 항상 `prompts/launch.template.md` 템플릿에
 
 ## Project self-registration
 
-`okstra.sh` 는 외부 등록 디렉토리(과거 `examples/projects/*.conf.sh` 모델은 폐기됨) 없이 동작합니다. 매 실행 시작 시 PROJECT_ROOT 를 다음 우선순위로 해석한 뒤 그 위치의 `.project-docs/okstra/project.json` 을 권위 소스로 자기 등록합니다.
+`okstra.sh` 는 외부 등록 디렉토리(과거 `examples/projects/*.conf.sh` 모델은 폐기됨) 없이 동작합니다. 매 실행 시작 시 PROJECT_ROOT 를 다음 우선순위로 해석한 뒤 그 위치의 `.okstra/project.json` 을 권위 소스로 자기 등록합니다.
 
 해석 우선순위:
 
 1. CLI 인자 `--project-root <path>`.
-2. cwd 또는 그 조상 디렉토리 중 `.project-docs/okstra/project.json` 보유 위치.
+2. cwd 또는 그 조상 디렉토리 중 `.okstra/project.json` 보유 위치.
 3. cwd 의 `git rev-parse --show-toplevel`.
 
 셋 다 실패하면 `okstra.sh` 는 즉시 에러로 종료합니다 (자동 추정 없음).
 
-`<PROJECT_ROOT>/.project-docs/okstra/project.json` 스키마:
+`<PROJECT_ROOT>/.okstra/project.json` 스키마:
 
 ```json
 {
@@ -306,22 +306,22 @@ Claude launch prompt 본문은 항상 `prompts/launch.template.md` 템플릿에
 
 처음 실행이면 위 4-필드(`projectId`, `projectRoot`, `createdAt`, `updatedAt`)를 새로 작성합니다. 이미 존재하면 `--project-id` 인자값과 저장된 `projectId` 가 일치하는지 검증한 뒤 `projectRoot`/`updatedAt` 만 갱신하고, 사용자가 추가한 알 수 없는 필드(`worktreeSyncDirs`, 향후 `mcpServers` 등)는 upsert 과정에서 보존됩니다. 불일치 시 즉시 종료해 동일 디렉토리에서 두 개의 ID 가 혼용되는 것을 막습니다.
 
-`worktreeSyncDirs` (선택) 는 task worktree 로 symlink 할 project-root-relative 디렉토리 목록을 per-project 로 override 합니다. 해석 우선순위는 `OKSTRA_WORKTREE_SYNC_DIRS` 환경변수 → `project.json` → built-in default (`.project-docs`, `.scratch`, `graphify-out`, `.claude`). 빈 배열을 지정하면 sync 자체를 비활성화합니다. sync 는 filesystem continuity 용도일 뿐이며, okstra context/write boundary 는 계속 `<PROJECT_ROOT>/.project-docs/okstra/**` 입니다.
+`worktreeSyncDirs` (선택) 는 task worktree 로 symlink 할 project-root-relative 디렉토리 목록을 per-project 로 override 합니다. 해석 우선순위는 `OKSTRA_WORKTREE_SYNC_DIRS` 환경변수 → `project.json` → built-in default (`.project-docs`, `.scratch`, `graphify-out`, `.claude`). 빈 배열을 지정하면 sync 자체를 비활성화합니다. sync 는 filesystem continuity 용도일 뿐이며, okstra context/write boundary 는 계속 `<PROJECT_ROOT>/.okstra/**` 입니다.
 
 `okstra-ctl` 의 reindex/backfill 도 신규 모델에서 권위 소스를 변경했습니다. 과거에는 `examples/projects/*.conf.sh` 를 source 했지만, 지금은 `~/.okstra/projects/<projectId>/meta.json` (record_start 가 위 project.json 정보를 mirror 한 결과) 을 스캔하여 (projectId, projectRoot) 매핑을 복원합니다. `OKSTRA_PROJECT_DEFINITION_DIR_OVERRIDE` 환경변수도 함께 폐기되었습니다.
 
 ## Artifact-home rule
 
-okstra 의 project artifact root 는 `<PROJECT_ROOT>/.project-docs/okstra/` 하나뿐입니다. 이 root 밖은 okstra memory 가 아닙니다. brief 의 `Source Material` 또는 `Reporter Confirmations` 가 명시적으로 cite 한 경우에만 read-only source material 로 읽고, 자체 판단으로 root 밖에 쓰지 않습니다.
+okstra 의 project artifact root 는 `<PROJECT_ROOT>/.okstra/` 하나뿐입니다. 이 root 밖은 okstra memory 가 아닙니다. brief 의 `Source Material` 또는 `Reporter Confirmations` 가 명시적으로 cite 한 경우에만 read-only source material 로 읽고, 자체 판단으로 root 밖에 쓰지 않습니다.
 
 유일한 예외: brief 의 `Source Material` 또는 `Reporter Confirmations` 섹션에서 사용자가 **verbatim** 으로 특정 non-okstra 파일 편집을 요청한 경우. 해당 편집을 수행하는 phase 는 자신의 final-report 에 사용자 원문 인용을 함께 남겨야 합니다.
 
 okstra 는 자기 subtree 안에 자체 institutional memory 를 유지합니다.
 
-- `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` — run 을 가로지르며 누적되는 okstra 용어집.
-- `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md` — okstra 의 결정 기록. 평가 시점은 `implementation-planning` phase 이며 `okstra-brief` 단계에서는 후보만 표시합니다.
+- `<PROJECT_ROOT>/.okstra/glossary.md` — run 을 가로지르며 누적되는 okstra 용어집.
+- `<PROJECT_ROOT>/.okstra/decisions/<NNNN>-<slug>.md` — okstra 의 결정 기록. 평가 시점은 `implementation-planning` phase 이며 `okstra-brief` 단계에서는 후보만 표시합니다.
 
-okstra phase 는 PRD / issue file 을 직접 쓰지 않습니다. 동등한 결정 산출물은 `requirements-discovery` 와 `implementation-planning` 이 `.project-docs/okstra/` 내부에 만듭니다.
+okstra phase 는 PRD / issue file 을 직접 쓰지 않습니다. 동등한 결정 산출물은 `requirements-discovery` 와 `implementation-planning` 이 `.okstra/` 내부에 만듭니다.
 
 ## Task type
 
@@ -389,7 +389,7 @@ task 자체의 기준 폴더입니다.
 task manifest, task index, instruction-set, runs, history가 이 루트 아래에 모입니다.
 
 ```text
-<target-project>/.project-docs/okstra/tasks/<task-group>/<task-id>/
+<target-project>/.okstra/tasks/<task-group>/<task-id>/
 ├── task-manifest.json
 ├── task-index.md
 ├── instruction-set/
@@ -433,7 +433,7 @@ task manifest, task index, instruction-set, runs, history가 이 루트 아래
 실행별 산출물은 아래 경로에 누적됩니다.
 
 ```text
-<target-project>/.project-docs/okstra/tasks/<task-group>/<task-id>/runs/<task-type>/
+<target-project>/.okstra/tasks/<task-group>/<task-id>/runs/<task-type>/
 ```
 
 여기에 저장되는 대표 파일:
@@ -469,8 +469,8 @@ worker prompt history는 `/tmp`가 아니라 항상 현재 run의 `prompts/` 아
 프로젝트 공용 discovery pointer는 아래 경로에 생성합니다.
 
 ```text
-<target-project>/.project-docs/okstra/discovery/latest-task.json
-<target-project>/.project-docs/okstra/discovery/task-catalog.json
+<target-project>/.okstra/discovery/latest-task.json
+<target-project>/.okstra/discovery/task-catalog.json
 ```
 scripts/okstra.sh workflow가 사용하는 project-local Claude assets는 아래 경로들에 seed합니다.
 
@@ -482,8 +482,8 @@ scripts/okstra.sh workflow가 사용하는 project-local Claude assets는 아래
 
 역할 구분:
 
-- `.project-docs/okstra/discovery/latest-task.json`: 현재 프로젝트에서 가장 최근에 준비된 okstra task bundle을 가리키는 current-task convenience pointer
-- `.project-docs/okstra/discovery/task-catalog.json`: 현재 프로젝트에 준비된 okstra task bundle 목록을 `taskKey`, `taskGroup`, `taskId` 기준으로 유지하는 canonical project-level catalog
+- `.okstra/discovery/latest-task.json`: 현재 프로젝트에서 가장 최근에 준비된 okstra task bundle을 가리키는 current-task convenience pointer
+- `.okstra/discovery/task-catalog.json`: 현재 프로젝트에 준비된 okstra task bundle 목록을 `taskKey`, `taskGroup`, `taskId` 기준으로 유지하는 canonical project-level catalog
 - `instruction-set/reference-expectations.md`: 현재 task가 참조해야 할 config files, deployment manifests, expected values를 task-level canonical artifact로 정리한 파일
 - `~/.claude/skills/okstra-*/...`, `~/.claude/agents/...`: `okstra install` 이 사용자 홈에 seed하는 Claude asset (project-local 시딩은 더 이상 발생하지 않음 — `okstra install --refresh` 로 갱신)
 
@@ -619,8 +619,8 @@ canonical metadata는 항상 `task-manifest.json`을 기준으로 확인합니
 
 `okstra` 실행 후 Claude는 아래 순서로 현재 task를 읽는 것을 기본 규칙으로 삼아야 합니다.
 
-1. task browsing 또는 task-id disambiguation이 필요하면 `.project-docs/okstra/discovery/task-catalog.json`을 먼저 읽습니다.
-2. 현재 task key나 task path가 명시되지 않았다면 `.project-docs/okstra/discovery/latest-task.json`을 current-task pointer로 읽습니다.
+1. task browsing 또는 task-id disambiguation이 필요하면 `.okstra/discovery/task-catalog.json`을 먼저 읽습니다.
+2. 현재 task key나 task path가 명시되지 않았다면 `.okstra/discovery/latest-task.json`을 current-task pointer로 읽습니다.
 3. `task-manifest.json`을 읽습니다.
 4. `task-index.md`는 quick summary가 필요할 때만 선택적으로 읽습니다.
 5. `instruction-set/analysis-profile.md`를 읽습니다.
@@ -660,8 +660,8 @@ brief에는 보통 아래를 포함합니다.
 - worker에게 줄 질문
 - 기대 출력
 - 이전 run 또는 연관 task 정보
-- (선택) glossary 추가 후보 — okstra-brief Step 4.5 가 `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` 에 직접 기록
-- (선택) decisions 후보 — `implementation-planning` phase 에서 평가 후 `.project-docs/okstra/decisions/<NNNN>-<slug>.md` 로 승격
+- (선택) glossary 추가 후보 — okstra-brief Step 4.5 가 `<PROJECT_ROOT>/.okstra/glossary.md` 에 직접 기록
+- (선택) decisions 후보 — `implementation-planning` phase 에서 평가 후 `.okstra/decisions/<NNNN>-<slug>.md` 로 승격
 
 okstra-brief 의 Step 6.5 는 **reporter batch confirmation** 입니다. brief 가 외부 입력을 옮기는 도중 의미 변화가 발생했는지를 사용자에게 일괄 확인받고 그 결과를 `Reporter Confirmations` 섹션에 기록합니다. 모든 분석 profile 은 이 섹션의 존재를 phase 분석 진입의 precondition 으로 강제합니다 (validator: `validators/validate-brief.py`).
 
@@ -820,8 +820,8 @@ scripts/okstra.sh --task-key <project-id>:<task-group>:<task-id> --task-type fin
 - `workflow.routingStatus`
 - `workflow.lastSafeCheckpoint`
 
-프로젝트 전체 상태를 훑을 때는 `.project-docs/okstra/discovery/task-catalog.json`을 사용합니다.
-특정 task의 최신 상태를 볼 때는 `.project-docs/okstra/discovery/latest-task.json`, `task-manifest.json`, 최신 `run-manifest`, `history/timeline.json` 순서로 확인합니다.
+프로젝트 전체 상태를 훑을 때는 `.okstra/discovery/task-catalog.json`을 사용합니다.
+특정 task의 최신 상태를 볼 때는 `.okstra/discovery/latest-task.json`, `task-manifest.json`, 최신 `run-manifest`, `history/timeline.json` 순서로 확인합니다.
 
 Claude에서는 seeded `okstra-status` skill을 사용해 아래 질문을 직접 처리할 수 있습니다.
 
@@ -946,8 +946,8 @@ phase 산출물의 출고 가능 여부를 강제하는 진입점:
 - worker 모델은 `--lead-model`, `--claude-model`, `--codex-model`, `--gemini-model`, `--report-writer-model`로 override할 수 있고, 기본값은 `OKSTRA_DEFAULT_*` 환경 변수에서 중앙 관리합니다. fallback 기본값은 `Claude lead`/`Report writer worker`=`opus-4-6`, `Claude worker`=`sonnet`, `Codex worker`=`gpt-5.5`, `Gemini worker`=`auto`입니다.
 - `--task-type implementation` 에서는 Executor 역할을 맡을 provider 를 `--executor <claude|codex|gemini>` (또는 `OKSTRA_DEFAULT_EXECUTOR`, fallback `claude`) 로 선택합니다. Executor 만 프로젝트 파일을 mutate 할 수 있고, 나머지 두 provider 와 자기 자신의 provider 가 모두 별도 CLI 세션으로 verifier 로 dispatch 됩니다 (세션 분리만으로도 self-review 안전장치 유지). Executor 의 모델은 선택된 provider 의 worker 모델 플래그(`--claude-model` / `--codex-model` / `--gemini-model`) 를 그대로 재사용하며, run-manifest 의 `teamContract.executor` 블록에 provider / displayName / workerAgent / model 이 기록됩니다.
 - Executor 별 worktree cwd 주입: codex / gemini executor 는 wrapper(`okstra-codex-exec.sh -C` / `okstra-gemini-exec.sh --include-directories`) 가 CLI layer 에서 cwd 를 worktree 로 고정합니다. Claude executor 는 Bash tool 에 per-call cwd 인자가 없어 cwd 민감 toolchain (`cargo`/`npm`/`pnpm`/`bun`/`pytest`/`make`/`go`) 호출을 같은 Bash invocation 안에서 `cd {{EXECUTOR_WORKTREE_PATH}} && <cmd>` 로 prefix 합니다 — `bash -lc`/`bash -c` 래핑은 금지되며 (`cd` leading token 이 가려져 permission auto-allow 우회 실패), 작업 디렉터리 플래그 (`git -C`, `cargo --manifest-path` 등) 가 있으면 그것을 우선합니다. 자세한 규약은 `prompts/profiles/implementation.md` 의 *Executor Worktree* 블록과 `agents/workers/claude-worker.md` 의 Executor exception 항목 참고.
-- project-level current-task convenience pointer는 `.project-docs/okstra/discovery/latest-task.json`입니다.
-- project-level canonical task inventory는 `.project-docs/okstra/discovery/task-catalog.json`입니다.
+- project-level current-task convenience pointer는 `.okstra/discovery/latest-task.json`입니다.
+- project-level canonical task inventory는 `.okstra/discovery/task-catalog.json`입니다.
 - okstra Claude asset은 `~/.claude/skills/`와 `~/.claude/agents/` 아래에 `okstra install` 시점에 seed되며, `okstra install --refresh` 로 갱신할 수 있습니다 (per-project seeding은 더 이상 수행되지 않음).
 - seeded okstra Claude assets는 Agent Teams 우선, sequential/background fallback 차선 규칙을 Claude에게 제공합니다.
 - 최종 판단은 스크립트가 아니라 Claude가 수행합니다.
@@ -957,7 +957,7 @@ phase 산출물의 출고 가능 여부를 강제하는 진입점:
 - `okstra.sh`는 worker CLI 호출 anchoring을 위해 절대 projectRoot를 강제합니다.
 - `okstra wizard step` 은 `--answer <val>` 을 **필수** 로 받습니다. 응답을 줄 차례가 아니라 다음 prompt 만 미리 보고 싶다면 `--no-submit` 으로 peek 합니다.
 - `/okstra-history`는 task manifest fallback / 페이지네이션 / 필터를 지원하고, `--base-ref`는 워크트리 registry에서 해석합니다.
-- 사용자 프로젝트에 대한 모든 쓰기는 `<PROJECT_ROOT>/.project-docs/okstra/` 안에만 발생합니다 (Artifact-home rule 참조).
+- 사용자 프로젝트에 대한 모든 쓰기는 `<PROJECT_ROOT>/.okstra/` 안에만 발생합니다 (Artifact-home rule 참조).
 
 ## Related documents
 

package/docs/kr/cli.md

@@ -78,7 +78,7 @@ interactive terminal에서 실행하면 다음 규칙이 추가로 적용됩니
 
 ### `--project-id`
 
-전역에서 고유해야 하는 프로젝트 ID입니다. 첫 실행 시 `<PROJECT_ROOT>/.project-docs/okstra/project.json` 에 자기 등록(self-registration)되며, 동일 PROJECT_ROOT 에서 재실행할 때 인자값과 저장된 `projectId` 가 다르면 즉시 에러로 종료합니다.
+전역에서 고유해야 하는 프로젝트 ID입니다. 첫 실행 시 `<PROJECT_ROOT>/.okstra/project.json` 에 자기 등록(self-registration)되며, 동일 PROJECT_ROOT 에서 재실행할 때 인자값과 저장된 `projectId` 가 다르면 즉시 에러로 종료합니다.
 
 예:
 
@@ -196,7 +196,7 @@ scripts/okstra.sh \
   --task-type implementation-planning \
   --project-id jobs --task-group tasks --task-id 8852 \
   --task-brief .project-docs/tasks/8852/BUG_REPORT.md \
-  --clarification-response .project-docs/okstra/tasks/tasks/8852/runs/2026-04-29/error-analysis/reports/final-report-2026-04-29_10-15-30.md
+  --clarification-response .okstra/tasks/tasks/8852/runs/2026-04-29/error-analysis/reports/final-report-2026-04-29_10-15-30.md
 ```
 
 ### `--resume-clarification`
@@ -226,7 +226,7 @@ EDITOR=code\ -w scripts/okstra.sh --resume-clarification --project-id jobs --tas
 내부적으로는 다음과 동등합니다.
 
 ```bash
-$EDITOR <project-root>/.project-docs/okstra/tasks/<group>/<id>/runs/<task-type>/reports/final-report-<latest>.md
+$EDITOR <project-root>/.okstra/tasks/<group>/<id>/runs/<task-type>/reports/final-report-<latest>.md
 scripts/okstra.sh --task-type <same-type> \
   --project-id <p> --task-group <g> --task-id <i> \
   --task-brief <from manifest> \
@@ -237,11 +237,11 @@ scripts/okstra.sh --task-type <same-type> \
 
 대상 프로젝트의 절대 경로입니다. 명시하지 않으면 `okstra.sh` 가 다음 우선순위로 자동 해석합니다.
 
-1. cwd 또는 그 조상 디렉토리 중 `.project-docs/okstra/project.json` 보유 위치를 찾아 PROJECT_ROOT 로 채택합니다.
+1. cwd 또는 그 조상 디렉토리 중 `.okstra/project.json` 보유 위치를 찾아 PROJECT_ROOT 로 채택합니다.
 2. 위가 실패하면 `git rev-parse --show-toplevel` 결과를 사용합니다.
 3. 모두 실패하면 즉시 에러로 종료합니다.
 
-해석된 PROJECT_ROOT 에서 첫 실행이라면 `<PROJECT_ROOT>/.project-docs/okstra/project.json` 이 다음 스키마로 자동 생성됩니다.
+해석된 PROJECT_ROOT 에서 첫 실행이라면 `<PROJECT_ROOT>/.okstra/project.json` 이 다음 스키마로 자동 생성됩니다.
 
 ```json
 {
@@ -574,9 +574,10 @@ chmod +x ~/.local/bin/okstra-ctl
 | `okstra ensure-installed [-q]` | 설치 상태 확인, stale이면 재설치 |
 | `okstra uninstall [--purge -y]` | 설치 자산 제거. 기본값은 사용자 데이터 보존 |
 | `okstra doctor` | runtime + Python import + skill/agent 설치 진단 |
-| `okstra setup --project-id <id>` | 현재 프로젝트의 `.project-docs/okstra/project.json` 생성/갱신 |
+| `okstra setup --project-id <id>` | 현재 프로젝트의 `.okstra/project.json` 생성/갱신 |
 | `okstra check-project [--json]` | 현재 프로젝트가 등록되었는지 검증 |
 | `okstra config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | 영구 설정 관리 (예: `pr-template-path`). 원자적 JSON 쓰기 |
+| `okstra migrate [--apply] [--cwd <dir>] [--quiet]` | 한 번만 실행: 프로젝트 산출물 루트를 `.project-docs/okstra/` → `.okstra/` 로 이동. 기본 dry-run, `--apply` 로 실제 실행. `git mv` (git worktree) + 빈 `.project-docs/` 제거 + `<PROJECT>/CLAUDE.md` import 라인 + `.gitignore` + `~/.okstra/{recent,active}.jsonl` + `~/.okstra/worktrees/registry.json` 의 해당 프로젝트 row 동기화. 이미 `.okstra/` 가 존재하거나 레거시 디렉토리가 없으면 exit 1 로 거부. v0.x 말까지 유지 후 제거 예정 |
 | `okstra task-list [--project-root <path>]` | `list_project_tasks` + `read_latest_task` 결과를 합쳐 task 카탈로그 + 최근 task 를 JSON 으로 반환 |
 | `okstra task-show <task-key> [--project-root <path>]` | task-manifest.json 의 workflow / phase / status 요약 |
 | `okstra worktree-lookup <task-key>` | `worktree_registry.lookup` 결과 (예약된 path / branch / base ref / 현재 상태) |

package/docs/pr-template-usage.md

@@ -11,7 +11,7 @@
 | # | source | 위치 | 비고 |
 |---|--------|------|------|
 | 1 | **per-run override** | `okstra render-bundle --pr-template-path <path>` 또는 wizard 의 한 번성 입력 | 상대경로는 호출자 cwd 기준 (override) 또는 `project_root` 기준 (project scope 와 동일 함수 사용). |
-| 2 | **project scope** | `<project_root>/.project-docs/okstra/project.json` 의 `prTemplatePath` 필드 | 상대경로는 `project_root` 기준으로 해석. |
+| 2 | **project scope** | `<project_root>/.okstra/project.json` 의 `prTemplatePath` 필드 | 상대경로는 `project_root` 기준으로 해석. |
 | 3 | **global scope** | `~/.okstra/config.json` 의 `prTemplatePath` 필드 | **절대경로 또는 `~/` 시작 경로만** 허용. 상대경로는 모호하므로 거절. |
 | 4 | **default (skill bundle)** | 후보 경로 중 먼저 존재하는 파일 (아래 §2) | `npx okstra install` 직후의 폴백 경로. |
 
@@ -35,7 +35,7 @@
 per-run override 보다 길게 유지하려면 wizard 가 자동 호출하거나 직접 다음 명령으로 기록한다.
 
 ```bash
-# project scope: <project_root>/.project-docs/okstra/project.json 의 prTemplatePath 갱신
+# project scope: <project_root>/.okstra/project.json 의 prTemplatePath 갱신
 okstra config set pr-template-path "<path>" --scope project
 
 # global scope: ~/.okstra/config.json 의 prTemplatePath 갱신 (절대경로 필수)

package/docs/project-structure-overview.md

@@ -36,7 +36,7 @@
 
 1. **Single prepare authority**: slash skill, Bash CLI, Node preview 모두 `prepare_task_bundle()`로 수렴합니다.
 2. **Stable task identity**: `<project-id>/<task-group>/<task-id>`가 phase, run, worktree, report를 관통합니다.
-3. **Artifact-home rule**: okstra-owned project artifact root는 `<PROJECT_ROOT>/.project-docs/okstra/**` 하나입니다.
+3. **Artifact-home rule**: okstra-owned project artifact root는 `<PROJECT_ROOT>/.okstra/**` 하나입니다.
 4. **Template/schema/validator lockstep**: `templates/`, `schemas/`, `validators/`, worker/report-writer 계약이 같은 report shape를 강제합니다.
 
 ---
@@ -134,7 +134,7 @@ So `runtime/` is not the only npm-published content. It is the install payload c
 | `install`, `ensure-installed` | `src/install.mjs` | Install or refresh runtime, skills, agents, templates |
 | `uninstall` | `src/uninstall.mjs` | Remove managed runtime/skills/agents, optionally purge data |
 | `doctor` | `src/doctor.mjs` | Diagnose runtime and Python imports |
-| `setup` | `src/setup.mjs` | Create/update `<PROJECT_ROOT>/.project-docs/okstra/project.json` |
+| `setup` | `src/setup.mjs` | Create/update `<PROJECT_ROOT>/.okstra/project.json` |
 | `check-project` | `src/check-project.mjs` | Verify project registration |
 | `config` | `src/config.mjs` | Read/write project/global settings such as PR template path |
 | `task-list`, `task-show` | `src/task-list.mjs`, `src/task-show.mjs` | Task/run introspection for skills |
@@ -341,7 +341,7 @@ The Markdown is derived, not the authoring source. The schema is the contract.
 ~/.claude/skills/okstra-*/SKILL.md
 ~/.claude/agents/{claude,codex,gemini,report-writer}-worker.md
 
-<PROJECT_ROOT>/.project-docs/okstra/
+<PROJECT_ROOT>/.okstra/
 ├── project.json
 ├── CLAUDE.md
 ├── glossary.md
@@ -366,7 +366,7 @@ The Markdown is derived, not the authoring source. The schema is the contract.
         └── (consumers.jsonl)         # implementation-planning 전용: impl-run 역링크 누적 파일
 ```
 
-Project-local `<PROJECT_ROOT>/.claude/settings.local.json`, `<PROJECT_ROOT>/.project-docs/okstra/CLAUDE.md`, and `<PROJECT_ROOT>/AGENTS.md` are provisioned as symlink/import helpers so spawned agents can load okstra permissions and guidance.
+Project-local `<PROJECT_ROOT>/.claude/settings.local.json`, `<PROJECT_ROOT>/.okstra/CLAUDE.md`, and `<PROJECT_ROOT>/AGENTS.md` are provisioned as symlink/import helpers so spawned agents can load okstra permissions and guidance.
 
 ---