okstra 0.8.0 → 0.9.0

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).
 

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

@@ -128,6 +128,7 @@ Output format:
 - `implementation-planning`: `<state>`
 - `implementation`: `<state>`
 - `final-verification`: `<state>`
+- `release-handoff`: `<state>`
 
 ### Safe Resume Checkpoint
 
@@ -147,7 +148,8 @@ The status response always includes one of the following options:
 2. **Restart current phase**
 - Indicates whether the task can be re-run with the same `task-key` and the current `taskType`.
 3. **Start next phase**
-- If `workflow.nextRecommendedPhase` is one of `error-analysis`, `implementation-planning`, or `final-verification`, that phase is proposed as the next candidate for the Okstra run.
+- If `workflow.nextRecommendedPhase` is one of `error-analysis`, `implementation-planning`, `final-verification`, or `release-handoff`, that phase is proposed as the next candidate for the Okstra run.
+- If `nextRecommendedPhase` is `pending-release-handoff`, the prior `final-verification` run completed but its verdict still has to be inspected before entering `release-handoff` — surface this as a verdict-gated next step and present `release-handoff` as a candidate only when the cited verdict is `accepted`.
 4. **Need more information**
 - If `nextRecommendedPhase` is `pending-routing-decision` or `routingStatus` is `pending`, this indicates that additional information is required.
 

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -209,6 +209,25 @@ A successful worker result must include the following sections in this exact ord
 
 Code evidence must include file paths and line numbers.
 
+### Ticket Tagging (mandatory for sections 1–5)
+
+Every item in sections 1–5 MUST be tagged with the ticket(s) it relates to. This applies whenever the run's task type is `requirements-discovery`, `error-analysis`, `implementation-planning`, or `implementation`.
+
+- **Table-form items**: include a `Ticket ID` column. The column is placed immediately after the row-ID column (e.g. after `F-001`, `M-001`).
+- **Bullet / numbered-list items**: prepend `[TICKETID: <id>]` to the item title, immediately after the row ID and before the body text. Example: `- F-001 [TICKETID: TICKET-123] — <summary> (path:line)`.
+- **Section headers in the final report** (e.g. `### 4.5.3 Recommended Option`): append `[TICKETID: <id>]` to the header when the section is scoped to a specific ticket. Headers that span all tickets in the run omit the tag.
+
+Ticket ID fill rule (in order):
+
+1. Use the `Issue / Ticket` value from the run's input template.
+2. If empty, fall back to the `Task ID` value (no prefix; write `8852` not `task:8852`).
+3. If both are absent, write `unknown`. This is allowed but signals an input-template defect — the worker SHOULD also record a `Missing Information` item noting the absent identifier.
+4. When a single item maps to multiple tickets, separate them with commas: `TICKET-123, TICKET-456`. Ticket IDs containing commas are not supported.
+
+Workers MUST apply these rules to every item in sections 1–5. Lead and report-writer MUST preserve the tagging when carrying worker findings into the final report.
+
+For phases other than the four listed above (e.g. `release-handoff`, `final-verification`), ticket tagging is optional.
+
 ### Optional errors sidecar (worker-reported)
 
 A worker MAY produce an errors sidecar file at:

package/runtime/skills/okstra-time-summary/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: okstra-time-summary
 description: Use when the user asks how long an okstra task took, time spent per task type, per-worker elapsed time, or for a duration/runtime breakdown of a specific task-id. Trigger words include "작업 시간", "소요 시간", "time summary", "duration", "elapsed", "얼마나 걸렸", "시간 분석".
+user-invocable: false
 ---
 
 # OKSTRA Time Summary

package/runtime/templates/reports/error-analysis-input.template.md

@@ -7,6 +7,7 @@
 - Task ID:
 - Related Tasks:
 - Issue / Ticket:
+  - 값이 비면 워커는 `Task ID`로 폴백한다 (prefix 없이 `8852`처럼). 한 run이 여러 ticket을 동시에 다루면 콤마로 구분 (`TICKET-123, TICKET-456`). 어느 쪽으로도 식별 불가하면 `unknown`을 허용한다.
 - Task Type: `error-analysis`
 - Requested Outcome:
 

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

@@ -28,6 +28,23 @@
 - Summarize the core problem, requirement, or verification target in 3 to 5 bullets.
 - Base the summary on the brief, source materials, and worker results.
 
+## Ticket Coverage
+
+이 run이 다룬 ticket을 한 자리에서 확인하는 인덱스 표입니다. 본 보고서의 본문 항목들은 모두 `Ticket ID` 컬럼 또는 `[TICKETID: <id>]` 태그로 ticket과 묶여 있으며, 이 표는 그 역방향 인덱스입니다.
+
+- 한 run이 단일 ticket만 다루는 경우: 표 대신 다음 한 줄로 대체할 수 있습니다 — `- Single ticket run: <TICKET-or-task-fallback>`
+- 다중 ticket이거나, `Issue / Ticket`이 비어 `Task ID` 폴백을 쓴 항목이 섞여 있는 경우: 표를 채웁니다.
+
+| Ticket ID | 등장 섹션 | 관련 항목 IDs |
+|-----------|-----------|---------------|
+| `<TICKET-123>` | `1.1, 3.1, 4.5.4` | `F-001, F-003, A1` |
+
+규칙:
+
+- `Ticket ID` 컬럼은 본문에서 등장한 ticket 키와 정확히 동일한 문자열을 사용합니다. `Issue / Ticket`이 비어 폴백된 경우 `Task ID` 값을 prefix 없이 그대로 적습니다 (예: `8852`). 어느 쪽으로도 식별 불가한 경우 `unknown`을 사용합니다.
+- `등장 섹션`은 본 보고서의 섹션 번호를 콤마로 구분합니다. 동일 ticket이 여러 섹션에 등장하면 모두 나열합니다.
+- `관련 항목 IDs`는 `F-001`, `M-002`, `A1`, `Q1` 같은 row ID를 콤마로 나열합니다. 섹션 헤더 단위로만 ticket이 표시된 경우(개별 row ID가 없는 경우)에는 헤더 번호 자체를 적습니다 (예: `4.5.3`).
+
 ## Execution Status by Agent
 - Summarize the status, assigned model, and key finding for each worker.
 - Do not replace worker outputs with unsupported claims.
@@ -46,11 +63,20 @@
 
 ## 1. Cross Verification Results
 ### 1.1 Consensus
-- Record the conclusions and evidence that multiple workers support.
+
+| ID | Ticket ID | Statement | Supporting workers | Evidence (path:line / log / worker report) |
+|----|-----------|-----------|--------------------|---------------------------------------------|
+| C-001 | `<TICKET-or-fallback>` | <합의된 결론> | claude, codex, gemini | <증거 위치> |
+
+- 합의된 결론을 row마다 기록합니다. `Ticket ID`는 본 보고서 상단 `Ticket Coverage` 규칙을 따릅니다.
 
 ### 1.2 Differences
-- Record meaningful differences in conclusions, interpretation, or evidence handling.
-- If there is no meaningful difference, state that clearly.
+
+| ID | Ticket ID | Disagreement | Workers (position) | Evidence |
+|----|-----------|--------------|--------------------|----------|
+| D-001 | `<TICKET-or-fallback>` | <차이 요약> | claude (A) / codex (B) / gemini (-) | <증거 위치> |
+
+- 유의미한 차이가 없을 경우 표 대신 다음 한 줄을 적습니다 — `- 유의미한 차이 없음. 1.1 Consensus가 그대로 유효합니다.`
 
 ## 2. Final Verdict
 - State the final conclusion clearly.
@@ -58,14 +84,26 @@
 
 ## 3. Evidence and Detailed Analysis
 ### 3.1 Primary Evidence
-- Cite concrete evidence such as file paths, line numbers, brief contents, logs, or worker reports.
+
+| ID | Ticket ID | Evidence | Source (path:line / log / worker report) |
+|----|-----------|----------|------------------------------------------|
+| E-001 | `<TICKET-or-fallback>` | <증거 한 줄 요약> | <출처> |
 
 ### 3.2 Secondary Evidence or Alternate Interpretations
-- Record supporting evidence, alternate hypotheses, or lower-confidence interpretations when relevant.
+
+| ID | Ticket ID | Hypothesis or supporting evidence | Source / confidence |
+|----|-----------|-----------------------------------|---------------------|
+| S-001 | `<TICKET-or-fallback>` | <보조 증거 또는 대안 해석> | <출처 + low/mid> |
+
+- 해당 없음 시: `- 보조 증거 또는 대안 해석 없음.`
 
 ## 4. Missing Information and Risks
-- Explicitly state any item that requires `I don't know` or `uncertain`.
-- Record the missing information and risks that weaken the current conclusion.
+
+| ID | Ticket ID | Item | Risk if ignored |
+|----|-----------|------|-----------------|
+| R-001 | `<TICKET-or-fallback>` | <누락 정보 또는 불확실 항목> | <무시할 때의 위험> |
+
+- `I don't know` / `uncertain`으로 표기해야 하는 항목은 모두 표 안에 두고 본문 산문 형식으로 흩지 않습니다.
 
 ## 4.5 Implementation Plan Deliverables (implementation-planning runs only)
 
@@ -75,7 +113,11 @@
 
 ### 4.5.1 Option Candidates (옵션 후보)
 - 최소 두 개의 구현 옵션을 제시합니다. 각 옵션마다 다음을 포함합니다.
-  - **File Structure**: `Create: <path> — <responsibility>` / `Modify: <path>:<line-range> — <change summary>` / `Delete: <path> — <reason>` 형식으로 파일 단위 책임을 한 줄씩 명시합니다.
+  - **File Structure**: 다음 표 형식으로 파일 단위 책임을 한 줄씩 명시합니다. 행마다 `Ticket ID` 컬럼을 채웁니다.
+
+    | ID | Ticket ID | Action | Path (and line-range) | Change summary |
+    |----|-----------|--------|------------------------|----------------|
+    | OF-001 | `<TICKET-or-fallback>` | Create / Modify / Delete | `<path>[:<line-range>]` | <한 줄 요약> |
   - 영향을 받는 인터페이스 / 공개 계약 / 다운스트림 소비자.
   - 폭발 반경 추정(units, configs, deployment manifests, data migrations).
 
@@ -88,15 +130,30 @@
 - 어떤 옵션을 권장하는지와 이유를 작성합니다. 근거는 `4.5.2`의 비교 결과 + 디자인 원칙(isolation, files-that-change-together, follow-established-patterns, YAGNI)에 묶어 설명합니다.
 
 ### 4.5.4 Stepwise Execution Order (단계별 실행 순서)
-1. 한 단계는 약 2~5분 안에 완료할 수 있는 작은 작업이어야 합니다(예: "X에 실패하는 테스트 작성", "테스트 실행해 실패 확인", "최소 구현", "테스트 통과 확인", "commit").
-2. 모든 단계는 정확한 파일 경로와 정확한 명령어를 포함해야 합니다. 코드 단계라면 실제 코드 또는 diff 스케치를 함께 적습니다.
-3. TDD 순서(failing test → implementation → green → commit)가 가능한 영역이라면 이 순서를 따릅니다.
+
+| Step | Ticket ID | Action (≤ 5min) | Files | Command / Test | Expected outcome |
+|------|-----------|------------------|-------|----------------|-------------------|
+| 1 | `<TICKET-or-fallback>` | <예: 실패하는 테스트 작성> | `tests/foo_test.py` | `pytest tests/foo_test.py::test_x -v` | FAIL with <reason> |
+
+규칙:
+
+- 한 step은 약 2~5분 안에 완료할 수 있는 작은 작업이어야 합니다(예: "X에 실패하는 테스트 작성", "테스트 실행해 실패 확인", "최소 구현", "테스트 통과 확인", "commit").
+- 모든 step은 정확한 파일 경로와 정확한 명령어를 포함합니다. 코드 단계라면 실제 코드 또는 diff 스케치를 함께 적습니다 (`Action` 셀에 줄바꿈 가능).
+- TDD 순서(failing test → implementation → green → commit)가 가능한 영역이라면 이 순서를 따릅니다.
+- 한 step이 여러 ticket을 동시에 진행한다면 `Ticket ID`에 콤마로 함께 적습니다.
 
 ### 4.5.5 Dependency / Migration Risk (의존성·마이그레이션 위험)
 - 순서 제약, 데이터 백필, feature-flag 선행 조건, 팀 간 조율 등을 모두 나열합니다.
 
 ### 4.5.6 Validation Checklist (검증 체크리스트)
-- pre / mid / post 검증 항목을 각각 정확한 명령어 또는 관찰 가능한 결과로 적습니다. 추상적 서술은 금지.
+
+| Phase | Ticket ID | Check | Command / Observation | Expected outcome |
+|-------|-----------|-------|------------------------|-------------------|
+| pre   | `<TICKET-or-fallback>` | <체크 이름> | `<정확한 명령어 또는 관찰 지점>` | <기대 출력 / 상태> |
+| mid   | `<TICKET-or-fallback>` | <체크 이름> | `<...>` | <...> |
+| post  | `<TICKET-or-fallback>` | <체크 이름> | `<...>` | <...> |
+
+추상적 서술 금지. 모든 row는 명령어 또는 관찰 가능한 결과를 포함해야 합니다.
 
 ### 4.5.7 Rollback Strategy (롤백 전략)
 - 정확한 revert 경로(commits, flags, migrations 등)와 롤백을 트리거하는 신호(에러율, latency, 사용자 보고 등)를 명시합니다.
@@ -108,6 +165,60 @@
 ### 4.5.9 Open Questions
 - pre-planning에서 발견된 모든 모호점을 항목으로 남겨, 사용자가 승인 전에 해소해야 할 질문 목록으로 사용합니다.
 
+## 4.6 Release Handoff Deliverables (release-handoff runs only)
+
+> **이 섹션은 `task-type` = `release-handoff` 실행 결과에만 포함하세요. 다른 task-type에서는 섹션 전체를 삭제하고 5번 섹션으로 넘어갑니다.**
+>
+> 이 섹션은 git/gh mutating 명령이 실행된 phase의 감사 기록입니다. 모든 mutating command 는 반드시 위 `User Selections` 표의 사용자 응답과 1:1로 대응되어야 하며, 대응되지 않는 mutating command 가 있으면 self-review 가 `contract-violated` 로 종료해야 합니다.
+
+### 4.6.1 Source Verification Report (선행 final-verification 인용)
+- Path (project-relative): `<runs/final-verification/.../reports/final-report-final-verification-<seq>.md>`
+- Quoted final verdict line (정확히 `accepted` 토큰을 포함해야 함):
+  > <원문 인용>
+- 만약 원본 verdict 가 `accepted` 가 아니라면 본 run 은 **실행되지 않아야 했습니다**. self-review 단계에서 contract-violated 로 처리하고 routing 을 `final-verification` 으로 되돌립니다.
+
+### 4.6.2 Feature Branch & Working-Tree State (run 시작 시점)
+- Feature branch (`git rev-parse --abbrev-ref HEAD`): `<branch-name>`
+- `git status --short` 출력:
+  ```
+  <원문 그대로>
+  ```
+- 기존 PR 존재 여부 (`gh pr list --head <branch> --state open --json url --jq '.[0].url'`): `<URL or empty>`
+
+### 4.6.3 User Selections (메뉴 응답 기록)
+| 질문 ID | 질문 본문 | 사용자 응답 (원문) | 응답이 가능한 보기 |
+|---------|-----------|--------------------|--------------------|
+| H1 | 어떤 작업을 실행할까요? | <`commit only` / `commit + PR` / `skip`> | `commit only` / `commit + PR` / `skip` |
+| H2 | PR base 브랜치를 골라주세요. (H1=`commit + PR` 인 경우에만 묻습니다) | <`staging` / `preprod` / `prod` / `main` / `dev` / 사용자가 입력한 브랜치명> | `staging` / `preprod` / `prod` / `main` / `dev` / 직접 입력 |
+| H3 | 워커가 작성한 commit 메시지 / PR 본문 초안을 어떻게 처리할까요? | <`use as-is` / `edit then proceed` / `cancel`> | `use as-is` / `edit then proceed` / `cancel` |
+
+H1 이 `skip` 이거나 H3 가 `cancel` 인 경우, 본 섹션 다음의 4.6.4 ~ 4.6.6 은 빈 결과로 채우고 (mutating 명령 미실행) 4.6.7 routing 만 채웁니다.
+
+### 4.6.4 Executed Commands (실행한 git / gh 명령 로그)
+- **Mutating commands**: 정확한 명령행 / exit code / 한 줄 stdout 요약을 한 행씩 모두 기록합니다. 누락은 contract-violated 입니다.
+- **Read-only inspection commands**: 요약 또는 명령행 목록만 적어도 됩니다.
+
+| # | command (verbatim) | exit code | stdout/stderr 요약 |
+|---|---------------------|-----------|--------------------|
+| 1 | `<예: git add path/to/file.py>` | `0` | `<요약>` |
+
+### 4.6.5 Commit List (생성된 commit)
+- 각 commit 의 short SHA / full SHA / subject / 영향 파일 목록을 한 항목씩 기록합니다.
+- staged 변경이 없어 commit 이 만들어지지 않았다면 다음 한 줄만 적습니다.
+  > `- No commit was produced (working tree had no staged changes).`
+
+### 4.6.6 Pull Request Outcome (PR 결과)
+- 다음 네 가지 중 정확히 하나의 형식으로 한 줄을 적습니다.
+  - `- No PR action requested.` (H1=`commit only` 또는 `skip` 인 경우)
+  - `- PR created: <url>` + 타이틀 + base 브랜치
+  - `- PR reused: <url>` (run 시작 시점에 같은 head 의 open PR 이 이미 존재해 `gh pr create` 를 생략한 경우)
+  - `- PR creation skipped: <reason>` (H3=`cancel`, 또는 push/PR 생성 도중 사용자가 중단 지시한 경우. reason 은 풀어 쓴 한 문장)
+
+### 4.6.7 Routing Recommendation (마지막 phase 라우팅)
+- `release-handoff` 는 lifecycle 의 종착 phase 이므로 일반적으로 `done` 으로 라우팅합니다.
+- 단, H1=`skip` 또는 H3=`cancel` 로 종료된 경우 사용자가 추후 재진입해 다시 release-handoff 를 실행할 수 있는지 한 줄로 명시합니다.
+- 형식 예시: `- Routing: done. PR <url> opened against <base>; no follow-up required.`
+
 ## 5. Clarification Requests for the Next Run
 
 이 섹션은 다음 run으로 넘어가기 전에 사용자에게 받아야 할 입력을 정리하는 자리입니다. `task-type`이 `error-analysis` 또는 `requirements-discovery`이고 지금까지의 증거만으로는 확신 있는 최종 판단이 어려울 때 반드시 채웁니다. 그 외의 `task-type`에서는 lead가 추가 run이 필요하다고 판단했을 때만 채우고, 그렇지 않다면 `- 추가 정보 요청 없음. Section 2의 최종 판단이 그대로 유효합니다.` 라고만 한 줄 적은 뒤 Section 6으로 넘어갑니다.
@@ -130,9 +241,9 @@
 
 이 하위 섹션에는 **사용자가 다음 run 전에 첨부 또는 공유해 주셨으면 하는 자료**만 적습니다. 질문이 아니라 자료 요청입니다. 자료가 어디에 있는지(파일 경로, 페이지 URL, 데이터베이스 쿼리 결과 등), 어떤 시점/조건의 데이터를 받아야 하는지, 받은 자료를 어디에 두면 되는지(예: `<project-root>/.project-docs/<task-group>/<task-id>/` 아래)를 함께 적습니다. 받을 자료가 없다면 `- 추가로 요청드릴 자료가 없습니다.` 한 줄만 남깁니다.
 
-| 자료 ID | 무엇을 / 왜 필요한지 (문장으로 서술) | 어디에서 가져올 수 있는지 (파일 경로, 시스템 이름, URL 등) | 어디에 두면 되는지 / 어떻게 전달해 주실지 | Status | 사용자가 첨부한 위치 또는 메모 (다음 run 전에 사용자가 채움) |
-|---------|--------------------------------------|------------------------------------------------------------|--------------------------------------------|--------|---------------------------------------------------------------|
-| A1 | <어떤 자료를 왜 받아야 하는지를 1~2문장으로. 예: "오류가 처음 보고된 시각 전후 30분 동안의 worker 로그가 필요합니다. 어떤 task가 실패했고 그때 큐에 무엇이 쌓여 있었는지를 함께 확인해야 root cause 가설을 좁힐 수 있기 때문입니다." > | <예: "Datadog 로그에서 `service:worker env:prod` 필터, 시각 범위 2026-04-30 09:30~10:30 KST" / 또는 정확한 파일 경로> | <예: "`.project-docs/tasks/8852/logs/` 아래에 `worker-2026-04-30.log` 라는 이름으로 저장해 주시면 됩니다."> | open | <빈칸으로 두고 다음 run 전에 사용자가 채움> |
+| 자료 ID | Ticket ID | 무엇을 / 왜 필요한지 (문장으로 서술) | 어디에서 가져올 수 있는지 (파일 경로, 시스템 이름, URL 등) | 어디에 두면 되는지 / 어떻게 전달해 주실지 | Status | 사용자가 첨부한 위치 또는 메모 (다음 run 전에 사용자가 채움) |
+|---------|-----------|--------------------------------------|------------------------------------------------------------|--------------------------------------------|--------|---------------------------------------------------------------|
+| A1 | `<TICKET-or-fallback>` | <어떤 자료를 왜 받아야 하는지를 1~2문장으로. 예: "오류가 처음 보고된 시각 전후 30분 동안의 worker 로그가 필요합니다. 어떤 task가 실패했고 그때 큐에 무엇이 쌓여 있었는지를 함께 확인해야 root cause 가설을 좁힐 수 있기 때문입니다." > | <예: "Datadog 로그에서 `service:worker env:prod` 필터, 시각 범위 2026-04-30 09:30~10:30 KST" / 또는 정확한 파일 경로> | <예: "`.project-docs/tasks/8852/logs/` 아래에 `worker-2026-04-30.log` 라는 이름으로 저장해 주시면 됩니다."> | open | <빈칸으로 두고 다음 run 전에 사용자가 채움> |
 
 ### 5.2 사용자 확인 질문 (Questions for the User)
 
@@ -144,9 +255,9 @@
 - **무엇을 묻는가**: 약어 없이 풀어 쓴 완전한 문장의 질문.
 - **어떤 형태의 답을 기대하는가**: 예/아니오인지, 둘 중 하나를 고르는 선택인지, 숫자/날짜/파일경로인지, 아니면 짧은 자유서술인지. 가능하면 보기를 함께 제시합니다.
 
-| 질문 ID | 이 답이 필요한 이유 (왜) | 질문 본문 (무엇을 묻는지, 풀어 쓴 문장) | 기대하는 답의 형태 / 보기 | Blocking (예 / 아니오) | Status | 사용자 답변 (다음 run 전에 사용자가 채움) |
-|---------|--------------------------|-----------------------------------------|----------------------------|------------------------|--------|--------------------------------------------|
-| Q1 | <예: "이 결정에 따라 `bugfix`로 이어갈지 `feature`로 이어갈지가 갈리며, 다음 run에서 사용할 task-type이 달라집니다."> | <예: "지난 주 새벽에 보고된 결제 실패가 일회성 사고였는지, 아니면 같은 증상이 다시 발생한 적이 있는지 알려주실 수 있을까요? 같은 증상이 다시 발생했다면 가장 최근 발생 시각과 영향 받은 사용자 수도 함께 부탁드립니다."> | <예: "다음 중 한 줄로 답해 주시면 됩니다 — (a) 일회성으로 그 후 재발 없음, (b) 재발 있음, 가장 최근 시각: YYYY-MM-DD HH:MM, 영향 사용자 수 약 N명"> | 예 | open | <빈칸으로 두고 다음 run 전에 사용자가 채움> |
+| 질문 ID | Ticket ID | 이 답이 필요한 이유 (왜) | 질문 본문 (무엇을 묻는지, 풀어 쓴 문장) | 기대하는 답의 형태 / 보기 | Blocking (예 / 아니오) | Status | 사용자 답변 (다음 run 전에 사용자가 채움) |
+|---------|-----------|--------------------------|-----------------------------------------|----------------------------|------------------------|--------|--------------------------------------------|
+| Q1 | `<TICKET-or-fallback>` | <예: "이 결정에 따라 `bugfix`로 이어갈지 `feature`로 이어갈지가 갈리며, 다음 run에서 사용할 task-type이 달라집니다."> | <예: "지난 주 새벽에 보고된 결제 실패가 일회성 사고였는지, 아니면 같은 증상이 다시 발생한 적이 있는지 알려주실 수 있을까요? 같은 증상이 다시 발생했다면 가장 최근 발생 시각과 영향 받은 사용자 수도 함께 부탁드립니다."> | <예: "다음 중 한 줄로 답해 주시면 됩니다 — (a) 일회성으로 그 후 재발 없음, (b) 재발 있음, 가장 최근 시각: YYYY-MM-DD HH:MM, 영향 사용자 수 약 N명"> | 예 | open | <빈칸으로 두고 다음 run 전에 사용자가 채움> |
 
 ## 6. Recommended Next Steps
 

package/runtime/templates/reports/implementation-input.template.md

@@ -7,6 +7,7 @@
 - Task ID:
 - Related Tasks:
 - Issue / Ticket:
+  - 값이 비면 워커는 `Task ID`로 폴백한다 (prefix 없이 `8852`처럼). 한 run이 여러 ticket을 동시에 다루면 콤마로 구분 (`TICKET-123, TICKET-456`). 어느 쪽으로도 식별 불가하면 `unknown`을 허용한다.
 - Task Type: `implementation`
 - Requested Outcome:
 

package/runtime/templates/reports/implementation-planning-input.template.md

@@ -7,6 +7,7 @@
 - Task ID:
 - Related Tasks:
 - Issue / Ticket:
+  - 값이 비면 워커는 `Task ID`로 폴백한다 (prefix 없이 `8852`처럼). 한 run이 여러 ticket을 동시에 다루면 콤마로 구분 (`TICKET-123, TICKET-456`). 어느 쪽으로도 식별 불가하면 `unknown`을 허용한다.
 - Task Type: `implementation-planning`
 - Requested Outcome:
 

package/runtime/templates/reports/quick-input.template.md

@@ -7,6 +7,7 @@
 - Task ID:
 - Related Tasks:
 - Issue / Ticket:
+  - 값이 비면 워커는 `Task ID`로 폴백한다 (prefix 없이 `8852`처럼). 한 run이 여러 ticket을 동시에 다루면 콤마로 구분 (`TICKET-123, TICKET-456`). 어느 쪽으로도 식별 불가하면 `unknown`을 허용한다.
 - Requested Task Type:
 - Requested Outcome: