okstra 0.103.0 → 0.105.0

package/docs/contributor-change-matrix.md

@@ -5,6 +5,9 @@ Use this matrix before changing high-risk repo contracts. Update the source file
 | Change | Must update | Tests |
 |---|---|---|
 | Add CLI flag | `src/`, `scripts/okstra_ctl/run.py`, `docs/kr/cli.md`, `prompts/wizard/` | JS CLI tests and pytest CLI contracts |
+| Add Node subcommand | `src/cli-registry.mjs`, `src/commands/`, `docs/kr/cli.md`, `docs/project-structure-overview.md` | `tests-js/cli-registry.test.mjs` plus command-specific JS/Python tests |
+| Add public skill | `src/lib/skill-catalog.mjs`, `.claude-plugin/plugin.json`, `skills/<name>/SKILL.md`, `docs/for-ai/README.md`, `docs/project-structure-overview.md`, `README*` | `tests-js/skill-catalog.test.mjs`, `tests/contract/test_docs_runtime_contract.py` |
+| Change manager contract | `scripts/okstra_ctl/manager_*.py`, `src/commands/manager.mjs`, `skills/okstra-manager/SKILL.md`, `docs/for-ai/skills/okstra-manager.md`, `docs/kr/cli.md`, `docs/kr/architecture/storage-model.md` | `tests-js/manager.test.mjs`, `tests/test_okstra_manager_*.py` |
 | Add phase | `scripts/okstra_ctl/workflow.py`, `prompts/profiles/`, `validators/`, `tests/` | workflow and validation contract tests |
 | Change worker roster | `prompts/profiles/*.md`, `scripts/okstra_ctl/workers.py`, `tests/contract/test_repo_contracts.py` | worker roster contract tests |
 | Change report section | `schemas/final-report-v1.0.schema.json`, `templates/reports/final-report.template.md`, `scripts/okstra_ctl/render_final_report.py`, `validators/validate-run.py` | final-report schema, renderer, and validator tests |

package/docs/for-ai/README.md

@@ -19,6 +19,7 @@
 | 새 프로젝트나 새 머신에서 okstra 설치/초기화 | `okstra-setup` | [`skills/okstra-setup.md`](skills/okstra-setup.md) |
 | 요구사항, 티켓, 링크, 코드베이스 스캔, error-zip을 okstra 입력 brief로 변환 | `okstra-brief` | [`skills/okstra-brief.md`](skills/okstra-brief.md) |
 | 현재 Claude Code 세션에서 okstra run 시작 또는 다음 phase 실행 | `okstra-run` | [`skills/okstra-run.md`](skills/okstra-run.md) |
+| 여러 프로젝트에 걸친 okstra task 묶음, 할당, sync snapshot, child launch packet 관리 | `okstra-manager` | [`skills/okstra-manager.md`](skills/okstra-manager.md) |
 | 상태, history, report, time, logs, cost, errors, error-zip, recap 확인 | `okstra-inspect` | [`skills/okstra-inspect.md`](skills/okstra-inspect.md) |
 | task-group 전체의 클라이언트용 작업 일정 생성 | `okstra-schedule` | [`skills/okstra-schedule.md`](skills/okstra-schedule.md) |
 | 대화/결정/선호/요구사항을 전역 Memory Book에 저장 또는 검색 | `okstra-memory` | [`skills/okstra-memory.md`](skills/okstra-memory.md) |
@@ -43,11 +44,12 @@
 
 ## 공개 스킬 목록
 
-`src/lib/skill-catalog.mjs` 기준 공개 스킬은 다음 7개다.
+`src/lib/skill-catalog.mjs` 기준 공개 스킬은 다음 8개다.
 
 - `okstra-setup`
 - `okstra-brief`
 - `okstra-run`
+- `okstra-manager`
 - `okstra-memory`
 - `okstra-inspect`
 - `okstra-schedule`

package/docs/for-ai/skills/okstra-manager.md

@@ -0,0 +1,62 @@
+# okstra-manager
+
+여러 프로젝트에 걸친 okstra task 를 하나의 manager-owned context 로 묶을 때 사용한다. 원문 계약은 [`skills/okstra-manager/SKILL.md`](../../../skills/okstra-manager/SKILL.md), CLI 구현은 [`src/commands/manager.mjs`](../../../src/commands/manager.mjs) 와 [`scripts/okstra_ctl/manager_cli.py`](../../../scripts/okstra_ctl/manager_cli.py) 이다.
+
+## 언제 쓰나
+
+- 사용자가 "여러 프로젝트", "cross-project", "okstra manager", "프로젝트 묶어서" 같은 의도를 말한다.
+- manager 아래에 프로젝트를 등록하거나 후보 프로젝트를 찾는다.
+- 공통 task-group/task-id 아래 child project task 를 계획하고 역할/지시를 배정한다.
+- child project `.okstra` 상태를 manager snapshot 으로 동기화하거나 status 를 본다.
+- 특정 child task 실행을 위한 launch packet 과 manager child context 를 준비한다.
+
+## 실행 규칙
+
+1. 모든 명령은 literal `okstra` 로 시작한다. 셸 변수, `$(...)`, `&&`, `eval`, 선행 env assignment 로 감싸지 않는다.
+2. JSON stdout 이 source of truth 다. manager 상태나 child launch args 를 문서/메모리에서 재구성하지 않는다.
+3. `--workspace-root` 는 Node wrapper 가 소유한다. 사용자가 넘기면 CLI 가 거부한다.
+4. `new project` 의 `--project-root` 는 이미 존재하는 디렉터리여야 한다. 그 안의 `.okstra/project.json` 이 없을 때만 setup-equivalent registration 을 수행한다.
+5. public child task identity 는 `project-id:task-group:task-id` 이다. `new task --task` 예시는 full key form 을 우선 보여준다.
+6. 같은 manager task id 아래 실제 child task id 가 다르면 `task assign` 과 `task run` 에 `--child-task-id <id>` 를 같이 넘긴다.
+
+## 명령 표면
+
+```bash
+okstra manager init --manager-id <manager-id> --json
+okstra manager discover-projects --json
+okstra manager new project --manager-id <manager-id> --project-id <project-id> --project-root <abs-path> [--role <role>] [--tag <tag>] --json
+okstra manager new task-group --manager-id <manager-id> --task-group <task-group> --json
+okstra manager new task --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --task <project-id:task-group:task-id> --json
+okstra manager task assign --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --project-id <project-id> [--child-task-id <child-task-id>] [--role <role>] [--tag <tag>] [--assignment <text>] --json
+okstra manager task note --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --scope <shared|project> [--project-id <project-id>] --body <text> --json
+okstra manager task sync --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --json
+okstra manager task status --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --json
+okstra manager task run --manager-id <manager-id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--child-task-id <child-task-id>] --json
+```
+
+## 저장 모델
+
+Manager state 는 `~/.okstra/managers/<manager-id>/` 아래에 저장된다.
+
+- `manager.json`: manager id / schema / createdAt
+- `projects.json`: 등록된 projectId, projectRoot, role, tags
+- `task-groups/<safe-group>/<safe-task>/manifest.json`: manager task objective, common brief, progress mode
+- `children.json`: child task plan, assignment, launch metadata
+- `directives.jsonl`: shared/project directive rows
+- `snapshots.json`: `task sync` 가 project-local `.okstra` 에서 읽어온 read-side snapshot
+- `events.jsonl`: `task-created`, `child-launch-prepared` 같은 manager event
+- `child-context/<safe-project>-<safe-task>.md`: `task run` 이 만든 child lead context
+
+비 ASCII task-group/task-id 처럼 slug 가 비는 segment 는 `u-<sha1-prefix>` path segment 를 사용하지만, manifest 와 child `taskKey` 는 원래 입력값을 보존한다.
+
+## Child launch
+
+`task run` 은 child 작업을 직접 실행하지 않고 launch packet 을 준비한다. 반환 packet 의 핵심 필드는:
+
+- `backend`: `$TMUX` 가 있으면 `tmux-child-lead`, 없으면 `subagent-child-lead`
+- `workerDispatchBackend`: v1 에서는 항상 `subagent`
+- `projectRoot`: child project root
+- `contextPath`: manager child context markdown
+- `runArgs`: host launcher 가 사용할 `okstra run ... --directive "Read manager child context: ..."` 인자
+
+packet 생성이 성공하면 `children.json` 의 해당 child launch 상태가 `prepared` 로 갱신되고, `events.jsonl` 에 `child-launch-prepared` 가 append 된다. 실패해도 project-local task state 는 수정하지 않는다.

package/docs/kr/architecture/storage-model.md

@@ -93,20 +93,13 @@ worker prompt history는 `/tmp`가 아니라 항상 현재 run의 `prompts/` 아
 같은 task-type으로 다시 실행하면 동일한 `runs/<task-type>/` 폴더를 재사용하지만, 유형별 하위 폴더 아래에서 run-level 파일명이 `-<task-type>-<seq>` suffix로 분리되므로 기존 산출물을 덮어쓰지 않습니다. `<seq>`는 카테고리 디렉토리(`manifests/`, `prompts/`, `reports/`, `status/`, `state/`, `sessions/`, `worker-results/`)별로 독립 스캔되므로 같은 run에서도 카테고리별 값이 다를 수 있습니다.
 이전 flat legacy artifact가 task-type run 폴더 최상위에 남아 있으면 다음 실행 시 해당 유형별 하위 폴더로 자동 정리합니다.
 
-### 3. Project-level discovery and skill documents
+### 3. Project-level discovery and installed skill assets
 프로젝트 공용 discovery pointer는 아래 경로에 생성합니다.
 
 ```text
 <target-project>/.okstra/discovery/latest-task.json
 <target-project>/.okstra/discovery/task-catalog.json
 ```
-scripts/okstra.sh workflow가 사용하는 project-local Claude assets는 아래 경로들에 seed합니다.
-
-```text
-<target-project>/.claude/skills/okstra/SKILL.md
-<target-project>/.claude/skills/<sub-skill>/SKILL.md
-<target-project>/.claude/agents/<agent>.md
-```
 
 역할 구분:
 
@@ -123,6 +116,34 @@ scripts/okstra.sh workflow가 사용하는 project-local Claude assets는 아래
 - `.project-docs/ai/okstra/okstra-guide.md`
 - `.project-docs/ai/okstra/worker-catalog.md`
 
+### 4. Manager-owned cross-project state
+
+`okstra manager` 는 project-local `.okstra` 정본을 대체하지 않고, 여러 project-local task 를 묶는 전역 manager state 를 사용자 홈에 저장합니다.
+
+```text
+~/.okstra/managers/<manager-id>/
+├── manager.json
+├── projects.json
+└── task-groups/<safe-task-group>/<safe-task-id>/
+    ├── manifest.json
+    ├── children.json
+    ├── directives.jsonl
+    ├── snapshots.json
+    ├── events.jsonl
+    └── child-context/<safe-project-id>-<safe-child-task-id>.md
+```
+
+저장 권위:
+
+- `manager.json`: manager identity 와 schema version.
+- `projects.json`: manager 에 등록된 projectId / projectRoot / role / tags. `projectRoot` 는 이미 존재하는 디렉터리여야 하며, project-local `.okstra/project.json` 이 없을 때만 setup-equivalent registration 을 수행합니다.
+- `manifest.json`, `children.json`, `directives.jsonl`: manager-owned plan, child assignment, shared/project directive.
+- `snapshots.json`: `task sync` 가 child project `.okstra` 에서 읽어온 read-side snapshot. project state 의 source of truth 가 아닙니다.
+- `events.jsonl`: `task-created`, `child-launch-prepared` 같은 manager event.
+- `child-context/*.md`: `task run` 이 준비한 child lead context. sibling project report/snapshot 은 read-side source material 로만 전달합니다.
+
+Path segment 는 slug 로 정규화합니다. 비 ASCII 값처럼 slug 가 비는 경우에는 `u-<sha1-prefix>` fallback segment 를 쓰지만, `manifest.json` 과 child `taskKey` 는 원래 입력값(`project-id:task-group:task-id`)을 보존합니다.
+
 ## Task manifest contract
 
 `task-manifest.json`은 Claude가 task continuity를 이해할 때 기준이 되는 canonical metadata 파일입니다.

package/docs/kr/architecture.md

@@ -77,7 +77,7 @@
 
 okstra 의 prepare 책임은 단일 python 진입점 [`okstra_ctl.run.prepare_task_bundle`](../../scripts/okstra_ctl/run.py) 에 모여 있습니다. 이 함수가 다음을 한 트랜잭션으로 수행합니다.
 
-- okstra 설치 자산(`~/.claude/skills/okstra/...`, `~/.claude/agents/...`, `~/.okstra/bin/...`) 존재 확인
+- okstra 설치 자산(`~/.agents/skills/okstra-*`, optional `~/.claude/skills/okstra-*` / `~/.claude/agents/*-worker.md`, `~/.okstra/bin/...`) 존재 확인
 - `<PROJECT_ROOT>/.okstra/project.json` self-registration (또는 projectId 일치 검증)
 - task type → `prompts/profiles/<task-type>.md` 로드 + 권장 workers 추출
 - 사용자 worker/model 오버라이드 정규화 (Claude/Codex/Antigravity/Report-writer 각각 display ↔ execution-value 매핑)
@@ -122,6 +122,7 @@ okstra 의 prepare 책임은 단일 python 진입점 [`okstra_ctl.run.prepare_ta
 - [`okstra_ctl.session`](../../scripts/okstra_ctl/session.py) · [`okstra_ctl.seeding`](../../scripts/okstra_ctl/seeding.py) — Claude session id / resume command / 설치 검증 / runtime settings.
 - [`okstra_ctl.{ids,index,invocation,jsonl,project_meta,reconcile,resolver,sequence,batch,backfill,listing,locks,tmux}`](../../scripts/okstra_ctl/) — 중앙 인덱스 (`~/.okstra`) 의 기존 모듈군.
 - [`okstra_project.{resolver,state}`](../../scripts/okstra_project/) — PROJECT_ROOT 해석 + project.json upsert + task-catalog/manifest reader.
+- [`okstra_ctl.manager_cli`](../../scripts/okstra_ctl/manager_cli.py), [`manager_store`](../../scripts/okstra_ctl/manager_store.py), [`manager_sync`](../../scripts/okstra_ctl/manager_sync.py), [`manager_launch`](../../scripts/okstra_ctl/manager_launch.py), [`manager_paths`](../../scripts/okstra_ctl/manager_paths.py) — `okstra manager` 의 cross-project manager state, one-way project snapshot sync, child launch packet/context 생성.
 
 ### Bash entry points (thin)
 
@@ -146,9 +147,9 @@ okstra 의 prepare 책임은 단일 python 진입점 [`okstra_ctl.run.prepare_ta
 - [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md) — main okstra lead contract. 런타임 리소스(`~/.okstra/prompts/lead/`)이며 agent skill 이 아닙니다.
 - [`skills/okstra-setup/SKILL.md`](../../skills/okstra-setup/SKILL.md) — **첫 실행 부트스트랩**. `okstra install` + `project.json` 생성.
 - [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md) — **현재 claude 세션 안에서 okstra task 를 시작**하는 in-session 진입점. `prepare_task_bundle` 직접 호출.
-- 사용자 호출 가능 스킬은 `skills/okstra-setup/SKILL.md`, `skills/okstra-brief/SKILL.md`, `skills/okstra-run/SKILL.md`, `skills/okstra-memory/SKILL.md`, `skills/okstra-inspect/SKILL.md`, `skills/okstra-schedule/SKILL.md`, `skills/okstra-container-build/SKILL.md` 7종뿐이며, 이것만 agent skill home 으로 복사됩니다 — brief 작성, phase 진행, 전역 Memory Book 저장/검색, status/history/report/time/logs/cost/errors/recap read-side, schedule 보조, 그리고 `okstra-container-build` 는 검증 완료된 task 코드를 docker compose 그룹으로 배포하고 컨테이너별 watcher 로 감시하는 비선형(PHASE_SEQUENCE 외부) 컨테이너 배포/감시 스킬. `okstra-inspect` 의 read-side facet 은 `skills/okstra-inspect/SKILL.md` 의 sub-command 표가 정본인 8종입니다. `okstra-inspect logs` 는 codex/antigravity wrapper 가 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` 로 남기는 live-log sidecar 의 인벤토리·정리 안내(read-only), `okstra-inspect cost` 는 `okstra context-cost` 결과 요약, `okstra-inspect errors` 는 task 의 okstra-run 에러 로그를 타임스탬프 markdown error-report 로 모아 렌더하고 요약을 출력, `okstra-inspect recap` 은 task 의 run 간 phase 전·후 요약에 더해 `.okstra` 산출물에 대한 자유 Q&A 까지 답합니다.
+- 사용자 호출 가능 스킬은 `skills/okstra-setup/SKILL.md`, `skills/okstra-brief/SKILL.md`, `skills/okstra-run/SKILL.md`, `skills/okstra-manager/SKILL.md`, `skills/okstra-memory/SKILL.md`, `skills/okstra-inspect/SKILL.md`, `skills/okstra-schedule/SKILL.md`, `skills/okstra-container-build/SKILL.md` 8종뿐이며, 이것만 agent skill home 으로 복사됩니다 — brief 작성, phase 진행, cross-project manager task 조정, 전역 Memory Book 저장/검색, status/history/report/time/logs/cost/errors/recap read-side, schedule 보조, 그리고 `okstra-container-build` 는 검증 완료된 task 코드를 docker compose 그룹으로 배포하고 컨테이너별 watcher 로 감시하는 비선형(PHASE_SEQUENCE 외부) 컨테이너 배포/감시 스킬. `okstra-manager` 는 `okstra manager` CLI JSON/launch packet 을 source of truth 로 사용하며, manager-owned plan/assignment/directive/snapshot/event 는 `~/.okstra/managers/<manager-id>/` 아래에 저장합니다. `okstra-inspect` 의 read-side facet 은 `skills/okstra-inspect/SKILL.md` 의 sub-command 표가 정본인 8종입니다. `okstra-inspect logs` 는 codex/antigravity wrapper 가 매 dispatch 마다 `runs/<task-type>/prompts/<worker>-prompt-<phase>-<seq>.log` 로 남기는 live-log sidecar 의 인벤토리·정리 안내(read-only), `okstra-inspect cost` 는 `okstra context-cost` 결과 요약, `okstra-inspect errors` 는 task 의 okstra-run 에러 로그를 타임스탬프 markdown error-report 로 모아 렌더하고 요약을 출력, `okstra-inspect recap` 은 task 의 run 간 phase 전·후 요약에 더해 `.okstra` 산출물에 대한 자유 Q&A 까지 답합니다.
 - 내부 운영 계약 — `context-loader` / `team-contract` / `convergence` / `report-writer` 와 lead 계약 — 은 `prompts/lead/*.md` 로, 구현/검증 워커의 언어별 coding preflight 는 `prompts/coding-preflight/*` (overview 라우터 + clean-code + languages/frameworks/architectures 3단계 선택) 로 이동했습니다. 모두 `~/.okstra/prompts/` 에 설치되는 런타임 리소스이며 skill discovery 대상이 아닙니다. generated launch prompt 가 lead 에게 절대 경로를 제공하고, 재설치 시 과거 `okstra-context-loader` / `okstra-team-contract` / `okstra-convergence` / `okstra-report-writer` / `okstra-coding-preflight` / `okstra` skill 디렉터리는 exact-name prune 됩니다.
-- 플러그인 매니페스트: [`../../.claude-plugin/plugin.json`](../../.claude-plugin/plugin.json) — `npx skills@latest add Devonshin/okstra` 보조 채널이 참조. 일반 셋업에는 `npx okstra@latest install` 을 사용한다. 플러그인 매니페스트는 사용자 진입점 7개(`okstra-setup`, `okstra-brief`, `okstra-run`, `okstra-memory`, `okstra-inspect`, `okstra-schedule`, `okstra-container-build`)만 노출한다.
+- 플러그인 매니페스트: [`../../.claude-plugin/plugin.json`](../../.claude-plugin/plugin.json) — `npx skills@latest add Devonshin/okstra` 보조 채널이 참조. 일반 셋업에는 `npx okstra@latest install` 을 사용한다. 플러그인 매니페스트는 사용자 진입점 8개(`okstra-setup`, `okstra-brief`, `okstra-run`, `okstra-manager`, `okstra-memory`, `okstra-inspect`, `okstra-schedule`, `okstra-container-build`)만 노출한다.
 - 설치 위치: `~/.claude/skills/<name>/SKILL.md` 또는 `~/.agents/skills/<name>/SKILL.md`.
 - 릴리스 절차: [`../../RELEASING.md`](../../RELEASING.md) — npm publish 흐름과 release-please / manual fallback.
 
@@ -175,7 +176,7 @@ okstra 의 prepare 단계는 디스크 권위 + 단일 python 진입점 모델
 │       ┌────────────┴────────────────┐                          │
 │       ▼                             ▼                          │
 │  on-disk authority             ~/.okstra (central index)       │
-│  <PROJECT_ROOT>/.project-docs/  per-task mutex + record_start  │
+│  <PROJECT_ROOT>/.okstra/        per-task mutex + record_start  │
 └────────────────────────────────────────────────────────────────┘
 ```
 

package/docs/kr/cli.md

@@ -620,7 +620,7 @@ chmod +x ~/.local/bin/okstra-ctl
 
 ### `okstra` Node CLI — admin / introspection subcommands
 
-`okstra` Node CLI (`bin/okstra`) 는 installer/admin 명령과 skill / agent 가 사용하는 introspection 명령을 함께 제공합니다. Python 런타임을 직접 호출하지 않고 Node wrapper를 통하므로 `PYTHONPATH` wiring은 `src/_python-helper.mjs`가 처리합니다.
+`okstra` Node CLI (`bin/okstra`) 는 installer/admin 명령과 skill / agent 가 사용하는 introspection 명령을 함께 제공합니다. Python 런타임을 직접 호출하지 않고 Node wrapper를 통하므로 `PYTHONPATH` wiring은 `src/lib/python-helper.mjs`가 처리합니다.
 
 | 명령 | 용도 |
 |---|---|
@@ -633,7 +633,7 @@ chmod +x ~/.local/bin/okstra-ctl
 | `okstra check-project [--json]` | 현재 프로젝트가 등록되었는지 검증 |
 | `okstra config <get\|set\|unset\|show> [key] [value] [--scope project\|global\|all]` | 영구 설정 관리 (예: `pr-template-path`). 원자적 JSON 쓰기 |
 | `okstra memory <add\|list\|search\|show\|archive>` | `~/.okstra/memory-book` 전역 대화 메모리 관리. 프로젝트 `.okstra/` 와 분리된 user-home 저장소이며, `okstra 에 정리해서 보관해` 자연어 스킬의 CLI 기반 |
-| `okstra manager <init\|discover-projects\|new\|task>` | 여러 프로젝트의 okstra task 를 manager-owned context 로 묶는 공개 CLI. `new project`, `new task-group`, `new task` 로 manager 계획을 만들고, `task assign` / `task note` / `task sync` / `task status` / `task run` 으로 프로젝트별 할당과 snapshot 을 관리한다. child task key 는 공개 문서에서 `project-id:task-group:task-id` 전체 형식을 사용하며, `task run` 은 child launch context packet 을 JSON 으로 반환한다 |
+| `okstra manager <init\|discover-projects\|new\|task>` | 여러 프로젝트의 okstra task 를 manager-owned context 로 묶는 공개 CLI. `new project`, `new task-group`, `new task` 로 manager 계획을 만들고, `task assign` / `task note` / `task sync` / `task status` / `task run` 으로 프로젝트별 할당과 snapshot 을 관리한다. `new project --project-root` 는 이미 존재하는 디렉터리만 받으며, 그 안의 `.okstra/project.json` 이 없을 때만 setup-equivalent registration 을 수행한다. child task key 는 공개 문서에서 `project-id:task-group:task-id` 전체 형식을 사용하고, 같은 manager task 안에서 child task id 가 다르면 `--child-task-id` 로 exact child 를 지정한다. `task run` 은 child lead 를 직접 실행하지 않고 `prepared` launch metadata/event 와 child launch context packet 을 JSON 으로 반환한다 |
 | `okstra migrate [--apply] [--cwd <dir>] [--quiet]` | 한 번만 실행: 프로젝트 산출물 루트를 `.project-docs/okstra/` → `.okstra/` 로 이동. 기본 dry-run, `--apply` 로 실제 실행. `git mv` (git worktree) + 빈 `.project-docs/` 제거 + `<PROJECT>/CLAUDE.md` import 라인 + `.gitignore` + `~/.okstra/{recent,active}.jsonl` + `~/.okstra/worktrees/registry.json` 의 해당 프로젝트 row 동기화. 이미 `.okstra/` 가 존재하거나 레거시 디렉토리가 없으면 exit 1 로 거부. v0.x 말까지 유지 후 제거 예정 |
 | `okstra task-list [--project-root <path>]` | `list_project_tasks` + `read_latest_task` 결과를 합쳐 task 카탈로그 + 최근 task 를 JSON 으로 반환 |
 | `okstra task-show <task-key> [--project-root <path>]` | task-manifest.json 의 workflow / phase / status 요약 |
@@ -647,7 +647,7 @@ chmod +x ~/.local/bin/okstra-ctl
 | `okstra wizard <init\|step\|render-args\|confirmation> --state-file <path>` | okstra-run 인터랙티브 입력 상태머신 (`okstra_ctl.wizard`). `init` 으로 state file 을 시드한 뒤 skill 이 `step --answer <val>` 을 반복 호출하면 다음 `Prompt` JSON 을 받음. `--answer` 는 **필수**. 응답을 주지 않고 다음 prompt 만 미리 보고 싶다면 `--no-submit` 으로 peek. `render-args` 는 최종 `render-bundle` 인자 맵, `confirmation` 은 사용자 echo 블록을 반환. `implementation` task type 에서는 `approved_plan_pick` 직후 `stage_pick` 단계가 추가되어 실행할 stage 를 선택하고, `executor_pick` 으로 넘어갑니다. brief 단계는 entry task-type(requirements-discovery / error-analysis / improvement-discovery)에서만 나오며, downstream 은 manifest 의 brief 를 자동 carry-in 하고(미등록 시 `brief_carry` 3-옵션 fallback), `release-handoff` 는 brief 없이 `handoff_stage_pick` 멀티선택(eligible stage 묶음 / 전체 task)으로 진입합니다 |
 | `okstra token-usage ...` | 설치된 `okstra-token-usage.py` 를 감싸 run token usage 수집/치환을 수행. 세션 jsonl 은 기본적으로 `$OKSTRA_HOME/cache/token-usage/` 의 byte cursor 캐시로 증분 스캔하며, `--no-cache` 로 캐시를 우회해 전체 재스캔을 강제할 수 있음(정확성 폴백) |
 
-> 모든 subcommand 는 `bin/okstra` 가 spawn 하는 python 헬퍼 (`src/_python-helper.mjs`) 가 `PYTHONPATH` 와 `~/.okstra/lib/python` 을 wire 합니다. 직접 `python3 -m okstra_ctl.*` 으로 호출하면 `PYTHONPATH` 를 사용자가 직접 셋업해야 합니다.
+> 모든 subcommand 는 `bin/okstra` 가 spawn 하는 python 헬퍼 (`src/lib/python-helper.mjs`) 가 `PYTHONPATH` 와 `~/.okstra/lib/python` 을 wire 합니다. 직접 `python3 -m okstra_ctl.*` 으로 호출하면 `PYTHONPATH` 를 사용자가 직접 셋업해야 합니다.
 
 ### Live-log sidecar
 

package/docs/project-structure-overview.md

@@ -153,17 +153,29 @@ Runtime/install asset changes follow this checklist:
 | `setup` | `src/commands/lifecycle/setup.mjs` | Create/update `<PROJECT_ROOT>/.okstra/project.json` |
 | `check-project` | `src/commands/lifecycle/check-project.mjs` | Verify project registration |
 | `config` | `src/commands/lifecycle/config.mjs` | Read/write project/global settings such as PR template path |
+| `migrate` | `src/commands/lifecycle/migrate.mjs` | One-shot legacy `.project-docs/okstra` → `.okstra` migration helper |
+| `git-reconcile` | `src/commands/execute/git-reconcile.mjs` | Reconcile stale stage SHAs after external git history changes |
+| `handoff` | `src/commands/execute/handoff.mjs` | Stage-group release-handoff eligibility / assemble / record helpers |
+| `integrate-stages` | `src/commands/execute/integrate-stages.mjs` | Merge verified stages into the task worktree and clean stage worktrees |
 | `task-list`, `task-show` | `src/commands/inspect/task-list.mjs`, `src/commands/inspect/task-show.mjs` | Task/run introspection for skills |
+| `resolve-task-key` | `src/commands/inspect/resolve-task-key.mjs` | Resolve a bare task-id to candidate task-keys from the project catalog |
+| `time-report`, `log-report`, `error-report`, `error-zip` | `src/commands/inspect/*.mjs` | Read-side task runtime, wrapper log, and error aggregation helpers |
 | `context-cost` | `src/commands/inspect/context-cost.mjs` | Estimate task bundle file/read context cost |
 | `worktree-lookup` | `src/commands/execute/worktree-lookup.mjs` | Look up a task-key's registered worktree |
 | `plan-validate` | `src/commands/execute/plan-validate.mjs` | Check approved-plan approval marker |
 | `render-bundle` | `src/commands/execute/render-bundle.mjs` | Preview `prepare_task_bundle(render_only=True)` |
+| `run` | `src/commands/execute/run.mjs` | Host-aware execution front door (`auto` → Claude/Codex/external path selection) |
+| `codex-run`, `codex-dispatch` | `src/commands/execute/codex-*.mjs` | Codex lead dry-run bundle preparation and CLI-backed worker dispatch |
+| `team` | `src/commands/execute/team.mjs` | External lead tmux-pane worker dispatch / await / teardown |
 | `render-views` | `src/commands/report/render-views.mjs` | Generate slim MD + self-contained HTML report views |
+| `render-final-report`, `inject-report-index` | `src/commands/report/*.mjs` | Render final-report Markdown from data.json and inject top-of-report index anchors |
 | `wizard` | `src/commands/execute/wizard.mjs` | Drive the `okstra-run` interactive state machine |
 | `token-usage` | `src/commands/execute/token-usage.mjs` | Wrap installed Python token usage CLI |
+| `spawn-followups`, `error-log` | `src/commands/execute/*.mjs` | Follow-up task bundle creation and run error-log append helpers |
 | `memory` | `src/commands/memory/memory.mjs` | Store/find global conversation memory under `~/.okstra/memory-book` |
 | `recap` | `src/commands/inspect/recap.mjs` | `okstra recap <assemble\|record>` Node wrapper backing the okstra-inspect `recap` facet |
 | `container` | `src/commands/inspect/container.mjs` | `bin okstra container` thin shim into `scripts/okstra_ctl/container.py` for the okstra-container-build skill |
+| `manager` | `src/commands/manager.mjs` | Thin shim into `scripts/okstra_ctl/manager_cli.py` for cross-project manager state and child launch packets |
 
 `src/lib/python-helper.mjs` centralizes Node → Python execution so command modules do not duplicate subprocess wiring.
 
@@ -176,7 +188,7 @@ Top-level scripts:
 | `okstra.sh` | Bash CLI wrapper around `prepare_task_bundle`, optionally launches `claude` |
 | `okstra-ctl.sh` | Bash control center for list/show/open/rerun/reconcile/project commands |
 | `okstra-central.sh` | Central run index writer / reconciler entrypoint |
-| `okstra-codex-exec.sh`, `okstra-antigravity-exec.sh` | Worker CLI wrappers with log/status sidecars |
+| `okstra-claude-exec.sh`, `okstra-codex-exec.sh`, `okstra-antigravity-exec.sh` | Worker CLI wrappers with log/status sidecars |
 | `okstra-wrapper-status.py` | Heartbeat sidecar writer used by worker wrappers |
 | `okstra-token-usage.py` | Token usage CLI entrypoint |
 | `okstra-render-final-report.py` | Render final-report Markdown from data.json |
@@ -227,6 +239,11 @@ Important modules:
 | `container.py` | okstra-container-build 공개 스킬의 `okstra container` 수렴 entrypoint — `provision_container_group` + `up`/`status`/`logs`/`stop-watcher`/`down` 디스패치, env override 합성, compose argv 조립, 컨테이너별 watcher 기동 |
 | `container_registry.py` | flock-guarded 보조 인덱스 — 컨테이너 그룹별 tmux session/pane 및 watcher findings 추적 |
 | `plan_run_root.py` | `approved_plan_path` → `plan_run_root` 파생 + task-key 역추적 공유 헬퍼 |
+| `manager_cli.py` | `okstra manager` Python entrypoint — manager init/discover/new/task subcommands and JSON output |
+| `manager_paths.py` | Manager state path SSOT under `~/.okstra/managers/<manager-id>/`; slug fallback uses `u-<sha1-prefix>` when a safe segment would be empty |
+| `manager_store.py` | Manager-owned state mutation — project membership, task planning, assignment, directives, event append |
+| `manager_sync.py` | One-way child project `.okstra` snapshot reader; corrupt child state becomes row-level `error` so other children continue |
+| `manager_launch.py` | Child launch packet and manager child context renderer; records `prepared` launch metadata/events without changing project-local task state |
 
 ### 4.4 `scripts/okstra_project/`
 
@@ -326,17 +343,17 @@ The lead operating contract moved out of `agents/` to `prompts/lead/okstra-lead-
 1. Resolve project root and verify/upsert `project.json`.
 2. Resolve profile, required workers, model assignments, executor provider.
 3. Compute task/run paths and persist run context under `runs/<task-type>/manifests/`.
-4. Provision or reuse the task-key worktree.
+4. Provision or reuse the task-key worktree, or the selected implementation stage worktree for stage-isolated runs.
 5. Materialize `instruction-set/` files and lead prompt snapshot.
 6. Persist run inputs, team state, task manifest, task index, run manifest, timeline, discovery pointers.
 7. Record the run in `~/.okstra/{active,recent}.jsonl` and project index.
 
 ### 5.2 Worktree model
 
-One task-key owns one worktree:
+Non-`implementation` phases share one task-key worktree:
 
 ```text
-~/.okstra/worktrees/<project-id>/<task-group>/<task-id>/
+~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/
 ```
 
 Branch name:
@@ -345,7 +362,16 @@ Branch name:
 <work-category-prefix>-<task-id-segment>
 ```
 
-The same worktree/branch is reused across all phases. `worktreeSyncDirs`, `worktreeSyncFiles`, and `worktreeSnapshotFiles` provide filesystem continuity only; they do not expand okstra's context/write boundary.
+That task-key worktree is reused for `requirements-discovery` through `implementation-planning`, and by whole-task verification / handoff flows after implementation stages have been integrated. `worktreeSyncDirs`, `worktreeSyncFiles`, and `worktreeSnapshotFiles` provide filesystem continuity only; they do not expand okstra's context/write boundary.
+
+`implementation` is stage-isolated: one run owns one `stage-<N>` worktree and branch, with stage-key reservation in `worktree_registry.py`.
+
+```text
+~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/stage-<N>/
+<work-category-prefix>-<task-id-segment>-s<N>
+```
+
+Single-stage `final-verification --stage <N>` reuses the matching implementation stage worktree read-only, while run artifacts are isolated under `runs/final-verification/stage-<N>/`. Whole-task final-verification keeps the flat `runs/final-verification/` shape.
 
 ### 5.3 Final report model
 
@@ -368,13 +394,14 @@ The Markdown is derived, not the authoring source. The schema is the contract.
 ~/.okstra/
 ├── version
 ├── lib/python/{okstra_ctl,okstra_project,okstra_token_usage,okstra_vendor,lib/}
-├── bin/{okstra.sh,okstra-codex-exec.sh,okstra-antigravity-exec.sh,...}
+├── bin/{okstra.sh,okstra-claude-exec.sh,okstra-codex-exec.sh,okstra-antigravity-exec.sh,...}
 ├── templates/
 ├── installed-skills.json
 ├── installed-agents.json
 ├── active.jsonl
 ├── recent.jsonl
 ├── projects/<project-id>/{meta.json,index.jsonl}
+├── managers/<manager-id>/{manager.json,projects.json,task-groups/...}
 ├── worktrees/{registry.json,registry.lock,<project>/<group>/<task>/}
 ├── archive/
 └── .locks/
@@ -481,4 +508,4 @@ Clarifications now live in the unified `## 1. Clarification Items` table. Deprec
 
 ---
 
-*Updated: 2026-06-05 · Source of truth checked against `package.json`, `bin/okstra`, `tools/build.mjs`, `scripts/`, `skills/`, `agents/`, `templates/`, `schemas/`, `validators/`, and tests.*
+*Updated: 2026-06-27 · Source of truth checked against `package.json`, `bin/okstra`, `src/cli-registry.mjs`, `src/lib/skill-catalog.mjs`, `tools/build.mjs`, `scripts/`, `skills/`, `agents/`, `templates/`, `schemas/`, `validators/`, and tests.*

package/docs/task-process/README.md

@@ -42,7 +42,7 @@ flowchart TD
 | `error-analysis` | [error-analysis.md](error-analysis.md) | 증상과 evidence로 원인 후보와 검증 경로를 찾는다. |
 | `implementation-planning` | [implementation-planning.md](implementation-planning.md) | 구현 옵션, 검증, rollback, approval gate가 있는 계획을 만든다. |
 | `implementation` | [implementation.md](implementation.md) | 승인된 계획을 executor가 구현하고 verifier가 독립 검증한다. |
-| `final-verification` | [final-verification.md](final-verification.md) | 구현 결과를 read-only로 acceptance 판단한다. |
+| `final-verification` | [final-verification.md](final-verification.md) | 구현 결과의 whole-task 또는 single-stage acceptance를 판정한다. |
 | `release-handoff` | [release-handoff.md](release-handoff.md) | accepted verdict 뒤 push/PR handoff를 lead-only로 수행한다. |
 
 ## 4. 핵심 코드 위치
@@ -52,10 +52,13 @@ flowchart TD
 | okstra-run skill 절차 | [`skills/okstra-run/SKILL.md`](../../skills/okstra-run/SKILL.md) |
 | wizard state machine | [`scripts/okstra_ctl/wizard.py`](../../scripts/okstra_ctl/wizard.py) |
 | wizard prompt text | [`prompts/wizard/prompts.ko.json`](../../prompts/wizard/prompts.ko.json) |
-| render-bundle Node shim | [`src/render-bundle.mjs`](../../src/render-bundle.mjs) |
+| render-bundle Node shim | [`src/commands/execute/render-bundle.mjs`](../../src/commands/execute/render-bundle.mjs) |
 | bundle 생성 단일 진입점 | [`scripts/okstra_ctl/run.py`](../../scripts/okstra_ctl/run.py) |
+| implementation stage 선택/provision | [`scripts/okstra_ctl/implementation_stage.py`](../../scripts/okstra_ctl/implementation_stage.py) |
+| stage target/base/verification 정책 | [`scripts/okstra_ctl/stage_targets.py`](../../scripts/okstra_ctl/stage_targets.py) |
 | phase boundary | [`scripts/okstra_ctl/workflow.py`](../../scripts/okstra_ctl/workflow.py) |
 | task worktree | [`scripts/okstra_ctl/worktree.py`](../../scripts/okstra_ctl/worktree.py) |
+| stage-group handoff | [`scripts/okstra_ctl/handoff.py`](../../scripts/okstra_ctl/handoff.py) |
 | worker roster parser | [`scripts/okstra_ctl/workers.py`](../../scripts/okstra_ctl/workers.py) |
 | lead operating contract | [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md) |
 | phase profiles | [`prompts/profiles/`](../../prompts/profiles/) |
@@ -68,7 +71,6 @@ flowchart TD
 | `requirements-discovery` | 공통 질문만 | profile/brief/base-ref 존재 | multi-worker analysis, convergence 1 round default | `pending-routing-decision` |
 | `error-analysis` | 공통 질문만 | profile/brief/base-ref 존재 | multi-worker analysis, convergence 2 rounds default | `implementation-planning` |
 | `implementation-planning` | 공통 질문만 | profile/brief/base-ref 존재 | multi-worker analysis + Phase 6 plan-body verification | `implementation` |
-| `implementation` | approved plan, stage, executor | approved marker, stage map, QA command deny-list | executor writes, verifiers read-only | `final-verification` |
-| `final-verification` | 공통 질문만 | profile/brief/base-ref 존재 | multi-worker read-only verification | `pending-release-handoff` |
-| `release-handoff` | PR template override/scope | PR template resolution, empty worker roster | single-lead, no TeamCreate, no workers | `done-or-follow-up` |
-
+| `implementation` | approved plan, stage multi-pick, executor | approved marker, stage map, stage-key reservation, QA command deny-list | one run = one stage; executor writes in isolated stage worktree, verifiers read-only | `final-verification` |
+| `final-verification` | approved plan, stage pick(whole-task or single-stage) | `VERIFICATION_TARGET` 해소; whole-task 자동 통합/teardown 또는 single-stage worktree reuse | whole-task may integrate stages first; analyser verification itself is read-only | `pending-release-handoff` |
+| `release-handoff` | handoff scope(stage-group or whole-task), PR template override/scope | accepted verification eligibility, generated `release-handoff-input.md`, empty worker roster | single-lead; whole-task PR or stage-group collector branch/PR | `done-or-follow-up` |

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

@@ -93,7 +93,7 @@ sequenceDiagram
     Skill->>FS: read claude-execution-prompt.md
 ```
 
-`render-bundle`은 `--workspace-root`와 `--render-only`를 직접 붙인다. 따라서 okstra-run 경로의 initial run status는 `prepared`, task status는 `instruction-set-generated`로 시작한다.
+`render-bundle`의 Node shim은 [`src/commands/execute/render-bundle.mjs`](../../src/commands/execute/render-bundle.mjs)다. 이 shim이 `--workspace-root`, `--render-only`, runtime resolution 인자를 직접 붙인다. 따라서 okstra-run 경로의 initial run status는 `prepared`, task status는 `instruction-set-generated`로 시작한다.
 
 ## 5. Claude lead phase 1-7
 
@@ -131,8 +131,15 @@ flowchart TD
     Runs --> Reports[reports/final-report-*.md<br/>reports/*.data.json]
     Runs --> State[state/*.json]
     Runs --> Status[status/final-status-*.json]
+    Runs --> ImplStage[implementation/stage-N/...]
+    Runs --> FvStage[final-verification/stage-N/...]
+    Runs --> Carry[implementation/carry/stage-N.json]
+    Runs --> Consumers[implementation-planning/consumers.jsonl]
+    Root --> Handoff[release-handoff-input.md]
 ```
 
+`implementation`과 단일-stage `final-verification`은 run 산출물을 `stage-<N>/` 아래에 격리한다. `implementation`의 carry sidecar와 `consumers.jsonl`은 stage 간 조율 ledger라 phase root에 남는다. `release-handoff`는 brief를 받지 않고 prepare가 `release-handoff-input.md`를 생성한다.
+
 `runtime/`은 build output이므로 이 흐름을 고칠 때는 source인 `scripts/`, `skills/`, `agents/`, `prompts/`, `templates/`, `validators/`를 수정하고 `npm run build`로 갱신한다.
 
 ## 7. 공통 분기 규칙
@@ -157,10 +164,12 @@ flowchart TD
 
 중요한 점은 `Use defaults`가 model 기본값을 뜻한다는 것이다. non-implementation task-type에서는 defaults를 골라도 worker roster 질문은 계속 나온다. 반대로 `implementation`은 worker override 질문이 없다. profile default roster와 executor binding을 사용한다.
 
+Worktree 규칙은 phase별로 다르다. `requirements-discovery`부터 `implementation-planning`까지는 task-key worktree를 재사용한다. `implementation`은 task-key worktree를 anchor로 삼되 실제 실행은 stage-key(`stage-<N>`) worktree와 `runs/implementation/stage-<N>/` 산출물에서 한 stage씩 격리한다. `final-verification --stage N`은 해당 implementation stage worktree를 읽기 대상으로 재사용하고, whole-task 모드는 task-key worktree에 stage commit을 자동 통합한 뒤 검증 target을 만든다.
+
 ## 8. 주의할 불일치 지점
 
 - `okstra-run` wizard 경로는 implementation approved plan에 이미 approval marker가 있어야 통과한다. `scripts/okstra.sh`에는 `--approve`가 있어 checkbox를 CLI ack로 flip할 수 있지만, 현재 wizard `render_args()`에는 `approve` flag가 없다.
-- `release-handoff`도 task worktree provisioning 대상이다. 정상적인 handoff는 같은 task-key의 implementation/final-verification worktree를 재사용하는 흐름이 안전하다. 새 task로 시작하면 새 worktree가 만들어지고, profile의 "implementation commit이 있어야 함" entry gate에서 막힐 수 있다.
+- `release-handoff`는 brief가 없다. prepare가 accepted final-verification report를 인용해 `release-handoff-input.md`를 만들고, wizard의 `handoff_stage_pick` 또는 CLI `--stages`가 whole-task/stage-group 범위를 고정한다.
+- `release-handoff`도 task worktree provisioning 대상이다. 정상적인 handoff는 같은 task-key의 implementation/final-verification 결과를 재사용하는 흐름이 안전하다. 새 task로 시작하면 새 worktree가 만들어지고, profile의 "implementation commit이 있어야 함" entry gate에서 막힐 수 있다.
 - `release-handoff`는 profile에 `Required workers:` block이 없다. runtime도 worker roster를 강제로 empty로 만든다.
 - 모든 task-type은 한 run 안에서 다음 lifecycle phase를 시작하지 않는다. "다음 단계 진행해"는 현재 phase 산출을 마무리하라는 뜻으로만 해석한다.
-

package/docs/task-process/final-verification.md

@@ -21,10 +21,10 @@
 flowchart TD
     Start[/okstra-run/] --> Common[공통 task identity flow]
     Common --> Type[task-type = final-verification]
-    Type --> Worktree{active task worktree?}
-    Worktree -->|yes| Defaults[Use defaults / Customize]
-    Worktree -->|no| BaseRef[base-ref pick/text]
-    BaseRef --> Defaults
+    Type --> PlanPick[approved plan pick]
+    PlanPick --> Approved[approval marker confirm]
+    Approved --> Stage[stage pick<br/>whole-task or stage number]
+    Stage --> Defaults[Use defaults / Customize]
     Defaults -->|defaults| Workers[worker roster pick<br/>claude/codex/report-writer default]
     Defaults -->|customize| Models[lead + worker model prompts]
     Models --> Extras[directive, related tasks, clarification]
@@ -35,38 +35,47 @@ flowchart TD
 
 `final-verification`은 analyser roster가 있는 non-implementation phase다. 따라서 `Use defaults`를 골라도 worker roster prompt는 계속 나온다. 기본 required workers는 `claude`, `codex`, `report-writer`이고, `antigravity`는 opt-in이다.
 
+이 phase는 `base-ref`를 직접 묻지 않는다. wizard는 approved plan의 Stage Map을 기준으로 whole-task 또는 단일 stage를 선택하고, prepare가 registry/`consumers.jsonl`/git 상태에서 `VERIFICATION_TARGET`을 해소한다.
+
 ## 3. entry gate
 
 ```mermaid
 sequenceDiagram
-    participant Lead as Claude lead
-    participant Brief as task brief
-    participant Impl as implementation final-report
+    participant P as prepare_task_bundle
+    participant C as consumers.jsonl
+    participant Reg as worktree registry
     participant Git as verification worktree
+    participant Lead as Claude lead
 
-    Lead->>Brief: Source Implementation Report section read
-    Lead->>Impl: required sections present?
-    Lead->>Git: inspect same worktree named by report
-    Lead->>Git: git rev-parse HEAD
-    Lead->>Git: git status --short
-    Lead->>Git: git diff --stat <implementation-base>..HEAD
-    Git-->>Lead: verification target snapshot
-    Lead->>Lead: commit list and diff summary match?
+    P->>C: backfill carry and read done rows
+    P->>Reg: resolve task or stage worktree
+    alt whole-task
+        P->>Git: merge done stage commits into task worktree
+        P->>Git: teardown clean stage worktrees/registry keys
+    else single-stage
+        P->>Git: reuse selected stage worktree
+    end
+    P->>Git: resolve base/head/diff stat
+    P-->>Lead: inject VERIFICATION_TARGET
+    Lead->>Lead: verify against injected target only
 ```
 
-lead는 worker dispatch 전에 verification target을 고정한다. 다음 중 하나라도 실패하면 검증하지 않고 `blocked`로 끝내며 `implementation` 또는 `implementation-planning`으로 되돌린다.
+prepare는 worker dispatch 전에 verification target을 고정한다. 다음 중 하나라도 실패하면 lead prompt가 시작되지 않고 `PrepareError`로 멈춘다.
+
+- approved plan의 Stage Map을 읽을 수 없다.
+- whole-task인데 Stage Map의 모든 stage가 `done`이 아니다.
+- whole-task 자동 통합 중 merge conflict가 난다.
+- single-stage인데 선택 stage의 implementation stage worktree가 없거나 dirty다.
+- verification worktree가 `.okstra/` 밖 dirty state다.
 
-- task brief에 `## Source Implementation Report`가 없다.
-- 인용된 implementation final report가 없거나 필수 section이 빠져 있다.
-- report가 named worktree를 가리키는데 lead가 다른 checkout을 보고 있다.
-- implementation report의 commit list / diff summary와 현재 checkout이 맞지 않는다.
-- delivered code change commit이 없다.
+시작된 lead는 `VERIFICATION_TARGET`을 권위로 취급한다. worktree/base/head/stage/source report를 brief에서 다시 고르지 않는다.
 
 ## 4. 검증 실행 흐름
 
 ```mermaid
 flowchart TD
-    Gate[entry gate passed] --> Lead[Claude lead fixes target snapshot]
+    Gate[entry gate passed] --> Target[injected VERIFICATION_TARGET]
+    Target --> Lead[Claude lead confirms target snapshot]
     Lead --> CW[Claude verifier<br/>read-only]
     Lead --> XW[Codex verifier<br/>read-only]
     Lead --> GW{Antigravity opt-in?}
@@ -110,7 +119,7 @@ flowchart TD
 
 `## 7. Final Verdict`에는 `Verdict Token` field가 정확히 하나 들어가야 하며 값은 다음 셋 중 하나다.
 
-- `accepted`: release-handoff로 넘겨도 되는 상태
+- `accepted`: whole-task이면 plain `release-handoff`, single-stage이면 `release-handoff(stage-group)` 후보가 되는 상태
 - `conditional-accept`: 조건을 모두 명시해야 하며, 조건이 gate면 다음 phase를 막는다
 - `blocked`: acceptance blocker가 있어 release-handoff로 갈 수 없는 상태
 
@@ -132,6 +141,7 @@ flowchart TD
 final report에는 최소 다음이 필요하다.
 
 - originating implementation final-report path
+- verification scope(`whole-task` 또는 `single-stage`)와 injected `VERIFICATION_TARGET`
 - inspected worktree path
 - implementation base ref와 run start head SHA
 - quoted commit list / diff summary
@@ -146,15 +156,16 @@ final report에는 최소 다음이 필요하다.
 
 ```mermaid
 flowchart TD
-    FV[final-verification] --> Allowed[read-only inspect/test/validate]
+    FV[final-verification] --> Runtime[prepare-owned whole-task integration<br/>or single-stage target resolution]
+    FV --> Allowed[lead read-only inspect/test/validate]
     FV -. forbidden .-> Edit[source edit or config edit]
     FV -. forbidden .-> Fix[in-run bug fix]
-    FV -. forbidden .-> Mutate[mutating command]
+    FV -. forbidden .-> Mutate[lead-owned mutating command]
     FV -. forbidden .-> Expand[scope expansion]
     FV -. forbidden .-> Hide[hide verifier dissent]
 ```
 
-source edit, follow-up fix, scope expansion은 전부 금지다. 결함을 발견하면 현재 run 안에서 고치지 않고 final report에 blocker로 기록한 뒤 새 `error-analysis` 또는 `implementation-planning` 입력으로 넘긴다.
+whole-task mode의 stage merge/teardown은 prepare가 수행하는 runtime-owned 통합 단계다. 그 이후 lead 검증은 read-only다. source edit, follow-up fix, scope expansion은 전부 금지다. 결함을 발견하면 현재 run 안에서 고치지 않고 final report에 blocker로 기록한 뒤 새 `error-analysis` 또는 `implementation-planning` 입력으로 넘긴다.
 
 ## 8. 확인한 코드
 

package/docs/task-process/implementation.md

@@ -27,8 +27,9 @@ flowchart TD
     BaseRef --> PlanPick
     PlanPick --> Approved{APPROVED marker present?}
     Approved -->|no| Retry[re-prompt same step]
-    Approved -->|yes| Stage[stage pick<br/>auto or number]
-    Stage --> Executor[executor pick<br/>claude/codex/antigravity]
+    Approved -->|yes| Stage[stage multi-pick<br/>ready/active markers]
+    Stage --> Chain[render-args<br/>stage + chain-stages]
+    Chain --> Executor[executor pick<br/>claude/codex/antigravity]
     Executor --> Defaults[Use defaults / Customize]
     Defaults -->|defaults| Confirm
     Defaults -->|customize| Models[lead + executor model + report-writer model]
@@ -37,7 +38,9 @@ flowchart TD
     Confirm --> Render[render-bundle]
 ```
 
-`implementation`은 worker override 질문이 없다. wizard `render_args()`가 `workers`를 빈 문자열로 내보내고, runtime이 profile default roster를 사용한다. 현재 okstra-run wizard 경로는 승인 checkbox를 직접 flip하는 `--approve`를 노출하지 않는다. plan file에는 이미 recognized approval marker가 있어야 한다.
+`implementation`은 worker override 질문이 없다. wizard `render_args()`가 `workers`를 빈 문자열로 내보내고, runtime이 profile default roster를 사용한다. `stage_pick`은 완료/진행중/준비됨/대기 상태를 보여주는 multi-pick이다. 선택한 stage 집합은 의존성 closure와 위상정렬을 거쳐 `chain-stages` CSV가 되고, 각 실제 run은 그중 한 stage만 실행한다.
+
+현재 okstra-run wizard 경로는 승인 checkbox를 직접 flip하는 `--approve`를 노출하지 않는다. plan file에는 이미 recognized approval marker가 있어야 한다.
 
 ## 3. runtime gate
 
@@ -47,16 +50,21 @@ sequenceDiagram
     participant P as prepare_task_bundle
     participant Plan as approved final-report
     participant QA as project.json qaCommands
-    participant Stage as stage validator
+    participant Stage as stage target policy
+    participant Reg as worktree registry
+    participant WT as stage worktree
 
     W->>P: task-type=implementation, approved-plan, stage, executor
     P->>Plan: file exists?
     P->>Plan: approval marker regex matches?
     P->>Plan: unresolved Blocks=approval rows?
-    P->>Stage: validate stage structure
+    P->>Stage: parse Stage Map and recover carry/done rows
+    P->>Reg: read active stage-key reservations
+    P->>Stage: select exactly one ready stage
+    P->>WT: provision stage-N worktree + branch
     P->>QA: validate qaCommands deny-list
     P->>P: executor provider in resolved roster?
-    P->>P: provision/reuse worktree
+    P->>P: namespace run artifacts under stage-N
     P-->>W: prepared implementation prompt or PrepareError
 ```
 
@@ -86,16 +94,21 @@ Executor만 project file을 mutate할 수 있다. verifier는 같은 worktree에
 ```mermaid
 flowchart LR
     Plan[approved plan<br/>Stage Map] --> Parse[parse stage map]
-    Parse --> Done[read consumers.jsonl<br/>done stages]
-    Done --> Resolve{stage arg}
-    Resolve -->|auto| Next[lowest unblocked unfinished stage]
+    Parse --> Done[backfill carry<br/>read consumers.jsonl]
+    Done --> Reserved[read registry<br/>active stage reservations]
+    Reserved --> Resolve{stage arg}
+    Resolve -->|auto| Next[lowest ready<br/>not done/started/reserved]
     Resolve -->|number| Forced[selected stage]
-    Next --> Started[append consumer status=started]
-    Forced --> Started
-    Started --> Run[implementation executes selected stage]
+    Next --> Base[resolve stage base commit]
+    Forced --> Base
+    Base --> WT[create/reuse stage worktree]
+    WT --> Started[append consumer status=started]
+    Started --> Run[implementation executes one selected stage]
 ```
 
-stage 선택은 `auto` 또는 숫자다. 다른 task-type에서 `--stage`가 오면 `PrepareError`다. wizard는 approved plan에서 Stage Map을 parse해 stage picker에 `auto`와 각 stage를 보여준다.
+stage 선택은 `auto` 또는 숫자다. 다른 task-type에서 `--stage`가 오면 `PrepareError`다. runtime은 `consumers.jsonl`의 `done`/`started`와 registry의 active stage-key를 함께 보고 점유 stage를 제외한다.
+
+stage worktree base는 dependency 형태로 정한다. 독립 stage는 첫 implementation 진입 때 고정한 task-key worktree HEAD를 anchor로 삼고, 단일 의존 stage는 선행 stage의 done `head_commit`에서 분기한다. 다중 의존 stage는 모든 선행 done commit이 task-key worktree HEAD의 ancestor인지 확인한 뒤 그 HEAD에서 분기한다.
 
 ## 6. 산출물
 
@@ -113,12 +126,14 @@ flowchart TD
 final report에는 최소 다음이 필요하다.
 
 - approved plan path와 quoted approval marker
+- selected stage, isolated stage worktree path, run artifact path(`runs/implementation/stage-<N>/`)
 - commit SHA, message, plan step mapping
 - diff summary와 per-file summary
 - out-of-plan edits block
 - plan validation command의 실제 stdout/stderr와 exit code
 - TDD failing-then-passing evidence
 - verifier별 independent validation rerun result
+- `carry/stage-<N>.json` evidence sidecar와 `consumers.jsonl` started/done row
 - rollback verification
 - follow-up tasks table
 
@@ -146,4 +161,3 @@ flowchart TD
 - [`validators/validate-implementation-plan-stages.py`](../../validators/validate-implementation-plan-stages.py)
 - [`scripts/okstra_ctl/qa_commands.py`](../../scripts/okstra_ctl/qa_commands.py)
 - [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)
-

package/docs/task-process/release-handoff.md

@@ -14,7 +14,7 @@
 
 ## 1. 목적
 
-`release-handoff`는 `accepted` verdict가 나온 already-committed implementation branch를 push하거나 PR로 넘기는 terminal phase다. 새 commit을 만들지 않고, 검증된 diff를 그대로 포장한다.
+`release-handoff`는 `accepted` verdict가 나온 already-committed implementation 결과를 push하거나 PR로 넘기는 terminal phase다. whole-task mode는 검증된 task branch를 그대로 포장한다. stage-group mode는 선택 stage들을 collector branch에 assemble해 한 PR로 묶을 수 있으며, 이때 생성되는 merge commit은 `okstra handoff assemble`만 만든다.
 
 이 phase는 worker dispatch가 없다. `claude`, `codex`, `report-writer` roster를 쓰지 않으며 Claude lead가 inline으로 git/gh inspection, 사용자 질문, PR draft, final report 작성을 모두 수행한다.
 
@@ -24,7 +24,9 @@
 flowchart TD
     Start[/okstra-run/] --> Common[공통 task identity flow]
     Common --> Type[task-type = release-handoff]
-    Type --> Worktree{active task worktree?}
+    Type --> Plan[approved plan auto/pick]
+    Plan --> Scope[handoff stage pick<br/>whole-task or eligible stages]
+    Scope --> Worktree{active task worktree?}
     Worktree -->|yes| Defaults[Use defaults / Customize]
     Worktree -->|no| BaseRef[base-ref pick/text]
     BaseRef --> Defaults
@@ -32,14 +34,14 @@ flowchart TD
     Defaults -->|customize| Models[lead model prompt]
     Models --> Extras[directive, related tasks, clarification]
     Extras --> Template[PR template override?]
-    Template --> Scope[save template to project/global?]
-    Scope --> Confirm
+    Template --> TemplateScope[save template to project/global?]
+    TemplateScope --> Confirm
     Confirm --> Render[render-bundle]
 ```
 
-`release-handoff`는 worker roster prompt가 없다. wizard의 `render_args()`는 `pr-template-path`를 release-handoff일 때만 포함하고, runtime은 worker list를 강제로 empty로 만든다.
+`release-handoff`는 worker roster prompt가 없다. wizard의 `render_args()`는 `pr-template-path`를 release-handoff일 때만 포함하고, runtime은 worker list를 강제로 empty로 만든다. scope 선택은 prepare 전에 끝난다. whole-task는 accepted whole-task verification report가 있어야 하고, stage-group은 accepted single-stage verification으로 `verified` 처리됐지만 아직 `pr`로 덮이지 않은 stage만 후보가 된다.
 
-주의할 점은 이 phase도 task worktree provisioning 대상이라는 것이다. 정상 흐름은 같은 task-key의 implementation/final-verification worktree를 재사용한다. 새 task로 시작하면 새 branch가 만들어질 수 있고, entry gate의 "implementation commit exists" 조건에서 막힐 가능성이 높다.
+주의할 점은 이 phase도 task worktree provisioning 대상이라는 것이다. 정상 흐름은 같은 task-key의 implementation/final-verification 결과를 재사용한다. 새 task로 시작하면 새 branch가 만들어질 수 있고, entry gate의 "implementation commit exists" 조건에서 막힐 가능성이 높다.
 
 ## 3. prepare 단계
 
@@ -72,7 +74,10 @@ flowchart TD
     Source -->|no| Block[blocked<br/>route final-verification]
     Source -->|yes| Verdict{Verdict Token == accepted?}
     Verdict -->|no| Block
-    Verdict -->|yes| Status{git status --short clean?}
+    Verdict -->|yes| Mode{HANDOFF_MODE}
+    Mode -->|stage-group| Eligible[each selected stage<br/>verified and not in PR]
+    Mode -->|whole-task| Status{git status --short clean?}
+    Eligible --> Status
     Status -->|no| Dirty[blocked<br/>dirty tree]
     Status -->|yes| Branch{current branch is base branch?}
     Branch -->|yes| BaseBlock[blocked<br/>never operate on base branch]
@@ -84,7 +89,8 @@ flowchart TD
 lead는 사용자에게 push/PR 여부를 묻기 전에 다음을 확인한다.
 
 - prepare 가 생성한 input 문서(`release-handoff-input.md`)의 `## Source Verification Report` 가 모드(`HANDOFF_MODE`)와 인용 보고서 표를 담고 있다. brief 는 entry phase 의 입력물이라 release-handoff 에는 없다 — 사용자의 stage 선택은 wizard `handoff_stage_pick` 또는 CLI `--stages` 로 prepare 전에 끝난다.
-- 인용된 각 report 의 `## 7. Final Verdict`에 `Verdict Token = accepted`가 정확히 있다.
+- whole-task mode에서는 인용 report가 `verificationScope=whole-task`이고 `Verdict Token = accepted`여야 한다.
+- stage-group mode에서는 인용된 각 single-stage report가 `Verdict Token = accepted`여야 하며, prepare/`okstra handoff assemble`이 eligibility와 dependency closure를 다시 강제한다.
 - working tree가 clean이다.
 - 현재 branch가 `main`, `master`, `prod`, `preprod`, `staging`, `dev` 같은 base branch가 아니다.
 - `<base>..HEAD` commit range가 비어 있지 않다.
@@ -99,7 +105,11 @@ stateDiagram-v2
     Gate --> Q1: action selection
     Q1 --> LocalCheckout: local checkout
     Q1 --> Skip: skip
-    Q1 --> Q2: push + PR
+    Q1 --> Q2: push + PR whole-task
+    Q1 --> G2: push + PR stage-group
+    state "base select + stage confirmation / okstra handoff assemble" as Assemble
+    G2 --> Assemble
+    Assemble --> Q3: collector branch ready
     Q2 --> Probe: choose PR base
     Probe --> Q3: no conflict
     Probe --> Conflict: conflict detected
@@ -124,6 +134,8 @@ stateDiagram-v2
 
 `push + PR`에서만 merge-conflict probe를 한다.
 
+stage-group mode에서는 `local checkout`을 제공하지 않는다. `push + PR`을 고른 뒤 PR base를 먼저 선택하고, 이미 고정된 `HANDOFF_STAGES`를 확인한 다음 `okstra handoff assemble`이 collector branch를 만든다. 이후 conflict probe와 PR title/body 확인은 collector branch를 head로 삼는다.
+
 ```mermaid
 flowchart TD
     PushPR[push + PR selected] --> Fetch[git fetch origin chosen-base]
@@ -170,11 +182,13 @@ flowchart TD
 final report에는 최소 다음이 필요하다.
 
 - originating final-verification report path와 quoted `accepted` verdict row
+- handoff mode(`whole-task` 또는 `stage-group`)와 selected stages
 - feature branch와 run start `git status --short`
 - 사용자 선택 기록
 - 실행한 모든 git/gh command와 exit code
 - implementation commit list
 - merge-conflict probe 결과
+- stage-group이면 collector branch, merge commit SHA, dependency-closure 결과
 - PR 생성, 재사용, 생략 결과
 - routing recommendation `done`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.103.0",
+  "version": "0.105.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.103.0",
-  "builtAt": "2026-06-27T12:06:27.647Z",
+  "package": "0.105.0",
+  "builtAt": "2026-06-27T14:17:33.391Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/container_registry.py

@@ -4,54 +4,33 @@ docker 라벨은 컨테이너 존재 여부의 기준값(SSOT)이지만 tmux ses
 findings 파일 경로 같은 운영 메타데이터는 추적하지 못한다. 이 모듈은 task root
 하위 ``container/registry.json`` 에 그런 보조 정보를 가벼운 dict 로 보관한다.
 
-flock + tmp+``os.replace`` 원자 쓰기 idiom 은 ``worktree_registry`` 의
-``_registry_lock``/``_load``/``_save`` 를 그대로 복제했고, lock/registry 경로만
-``paths.container_paths()`` 로 해소해 전역 ``~/.okstra/worktrees/registry.json``
-과 분리한다. dict 구조는 ``{"services": {<svc>: {session_name, pane_id,
-findings_path}}}`` 한 가지뿐 — worktree_registry 의 dataclass 는 복제하지 않는다.
+flock + tmp+``os.replace`` 원자 쓰기 idiom 은 ``json_registry`` 의 공용
+Interface 를 사용하고, lock/registry 경로만 ``paths.container_paths()`` 로
+해소해 전역 ``~/.okstra/worktrees/registry.json`` 과 분리한다. dict 구조는
+``{"services": {<svc>: {session_name, pane_id, findings_path}}}`` 한 가지뿐 —
+worktree_registry 의 dataclass 는 복제하지 않는다.
 """
 from __future__ import annotations
 
-import contextlib
-import fcntl
-import json
-import os
 from pathlib import Path
 
+from .json_registry import load_registry_json, registry_lock, save_registry_json
 from . import paths
 
 
-@contextlib.contextmanager
 def _registry_lock(lock_path: Path):
-    """``container/registry.json.lock`` 에 대한 배타 flock. worktree_registry 의
-    ``_registry_lock`` 과 동일한 패턴이되 경로를 인자로 받는다(전역 lock 과 분리)."""
-    lock_path.parent.mkdir(parents=True, exist_ok=True)
-    if not lock_path.exists():
-        lock_path.touch()
-    f = lock_path.open("r+")
-    try:
-        fcntl.flock(f.fileno(), fcntl.LOCK_EX)
-        yield
-    finally:
-        f.close()
+    """``container/registry.json.lock`` 에 대한 배타 flock."""
+    return registry_lock(lock_path)
 
 
 def _load(registry_path: Path) -> dict:
-    if not registry_path.exists():
-        return {"services": {}}
-    try:
-        data = json.loads(registry_path.read_text())
-    except (OSError, json.JSONDecodeError):
-        return {"services": {}}
+    data = load_registry_json(registry_path, lambda: {"services": {}})
     data.setdefault("services", {})
     return data
 
 
 def _save(registry_path: Path, data: dict) -> None:
-    registry_path.parent.mkdir(parents=True, exist_ok=True)
-    tmp = registry_path.with_suffix(".json.tmp")
-    tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
-    os.replace(tmp, registry_path)
+    save_registry_json(registry_path, data)
 
 
 def reserve(

package/runtime/python/okstra_ctl/json_registry.py

@@ -0,0 +1,43 @@
+"""Shared flock + atomic JSON persistence for small okstra registries."""
+from __future__ import annotations
+
+import contextlib
+import fcntl
+import json
+import os
+from collections.abc import Callable, Iterator
+from pathlib import Path
+
+
+@contextlib.contextmanager
+def registry_lock(lock_path: Path) -> Iterator[None]:
+    """Hold an exclusive flock on ``lock_path``."""
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    if not lock_path.exists():
+        lock_path.touch()
+    handle = lock_path.open("r+")
+    try:
+        fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+        yield
+    finally:
+        fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+        handle.close()
+
+
+def load_registry_json(path: Path, default_factory: Callable[[], dict]) -> dict:
+    """Load a registry dict, or a fresh default when absent/corrupt."""
+    if not path.exists():
+        return default_factory()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return default_factory()
+    return data if isinstance(data, dict) else default_factory()
+
+
+def save_registry_json(path: Path, data: dict) -> None:
+    """Persist registry JSON via temp file + ``os.replace``."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    os.replace(tmp, path)

package/runtime/python/okstra_ctl/manager_launch.py

@@ -4,17 +4,22 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Mapping
 
-from okstra_ctl.jsonl import read_jsonl
+from okstra_ctl.jsonl import append_jsonl, read_jsonl
 
 from .manager_paths import (
     child_context_path,
     children_json_path,
     directives_jsonl_path,
+    events_jsonl_path,
     projects_json_path,
     snapshots_json_path,
     task_manifest_path,
 )
-from .manager_store import ManagerError, _now_iso, _read_json, _read_json_default
+from .manager_store import ManagerError, _now_iso, _read_json, _read_json_default, _write_json
+
+
+WORKER_DISPATCH_BACKEND = "subagent"
+LAUNCH_STATUS_PREPARED = "prepared"
 
 
 def select_child_lead_backend(env: Mapping[str, str]) -> str:
@@ -135,6 +140,47 @@ def _render_context(
     return "\n".join(lines)
 
 
+def _record_launch_prepared(
+    *,
+    home: Path,
+    manager_id: str,
+    task_group: str,
+    task_id: str,
+    children: dict,
+    child: dict,
+    packet: dict,
+    created_at: str,
+) -> None:
+    launch = child.get("launch")
+    if not isinstance(launch, dict):
+        launch = {}
+    launch.update(
+        {
+            "status": LAUNCH_STATUS_PREPARED,
+            "childLeadBackend": packet["backend"],
+            "workerDispatchBackend": WORKER_DISPATCH_BACKEND,
+            "taskKey": packet["taskKey"],
+            "contextPath": packet["contextPath"],
+            "preparedAt": created_at,
+        }
+    )
+    child["launch"] = launch
+    _write_json(children_json_path(home, manager_id, task_group, task_id), children)
+    append_jsonl(
+        events_jsonl_path(home, manager_id, task_group, task_id),
+        {
+            "event": "child-launch-prepared",
+            "createdAt": created_at,
+            "projectId": packet["projectId"],
+            "taskKey": packet["taskKey"],
+            "backend": packet["backend"],
+            "workerDispatchBackend": WORKER_DISPATCH_BACKEND,
+            "contextPath": packet["contextPath"],
+            "runArgs": packet["runArgs"],
+        },
+    )
+
+
 def build_launch_packet(
     home: Path,
     manager_id: str,
@@ -159,6 +205,7 @@ def build_launch_packet(
     _validate_child_task_key(child, target_task_key)
     project_root = _validated_project_root(project)
     backend = select_child_lead_backend(env or {})
+    created_at = now or _now_iso()
     context_path = child_context_path(home, manager_id, task_group, task_id, project_id, child_task_id_value)
     context_path.parent.mkdir(parents=True, exist_ok=True)
     context_path.write_text(
@@ -171,14 +218,14 @@ def build_launch_packet(
         ),
         encoding="utf-8",
     )
-    return {
+    packet = {
         "managerId": manager_id,
         "taskGroup": task_group,
         "taskId": task_id,
         "projectId": project_id,
         "taskKey": target_task_key,
         "backend": backend,
-        "workerDispatchBackend": "subagent",
+        "workerDispatchBackend": WORKER_DISPATCH_BACKEND,
         "projectRoot": project_root,
         "contextPath": str(context_path),
         "runArgs": [
@@ -194,5 +241,16 @@ def build_launch_packet(
             "--directive",
             f"Read manager child context: {context_path}",
         ],
-        "createdAt": now or _now_iso(),
+        "createdAt": created_at,
     }
+    _record_launch_prepared(
+        home=home,
+        manager_id=manager_id,
+        task_group=task_group,
+        task_id=task_id,
+        children=children,
+        child=child,
+        packet=packet,
+        created_at=created_at,
+    )
+    return packet

package/runtime/python/okstra_ctl/manager_paths.py

@@ -1,6 +1,7 @@
 """Pure path computation for okstra manager state."""
 from __future__ import annotations
 
+import hashlib
 from pathlib import Path
 import os
 
@@ -21,9 +22,11 @@ def _require_id(value: str, label: str) -> str:
 
 
 def _slug_segment(value: str, label: str) -> str:
-    segment = slugify(_require_id(value, label))
+    cleaned = _require_id(value, label)
+    segment = slugify(cleaned)
     if not segment:
-        raise ManagerPathError(f"{label} must contain at least one ASCII alphanumeric character")
+        digest = hashlib.sha1(cleaned.encode("utf-8")).hexdigest()[:12]
+        return f"u-{digest}"
     return segment
 
 
@@ -93,6 +96,6 @@ def child_context_path(
     project_id: str,
     child_task_id: str,
 ) -> Path:
-    safe_project = slugify(_require_id(project_id, "project-id"))
-    safe_task = slugify(_require_id(child_task_id, "task-id"))
+    safe_project = _slug_segment(project_id, "project-id")
+    safe_task = _slug_segment(child_task_id, "task-id")
     return task_root(home, manager_id, task_group, task_id) / "child-context" / f"{safe_project}-{safe_task}.md"

package/runtime/python/okstra_ctl/manager_store.py

@@ -126,9 +126,11 @@ def link_project(
     role: str,
     tags: list[str],
     now: str | None = None,
-) -> dict:
+    ) -> dict:
     load_manager(home, manager_id)
     root = Path(project_root).resolve()
+    if not root.is_dir():
+        raise ManagerError(f"projectRoot is not a directory: {root}")
     project_json = project_json_path(root)
     if project_json.is_file():
         try:

package/runtime/python/okstra_ctl/manager_sync.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 
 from pathlib import Path
 
-from okstra_project import TASKS_RELATIVE, parse_task_key, read_task_catalog, read_task_manifest, slugify
+from okstra_project import TASKS_RELATIVE, StateError, parse_task_key, read_task_catalog, read_task_manifest, slugify
 
 from .manager_paths import children_json_path, projects_json_path, snapshots_json_path, task_manifest_path
 from .manager_store import _now_iso, _read_json, _read_json_default, _write_json
@@ -52,9 +52,9 @@ def _resolve_task_root_read_only(project_root: Path, task_key: str) -> Path | No
     return None
 
 
-def _snapshot_child(project_root: Path, child: dict) -> dict:
+def _base_child_snapshot(child: dict) -> dict:
     task_key = str(child.get("taskKey") or "")
-    base = {
+    return {
         "projectId": str(child.get("projectId") or ""),
         "taskGroup": str(child.get("taskGroup") or ""),
         "taskId": str(child.get("taskId") or ""),
@@ -62,10 +62,18 @@ def _snapshot_child(project_root: Path, child: dict) -> dict:
         "exists": False,
         "taskRoot": "",
     }
-    task_dir = _resolve_task_root_read_only(project_root, task_key)
-    if task_dir is None:
-        return base
-    manifest = read_task_manifest(task_dir) or {}
+
+
+def _snapshot_child(project_root: Path, child: dict) -> dict:
+    base = _base_child_snapshot(child)
+    task_key = base["taskKey"]
+    try:
+        task_dir = _resolve_task_root_read_only(project_root, task_key)
+        if task_dir is None:
+            return base
+        manifest = read_task_manifest(task_dir) or {}
+    except StateError as exc:
+        return {**base, "error": str(exc)}
     workflow = _workflow(manifest)
     outcome = _phase_outcome(manifest)
     return {

package/runtime/python/okstra_ctl/worktree_registry.py

@@ -23,10 +23,6 @@ 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
@@ -34,6 +30,8 @@ from typing import Optional
 
 from okstra_project.dirs import okstra_home
 
+from .json_registry import load_registry_json, registry_lock, save_registry_json
+
 
 REGISTRY_FILENAME = "registry.json"
 LOCK_FILENAME = "registry.lock"
@@ -77,23 +75,9 @@ class WorktreeEntry:
     stages: Optional[list] = None
 
 
-@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()
+    """Exclusive flock on `<worktrees>/registry.lock`."""
+    return registry_lock(_okstra_worktrees_dir() / LOCK_FILENAME)
 
 
 def _registry_path() -> Path:
@@ -101,24 +85,14 @@ def _registry_path() -> Path:
 
 
 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 = load_registry_json(_registry_path(), lambda: {"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)
+    save_registry_json(_registry_path(), data)
 
 
 def lookup(