okstra 0.11.0 → 0.12.0

package/README.md

@@ -164,7 +164,7 @@ Notable flags added in 0.7.0 / 0.8.0:
 
 Recent workflow additions (post-0.8.0, on `main`):
 
-- **Isolated executor worktree for `--task-type implementation`** — prepare automatically runs `git worktree add ~/.okstra/worktrees/<project>/<group>/<task>-<seq>` on a fresh branch `<work-category-prefix>-<task-id-segment>-<seq>` branched from `HEAD`. Executor and verifiers operate inside that worktree so the caller's working tree stays clean, and the worktree is preserved after the run as the canonical artefact for 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>`. Details: [`docs/kr/architecture.md`](docs/kr/architecture.md) (*Task type* section) and [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
+- **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 main worktree's `HEAD` the first time a task-key is seen. Every subsequent phase of the same task-key (`requirements-discovery` → `error-analysis` → `implementation-planning` → `implementation`) 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 removing the task-key entry 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).
 
 ### 3.5 Ops commands

package/docs/kr/architecture.md

@@ -321,7 +321,7 @@ Claude launch prompt 본문은 항상 `prompts/launch.template.md` 템플릿에
 공통 제약:
 
 - `implementation`을 제외한 모든 phase는 source code edit, build, migration, deployment, 그 밖의 state-mutating 명령을 금지합니다(`final-verification`은 read-only 테스트 명령만 허용). `implementation`은 승인된 plan의 파일 목록 안에서만 edit/commit이 허용되며, `git push`·publish·deploy·실제 migration·third-party write API는 여전히 금지됩니다.
-- **`implementation` 격리 worktree (BLOCKING)**: `--task-type implementation` run은 prepare 단계에서 `okstra-ctl` 이 자동으로 `git worktree` 를 생성해 executor·verifier가 모두 그 안에서 작업하도록 강제합니다. 위치는 `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>-<run-seq>` 이고, 브랜치 이름은 `<work-category-prefix>-<task-id-segment>-<run-seq>` (예: `feat-dev-9436-001`, `fix-dev-7311-002`) 입니다. base ref 는 prepare 시점의 `HEAD`. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 되고 executor 는 project_root 에서 그대로 작업합니다. worktree 는 run 종료 후 자동 삭제되지 않으며 PR 작성·rollback 검증·후속 `final-verification` 의 권위 artefact 입니다. 수동 cleanup: `git -C <project_root> worktree remove <path>` 후 `git -C <project_root> branch -D <branch>`. 자세한 동작은 `prompts/profiles/implementation.md` 의 *Executor worktree* 블록과 `agents/SKILL.md` 의 *Implementation phase: Executor binding → Executor worktree* 섹션 참고.
+- **모든 task-type 격리 worktree (BLOCKING)**: 모든 task-type 의 첫 번째 phase prepare 단계에서 `okstra-ctl` 이 자동으로 task-key 단위 `git worktree` 를 생성하고, 같은 task-key 의 이후 phase (`requirements-discovery` → `error-analysis` → `implementation-planning` → `implementation`) 는 동일한 worktree·브랜치를 재사용합니다. 위치는 `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/` (segment 의 `/`·`:` 등 특수문자는 `-` 로 정규화) 이고, 브랜치 이름은 `<work-category-prefix>-<task-id-segment>` (예: `feat-dev-9436`, `fix-dev-7311`) 입니다. base ref 는 첫 phase prepare 시점의 main worktree `HEAD`. `~/.okstra/worktrees/registry.json` (flock-guarded) 가 task-key → path/branch 매핑을 전역 관리해 동시 실행 시 path·branch 충돌을 방지합니다. `.project-docs/`, `.scratch/`, `graphify-out/` 은 main worktree 에서 symlink 로 연결되어 모든 task 가 동일한 shared state 를 봅니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 되고 executor 는 project_root 에서 그대로 작업합니다. worktree 는 run 종료 후 자동 삭제되지 않으며 후속 phase·PR 작성·rollback 검증의 권위 artefact 입니다. 수동 cleanup: `git -C <main-worktree> worktree remove <path>` → `git -C <main-worktree> branch -D <branch>` + registry 항목 삭제. 자세한 동작은 `prompts/profiles/implementation.md` 의 *Task worktree* 블록과 `agents/SKILL.md` 의 *Task worktree (BLOCKING for every task-type)* 섹션 참고.
 - `implementation` 과 `release-handoff` 를 제외한 모든 phase 는 source code edit, build, migration, deployment, 그 밖의 state-mutating 명령을 금지합니다 (`final-verification` 은 read-only 테스트 명령만 허용). `implementation` 은 승인된 plan 의 파일 목록 안에서만 edit/commit 이 허용되며, `git push`·publish·deploy·실제 migration·third-party write API 는 여전히 금지됩니다. `release-handoff` 는 source code 자체는 수정하지 않고, 사용자가 메뉴로 선택한 commit / push / PR 명령만 실행합니다 (force push, base 브랜치 직접 push, hook bypass, release publish 는 여전히 금지).
 - 사용자가 "다음 단계 진행해" 같은 표현을 보내도, 그 발화만으로 다음 phase가 자동 시작되지 않습니다. 다음 phase는 새 `okstra.sh` 실행으로만 시작합니다.
 - **Authority & permissions assumption (HARD RULE — 모든 task-type 및 `okstra-schedule` 공통)**: 사용자(및 팀)는 예상되는 모든 작업에 대해 완전한 권한·승인 권한을 보유한다고 가정합니다. 외부 승인, 서드파티 액세스, 역할/IAM 권한, 조직적 sign-off, 법무·보안 검토, 벤더 협의, "권한 보유 여부 확인" 같은 항목을 routing 결정·missing inputs·clarification questions·risk·dependency·open questions·effort/day 추정에 포함하지 않습니다. okstra 내부 phase 핸드오프(`User Approval Request` 등)는 사용자 본인이 즉시 승인 가능한 내부 게이트이므로 영향 없으며, `implementation`의 forbidden actions(`git push`, prod deploy, shared-DB migration 등)도 권한 사유가 아닌 **안전 사유**로 계속 적용됩니다.

package/docs/kr/cli.md

@@ -288,7 +288,7 @@ fallback 기본값은 아래와 같습니다.
 - Executor 의 모델은 provider 별 worker 모델 플래그를 그대로 재사용합니다. 즉 `--executor codex` 이면 Executor 의 모델은 `--codex-model` (기본 `gpt-5.5`), `--executor gemini` 이면 `--gemini-model` (기본 `auto`) 가 됩니다.
 - Claude/Codex/Gemini 세 verifier 는 executor provider 와 관계없이 항상 dispatch 됩니다. Executor 와 같은 provider 라도 별도 CLI 세션으로 verifier 가 호출되어 context 가 분리되므로 self-review 안전장치는 유지됩니다.
 - 실제 파일 변경은 Codex/Gemini 의 경우 각 CLI 의 auto-edit 모드 (예: `codex exec --full-auto`) 를 통해 일어나며, Claude-side Edit/Write tool 을 거치지 않습니다.
-- **Executor worktree (자동 격리)**: prepare 단계에서 `okstra-ctl` 이 `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>-<run-seq>` 에 `git worktree` 를 생성하고, 브랜치 `<work-category-prefix>-<task-id-segment>-<run-seq>` 를 prepare 시점 `HEAD` 에서 분기합니다. Executor 의 Edit/Write/build/test/commit 은 모두 이 worktree 안에서 수행되며, verifier 들도 같은 worktree 를 읽어 동일한 diff 를 봅니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 되고 status 가 `skipped-in-worktree` / `skipped-not-git` 로 기록됩니다. 경로·브랜치 충돌은 `PrepareError` 로 즉시 실패시키며, run 종료 후 worktree 는 자동 삭제하지 않습니다(수동: `git worktree remove` → `git branch -D`).
+- **Task worktree (모든 task-type 자동 격리)**: 모든 task-type 의 첫 번째 phase prepare 단계에서 `okstra-ctl` 이 `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/` 에 `git worktree` 를 생성하고, 브랜치 `<work-category-prefix>-<task-id-segment>` 를 main worktree `HEAD` 에서 분기합니다. 같은 task-key 의 이후 phase 는 동일한 path/branch 를 재사용하므로 status 가 `reused` 로 기록됩니다 (run-prep 시점에 새 `git worktree add` 가 일어나지 않음). 모든 segment 의 `/`·`:` 등 특수문자는 `-` 로 정규화되며, `~/.okstra/worktrees/registry.json` 가 task-key → path/branch 매핑을 전역 관리합니다 (flock-guarded). Executor 의 Edit/Write/build/test/commit, verifier 의 read 는 모두 이 worktree 안에서 수행됩니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 되고 status 가 `skipped-in-worktree` / `skipped-not-git` 로 기록됩니다. 경로·브랜치 충돌은 `PrepareError` 로 즉시 실패시키며, run 종료 후 worktree 는 자동 삭제하지 않습니다 (수동: `git worktree remove` → `git branch -D` + registry 항목 삭제).
 
 예:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.11.0",
+  "version": "0.12.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.11.0",
-  "builtAt": "2026-05-12T17:46:50.784Z",
+  "package": "0.12.0",
+  "builtAt": "2026-05-12T18:39:56.088Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -107,18 +107,21 @@ Lead MUST dispatch Edit/Write-bearing work only through the `workerAgent` declar
 
 Executor is chosen at run-prep time via `--executor <claude|codex|gemini>` (or `OKSTRA_DEFAULT_EXECUTOR`, fallback `claude`); the model used by the executor is taken from the corresponding worker model flag (`--claude-model` / `--codex-model` / `--gemini-model`). For Codex/Gemini executors, the underlying file mutation happens inside the executor CLI's own auto-edit mode (e.g. `codex exec --full-auto`), not through Claude-side Edit/Write tools.
 
-#### Executor worktree (BLOCKING for `implementation`)
+#### Task worktree (BLOCKING for every task-type)
 
-For `--task-type implementation` runs, `okstra-ctl` provisions a dedicated `git worktree` at run-prep time. Lead, the Executor, and every verifier MUST treat the provisioned worktree as the canonical working directory.
+`okstra-ctl` provisions a dedicated `git worktree` per task-key at run-prep time of the **first** phase, and every subsequent phase of the same task-key reuses the same worktree on the same branch. Lead, the Executor, and every verifier MUST treat the provisioned worktree as the canonical working directory regardless of task-type.
 
-- Location: `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>-<run-seq>` (override `OKSTRA_HOME` only for tests).
-- Branch: `<work-category-prefix>-<task-id-segment>-<run-seq>` (e.g. `feat-dev-9436-001`, `fix-dev-7311-002`). Branched from `HEAD` of `project_root` at prep time; base SHA is recorded in `EXECUTOR_WORKTREE_BASE_REF`.
-- The worktree path, branch, base ref, and provisioning status (`created` | `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; executor uses `project_root` directly):
+- One worktree per task-key — `requirements-discovery`, `error-analysis`, `implementation-planning`, and `implementation` all share the same path and branch so phase N inherits the working-tree state phase N-1 left behind.
+- 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.
+- Sync dirs (`.project-docs`, `.scratch`, `graphify-out` by default; override with `OKSTRA_WORKTREE_SYNC_DIRS`) are symlinked from the **main worktree** so every task observes the same shared state irrespective of which checkout invoked okstra.
+- 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).
   - `project_root` is not inside a git repository at all.
-- **Failure mode**: any other error during `git worktree add` (path collision, branch collision, detached-HEAD with no SHA) raises `PrepareError`. Re-run after manually removing the stale path/branch — the worktree is intentionally not garbage-collected.
-- **Lifecycle**: kept after the run for manual PR authoring, rollback verification, and follow-up `final-verification` runs. Manual cleanup: `git -C <project_root> worktree remove <path>` then `git -C <project_root> branch -D <branch>`.
+- **Failure mode**: any other error during `git worktree add` (on-disk path collision not tracked by the registry, branch collision with a different task-key, detached-HEAD with no SHA) raises `PrepareError`. Re-run after manually removing the stale path/branch — the worktree is intentionally not garbage-collected.
+- **Lifecycle**: kept after the run for follow-up phases, manual PR authoring, rollback verification, and `final-verification`. Manual cleanup: `git -C <main-worktree> worktree remove <path>` then `git -C <main-worktree> branch -D <branch>`; remove the corresponding registry entry by hand or via `okstra worktree release <task-key>` (when available).
 
 ## Phase 1: Task-bundle intake and required reading order
 

package/runtime/prompts/launch.template.md

@@ -14,31 +14,7 @@ Invoke the `okstra` skill now. Read the manifests below for all task metadata, p
 - Phase advancement requires a new okstra invocation launched with `--task-type {{WORKFLOW_NEXT_RECOMMENDED_PHASE}}` after this run's final report is written and approved. The lead must not write source code, run builds/migrations/deployments, or otherwise produce artifacts of a different phase from inside this run.
 - See `Lifecycle Phase Boundaries` in the okstra skill (`agents/SKILL.md`) for the canonical rules and the phase-transition checklist.
 
-## Team Creation Gate (BLOCKING)
-
-Before any `Agent` dispatch for workers, you MUST perform Phase 3 of the
-`okstra` skill (`agents/SKILL.md` → "Phase 3 — Team creation"). Skipping
-this gate silently degrades the run to in-process background dispatch and
-loses the Teams split-pane observability surface, even though worker
-outputs may still appear correct on disk.
-
-Required actions, in order, regardless of how many workers are selected
-for this run (roster comes from `resultContract.requiredWorkerRoles` in
-`task-manifest.json` — it may be 1, 2, 3, or more workers):
-
-1. Invoke the `okstra-team-contract` skill and verify the selected worker
-   roster against `task-manifest.json`'s `resultContract.requiredWorkerRoles`.
-2. Call `TeamCreate(team_name: "okstra-{{TASK_KEY}}", description: ...)`.
-3. Record the outcome in team-state under
-   `teamCreate: { attempted: true, status: "ok" | "error", error?: <msg> }`
-   BEFORE any `Agent(...)` worker dispatch.
-4. Only after `teamCreate` is persisted may you dispatch workers — with
-   `team_name` on success, or with `run_in_background: true` and no
-   `team_name` ONLY when `teamCreate.status == "error"` was recorded.
-
-If the Agent tool rejects a dispatch with `"team must be created first"` /
-`"team을 먼저 생성하거나 team_name 없이 호출해야 합니다"`, the correct
-response is to go back to step 2 — NOT to strip `team_name` and retry.
+{{TEAM_CREATION_GATE}}
 
 ## Project Root
 
@@ -70,9 +46,10 @@ response is to go back to step 2 — NOT to strip `team_name` and retry.
 - Branch: `{{EXECUTOR_WORKTREE_BRANCH}}`
 - Base ref: `{{EXECUTOR_WORKTREE_BASE_REF}}`
 - Note: `{{EXECUTOR_WORKTREE_NOTE}}`
-- For `implementation` runs with status `created`, the Executor MUST perform every Edit / Write / build / test command inside the working tree path above. Verifiers (Claude / Codex / Gemini) read from the SAME path so they observe the exact diff produced by the Executor.
-- The worktree is preserved after the run (no automatic cleanup). PR authoring, manual review, and rollback verification happen from the worktree branch.
-- For any other status (`skipped-non-implementation`, `skipped-in-worktree`, `skipped-not-git`), the run operates directly in `{{PROJECT_ROOT}}` and this section is informational only.
+- For any task-type with status `created` or `reused`, every role (lead, executor, verifier) MUST anchor reads and writes to the working tree path above — phase N inherits the working-tree state phase N-1 left behind. Verifiers read from the SAME path so they observe the exact diff produced by the Executor.
+- Branch and path are globally reserved per task-key via `~/.okstra/worktrees/registry.json`; concurrent okstra runs on this machine cannot collide.
+- The worktree is preserved after every run (no automatic cleanup) and is reused by every subsequent phase of the same task-key. Manual cleanup when fully done: `git worktree remove <path>` → `git branch -D <branch>` + remove the task-key entry from the registry.
+- For status `skipped-in-worktree` or `skipped-not-git`, the run operates directly in `{{PROJECT_ROOT}}` and this section is informational only.
 
 ## Available MCP Servers
 

package/runtime/prompts/profiles/implementation.md

@@ -27,17 +27,17 @@
     - **CLI ack** — the user runs `okstra ... --task-type implementation --approved-plan <path> --approve`. The CLI invocation itself is modelled as the user's act of approval; the runtime (`okstra_ctl.run._apply_cli_approval`) flips the checkbox in the report file and appends an audit line `- 승인 일시 (CLI ack): <ISO8601> — recorded by \`okstra --approve\`` before the standard regex validation runs. Use this when running unattended or when you want a single command to both approve and launch the next phase.
   - The `--approve` flag is **only meaningful with `--task-type implementation` and `--approved-plan <path>`**. Passing it with any other task-type causes `PrepareError` (the runtime refuses to silently ignore approval signals). It is also a no-op if the file already carries a valid approval marker (idempotent — only an audit line is appended, the marker is not re-toggled).
   - the file's `Recommended option` and its bite-sized step list become the authoritative scope for this run; any deviation must be justified in the final report and routed back to a new `implementation-planning` run instead of being silently expanded.
-- Executor worktree (provisioned by `okstra-ctl` at run-prep time, fixed for this run):
-  - Status: `{{EXECUTOR_WORKTREE_STATUS}}` (one of: `created` | `skipped-in-worktree` | `skipped-not-git`)
-  - Working tree path: `{{EXECUTOR_WORKTREE_PATH}}` — when status is `created`, this is a fresh `git worktree` rooted under `~/.okstra/worktrees/<project>/<task-group>/<task-id>-<seq>`; when skipped, this is the caller's `project_root`.
-  - Branch: `{{EXECUTOR_WORKTREE_BRANCH}}` — empty when status is `skipped-*`. The branch name encodes `<work-category-prefix>-<task-id-segment>-<seq>`.
-  - Base ref: `{{EXECUTOR_WORKTREE_BASE_REF}}` — commit SHA the worktree was branched from; canonical `<base>` for every `git diff` / `git log` in this run.
+- Task worktree (provisioned by `okstra-ctl` at the first phase's run-prep time, reused for every subsequent phase of this task-key):
+  - Status: `{{EXECUTOR_WORKTREE_STATUS}}` (one of: `created` | `reused` | `skipped-in-worktree` | `skipped-not-git`)
+  - Working tree path: `{{EXECUTOR_WORKTREE_PATH}}` — when status is `created` or `reused`, this is the task's `git worktree` rooted at `~/.okstra/worktrees/<project>/<task-group>/<task-id>/` (segments sanitised — `/` `:` → `-`). When skipped, this is the caller's `project_root`.
+  - Branch: `{{EXECUTOR_WORKTREE_BRANCH}}` — empty when status is `skipped-*`. The branch name encodes `<work-category-prefix>-<task-id-segment>` and is globally unique across task-keys via `~/.okstra/worktrees/registry.json`.
+  - Base ref: `{{EXECUTOR_WORKTREE_BASE_REF}}` — commit SHA the worktree was branched from at the first phase; canonical `<base>` for every `git diff` / `git log` in this run.
   - Provisioning note: `{{EXECUTOR_WORKTREE_NOTE}}`
-  - **Executor behaviour**: when status is `created`, the Executor MUST run every Edit / Write / build / test / commit command with the working tree path above 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.
+  - **Executor behaviour**: when status is `created` or `reused`, the Executor MUST run every Edit / Write / build / test / commit command with the working tree path above 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.
   - **Verifier behaviour**: all three verifier roles read from the SAME working tree path so they observe the exact diff the Executor produced. Verifiers remain strictly read-only there.
-  - **Lifecycle**: the worktree is kept after the run completes (no automatic cleanup). It is the canonical artefact for manual PR authoring, rollback verification, and follow-up `final-verification` runs. Cleanup, when desired, is manual: `git -C <project_root> worktree remove <path>` followed by `git -C <project_root> branch -D <branch>`.
+  - **Lifecycle**: the worktree is kept after the run completes (no automatic cleanup) and is reused by every subsequent phase of the same task-key. Cleanup, when the task is fully done, is manual: `git -C <main-worktree> worktree remove <path>` followed by `git -C <main-worktree> branch -D <branch>`, plus removing the task-key entry from `~/.okstra/worktrees/registry.json`.
   - **Skipped paths**: when status is `skipped-in-worktree` or `skipped-not-git`, the executor operates in `project_root` as before. Cite the status in the final report's metadata header so reviewers know which path was taken.
-  - **Synced state directories (symlinks into the original `project_root`)**: at provision time `okstra-ctl` symlinks `.project-docs/`, `.scratch/`, and `graphify-out/` from the original `project_root` into the worktree (override via `OKSTRA_WORKTREE_SYNC_DIRS`; empty string disables). These are NOT independent copies — writes through them land in `project_root`. Inside this run the executor MUST confine writes under these paths to its own task scope (i.e. only `.project-docs/okstra/tasks/<this-task-id>/...`). Reading from elsewhere under the symlinks (other tasks, `graphify-out/GRAPH_REPORT.md`, `.scratch/` issues) is allowed and expected for context.
+  - **Synced state directories (symlinks into the MAIN worktree)**: at provision time `okstra-ctl` symlinks `.project-docs/`, `.scratch/`, and `graphify-out/` from the repo's **main worktree** into the task worktree (override via `OKSTRA_WORKTREE_SYNC_DIRS`; empty string disables). These are NOT independent copies — writes through them land in the main worktree. Inside this run the executor MUST confine writes under these paths to its own task scope (i.e. only `.project-docs/okstra/tasks/<this-task-id>/...`). Reading from elsewhere under the symlinks (other tasks, `graphify-out/GRAPH_REPORT.md`, `.scratch/` issues) is allowed and expected for context.
 - Pre-implementation context exploration (executor before first edit):
   - **Mandatory skill invocation — `tdd`**: BEFORE the first `Edit` or `Write` call, the executor MUST invoke the `tdd` skill via the `Skill` tool and follow its red-green-refactor loop for every code change in this run. This is a hard requirement, not a recommendation; skipping it is a `contract-violated` outcome. The skill governs HOW each step is executed (failing test first → minimal implementation → refactor); it does not override the approved plan's WHAT/file scope.
     - Order of operations per plan step: (1) write/extend the test that captures the step's acceptance criterion and confirm it fails for the right reason, (2) commit the failing test (`test(<scope>): ...`), (3) implement the minimum change to make it pass, (4) commit the implementation (`feat|fix(<scope>): ...`), (5) refactor without changing behaviour and commit separately if any cleanup is made (`refactor(<scope>): ...`). The failing-then-passing transition between steps (2) and (4) is the `TDD evidence` required by the final report.

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

@@ -1,14 +1,15 @@
 # Release Handoff Profile
 
 - Purpose: take an `accepted` final-verification verdict and turn it into a delivered commit and/or pull request, with explicit user selection at every mutating step
-- Required workers:
-  - claude
-  - report-writer
-{{INCLUDE:_common-contract.md}}
-- Team contract (phase-specific overrides):
-  - `Claude lead` is the **executor of every git / gh command** in this phase. Workers never call mutating git commands themselves.
-  - `Claude worker` (drafter) is read-only and produces **commit message candidate(s) and a PR body candidate** in markdown; the lead presents these to the user, accepts edits, and only then runs git.
-  - Codex / Gemini workers are NOT part of this profile's roster (see `Required workers:` above); the shared contract's `Gemini worker must always be attempted` clause does not apply to release-handoff.
+- **Execution model: single-lead, no worker dispatch.** This phase is a thin orchestrator over `git` / `gh`; it does NOT run team-mode, does NOT call `TeamCreate`, does NOT dispatch analysis or drafter sub-agents, and does NOT run convergence. The Claude lead performs every step inline (drafting commit/PR text, asking the user, running git, writing the final report) — see "Lead-only contract" below.
+- Required workers: *(none — this profile intentionally has no `- Required workers:` block; the run is executed entirely by the Claude lead)*
+- Lead-only contract (replaces the shared team contract for this phase):
+  - The Claude lead is the sole agent for this run. No `Agent(...)` worker dispatch, no `TeamCreate`, no parallel sub-agents, no convergence loop.
+  - The lead drafts the commit message and PR body **inline** by reading the run brief, the cited final-verification report, and `git diff <base>..HEAD --stat`. No drafter worker is dispatched.
+  - The lead authors the final-report file directly (no `Report writer worker` dispatch). The report still conforms to the standard `okstra-final-report.template.md` structure, including the `## 4.6 Release Handoff Deliverables` section.
+  - The shared anti-escalation rule from the common contract still applies: do not start any other lifecycle phase from inside this run.
+  - The shared "authority & permissions assumption" rule from the common contract still applies: assume the user holds every permission needed; do not block on hypothetical approvals.
+  - The shared "MCP read-only" rule still applies if the brief lists MCP servers, though most release-handoff runs do not use MCP.
 - Pre-handoff entry gate (mandatory — refuse to start if any item fails):
   - the task brief MUST cite the originating `final-verification` final-report path under `## Source Verification Report`. The lead opens that file and confirms section `## 2. Final Verdict` contains exactly the token `accepted`.
   - if the verdict is `conditional-accept`, `blocked`, or any other token (including ambiguous phrasing like "looks good"), the run MUST end immediately with status `blocked` and a routing recommendation back to `error-analysis` or `implementation-planning`. Do NOT prompt the user; do NOT run any git command.
@@ -28,18 +29,17 @@
      - `dev`
      - `직접 입력` (free-form branch name; lead validates the name exists on origin via `git ls-remote --heads origin <name>` and re-asks on failure)
      The chosen base MUST NOT equal the feature branch. If it does, re-ask.
-  3. **Commit message + PR body confirmation** — show the `Claude worker` drafter's output verbatim and capture one of:
-     - `use as-is` — proceed with the drafter's text.
+  3. **Commit message + PR body confirmation** — show the lead's inline draft verbatim and capture one of:
+     - `use as-is` — proceed with the drafted text.
      - `edit then proceed` — accept inline edits from the user, then proceed with the edited text.
      - `cancel` — end the run without executing any git command; record the cancellation in the final report.
-- Drafter worker contract (`Claude worker`):
-  - reads the run brief, the cited final-verification report, and `git diff <base>..HEAD --stat` to ground its output in actual changes.
-  - produces **two artifacts** in its worker result:
-    1. **Commit message candidate** — a single message in Conventional Commits style (`<type>(<scope>): <subject>` + optional body + optional footer). When `commit + PR` will be opened against a `release-please`-managed repo, the type MUST match a configured changelog section (`feat` / `fix` / `perf` / `revert` / `deps` / `docs` / `refactor` / `build` / `ci` / `chore` / `test`).
-    2. **PR body candidate** — markdown with sections `## Summary`, `## Changes`, `## Test plan`, `## Linked issues` (omit a section only if it is genuinely empty).
-  - is strictly **read-only**: MUST NOT run any git mutating command, MUST NOT call `gh pr create`, MUST NOT call `git push`.
-  - if the drafter cannot produce output (no diff exists, repo is bare, etc.), it returns terminal status `not-run` with a reason; the lead falls back to a manually-authored message captured directly from the user.
-- Allowed actions during the run (Claude lead only — workers stay read-only):
+- Inline drafting rules (Claude lead):
+  - read the run brief, the cited final-verification report, and `git diff <base>..HEAD --stat` to ground the drafted text in actual changes.
+  - produce **two artifacts** before showing them to the user:
+    1. **Commit message** — a single message in Conventional Commits style (`<type>(<scope>): <subject>` + optional body + optional footer). When `commit + PR` will be opened against a `release-please`-managed repo, the type MUST match a configured changelog section (`feat` / `fix` / `perf` / `revert` / `deps` / `docs` / `refactor` / `build` / `ci` / `chore` / `test`).
+    2. **PR body** — markdown with sections `## Summary`, `## Changes`, `## Test plan`, `## Linked issues` (omit a section only if it is genuinely empty).
+  - if the diff is empty or no commit can be produced (working tree already matches the base), record "no staged changes; commit skipped" in the final report and skip `git commit` while still proceeding to the PR step if requested.
+- Allowed actions during the run (Claude lead only):
   - read-only inspection: `git status`, `git status --short`, `git diff`, `git log`, `git rev-parse`, `git ls-remote --heads origin <name>`, `gh pr list --head <branch>`, `gh pr view <url>`.
   - local commit: `git add -- <path>...` (prefer explicit file paths over `git add -A` / `git add .`), `git commit -m "<message>"`. Re-use the user-confirmed message exactly.
   - feature-branch push (only when the user picked `commit + PR`): `git push -u origin <current-branch>`. The pushed ref MUST be the feature branch — never the chosen base branch.
@@ -59,7 +59,7 @@
   - source-code edits, refactors, or any modification to files outside the run's own artifact directories (`reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/`). The diff being shipped MUST be exactly what the prior `implementation` run produced; release-handoff packages it, it does not re-author it.
   - executing any mutating command the user did NOT select. Examples: opening a PR when the user picked `commit only`; running `git commit` when the user picked `skip`; switching the PR base branch silently after the user already chose one.
   - retrying a failed git / gh command with weaker safety flags. If `git push` fails with non-fast-forward, the lead MUST stop, explain the failure to the user, and ask for instructions — it MUST NOT add `--force`.
-  - dispatching parallel sub-agents beyond the required worker roster.
+  - `TeamCreate`, `Agent(...)` dispatch of any kind, or any other parallel sub-agent fan-out. This phase runs entirely under the Claude lead.
   - silently treating an unrecognised user reply as one of the menu options. If the user's answer does not match a presented choice, re-ask the question verbatim.
 - Required deliverable shape (final report, in addition to the standard sections):
   - **Source Verification Report**: relative path of the originating `final-verification` final-report file plus the literal quoted `## 2. Final Verdict` line that read `accepted`.
@@ -67,7 +67,7 @@
   - **User Selections**: a block recording each prompt and the user's verbatim answer.
     - Q1 action: `commit only` | `commit + PR` | `skip`.
     - Q2 PR base (if applicable): the chosen branch and how it was selected (menu pick vs free-form input).
-    - Q3 message/body: `use as-is` | `edit then proceed` (with a diff between the drafter's text and the final text) | `cancel`.
+    - Q3 message/body: `use as-is` | `edit then proceed` (with a diff between the lead's draft and the final text) | `cancel`.
   - **Executed Commands**: every git / gh command the lead actually ran, with its exit code and a one-line stdout/stderr summary. Read-only inspection commands MAY be summarised; mutating commands MUST be listed verbatim.
   - **Commit List**: each commit SHA (short and full), its subject line, and the files it touched. If no commit was produced (idempotent no-op), state `- No commit was produced (working tree had no staged changes).`
   - **Pull Request Outcome**: one of
@@ -76,7 +76,7 @@
     - `- PR reused: <url>` when an existing PR was found via `gh pr list`
     - `- PR creation skipped: <reason>` for any user-driven cancellation
   - **Routing recommendation**: explicit `done` token, since release-handoff is the terminal lifecycle phase. If the run ended in `skip` or `cancel`, the recommendation MUST also state whether re-entry into release-handoff is appropriate.
-- Self-review pass before finalising the report (`Claude lead` runs this; do not delegate to a generic subagent):
+- Self-review pass before finalising the report (`Claude lead` runs this):
   1. **Entry-gate audit** — section 2 cites the originating final-verification report path and the literal `accepted` verdict line. If either is missing, the run is invalid and MUST be re-routed to `final-verification`.
   2. **User-selection traceability** — every executed mutating command maps to a user selection captured in the report. Any mutating command without a corresponding user answer is a contract violation.
   3. **Forbidden-action audit** — scan the run's session transcripts (`git`, `gh` invocations) for every entry in the Forbidden actions list above. Any occurrence means the run has crossed into unsafe territory and MUST be flagged as `contract-violated`.
@@ -86,4 +86,4 @@
   - re-litigating the final-verification verdict — release-handoff trusts the cited `accepted` verdict and does not reopen acceptance checks.
   - opening additional PRs, releases, or deployments beyond the single PR the user chose to create.
   - merging the PR. Merging is a separate, manual step performed by the user (or by repo automation) after release-handoff ends; the lead MUST NOT call `gh pr merge`.
-  - escalating beyond the menu choices on user phrasing — every mutating action requires an explicit menu selection (the shared anti-escalation rule applies, with this phase-specific tightening).
+  - escalating beyond the menu choices on user phrasing — every mutating action requires an explicit menu selection.

package/runtime/python/okstra_ctl/render.py

@@ -986,7 +986,55 @@ def render_template_file(template_path: str, output_path: str, ctx: dict) -> Non
         else "- `Gemini worker` is not selected for this run, so no Gemini attempt is required."
     )
 
+    # Team creation gate block: phase-conditional.
+    # - release-handoff (and any other phase that renders with no workers
+    #   selected) is single-lead and MUST NOT call `TeamCreate`. Emit a
+    #   short notice instead of the BLOCKING gate.
+    # - All other phases keep the full team-creation contract.
+    task_type = ctx.get("ANALYSIS_TYPE", "")
+    if task_type == "release-handoff" or not selected:
+        team_creation_gate_block = (
+            "## Single-Lead Phase (no team creation)\n"
+            "\n"
+            "This run is single-lead. There is no worker roster, no\n"
+            "`TeamCreate` call, no `Agent(...)` worker dispatch, and no\n"
+            "convergence loop. The Claude lead performs every step inline\n"
+            "(reading inputs, drafting commit / PR text when applicable,\n"
+            "asking the user, running git / gh, and writing the final\n"
+            "report). Do NOT call `TeamCreate` or dispatch any sub-agent\n"
+            "from this run — that would be a contract violation."
+        )
+    else:
+        team_creation_gate_block = (
+            "## Team Creation Gate (BLOCKING)\n"
+            "\n"
+            "Before any `Agent` dispatch for workers, you MUST perform Phase 3 of the\n"
+            "`okstra` skill (`agents/SKILL.md` → \"Phase 3 — Team creation\"). Skipping\n"
+            "this gate silently degrades the run to in-process background dispatch and\n"
+            "loses the Teams split-pane observability surface, even though worker\n"
+            "outputs may still appear correct on disk.\n"
+            "\n"
+            "Required actions, in order, regardless of how many workers are selected\n"
+            "for this run (roster comes from `resultContract.requiredWorkerRoles` in\n"
+            "`task-manifest.json` — it may be 1, 2, 3, or more workers):\n"
+            "\n"
+            "1. Invoke the `okstra-team-contract` skill and verify the selected worker\n"
+            "   roster against `task-manifest.json`'s `resultContract.requiredWorkerRoles`.\n"
+            f"2. Call `TeamCreate(team_name: \"okstra-{ctx.get('TASK_KEY', '')}\", description: ...)`.\n"
+            "3. Record the outcome in team-state under\n"
+            "   `teamCreate: { attempted: true, status: \"ok\" | \"error\", error?: <msg> }`\n"
+            "   BEFORE any `Agent(...)` worker dispatch.\n"
+            "4. Only after `teamCreate` is persisted may you dispatch workers — with\n"
+            "   `team_name` on success, or with `run_in_background: true` and no\n"
+            "   `team_name` ONLY when `teamCreate.status == \"error\"` was recorded.\n"
+            "\n"
+            "If the Agent tool rejects a dispatch with `\"team must be created first\"` /\n"
+            "`\"team을 먼저 생성하거나 team_name 없이 호출해야 합니다\"`, the correct\n"
+            "response is to go back to step 2 — NOT to strip `team_name` and retry."
+        )
+
     mapping = {
+        "{{TEAM_CREATION_GATE}}": team_creation_gate_block,
         "{{PROJECT_ID}}": ctx.get("PROJECT_ID", ""),
         "{{TASK_GROUP}}": ctx.get("TASK_GROUP", ""),
         "{{TASK_ID}}": ctx.get("TASK_ID", ""),

package/runtime/python/okstra_ctl/run.py

@@ -58,7 +58,7 @@ from .session import (
 )
 from .workers import normalize_workers, resolve_profile_workers
 from .workflow import compute_workflow_state
-from .worktree import provision_implementation_worktree
+from .worktree import provision_task_worktree
 
 APPROVED_PLAN_PATTERN = re.compile(
     r"^[ \t]*(?:[-*+][ \t]+)?(APPROVED([ \t]|:|$)|\[x\][ \t]*Approved|"
@@ -457,10 +457,17 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         raise PrepareError(f"project.json upsert failed for {project_root}: {exc}") from exc
 
     # ---- workers resolution ----
-    profile_workers_csv = ",".join(resolve_profile_workers(profile_file))
-    workers = normalize_workers(inp.workers_override or profile_workers_csv)
-    if not workers:
-        raise PrepareError(f"no workers resolved for profile: {inp.task_type}")
+    # release-handoff is intentionally single-lead (no worker dispatch, no
+    # TeamCreate, no convergence). The profile has no `- Required workers:`
+    # block; force an empty roster regardless of any user override so the
+    # rendered task bundle stays consistent with the profile contract.
+    if inp.task_type == "release-handoff":
+        workers: list[str] = []
+    else:
+        profile_workers_csv = ",".join(resolve_profile_workers(profile_file))
+        workers = normalize_workers(inp.workers_override or profile_workers_csv)
+        if not workers:
+            raise PrepareError(f"no workers resolved for profile: {inp.task_type}")
     selected_reviewers = ",".join(workers)
 
     # ---- model assignments ----
@@ -517,21 +524,22 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         task_type=inp.task_type, run_seq_override=run_seq_override,
     )
 
-    # ---- executor worktree provisioning (implementation phase only) ----
-    # The reports-seq is reused as the worktree-seq so the on-disk worktree
-    # path is colocated with the artefacts produced by this run.
+    # ---- task worktree provisioning (every phase, every task-type) ----
+    # One worktree per task-key: requirements-discovery, error-analysis,
+    # implementation-planning and implementation phases of the same task
+    # all share this directory and branch. The global registry handles
+    # reservation across concurrent runs.
     try:
-        worktree = provision_implementation_worktree(
+        worktree = provision_task_worktree(
             task_type=inp.task_type,
             project_root=project_root,
             project_id=inp.project_id,
             task_group_segment=ctx["TASK_GROUP_SEGMENT"],
             task_id_segment=ctx["TASK_ID_SEGMENT"],
-            run_seq=int(ctx["RUN_REPORTS_SEQ"]),
             work_category=inp.work_category,
         )
     except RuntimeError as exc:
-        raise PrepareError(f"executor worktree provisioning failed: {exc}") from exc
+        raise PrepareError(f"task worktree provisioning failed: {exc}") from exc
 
     ctx.update({
         "EXECUTOR_WORKTREE_PATH": worktree.path,

package/runtime/python/okstra_ctl/workflow.py

@@ -127,11 +127,11 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - entering this phase only when the cited final-verification report's verdict is exactly `accepted`\n"
             "  - asking the user (via `AskUserQuestion` / interactive prompt) which delivery action to take: `commit only`, `commit + PR`, or `skip` (end the run)\n"
             "  - asking the user to pick a PR base branch from `staging` | `preprod` | `prod` | `main` | `dev` | a user-supplied branch name\n"
-            "  - dispatching the `Claude worker` (drafter) to produce candidate commit message(s) and PR body in markdown; the lead reviews and offers them to the user before any git command runs\n"
+            "  - drafting commit message(s) and PR body **inline as the Claude lead** (no drafter worker, no `Agent` dispatch); the lead reviews its own draft with the user before any git command runs\n"
             "  - local git operations: `git status`, `git diff`, `git log`, `git add`, `git commit -m`\n"
             "  - pushing the current feature branch to its origin remote via `git push -u origin <current-branch>` (the feature branch only — NEVER the base branch)\n"
             "  - creating a pull request via `gh pr create --base <chosen-base> --head <current-branch>`; if a PR with the same head already exists, surface its URL and skip creation\n"
-            "  - recording the executed actions, commit SHAs, PR URL, and user selections in the final report"
+            "  - the lead writes the final report directly (no `Report writer worker` dispatch); the report still conforms to the standard final-report template"
         ),
         "forbidden": (
             "  - entering this phase when the cited final-verification verdict is `conditional-accept` or `blocked`, or when no final-verification report is cited\n"
@@ -141,7 +141,7 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - bypassing git hooks (`--no-verify`, `-n`), bypassing GPG signing, or otherwise disabling repo-configured safeguards\n"
             "  - release-publishing commands: `gh release`, `npm publish`, `cargo publish`, `pip publish`, `docker push`, `terraform apply`, `kubectl apply` against non-local clusters\n"
             "  - executing any command the user did NOT select (e.g. if the user picked `commit only`, opening a PR is forbidden; if the user picked `skip`, the run ends without git commands)\n"
-            "  - dispatching parallel sub-agents beyond the required worker roster (`Claude worker` drafter + `Report writer worker`)\n"
+            "  - `TeamCreate`, `Agent(...)` worker dispatch, parallel sub-agent fan-out, or any team-mode orchestration — this phase runs single-lead\n"
             "  - silently retrying a failed git/gh command with weaker flags (e.g. retrying `git push` with `--force` after a non-fast-forward rejection)"
         ),
     },

package/runtime/python/okstra_ctl/worktree.py

@@ -1,19 +1,34 @@
-"""Implementation-phase git worktree provisioning.
+"""Per-task git worktree provisioning.
 
-Implementation runs operate on an isolated git worktree rooted under
-`~/.okstra/worktrees/<project_id>/<task_group_segment>/<task_id_segment>-<run_seq>`.
-The executor mutates files there; verifiers read from the same path.
-The worktree is always kept after the run for inspection, manual PR
-authoring, and rollback verification.
+Every okstra task — regardless of task-type/phase — runs inside an
+isolated git worktree rooted at
+`~/.okstra/worktrees/<project_id>/<task_group>/<task_id>/`. The same
+worktree is reused across all phases of one task-key (requirements-
+discovery → error-analysis → implementation-planning → implementation),
+so phase N picks up exactly the working-tree state phase N-1 left
+behind.
 
-Pre-conditions handled here:
-  - Skip non-`implementation` task-types entirely.
-  - Skip when `project_root` itself already sits inside a non-main git
-    worktree (the run reuses the caller's working tree).
-  - Refuse to clobber an existing path or branch — raise PrepareError.
+A global registry (`worktree_registry.py`) maps task-keys to the
+on-disk path + branch and serialises reservations, so two concurrent
+okstra runs cannot collide on the same path or branch name.
 
-Side effects: `git worktree add -b <branch> <path> <base_ref>` is invoked
-in `project_root`. The function does NOT chdir.
+Pre-conditions handled here:
+  - Skip when `project_root` is not a git repo (degrade gracefully).
+  - Skip when `project_root` itself is already a non-main worktree
+    (caller's tree is already an isolated workspace; reuse it).
+  - Re-entry of the same task-key returns the existing worktree.
+  - Branch / path collisions across task-keys raise PrepareError-like
+    RuntimeError.
+
+Side effects:
+  - `git worktree add -b <branch> <path> <base_ref>` invoked in the
+    main worktree of `project_root` (NOT `project_root` itself when it
+    is also a worktree — base must be the main checkout).
+  - Per-task sync dirs (.project-docs, .scratch, graphify-out by
+    default) symlinked from the **main worktree** into the new
+    worktree so every task sees the same shared state, irrespective of
+    which worktree the caller invoked okstra from.
+  - The function does NOT chdir.
 """
 from __future__ import annotations
 
@@ -23,17 +38,20 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Optional
 
+from .ids import _safe_fs_segment
+from . import worktree_registry
+
 
 OKSTRA_WORKTREES_RELATIVE = Path(".okstra/worktrees")
 
 
 # Project-root directories that hold okstra task state, ignored by git, or
 # otherwise required for the executor to operate but NOT carried across by
-# `git worktree add`. Each is symlinked from project_root into the new
-# worktree at provision time. Symlinks (not copies) so the executor sees
-# the live state and disk/CPU cost stays near zero; the trade-off is that
-# any write through the link reaches the original project_root, which is
-# acceptable because the executor only writes inside its own task-scoped
+# `git worktree add`. Each is symlinked from the MAIN worktree into the new
+# worktree at provision time. Symlinks (not copies) so every task sees the
+# live shared state and disk/CPU cost stays near zero; the trade-off is
+# that any write through the link reaches the main worktree, which is
+# acceptable because okstra only writes inside its own task-scoped
 # subdirectory (e.g. `.project-docs/okstra/tasks/<task-id>/runs/...`).
 #
 # Override via the `OKSTRA_WORKTREE_SYNC_DIRS` env var: a colon-separated
@@ -62,32 +80,45 @@ _WORK_CATEGORY_PREFIX = {
 
 @dataclass
 class WorktreeProvision:
-    """Result of `provision_implementation_worktree`.
+    """Result of `provision_task_worktree`.
 
     status:
       - "created": fresh worktree at `path` on `branch`
-      - "skipped-non-implementation": task-type was not `implementation`
-      - "skipped-in-worktree": project_root is already inside a non-main
+      - "reused": registry already had this task-key; same path/branch
+        returned and no new `git worktree add` was executed
+      - "skipped-in-worktree": project_root is itself a non-main
         worktree; the run reuses `project_root` and no new worktree is
-        materialised
+        materialised (registry NOT updated — that caller is already
+        isolated by virtue of its own worktree)
       - "skipped-not-git": project_root has no `.git` (worktree path
         cannot be provisioned; degrade gracefully)
     """
     status: str
-    path: str = ""          # absolute path of the executor worktree (or project_root when reused)
+    path: str = ""          # absolute path of the task worktree (or project_root when reused)
     branch: str = ""        # branch checked out in the worktree (empty when reused / not-git)
     base_ref: str = ""      # commit SHA the worktree was branched from (empty when not created)
     note: str = ""          # human-readable explanation, surfaced in team-state / manifests
 
 
+def _safe_segment(value: str) -> str:
+    """Sanitise a single path/branch segment.
+
+    Forbidden chars (`/`, `:`, spaces, anything outside `[a-z0-9-]`)
+    are collapsed to `-`. Empty result becomes `_` so we never create
+    an empty path component. Delegates to the canonical slugifier in
+    `ids.py` to stay in lock-step with run-id / manifest segmentation.
+    """
+    return _safe_fs_segment(value)
+
+
 def _work_category_prefix(work_category: str) -> str:
     key = (work_category or "").strip().lower()
     return _WORK_CATEGORY_PREFIX.get(key, "task")
 
 
-def _git(project_root: Path, *args: str) -> subprocess.CompletedProcess:
+def _git(cwd: Path, *args: str) -> subprocess.CompletedProcess:
     return subprocess.run(
-        ["git", "-C", str(project_root), *args],
+        ["git", "-C", str(cwd), *args],
         capture_output=True, text=True, check=False,
     )
 
@@ -101,7 +132,6 @@ def _is_inside_non_main_worktree(project_root: Path) -> bool:
     per_tree = _git(project_root, "rev-parse", "--git-dir")
     if common.returncode != 0 or per_tree.returncode != 0:
         return False
-    # Both paths can be relative to project_root; resolve before compare.
     common_abs = (project_root / common.stdout.strip()).resolve()
     per_tree_abs = (project_root / per_tree.stdout.strip()).resolve()
     return common_abs != per_tree_abs
@@ -117,13 +147,31 @@ def _branch_exists(project_root: Path, branch: str) -> bool:
     return res.returncode == 0
 
 
-def _head_sha(project_root: Path) -> str:
-    res = _git(project_root, "rev-parse", "HEAD")
+def _head_sha(cwd: Path) -> str:
+    res = _git(cwd, "rev-parse", "HEAD")
     if res.returncode != 0:
         return ""
     return res.stdout.strip()
 
 
+def _main_worktree_path(project_root: Path) -> Path:
+    """Locate the repository's MAIN worktree (the original checkout).
+
+    `git worktree list --porcelain` lists worktrees in a stable order
+    where the first `worktree <path>` block is the main checkout.
+    Falls back to `project_root` if parsing fails — caller still gets
+    a working path, sync-dir links just point at the caller's tree
+    (the prior behaviour).
+    """
+    res = _git(project_root, "worktree", "list", "--porcelain")
+    if res.returncode != 0:
+        return project_root
+    for line in res.stdout.splitlines():
+        if line.startswith("worktree "):
+            return Path(line[len("worktree "):].strip())
+    return project_root
+
+
 def _resolve_sync_dirs() -> tuple[str, ...]:
     """Return the list of project-root-relative dirs to symlink into the
     new worktree. Reads `OKSTRA_WORKTREE_SYNC_DIRS` if set (colon-separated,
@@ -138,11 +186,12 @@ def _resolve_sync_dirs() -> tuple[str, ...]:
     return tuple(part for part in (p.strip() for p in raw.split(":")) if part)
 
 
-def _link_sync_dirs(project_root: Path, worktree_path: Path) -> list[str]:
-    """Symlink each configured project-root dir into the new worktree.
+def _link_sync_dirs(source_root: Path, worktree_path: Path) -> list[str]:
+    """Symlink each configured dir from `source_root` (the MAIN
+    worktree) into the new worktree.
 
     Skip rules:
-      - Source missing in project_root → silently skipped.
+      - Source missing in `source_root` → silently skipped.
       - Target path already exists in worktree (e.g. tracked content
         checked out by `git worktree add`) → skipped to avoid clobbering
         version-controlled files.
@@ -153,7 +202,7 @@ def _link_sync_dirs(project_root: Path, worktree_path: Path) -> list[str]:
     """
     notes: list[str] = []
     for rel in _resolve_sync_dirs():
-        src = (project_root / rel).resolve()
+        src = (source_root / rel).resolve()
         if not src.exists():
             continue
         dst = worktree_path / rel
@@ -170,17 +219,20 @@ def compute_worktree_path(
     project_id: str,
     task_group_segment: str,
     task_id_segment: str,
-    run_seq: int,
 ) -> Path:
-    """Pure path computation. Mirrors `okstra_root` location convention.
+    """Pure path computation. One worktree dir per task-key.
 
-    Uses `OKSTRA_HOME` when set (test hook), else `~/.okstra`.
+    Uses `OKSTRA_HOME` when set (test hook), else `~/.okstra`. Note
+    there is NO run-seq segment — every phase of the same task-key
+    shares this dir.
     """
     okstra_home = os.environ.get("OKSTRA_HOME", "").strip()
     base = Path(okstra_home) if okstra_home else (Path.home() / ".okstra")
     return (
-        base / "worktrees" / project_id
-        / task_group_segment / f"{task_id_segment}-{int(run_seq):03d}"
+        base / "worktrees"
+        / _safe_segment(project_id)
+        / _safe_segment(task_group_segment)
+        / _safe_segment(task_id_segment)
     )
 
 
@@ -188,46 +240,40 @@ def compute_branch_name(
     *,
     work_category: str,
     task_id_segment: str,
-    run_seq: int,
 ) -> str:
-    return f"{_work_category_prefix(work_category)}-{task_id_segment}-{int(run_seq):03d}"
+    """One branch per task-key. No run-seq — phases share the branch."""
+    return f"{_work_category_prefix(work_category)}-{_safe_segment(task_id_segment)}"
 
 
-def provision_implementation_worktree(
+def provision_task_worktree(
     *,
     task_type: str,
     project_root: Path,
     project_id: str,
     task_group_segment: str,
     task_id_segment: str,
-    run_seq: int,
     work_category: str,
 ) -> WorktreeProvision:
-    """Materialise (or skip) the executor worktree for this run.
+    """Materialise (or reuse) the task worktree for this run.
 
-    The caller passes the same `run_seq` used by the reports/manifests
-    artefacts so the worktree directory is colocated by sequence number.
+    First phase of a task-key creates the worktree on a new branch.
+    Subsequent phases of the same task-key look up the registry and
+    return the existing path + branch unchanged.
 
     Raises:
-        PrepareError-like RuntimeError when worktree creation fails
-        (path clash, branch clash, `git worktree add` non-zero). The
-        caller (`run.py`) catches and re-raises as PrepareError to keep
-        a single error surface.
+        RuntimeError when worktree creation fails (path clash on disk
+        that the registry does not know about, branch clash with a
+        different task-key, `git worktree add` non-zero). The caller
+        (`run.py`) catches and re-raises as PrepareError to keep a
+        single error surface.
     """
-    if task_type != "implementation":
-        return WorktreeProvision(
-            status="skipped-non-implementation",
-            path=str(project_root),
-            note="worktree provisioning skipped: task-type is not 'implementation'",
-        )
-
     if not _is_git_repo(project_root):
         return WorktreeProvision(
             status="skipped-not-git",
             path=str(project_root),
             note=(
                 "worktree provisioning skipped: project_root is not inside a git "
-                "repository; executor will operate directly on project_root"
+                "repository; task will operate directly on project_root"
             ),
         )
 
@@ -237,44 +283,62 @@ def provision_implementation_worktree(
             path=str(project_root),
             note=(
                 "worktree provisioning skipped: project_root is already inside a "
-                "non-main git worktree; executor reuses the caller's worktree"
+                "non-main git worktree; task reuses the caller's worktree"
+            ),
+        )
+
+    safe_project = _safe_segment(project_id)
+    safe_group = _safe_segment(task_group_segment)
+    safe_task = _safe_segment(task_id_segment)
+
+    # Registry lookup first — same task-key across phases must reuse.
+    existing = worktree_registry.lookup(safe_project, safe_group, safe_task)
+    if existing is not None and existing.status == "active":
+        worktree_registry.touch_phase(safe_project, safe_group, safe_task, task_type)
+        return WorktreeProvision(
+            status="reused",
+            path=existing.worktree_path,
+            branch=existing.branch,
+            base_ref=existing.base_ref,
+            note=(
+                f"task worktree reused at {existing.worktree_path} on branch "
+                f"{existing.branch} (base {existing.base_ref[:12]}); phase {task_type}"
             ),
         )
 
     worktree_path = compute_worktree_path(
-        project_id=project_id,
-        task_group_segment=task_group_segment,
-        task_id_segment=task_id_segment,
-        run_seq=run_seq,
+        project_id=safe_project,
+        task_group_segment=safe_group,
+        task_id_segment=safe_task,
     )
     branch = compute_branch_name(
         work_category=work_category,
-        task_id_segment=task_id_segment,
-        run_seq=run_seq,
+        task_id_segment=safe_task,
     )
 
     if worktree_path.exists():
         raise RuntimeError(
-            f"executor worktree path already exists: {worktree_path}. "
-            "Remove it with `git worktree remove <path>` (or `rm -rf` if it is "
-            "not a registered worktree) before retrying this implementation run."
+            f"task worktree path already exists but is not in the registry: "
+            f"{worktree_path}. Remove it with `git worktree remove <path>` "
+            "(or `rm -rf` if it is not a registered worktree) before retrying."
         )
     if _branch_exists(project_root, branch):
         raise RuntimeError(
-            f"executor worktree branch already exists: {branch}. "
-            "Delete it (`git branch -D <branch>`) or bump OKSTRA_RUN_SEQ_OVERRIDE "
-            "before retrying."
+            f"task worktree branch already exists: {branch}. "
+            "Delete it (`git branch -D <branch>`) or choose a different "
+            "work-category before retrying."
         )
 
-    base_ref = _head_sha(project_root)
+    main_root = _main_worktree_path(project_root)
+    base_ref = _head_sha(main_root)
     if not base_ref:
         raise RuntimeError(
-            "could not resolve HEAD sha in project_root; cannot create worktree"
+            "could not resolve HEAD sha in main worktree; cannot create task worktree"
         )
 
     worktree_path.parent.mkdir(parents=True, exist_ok=True)
     res = _git(
-        project_root,
+        main_root,
         "worktree", "add", "-b", branch, str(worktree_path), base_ref,
     )
     if res.returncode != 0:
@@ -283,16 +347,35 @@ def provision_implementation_worktree(
             f"{(res.stderr or res.stdout).strip()}"
         )
 
-    linked = _link_sync_dirs(project_root, worktree_path)
+    # Sync dirs sourced from the MAIN worktree so every task sees the
+    # same shared state regardless of which checkout invoked okstra.
+    linked = _link_sync_dirs(main_root, worktree_path)
     linked_suffix = f"; linked {', '.join(linked)}" if linked else ""
 
+    try:
+        worktree_registry.reserve(
+            project_id=safe_project,
+            task_group=safe_group,
+            task_id=safe_task,
+            worktree_path=str(worktree_path),
+            branch=branch,
+            base_ref=base_ref,
+            phase=task_type,
+        )
+    except RuntimeError:
+        # Roll back the on-disk worktree so the next attempt is not
+        # blocked by the lingering directory / branch.
+        _git(main_root, "worktree", "remove", "--force", str(worktree_path))
+        _git(main_root, "branch", "-D", branch)
+        raise
+
     return WorktreeProvision(
         status="created",
         path=str(worktree_path),
         branch=branch,
         base_ref=base_ref,
         note=(
-            f"executor worktree created at {worktree_path} on branch {branch} "
-            f"(base {base_ref[:12]}){linked_suffix}"
+            f"task worktree created at {worktree_path} on branch {branch} "
+            f"(base {base_ref[:12]}; phase {task_type}){linked_suffix}"
         ),
     )

package/runtime/python/okstra_ctl/worktree_registry.py

@@ -0,0 +1,211 @@
+"""Global task-worktree registry.
+
+Tracks which `(project_id, task_group, task_id)` task-key owns which
+on-disk worktree path and branch, across concurrent okstra runs on the
+same machine. The registry lives under `OKSTRA_HOME` (default
+`~/.okstra`) and is guarded by an `fcntl` exclusive lock so that two
+processes cannot race to reserve the same path or branch.
+
+Why a global registry:
+  - A single task-key spans multiple phases (requirements-discovery →
+    error-analysis → implementation-planning → implementation). All
+    phases must land in the **same** worktree on the **same** branch.
+    Re-entry from any phase must look up the existing entry instead of
+    creating a duplicate.
+  - Two different task-keys must never collide on the same branch name.
+    A global branch index makes that detectable cheaply.
+  - Cleanup of stale entries (worktree dir removed manually) needs a
+    single source of truth.
+
+The registry is intentionally JSON-on-disk (no SQLite): the data set is
+tiny (one row per active task on this machine) and the human-readable
+file is useful for debugging.
+"""
+from __future__ import annotations
+
+import contextlib
+import fcntl
+import json
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+REGISTRY_FILENAME = "registry.json"
+LOCK_FILENAME = "registry.lock"
+
+
+def _okstra_worktrees_dir() -> Path:
+    home_env = os.environ.get("OKSTRA_HOME", "").strip()
+    base = Path(home_env) if home_env else (Path.home() / ".okstra")
+    return base / "worktrees"
+
+
+def task_key(project_id: str, task_group: str, task_id: str) -> str:
+    """Canonical task-key string used as the registry primary key.
+
+    Segments are NOT re-slugified here — callers must pass already
+    sanitised segments (see `worktree._safe_segment`). The key form
+    `<project>/<group>/<task>` is the same shape used for filesystem
+    paths so a key can be visually correlated with the worktree dir.
+    """
+    return f"{project_id}/{task_group}/{task_id}"
+
+
+@dataclass
+class WorktreeEntry:
+    task_key: str
+    project_id: str
+    task_group: str
+    task_id: str
+    worktree_path: str
+    branch: str
+    base_ref: str
+    created_at: str
+    last_phase: str = ""
+    status: str = "active"  # "active" | "released"
+
+
+@contextlib.contextmanager
+def _registry_lock():
+    """Exclusive flock on `<worktrees>/registry.lock`. Mirrors the
+    `central_lock` pattern from `locks.py` but scoped to the registry
+    so we do not serialise unrelated central operations.
+    """
+    root = _okstra_worktrees_dir()
+    root.mkdir(parents=True, exist_ok=True)
+    lockfile = root / LOCK_FILENAME
+    if not lockfile.exists():
+        lockfile.touch()
+    f = lockfile.open("r+")
+    try:
+        fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+        yield
+    finally:
+        f.close()
+
+
+def _registry_path() -> Path:
+    return _okstra_worktrees_dir() / REGISTRY_FILENAME
+
+
+def _load() -> dict:
+    p = _registry_path()
+    if not p.exists():
+        return {"tasks": {}, "branches": {}}
+    try:
+        data = json.loads(p.read_text())
+    except (OSError, json.JSONDecodeError):
+        return {"tasks": {}, "branches": {}}
+    data.setdefault("tasks", {})
+    data.setdefault("branches", {})
+    return data
+
+
+def _save(data: dict) -> None:
+    p = _registry_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    tmp = p.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+    os.replace(tmp, p)
+
+
+def lookup(project_id: str, task_group: str, task_id: str) -> Optional[WorktreeEntry]:
+    """Return the registered entry for this task-key, or None.
+
+    Does not validate that `worktree_path` still exists on disk — that
+    is the caller's responsibility (so reclaim logic can decide policy).
+    """
+    key = task_key(project_id, task_group, task_id)
+    with _registry_lock():
+        data = _load()
+        row = data["tasks"].get(key)
+        if not row:
+            return None
+        return WorktreeEntry(task_key=key, **row)
+
+
+def reserve(
+    *,
+    project_id: str,
+    task_group: str,
+    task_id: str,
+    worktree_path: str,
+    branch: str,
+    base_ref: str,
+    phase: str = "",
+) -> WorktreeEntry:
+    """Atomically insert a new entry. Raises RuntimeError if the
+    task-key already exists or the branch is already owned by a
+    different task-key. Callers should `lookup()` first when re-entry
+    is expected.
+    """
+    key = task_key(project_id, task_group, task_id)
+    now = time.strftime("%Y-%m-%dT%H:%M:%S%z") or time.strftime("%Y-%m-%dT%H:%M:%S")
+    with _registry_lock():
+        data = _load()
+        if key in data["tasks"]:
+            existing = data["tasks"][key]
+            raise RuntimeError(
+                f"task-key already has a worktree registered: {key} → "
+                f"{existing['worktree_path']} (branch {existing['branch']}). "
+                "Use `lookup` to reuse it, or release it before reserving anew."
+            )
+        owner = data["branches"].get(branch)
+        if owner and owner != key:
+            raise RuntimeError(
+                f"branch {branch!r} is already registered to a different "
+                f"task-key: {owner}. Choose a different work-category or "
+                "release the conflicting task first."
+            )
+        row = {
+            "project_id": project_id,
+            "task_group": task_group,
+            "task_id": task_id,
+            "worktree_path": worktree_path,
+            "branch": branch,
+            "base_ref": base_ref,
+            "created_at": now,
+            "last_phase": phase,
+            "status": "active",
+        }
+        data["tasks"][key] = row
+        data["branches"][branch] = key
+        _save(data)
+        return WorktreeEntry(task_key=key, **row)
+
+
+def touch_phase(project_id: str, task_group: str, task_id: str, phase: str) -> None:
+    """Record the most recent phase observed on this worktree.
+    Best-effort: silently no-ops if the task-key is not registered.
+    """
+    key = task_key(project_id, task_group, task_id)
+    with _registry_lock():
+        data = _load()
+        row = data["tasks"].get(key)
+        if not row:
+            return
+        row["last_phase"] = phase
+        _save(data)
+
+
+def release(project_id: str, task_group: str, task_id: str) -> Optional[WorktreeEntry]:
+    """Mark the entry as `released` (worktree dir intact — preservation
+    is the project's policy). The branch index is freed so future
+    reservations of the same branch name are not blocked.
+    Returns the prior entry, or None when not found.
+    """
+    key = task_key(project_id, task_group, task_id)
+    with _registry_lock():
+        data = _load()
+        row = data["tasks"].get(key)
+        if not row:
+            return None
+        row["status"] = "released"
+        # Free the branch slot so reuse / new task can reclaim the name.
+        if data["branches"].get(row["branch"]) == key:
+            del data["branches"][row["branch"]]
+        _save(data)
+        return WorktreeEntry(task_key=key, **row)

package/runtime/skills/okstra-report-writer/SKILL.md

@@ -199,7 +199,9 @@ The final-report template `okstra-final-report.template.md` Section 4.5 already
 
 ### Release-handoff section contract (release-handoff runs only)
 
-When the run's `task-type` is `release-handoff`, the final report MUST include Section `## 4.6 Release Handoff Deliverables` with all seven sub-sections (`4.6.1` Source Verification Report, `4.6.2` Feature Branch & Working-Tree State, `4.6.3` User Selections, `4.6.4` Executed Commands, `4.6.5` Commit List, `4.6.6` Pull Request Outcome, `4.6.7` Routing Recommendation). The drafter does **not** invent values for these sub-sections — every entry is dictated by the lead's recorded git/gh command log and the user's verbatim answers to the H1/H2/H3 menu prompts. If the user picked `skip` (H1) or `cancel` (H3), keep 4.6.3 populated but leave 4.6.4–4.6.6 explicitly empty per the template's empty-state lines.
+When the run's `task-type` is `release-handoff`, the final report MUST include Section `## 4.6 Release Handoff Deliverables` with all seven sub-sections (`4.6.1` Source Verification Report, `4.6.2` Feature Branch & Working-Tree State, `4.6.3` User Selections, `4.6.4` Executed Commands, `4.6.5` Commit List, `4.6.6` Pull Request Outcome, `4.6.7` Routing Recommendation). Every entry is dictated by the lead's recorded git/gh command log and the user's verbatim answers to the H1/H2/H3 menu prompts. If the user picked `skip` (H1) or `cancel` (H3), keep 4.6.3 populated but leave 4.6.4–4.6.6 explicitly empty per the template's empty-state lines.
+
+**Single-lead authorship (release-handoff only):** release-handoff has no worker roster (no `Report writer worker`, no `Claude worker` drafter). The Claude lead authors the final-report file directly — there is no `Report writer worker` dispatch to perform in Phase 6, no resume-safe dispatch concern, and no mandatory worker-results file for a report-writer role. The rest of this skill's dispatch / resume / fallback machinery applies ONLY when `Report writer worker` is in the roster (i.e. every task-type other than `release-handoff`).
 
 The final-report template `okstra-final-report.template.md` Section 4.6 already encodes this contract — copy that block verbatim and fill in. For non-`release-handoff` runs, omit Section 4.6 entirely.