okstra 0.7.0 → 0.9.0

package/runtime/python/okstra_ctl/run.py

@@ -21,6 +21,7 @@ import re
 import shutil
 import subprocess
 from dataclasses import dataclass, field
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
@@ -53,9 +54,10 @@ 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]*(APPROVED([ \t]|:|$)|\[x\][ \t]*Approved|"
+    r"^[ \t]*(?:[-*+][ \t]+)?(APPROVED([ \t]|:|$)|\[x\][ \t]*Approved|"
     r"User[ \t]+Approval[ \t]*:[ \t]*(APPROVED|granted|yes))",
     re.IGNORECASE | re.MULTILINE,
 )
@@ -83,10 +85,12 @@ class PrepareInputs:
     report_writer_model: str = ""
     executor: str = ""
     related_tasks_raw: str = ""
+    work_category: str = ""
     approved_plan_path: str = ""
     clarification_response_path: str = ""  # absolute or empty
     render_only: bool = False
     refresh_assets: bool = False
+    approve_plan_ack: bool = False
 
 
 @dataclass
@@ -108,11 +112,65 @@ def _validate_approved_plan(path: str) -> None:
     if not APPROVED_PLAN_PATTERN.search(p.read_text(encoding="utf-8", errors="replace")):
         raise PrepareError(
             f"approved plan has no recognised user-approval marker: {path}\n"
-            '  expected one of (case-insensitive, line-anchored): "APPROVED", '
-            '"[x] Approved", "User Approval: APPROVED|granted|yes"'
+            '  canonical form (single line, top-of-report block): "- [x] Approved"\n'
+            '  also accepted (case-insensitive, line-anchored, optional leading bullet): '
+            '"APPROVED", "[x] Approved", "User Approval: APPROVED|granted|yes"\n'
+            "  shortcut: re-run okstra with --approve to have the CLI itself "
+            "record the approval marker on this file."
         )
 
 
+# `- [ ] Approved` 라인을 정확히 한 번만 매치한다. 좌측 leading whitespace 와
+# 옵션 bullet 은 보존된 채 체크박스 안쪽 공백만 `x` 로 갱신된다.
+APPROVAL_UNCHECKED_PATTERN = re.compile(
+    r"^([ \t]*(?:[-*+][ \t]+)?)\[[ \t]\][ \t]*Approved[ \t]*$",
+    re.IGNORECASE | re.MULTILINE,
+)
+
+
+def _apply_cli_approval(path: str) -> str:
+    """`--approve` 가 지정된 경우 approved-plan 파일에 사용자 승인 마커를 새겨 넣는다.
+
+    Returns a short human-readable description of the action taken (used in the
+    runtime audit line). Idempotent: if the file already carries a valid
+    approval marker, no edits are written and `"already-approved"` is returned.
+    """
+    p = Path(path)
+    if not p.is_file():
+        raise PrepareError(f"approved plan file not found: {path}")
+    body = p.read_text(encoding="utf-8", errors="replace")
+
+    audit_iso = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    audit_line = (
+        f"- 승인 일시 (CLI ack): {audit_iso} — recorded by `okstra --approve` "
+        "(user CLI invocation treated as approval signal)"
+    )
+
+    if APPROVED_PLAN_PATTERN.search(body):
+        # 이미 사용자(또는 이전 --approve 호출)가 마커를 남긴 상태. audit 라인이
+        # 없으면 보조적으로 한 줄만 추가하고 마커 자체는 건드리지 않는다.
+        if audit_line.split(" — ")[1] in body:
+            return "already-approved"
+        new_body = body.rstrip("\n") + "\n" + audit_line + "\n"
+        p.write_text(new_body, encoding="utf-8")
+        return "already-approved-audit-appended"
+
+    if APPROVAL_UNCHECKED_PATTERN.search(body):
+        new_body, count = APPROVAL_UNCHECKED_PATTERN.subn(
+            lambda m: f"{m.group(1)}[x] Approved", body, count=1,
+        )
+        new_body = new_body.rstrip("\n") + "\n" + audit_line + "\n"
+        p.write_text(new_body, encoding="utf-8")
+        return "checkbox-flipped"
+
+    raise PrepareError(
+        f"--approve was given but the approved-plan file has no `User Approval Request` "
+        f"checkbox to flip: {path}\n"
+        "  expected a line of the form `- [ ] Approved` near the top of the report "
+        "(see templates/reports/final-report.template.md)."
+    )
+
+
 def _ensure_task_directories(ctx: dict) -> None:
     for key in (
         "TASK_ROOT", "INSTRUCTION_SET_DIR", "RUNS_DIR", "HISTORY_DIR",
@@ -268,6 +326,7 @@ def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
         ("--report-writer-model", inp.report_writer_model or ctx.get("REPORT_WRITER_MODEL_DISPLAY", "")),
         ("--executor", inp.executor or ctx.get("EXECUTOR_PROVIDER", "")),
         ("--related-tasks", inp.related_tasks_raw),
+        ("--work-category", inp.work_category),
     ]
     argv: list[str] = []
     for flag, val in pairs:
@@ -330,7 +389,19 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
             raise PrepareError(
                 "task-type implementation requires --approved-plan <path-to-final-report.md>"
             )
+        if inp.approve_plan_ack:
+            # 사용자가 직접 `--approve` 를 입력한 행위 자체를 승인 의사로 모델링한다.
+            # 파일을 먼저 갱신한 뒤 동일한 검증 경로를 그대로 통과시킨다 — 검증
+            # 책임을 단일 지점(`_validate_approved_plan`)으로 유지한다.
+            _apply_cli_approval(inp.approved_plan_path)
         _validate_approved_plan(inp.approved_plan_path)
+    elif inp.approve_plan_ack:
+        # implementation 외 task-type 에서 `--approve` 는 의미가 없다. 사용자에게
+        # 정확한 시점을 알려주기 위해 조용히 무시하지 않고 즉시 거부한다.
+        raise PrepareError(
+            "--approve is only meaningful with --task-type implementation "
+            "and --approved-plan <path>"
+        )
     if inp.clarification_response_path and not Path(inp.clarification_response_path).is_file():
         raise PrepareError(
             f"clarification response file not found: {inp.clarification_response_path}"
@@ -412,6 +483,30 @@ 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 ----
@@ -487,11 +582,15 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     cleanup_obsolete_generated_docs(
         project_root=project_root, instruction_set_dir=Path(ctx["INSTRUCTION_SET_DIR"]),
     )
-    if not inp.render_only:
-        write_claude_resume_command_file(
-            resume_command_path=Path(ctx["CLAUDE_RESUME_COMMAND_FILE"]),
-            project_root=project_root, claude_session_id=claude_session_id,
-        )
+    # Always materialise the resume command script. Even in --render-only
+    # preparation flows the user (or a later non-interactive runner) may
+    # invoke it manually; deferring its creation until interactive launch
+    # leaves runs/<phase>/sessions/ empty and the manifest pointing at a
+    # path that does not exist.
+    write_claude_resume_command_file(
+        resume_command_path=Path(ctx["CLAUDE_RESUME_COMMAND_FILE"]),
+        project_root=project_root, claude_session_id=claude_session_id,
+    )
 
     # ---- write instruction-set scaffolding ----
     instruction_set = Path(ctx["INSTRUCTION_SET_DIR"])
@@ -503,6 +602,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")
@@ -569,6 +673,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         current_run_status=ctx["CURRENT_RUN_STATUS"],
         current_task_status=ctx["CURRENT_TASK_STATUS"],
         render_only=inp.render_only,
+        work_category=inp.work_category,
     ))
     render_team_state(ctx["TEAM_STATE_FILE"], ctx)
     render_task_manifest(ctx["TASK_MANIFEST_FILE"], ctx)
@@ -639,9 +744,29 @@ def main(argv: list[str]) -> int:
     p.add_argument("--executor", default="")
     p.add_argument("--related-tasks", default="", dest="related_tasks_raw")
     p.add_argument("--approved-plan", default="", dest="approved_plan_path")
+    p.add_argument(
+        "--approve",
+        action="store_true",
+        dest="approve_plan_ack",
+        help=(
+            "Treat the CLI invocation itself as the plan approval signal. "
+            "Flips `- [ ] Approved` to `- [x] Approved` in the --approved-plan file "
+            "and appends an audit line."
+        ),
+    )
     p.add_argument("--clarification-response", default="", dest="clarification_response_path")
     p.add_argument("--render-only", action="store_true", dest="render_only")
     p.add_argument("--refresh-assets", action="store_true", dest="refresh_assets")
+    p.add_argument(
+        "--work-category",
+        default="",
+        dest="work_category",
+        help=(
+            "Work-category classification for this task "
+            "(bugfix / feature / refactor / ops / improvement). "
+            "Falls back to `unknown` when omitted."
+        ),
+    )
     args = p.parse_args(argv)
 
     project_root = Path(args.project_root).expanduser().resolve()
@@ -677,10 +802,12 @@ def main(argv: list[str]) -> int:
         report_writer_model=args.report_writer_model,
         executor=args.executor,
         related_tasks_raw=args.related_tasks_raw,
+        work_category=args.work_category,
         approved_plan_path=args.approved_plan_path,
         clarification_response_path=clarification_abs,
         render_only=args.render_only,
         refresh_assets=args.refresh_assets,
+        approve_plan_ack=args.approve_plan_ack,
     )
     try:
         out = prepare_task_bundle(inputs)

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 = {
@@ -138,6 +166,7 @@ def compute_workflow_state(
     current_run_status: str,
     current_task_status: str,
     render_only: bool,
+    work_category: str = "",
 ) -> dict:
     """WORKFLOW_* + PHASE_* 값을 dict 로 돌려준다."""
     if current_run_status == "in-progress":
@@ -170,8 +199,10 @@ def compute_workflow_state(
     rules = PHASE_RULES.get(task_type, PHASE_RULES_UNKNOWN)
     last_completed = task_type if current_run_status == "completed" else ""
 
+    resolved_work_category = (work_category or "").strip() or "unknown"
+
     return {
-        "WORKFLOW_WORK_CATEGORY": "unknown",
+        "WORKFLOW_WORK_CATEGORY": resolved_work_category,
         "WORKFLOW_CURRENT_PHASE": task_type,
         "WORKFLOW_CURRENT_PHASE_STATE": phase_state,
         "WORKFLOW_NEXT_RECOMMENDED_PHASE": default_next_phase_for(task_type),

package/runtime/python/okstra_ctl/worktree.py

@@ -0,0 +1,235 @@
+"""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")
+
+
+# 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 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()}"
+        )
+
+    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]})"
+        ),
+    )

package/runtime/skills/okstra-context-loader/SKILL.md

@@ -40,7 +40,7 @@ task-manifest.json is the canonical metadata source. The following fields must b
 | `projectId` | Project ID |
 | `taskGroup` | Task group |
 | `taskId` | Task ID |
-| `taskType` | Analysis type (requirements-discovery, error-analysis, final-verification, implementation-planning) |
+| `taskType` | Analysis type (requirements-discovery, error-analysis, implementation-planning, implementation, final-verification, release-handoff) |
 | `workCategory` | bugfix / feature / improvement / refactor / ops-change / unknown |
 | `recommendedWorkers` | List of selected workers |
 | `currentStatus` | Current task status |

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

@@ -37,12 +37,18 @@ Configure this in the `convergence` block of `task-manifest.json`. If the block
 
 Read the worker result files generated in Phase 4/5 and extract individual findings.
 
-1. In the "Findings" section of each worker's results, identify individual items by number (F-001, F-002, ...).
-2. For each finding, record the summary, evidence (file path, line number, basis), and the worker who identified it.
-3. Claude Lead groups findings based on semantic similarity:
-  - When 2 or more workers report the same or similar findings → immediately reach `full consensus`
-  - Only one worker confirms → `unique`, enter the verification queue
+1. In the "Findings" section of each worker's results, identify individual items by number (F-001, F-002, ...) and parse the ticket identifier attached to each item:
+   - For table-form findings, read the `Ticket ID` column.
+   - For bullet/numbered findings, parse `[TICKETID: <id>]` from the item title.
+   - Items with multiple tickets (e.g. `TICKET-123, TICKET-456`) expand to a set of ticket keys.
+   - Items tagged `unknown` keep the literal `unknown` as their ticket key.
+2. For each finding, record the summary, evidence (file path, line number, basis), the worker who identified it, and the parsed ticket set.
+3. Claude Lead groups findings based on semantic similarity AND ticket-set equality:
+  - Same semantics + same ticket set across 2+ workers → immediately reach `full consensus`.
+  - Same semantics but disjoint ticket sets → keep as separate groups (do NOT over-merge across tickets).
+  - Only one worker confirms a finding → `unique`, enter the verification queue.
 4. When grouping is ambiguous, prefer splitting over merging (avoid over-merging).
+5. Persist each finding's ticket set in the convergence state artifact under a `ticketIds` field on the finding record. Re-verification rounds carry the same field forward.
 
 ### Round 1-N: Re-verification Loop
 

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

@@ -1,6 +1,7 @@
 ---
 name: okstra-report-finder
 description: Use when the user provides a task key and needs to find the final report path, or wants to read a previous okstra report to continue work based on its findings. Trigger words include "find report", "show report for", "read the okstra report", "continue from report".
+user-invocable: false
 ---
 
 # OKSTRA Report Finder

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

@@ -172,6 +172,12 @@ The Korean translation in parentheses is optional but the English keyword is man
 
 The final-report template `okstra-final-report.template.md` Section 4.5 already encodes this contract — copy that block verbatim and fill in.
 
+### Release-handoff section contract (release-handoff runs only)
+
+When the run's `task-type` is `release-handoff`, the final report MUST include Section `## 4.6 Release Handoff Deliverables` with all seven sub-sections (`4.6.1` Source Verification Report, `4.6.2` Feature Branch & Working-Tree State, `4.6.3` User Selections, `4.6.4` Executed Commands, `4.6.5` Commit List, `4.6.6` Pull Request Outcome, `4.6.7` Routing Recommendation). The drafter does **not** invent values for these sub-sections — every entry is dictated by the lead's recorded git/gh command log and the user's verbatim answers to the H1/H2/H3 menu prompts. If the user picked `skip` (H1) or `cancel` (H3), keep 4.6.3 populated but leave 4.6.4–4.6.6 explicitly empty per the template's empty-state lines.
+
+The final-report template `okstra-final-report.template.md` Section 4.6 already encodes this contract — copy that block verbatim and fill in. For non-`release-handoff` runs, omit Section 4.6 entirely.
+
 ### Mandatory worker-results file (BLOCKING)
 
 You (the report-writer-worker subagent) MUST also write a worker-results audit file at the path the lead provides as `**Worker Result Path:**`, defaulting to:

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

@@ -116,7 +116,7 @@ Validate that slugified `task_group` and `task_id` each contain at least one alp
 
 ## Step 4: Choose task-type
 
-`AskUserQuestion` with five fixed options:
+`AskUserQuestion` with six fixed options:
 
 | Option | Description |
 |---|---|
@@ -125,6 +125,7 @@ Validate that slugified `task_group` and `task_id` each contain at least one alp
 | `implementation-planning` | Plan options + request user approval |
 | `implementation` | Execute approved plan (requires `--approved-plan`) |
 | `final-verification` | Acceptance + residual-risk review |
+| `release-handoff` | Drive commit / push / PR with user-selected actions after `accepted` final-verification |
 
 For existing tasks, present `nextRecommendedPhase` as the first option (recommended default).