okstra 0.8.0 → 0.10.0

package/docs/superpowers/specs/2026-05-12-ticket-id-in-reports-design.md

@@ -0,0 +1,131 @@
+# Ticket ID in Worker / Lead / Report Outputs — Design
+
+- Date: 2026-05-12
+- Scope: okstra phases `requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`
+- Status: Implemented
+- Implementation plan: `docs/superpowers/plans/2026-05-12-ticket-id-in-reports.md`
+
+## 1. 목적
+
+okstra의 작업 단위는 보통 외부 트래커의 ticket과 1:1로 묶이지만, 현재 워커·lead·report-writer 산출물은 보고서 헤더의 `Task Key` 한 곳에서만 ticket을 식별한다. 항목별로 어떤 ticket을 다루고 있는지 추적할 수 없어, 한 run이 여러 ticket을 동시에 다룰 때 항목·ticket 매핑이 누락된다.
+
+본 변경은 워커가 작성하는 모든 항목과 final report의 본문 섹션에 ticket 식별자를 박아 trace를 ticket 단위로 동기화한다.
+
+## 2. Ticket ID 채움 규칙 (모든 산출물 공통)
+
+1. 입력 템플릿의 `Issue / Ticket` 값을 우선 사용한다.
+2. 비어 있으면 `Task ID`로 폴백한다. 폴백 표기에는 prefix를 붙이지 않는다 (예: `8852`).
+3. `Issue / Ticket`도 비고 `Task ID`도 사용할 수 없는 예외 상황에 한해 `unknown` 표기를 허용한다.
+4. 한 항목이 여러 ticket을 동시에 다루면 쉼표로 구분한다 (예: `TICKET-123, TICKET-456`).
+
+## 3. 표기 규칙
+
+### 3.1 표 형식 섹션
+표 형식 섹션은 `Ticket ID` 컬럼을 추가한다. 컬럼은 표의 가장 왼쪽 ID 컬럼 바로 다음에 위치한다.
+
+### 3.2 비-표 섹션 (bullet / 번호 목록 / 섹션 헤더)
+항목 또는 섹션 헤더의 타이틀에 `[TICKETID: <id>]` 태그를 강제한다.
+
+- 항목 예: `- F-001 [TICKETID: TICKET-123] — <summary> (path:line)`
+- 헤더 예: `### 4.5.3 Recommended Option [TICKETID: TICKET-123]`
+
+태그는 ID 직후, 본문 텍스트 앞에 위치한다. 한 줄 안에서 태그가 보이지 않으면 contract violation이다.
+
+## 4. 변경 파일
+
+### 4.1 `skills/okstra-team-contract/SKILL.md`
+- Worker Output Contract 섹션에 "Ticket Tagging" 항목 신설.
+- 섹션 1 Findings, 2 Missing Information / Assumptions, 3 Safe or Reasonable Areas, 4 Uncertain Points, 5 Recommended Next Actions 모두에 적용된다는 점을 명시.
+- bullet 항목은 `[TICKETID: ...]` 태그 강제, 표 항목은 `Ticket ID` 컬럼 강제.
+- 폴백/다중 ticket/`unknown` 규칙을 본 spec과 동일한 문구로 인용.
+
+### 4.2 `skills/okstra-convergence/SKILL.md`
+- Round 0 (Parse worker results)에 ticket 추출 절차 추가.
+- finding 그룹핑 시 ticket이 다르면 의미가 유사해도 별도 그룹으로 처리해 과병합을 방지한다는 규칙 추가.
+- 컨버전스 상태 아티팩트에 각 finding의 `ticketId` 필드를 함께 기록.
+
+### 4.3 `templates/reports/final-report.template.md`
+- 보고서 상단(`## Summary of the Problem or Verification Target` 직후)에 `## Ticket Coverage` 표 신규 추가.
+
+  | Ticket ID | 등장 섹션 | 관련 항목 IDs |
+  |-----------|-----------|---------------|
+
+  - 한 run에 ticket이 0~1개면 단일 행으로 채우거나 `- Single ticket run: <id>` 한 줄로 대체 가능.
+  - 다중 ticket이면 ticket마다 한 행씩 작성하고, `등장 섹션` 컬럼에는 본문에서 해당 ticket이 나타나는 섹션 번호를 콤마 구분으로, `관련 항목 IDs` 컬럼에는 `F-001`, `A1`, `Q1` 등 항목 ID를 콤마 구분으로 적는다.
+
+- `1.1 Consensus`, `1.2 Differences` → bullet에서 표로 전환.
+
+  | ID | Ticket ID | Statement | Supporting workers | Evidence |
+  |----|-----------|-----------|--------------------|----------|
+
+- `3.1 Primary Evidence`, `3.2 Secondary Evidence or Alternate Interpretations` → 표로 전환.
+
+  | ID | Ticket ID | Evidence | Source (path:line / log / worker) |
+  |----|-----------|----------|------------------------------------|
+
+- `4. Missing Information and Risks` → 표로 전환.
+
+  | ID | Ticket ID | Item | Risk if ignored |
+  |----|-----------|------|-----------------|
+
+- `4.5.1 Option Candidates`: 옵션별 File Structure 표에 `Ticket ID` 컬럼 추가.
+- `4.5.2 Trade-off Matrix`: 컬럼 변경 없음 (옵션 단위 매트릭스이며 옵션 자체가 ticket scope를 가로지를 수 있다).
+- `4.5.4 Stepwise Execution Order`: 각 step 행에 `Ticket ID` 컬럼 추가 (현재 번호 목록이라면 표로 전환).
+- `4.5.6 Validation Checklist`: pre/mid/post 각 체크 행에 `Ticket ID` 컬럼 추가.
+- `5.1 추가 자료 요청`, `5.2 사용자 확인 질문`: 기존 표에 `Ticket ID` 컬럼을 두 번째 위치로 삽입 (`자료 ID` / `질문 ID` 다음).
+
+### 4.4 입력 템플릿
+대상 파일:
+- `templates/reports/error-analysis-input.template.md`
+- `templates/reports/implementation-planning-input.template.md`
+- `templates/reports/implementation-input.template.md`
+- `templates/reports/quick-input.template.md`
+
+변경:
+- `Identity` 섹션의 `Issue / Ticket:` 줄 바로 아래에 한 줄 가이드 추가.
+  > `Issue / Ticket` 값이 비면 워커는 `Task ID`로 폴백한다 (예: `8852`). 한 run에서 여러 ticket을 동시에 다루는 경우 쉼표로 구분한다 (`TICKET-123, TICKET-456`).
+
+### 4.5 `templates/reports/task-brief.template.md`
+- `Identity` 섹션에 동일한 폴백/다중 ticket 가이드 한 줄 추가.
+- `Questions for Workers > Standing Scope-Discipline Questions` 직전에 한 줄 추가: "모든 항목 및 표 행에 ticket을 명시해야 한다. 표 형식은 `Ticket ID` 컬럼, bullet/번호목록·섹션 헤더는 `[TICKETID: ...]` 태그를 사용한다. 자세한 규칙은 `okstra-team-contract` SKILL을 참조."
+
+### 4.6 워커 프롬프트
+대상 파일:
+- `agents/workers/claude-worker.md`
+- `agents/workers/codex-worker.md`
+- `agents/workers/gemini-worker.md`
+
+변경:
+- `Worker Output Structure` 절 끝에 한 단락 추가. 표기 규칙은 team-contract가 authoritative source임을 명시하고, 표/비-표 두 가지 형식과 폴백·다중 ticket·`unknown` 규칙을 한 번에 인용.
+
+### 4.7 `agents/workers/report-writer-worker.md`
+- final-report 작성 의무 절에 한 줄 추가: "워커 산출물의 `Ticket ID` 컬럼 및 `[TICKETID: ...]` 태그를 보존하고, 상단 `## Ticket Coverage` 표를 본 spec 규칙대로 채울 것."
+
+## 5. 손대지 않는 곳
+
+- 기존 `F-001`, `A1`, `Q1` 등 ID 카운터 체계 (전역 유일성 그대로 유지).
+- `User Approval Request` 체크박스, validator의 영문 키워드 매칭(`Option Candidates`, `Trade-off`, `Recommended Option`, `Stepwise Execution Order`, `Dependency`, `Validation Checklist`, `Rollback`, `User Approval Request`).
+- `release-handoff`, `final-verification` 산출물 및 그 phase의 워커/lead 출력.
+- 토큰 사용량 표, Execution Status 표 등 ticket scope와 무관한 메타 표.
+
+## 6. 영향과 위험
+
+- **convergence 파서**: bullet 한 줄 안에 ticket 태그가 함께 들어가 정규식 변경이 필요. ticket이 finding의 그룹핑 키 일부가 되므로 동일 root cause라도 ticket이 다르면 별도 그룹으로 처리된다. 의도된 동작.
+- **기존 보고서 호환성**: 본 변경은 신규 run에만 적용. 과거 보고서는 마이그레이션하지 않는다.
+- **워커가 ticket을 못 채우는 경우**: `unknown` 표기를 허용하지만, 이는 입력 템플릿이 잘못 채워졌다는 신호이므로 lead가 `Missing Information` 항목으로 함께 기록한다.
+- **다중 ticket 콤마 구분 vs 정규식**: ticket ID 자체에 콤마가 들어가는 경우는 없다고 가정한다. JIRA/GitHub/Linear 모두 콤마 미사용. 만약 향후 콤마를 포함한 ticket ID가 나오면 별도 escape 룰을 추가한다 (현재 spec에는 포함하지 않음).
+
+## 7. 검증
+
+- 신규 run 1건씩 phase별로 실행해 다음을 수동 확인:
+  - 입력 템플릿 가이드가 노출되는지.
+  - 워커 출력의 bullet 항목 전부에 `[TICKETID: ...]` 태그가 붙는지.
+  - 표 섹션에 `Ticket ID` 컬럼이 채워지는지.
+  - final report 상단 `## Ticket Coverage` 표가 본문 항목과 정합한지 (수동 cross-check).
+- `validators/` 디렉토리에 ticket 태그/컬럼 누락을 잡는 정적 체크를 추가하는 것은 후속 작업(이번 spec 범위 밖).
+
+## 8. 후속 작업 (이번 spec 범위 밖)
+
+- `validators/`에 ticket 표기 강제용 정적 검증기 추가.
+- `final-verification`, `release-handoff` phase에도 동일 규칙 확장 여부 결정.
+- `okstra-convergence` 상태 아티팩트 스키마에 `ticketId` 정식 필드화 (현재는 분류 키로만 사용).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.8.0",
-  "builtAt": "2026-05-12T09:54:25.514Z",
+  "package": "0.10.0",
+  "builtAt": "2026-05-12T16:26:44.380Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -107,6 +107,19 @@ Lead MUST dispatch Edit/Write-bearing work only through the `workerAgent` declar
 
 Executor is chosen at run-prep time via `--executor <claude|codex|gemini>` (or `OKSTRA_DEFAULT_EXECUTOR`, fallback `claude`); the model used by the executor is taken from the corresponding worker model flag (`--claude-model` / `--codex-model` / `--gemini-model`). For Codex/Gemini executors, the underlying file mutation happens inside the executor CLI's own auto-edit mode (e.g. `codex exec --full-auto`), not through Claude-side Edit/Write tools.
 
+#### Executor worktree (BLOCKING for `implementation`)
+
+For `--task-type implementation` runs, `okstra-ctl` provisions a dedicated `git worktree` at run-prep time. Lead, the Executor, and every verifier MUST treat the provisioned worktree as the canonical working directory.
+
+- Location: `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>-<run-seq>` (override `OKSTRA_HOME` only for tests).
+- Branch: `<work-category-prefix>-<task-id-segment>-<run-seq>` (e.g. `feat-dev-9436-001`, `fix-dev-7311-002`). Branched from `HEAD` of `project_root` at prep time; base SHA is recorded in `EXECUTOR_WORKTREE_BASE_REF`.
+- The worktree path, branch, base ref, and provisioning status (`created` | `skipped-in-worktree` | `skipped-not-git`) are exposed through the launch prompt's `## Executor Worktree` section and the implementation profile's worktree block.
+- **Skip conditions** (worktree provisioning is a no-op; executor uses `project_root` directly):
+  - `project_root` is already inside a non-main worktree (the run reuses the caller's worktree to avoid nesting).
+  - `project_root` is not inside a git repository at all.
+- **Failure mode**: any other error during `git worktree add` (path collision, branch collision, detached-HEAD with no SHA) raises `PrepareError`. Re-run after manually removing the stale path/branch — the worktree is intentionally not garbage-collected.
+- **Lifecycle**: kept after the run for manual PR authoring, rollback verification, and follow-up `final-verification` runs. Manual cleanup: `git -C <project_root> worktree remove <path>` then `git -C <project_root> branch -D <branch>`.
+
 ## Phase 1: Task-bundle intake and required reading order
 
 **REQUIRED SUB-SKILL:** Invoke [okstra-context-loader](./skills/okstra-context-loader/SKILL.md) first to discover task bundle paths.

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

@@ -69,6 +69,8 @@ When returning results, organize into the following sections in this exact order
 
 Include file paths and line numbers when discussing code evidence.
 
+**Ticket tagging:** For runs whose task type is `requirements-discovery`, `error-analysis`, `implementation-planning`, or `implementation`, every item in sections 1–5 MUST carry a ticket identifier. Use the `Ticket ID` column in table-form items and the `[TICKETID: <id>]` prefix in bullet/numbered items. Fill priority: `Issue / Ticket` from the input → `Task ID` (no prefix, e.g. `8852`) → `unknown`. Multiple tickets are comma-separated. Full rules live in the `okstra-team-contract` skill's Ticket Tagging section.
+
 This contract mirrors the `okstra-team-contract` skill's Worker Output Contract — that skill is the authoritative source if the two ever diverge.
 
 ## Stop Condition (BLOCKING)

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

@@ -123,6 +123,8 @@ When returning results, organize into the following sections in this exact order
 
 Include file paths and line numbers when discussing code evidence.
 
+**Ticket tagging:** For runs whose task type is `requirements-discovery`, `error-analysis`, `implementation-planning`, or `implementation`, every item in sections 1–5 MUST carry a ticket identifier. Use the `Ticket ID` column in table-form items and the `[TICKETID: <id>]` prefix in bullet/numbered items. Fill priority: `Issue / Ticket` from the input → `Task ID` (no prefix, e.g. `8852`) → `unknown`. Multiple tickets are comma-separated. Full rules live in the `okstra-team-contract` skill's Ticket Tagging section.
+
 This contract mirrors the `okstra-team-contract` skill's Worker Output Contract — that skill is the authoritative source if the two ever diverge.
 
 ## Error reporting

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

@@ -123,6 +123,8 @@ When returning results, organize into the following sections in this exact order
 
 Include file paths and line numbers when discussing code evidence.
 
+**Ticket tagging:** For runs whose task type is `requirements-discovery`, `error-analysis`, `implementation-planning`, or `implementation`, every item in sections 1–5 MUST carry a ticket identifier. Use the `Ticket ID` column in table-form items and the `[TICKETID: <id>]` prefix in bullet/numbered items. Fill priority: `Issue / Ticket` from the input → `Task ID` (no prefix, e.g. `8852`) → `unknown`. Multiple tickets are comma-separated. Full rules live in the `okstra-team-contract` skill's Ticket Tagging section.
+
 This contract mirrors the `okstra-team-contract` skill's Worker Output Contract — that skill is the authoritative source if the two ever diverge.
 
 ## Error reporting

package/runtime/agents/workers/report-writer-worker.md

@@ -62,6 +62,7 @@ Hard rules:
 - If only one analysis worker produced a usable result, perform a reduced-confidence write-up and say so explicitly.
 - If evidence is missing, write `I don't know` rather than fabricating confidence.
 - Cite file paths and line numbers for every code-evidence claim.
+- Preserve every analysis worker's ticket tagging (`Ticket ID` columns and `[TICKETID: <id>]` prefixes) when carrying findings into the final report. Populate the final report's top-level `## Ticket Coverage` table per the rules in `templates/reports/final-report.template.md`. For runs that do not require ticket tagging (e.g. `release-handoff`, `final-verification`), omit the `Ticket Coverage` table and do not invent ticket IDs.
 
 Write the file with your `Write` tool against the absolute `Result Path`. Do not return the report inline as your subagent response — the file on disk is the canonical artifact. Your subagent response should be a short status line: `Final report written to <abs path>. Worker-results pointer written to <pointer path>. Sections: <count>. Convergence categories represented: full=<n>, partial=<n>, contested=<n>, unique=<n>.`
 

package/runtime/prompts/launch.template.md

@@ -37,6 +37,17 @@ Invoke the `okstra` skill now. Read the manifests below for all task metadata, p
 - Final status: `{{FINAL_STATUS_RELATIVE_PATH}}`
 - Validator: `{{RUN_VALIDATOR_RELATIVE_PATH}}`
 
+## Executor Worktree
+
+- Status: `{{EXECUTOR_WORKTREE_STATUS}}`
+- Working tree path: `{{EXECUTOR_WORKTREE_PATH}}`
+- Branch: `{{EXECUTOR_WORKTREE_BRANCH}}`
+- Base ref: `{{EXECUTOR_WORKTREE_BASE_REF}}`
+- Note: `{{EXECUTOR_WORKTREE_NOTE}}`
+- For `implementation` runs with status `created`, the Executor MUST perform every Edit / Write / build / test command inside the working tree path above. Verifiers (Claude / Codex / Gemini) read from the SAME path so they observe the exact diff produced by the Executor.
+- The worktree is preserved after the run (no automatic cleanup). PR authoring, manual review, and rollback verification happen from the worktree branch.
+- For any other status (`skipped-non-implementation`, `skipped-in-worktree`, `skipped-not-git`), the run operates directly in `{{PROJECT_ROOT}}` and this section is informational only.
+
 ## Available MCP Servers
 
 {{AVAILABLE_MCP_SERVERS}}

package/runtime/prompts/profiles/_common-contract.md

@@ -0,0 +1,27 @@
+<!--
+Shared contract fragment included verbatim by every profile via the
+INCLUDE directive (see scripts/okstra_ctl/run.py:_expand_profile_includes).
+Edit here once; every profile picks the change up at next render. Do NOT
+add phase-specific rules to this file — phase rules stay in the per-
+profile document.
+-->
+- Team contract (shared):
+  - `Claude lead` is synthesis-only and stays distinct from `Claude worker` (or, in `implementation`, the `Executor` and verifiers).
+  - `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 centralised defaults; the fallback values are `Claude lead`/`Report writer worker`=`opus`, `Claude worker`=`sonnet`, `Codex worker`=`gpt-5.5`, `Gemini worker`=`auto`. Phase-specific overrides (e.g. `implementation`'s executor binding) live in the per-profile document.
+  - every required worker listed in the per-profile `Required workers:` block must be attempted; the final verdict waits until each has either a result or an explicit terminal status (`timeout`, `error`, `not-run`).
+  - unnamed generic parallel workers must not replace the required role roster, and no additional sub-agent dispatch is allowed beyond this roster.
+- Tooling — read-only MCP availability (shared):
+  - the read-only MCP servers declared in the task brief's `## Available MCP Servers` section may be queried as a read-only cross-check; 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. MCP MUST NEVER be used as a write path — schema/data mutations go through repository migration files reviewed by humans.
+- 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, in-flight, or follow-up 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 task brief explicitly states otherwise.
+  - Do NOT add such items to routing decisions, missing-materials lists, clarification questions, option trade-offs, dependency/migration risk, validation checklists, rollout plans, acceptance blockers, residual risks, release recommendations, `Open Questions`, or any day/effort estimate. 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.
+  - This rule does NOT relax any phase-specific Forbidden actions list; safety rules in the per-profile document remain in force regardless of the user's authority.
+- Anti-escalation rule (shared):
+  - treating "다음 단계 진행해" or equivalent user phrases as authorisation to start a *different* lifecycle phase is forbidden. The next phase begins only in a separate okstra run launched with the new `--task-type`. Per-profile documents may further restrict this within their own scope.
+- Clarification request policy (shared — applies whenever a profile uses `## 5. Clarification Requests for the Next Run`):
+  - section 5 MUST be split into two distinct sub-sections per `final-report-template.md` — `5.1 추가 자료 요청 (Additional Materials Requested)` for files/logs/screenshots/links the user must attach, and `5.2 사용자 확인 질문 (Questions for the User)` for decisions or facts only the user can confirm. Never mix material requests and decision questions in the same row or list.
+  - 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 next step, *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 next decision/verdict.

package/runtime/prompts/profiles/error-analysis.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 to confirm symptoms against live schema or to inspect rows that reproduce the failure; that section is the canonical source of which servers and tools exist for this run, and any MCP-derived hypothesis MUST cite server, table, and the SELECT used
+{{INCLUDE:_common-contract.md}}
 - Primary focus areas:
   - symptom and trigger clarification
   - root-cause candidates
@@ -27,17 +18,10 @@
   - evidence-backed cause analysis
   - uncertainty boundaries
   - practical next diagnostic steps
-- Clarification request policy:
+- Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
   - if any blocking uncertainty remains 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/logs/screenshots the user must attach, and `5.2 사용자 확인 질문 (Questions for the User)` for decisions or facts only the user can confirm. Never mix material requests and decision questions in the same row or list.
-  - write every entry in full, descriptive sentences that a non-developer can act on without further context. Avoid abbreviations and internal jargon (e.g. write "초당 평균 요청 수" instead of "QPS", "재현 절차" instead of "repro"). 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 next step, *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 deciding the verdict
-- 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 root-cause hypotheses, validation paths, missing-evidence lists, clarification questions, risk lists, 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.
+  - prefer plain Korean over abbreviations (e.g. write "초당 평균 요청 수" instead of "QPS", "재현 절차" instead of "repro")
 - Non-goals:
   - implementation details unless they are necessary to validate the cause
   - **source code edits, builds, migrations, or deployments** — this run produces evidence and cause analysis only; the fix belongs to a later `implementation-planning` run followed by an `implementation` run
-  - treating "다음 단계 진행해" or equivalent user phrases as authorisation to begin planning or coding — this run stays in `error-analysis` regardless of such phrasing
+  - this run stays in `error-analysis` regardless of user phrasing — the shared anti-escalation rule applies

package/runtime/prompts/profiles/final-verification.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 to verify that the delivered change matches the live schema, that expected rows exist after a migration, or that invariants in `reference-expectations.md` hold against the database; that section is the canonical source of which servers and tools exist for this run, and any MCP-derived blocker MUST cite server, table, and the SELECT used. MCP MUST NOT be used to perform fixes — defects become inputs to a new run.
+{{INCLUDE:_common-contract.md}}
 - Primary focus areas:
   - requirement coverage
   - whether delivered config files and deployment manifests satisfy the recorded expected values
@@ -34,23 +25,16 @@
   - **Validation Evidence**: for every requirement in the originating plan or task brief, cite the artifact (commit SHA, test output, log line, MCP SELECT result) that demonstrates coverage. Paraphrased "verified" claims without an artifact are rejected.
   - **Read-only command log**: any pre-existing test/validation command executed during this run MUST be listed with its exact command line and exit code. No mutating commands may appear here.
   - **Routing recommendation**: brief note on the next safe phase (`done`, `error-analysis`, `implementation-planning`) tied to the verdict and blocker list.
-- Clarification request policy:
-  - if a blocker hinges on information only the user can supply (deployment intent, intended target environment, business-rule interpretation), populate `## 5. Clarification Requests for the Next Run` in `final-report-template.md`
-  - section 5 must be split into `5.1 추가 자료 요청 (Additional Materials Requested)` and `5.2 사용자 확인 질문 (Questions for the User)` per the template. Never mix material requests and decision questions in the same row or list.
-  - 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 verdict, *what* is being asked in a complete sentence, and *what shape of answer* is expected (예/아니오, 보기 중 하나, 숫자/날짜, 짧은 서술 등); supply concrete option choices when applicable.
-  - the preferred turn-around is `scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<task-id>`; 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*` and `Q*` row in section 0 and update its `Status` (`resolved`, `obsolete`) before issuing the final verdict
+- Clarification request policy (phase-specific addendum — shared policy is in `_common-contract.md`):
+  - populate section 5 only when a blocker hinges on information only the user can supply (deployment intent, intended target environment, business-rule interpretation)
 - Self-review pass before finalising the report (`Claude lead` runs this; do not delegate to a generic subagent):
   1. **Verdict precision** — section 2 uses one of the three allowed verdict tokens; `conditional-accept` lists every condition as an actionable item.
   2. **Blocker traceability** — every blocker cites a concrete artifact (file:line, log excerpt, test exit code, MCP SELECT). Blockers without evidence are demoted to residual risk or removed.
   3. **Coverage check** — every requirement in the originating plan/task brief is either marked covered (with artifact) or listed as a blocker. No silent omissions.
   4. **Verifier dissent preserved** — if workers reach different verdicts, the disagreement is visible in section 1.2; synthesis hides nothing.
   5. **No-mutation audit** — scan the run's session transcripts for any Edit / Write / mutating Bash command. Any occurrence means the run has crossed into implementation and MUST be re-routed; do NOT silently strip the evidence.
-- 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 delivered and follow-up 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 task brief explicitly states otherwise.
-  - Do NOT raise such items as acceptance blockers, residual risks, or release recommendations, and do not factor them into any effort/day estimate for follow-up runs. They are not legitimate sources of schedule extension.
 - Non-goals:
   - proposing unrelated refactors beyond the delivered scope
   - **source code edits, follow-up bug fixes, or scope expansion** — this run renders a verdict only; defects detected here become inputs to a new `error-analysis` or `implementation-planning` run
   - read-only execution of pre-existing test or validation commands is permitted, but any command that mutates source, schema, or deployment state is forbidden
-  - treating "다음 단계 진행해" or equivalent user phrases as authorisation to fix detected issues inside this run — record the issues and end the run
+  - this run records detected issues and ends — the shared anti-escalation rule forbids in-run fixes regardless of user phrasing

package/runtime/prompts/profiles/implementation-planning.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 to size the blast radius of an option (table cardinality, column types, foreign-key fan-out, indexes), to validate migration assumptions, or to confirm that a proposed query shape returns the expected rows; that section is the canonical source of which servers and tools exist for this run, and any MCP-derived figure entering the trade-off matrix or risk assessment MUST cite server, table, and the SELECT used. MCP MUST NOT be used as a write path even when planning a migration — schema changes belong in migration files reviewed by humans.
+{{INCLUDE:_common-contract.md}}
 - Pre-planning context exploration (mandatory before option drafting):
   - read the task brief, related-task briefs, and any cited spec / design doc end-to-end
   - inspect the current state of every file the task names (or the closest matching files if names are stale) — record current responsibilities, public interfaces, and known coupling points
@@ -37,15 +28,13 @@
   - feasible plan options
   - dependency and risk visibility
   - recommended execution order
-- 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 option trade-offs, dependency/migration risk, validation checklists, rollout plans, `Open Questions`, or day/effort estimates. They are not legitimate sources of schedule extension; effort sizing must reflect engineering work only.
-  - The `User Approval Request (사용자 승인 게이트)` block at the **top of the final report** (immediately under the metadata header, before `Section 0`) is the only authorised approval gate — that gate is the user themselves, who clears it either by (a) editing the single checkbox `- [ ] Approved` to `- [x] Approved` directly, or (b) invoking the next phase with `--approve` so the CLI invocation itself is treated as the approval signal and the runtime flips the checkbox on the user's behalf. No external coordination is expected.
+- Approval gate (phase-specific addendum to shared authority rule):
+  - The `User Approval Request (사용자 승인 게이트)` block at the **top of the final report** (immediately under the metadata header, before `Section 0`) is the only authorised approval gate. The user clears it either by (a) editing the single checkbox `- [ ] Approved` to `- [x] Approved` directly, or (b) invoking the next phase with `--approve` so the CLI invocation itself is treated as the approval signal and the runtime flips the checkbox on the user's behalf.
 - Non-goals:
   - code-level micro-optimization unless it changes the implementation approach
   - **source code edits of any kind** — this run produces a plan document only; Edit/Write on project source files is forbidden until the plan is approved and a separate `implementation` run starts
   - executing builds, migrations, deployments, or any command that mutates project state outside the run's own artifact directories (`reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/`)
-  - treating "다음 단계 진행해" or equivalent user phrases as authorisation to start the implementation phase — this run stays in `implementation-planning` regardless of such phrasing
+  - this run stays in `implementation-planning` regardless of user phrasing — the shared anti-escalation rule applies
   - dispatching parallel sub-agents beyond the required worker roster — okstra owns worker fan-out
   - writing artifacts to `docs/superpowers/specs/` or `docs/superpowers/plans/` — the run's `reports/` directory is the canonical location
 - Section heading contract (BLOCKING — validator scans for these literal English substrings):
@@ -79,7 +68,3 @@
   3. **Internal consistency** — option file lists, trade-off matrix, and recommended step list must agree on file paths, names, and signatures. A symbol called `clearLayers()` in the matrix and `clearFullLayers()` in the steps is a bug.
   4. **Ambiguity check** — any requirement that could be read two ways must be made explicit or moved to `Open Questions`.
   5. **Scope check** — if the recommended plan now spans multiple independent subsystems, recommend splitting into separate planning runs rather than shipping an oversized plan.
-- Skill provenance (for maintainers):
-  - "Pre-planning context exploration", "Design principles applied when scoring options", and the self-review pass items 3–5 are adapted from the `brainstorming` skill (clarification + spec self-review portions). The interactive one-question-at-a-time dialogue, visual companion, and `docs/superpowers/specs/` save path from that skill are intentionally **not** adopted — okstra is a non-interactive multi-worker run with its own artifact layout.
-  - "File Structure" per option, bite-sized step granularity, the No-placeholder rule, and self-review items 1–2 are adapted from the `writing-plans` skill. The skill's default save path (`docs/superpowers/plans/`), the subagent-vs-inline execution-handoff prompt, and the plan-document header referencing other skills are intentionally **not** adopted — okstra owns artifact paths, worker dispatch, and lifecycle handoff.
-  - Skill names above are written without the deprecated `superpowers:` prefix.

package/runtime/prompts/profiles/implementation.md

@@ -12,18 +12,13 @@
   - Executor subagent for dispatch: `{{EXECUTOR_WORKER_AGENT}}`
   - Executor model: `{{EXECUTOR_MODEL_DISPLAY}}` (launch value: `{{EXECUTOR_MODEL_EXECUTION_VALUE}}`)
   - Wherever this profile mentions the `Executor`, it refers to the role bound above. The other two providers in the roster (`claude` / `codex` / `gemini` minus the executor) are dispatched as **verifiers only** for this run and remain strictly read-only.
-- Team contract:
-  - `Claude lead` is synthesis-only and stays distinct from the `Executor` and the verifiers
+{{INCLUDE:_common-contract.md}}
+- Team contract (phase-specific overrides — `Claude worker` is replaced by `Executor` + verifier triad in this phase):
   - **Executor role:** the `Executor` (bound above) is the **only worker permitted to use Edit / Write / state-mutating Bash commands** on project files. All other workers run read-only. When the executor provider is `codex` or `gemini`, the actual file mutation happens inside the executor CLI's own auto-edit mode (e.g. `codex exec --full-auto`, gemini's equivalent) — not through Claude-side Edit/Write tools — but the safety rules in this profile still apply identically.
   - **Verifier roles:** the three verifier slots are `Claude verifier`, `Codex verifier`, and `Gemini verifier`. All three are dispatched regardless of which provider holds the executor role; the executor's own provider is run *separately* as a verifier (a fresh CLI session with no shared context) so that no verdict is produced from the same session that wrote the diff. Verifiers MUST NOT call Edit, Write, or any Bash command that mutates files outside the run's artifact directories. If a verifier wants a fix, it records the recommendation in its worker result; it does not apply the fix itself.
-  - Session isolation — not model-variant divergence — is the primary self-review safeguard: each verifier is a separate CLI invocation with its own context window, so reusing the same model variant for executor and same-provider verifier is acceptable. Assigning different model variants (e.g. executor=opus / Claude verifier=sonnet) remains recommended when available because it adds defence-in-depth, but it is no longer a hard requirement.
-  - `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 centralised defaults; the fallback values are `Claude lead`/`Report writer worker`=`opus`, `Claude verifier`=`sonnet`, `Codex verifier`=`gpt-5.5`, `Gemini verifier`=`auto`. The `Executor`'s model is taken from the provider-specific worker model corresponding to `--executor`: claude→`--claude-model` (default `sonnet`, override to `opus` recommended when this run's executor is claude), codex→`--codex-model` (default `gpt-5.5`), gemini→`--gemini-model` (default `auto`).
-  - all three verifier roles (`Gemini verifier`, `Codex verifier`, `Claude verifier`) must be attempted; the final verdict waits until each has either a result or an explicit terminal status
-  - **All-verifier-failure policy**: if every required verifier (`Gemini verifier`, `Codex verifier`, `Claude verifier`) ends with a non-result terminal status (`timeout`, `error`, `not-run`) — i.e. zero independent verdicts were produced — the run MUST end with status `blocked` and route to a follow-up `error-analysis` run. `Claude lead` MUST NOT substitute its own verdict in place of the missing verifier outputs; synthesis requires at least one independent verifier's verdict. If one or two verifiers fail but at least one returns a verdict, the run proceeds with the surviving verdict(s) and the final report MUST explicitly notate which verifiers were unavailable, with the captured error / timeout evidence per failed verifier.
-  - unnamed generic parallel workers must not replace the required role roster, and no additional sub-agent dispatch is allowed beyond this roster
-- Tooling — read-only MCP availability:
-  - the read-only MCP servers declared in the task brief's `## Available MCP Servers` section may be queried by both executor and verifiers as a read-only cross-check (sanity-checking row counts after a migration script's dry-run, comparing observed schema against the plan's expectations, etc.); that section is the canonical source of which servers and tools exist for this run, and any MCP-derived evidence MUST cite server, table, and the SELECT used. MCP MUST NEVER be used as a write path — schema/data mutations go through repository migration files, never through this MCP.
+  - Session isolation — not model-variant divergence — is the primary self-review safeguard: each verifier is a separate CLI invocation with its own context window, so reusing the same model variant for executor and same-provider verifier is acceptable. Different model variants (e.g. executor=opus / Claude verifier=sonnet) remain recommended when available.
+  - Phase-specific model defaults override the shared defaults: `Claude verifier`=`sonnet`, `Codex verifier`=`gpt-5.5`, `Gemini verifier`=`auto`. The `Executor`'s model is taken from the provider-specific worker model corresponding to `--executor`: claude→`--claude-model` (default `sonnet`, override to `opus` recommended when this run's executor is claude), codex→`--codex-model` (default `gpt-5.5`), gemini→`--gemini-model` (default `auto`).
+  - **All-verifier-failure policy**: if every verifier (`Gemini verifier`, `Codex verifier`, `Claude verifier`) ends with a non-result terminal status (`timeout`, `error`, `not-run`) — i.e. zero independent verdicts were produced — the run MUST end with status `blocked` and route to a follow-up `error-analysis` run. `Claude lead` MUST NOT substitute its own verdict in place of the missing verifier outputs; synthesis requires at least one independent verifier's verdict. If one or two verifiers fail but at least one returns a verdict, the run proceeds with the surviving verdict(s) and the final report MUST explicitly notate which verifiers were unavailable, with the captured error / timeout evidence per failed verifier.
 - Pre-implementation gate (mandatory — refuse to start if any item fails):
   - the run brief MUST cite `--approved-plan <path>` pointing to a `final-report.md` produced by a prior `implementation-planning` run located under `runs/implementation-planning/.../reports/final-report.md`
   - that file MUST contain a `User Approval Request` block (canonically placed at the **top of the report**, immediately under the metadata header) AND a recorded user approval marker. The canonical, recommended form is the single markdown checkbox line `- [x] Approved`. The runtime regex in `okstra_ctl.run._validate_approved_plan` also accepts (case-insensitive, line-anchored, optional leading `-`/`*`/`+` bullet): `APPROVED` (alone, followed by `:`, or end-of-line), `[x] Approved`, or `User Approval: APPROVED|granted|yes`. Free-form approvals such as "lgtm", "go ahead", or paraphrased confirmations are intentionally NOT accepted; if the user's approval is informal, re-edit the plan file to flip the top checkbox to `- [x] Approved` before invoking the implementation run.
@@ -32,7 +27,22 @@
     - **CLI ack** — the user runs `okstra ... --task-type implementation --approved-plan <path> --approve`. The CLI invocation itself is modelled as the user's act of approval; the runtime (`okstra_ctl.run._apply_cli_approval`) flips the checkbox in the report file and appends an audit line `- 승인 일시 (CLI ack): <ISO8601> — recorded by \`okstra --approve\`` before the standard regex validation runs. Use this when running unattended or when you want a single command to both approve and launch the next phase.
   - The `--approve` flag is **only meaningful with `--task-type implementation` and `--approved-plan <path>`**. Passing it with any other task-type causes `PrepareError` (the runtime refuses to silently ignore approval signals). It is also a no-op if the file already carries a valid approval marker (idempotent — only an audit line is appended, the marker is not re-toggled).
   - the file's `Recommended option` and its bite-sized step list become the authoritative scope for this run; any deviation must be justified in the final report and routed back to a new `implementation-planning` run instead of being silently expanded.
+- Executor worktree (provisioned by `okstra-ctl` at run-prep time, fixed for this run):
+  - Status: `{{EXECUTOR_WORKTREE_STATUS}}` (one of: `created` | `skipped-in-worktree` | `skipped-not-git`)
+  - Working tree path: `{{EXECUTOR_WORKTREE_PATH}}` — when status is `created`, this is a fresh `git worktree` rooted under `~/.okstra/worktrees/<project>/<task-group>/<task-id>-<seq>`; when skipped, this is the caller's `project_root`.
+  - Branch: `{{EXECUTOR_WORKTREE_BRANCH}}` — empty when status is `skipped-*`. The branch name encodes `<work-category-prefix>-<task-id-segment>-<seq>`.
+  - Base ref: `{{EXECUTOR_WORKTREE_BASE_REF}}` — commit SHA the worktree was branched from; canonical `<base>` for every `git diff` / `git log` in this run.
+  - Provisioning note: `{{EXECUTOR_WORKTREE_NOTE}}`
+  - **Executor behaviour**: when status is `created`, the Executor MUST run every Edit / Write / build / test / commit command with the working tree path above as cwd. Treat it as `project_root` for the duration of this run. Do NOT mutate the caller's original checkout. Do NOT `cd` out of the worktree to reach files; if a file outside the worktree is needed, the dependency is a planning gap — record it in `Out-of-plan edits` and continue.
+  - **Verifier behaviour**: all three verifier roles read from the SAME working tree path so they observe the exact diff the Executor produced. Verifiers remain strictly read-only there.
+  - **Lifecycle**: the worktree is kept after the run completes (no automatic cleanup). It is the canonical artefact for manual PR authoring, rollback verification, and follow-up `final-verification` runs. Cleanup, when desired, is manual: `git -C <project_root> worktree remove <path>` followed by `git -C <project_root> branch -D <branch>`.
+  - **Skipped paths**: when status is `skipped-in-worktree` or `skipped-not-git`, the executor operates in `project_root` as before. Cite the status in the final report's metadata header so reviewers know which path was taken.
+  - **Synced state directories (symlinks into the original `project_root`)**: at provision time `okstra-ctl` symlinks `.project-docs/`, `.scratch/`, and `graphify-out/` from the original `project_root` into the worktree (override via `OKSTRA_WORKTREE_SYNC_DIRS`; empty string disables). These are NOT independent copies — writes through them land in `project_root`. Inside this run the executor MUST confine writes under these paths to its own task scope (i.e. only `.project-docs/okstra/tasks/<this-task-id>/...`). Reading from elsewhere under the symlinks (other tasks, `graphify-out/GRAPH_REPORT.md`, `.scratch/` issues) is allowed and expected for context.
 - Pre-implementation context exploration (executor before first edit):
+  - **Mandatory skill invocation — `tdd`**: BEFORE the first `Edit` or `Write` call, the executor MUST invoke the `tdd` skill via the `Skill` tool and follow its red-green-refactor loop for every code change in this run. This is a hard requirement, not a recommendation; skipping it is a `contract-violated` outcome. The skill governs HOW each step is executed (failing test first → minimal implementation → refactor); it does not override the approved plan's WHAT/file scope.
+    - Order of operations per plan step: (1) write/extend the test that captures the step's acceptance criterion and confirm it fails for the right reason, (2) commit the failing test (`test(<scope>): ...`), (3) implement the minimum change to make it pass, (4) commit the implementation (`feat|fix(<scope>): ...`), (5) refactor without changing behaviour and commit separately if any cleanup is made (`refactor(<scope>): ...`). The failing-then-passing transition between steps (2) and (4) is the `TDD evidence` required by the final report.
+    - Doc-only / config-only / pure-rename steps that have no observable runtime behaviour are exempt from the failing-test requirement, but the executor MUST cite the exemption per step in the final report (`TDD exemption: <reason>`).
+    - When the touched area has no existing test harness, the executor MUST stand up the minimum harness needed to host one regression test for this run rather than skipping TDD entirely. Record the harness-bootstrap step as an `Out-of-plan edit` if it is not in the plan.
   - re-read the approved plan end-to-end and extract: file list, step order, validation commands, rollback path
   - inspect the current state of every file the plan names; if any file has changed materially since the plan was written, stop and route to a new `implementation-planning` run instead of editing speculatively
   - "materially changed" means: the function, class, section, or behaviour the plan targets has been edited, renamed, moved, removed, or otherwise altered in a way that invalidates the plan's reasoning. Cosmetic edits (whitespace, comment-only changes, unrelated function modifications elsewhere in the same file) do NOT trigger a re-plan; cite the diff (`git log --oneline <plan-created-at>..HEAD -- <file>`) in the final report and proceed.
@@ -45,10 +55,17 @@
   - read-only inspection commands: `git status`, `git diff`, `git log`, `grep`, `rg`, `find`, `cat`, `ls`, file Read tools
   - build, lint, type-check, and test commands (`npm test`, `pytest`, `go build`, `cargo test`, `bash -n`, etc.)
   - **local git operations only**: `git add`, `git commit`. Prefer small commits keyed to plan steps.
-- 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 approved 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 approved plan or task brief explicitly states otherwise.
-  - Do NOT add such items to commit ordering, validation evidence, rollback verification, routing recommendations, or any time/effort accounting. They are not legitimate sources of schedule extension.
-  - The pre-implementation gate's recorded user approval marker is the only authorised approval gate at this phase — proceed once it is satisfied without further external coordination. (This rule does NOT relax the existing forbidden-action list below; deploy/publish/push/migrate to shared environments remain blocked for safety, not for permission reasons.)
+  - **Commit message format (mandatory)**: every commit message MUST follow Conventional Commits — `<type>(<scope>): <subject>` for the first line, optional body separated by a blank line, optional footer. Constraints:
+    - `<type>` MUST be one of: `feat` / `fix` / `perf` / `revert` / `deps` / `docs` / `refactor` / `build` / `ci` / `chore` / `test`. When the repo is `release-please`-managed, this aligns the commit with a configured changelog section.
+    - `<scope>` SHOULD be the plan step identifier or the primary module touched (e.g. `feat(report-writer): ...`). Omit the parentheses only when no meaningful scope applies.
+    - `<subject>` MUST be ≤72 characters, imperative mood (`add`, `fix`, `remove` — not `added` / `adding`), no trailing period, no emoji, no AI attribution lines (no `Co-Authored-By: Claude ...`, no `Generated with Claude Code`).
+    - Body (when present) explains *why*, not *what*; wrap at ~100 chars.
+    - Do NOT append okstra artefact paths to the commit message — no `Plan: .project-docs/okstra/...`, no `Report: ...`, no `Run: ...`, no `Task: ...` footers, and no other reference to files under `.project-docs/okstra/`. Those paths belong in the final report's `Plan link & approval evidence` section, not in git history; they rot quickly and leak internal layout into the upstream changelog.
+    - Allowed footers are limited to standard Conventional Commits trailers (`BREAKING CHANGE: ...`, `Refs: <issue/ticket-id>`, `Closes #<n>`). When citing a ticket, use the ticket id only (e.g. `Refs: DEV-9423`) — never a filesystem path.
+    - One commit MUST correspond to one plan step (or one cohesive sub-step). Do NOT bundle unrelated steps into a single commit, and do NOT split a single step across commits unless the plan explicitly sequenced it that way.
+    - The exact message used for each commit MUST be reproduced verbatim in the final report's `Commit list` so reviewers can audit it without re-running `git log`.
+- Approval gate (phase-specific addendum to shared authority rule):
+  - the pre-implementation gate's recorded user approval marker is the only authorised approval gate at this phase — proceed once it is satisfied without further external coordination
 - Forbidden actions (any occurrence → terminal status `contract-violated`):
   - **`git push` of any kind**, including `--dry-run` against a real remote that produces side-effects
   - publishing or release commands: `npm publish`, `cargo publish`, `pip publish`, `gh release`, `docker push`
@@ -73,6 +90,7 @@
     - **Feature-flag-gated changes**: confirm the off-switch path was exercised in this run's validation evidence (i.e. one of the validation commands ran with the flag off and succeeded). A plan that ships a flag without exercising the off-path does NOT satisfy this requirement.
     - **Schema migrations, config-format changes, or any change with persisted state**: a **dry-run of the rollback step is mandatory**, not preferred. Record the exact rollback command and its captured exit code / stdout. If the migration tool offers no dry-run mode (`--dry-run`, `--plan`, equivalent), the executor MUST refuse to claim rollback verification and instead end the run with a routing recommendation back to `implementation-planning` for a safer rollback strategy. Skipping this step on a stateful change is treated as a `contract-violated` outcome by `final-verification`.
   - **Routing recommendation for `final-verification`**: brief note on whether the changes are ready for final-verification phase or need a new error-analysis / planning loop first.
+  - **Follow-up tasks (Section 7 of the final report)**: every item discovered during this run that was *not* delivered MUST appear in the final report's `## 7. Follow-up Tasks (후속 작업)` table with a concrete `Origin`, `New Task ID`, `Suggested task-type`, `Scope`, and `Reason / Why deferred`. Sources include: out-of-scope discoveries that the executor consciously chose not to fold into this run, verifier concerns the executor declined to fix in-place, scope-boundary items from the approved plan that turned out to need their own ticket, and any open question carried over from `4.5.9`. An empty section is acceptable but only when expressed as the single line `- 후속 작업 없음.` — silence is treated as a contract violation. Rows with `Auto-spawn? = yes` will be materialised by `scripts/okstra-spawn-followups.py` in Phase 7; rows with `Auto-spawn? = no` MUST also appear in `Section 6. Recommended Next Steps` so the user knows to act manually.
 - Self-review pass before finalising the report (`Claude lead` runs this; do not delegate to a generic subagent):
   1. **Plan coverage** — every step in the approved plan's recommended option must point to a commit (or an explicit `Skipped: <reason>` entry). List gaps.
   2. **Evidence completeness** — every `Validation evidence` and `TDD evidence` claim has the actual command line and exit code? No paraphrased "tests pass" without output?
@@ -84,10 +102,5 @@
      git diff <base>..HEAD | grep -E '^\+[^+].*\b(TBD|TODO|FIXME|XXX|implement later|handle edge cases|similar to|placeholder)\b' || echo 'clean'
      ```
      Only newly-added lines (those starting with `+` and not part of the `+++` header) are inspected. If output is anything other than `clean`, the run MUST either remove the placeholders before finalising or record an explicit justification per occurrence in the final report.
-- Skill provenance (for maintainers — these skills are referenced as inspiration, NOT invoked at runtime):
-  - The pre-implementation gate, "Plan coverage" and "Evidence completeness" self-review items are adapted from the `executing-plans` skill (inline mode). The skill's "subagent-driven vs inline" choice prompt and its plan-document-header conventions are intentionally not adopted — okstra owns lifecycle handoff.
-  - The "TDD evidence" requirement and the failing-test-before-implementation ordering preference are adapted from `test-driven-development`. Strict enforcement is relaxed where the touched area has no test infrastructure; in those cases the executor must add at minimum a regression test and record a justification.
-  - The "Validation evidence" and "Forbidden action audit" requirements are adapted from `verification-before-completion`. The skill's bare-name principle ("evidence before assertions") is treated as a hard rule.
-  - Verifier role behaviour (read-only review, recommendation without application, dissent preservation) is adapted from `receiving-code-review` and `requesting-code-review`. The skills' UI/dialogue framing is replaced by structured worker-result sections.
-  - In-phase debugging follows the spirit of `systematic-debugging` (root cause before fix), but the executor must NOT route to a separate `error-analysis` phase mid-run; if a defect blocks plan progress, the executor records findings and routes to a new run after this one ends.
-  - Skill names above are written without the deprecated `superpowers:` prefix.
+- In-phase debugging:
+  - follows the spirit of `systematic-debugging` (root cause before fix), but the executor MUST NOT route to a separate `error-analysis` phase mid-run; if a defect blocks plan progress, the executor records findings and routes to a new run after this one ends.