okstra 0.36.1 → 0.37.0

package/docs/task-process/common-flow.md

@@ -76,7 +76,7 @@ sequenceDiagram
     participant Skill as okstra-run skill
     participant Node as okstra CLI
     participant Py as okstra_ctl.run
-    participant FS as .project-docs/okstra
+    participant FS as .okstra
     participant Home as ~/.okstra
 
     Skill->>Node: okstra wizard render-args
@@ -119,7 +119,7 @@ flowchart TD
 
 ```mermaid
 flowchart TD
-    Root["<PROJECT_ROOT>/.project-docs/okstra/tasks/<group>/<task>/"] --> IS[instruction-set/]
+    Root["<PROJECT_ROOT>/.okstra/tasks/<group>/<task>/"] --> IS[instruction-set/]
     Root --> Runs[runs/<task-type>/]
     Root --> Hist[history/timeline.json]
     IS --> Profile[analysis-profile.md]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.36.1",
+  "version": "0.37.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.36.1",
-  "builtAt": "2026-05-24T11:52:05.811Z",
+  "package": "0.37.0",
+  "builtAt": "2026-05-27T07:29:11.725Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -133,7 +133,7 @@ Executor is chosen at run-prep time via `--executor <claude|codex|gemini>` (or `
 - Location: `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/` (override `OKSTRA_HOME` only for tests). All segments are sanitised — `/`, `:`, and other special chars collapse to `-`.
 - Branch: `<work-category-prefix>-<task-id-segment>` (e.g. `feat-dev-9436`, `fix-dev-7311`). Branched from `HEAD` of the repo's **main** worktree at the first phase's prep time; base SHA is recorded in `EXECUTOR_WORKTREE_BASE_REF`.
 - A global registry at `~/.okstra/worktrees/registry.json` (flock-guarded) maps each task-key to its path + branch and prevents concurrent runs from colliding. Branch names are globally unique across task-keys on this machine.
-- Worktree sync mirrors the configured project-relative directories from the **main worktree** so task checkouts see the same filesystem state. This is filesystem continuity only: okstra-owned context and writes still stay inside `<PROJECT_ROOT>/.project-docs/okstra/**` unless the brief explicitly authorizes a non-okstra path.
+- Worktree sync mirrors the configured project-relative directories from the **main worktree** so task checkouts see the same filesystem state. This is filesystem continuity only: okstra-owned context and writes still stay inside `<PROJECT_ROOT>/.okstra/**` unless the brief explicitly authorizes a non-okstra path.
 - The path, branch, base ref, and provisioning status (`created` | `reused` | `skipped-in-worktree` | `skipped-not-git`) are exposed through the launch prompt's `## Executor Worktree` section and the implementation profile's worktree block.
 - **Skip conditions** (worktree provisioning is a no-op; task uses `project_root` directly):
   - `project_root` is already inside a non-main worktree (the run reuses the caller's worktree to avoid nesting).
@@ -145,7 +145,7 @@ Executor is chosen at run-prep time via `--executor <claude|codex|gemini>` (or `
 
 **REQUIRED SUB-SKILL:** Invoke [okstra-context-loader](./skills/okstra-context-loader/SKILL.md) first to discover task bundle paths.
 
-Treat cross verify input as a task bundle, not as a single file. If the user did not specify an explicit task key or task path, use `.project-docs/okstra/discovery/latest-task.json` as the current-task convenience pointer. If task browsing, task-id disambiguation, or project-level task inventory is needed, inspect `.project-docs/okstra/discovery/task-catalog.json` first.
+Treat cross verify input as a task bundle, not as a single file. If the user did not specify an explicit task key or task path, use `.okstra/discovery/latest-task.json` as the current-task convenience pointer. If task browsing, task-id disambiguation, or project-level task inventory is needed, inspect `.okstra/discovery/task-catalog.json` first.
 
 After context-loader completes, read **only the five mandatory files below** in a single parallel-Read message at the start of Phase 1. The other instruction-set files are loaded lazily at the phase that actually needs them — see "Lazy reading discipline" below. This split came from observed lead-token bloat: in `fontsninja-classifier-v2:dev-9461:dev-9495` RD-001 the lead burned 71 M tokens (97 % cache_read) largely because every phase entry re-absorbed a 93 KB instruction-set baseline that included files only one downstream phase ever actually used.
 

package/runtime/agents/workers/claude-worker.md

@@ -48,7 +48,7 @@ Unlike the Codex / Gemini workers, you are an in-process Claude subagent — you
    - **Verifier QA-gate exception:** verifier roles MAY use the same `cd <WORKTREE> && <cmd>` shape when executing project-declared `qaCommands` (lint / format / typecheck / test) from `project.json`, since those commands are cwd-sensitive by nature. Outside the QA gate, verifiers still read with absolute paths only — do NOT use `cd` for file inspection.
    - **No extra chaining beyond `cd && cmd`:** the permission matcher only allows the exact two-segment shape `cd <PATH> && <single-command>`. Do NOT append additional pipes, semicolons, redirects, or `&&` chains — e.g. `cd ... && cargo test ... 2>&1 | tail -20; echo "exit:$?"` will trigger a permission prompt every dispatch because the trailing `| tail`, `; echo`, and `2>&1` tokens disqualify the prefix match against `Bash(cargo:*)`. Let Claude Code capture the full stdout/stderr and exit code natively — do not post-process with `tail`, `head`, or `echo "exit:$?"`. If output truncation is genuinely needed, run the command first and read the result in a separate tool call.
 
-5. **MCP usage**: The canonical list of MCP servers and tools available for this run lives in the lead prompt's `## Available MCP Servers` section (sourced from `.project-docs/okstra/project.json`'s `mcpServers` array). When the task requires inspection of an external system covered by one of those servers, call the listed tool directly by name (e.g. `mcp__<server>__<tool>`). Do NOT shell out via `claude --mcp-cli call ...` or run the tool name as a Bash command — those are not valid invocation paths. If a server you need is not listed, record `MCP not available for this run` in your worker output rather than guessing a tool name.
+5. **MCP usage**: The canonical list of MCP servers and tools available for this run lives in the lead prompt's `## Available MCP Servers` section (sourced from `.okstra/project.json`'s `mcpServers` array). When the task requires inspection of an external system covered by one of those servers, call the listed tool directly by name (e.g. `mcp__<server>__<tool>`). Do NOT shell out via `claude --mcp-cli call ...` or run the tool name as a Bash command — those are not valid invocation paths. If a server you need is not listed, record `MCP not available for this run` in your worker output rather than guessing a tool name.
 
 6. If the task brief includes an `## Available MCP Servers` section in the lead prompt, treat that as the canonical list of MCP tools you may invoke for this run. If a needed server is not listed, record `MCP not available for this run` rather than calling it.
 

package/runtime/prompts/profiles/_common-contract.md

@@ -19,9 +19,9 @@ profile document.
 - Tooling — read-only MCP availability (shared):
   - MCP is not implicit okstra context. Query an MCP server only when the task brief explicitly lists it as source material for this run. Any MCP-derived finding MUST cite server, table, and the SELECT used. MCP MUST NEVER be used as a write path — schema/data mutations go through repository migration files reviewed by humans.
 - Resource boundary (shared — artifact-home rule):
-  - Okstra-owned project artifacts live only under `<PROJECT_ROOT>/.project-docs/okstra/**`. Treat `project.json`, task bundles, run artifacts, `glossary.md`, and `decisions/` under that subtree as the canonical okstra memory.
-  - Treat paths outside `<PROJECT_ROOT>/.project-docs/okstra/**` as source material only when the task brief's `Source Material` or `Reporter Confirmations` explicitly cites them; they never become okstra memory.
-  - Create, modify, or delete only inside `<PROJECT_ROOT>/.project-docs/okstra/**` unless the brief verbatim requests a specific non-okstra edit. The phase performing that edit must quote the user instruction in its report. Implementation source edits also require the approved implementation plan.
+  - Okstra-owned project artifacts live only under `<PROJECT_ROOT>/.okstra/**`. Treat `project.json`, task bundles, run artifacts, `glossary.md`, and `decisions/` under that subtree as the canonical okstra memory.
+  - Treat paths outside `<PROJECT_ROOT>/.okstra/**` as source material only when the task brief's `Source Material` or `Reporter Confirmations` explicitly cites them; they never become okstra memory.
+  - Create, modify, or delete only inside `<PROJECT_ROOT>/.okstra/**` unless the brief verbatim requests a specific non-okstra edit. The phase performing that edit must quote the user instruction in its report. Implementation source edits also require the approved implementation plan.
 - Authority & permissions assumption (applies to every okstra task-type):
   - **Assume the user (and their team) holds full authority and every permission required for the anticipated, in-flight, or follow-up work.** Treat external approvals, third-party access grants, role/IAM permissions, organisational sign-off, legal/compliance review, vendor coordination, and "verify access exists" steps as already satisfied unless the task brief explicitly states otherwise.
   - Do NOT add such items to routing decisions, missing-materials lists, clarification questions, option trade-offs, dependency/migration risk, validation checklists, rollout plans, acceptance blockers, residual risks, release recommendations, the `## 5. Clarification Items` table, or any day/effort estimate. They are not legitimate sources of schedule extension.
@@ -52,13 +52,13 @@ profile document.
   - `Source Material` is reporter-verbatim. Do NOT paraphrase, summarize, reorder, or restructure it. Quote it directly when needed.
   - `Augmentation` entries carry one of four labels — `evidence-link`, `format-conversion`, `terminology-mapping`, `intent-inference`. Treat them as follows:
     - `evidence-link` / `format-conversion` → trust without re-verification.
-    - `terminology-mapping` → verify against `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` (authoritative); raise a `Clarification Items` row if the mapping is missing or contradicts the glossary.
+    - `terminology-mapping` → verify against `<PROJECT_ROOT>/.okstra/glossary.md` (authoritative); raise a `Clarification Items` row if the mapping is missing or contradicts the glossary.
     - `intent-inference` → treat as an **unverified hypothesis**. Every `intent-inference` augmentation MUST be paired in the brief with an `Open Questions` row prefixed `intent-check:`. Promote that row into the run's `## 5. Clarification Items` table as `Kind=decision, Blocks=next-phase` (or `Blocks=approval` for `implementation-planning`) with the recommended answer set to "보고자에게 직접 확인 후 응답" unless the codebase can be inspected to confirm or refute the inference.
   - `Open Questions` row prefixes are signals — do not strip them when promoting:
     - `intent-check:` → `Kind=decision`, recommended answer = reporter confirmation. NEVER silently resolve an `intent-check:` by inference at this layer.
-    - `terminology:` → `Kind=decision`, recommended answer = canonical term from `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` (or "extend okstra glossary via brief Step 4.5").
+    - `terminology:` → `Kind=decision`, recommended answer = canonical term from `<PROJECT_ROOT>/.okstra/glossary.md` (or "extend okstra glossary via brief Step 4.5").
     - `conversion-block:` → `Kind=decision`, recommended answer = "보고자에게 직접 확인". The brief is explicitly signalling that translation failed; further inference is forbidden until the reporter clarifies.
-    - `adr-candidate:` → handled by `implementation-planning`; carry forward without modification. Approved decision files land only at `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`.
+    - `adr-candidate:` → handled by `implementation-planning`; carry forward without modification. Approved decision files land only at `<PROJECT_ROOT>/.okstra/decisions/<NNNN>-<slug>.md`.
     - `general:` → free-form; classify per the standard `Clarification Items` rules.
   - Any decision in this run that contradicts the brief's `Source Material` must be raised back to the reporter via a `Clarification Items` row; it must NOT be silently overridden. Disagreement with the reporter is allowed only after the row is resolved.
   - This contract is the single authority on brief consumption. Phase-specific addenda may *tighten* these rules but may not relax them.

package/runtime/prompts/profiles/_implementation-executor.md

@@ -14,7 +14,7 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
 - The `Executor` (bound in `implementation.md` thin core) is the **only worker permitted to use Edit / Write / state-mutating Bash commands** on project files. All other workers run read-only. When the executor provider is `codex` or `gemini`, the actual file mutation happens inside the executor CLI's own auto-edit mode (e.g. `codex exec --sandbox workspace-write`, gemini's equivalent) — not through Claude-side Edit/Write tools — but the safety rules in this sidecar still apply identically.
 - Worktree cwd handling — when the thin core's Task worktree block resolves status to `created` or `reused`, the Executor MUST run every Edit / Write / build / test / commit command with the worktree path as cwd. Treat it as `project_root` for the duration of this run. Do NOT mutate the caller's original checkout. Do NOT `cd` out of the worktree to reach files; if a file outside the worktree is needed, the dependency is a planning gap — record it in `Out-of-plan edits` and continue.
   - **How to set cwd per Bash call**: the Claude Bash tool inherits its cwd from the lead session, which is NOT the worktree. To put cwd-sensitive toolchains (`cargo`, `npm`, `pnpm`, `bun`, `pytest`, `make`, `go`) into the worktree, prefix the command with `cd {{EXECUTOR_WORKTREE_PATH}} && ` inside the same Bash invocation — e.g. `cd {{EXECUTOR_WORKTREE_PATH}} && cargo test -p foo`. **Never wrap in `bash -lc "..."` or `bash -c "..."`** — the wrapper hides the leading `cd` token from Claude Code's permission auto-allow layer (causing prompts on every call) without any safety benefit. For tools that accept an explicit working-directory flag (`git -C <path>`, `cargo --manifest-path`, `pytest --rootdir`), prefer that form over the `cd && ` chain. Edit / Write / Read tool calls already use absolute paths and need no cwd handling. The codex / gemini executor CLI wrappers (`okstra-codex-exec.sh -C`, `okstra-gemini-exec.sh --include-directories`) already inject worktree cwd at the CLI layer, so this rule applies primarily to the Claude executor.
-- **Synced okstra state directory.** At provision time `okstra-ctl` may symlink `.project-docs/` from the repo's **main worktree** into the task worktree. This is NOT an independent copy — writes through it land in the main worktree. Inside this run the executor MUST confine okstra artifact writes to its own task scope (i.e. `.project-docs/okstra/tasks/<this-task-id>/...`). Other synced directories, if present due to local configuration, are not implicit okstra context; read them only when the brief explicitly cites them as source material.
+- **Synced okstra state directory.** At provision time `okstra-ctl` may symlink `.project-docs/` from the repo's **main worktree** into the task worktree. This is NOT an independent copy — writes through it land in the main worktree. Inside this run the executor MUST confine okstra artifact writes to its own task scope (i.e. `.okstra/tasks/<this-task-id>/...`). Other synced directories, if present due to local configuration, are not implicit okstra context; read them only when the brief explicitly cites them as source material.
 
 ## Pre-implementation context exploration (executor before first edit)
 
@@ -54,7 +54,7 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
   - `<scope>` SHOULD be the plan step identifier or the primary module touched (e.g. `feat(report-writer): ...`). Omit the parentheses only when no meaningful scope applies.
   - `<subject>` MUST be ≤72 characters, imperative mood (`add`, `fix`, `remove` — not `added` / `adding`), no trailing period, no emoji, no AI attribution lines (no `Co-Authored-By: Claude ...`, no `Generated with Claude Code`).
   - Body (when present) explains *why*, not *what*; wrap at ~100 chars.
-  - Do NOT append okstra artefact paths to the commit message — no `Plan: .project-docs/okstra/...`, no `Report: ...`, no `Run: ...`, no `Task: ...` footers, and no other reference to files under `.project-docs/okstra/`. Those paths belong in the final report's `Plan link & approval evidence` section, not in git history; they rot quickly and leak internal layout into the upstream changelog.
+  - Do NOT append okstra artefact paths to the commit message — no `Plan: .okstra/...`, no `Report: ...`, no `Run: ...`, no `Task: ...` footers, and no other reference to files under `.okstra/`. Those paths belong in the final report's `Plan link & approval evidence` section, not in git history; they rot quickly and leak internal layout into the upstream changelog.
   - Allowed footers are limited to standard Conventional Commits trailers (`BREAKING CHANGE: ...`, `Refs: <issue/ticket-id>`, `Closes #<n>`). When citing a ticket, use the ticket id only (e.g. `Refs: DEV-9423`) — never a filesystem path.
   - One commit MUST correspond to one plan step (or one cohesive sub-step). Do NOT bundle unrelated steps into a single commit, and do NOT split a single step across commits unless the plan explicitly sequenced it that way.
   - The exact message used for each commit MUST be reproduced verbatim in the final report's `Commit list` so reviewers can audit it without re-running `git log`.

package/runtime/prompts/profiles/_implementation-verifier.md

@@ -23,7 +23,7 @@ Every verifier acts as a QA gate, not just a diff reviewer. Trusting the executo
 Verifier obtains the QA command set from exactly two declared sources, in order — there is **no fallback to guessing tools from manifest files**.
 
 1. **Tier 1 — plan validation set (task-specific):** every command listed under the approved plan's `validation` block (pre / mid / post).
-2. **Tier 2 — project baseline (`project.json.qaCommands`):** the project's standing QA baseline declared in `<PROJECT_ROOT>/.project-docs/okstra/project.json` under the `qaCommands` key. Schema (each category is an array of `{ "label", "cmd", "language"? }` objects):
+2. **Tier 2 — project baseline (`project.json.qaCommands`):** the project's standing QA baseline declared in `<PROJECT_ROOT>/.okstra/project.json` under the `qaCommands` key. Schema (each category is an array of `{ "label", "cmd", "language"? }` objects):
    ```json
    {
      "qaCommands": {

package/runtime/prompts/profiles/final-verification.md

@@ -31,7 +31,7 @@
   - **Residual Risk block** (under section 4): risks that are not blockers but should be tracked, each with mitigation owner and a trigger that would escalate them to a blocker.
   - **Validation Evidence**: for every requirement in the originating plan or task brief, cite the artifact (commit SHA, test output, log line, MCP SELECT result) that demonstrates coverage. Paraphrased "verified" claims without an artifact are rejected.
   - **Read-only command log**: any pre-existing test/validation command executed during this run MUST be listed with its exact command line and exit code. No mutating commands may appear here.
-  - **Two-tier command lookup (shared with `implementation`):** when this phase performs its own independent re-validation, the command source is exactly the same two tiers `implementation` verifiers use — Tier 1 is the originating task brief / approved plan's `validation` set, Tier 2 is `<PROJECT_ROOT>/.project-docs/okstra/project.json` under `qaCommands`. Auto-detecting tools from manifest files is forbidden; missing tiers are recorded as `qa-command not configured: <category>` and do NOT trigger a guess. The `cmd` deny-list (`--fix`, `--write`, ` -w`, ` -u`, `--snapshot-update`, `INSTA_UPDATE=<not-no>`, `cargo update`, `npm install` without `ci`, etc.) is enforced identically. NOTE: runtime fail-fast validation (`okstra_ctl.qa_commands.validate_qa_commands`) only fires at `--task-type implementation` run-prep, so this phase MUST self-check each `qaCommands` entry against the deny-list before executing it — if a denied token is present, skip the command and record it as a `Read-only command log` line `qa-command rejected (denied token: <token>): <label>`.
+  - **Two-tier command lookup (shared with `implementation`):** when this phase performs its own independent re-validation, the command source is exactly the same two tiers `implementation` verifiers use — Tier 1 is the originating task brief / approved plan's `validation` set, Tier 2 is `<PROJECT_ROOT>/.okstra/project.json` under `qaCommands`. Auto-detecting tools from manifest files is forbidden; missing tiers are recorded as `qa-command not configured: <category>` and do NOT trigger a guess. The `cmd` deny-list (`--fix`, `--write`, ` -w`, ` -u`, `--snapshot-update`, `INSTA_UPDATE=<not-no>`, `cargo update`, `npm install` without `ci`, etc.) is enforced identically. NOTE: runtime fail-fast validation (`okstra_ctl.qa_commands.validate_qa_commands`) only fires at `--task-type implementation` run-prep, so this phase MUST self-check each `qaCommands` entry against the deny-list before executing it — if a denied token is present, skip the command and record it as a `Read-only command log` line `qa-command rejected (denied token: <token>): <label>`.
   - **Routing recommendation**: brief note on the next safe phase (`done`, `error-analysis`, `implementation-planning`) tied to the verdict and blocker list.
 - Clarification request policy (phase-specific addendum — shared policy is in `_common-contract.md`):
   - populate `## 5. Clarification Items` only when a blocker hinges on information only the user can supply (deployment intent, intended target environment, business-rule interpretation); use `Blocks=next-phase` for items that gate continuing to release-handoff

package/runtime/prompts/profiles/implementation-planning.md

@@ -18,7 +18,7 @@
   - skim recent commits touching those files (`git log -- <path>`) to surface in-flight work or contested areas
   - **codebase-first ambiguity resolution**: any ambiguity that can be answered by `Read` / `Grep` MUST be resolved that way and recorded with file:line evidence. Only ambiguities that genuinely require a human decision are escalated as `Clarification Items` rows. Writing a clarification row for something the code already answers is a defect of this phase.
   - flag any requirement that is ambiguous, contradictory, or missing success criteria — register each one as a row in the report's `## 5. Clarification Items` table with `Blocks=approval` instead of guessing
-  - read `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` and `<PROJECT_ROOT>/.project-docs/okstra/decisions/` titles if present. Absent okstra memory files are the normal state — do not error. Treat the brief's `terminology:*` resolutions from `requirements-discovery` (if any) as authoritative; if missing, resolve any remaining fuzzy term as a `Blocks=approval` clarification row.
+  - read `<PROJECT_ROOT>/.okstra/glossary.md` and `<PROJECT_ROOT>/.okstra/decisions/` titles if present. Absent okstra memory files are the normal state — do not error. Treat the brief's `terminology:*` resolutions from `requirements-discovery` (if any) as authoritative; if missing, resolve any remaining fuzzy term as a `Blocks=approval` clarification row.
 - Primary focus areas:
   - requirement gaps
   - affected components and boundaries
@@ -43,7 +43,7 @@
   - executing builds, migrations, deployments, or any command that mutates project state outside the run's own artifact directories (`reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/`)
   - this run stays in `implementation-planning` regardless of user phrasing — the shared anti-escalation rule applies
   - dispatching parallel sub-agents beyond the required worker roster — okstra owns worker fan-out
-  - writing artifacts anywhere except `<PROJECT_ROOT>/.project-docs/okstra/` — the run's `reports/` directory is the canonical location for this phase
+  - writing artifacts anywhere except `<PROJECT_ROOT>/.okstra/` — the run's `reports/` directory is the canonical location for this phase
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
   - every clarification row carries a recommended answer + one-line rationale inside the `Expected form` cell; rows that lack a recommendation are rejected as half-formed.
   - **Evidence note required inside `Statement`**: every clarification row includes `Evidence checked: <path:line>` or `Evidence checked: none — <human-only reason>` in the `Statement` cell. `none` is allowed ONLY when the row's nature is "only a human can answer this" (reporter intent, business priority, organisational decision). A row with `none` that *could* have been answered by the codebase is a defect of this phase, restated from the pre-planning rule above.
@@ -77,9 +77,9 @@
     1. **Hard to reverse** — would changing the decision later cost meaningfully more than deciding now?
     2. **Surprising without context** — would a future reader, seeing only the code, wonder "why was it built this way?"?
     3. **Real trade-off** — were there named alternatives, and was one picked for specific reasons?
-    If **all three** hold, attach a decision draft as a report appendix section titled `Decision Drafts` (one decision per subsection). Each draft uses the `## Context / ## Decision / ## Consequences / ## Alternatives Considered` shape, names the alternatives that were rejected and why, and starts with `## Status: Proposed`. The next decision number is `(max existing in <PROJECT_ROOT>/.project-docs/okstra/decisions/ + 1)` zero-padded to 4 digits. If any of the three criteria is missing, do NOT raise a decision draft — instead record `skipped adr-candidate: <topic> — reason: <criterion that failed>` on one line under `Decision Drafts` so the next reader knows the candidate was evaluated and intentionally dropped.
-    The drafts are NOT written by this phase. The approved plan's stepwise execution order MUST include the step `Create <PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md from the decision draft in section X` so the `implementation` run commits the file inside okstra's subtree.
-  - **Glossary proposals**: if a term or definition should become okstra institutional memory, add the step `Update <PROJECT_ROOT>/.project-docs/okstra/glossary.md: <term> = <definition>` to the stepwise execution order. Use no other project-memory path.
+    If **all three** hold, attach a decision draft as a report appendix section titled `Decision Drafts` (one decision per subsection). Each draft uses the `## Context / ## Decision / ## Consequences / ## Alternatives Considered` shape, names the alternatives that were rejected and why, and starts with `## Status: Proposed`. The next decision number is `(max existing in <PROJECT_ROOT>/.okstra/decisions/ + 1)` zero-padded to 4 digits. If any of the three criteria is missing, do NOT raise a decision draft — instead record `skipped adr-candidate: <topic> — reason: <criterion that failed>` on one line under `Decision Drafts` so the next reader knows the candidate was evaluated and intentionally dropped.
+    The drafts are NOT written by this phase. The approved plan's stepwise execution order MUST include the step `Create <PROJECT_ROOT>/.okstra/decisions/<NNNN>-<slug>.md from the decision draft in section X` so the `implementation` run commits the file inside okstra's subtree.
+  - **Glossary proposals**: if a term or definition should become okstra institutional memory, add the step `Update <PROJECT_ROOT>/.okstra/glossary.md: <term> = <definition>` to the stepwise execution order. Use no other project-memory path.
 - No-placeholder rule (plan failures — reject any option or step that contains these):
   - "TBD", "TODO", "implement later", "fill in details", "add appropriate error handling", "handle edge cases", "write tests for the above" without actual test code
   - "similar to Option/Task N" without repeating the concrete content (readers may consume sections out of order)

package/runtime/prompts/profiles/release-handoff.md

@@ -43,7 +43,7 @@
      - `cancel` — end the run without executing push or PR commands; record the cancellation in the final report.
 - Inline drafting rules (Claude lead):
   - read the run brief, the cited final-verification report, `git log --oneline <base>..HEAD`, and `git diff <base>..HEAD --stat` to ground the drafted text in actual committed changes.
-  - **PR body template** — the run context exposes `PR_TEMPLATE_PATH` and `PR_TEMPLATE_SOURCE`. The path MUST be an okstra-owned project artifact under `<PROJECT_ROOT>/.project-docs/okstra/**` or a file already materialised into this run's artifact directory by the prepare step. The lead MUST `Read` this file verbatim, strip HTML comments, then fill in the placeholders. Do NOT hard-code a section list — the template is the source of truth for the structure. If the resolved file is missing or outside the okstra resource boundary at draft time, abort the run with a clear error rather than inventing a structure.
+  - **PR body template** — the run context exposes `PR_TEMPLATE_PATH` and `PR_TEMPLATE_SOURCE`. The path MUST be an okstra-owned project artifact under `<PROJECT_ROOT>/.okstra/**` or a file already materialised into this run's artifact directory by the prepare step. The lead MUST `Read` this file verbatim, strip HTML comments, then fill in the placeholders. Do NOT hard-code a section list — the template is the source of truth for the structure. If the resolved file is missing or outside the okstra resource boundary at draft time, abort the run with a clear error rather than inventing a structure.
   - produce **two artifacts** before showing them to the user:
     1. **PR title** — by default the subject of the most recent implementation commit, or a concise Conventional Commits-style summary of the committed range.
     2. **PR body** — markdown filled from `PR_TEMPLATE_PATH`. The user-confirmation step's diff (Q3 `edit then proceed`) is computed against the filled template, not against the raw template file.

package/runtime/prompts/profiles/requirements-discovery.md

@@ -19,7 +19,7 @@
   - identify missing materials that block reliable routing
   - define task continuity expectations for long-running work under the same task key
   - capture approval or confirmation points before the next phase starts
-  - **domain alignment check**: read `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` and `<PROJECT_ROOT>/.project-docs/okstra/decisions/` titles if present. Absent okstra memory files are normal — do not error. Validate that every `terminology:*` entry under the brief's `Open Questions` has a canonical resolution before routing. Fuzzy or overloaded terms in the brief MUST be resolved to a single canonical term in this phase.
+  - **domain alignment check**: read `<PROJECT_ROOT>/.okstra/glossary.md` and `<PROJECT_ROOT>/.okstra/decisions/` titles if present. Absent okstra memory files are normal — do not error. Validate that every `terminology:*` entry under the brief's `Open Questions` has a canonical resolution before routing. Fuzzy or overloaded terms in the brief MUST be resolved to a single canonical term in this phase.
 - Decision-tree walk (bounded):
   - When the brief's `Desired Outcome`, classification, or routing target depends on a chain of decisions, walk that chain one branch at a time. Each branch is one `Clarification Items` row, not a free-form interview.
   - For every clarification row, put the single best answer and one-line rationale in `Expected form` as `Recommended: ...`. Put other options and one-sentence consequences in the same cell as `Alternatives: ...`.
@@ -29,7 +29,7 @@
   - evidence-backed routing decision
   - uncertainty boundaries and missing inputs
   - next recommended phase and safe resume guidance
-  - canonical-term resolution for every `terminology:*` brief item, written as a one-line `<term> = <definition>` line in a new `Domain Alignment` subsection of the final report; alongside each, propose whether `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` should be updated (proposal only — actual writes happen via `okstra-brief` Step 4.5 on a subsequent run)
+  - canonical-term resolution for every `terminology:*` brief item, written as a one-line `<term> = <definition>` line in a new `Domain Alignment` subsection of the final report; alongside each, propose whether `<PROJECT_ROOT>/.okstra/glossary.md` should be updated (proposal only — actual writes happen via `okstra-brief` Step 4.5 on a subsequent run)
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
   - if any blocking input is missing at the time of writing the final report, populate `## 5. Clarification Items` in `final-report-template.md` (a single unified table; `Blocks=next-phase` for items the next run cannot start without)
   - prefer concrete questions whose answers map directly to a routing decision (`bugfix` vs `feature`, `error-analysis` vs `implementation-planning`, etc.). State each option in plain language with one sentence describing what choosing it would mean for the next phase.
@@ -39,4 +39,4 @@
 - Non-goals:
   - full implementation design unless it is required to decide the next phase
   - **source code edits, plan authoring, builds, or deployments** — this run only classifies the work and routes it; deeper analysis and planning belong to subsequent phases
-  - **writes outside `<PROJECT_ROOT>/.project-docs/okstra/`** — this phase only uses okstra's artifact root. Glossary additions land in `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` (via `okstra-brief` Step 4.5); decision drafts land in `<PROJECT_ROOT>/.project-docs/okstra/decisions/` (via `implementation-planning`).
+  - **writes outside `<PROJECT_ROOT>/.okstra/`** — this phase only uses okstra's artifact root. Glossary additions land in `<PROJECT_ROOT>/.okstra/glossary.md` (via `okstra-brief` Step 4.5); decision drafts land in `<PROJECT_ROOT>/.okstra/decisions/` (via `implementation-planning`).

package/runtime/prompts/wizard/prompts.ko.json

@@ -23,6 +23,20 @@
       "options": {
         "__use_suggested__": "brief 값 사용: {suggestion}",
         "__free_input__": "다른 값 입력"
+      },
+      "echo_variants": {
+        "free_input": "task-group: (직접 입력)"
+      }
+    },
+    "task_group_no_suggestion": {
+      "label": "Task group? (예: backend-api, INV-1234)",
+      "echo_template": "task-group: {value}",
+      "options": {
+        "__free_input__": "직접 입력"
+      },
+      "recent_label_prefix": "최근 사용: ",
+      "echo_variants": {
+        "free_input": "task-group: (직접 입력)"
       }
     },
     "task_group_text": {
@@ -42,6 +56,20 @@
       "options": {
         "__use_suggested__": "brief 값 사용: {suggestion}",
         "__free_input__": "다른 값 입력"
+      },
+      "echo_variants": {
+        "free_input": "task-id: (직접 입력)"
+      }
+    },
+    "task_id_no_suggestion": {
+      "label": "Task id? (예: login-error-analysis, dev-9043)",
+      "echo_template": "task-id: {value}",
+      "options": {
+        "__free_input__": "직접 입력"
+      },
+      "recent_label_prefix": "같은 group 의 기존: ",
+      "echo_variants": {
+        "free_input": "task-id: (직접 입력)"
       }
     },
     "task_id_text": {
@@ -66,6 +94,18 @@
         "kept": "brief: {brief_path} (유지)"
       }
     },
+    "brief_path_pick": {
+      "label": "task brief markdown 의 경로를 선택해주세요",
+      "echo_template": "brief(pick): {value}",
+      "options": {
+        "__existing__": "기존 brief 사용: {existing}",
+        "__standard__": "표준 경로 사용: {standard}",
+        "__free_input__": "직접 입력"
+      },
+      "errors": {
+        "existing_missing": "기존 brief 가 없습니다. 다른 옵션을 선택하세요."
+      }
+    },
     "brief_path": {
       "label": "task brief markdown 의 경로를 알려주세요 (project root 기준 상대경로 또는 절대경로)",
       "echo_template": "brief: {value}"
@@ -87,10 +127,16 @@
       "echo_template": "approved-plan(pick): {value}",
       "options": {
         "__use_default__": "기본 경로 사용: {default}",
-        "__other__": "다른 경로 입력"
+        "__other__": "직접 입력"
+      },
+      "labels": {
+        "other_report": "이전 보고서: {path}"
+      },
+      "echo_suffixes": {
+        "other_report": "(이전 보고서)"
       },
       "errors": {
-        "default_not_found": "기본 approved-plan 경로를 찾을 수 없습니다. '다른 경로 입력'을 선택하세요."
+        "default_not_found": "기본 approved-plan 경로를 찾을 수 없습니다. '직접 입력'을 선택하세요."
       }
     },
     "approved_plan": {
@@ -109,7 +155,14 @@
       "echo_template": "directive(pick): {value}",
       "options": {
         "__skip__": "없음 (건너뛰기)",
-        "__enter__": "있음 (입력)"
+        "__free_input__": "직접 입력"
+      },
+      "labels": {
+        "reuse_last": "이전 run 의 directive 재사용: {snippet}"
+      },
+      "echo_suffixes": {
+        "reuse": "directive: {value} (재사용)",
+        "skip": "directive: (none)"
       }
     },
     "related_tasks_pick": {
@@ -117,7 +170,14 @@
       "echo_template": "related-tasks(pick): {value}",
       "options": {
         "__skip__": "없음 (건너뛰기)",
-        "__enter__": "있음 (입력)"
+        "__free_input__": "직접 입력"
+      },
+      "labels": {
+        "siblings": "같은 group 의 task-id 사용: {snippet}"
+      },
+      "echo_suffixes": {
+        "skip": "related-tasks: (none)",
+        "siblings": "related-tasks: {value} (siblings)"
       }
     },
     "clarification_pick": {
@@ -125,7 +185,14 @@
       "echo_template": "clarification(pick): {value}",
       "options": {
         "__skip__": "없음 (건너뛰기)",
-        "__enter__": "있음 (입력)"
+        "__free_input__": "직접 입력"
+      },
+      "labels": {
+        "latest_report": "최근 final-report 사용: {snippet}"
+      },
+      "echo_suffixes": {
+        "skip": "clarification: (none)",
+        "latest_report": "clarification: {value} (재사용)"
       }
     },
     "pr_template_pick": {
@@ -133,7 +200,14 @@
       "echo_template": "pr-template(pick): {value}",
       "options": {
         "__skip__": "자동 해석 (project.json → config → 기본)",
-        "__enter__": "직접 경로 입력 (1회성 override)"
+        "__free_input__": "직접 입력"
+      },
+      "labels": {
+        "project_default": "project.json 의 prTemplatePath 사용: {snippet}"
+      },
+      "echo_suffixes": {
+        "skip": "pr-template: (auto-resolve)",
+        "project_default": "pr-template: {value} (project default)"
       }
     },
     "executor": {

package/runtime/python/lib/okstra/interactive.sh

@@ -78,7 +78,7 @@ def slugify(value: str) -> str:
 
 candidates = []
 
-catalog_path = project_root / ".project-docs" / "okstra" / "discovery" / "task-catalog.json"
+catalog_path = project_root / ".okstra" / "discovery" / "task-catalog.json"
 catalog_keys = []
 if catalog_path.is_file():
     try:
@@ -111,7 +111,7 @@ if catalog_path.is_file():
                         sys.exit(0)
                     candidates.append(str(abs_path))
 
-slug_path = project_root / ".project-docs" / "okstra" / "tasks" / slugify(task_group) / slugify(task_id)
+slug_path = project_root / ".okstra" / "tasks" / slugify(task_group) / slugify(task_id)
 if slug_path.is_dir():
     print(f"OK\t{slug_path}")
     sys.exit(0)

package/runtime/python/lib/okstra/project-resolver.sh

@@ -1,7 +1,7 @@
 # shellcheck shell=bash
 
 # bash wrappers around scripts/okstra_project resolver. okstra.sh 가 시작 시
-# PROJECT_ROOT 를 확정하고 <PROJECT_ROOT>/.project-docs/okstra/project.json 을
+# PROJECT_ROOT 를 확정하고 <PROJECT_ROOT>/.okstra/project.json 을
 # upsert 한다. 과거 conf 파일 모델은 폐기되었다.
 
 # 절대경로(또는 빈 문자열) 를 stdout 으로 출력한다. 실패 시 stderr 에 메시지를

package/runtime/python/lib/okstra/usage.sh

@@ -16,7 +16,7 @@ summary:
 
 required arguments:
   --project-id         Globally unique project ID. Example: sample-project-v2-api.
-                       Each project is registered at <project-root>/.project-docs/okstra/project.json
+                       Each project is registered at <project-root>/.okstra/project.json
                        on first run; subsequent runs verify the projectId there matches.
   --task-group         Logical task group. Example: backend-api, bugfix, linear-8858
   --task-id            Stable task identifier inside the task group. Example: login-error-analysis
@@ -25,7 +25,7 @@ required arguments:
 
 optional arguments:
   --project-root       Absolute path to the target project root. Resolution order when omitted:
-                       (1) ancestor of cwd that contains .project-docs/okstra/project.json,
+                       (1) ancestor of cwd that contains .okstra/project.json,
                        (2) `git rev-parse --show-toplevel` from cwd. Errors out if neither resolves.
   --directive        Free-form user-supplied directive carried into the run as a "## Directive" section
                        inside instruction-set/analysis-material.md. Lead, workers, and skills (e.g. okstra-schedule)
@@ -107,15 +107,15 @@ model defaults:
 
 output:
   Stable task bundles are stored under:
-    <target-project>/.project-docs/okstra/tasks/<task-group>/<task-id>/
+    <target-project>/.okstra/tasks/<task-group>/<task-id>/
   Per-run history is stored under:
-    <target-project>/.project-docs/okstra/tasks/<task-group>/<task-id>/runs/
+    <target-project>/.okstra/tasks/<task-group>/<task-id>/runs/
   Inside each run date folder, artifacts are grouped by type under:
     manifests/, state/, prompts/, reports/, status/, sessions/, worker-results/
 
 project-level discovery:
   Latest $DISPLAY_TOOL_NAME task pointer:
-    <target-project>/.project-docs/okstra/discovery/latest-task.json
+    <target-project>/.okstra/discovery/latest-task.json
 
 interactive behavior:
   If required arguments are missing and stdin is interactive, $DISPLAY_TOOL_NAME prompts for them.

package/runtime/python/lib/okstra-ctl/cmd-rerun.sh

@@ -216,7 +216,7 @@ for original in targets:
                 slug_group = slugify_task_segment(row["taskGroup"])
                 slug_task = slugify_task_segment(row["taskId"])
                 slug_type = slugify_task_segment(row["taskType"])
-                base_run = (".project-docs/okstra/tasks/"
+                base_run = (".okstra/tasks/"
                             f"{slug_group}/{slug_task}/runs/{slug_type}")
                 final_rel = (f"{base_run}/reports/"
                              f"final-report-{slug_type}-{next_seq:03d}.md")

package/runtime/python/okstra_ctl/backfill.py

@@ -7,6 +7,8 @@ import re as _re
 from pathlib import Path
 from typing import List
 
+from okstra_project.dirs import tasks_root
+
 from .ids import build_run_id
 from .invocation import invocation_path, save_invocation
 from .jsonl import append_jsonl, read_jsonl, rotate_recent_if_needed
@@ -19,7 +21,7 @@ def discover_project_roots(home: Path) -> List[tuple]:
     project_root) 목록을 반환한다.
 
     신규 모델에서는 okstra.sh 가 첫 실행 시 PROJECT_ROOT 를 해석해
-    `<PROJECT_ROOT>/.project-docs/okstra/project.json` 에 자기 등록하고,
+    `<PROJECT_ROOT>/.okstra/project.json` 에 자기 등록하고,
     record_start 가 그 PROJECT_ROOT 를 meta.json 에 mirror 한다. ctl 입장
     에서는 한 번이라도 record_start 를 거친 프로젝트는 meta.json 에 등재
     되어 있으므로, examples/projects 같은 외부 등록 디렉토리가 필요하지
@@ -88,11 +90,11 @@ def _apply_backfill_meta(home: Path, project_id: str, project_root: Path, *,
 
 
 def backfill_project(home: Path, project_id: str, project_root: Path) -> int:
-    """타깃 프로젝트의 .project-docs/okstra/tasks 를 스캔해 누락된 run 을 인덱스에 채움.
+    """타깃 프로젝트의 okstra tasks 디렉토리를 스캔해 누락된 run 을 인덱스에 채움.
     실제 okstra 레이아웃: runs/<task_type>/manifests/run-manifest-<task_type>-<seq:03d>.json
     이미 존재하는 runId 는 스킵. 새로 추가된 run 수를 반환.
     """
-    base = project_root / ".project-docs" / "okstra" / "tasks"
+    base = tasks_root(project_root)
     if not base.is_dir():
         return 0
     existing_index = home / "projects" / project_id / "index.jsonl"