okstra 0.13.0 → 0.13.2

package/README.kr.md

@@ -165,7 +165,7 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 
 0.8.0 이후 `main` 에 추가된 workflow 변경:
 
-- **`--task-type implementation` 격리 worktree 자동 provisioning** — prepare 단계에서 `okstra-ctl` 이 `git worktree add ~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>-<run-seq>` 를 수행해 격리된 working tree 와 브랜치 `<work-category-prefix>-<task-id-segment>-<run-seq>` (예: `feat-dev-9436-001`, `fix-dev-7311-002`) 를 만듭니다. base ref 는 prepare 시점의 `HEAD`. Executor 와 verifier 모두 이 worktree 안에서 동작하므로 caller 의 작업 디렉터리는 깨끗하게 유지되고, worktree 는 PR 작성 · rollback 검증의 권위 artefact 로 남습니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 됩니다. 수동 cleanup: `git worktree remove <path>` → `git branch -D <branch>`. 상세: [`docs/kr/architecture.md`](docs/kr/architecture.md) *Task type* 섹션, [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
+- **`--task-type implementation` 격리 worktree 자동 provisioning** — prepare 단계에서 `okstra-ctl` 이 `git worktree add ~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>-<run-seq>` 를 수행해 격리된 working tree 와 브랜치 `<work-category-prefix>-<task-id-segment>-<run-seq>` (예: `feat-dev-9436-001`, `fix-dev-7311-002`) 를 만듭니다. base ref 는 사용자가 `--base-ref` 로 지정 (release-handoff PR base picker 와 동일한 메뉴: `main` / `dev` / `staging` / `preprod` / `prod` / 직접 입력). 첫 phase 에서는 필수이며, okstra-run skill 이 `AskUserQuestion` 으로 수집합니다 — 비대화형 호출자는 `--base-ref` 플래그를 직접 전달해야 prepare 가 통과합니다. Executor 와 verifier 모두 이 worktree 안에서 동작하므로 caller 의 작업 디렉터리는 깨끗하게 유지되고, worktree 는 PR 작성 · rollback 검증의 권위 artefact 로 남습니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 됩니다. 수동 cleanup: `git worktree remove <path>` → `git branch -D <branch>`. 상세: [`docs/kr/architecture.md`](docs/kr/architecture.md) *Task type* 섹션, [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
 - **`release-handoff` lifecycle phase** — `final-verification` 이 `verdict=accepted` 를 반환한 직후에 실행되는 신규 phase. lead 가 Claude worker (drafter) 를 통해 commit message · PR body 후보를 만들고, `AskUserQuestion` 으로 사용자에게 (1) action (`commit only` / `commit + PR` / `skip`), (2) PR base branch (`staging` / `preprod` / `prod` / `main` / `dev` / 직접 입력), (3) message handling (`use as-is` / `edit then proceed` / `cancel`) 세 가지를 순서대로 묻습니다. 사용자가 메뉴로 선택한 git / gh 명령만 실행되고, force-push, base 브랜치 직접 push, hook bypass (`--no-verify`), release publish (`gh release`, `npm publish`, ...) 는 금지됩니다. 이 phase 에서는 소스 코드를 수정하지 않습니다. profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
 
 ### 3.5 운영 명령

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 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).
+- **Isolated task worktree for every task-type** — prepare automatically runs `git worktree add ~/.okstra/worktrees/<project>/<group>/<task>/` on a fresh branch `<work-category-prefix>-<task-id-segment>` branched from the **user-chosen base ref** (`--base-ref`, mirroring the `release-handoff` PR-base picker: `main` / `dev` / `staging` / `preprod` / `prod` / any local ref) the first time a task-key is seen. `--base-ref` is required on first phase; the okstra-run skill collects it via `AskUserQuestion`, non-interactive callers must pass the flag explicitly. Every subsequent phase of the same task-key (`requirements-discovery` → `error-analysis` → `implementation-planning` → `implementation`) 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

@@ -286,11 +286,14 @@ Claude launch prompt 본문은 항상 `prompts/launch.template.md` 템플릿에
   "projectId": "sample-project-v2-api",
   "projectRoot": "/Volumes/Workspaces/workspace/projects/sample-project",
   "createdAt": "2026-05-10T00:00:00Z",
-  "updatedAt": "2026-05-10T00:00:00Z"
+  "updatedAt": "2026-05-10T00:00:00Z",
+  "worktreeSyncDirs": [".project-docs", ".scratch", "graphify-out", ".claude"]
 }
 ```
 
-처음 실행이면 위 4-필드를 새로 작성합니다. 이미 존재하면 `--project-id` 인자값과 저장된 `projectId` 가 일치하는지 검증한 뒤 `projectRoot`/`updatedAt` 만 갱신합니다. 불일치 시 즉시 종료해 동일 디렉토리에서 두 개의 ID 가 혼용되는 것을 막습니다.
+처음 실행이면 위 4-필드(`projectId`, `projectRoot`, `createdAt`, `updatedAt`)를 새로 작성합니다. 이미 존재하면 `--project-id` 인자값과 저장된 `projectId` 가 일치하는지 검증한 뒤 `projectRoot`/`updatedAt` 만 갱신하고, 사용자가 추가한 알 수 없는 필드(`worktreeSyncDirs`, 향후 `mcpServers` 등)는 upsert 과정에서 보존됩니다. 불일치 시 즉시 종료해 동일 디렉토리에서 두 개의 ID 가 혼용되는 것을 막습니다.
+
+`worktreeSyncDirs` (선택) 는 task worktree 로 symlink 할 project-root-relative 디렉토리 목록을 per-project 로 override 합니다. 해석 우선순위는 `OKSTRA_WORKTREE_SYNC_DIRS` 환경변수 → `project.json` → built-in default (`.project-docs`, `.scratch`, `graphify-out`, `.claude`). 빈 배열을 지정하면 sync 자체를 비활성화합니다.
 
 `okstra-ctl` 의 reindex/backfill 도 신규 모델에서 권위 소스를 변경했습니다. 과거에는 `examples/projects/*.conf.sh` 를 source 했지만, 지금은 `~/.okstra/projects/<projectId>/meta.json` (record_start 가 위 project.json 정보를 mirror 한 결과) 을 스캔하여 (projectId, projectRoot) 매핑을 복원합니다. `OKSTRA_PROJECT_DEFINITION_DIR_OVERRIDE` 환경변수도 함께 폐기되었습니다.
 
@@ -321,7 +324,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는 여전히 금지됩니다.
-- **모든 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)* 섹션 참고.
+- **모든 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/`, `.claude/` 는 main worktree 에서 symlink 로 연결되어 모든 task 가 동일한 shared state 를 봅니다 (sync 대상 목록은 `project.json` 의 `worktreeSyncDirs` 또는 `OKSTRA_WORKTREE_SYNC_DIRS` 환경변수로 override 가능; 빈 배열이면 sync 비활성화). 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

@@ -227,7 +227,7 @@ scripts/okstra.sh --task-type implementation-planning ... \
 ### `--workers`
 
 이번 run에서 사용할 worker 목록을 직접 지정합니다.
-생략하면 기본값 `claude,codex,gemini,report-writer`를 사용합니다.
+생략하면 기본값 `claude,codex,report-writer`를 사용합니다. Gemini worker는 옵션이며 필요할 때 `--workers claude,codex,gemini,report-writer` 와 같이 명시적으로 추가하세요.
 지정하면 전달한 worker subset만 dedupe 후 기록됩니다.
 
 예:
@@ -287,7 +287,7 @@ fallback 기본값은 아래와 같습니다.
 - Executor 는 이 run 에서 **유일하게 프로젝트 파일을 mutate 할 수 있는 worker** 입니다. 나머지 두 provider 는 같은 run 에서 strict read-only verifier 로 dispatch 됩니다.
 - 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 을 거치지 않습니다.
+- 실제 파일 변경은 Codex/Gemini 의 경우 각 CLI 의 auto-edit 모드 (예: `codex exec --sandbox workspace-write`) 를 통해 일어나며, Claude-side Edit/Write tool 을 거치지 않습니다.
 - **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.13.0",
+  "version": "0.13.2",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.13.0",
-  "builtAt": "2026-05-13T00:13:18.534Z",
+  "package": "0.13.2",
+  "builtAt": "2026-05-13T02:07:39.150Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -105,7 +105,7 @@ For `--task-type implementation` runs, the task bundle additionally pins one of
 
 Lead MUST dispatch Edit/Write-bearing work only through the `workerAgent` declared there. The other two providers still run as read-only verifiers in the same run; the executor's own provider is *also* dispatched separately as a verifier (a fresh CLI session) so the diff is reviewed by a context-isolated session. Session isolation is the primary self-review safeguard — same-model executor and same-provider verifier is acceptable when running in distinct sessions. Selecting a different model variant (e.g. executor=opus / Claude verifier=sonnet) is recommended but no longer mandatory.
 
-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 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 --sandbox workspace-write`), not through Claude-side Edit/Write tools.
 
 #### Task worktree (BLOCKING for every task-type)
 

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

@@ -32,7 +32,7 @@ $HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-mode
 
 The wrapper internally runs:
 ```bash
-codex exec -C "<project-root>" --model "<model>" --full-auto - < "<prompt-path>" 2>/dev/null
+codex exec -C "<project-root>" --model "<model>" --sandbox workspace-write - < "<prompt-path>" 2>/dev/null
 ```
 
 The wrapper exists because Claude Code's Bash permission matcher rejects simple-prefix matches when the command contains stdin/stderr redirects. Calling `codex exec ... - < <path> 2>/dev/null` directly triggers a permission prompt every dispatch even when `Bash(codex exec:*)` is allowlisted. The wrapper folds the redirects inside, so the harness sees a single non-redirect command that matches `Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)`.
@@ -71,7 +71,7 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
    ```bash
    $HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>"
    ```
-   Substitute the literal extracted Project Root, model execution value, and prompt-history path in place of the placeholders above. The wrapper handles `-C`, `--model`, `--full-auto`, the stdin redirect from the prompt file, and stderr suppression internally. Calling `codex exec` directly (without the wrapper) is an error in this skill: the redirect tokens disqualify the prefix match against `Bash(codex exec:*)` and produce a permission prompt every dispatch.
+   Substitute the literal extracted Project Root, model execution value, and prompt-history path in place of the placeholders above. The wrapper handles `-C`, `--model`, `--sandbox workspace-write`, the stdin redirect from the prompt file, and stderr suppression internally. Calling `codex exec` directly (without the wrapper) is an error in this skill: the redirect tokens disqualify the prefix match against `Bash(codex exec:*)` and produce a permission prompt every dispatch.
 
 8. Return the codex output as-is without modification.
 

package/runtime/bin/okstra-codex-exec.sh

@@ -50,4 +50,4 @@ fi
 
 # stdin redirect and stderr suppression are intentionally inside the wrapper —
 # this is the entire reason this script exists.
-exec codex exec -C "$project_root" --model "$model" --full-auto - < "$prompt_path" 2>/dev/null
+exec codex exec -C "$project_root" --model "$model" --sandbox workspace-write - < "$prompt_path" 2>/dev/null

package/runtime/bin/okstra.sh

@@ -119,6 +119,7 @@ PY_ARGS=(
 [[ "$APPROVE_PLAN_ACK" == "true" ]] && PY_ARGS+=(--approve)
 [[ -n "${CLARIFICATION_RESPONSE_PATH-}" ]] && PY_ARGS+=(--clarification-response "$CLARIFICATION_RESPONSE_PATH")
 [[ -n "${WORK_CATEGORY-}" ]] && PY_ARGS+=(--work-category "$WORK_CATEGORY")
+[[ -n "${BASE_REF-}" ]] && PY_ARGS+=(--base-ref "$BASE_REF")
 [[ "$RENDER_ONLY" == "true" ]] && PY_ARGS+=(--render-only)
 [[ "$REFRESH_OKSTRA_ASSETS" == "true" ]] && PY_ARGS+=(--refresh-assets)
 

package/runtime/prompts/profiles/implementation.md

@@ -4,8 +4,9 @@
 - Required workers:
   - claude
   - codex
-  - gemini
   - report-writer
+- Optional workers (opt-in via `--workers`):
+  - gemini — when added to the roster it joins the verifier set; when omitted only the Claude+Codex verifiers participate (`--executor gemini` is therefore not selectable without explicitly listing `gemini` in `--workers`)
 - **Executor binding (resolved at run-prep time, fixed for this run):**
   - Executor display name: `{{EXECUTOR_DISPLAY_NAME}}`
   - Executor provider: `{{EXECUTOR_PROVIDER}}` (one of: `claude` | `codex` | `gemini`; chosen via `--executor` or `OKSTRA_DEFAULT_EXECUTOR`, default `claude`)
@@ -13,12 +14,12 @@
   - Executor model: `{{EXECUTOR_MODEL_DISPLAY}}` (launch value: `{{EXECUTOR_MODEL_EXECUTION_VALUE}}`)
   - Wherever this profile mentions the `Executor`, it refers to the role bound above. The other two providers in the roster (`claude` / `codex` / `gemini` minus the executor) are dispatched as **verifiers only** for this run and remain strictly read-only.
 {{INCLUDE:_common-contract.md}}
-- Team contract (phase-specific overrides — `Claude worker` is replaced by `Executor` + verifier triad in this phase):
-  - **Executor role:** the `Executor` (bound above) is the **only worker permitted to use Edit / Write / state-mutating Bash commands** on project files. All other workers run read-only. When the executor provider is `codex` or `gemini`, the actual file mutation happens inside the executor CLI's own auto-edit mode (e.g. `codex exec --full-auto`, gemini's equivalent) — not through Claude-side Edit/Write tools — but the safety rules in this profile still apply identically.
-  - **Verifier roles:** the three verifier slots are `Claude verifier`, `Codex verifier`, and `Gemini verifier`. All three are dispatched regardless of which provider holds the executor role; the executor's own provider is run *separately* as a verifier (a fresh CLI session with no shared context) so that no verdict is produced from the same session that wrote the diff. Verifiers MUST NOT call Edit, Write, or any Bash command that mutates files outside the run's artifact directories. If a verifier wants a fix, it records the recommendation in its worker result; it does not apply the fix itself.
+- Team contract (phase-specific overrides — `Claude worker` is replaced by `Executor` + verifier set in this phase):
+  - **Executor role:** the `Executor` (bound above) is the **only worker permitted to use Edit / Write / state-mutating Bash commands** on project files. All other workers run read-only. When the executor provider is `codex` or `gemini`, the actual file mutation happens inside the executor CLI's own auto-edit mode (e.g. `codex exec --sandbox workspace-write`, gemini's equivalent) — not through Claude-side Edit/Write tools — but the safety rules in this profile still apply identically.
+  - **Verifier roles:** the verifier slots are `Claude verifier` and `Codex verifier`, plus `Gemini verifier` **only when `gemini` is in the resolved `--workers` roster**. Every verifier in the resolved roster is dispatched regardless of which provider holds the executor role; the executor's own provider is run *separately* as a verifier (a fresh CLI session with no shared context) so that no verdict is produced from the same session that wrote the diff. Verifiers MUST NOT call Edit, Write, or any Bash command that mutates files outside the run's artifact directories. If a verifier wants a fix, it records the recommendation in its worker result; it does not apply the fix itself.
   - Session isolation — not model-variant divergence — is the primary self-review safeguard: each verifier is a separate CLI invocation with its own context window, so reusing the same model variant for executor and same-provider verifier is acceptable. Different model variants (e.g. executor=opus / Claude verifier=sonnet) remain recommended when available.
-  - Phase-specific model defaults override the shared defaults: `Claude verifier`=`sonnet`, `Codex verifier`=`gpt-5.5`, `Gemini verifier`=`auto`. The `Executor`'s model is taken from the provider-specific worker model corresponding to `--executor`: claude→`--claude-model` (default `sonnet`, override to `opus` recommended when this run's executor is claude), codex→`--codex-model` (default `gpt-5.5`), gemini→`--gemini-model` (default `auto`).
-  - **All-verifier-failure policy**: if every verifier (`Gemini verifier`, `Codex verifier`, `Claude verifier`) ends with a non-result terminal status (`timeout`, `error`, `not-run`) — i.e. zero independent verdicts were produced — the run MUST end with status `blocked` and route to a follow-up `error-analysis` run. `Claude lead` MUST NOT substitute its own verdict in place of the missing verifier outputs; synthesis requires at least one independent verifier's verdict. If one or two verifiers fail but at least one returns a verdict, the run proceeds with the surviving verdict(s) and the final report MUST explicitly notate which verifiers were unavailable, with the captured error / timeout evidence per failed verifier.
+  - Phase-specific model defaults override the shared defaults: `Claude verifier`=`sonnet`, `Codex verifier`=`gpt-5.5`, `Gemini verifier`=`auto` (only when present in the roster). The `Executor`'s model is taken from the provider-specific worker model corresponding to `--executor`: claude→`--claude-model` (default `sonnet`, override to `opus` recommended when this run's executor is claude), codex→`--codex-model` (default `gpt-5.5`), gemini→`--gemini-model` (default `auto`).
+  - **All-verifier-failure policy**: if every verifier present in the resolved roster (`Claude verifier`, `Codex verifier`, and `Gemini verifier` when opted in) ends with a non-result terminal status (`timeout`, `error`, `not-run`) — i.e. zero independent verdicts were produced — the run MUST end with status `blocked` and route to a follow-up `error-analysis` run. `Claude lead` MUST NOT substitute its own verdict in place of the missing verifier outputs; synthesis requires at least one independent verifier's verdict. If one or more verifiers fail but at least one returns a verdict, the run proceeds with the surviving verdict(s) and the final report MUST explicitly notate which verifiers were unavailable, with the captured error / timeout evidence per failed verifier.
 - Pre-implementation gate (mandatory — refuse to start if any item fails):
   - the run brief MUST cite `--approved-plan <path>` pointing to a `final-report.md` produced by a prior `implementation-planning` run located under `runs/implementation-planning/.../reports/final-report.md`
   - that file MUST contain a `User Approval Request` block (canonically placed at the **top of the report**, immediately under the metadata header) AND a recorded user approval marker. The canonical, recommended form is the single markdown checkbox line `- [x] Approved`. The runtime regex in `okstra_ctl.run._validate_approved_plan` also accepts (case-insensitive, line-anchored, optional leading `-`/`*`/`+` bullet): `APPROVED` (alone, followed by `:`, or end-of-line), `[x] Approved`, or `User Approval: APPROVED|granted|yes`. Free-form approvals such as "lgtm", "go ahead", or paraphrased confirmations are intentionally NOT accepted; if the user's approval is informal, re-edit the plan file to flip the top checkbox to `- [x] Approved` before invoking the implementation run.
@@ -34,7 +35,7 @@
   - 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` 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.
+  - **Verifier behaviour**: all verifier roles in the resolved roster 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) 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 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.
@@ -84,7 +85,7 @@
   - **Out-of-plan edits block**: every file edited that was not in the approved plan's file list, with rationale (empty block is acceptable and preferred)
   - **Validation evidence**: actual command output (stdout/stderr) for every `pre / mid / post` validation command from the plan. Truncated output is acceptable but the command line and exit code MUST be exact. No paraphrasing of test results.
   - **TDD evidence (when applicable)**: for steps that should be TDD-ordered, show the failing-test output BEFORE the implementation commit and the passing-test output AFTER, with commit SHAs framing the transition.
-  - **Verifier results**: a section per verifier (`Gemini verifier`, `Codex verifier`, `Claude verifier`) containing their independent verdict (PASS / CONCERNS / FAIL), their cited diff snippets, and any fix recommendations they declined to apply. `Claude lead` synthesises a unified verdict but MUST preserve dissent — do not collapse three opinions into one paragraph.
+  - **Verifier results**: a section per verifier present in the resolved roster (`Claude verifier`, `Codex verifier`, and `Gemini verifier` when opted in) containing their independent verdict (PASS / CONCERNS / FAIL), their cited diff snippets, and any fix recommendations they declined to apply. `Claude lead` synthesises a unified verdict but MUST preserve dissent — do not collapse opinions into one paragraph.
   - **Rollback verification**: confirmation that the plan's rollback path is still valid after the changes. Strength of verification depends on the change category:
     - **Pure code changes** (no persisted state, no infra mutation): a reachable revert SHA is sufficient. Record the exact `git revert <SHA>` command that would undo the change, and confirm `git rev-parse <SHA>` resolves.
     - **Feature-flag-gated changes**: confirm the off-switch path was exercised in this run's validation evidence (i.e. one of the validation commands ran with the flag off and succeeded). A plan that ships a flag without exercising the off-path does NOT satisfy this requirement.
@@ -95,7 +96,7 @@
   1. **Plan coverage** — every step in the approved plan's recommended option must point to a commit (or an explicit `Skipped: <reason>` entry). List gaps.
   2. **Evidence completeness** — every `Validation evidence` and `TDD evidence` claim has the actual command line and exit code? No paraphrased "tests pass" without output?
   3. **Out-of-plan honesty** — files in the diff that are NOT in the plan list must appear in the `Out-of-plan edits` block. Cross-check with `git diff --name-only`.
-  4. **Verifier dissent preserved** — if the three verifiers disagree, the disagreement is visible in the report? Synthesis hides nothing?
+  4. **Verifier dissent preserved** — if the verifiers in the resolved roster disagree, the disagreement is visible in the report? Synthesis hides nothing?
   5. **Forbidden action audit** — `git push`, publish, deploy, migration, third-party write commands: scan the run's session transcripts for any occurrence and confirm none happened.
   6. **Placeholder scan** — restrict the scan to lines this run actually introduced; pre-existing placeholders in unchanged regions of touched files are out of scope. Required command (substitute `<base>` with the parent of the first commit in this run's commit list):
      ```

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

@@ -144,6 +144,10 @@ while [[ $# -gt 0 ]]; do
       WORK_CATEGORY="$(require_option_value --work-category "${2-}")"
       shift 2
       ;;
+    --base-ref)
+      BASE_REF="$(require_option_value --base-ref "${2-}")"
+      shift 2
+      ;;
     --task-type)
       ANALYSIS_TYPE="$(require_option_value --task-type "${2-}")"
       shift 2

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

@@ -26,6 +26,7 @@ GEMINI_MODEL_OVERRIDE=""
 REPORT_WRITER_MODEL_OVERRIDE=""
 EXECUTOR_OVERRIDE=""
 WORK_CATEGORY=""
+BASE_REF=""
 RELATED_TASKS_RAW=""
 ANALYSIS_TYPE=""
 BRIEF_PATH=""
@@ -150,7 +151,7 @@ GEMINI_WORKER_MODEL_DISPLAY=""
 GEMINI_WORKER_MODEL_EXECUTION_VALUE=""
 REPORT_WRITER_MODEL_DISPLAY=""
 REPORT_WRITER_MODEL_EXECUTION_VALUE=""
-DEFAULT_WORKERS="claude,codex,gemini,report-writer"
+DEFAULT_WORKERS="claude,codex,report-writer"
 DEFAULT_LEAD_MODEL_NAME="${OKSTRA_DEFAULT_LEAD_MODEL:-opus}"
 DEFAULT_CLAUDE_WORKER_MODEL_NAME="${OKSTRA_DEFAULT_CLAUDE_MODEL:-sonnet}"
 DEFAULT_CODEX_WORKER_MODEL_NAME="${OKSTRA_DEFAULT_CODEX_MODEL:-gpt-5.5}"

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

@@ -65,7 +65,8 @@ options:
   --refresh-assets    Deprecated. okstra now installs skills/agents into ~/.claude and the codex
                       wrapper into ~/.okstra/bin via scripts/okstra-install.sh. Re-run that
                       installer with --refresh to update installed assets.
-  --workers            Comma-separated worker list for this run. Default: claude,codex,gemini,report-writer
+  --workers            Comma-separated worker list for this run. Default: claude,codex,report-writer
+                      (Gemini worker is optional; add `gemini` explicitly, e.g. --workers claude,codex,gemini,report-writer)
   --lead-model         Model for Claude lead. Default: OKSTRA_DEFAULT_LEAD_MODEL or opus
   --claude-model       Model for Claude worker. Default: OKSTRA_DEFAULT_CLAUDE_MODEL or sonnet
   --codex-model        Model for Codex worker. Default: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.5
@@ -83,6 +84,12 @@ options:
                        Defaults to 'unknown' when omitted. Use this when the
                        lifecycle skipped --task-type=requirements-discovery
                        (where work-category would otherwise be inferred).
+  --base-ref           Git ref (branch name, tag, or commit SHA) used as the
+                       base of the per-task worktree on the FIRST phase of a
+                       task-key. Required on first phase; ignored on
+                       subsequent phases (the registered worktree is reused).
+                       Typical values mirror the release-handoff PR-base picker:
+                       main | dev | staging | preprod | prod | any local ref.
   --task-type          Set the task purpose for this run and select the matching profile file.
   -h, --help           Show this help.
 

package/runtime/python/okstra_ctl/run.py

@@ -90,6 +90,7 @@ class PrepareInputs:
     executor: str = ""
     related_tasks_raw: str = ""
     work_category: str = ""
+    base_ref: str = ""
     approved_plan_path: str = ""
     clarification_response_path: str = ""  # absolute or empty
     render_only: bool = False
@@ -504,6 +505,15 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         raise PrepareError(
             f"--executor must be one of: claude, codex, gemini (got: {executor_provider!r})"
         )
+    if (
+        inp.task_type == "implementation"
+        and executor_provider not in workers
+    ):
+        raise PrepareError(
+            f"--executor {executor_provider} requires {executor_provider!r} in "
+            f"--workers, but resolved roster is {workers!r}. "
+            f"Add it explicitly, e.g. --workers {','.join(sorted(set(workers + [executor_provider])))}."
+        )
     executor_provider_to_meta = {
         "claude": ("Claude executor", "claude-worker", cw),
         "codex": ("Codex executor", "codex-worker", co),
@@ -537,6 +547,8 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
             task_group_segment=ctx["TASK_GROUP_SEGMENT"],
             task_id_segment=ctx["TASK_ID_SEGMENT"],
             work_category=inp.work_category,
+            base_ref=inp.base_ref,
+            require_base_ref=True,
         )
     except RuntimeError as exc:
         raise PrepareError(f"task worktree provisioning failed: {exc}") from exc
@@ -818,6 +830,19 @@ def main(argv: list[str]) -> int:
             "Falls back to `unknown` when omitted."
         ),
     )
+    p.add_argument(
+        "--base-ref",
+        default="",
+        dest="base_ref",
+        help=(
+            "Git ref (branch name, tag, or commit SHA) used as the base of "
+            "the task worktree on the first phase of this task-key. "
+            "Required for first-phase prepare; ignored on subsequent phases "
+            "(the registered worktree is reused). Mirrors the PR-base picker "
+            "used by the `release-handoff` phase: typical values are "
+            "`main` / `dev` / `staging` / `preprod` / `prod` or any local ref."
+        ),
+    )
     args = p.parse_args(argv)
 
     project_root = Path(args.project_root).expanduser().resolve()
@@ -854,6 +879,7 @@ def main(argv: list[str]) -> int:
         executor=args.executor,
         related_tasks_raw=args.related_tasks_raw,
         work_category=args.work_category,
+        base_ref=args.base_ref,
         approved_plan_path=args.approved_plan_path,
         clarification_response_path=clarification_abs,
         render_only=args.render_only,

package/runtime/python/okstra_ctl/worktree.py

@@ -161,6 +161,17 @@ def _head_sha(cwd: Path) -> str:
     return res.stdout.strip()
 
 
+def _resolve_commit_sha(cwd: Path, ref: str) -> str:
+    """Resolve a user-supplied ref (branch, tag, short/long SHA) to a full
+    commit SHA in `cwd`. Returns empty string when the ref is not resolvable
+    so the caller can raise a contextual error.
+    """
+    res = _git(cwd, "rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}")
+    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).
 
@@ -292,6 +303,8 @@ def provision_task_worktree(
     task_group_segment: str,
     task_id_segment: str,
     work_category: str,
+    base_ref: str = "",
+    require_base_ref: bool = False,
 ) -> WorktreeProvision:
     """Materialise (or reuse) the task worktree for this run.
 
@@ -299,6 +312,13 @@ def provision_task_worktree(
     Subsequent phases of the same task-key look up the registry and
     return the existing path + branch unchanged.
 
+    ``base_ref`` is the ref (branch name, tag, or commit SHA) to branch
+    the new worktree from on first phase. When empty, the main worktree's
+    current ``HEAD`` is used (legacy default; the CLI enforces a
+    non-empty value on first phase so callers go through the
+    AskUserQuestion menu in the okstra-run skill). Subsequent phases
+    ignore ``base_ref`` — the registered entry's base is reused.
+
     Raises:
         RuntimeError when worktree creation fails (path clash on disk
         that the registry does not know about, branch clash with a
@@ -369,16 +389,34 @@ def provision_task_worktree(
         )
 
     main_root = _main_worktree_path(project_root)
-    base_ref = _head_sha(main_root)
-    if not base_ref:
+    requested_base = (base_ref or "").strip()
+    if not requested_base and require_base_ref:
         raise RuntimeError(
-            "could not resolve HEAD sha in main worktree; cannot create task worktree"
+            "first-phase task worktree requires an explicit base ref; "
+            "pass `--base-ref <branch|tag|sha>` (or invoke through the "
+            "okstra-run skill which collects this interactively)"
         )
+    if requested_base:
+        resolved_sha = _resolve_commit_sha(main_root, requested_base)
+        if not resolved_sha:
+            raise RuntimeError(
+                f"could not resolve base ref `{requested_base}` in main worktree "
+                f"({main_root}); ensure the branch/tag/SHA exists locally"
+            )
+        resolved_base_ref = resolved_sha
+        base_origin = requested_base
+    else:
+        resolved_base_ref = _head_sha(main_root)
+        if not resolved_base_ref:
+            raise RuntimeError(
+                "could not resolve HEAD sha in main worktree; cannot create task worktree"
+            )
+        base_origin = "HEAD"
 
     worktree_path.parent.mkdir(parents=True, exist_ok=True)
     res = _git(
         main_root,
-        "worktree", "add", "-b", branch, str(worktree_path), base_ref,
+        "worktree", "add", "-b", branch, str(worktree_path), resolved_base_ref,
     )
     if res.returncode != 0:
         raise RuntimeError(
@@ -398,7 +436,7 @@ def provision_task_worktree(
             task_id=safe_task,
             worktree_path=str(worktree_path),
             branch=branch,
-            base_ref=base_ref,
+            base_ref=resolved_base_ref,
             phase=task_type,
         )
     except RuntimeError:
@@ -408,13 +446,18 @@ def provision_task_worktree(
         _git(main_root, "branch", "-D", branch)
         raise
 
+    base_label = (
+        f"{base_origin} @ {resolved_base_ref[:12]}"
+        if base_origin != "HEAD"
+        else f"HEAD @ {resolved_base_ref[:12]}"
+    )
     return WorktreeProvision(
         status="created",
         path=str(worktree_path),
         branch=branch,
-        base_ref=base_ref,
+        base_ref=resolved_base_ref,
         note=(
             f"task worktree created at {worktree_path} on branch {branch} "
-            f"(base {base_ref[:12]}; phase {task_type}){linked_suffix}"
+            f"(base {base_label}; phase {task_type}){linked_suffix}"
         ),
     )

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

@@ -141,6 +141,58 @@ If `implementation` chosen, ask two more `AskUserQuestion` in order:
 - `"Path to the approved final-report.md (must contain APPROVED marker)"` — the underlying python `prepare_task_bundle` re-validates the marker, but you can pre-check with `grep`.
 - `"Executor provider for this run (claude | codex | gemini)?"` — only this provider mutates project files; the other two run as read-only verifiers. Default `claude` (or `OKSTRA_DEFAULT_EXECUTOR` if set). Pass the answer through `PrepareInputs.executor`.
 
+## Step 4.6: Base ref for the task worktree (first phase only)
+
+`okstra prepare` provisions a per-task git worktree on first phase of a task-key
+and reuses it on every subsequent phase. The base ref of that worktree is the
+**user's choice**, not the caller's current `HEAD`, so the worktree never
+silently inherits an unrelated branch you happen to be checked out on.
+
+First, decide whether to ask:
+
+```bash
+python3 - <<PY
+import sys
+from pathlib import Path
+sys.path.insert(0, "$OKSTRA_PYTHONPATH".split(":")[0])
+from okstra_ctl import worktree_registry
+from okstra_ctl.ids import _safe_fs_segment
+entry = worktree_registry.lookup(
+    _safe_fs_segment("<project-id>"),
+    _safe_fs_segment("<task-group>"),
+    _safe_fs_segment("<task-id>"),
+)
+print("REUSE" if (entry and entry.status == "active") else "ASK")
+PY
+```
+
+- `REUSE` → the registered worktree is reused; set `base_ref=""` and skip the
+  question (the registered base is authoritative).
+- `ASK` → this is the first phase for this task-key. Continue.
+
+`AskUserQuestion` (mirrors the `release-handoff` PR-base picker):
+
+- **Label**: `"이 task worktree 의 base branch?"`
+- **Options** (single-select):
+  1. `main` (recommended)
+  2. `dev`
+  3. `staging`
+  4. `preprod`
+  5. `prod`
+  6. Free text — let the user type any local ref (branch, tag, or full/short SHA).
+
+Validate the chosen ref exists in the MAIN worktree before continuing:
+
+```bash
+git -C "$(git -C "$PROJECT_ROOT" rev-parse --path-format=absolute --git-common-dir | xargs dirname)" \
+    rev-parse --verify --quiet "<chosen-ref>^{commit}" >/dev/null \
+  || { echo "ref not found locally: <chosen-ref>"; exit 1; }
+```
+
+Re-ask on failure. Echo the resolved short SHA back to the user
+(`base 확정: <ref> (<short-sha>)`) and capture `base_ref=<chosen-ref>` for
+Step 7.
+
 ## Step 5: Brief path
 
 - New task: `AskUserQuestion` (free text) `"Path to the task brief markdown (relative to project root)"`. Verify file exists; re-ask on failure.
@@ -169,7 +221,7 @@ Do NOT ask for `workers_override` in implementation — the profile's required r
 
 Ask each in turn (free text, blank = default):
 
-1. `"참여 워커 목록 (쉼표 구분, 빈 칸 = 프로필 기본값). 선택지: claude, codex, gemini, report-writer"` → `workers_override`
+1. `"참여 워커 목록 (쉼표 구분, 빈 칸 = 프로필 기본값 claude,codex,report-writer). 선택지: claude, codex, gemini, report-writer — gemini는 옵션이므로 필요할 때 명시"` → `workers_override`
 2. `"리더(Claude lead) 모델? (빈 칸 = 기본값)"` → `lead_model`
 3. `"claude 워커 모델? (빈 칸 = 기본값)"` → `claude_model`
 4. `"codex 워커 모델? (빈 칸 = 기본값)"` → `codex_model`
@@ -189,6 +241,7 @@ Before calling `prepare_task_bundle`, echo the resolved selections back to the u
 선택 확인:
   task-type     : implementation
   task-key      : <group>/<id>
+  base-ref      : main (resolved <short-sha>)   ← worktree base, first phase only
   executor      : codex
   workers       : (프로필 기본 — executor + verifier 2 + report-writer)
   lead-model    : default (opus)
@@ -231,6 +284,7 @@ out = prepare_task_bundle(PrepareInputs(
     gemini_model="...", report_writer_model="...",
     related_tasks_raw="...",
     executor="<claude|codex|gemini or empty>",  # implementation only; empty → default (claude / OKSTRA_DEFAULT_EXECUTOR)
+    base_ref="<chosen-ref-from-step-4.6 or empty when reusing existing worktree>",
     approved_plan_path="<approved-plan-or-empty>",
     clarification_response_path=str(clarification_abs) if clarification_abs else "",
     render_only=True,

package/runtime/templates/reports/final-report.template.md

@@ -333,15 +333,16 @@ Empty-state placeholder, copy verbatim when nothing else applies:
 규칙:
 
 - 각 row의 `Auto-spawn?` 값이 `yes` 이면 Phase 7 의 `scripts/okstra-spawn-followups.py` 가 자동으로 후속 task 디렉터리(`tasks/<TASK_GROUP>/<New Task ID>/`)와 `task-manifest.json` (status: `todo`), stub task-brief 를 생성합니다. `no` 이면 사람이 따로 결정합니다.
+- `Ticket ID` 는 본 보고서 상단 `Ticket Coverage` 규칙과 동일합니다. 후속 작업이 특정 외부 ticket(Jira/Linear/이슈 트래커 등)이나 본 보고서의 ticket 인덱스에 묶이면 그 키를 적고, 매핑이 없으면 `Task ID` 폴백 값을 prefix 없이 적습니다(예: `8852`). 어느 쪽으로도 식별 불가하면 `unknown`.
 - `New Task ID` 는 알파숫자·하이픈만 사용하는 짧은 slug 입니다 (예: `8852-followup-logs`). 같은 task-group 안에서 유일해야 합니다.
 - `Suggested task-type` 은 `requirements-discovery` / `error-analysis` / `implementation-planning` / `implementation` / `final-verification` / `release-handoff` 중 하나.
 - `Scope` 는 영향 파일·영역을 콤마 또는 한 줄로 적습니다.
 - `Reason / Why deferred` 는 본 run 에서 처리하지 못한 이유를 한 두 문장으로 적습니다. "시간이 없어서" 같은 모호한 사유는 거절됩니다.
 - 동일 follow-up 이 여러 run 에 걸쳐 등장하면 `New Task ID` 를 동일하게 유지하여 중복 spawn 을 방지합니다 (script 가 기존 디렉터리 존재 여부로 idempotent 처리).
 
-| ID | Origin | New Task ID | Title | Suggested task-type | Scope (files/areas) | Reason / Why deferred | Priority (P0/P1/P2) | Auto-spawn? |
-|----|--------|-------------|-------|---------------------|---------------------|------------------------|---------------------|-------------|
-| FU-001 | `<out-of-plan / verifier-concern / scope-boundary / open-question / manual>` | `<new-task-id-slug>` | <한 줄 제목> | `<task-type>` | `<files / areas>` | <한 두 문장 사유> | `P1` | `yes` |
+| ID | Ticket ID | Origin | New Task ID | Title | Suggested task-type | Scope (files/areas) | Reason / Why deferred | Priority (P0/P1/P2) | Auto-spawn? |
+|----|-----------|--------|-------------|-------|---------------------|---------------------|------------------------|---------------------|-------------|
+| FU-001 | `<TICKET-or-fallback>` | `<out-of-plan / verifier-concern / scope-boundary / open-question / manual>` | `<new-task-id-slug>` | <한 줄 제목> | `<task-type>` | `<files / areas>` | <한 두 문장 사유> | `P1` | `yes` |
 
 빈 상태 예시 (해당 없음):