okstra 0.8.0 → 0.10.0

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

@@ -0,0 +1,89 @@
+# Release Handoff Profile
+
+- Purpose: take an `accepted` final-verification verdict and turn it into a delivered commit and/or pull request, with explicit user selection at every mutating step
+- Required workers:
+  - claude
+  - report-writer
+{{INCLUDE:_common-contract.md}}
+- Team contract (phase-specific overrides):
+  - `Claude lead` is the **executor of every git / gh command** in this phase. Workers never call mutating git commands themselves.
+  - `Claude worker` (drafter) is read-only and produces **commit message candidate(s) and a PR body candidate** in markdown; the lead presents these to the user, accepts edits, and only then runs git.
+  - Codex / Gemini workers are NOT part of this profile's roster (see `Required workers:` above); the shared contract's `Gemini worker must always be attempted` clause does not apply to release-handoff.
+- Pre-handoff entry gate (mandatory — refuse to start if any item fails):
+  - the task brief MUST cite the originating `final-verification` final-report path under `## Source Verification Report`. The lead opens that file and confirms section `## 2. Final Verdict` contains exactly the token `accepted`.
+  - if the verdict is `conditional-accept`, `blocked`, or any other token (including ambiguous phrasing like "looks good"), the run MUST end immediately with status `blocked` and a routing recommendation back to `error-analysis` or `implementation-planning`. Do NOT prompt the user; do NOT run any git command.
+  - the lead MUST capture `git status --short` and confirm the working tree is clean OR contains only the files listed in the prior `implementation` run's `Out-of-plan edits` block. Unexpected dirty state aborts the run.
+  - the lead MUST capture `git rev-parse --abbrev-ref HEAD` and record it as the **feature branch**. If the current branch is itself `main`, `master`, `prod`, `preprod`, `staging`, or `dev`, the run MUST end immediately — release-handoff never operates on a base branch.
+- User interaction protocol (Claude lead — performed in order, using `AskUserQuestion` or the equivalent interactive prompt):
+  1. **Action selection** — present three choices and capture exactly one:
+     - `commit only` — stage and commit the working-tree changes locally; no push, no PR.
+     - `commit + PR` — commit, push the feature branch, then open a pull request.
+     - `skip` — record the verified state and end the run without any git command.
+     If the user picks `skip`, route directly to the final-report self-review pass.
+  2. **PR base branch** (only when the user picked `commit + PR`) — present six options and capture exactly one:
+     - `staging`
+     - `preprod`
+     - `prod`
+     - `main`
+     - `dev`
+     - `직접 입력` (free-form branch name; lead validates the name exists on origin via `git ls-remote --heads origin <name>` and re-asks on failure)
+     The chosen base MUST NOT equal the feature branch. If it does, re-ask.
+  3. **Commit message + PR body confirmation** — show the `Claude worker` drafter's output verbatim and capture one of:
+     - `use as-is` — proceed with the drafter's text.
+     - `edit then proceed` — accept inline edits from the user, then proceed with the edited text.
+     - `cancel` — end the run without executing any git command; record the cancellation in the final report.
+- Drafter worker contract (`Claude worker`):
+  - reads the run brief, the cited final-verification report, and `git diff <base>..HEAD --stat` to ground its output in actual changes.
+  - produces **two artifacts** in its worker result:
+    1. **Commit message candidate** — a single message in Conventional Commits style (`<type>(<scope>): <subject>` + optional body + optional footer). When `commit + PR` will be opened against a `release-please`-managed repo, the type MUST match a configured changelog section (`feat` / `fix` / `perf` / `revert` / `deps` / `docs` / `refactor` / `build` / `ci` / `chore` / `test`).
+    2. **PR body candidate** — markdown with sections `## Summary`, `## Changes`, `## Test plan`, `## Linked issues` (omit a section only if it is genuinely empty).
+  - is strictly **read-only**: MUST NOT run any git mutating command, MUST NOT call `gh pr create`, MUST NOT call `git push`.
+  - if the drafter cannot produce output (no diff exists, repo is bare, etc.), it returns terminal status `not-run` with a reason; the lead falls back to a manually-authored message captured directly from the user.
+- Allowed actions during the run (Claude lead only — workers stay read-only):
+  - read-only inspection: `git status`, `git status --short`, `git diff`, `git log`, `git rev-parse`, `git ls-remote --heads origin <name>`, `gh pr list --head <branch>`, `gh pr view <url>`.
+  - local commit: `git add -- <path>...` (prefer explicit file paths over `git add -A` / `git add .`), `git commit -m "<message>"`. Re-use the user-confirmed message exactly.
+  - feature-branch push (only when the user picked `commit + PR`): `git push -u origin <current-branch>`. The pushed ref MUST be the feature branch — never the chosen base branch.
+  - PR creation (only when the user picked `commit + PR` AND no PR with the same head already exists on origin): `gh pr create --base <chosen-base> --head <current-branch> --title "<title>" --body "<body>"`. The title is the commit message subject by default; the body is the user-confirmed PR body.
+  - PR reuse: if `gh pr list --head <branch> --state open --json url --jq '.[0].url'` returns a URL, treat that PR as already existing — record the URL in the final report and SKIP `gh pr create`.
+  - Idempotency: if `git diff --cached` and `git diff` are both empty (nothing to commit), record "no staged changes; commit skipped" in the final report and skip `git commit` while still proceeding to the PR step if requested.
+- Forbidden actions (any occurrence → terminal status `contract-violated`):
+  - any of the following git push variants, regardless of intent or whether the user said "force it":
+    - `git push --force`
+    - `git push --force-with-lease`
+    - `git push -f`
+    - `git push +<refspec>`
+    - any other invocation that rewrites remote history
+  - pushing directly to a base branch — i.e. `git push origin <branch>` where `<branch>` is `main`, `master`, `prod`, `preprod`, `staging`, `dev`, or the branch the user chose as the PR base in this run. The only permitted push target is the current feature branch.
+  - bypassing repo safeguards: `--no-verify` / `-n` on `git commit` or `git push`, disabling GPG signing via `-c commit.gpgsign=false` / `--no-gpg-sign`, or any equivalent flag-based hook bypass.
+  - release-publishing commands: `gh release create`, `gh release edit`, `npm publish`, `cargo publish`, `pip publish`, `twine upload`, `docker push`, `terraform apply`, `kubectl apply` against any non-local cluster.
+  - source-code edits, refactors, or any modification to files outside the run's own artifact directories (`reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/`). The diff being shipped MUST be exactly what the prior `implementation` run produced; release-handoff packages it, it does not re-author it.
+  - executing any mutating command the user did NOT select. Examples: opening a PR when the user picked `commit only`; running `git commit` when the user picked `skip`; switching the PR base branch silently after the user already chose one.
+  - retrying a failed git / gh command with weaker safety flags. If `git push` fails with non-fast-forward, the lead MUST stop, explain the failure to the user, and ask for instructions — it MUST NOT add `--force`.
+  - dispatching parallel sub-agents beyond the required worker roster.
+  - silently treating an unrecognised user reply as one of the menu options. If the user's answer does not match a presented choice, re-ask the question verbatim.
+- Required deliverable shape (final report, in addition to the standard sections):
+  - **Source Verification Report**: relative path of the originating `final-verification` final-report file plus the literal quoted `## 2. Final Verdict` line that read `accepted`.
+  - **Feature Branch & Working-Tree State**: branch name from `git rev-parse --abbrev-ref HEAD`, output of `git status --short` at run start.
+  - **User Selections**: a block recording each prompt and the user's verbatim answer.
+    - Q1 action: `commit only` | `commit + PR` | `skip`.
+    - Q2 PR base (if applicable): the chosen branch and how it was selected (menu pick vs free-form input).
+    - Q3 message/body: `use as-is` | `edit then proceed` (with a diff between the drafter's text and the final text) | `cancel`.
+  - **Executed Commands**: every git / gh command the lead actually ran, with its exit code and a one-line stdout/stderr summary. Read-only inspection commands MAY be summarised; mutating commands MUST be listed verbatim.
+  - **Commit List**: each commit SHA (short and full), its subject line, and the files it touched. If no commit was produced (idempotent no-op), state `- No commit was produced (working tree had no staged changes).`
+  - **Pull Request Outcome**: one of
+    - `- No PR action requested.` (user picked `commit only` or `skip`)
+    - `- PR created: <url>` with title and base branch
+    - `- PR reused: <url>` when an existing PR was found via `gh pr list`
+    - `- PR creation skipped: <reason>` for any user-driven cancellation
+  - **Routing recommendation**: explicit `done` token, since release-handoff is the terminal lifecycle phase. If the run ended in `skip` or `cancel`, the recommendation MUST also state whether re-entry into release-handoff is appropriate.
+- Self-review pass before finalising the report (`Claude lead` runs this; do not delegate to a generic subagent):
+  1. **Entry-gate audit** — section 2 cites the originating final-verification report path and the literal `accepted` verdict line. If either is missing, the run is invalid and MUST be re-routed to `final-verification`.
+  2. **User-selection traceability** — every executed mutating command maps to a user selection captured in the report. Any mutating command without a corresponding user answer is a contract violation.
+  3. **Forbidden-action audit** — scan the run's session transcripts (`git`, `gh` invocations) for every entry in the Forbidden actions list above. Any occurrence means the run has crossed into unsafe territory and MUST be flagged as `contract-violated`.
+  4. **Push-target audit** — for every `git push` recorded, confirm the refspec resolves to the feature branch, not the base branch.
+  5. **Idempotency check** — if a PR with the same head already existed at run start, confirm the report records `PR reused` rather than a fresh `gh pr create` invocation.
+- Non-goals:
+  - re-litigating the final-verification verdict — release-handoff trusts the cited `accepted` verdict and does not reopen acceptance checks.
+  - opening additional PRs, releases, or deployments beyond the single PR the user chose to create.
+  - merging the PR. Merging is a separate, manual step performed by the user (or by repo automation) after release-handoff ends; the lead MUST NOT call `gh pr merge`.
+  - escalating beyond the menu choices on user phrasing — every mutating action requires an explicit menu selection (the shared anti-escalation rule applies, with this phase-specific tightening).

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

@@ -6,16 +6,7 @@
   - codex
   - gemini
   - report-writer
-- Team contract:
-  - `Claude lead` is synthesis-only and stays distinct from `Claude worker`
-  - required worker roles are `Claude worker`, `Codex worker`, `Gemini worker`, and `Report writer worker`
-  - `Report writer worker` is the **author** of the final-report file; `Claude lead` reviews and approves the produced draft and does NOT write the file itself (see `okstra-team-contract` and `okstra-report-writer` for the authoritative contract)
-  - default model assignments are resolved from centralized defaults; the fallback values are `Claude lead`/`Report writer worker`=`opus`, `Claude worker`=`sonnet`, `Codex worker`=`gpt-5.5`, `Gemini worker`=`auto`
-  - `Gemini worker` must always be attempted for this workflow
-  - the final verdict waits until each required worker has either a result or an explicit terminal status
-  - unnamed generic parallel workers must not replace the required role roster
-- Tooling — read-only MCP availability:
-  - the read-only MCP servers declared in the task brief's `## Available MCP Servers` section may be queried when local schema or sample data clarifies the work category or routing decision; that section is the canonical source of which servers and tools exist for this run, and any MCP-derived finding MUST cite server, table, and the SELECT used
+{{INCLUDE:_common-contract.md}}
 - Primary focus areas:
   - classify the work as bugfix, feature, improvement, refactor, or ops-change
   - determine whether `error-analysis`, `implementation-planning`, or a direct implementation handoff is the next safe step
@@ -26,18 +17,9 @@
   - evidence-backed routing decision
   - uncertainty boundaries and missing inputs
   - next recommended phase and safe resume guidance
-- Clarification request policy:
+- Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
   - if any blocking input is missing at the time of writing the final report, populate `## 5. Clarification Requests for the Next Run` in `final-report-template.md`
-  - section 5 must be split into two distinct sub-sections per the template — `5.1 추가 자료 요청 (Additional Materials Requested)` for files/screenshots/links the user must attach, and `5.2 사용자 확인 질문 (Questions for the User)` for routing or scoping decisions only the user can make. Never mix material requests and decision questions in the same row or list.
   - prefer concrete questions whose answers map directly to a routing decision (`bugfix` vs `feature`, `error-analysis` vs `implementation-planning`, etc.). State each option in plain language with one sentence describing what choosing it would mean for the next phase.
-  - write every entry in full, descriptive sentences that a non-developer can act on without further context. Avoid abbreviations and internal jargon. For each material request, state *why* it is needed, *where* the user can find it, and *where* to place it. For each question, state *why* the answer changes the routing decision, *what* is being asked in a complete sentence, and *what shape of answer* is expected (예/아니오, 보기 중 하나, 숫자/날짜, 짧은 서술 등); supply concrete option choices when applicable.
-  - the same `final-report.md` file is the canonical artifact carried into the next run; the user appends answers inline before rerunning. The preferred turn-around is `scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<task-id>` (opens the latest report in `$EDITOR`, then auto-reruns the same phase with `--clarification-response` carry-in). The lower-level form `--clarification-response <path>` remains available for scripted runs.
-  - if a clarification response was carried in for this run, reconcile each prior `A*` (material) and `Q*` (question) row in section 0 and update its `Status` (`resolved`, `obsolete`) before issuing the routing decision
-- Authority & permissions assumption (HARD RULE — applies to every okstra task-type):
-  - **Assume the user (and their team) holds full authority and every permission required for the anticipated work.** Treat external approvals, third-party access grants, role/IAM permissions, organisational sign-off, legal/compliance review, vendor coordination, and "verify access exists" steps as already satisfied unless the user explicitly states otherwise in the task brief.
-  - Do NOT add such items to routing decisions, missing-materials lists, clarification questions, risk lists, dependencies, open questions, or day/effort estimates. They are not legitimate sources of schedule extension.
-  - Internal okstra phase handoffs (e.g. the `User Approval Request` block in `implementation-planning`) are unaffected — those are the user themselves approving and proceed without external coordination.
 - Non-goals:
   - full implementation design unless it is required to decide the next phase
   - **source code edits, plan authoring, builds, or deployments** — this run only classifies the work and routes it; deeper analysis and planning belong to subsequent phases
-  - treating "다음 단계 진행해" or equivalent user phrases as authorisation to start `error-analysis`, `implementation-planning`, or `implementation` — the next phase begins only in a separate okstra run launched with the new `--task-type`

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

@@ -201,7 +201,7 @@ while [[ $# -gt 0 ]]; do
       printf 'unknown option: %s\n' "$__unknown_opt" >&2
       case "$__opt_name" in
         --phase|--phases|--lifecycle-phase)
-          printf '  hint: --phase is not a valid flag. Use --task-type <requirements-discovery|error-analysis|implementation-planning|implementation|final-verification>.\n' >&2
+          printf '  hint: --phase is not a valid flag. Use --task-type <requirements-discovery|error-analysis|implementation-planning|implementation|final-verification|release-handoff>.\n' >&2
           printf '        "phase" is a manifest lifecycle field name, not a CLI option.\n' >&2
           ;;
         --brief|--task-brief)

package/runtime/python/okstra_ctl/render.py

@@ -415,14 +415,15 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
     catalog = _worker_catalog(ctx)
     phase_sequence = [
         "requirements-discovery", "error-analysis", "implementation-planning",
-        "implementation", "final-verification",
+        "implementation", "final-verification", "release-handoff",
     ]
     default_next_phase = {
         "requirements-discovery": "pending-routing-decision",
         "error-analysis": "implementation-planning",
         "implementation-planning": "implementation",
         "implementation": "final-verification",
-        "final-verification": "done-or-follow-up",
+        "final-verification": "pending-release-handoff",
+        "release-handoff": "done-or-follow-up",
     }
     required_worker_roles = _required_worker_roles(ctx, reviewers)
     worker_prompt_paths = {item: catalog[item]["promptPath"] for item in reviewers}
@@ -809,6 +810,7 @@ def render_task_index(template_path: str, output_path: str, ctx: dict) -> None:
         phase_order = [
             "requirements-discovery", "error-analysis",
             "implementation-planning", "implementation", "final-verification",
+            "release-handoff",
         ]
     phase_state_lines = [
         f"- `{phase}`: `{phase_states.get(phase, 'not-started')}`"
@@ -1077,6 +1079,11 @@ def render_template_file(template_path: str, output_path: str, ctx: dict) -> Non
             "AVAILABLE_MCP_SERVERS",
             build_available_mcp_servers_block(Path(ctx.get("PROJECT_ROOT", "."))),
         ),
+        "{{EXECUTOR_WORKTREE_PATH}}": ctx.get("EXECUTOR_WORKTREE_PATH", ""),
+        "{{EXECUTOR_WORKTREE_BRANCH}}": ctx.get("EXECUTOR_WORKTREE_BRANCH", ""),
+        "{{EXECUTOR_WORKTREE_BASE_REF}}": ctx.get("EXECUTOR_WORKTREE_BASE_REF", ""),
+        "{{EXECUTOR_WORKTREE_STATUS}}": ctx.get("EXECUTOR_WORKTREE_STATUS", ""),
+        "{{EXECUTOR_WORKTREE_NOTE}}": ctx.get("EXECUTOR_WORKTREE_NOTE", ""),
     }
     rendered = template
     for k, v in mapping.items():

package/runtime/python/okstra_ctl/run.py

@@ -54,6 +54,7 @@ from .seeding import (
 from .session import generate_claude_session_id, write_claude_resume_command_file
 from .workers import normalize_workers, resolve_profile_workers
 from .workflow import compute_workflow_state
+from .worktree import provision_implementation_worktree
 
 APPROVED_PLAN_PATTERN = re.compile(
     r"^[ \t]*(?:[-*+][ \t]+)?(APPROVED([ \t]|:|$)|\[x\][ \t]*Approved|"
@@ -339,6 +340,36 @@ def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
     return argv
 
 
+_INCLUDE_DIRECTIVE = re.compile(r"\{\{INCLUDE:([^}]+?)\}\}")
+
+
+def _expand_profile_includes(profile_path: Path, _depth: int = 0) -> str:
+    """Resolve `{{INCLUDE:<name>}}` directives in a profile file.
+
+    Includes are resolved relative to the profile's directory. A maximum
+    recursion depth of 4 prevents accidental cycles; the included file
+    contents replace the directive line in-place. Missing include targets
+    raise PrepareError so a bad reference fails fast instead of silently
+    leaving a `{{INCLUDE:...}}` token in the rendered profile.
+    """
+    if _depth > 4:
+        raise PrepareError(
+            f"profile include recursion exceeded depth 4 while resolving {profile_path}"
+        )
+    text = profile_path.read_text(encoding="utf-8")
+
+    def _sub(match: "re.Match[str]") -> str:
+        target_name = match.group(1).strip()
+        target = profile_path.parent / target_name
+        if not target.is_file():
+            raise PrepareError(
+                f"profile include target missing: {target} (referenced from {profile_path})"
+            )
+        return _expand_profile_includes(target, _depth + 1).rstrip("\n")
+
+    return _INCLUDE_DIRECTIVE.sub(_sub, text)
+
+
 def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     """Produce a complete okstra task bundle on disk. See module docstring."""
     workspace_root = Path(inp.workspace_root)
@@ -482,10 +513,34 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         task_type=inp.task_type, run_seq_override=run_seq_override,
     )
 
+    # ---- executor worktree provisioning (implementation phase only) ----
+    # The reports-seq is reused as the worktree-seq so the on-disk worktree
+    # path is colocated with the artefacts produced by this run.
+    try:
+        worktree = provision_implementation_worktree(
+            task_type=inp.task_type,
+            project_root=project_root,
+            project_id=inp.project_id,
+            task_group_segment=ctx["TASK_GROUP_SEGMENT"],
+            task_id_segment=ctx["TASK_ID_SEGMENT"],
+            run_seq=int(ctx["RUN_REPORTS_SEQ"]),
+            work_category=inp.work_category,
+        )
+    except RuntimeError as exc:
+        raise PrepareError(f"executor worktree provisioning failed: {exc}") from exc
+
+    ctx.update({
+        "EXECUTOR_WORKTREE_PATH": worktree.path,
+        "EXECUTOR_WORKTREE_BRANCH": worktree.branch,
+        "EXECUTOR_WORKTREE_BASE_REF": worktree.base_ref,
+        "EXECUTOR_WORKTREE_STATUS": worktree.status,
+        "EXECUTOR_WORKTREE_NOTE": worktree.note,
+    })
+
     claude_session_id = "" if inp.render_only else generate_claude_session_id()
 
     # ---- material + related-tasks ----
-    profile_content = profile_file.read_text(encoding="utf-8")
+    profile_content = _expand_profile_includes(profile_file)
     review_material = build_analysis_material(inp.brief_path, inp.directive)
     related_items = resolve_related_tasks(
         task_manifest_path=Path(ctx["TASK_MANIFEST_FILE"]),
@@ -577,6 +632,11 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "EXECUTOR_WORKER_AGENT",
         "EXECUTOR_MODEL_DISPLAY",
         "EXECUTOR_MODEL_EXECUTION_VALUE",
+        "EXECUTOR_WORKTREE_PATH",
+        "EXECUTOR_WORKTREE_BRANCH",
+        "EXECUTOR_WORKTREE_BASE_REF",
+        "EXECUTOR_WORKTREE_STATUS",
+        "EXECUTOR_WORKTREE_NOTE",
     ):
         profile_rendered = profile_rendered.replace("{{" + key + "}}", ctx.get(key, ""))
     (instruction_set / "analysis-profile.md").write_text(profile_rendered, encoding="utf-8")

package/runtime/python/okstra_ctl/workers.py

@@ -9,7 +9,12 @@ from __future__ import annotations
 from pathlib import Path
 
 ALLOWED_WORKERS = ["claude", "codex", "gemini", "report-writer"]
-PROFILE_BULLET_HEADERS = {"- Workers:", "- Reviewers:", "- Analysers:"}
+PROFILE_BULLET_HEADERS = {
+    "- Workers:",
+    "- Required workers:",
+    "- Reviewers:",
+    "- Analysers:",
+}
 
 
 class WorkersError(Exception):

package/runtime/python/okstra_ctl/workflow.py

@@ -15,6 +15,7 @@ PHASE_SEQUENCE = [
     "implementation-planning",
     "implementation",
     "final-verification",
+    "release-handoff",
 ]
 
 DEFAULT_NEXT_PHASE = {
@@ -22,7 +23,11 @@ DEFAULT_NEXT_PHASE = {
     "error-analysis": "implementation-planning",
     "implementation-planning": "implementation",
     "implementation": "final-verification",
-    "final-verification": "done-or-follow-up",
+    # final-verification 의 다음 단계는 verdict 에 따라 갈리므로 정적 매핑은
+    # `pending-release-handoff` 로 둔다 (accepted 일 때만 release-handoff 로
+    # 진입; 그 외에는 error-analysis / implementation-planning 으로 리라우팅).
+    "final-verification": "pending-release-handoff",
+    "release-handoff": "done-or-follow-up",
 }
 
 # Phase 별 allowed outputs / forbidden actions. bash heredoc 원문 그대로 옮긴 값.
@@ -109,7 +114,7 @@ PHASE_RULES: dict[str, dict[str, str]] = {
         "allowed": (
             "  - acceptance verdict with requirement coverage assessment\n"
             "  - residual risk and regression notes\n"
-            "  - recommended follow-up routing (`error-analysis` / `implementation-planning`) for any defects detected"
+            "  - recommended follow-up routing (`error-analysis` / `implementation-planning` / `release-handoff`) for any defects detected"
         ),
         "forbidden": (
             "  - source code edits, follow-up bug fixes, or scope expansion\n"
@@ -117,6 +122,29 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - starting any follow-up phase inside this run; record findings and end the run"
         ),
     },
+    "release-handoff": {
+        "allowed": (
+            "  - entering this phase only when the cited final-verification report's verdict is exactly `accepted`\n"
+            "  - asking the user (via `AskUserQuestion` / interactive prompt) which delivery action to take: `commit only`, `commit + PR`, or `skip` (end the run)\n"
+            "  - asking the user to pick a PR base branch from `staging` | `preprod` | `prod` | `main` | `dev` | a user-supplied branch name\n"
+            "  - dispatching the `Claude worker` (drafter) to produce candidate commit message(s) and PR body in markdown; the lead reviews and offers them to the user before any git command runs\n"
+            "  - local git operations: `git status`, `git diff`, `git log`, `git add`, `git commit -m`\n"
+            "  - pushing the current feature branch to its origin remote via `git push -u origin <current-branch>` (the feature branch only — NEVER the base branch)\n"
+            "  - creating a pull request via `gh pr create --base <chosen-base> --head <current-branch>`; if a PR with the same head already exists, surface its URL and skip creation\n"
+            "  - recording the executed actions, commit SHAs, PR URL, and user selections in the final report"
+        ),
+        "forbidden": (
+            "  - entering this phase when the cited final-verification verdict is `conditional-accept` or `blocked`, or when no final-verification report is cited\n"
+            "  - any source-code edit, refactor, or scope expansion beyond what is strictly needed to author commit messages / PR descriptions (the changes themselves are inherited from prior `implementation` runs)\n"
+            "  - `git push --force`, `git push --force-with-lease`, or any rewriting of remote history\n"
+            "  - pushing directly to a base branch (`main`, `master`, `prod`, `preprod`, `staging`, `dev`, or any branch the user named as the PR base)\n"
+            "  - bypassing git hooks (`--no-verify`, `-n`), bypassing GPG signing, or otherwise disabling repo-configured safeguards\n"
+            "  - release-publishing commands: `gh release`, `npm publish`, `cargo publish`, `pip publish`, `docker push`, `terraform apply`, `kubectl apply` against non-local clusters\n"
+            "  - executing any command the user did NOT select (e.g. if the user picked `commit only`, opening a PR is forbidden; if the user picked `skip`, the run ends without git commands)\n"
+            "  - dispatching parallel sub-agents beyond the required worker roster (`Claude worker` drafter + `Report writer worker`)\n"
+            "  - silently retrying a failed git/gh command with weaker flags (e.g. retrying `git push` with `--force` after a non-fast-forward rejection)"
+        ),
+    },
 }
 
 PHASE_RULES_UNKNOWN = {

package/runtime/python/okstra_ctl/worktree.py

@@ -0,0 +1,298 @@
+"""Implementation-phase git worktree provisioning.
+
+Implementation runs operate on an isolated git worktree rooted under
+`~/.okstra/worktrees/<project_id>/<task_group_segment>/<task_id_segment>-<run_seq>`.
+The executor mutates files there; verifiers read from the same path.
+The worktree is always kept after the run for inspection, manual PR
+authoring, and rollback verification.
+
+Pre-conditions handled here:
+  - Skip non-`implementation` task-types entirely.
+  - Skip when `project_root` itself already sits inside a non-main git
+    worktree (the run reuses the caller's working tree).
+  - Refuse to clobber an existing path or branch — raise PrepareError.
+
+Side effects: `git worktree add -b <branch> <path> <base_ref>` is invoked
+in `project_root`. The function does NOT chdir.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+OKSTRA_WORKTREES_RELATIVE = Path(".okstra/worktrees")
+
+
+# Project-root directories that hold okstra task state, ignored by git, or
+# otherwise required for the executor to operate but NOT carried across by
+# `git worktree add`. Each is symlinked from project_root into the new
+# worktree at provision time. Symlinks (not copies) so the executor sees
+# the live state and disk/CPU cost stays near zero; the trade-off is that
+# any write through the link reaches the original project_root, which is
+# acceptable because the executor only writes inside its own task-scoped
+# subdirectory (e.g. `.project-docs/okstra/tasks/<task-id>/runs/...`).
+#
+# Override via the `OKSTRA_WORKTREE_SYNC_DIRS` env var: a colon-separated
+# list of project-root-relative paths that REPLACES this default. Use an
+# empty string to disable the feature entirely.
+DEFAULT_WORKTREE_SYNC_DIRS: tuple[str, ...] = (
+    ".project-docs",
+    ".scratch",
+    "graphify-out",
+)
+
+
+# Work-category → short branch prefix. Mirrors the values accepted by
+# `--work-category` (bugfix / feature / refactor / ops / improvement) and
+# falls back to `task` when the category is unset or unrecognised.
+_WORK_CATEGORY_PREFIX = {
+    "feature": "feat",
+    "bugfix": "fix",
+    "refactor": "refactor",
+    "ops": "ops",
+    "improvement": "improve",
+    "docs": "doc",
+    "doc": "doc",
+}
+
+
+@dataclass
+class WorktreeProvision:
+    """Result of `provision_implementation_worktree`.
+
+    status:
+      - "created": fresh worktree at `path` on `branch`
+      - "skipped-non-implementation": task-type was not `implementation`
+      - "skipped-in-worktree": project_root is already inside a non-main
+        worktree; the run reuses `project_root` and no new worktree is
+        materialised
+      - "skipped-not-git": project_root has no `.git` (worktree path
+        cannot be provisioned; degrade gracefully)
+    """
+    status: str
+    path: str = ""          # absolute path of the executor worktree (or project_root when reused)
+    branch: str = ""        # branch checked out in the worktree (empty when reused / not-git)
+    base_ref: str = ""      # commit SHA the worktree was branched from (empty when not created)
+    note: str = ""          # human-readable explanation, surfaced in team-state / manifests
+
+
+def _work_category_prefix(work_category: str) -> str:
+    key = (work_category or "").strip().lower()
+    return _WORK_CATEGORY_PREFIX.get(key, "task")
+
+
+def _git(project_root: Path, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", "-C", str(project_root), *args],
+        capture_output=True, text=True, check=False,
+    )
+
+
+def _is_inside_non_main_worktree(project_root: Path) -> bool:
+    """True iff project_root is inside a git worktree that is NOT the
+    repository's main checkout. Detection rule: `--git-dir` (per-worktree
+    .git pointer) differs from `--git-common-dir` (shared object store).
+    """
+    common = _git(project_root, "rev-parse", "--git-common-dir")
+    per_tree = _git(project_root, "rev-parse", "--git-dir")
+    if common.returncode != 0 or per_tree.returncode != 0:
+        return False
+    # Both paths can be relative to project_root; resolve before compare.
+    common_abs = (project_root / common.stdout.strip()).resolve()
+    per_tree_abs = (project_root / per_tree.stdout.strip()).resolve()
+    return common_abs != per_tree_abs
+
+
+def _is_git_repo(project_root: Path) -> bool:
+    res = _git(project_root, "rev-parse", "--is-inside-work-tree")
+    return res.returncode == 0 and res.stdout.strip() == "true"
+
+
+def _branch_exists(project_root: Path, branch: str) -> bool:
+    res = _git(project_root, "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}")
+    return res.returncode == 0
+
+
+def _head_sha(project_root: Path) -> str:
+    res = _git(project_root, "rev-parse", "HEAD")
+    if res.returncode != 0:
+        return ""
+    return res.stdout.strip()
+
+
+def _resolve_sync_dirs() -> tuple[str, ...]:
+    """Return the list of project-root-relative dirs to symlink into the
+    new worktree. Reads `OKSTRA_WORKTREE_SYNC_DIRS` if set (colon-separated,
+    empty string disables); otherwise returns the built-in default.
+    """
+    raw = os.environ.get("OKSTRA_WORKTREE_SYNC_DIRS")
+    if raw is None:
+        return DEFAULT_WORKTREE_SYNC_DIRS
+    raw = raw.strip()
+    if not raw:
+        return ()
+    return tuple(part for part in (p.strip() for p in raw.split(":")) if part)
+
+
+def _link_sync_dirs(project_root: Path, worktree_path: Path) -> list[str]:
+    """Symlink each configured project-root dir into the new worktree.
+
+    Skip rules:
+      - Source missing in project_root → silently skipped.
+      - Target path already exists in worktree (e.g. tracked content
+        checked out by `git worktree add`) → skipped to avoid clobbering
+        version-controlled files.
+      - Parent directories are created as needed for nested entries.
+
+    Returns a list of human-readable notes (one per linked entry) so the
+    caller can include them in the provisioning note.
+    """
+    notes: list[str] = []
+    for rel in _resolve_sync_dirs():
+        src = (project_root / rel).resolve()
+        if not src.exists():
+            continue
+        dst = worktree_path / rel
+        if dst.exists() or dst.is_symlink():
+            continue
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        os.symlink(src, dst)
+        notes.append(rel)
+    return notes
+
+
+def compute_worktree_path(
+    *,
+    project_id: str,
+    task_group_segment: str,
+    task_id_segment: str,
+    run_seq: int,
+) -> Path:
+    """Pure path computation. Mirrors `okstra_root` location convention.
+
+    Uses `OKSTRA_HOME` when set (test hook), else `~/.okstra`.
+    """
+    okstra_home = os.environ.get("OKSTRA_HOME", "").strip()
+    base = Path(okstra_home) if okstra_home else (Path.home() / ".okstra")
+    return (
+        base / "worktrees" / project_id
+        / task_group_segment / f"{task_id_segment}-{int(run_seq):03d}"
+    )
+
+
+def compute_branch_name(
+    *,
+    work_category: str,
+    task_id_segment: str,
+    run_seq: int,
+) -> str:
+    return f"{_work_category_prefix(work_category)}-{task_id_segment}-{int(run_seq):03d}"
+
+
+def provision_implementation_worktree(
+    *,
+    task_type: str,
+    project_root: Path,
+    project_id: str,
+    task_group_segment: str,
+    task_id_segment: str,
+    run_seq: int,
+    work_category: str,
+) -> WorktreeProvision:
+    """Materialise (or skip) the executor worktree for this run.
+
+    The caller passes the same `run_seq` used by the reports/manifests
+    artefacts so the worktree directory is colocated by sequence number.
+
+    Raises:
+        PrepareError-like RuntimeError when worktree creation fails
+        (path clash, branch clash, `git worktree add` non-zero). The
+        caller (`run.py`) catches and re-raises as PrepareError to keep
+        a single error surface.
+    """
+    if task_type != "implementation":
+        return WorktreeProvision(
+            status="skipped-non-implementation",
+            path=str(project_root),
+            note="worktree provisioning skipped: task-type is not 'implementation'",
+        )
+
+    if not _is_git_repo(project_root):
+        return WorktreeProvision(
+            status="skipped-not-git",
+            path=str(project_root),
+            note=(
+                "worktree provisioning skipped: project_root is not inside a git "
+                "repository; executor will operate directly on project_root"
+            ),
+        )
+
+    if _is_inside_non_main_worktree(project_root):
+        return WorktreeProvision(
+            status="skipped-in-worktree",
+            path=str(project_root),
+            note=(
+                "worktree provisioning skipped: project_root is already inside a "
+                "non-main git worktree; executor reuses the caller's worktree"
+            ),
+        )
+
+    worktree_path = compute_worktree_path(
+        project_id=project_id,
+        task_group_segment=task_group_segment,
+        task_id_segment=task_id_segment,
+        run_seq=run_seq,
+    )
+    branch = compute_branch_name(
+        work_category=work_category,
+        task_id_segment=task_id_segment,
+        run_seq=run_seq,
+    )
+
+    if worktree_path.exists():
+        raise RuntimeError(
+            f"executor worktree path already exists: {worktree_path}. "
+            "Remove it with `git worktree remove <path>` (or `rm -rf` if it is "
+            "not a registered worktree) before retrying this implementation run."
+        )
+    if _branch_exists(project_root, branch):
+        raise RuntimeError(
+            f"executor worktree branch already exists: {branch}. "
+            "Delete it (`git branch -D <branch>`) or bump OKSTRA_RUN_SEQ_OVERRIDE "
+            "before retrying."
+        )
+
+    base_ref = _head_sha(project_root)
+    if not base_ref:
+        raise RuntimeError(
+            "could not resolve HEAD sha in project_root; cannot create worktree"
+        )
+
+    worktree_path.parent.mkdir(parents=True, exist_ok=True)
+    res = _git(
+        project_root,
+        "worktree", "add", "-b", branch, str(worktree_path), base_ref,
+    )
+    if res.returncode != 0:
+        raise RuntimeError(
+            f"`git worktree add` failed (exit={res.returncode}): "
+            f"{(res.stderr or res.stdout).strip()}"
+        )
+
+    linked = _link_sync_dirs(project_root, worktree_path)
+    linked_suffix = f"; linked {', '.join(linked)}" if linked else ""
+
+    return WorktreeProvision(
+        status="created",
+        path=str(worktree_path),
+        branch=branch,
+        base_ref=base_ref,
+        note=(
+            f"executor worktree created at {worktree_path} on branch {branch} "
+            f"(base {base_ref[:12]}){linked_suffix}"
+        ),
+    )