okstra 0.66.0 → 0.68.0

package/runtime/python/okstra_ctl/worktree_registry.py

@@ -46,13 +46,17 @@ def _okstra_worktrees_dir() -> Path:
 def task_key(
     project_id: str, task_group: str, task_id: str,
     stage_number: Optional[int] = None,
+    group_id: Optional[str] = None,
 ) -> str:
-    """Canonical task-key. With stage_number, returns the stage-scoped
-    key `<proj>/<group>/<task>#stage-<N>` used to reserve a per-stage
-    worktree independently of the task-key entry."""
+    """Canonical task-key. stage_number → `#stage-<N>` (per-stage worktree),
+    group_id → `#group-<id>` (stage-group collector worktree). 둘은 상호배타."""
+    if stage_number is not None and group_id is not None:
+        raise ValueError("stage_number and group_id are mutually exclusive")
     base = f"{project_id}/{task_group}/{task_id}"
     if stage_number is not None:
         return f"{base}#stage-{stage_number}"
+    if group_id is not None:
+        return f"{base}#group-{group_id}"
     return base
 
 
@@ -70,6 +74,7 @@ class WorktreeEntry:
     status: str = "active"  # "active" | "released"
     stage: Optional[int] = None
     implementation_base_commit: str = ""
+    stages: Optional[list] = None
 
 
 @contextlib.contextmanager
@@ -119,8 +124,9 @@ def _save(data: dict) -> None:
 def lookup(
     project_id: str, task_group: str, task_id: str,
     stage_number: Optional[int] = None,
+    group_id: Optional[str] = None,
 ) -> Optional[WorktreeEntry]:
-    key = task_key(project_id, task_group, task_id, stage_number)
+    key = task_key(project_id, task_group, task_id, stage_number, group_id)
     with _registry_lock():
         data = _load()
         row = data["tasks"].get(key)
@@ -139,18 +145,20 @@ def reserve(
     base_ref: str,
     phase: str = "",
     stage_number: Optional[int] = None,
+    group_id: Optional[str] = None,
+    stages: Optional[list] = None,
 ) -> WorktreeEntry:
     """Atomically insert a new entry. Raises RuntimeError if the
     task-key already exists or the branch is already owned by a
     different task-key. Callers should `lookup()` first when re-entry
     is expected.
     """
-    key = task_key(project_id, task_group, task_id, stage_number)
+    key = task_key(project_id, task_group, task_id, stage_number, group_id)
     now = time.strftime("%Y-%m-%dT%H:%M:%S%z") or time.strftime("%Y-%m-%dT%H:%M:%S")
     with _registry_lock():
         data = _load()
-        if key in data["tasks"]:
-            existing = data["tasks"][key]
+        existing = data["tasks"].get(key)
+        if existing and existing.get("status") != "released":
             raise RuntimeError(
                 f"task-key already has a worktree registered: {key} → "
                 f"{existing['worktree_path']} (branch {existing['branch']}). "
@@ -174,6 +182,7 @@ def reserve(
             "last_phase": phase,
             "status": "active",
             "stage": stage_number,
+            "stages": stages,
         }
         data["tasks"][key] = row
         data["branches"][branch] = key
@@ -218,6 +227,24 @@ def set_implementation_base(
         return commit
 
 
+def reset_implementation_base(
+    project_id: str, task_group: str, task_id: str, commit: str,
+) -> str:
+    """anchor 를 의식적으로 재고정한다. 유일한 호출자는 git-reconcile 의
+    `--reset-anchor` — prepare 경로는 절대 anchor 를 움직이지 않는다."""
+    key = task_key(project_id, task_group, task_id)
+    with _registry_lock():
+        data = _load()
+        row = data["tasks"].get(key)
+        if row is None:
+            raise RuntimeError(
+                f"no task-key entry to reset implementation base: {key}"
+            )
+        row["implementation_base_commit"] = commit
+        _save(data)
+        return commit
+
+
 def get_implementation_base(
     project_id: str, task_group: str, task_id: str,
 ) -> Optional[str]:
@@ -262,13 +289,17 @@ def list_active_stage_numbers(
         return out
 
 
-def release(project_id: str, task_group: str, task_id: str) -> Optional[WorktreeEntry]:
+def release(
+    project_id: str, task_group: str, task_id: str,
+    stage_number: Optional[int] = None,
+    group_id: Optional[str] = None,
+) -> Optional[WorktreeEntry]:
     """Mark the entry as `released` (worktree dir intact — preservation
     is the project's policy). The branch index is freed so future
     reservations of the same branch name are not blocked.
     Returns the prior entry, or None when not found.
     """
-    key = task_key(project_id, task_group, task_id)
+    key = task_key(project_id, task_group, task_id, stage_number, group_id)
     with _registry_lock():
         data = _load()
         row = data["tasks"].get(key)

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

@@ -155,6 +155,6 @@ Information to be obtained after executing this skill:
 - Reference list of config files/deployment manifests and task-level expected values
 - Current run status and presence of existing worker results
 - Current run prompt history contract for attempted workers
-- Candidate `teamName` for Phase 3 hand-off: `okstra-<task-key>` (with task-key slugified per Step 1's slug rule)
+- Candidate `teamName` for Phase 3 hand-off: `okstra-<task-key>` (with task-key slugified per Step 1's slug rule); implementation stage runs append `-s<N>` — the launch prompt's Team Creation Gate block carries the final name verbatim
 - Current Claude `lead.sessionId` (the in-flight Claude Code session) — required by `okstra-team-contract` when registering the lead in `team-state.json`
 - Resume command path: from `task-manifest.json` → `latestResumeCommandPath` (fallback: latest `runs/<task-type>/sessions/claude-resume-*.sh` by mtime). Never reconstruct the filename — the `<seq>` counter is category-local and may diverge from `manifests/`.

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

@@ -264,7 +264,7 @@ Agent(
   prompt: "<re-verification prompt with findings batch>",
   name: "<role-slug>-reverify-r<N>",
   subagent_type: "<same as initial execution>",
-  team_name: "okstra-<task-key>",
+  team_name: "<teamName recorded in team-state>",
   model: "<same as initial execution>",
   mode: "auto"
 )

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

@@ -34,7 +34,7 @@ Agent(
   prompt: "<report-writer prompt: see this skill + Required reading clause + Available MCP Servers section>",
   name: "report-writer",
   subagent_type: "report-writer-worker",
-  team_name: "okstra-<task-key>",   # omit if team is not alive — see Resume-safe dispatch
+  team_name: "<teamName recorded in team-state>",   # omit if team is not alive — see Resume-safe dispatch
   model: "<family token of Report writer worker's modelExecutionValue>",   # opus/sonnet/haiku — NOT hardcoded; see below
   mode: "auto"
 )
@@ -68,7 +68,7 @@ The prompt MUST include, in this order at the top:
 
 A resumed lead session can ALWAYS dispatch a fresh Report writer worker. The Agent tool does not require a previously created Team to be alive:
 
-- If `TeamCreate` for `okstra-<task-key>` still succeeds (or the team is still listed), include `team_name` in the dispatch.
+- If `TeamCreate` for the team-state `teamName` still succeeds (or the team is still listed), include `team_name` in the dispatch.
 - If `TeamCreate` reports the name is taken or the team is gone, omit `team_name` from the dispatch — the worker still runs as a background subagent and its session is still recoverable by `agentName: "report-writer"` in `okstra-token-usage.py`.
 - Do NOT skip dispatch because of any team-related error. Record the team status in team-state and proceed without `team_name`.
 

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

@@ -45,8 +45,9 @@ The wizard tells you *which UI to use* via `kind` (and the optional `multi` flag
 - `kind: "pick_group"` → render a SINGLE `AskUserQuestion` whose questions array maps 1:1 to the wizard's `questions[]`. For each entry use `questions[].label`, `questions[].options[].label`, and `multiSelect: questions[].multi`. Collect the user's chosen `options[].value` per tab, build a JSON object keyed by each `questions[].step`, and submit it as a single literal `--answer '{"lead_model":"opus","claude_model":"default",...}'`. A tab the user leaves at its default still gets its `"default"`/`""` value in the JSON. Never split a `pick_group` into multiple `AskUserQuestion` calls — the wizard already capped it at 4 tabs and emits any remainder as the next prompt.
 - `kind: "text"` → write `label` as a plain text message and consume the user's NEXT message as the answer.
 - `kind: "done"` → input collection finished; move to Step 5.
+- `kind: "aborted"` → the user picked 중단; the wizard is terminally cancelled. Tell the user on one short line that the run setup was aborted, delete the state file (`rm` with the literal path), and stop this skill — do NOT call `render-args` or `render-bundle` (the wizard rejects `render-args` on an aborted state).
 
-The `branch_confirm` step (shown just before `confirm`) is a normal `pick` step and is rendered the same way — no special handling needed.
+The `branch_confirm` step (shown just before `confirm`) is a normal `pick` step and is rendered the same way — no special handling needed. Its options always include `중단` (abort); `base-ref 다시 고르기` (edit) appears only when a new worktree would be created.
 
 Never invent additional questions. Never reorder. **Never drop, hide, or merge a `pick` / `pick_group` option** — render every `options[]` entry as its own selectable `AskUserQuestion` choice, including entries that carry a `(default)` / `(recommended)` suffix. Do NOT collapse a multi-option pick into a "recommended + 직접 입력 / Other" shortlist: the wizard's `options[]` array IS the complete, authoritative choice set. Example: the `executor` step always emits `claude` / `codex` / `gemini` — show all three, never just `claude`. The run-prompt recommendation rule (1–2 추천 + 직접 입력) applies ONLY to prompts this skill authors itself (e.g. the conformance-waiver picker), never to wizard-provided `options[]`. Never use `AskUserQuestion` for `text` prompts — the wizard explicitly chose `text` to avoid the picker-Other re-render lag.
 
@@ -92,7 +93,7 @@ Output: the same `{ok, next}` JSON described above. The first `next` is always `
 
 ## Step 3: Run the prompt loop
 
-Repeat until `next.kind == "done"`:
+Repeat until `next.kind == "done"` (or `"aborted"` — terminal cancel, see "How the wizard talks to you"):
 
 1. **Render** the prompt according to `kind` (and `multi` for pick):
    - `pick` + `multi: false` → `AskUserQuestion` with `multiSelect: false`, `label`, and `options`. The user's chosen option's `value` is the answer string.
@@ -118,8 +119,8 @@ Repeat until `next.kind == "done"`:
 
 That is the entire interactive flow. The wizard handles:
 
-- new-vs-existing task split, task-group / task-id slug validation,
-- task-type pick (with `nextRecommendedPhase` surfaced as recommended for existing tasks),
+- new-vs-existing task split (남은 작업 — `workStatus != done` — 최신순 3개 추천 + 직접 입력), task-group / task-id slug validation (각각 최근 후보 3개 추천 + 직접 입력),
+- task-type pick (추천 3개 — `nextRecommendedPhase` recommended / 현재 phase 재실행 / 라이프사이클 다음 단계 — + 직접 입력; 직접 입력은 후속 `text` 단계에서 전체 task-type 화이트리스트로 검증),
 - brief path after task-group selection (same-group `.okstra/briefs/<task-group>/**/*.md` candidates first, direct input last; `유지 / 변경` for existing tasks),
 - base-ref pick + git rev-parse validation (skipped when reusing an active worktree),
 - `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = 의존성 충족된 가장 빠른 미완료 stage, 또는 특정 stage 번호) + executor pick,
@@ -178,7 +179,7 @@ okstra render-bundle \
   --pr-template-path "<args.pr-template-path>"
 ```
 
-`render-bundle` auto-supplies `--workspace-root` and forces `--render-only`. Stdout prints `okstra task root:`, `okstra instruction-set:`, and the full rendered lead prompt. Parse the labelled lines for `TASK_ROOT` and `INSTRUCTION_SET_PATH`.
+`render-bundle` auto-supplies `--workspace-root` and forces `--render-only`. Stdout prints `okstra task root:`, `okstra instruction-set:`, and the full rendered lead prompt. Parse the labelled lines for `TASK_ROOT` and `INSTRUCTION_SET_PATH`. Also watch for an optional `okstra concurrent-run stages:` label line — present only when a concurrent run is detected (see "동시-run 감지 분기" below).
 
 The python function underneath is mutex-protected (`~/.okstra/.locks/<task-key>.lock`), writes `run-context-*.json` + `run-inputs-*.json` + all manifests + discovery files, and registers the run in `~/.okstra/recent.jsonl` with status `prepared`.
 
@@ -196,6 +197,45 @@ This is **never** a lead/worker self-exemption — only the user may waive. Offe
 
 When the user picks a waiver, append `--qa-waiver "<stageKey>:<reason>"` to the `render-bundle` invocation above. Omit the flag entirely otherwise (do **not** pass `--qa-waiver ""`). A malformed value or unknown `<stageKey>` aborts `render-bundle` with a `PrepareError`.
 
+### 동시-run 감지 분기 (concurrent-run)
+
+`render-bundle` stdout 에 `okstra concurrent-run stages: <stages>` 라벨 라인이
+있으면(같은 task-key 의 다른 implementation run 이 `<stages>` 를 점유 중), launch
+프롬프트는 이미 "Concurrent-run: no-team background" 게이트로 렌더돼 있다. 이 라인이
+없으면 동시-run 이 아니므로 이 분기를 건너뛴다. 라인이 있으면 dispatch 전에
+사용자에게 3-옵션 recommendation picker 를 제시한다 (run-prompt recommendation 규칙:
+1–2 추천 + 직접 입력; 이 picker 는 스킬이 author 하는 것이라 wizard `options[]`
+제약과 무관):
+
+1. (추천) 이대로 no-team background 로 진행 — 이미 렌더된 bundle 을 그대로 사용한다.
+   team 을 만들지 않아 `~/.claude/teams/` race 를 회피한다(Teams split-pane 관찰성만 포기).
+2. 대기 — 지금 dispatch 를 보류한다. stage worktree·run-context 는 보존되므로,
+   점유 중인 다른 run 종료 후 같은 stage 를 resume 으로 재개하면 그때는 정상 team
+   경로다. resume 명령(`okstra-inspect` history → resume)을 사용자에게 출력한다.
+3. 직접 입력.
+
+### Stale git SHA recovery (git-reconcile gate)
+
+`render-bundle` 이 `Recorded stage SHAs no longer match the git history` 를 포함한
+`PrepareError` 로 실패하면, okstra 밖에서 git 히스토리가 바뀐 것이다(rebase /
+squash / 리뷰 반영 amend / branch 삭제). 절대 registry/consumers 를 손으로
+고치지 말고 다음 순서로 회복한다:
+
+1. 에러 메시지에 인쇄된 `okstra git-reconcile … --check --json` 명령을 그대로 실행해
+   stale 리포트를 얻는다. (patch-id 로 내용 동일성이 증명되는 항목은 prepare
+   가 이미 자동 화해했으므로, 여기 남는 것은 confirm 항목뿐이다.)
+2. confirm 항목별로 사용자에게 3-옵션 picker 를 제시한다:
+   - **`stage-<N>` branch 의 현재 tip 으로 재기록 (추천)** — 리뷰 반영 등
+     의도된 수정이 그 branch 에 있을 때.
+   - **다른 ref 직접 입력** — 사용자가 commit/branch/tag 를 직접 지정.
+   - **중단** — 회복하지 않고 run 을 멈춘다.
+3. 선택된 ref 로 `okstra git-reconcile … --apply --stage <N> --use-ref <ref>`
+   를 실행한 뒤, 실패했던 `render-bundle` 을 동일 인자로 재시도한다.
+
+anchor(`implementation_base_commit`)가 unresolvable 로 보고되면 같은 명령의
+`--reset-anchor <ref>` 를 사용자 확인 후 실행한다. picker 없이 confirm 항목을
+보정하는 것은 금지 — 런타임도 `--use-ref` 없는 confirm 보정을 거부한다.
+
 ## Step 6: Take over as Claude lead
 
 Read `<INSTRUCTION_SET_PATH>/claude-execution-prompt.md` verbatim and enter `Claude lead` mode. The lead prompt now points to compact intake artifacts first (`active-run-context`, `analysis-profile.md`, and `analysis-packet.md`); full source files such as `analysis-material.md`, `reference-expectations.md`, and `final-report-template.md` are lazy/fallback inputs. Follow the rendered prompt order, do not preempt it.

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

@@ -54,7 +54,7 @@ Only workers selected from `recommendedWorkers` in `task-manifest.json` and `res
 
 ## Operating Rules
 
-0. **TeamCreate ordering (BLOCKING).** Before issuing any `Agent` dispatch that includes `team_name`, Lead MUST have called `TeamCreate(team_name: "okstra-<task-key>", ...)` in this run and recorded the outcome in team-state as `teamCreate: { attempted: true, status: "ok"|"error", error?: <message> }`. If the Agent tool rejects a dispatch with `"team must be created first or call without team_name"` / `"team을 먼저 생성하거나 team_name 없이 호출해야 합니다"`, the correct response is to go back to Phase 3 and call `TeamCreate` — NOT to strip `team_name` and retry. The no-`team_name` Phase 5 fallback is only legal when `teamCreate.status == "error"` is already recorded; otherwise stripping `team_name` silently degrades the run to in-process background dispatch and loses the Teams split-pane behavior. See [okstra agent SKILL.md Phase 3](../../agents/SKILL.md) for the full team-creation sequence.
+0. **TeamCreate ordering (BLOCKING).** Before issuing any `Agent` dispatch that includes `team_name`, Lead MUST have called `TeamCreate` with the exact team name from the launch prompt's Team Creation Gate block (`okstra-<task-key>`; implementation stage runs append `-s<N>`) in this run and recorded the outcome in team-state as `teamCreate: { attempted: true, status: "ok"|"error", error?: <message> }` plus the name as `teamName`. On a "team already exists" failure, follow the stale-team recovery in [okstra agent SKILL.md Phase 3 step 2-1](../../agents/SKILL.md) — never shell-delete `~/.claude/teams/...` on your own initiative. If the Agent tool rejects a dispatch with `"team must be created first or call without team_name"` / `"team을 먼저 생성하거나 team_name 없이 호출해야 합니다"`, the correct response is to go back to Phase 3 and call `TeamCreate` — NOT to strip `team_name` and retry. The no-`team_name` Phase 5 fallback is legal when `teamCreate.status == "error"` is already recorded, OR when the launch prompt's concurrent-run gate recorded `status: "skipped", reason: "concurrent-run"`; otherwise stripping `team_name` silently degrades the run to in-process background dispatch and loses the Teams split-pane behavior. See [okstra agent SKILL.md Phase 3](../../agents/SKILL.md) for the full team-creation sequence.
 1. `Claude lead` is responsible for orchestration, convergence supervision, and final-report review/approval. It never overrides worker analysis results, and it never authors the final-report file when `Report writer worker` is in the roster.
 2. `Report writer worker` is NOT an analysis worker. It is excluded from Phase 4/5 (initial analysis) and Phase 5.5 (convergence re-verification). It is spawned only in Phase 6 and is the **author** of the final-report file at `runs/<task-type>/reports/final-report-<task-type>-<seq>.md`.
 3. When `Report writer worker` is in the roster, Lead MUST dispatch it in Phase 6. The only legal lead-authored fallback is when a dispatch was attempted and recorded a terminal status of `error` / `timeout` / `not-run` with a concrete logged reason. Speculative reasons such as "session resume constraint" or "team is no longer alive" are NOT valid — Lead can always dispatch a fresh subagent (omit `team_name` if the team is gone).
@@ -406,7 +406,7 @@ okstra token-usage /abs/path/to/run/state/team-state-<task-type>-<seq>.json --wr
 `okstra token-usage` is a thin Node-side wrapper around the python helper installed at `~/.okstra/bin/okstra-token-usage.py`. Calling the python script directly with `python3 "$HOME/..."` is forbidden — the `$HOME` expansion breaks the literal-token permission match and forces a confirmation prompt every call.
 
 The script reads:
-- `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl` for the lead and every Claude-side worker (Claude worker, Report writer worker, plus the Claude wrappers around Codex/Gemini workers). Sessions are discovered by `teamName: okstra-<task-id>`, lead is identified by `lead.sessionId`, and other workers are identified by `agentName` (e.g. `claude-worker`, `codex-worker`, `gemini-worker`, `report-writer`). **For this `agentName` match to work, Lead MUST set the Agent `name` arg to `<workerId>-worker` on every dispatch** (see [agents SKILL.md Phase 4 — "Agent `name` on dispatch"](../../agents/SKILL.md)); a worker dispatched without `name` carries no `agentName`, so the collector cannot attribute its session and records it `unavailable` (now surfaced as a `usageSummary.unattributedTeamSessions` entry rather than dropped silently).
+- `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl` for the lead and every Claude-side worker (Claude worker, Report writer worker, plus the Claude wrappers around Codex/Gemini workers). Sessions are discovered by the recorded team-state `teamName`, lead is identified by `lead.sessionId`, and other workers are identified by `agentName` (e.g. `claude-worker`, `codex-worker`, `gemini-worker`, `report-writer`). **For this `agentName` match to work, Lead MUST set the Agent `name` arg to `<workerId>-worker` on every dispatch** (see [agents SKILL.md Phase 4 — "Agent `name` on dispatch"](../../agents/SKILL.md)); a worker dispatched without `name` carries no `agentName`, so the collector cannot attribute its session and records it `unavailable` (now surfaced as a `usageSummary.unattributedTeamSessions` entry rather than dropped silently).
 - `~/.codex/sessions/Y/M/D/rollout-*.jsonl` for the underlying Codex CLI session (matched by `cwd` and timestamp window of the wrapper subagent). Last `event_msg.token_count.total_token_usage.total_tokens` is the session total.
 - `~/.gemini/tmp/<project>/chats/session-*.json` for the underlying Gemini CLI session. Sum of per-message `tokens.total`.
 

package/runtime/validators/validate-run.py

@@ -748,6 +748,36 @@ def _parse_diff_summary_files(content: str) -> list[str]:
     return _DIFF_ROW_PATH_RE.findall(section.group(0))
 
 
+_STAGE_RUN_DIR_RE = re.compile(r"^stage-\d+$")
+
+
+def _implementation_stage_name(run_dir: Path) -> str | None:
+    """implementation stage 격리 run(`runs/implementation/stage-<N>`)이면
+    `stage-<N>` 을 반환. 그 외(final-verification 등 task-type 레벨 run)는
+    None — whole-task 스코프."""
+    if run_dir.parent.name == "implementation" and _STAGE_RUN_DIR_RE.match(run_dir.name):
+        return run_dir.name
+    return None
+
+
+def _scope_manifest_entries(manifest: dict, stage_name: str | None) -> dict:
+    """게이트 평가 대상 entry 를 run 스코프로 좁힌 manifest 를 반환.
+
+    implementation 은 한 run = 한 stage 이므로 자기 stageKey
+    (`<task-id>-stage-<N>`) entry 만 게이트한다 — 다른 stage 는 각자의
+    implementation run / final-verification(whole-task) 이 검증한다.
+    suffix 매칭인 이유: stageKey 의 `<task-id>` 는 planning 이 쓴 원문이라
+    task 디렉터리 segment 와 표기가 다를 수 있다.
+    """
+    if stage_name is None:
+        return manifest
+    entries = [
+        e for e in manifest.get("entries", [])
+        if isinstance(e, dict) and str(e.get("stageKey", "")).endswith(f"-{stage_name}")
+    ]
+    return {"entries": entries}
+
+
 def _task_root_from_run_dir(run_dir: Path) -> Path:
     """run_dir 에서 `runs` 디렉터리를 앵커로 task_root 를 복원한다.
 
@@ -770,6 +800,12 @@ def _validate_conformance(report_path: Path, failures: list[str],
     가 없다는 뜻 — 선언을 강제하는 것은 planning 계약(Phase 4)의 몫). 매니페스트가
     있으면 결과 사이드카와 함께 evaluate_conformance 로 판정하고 BLOCKING verdict
     를 run 검증 실패로 승격한다. WAIVED(conditional)/EXEMPT 는 통과시킨다.
+
+    게이트 스코프: implementation stage 격리 run 은 자기 stage entry 만(결과
+    게이트·diff-surface 교차검증 모두 — 미래 stage 의 미실행이 현재 run 을
+    막으면 안 된다), final-verification 등 task-type 레벨 run 은 전 entry
+    (whole-task). prompts/profiles/_implementation-verifier.md §Tier 3 /
+    final-verification.md 의 스코프 계약과 동형.
     """
     # conformance 산출물은 task-level(<task_root>/qa)에 있어 planning/
     # implementation/final-verification 가 공유한다. report_path 는
@@ -792,8 +828,9 @@ def _validate_conformance(report_path: Path, failures: list[str],
     if schema_errors:
         failures.extend(f"conformance manifest: {e}" for e in schema_errors)
         return
-    results = _load_conformance_results(qa_dir, manifest)
-    for verdict in evaluate_conformance(manifest, results):
+    scoped = _scope_manifest_entries(manifest, _implementation_stage_name(run_dir))
+    results = _load_conformance_results(qa_dir, scoped)
+    for verdict in evaluate_conformance(scoped, results):
         if not verdict.ok:
             failures.append(
                 f"conformance gate BLOCKING for stage {verdict.stage_key}: "
@@ -803,13 +840,14 @@ def _validate_conformance(report_path: Path, failures: list[str],
             )
     changed_files = _parse_diff_summary_files(report_path.read_text(encoding="utf-8"))
     if changed_files:
-        uncovered = detect_surfaces(changed_files, surface_patterns) - manifest_required_surfaces(manifest)
+        uncovered = detect_surfaces(changed_files, surface_patterns) - manifest_required_surfaces(scoped)
         if uncovered:
             failures.append(
                 "conformance gate BLOCKING: implementation diff touches undeclared "
-                f"surface(s) {sorted(uncovered)} — no stage declares `requires` for "
-                "them. Declare a conformance entry (requires=[...]) for the touching "
-                "stage, or an explicit exemption. (silent mock-green 방지 — DEV-9184)"
+                f"surface(s) {sorted(uncovered)} — no in-scope stage declares "
+                "`requires` for them. Declare a conformance entry (requires=[...]) "
+                "for the touching stage, or an explicit exemption. "
+                "(silent mock-green 방지 — DEV-9184)"
             )
 
 
@@ -1399,11 +1437,13 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
             f"final-verification: verificationScope must be `whole-task` or "
             f"`single-stage`, got {scope!r}."
         )
-    if scope == "single-stage" and "release-handoff" in routing:
+    if (scope == "single-stage" and "release-handoff" in routing
+            and "release-handoff(stage-group)" not in routing):
         failures.append(
             "final-verification: verificationScope `single-stage` cannot recommend "
-            "release-handoff routing — single-stage is a partial verification and "
-            "release-handoff requires whole-task verification."
+            "plain release-handoff routing — a single-stage accepted verdict may "
+            "only route to `release-handoff(stage-group)` (partial-PR mode); "
+            "whole-task release-handoff requires whole-task verification."
         )
 
 

package/src/git-reconcile.mjs

@@ -0,0 +1,31 @@
+import { runPythonModule } from "./_python-helper.mjs";
+
+const USAGE = `okstra git-reconcile — okstra 밖 git 히스토리 변경 후 기록 화해
+
+A thin shim over \`python3 -m okstra_ctl.git_reconcile\`. 기본은 검사:
+stale 항목을 JSON 으로 출력하고, confirm 항목이 남으면 exit 2.
+patch-id 로 내용 동일성이 증명되는 항목(auto)은 --apply 로 일괄 보정되고,
+내용이 바뀐 항목(confirm)은 --stage/--use-ref 로만 보정된다.
+
+Usage:
+  okstra git-reconcile --plan-run-root <dir> --project-id <id> \\
+    --task-group <g> --task-id <t> --work-category <c> \\
+    [--apply] [--stage <N> --use-ref <ref>] [--reset-anchor <ref>] [--json]
+
+Exit codes:
+  0  stale 없음 또는 보정 완료
+  2  confirm 항목 잔존 (check: 확인 필요 / apply: 일부 미보정)
+  1  error (resolve 실패 등)
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const { code } = await runPythonModule({
+    module: "okstra_ctl.git_reconcile",
+    args,
+  });
+  return code ?? 1;
+}

package/src/handoff.mjs

@@ -0,0 +1,30 @@
+import { runPythonModule } from "./_python-helper.mjs";
+
+const USAGE = `okstra handoff — release-handoff stage-group 보조 (자격/수집/기록)
+
+A thin shim over \`python3 -m okstra_ctl.handoff\`. JSON 출력.
+
+Usage:
+  okstra handoff eligible --plan-run-root <dir> --approved-plan <md>
+  okstra handoff assemble --plan-run-root <dir> --approved-plan <md> \\
+    --project-root <dir> --project-id <id> --task-group <g> --task-id <t> \\
+    --work-category <c> --stages 2,3 --base <branch>
+  okstra handoff record-verified --plan-run-root <dir> --stage <N> \\
+    --report-path <md> --data-json <json>
+  okstra handoff record-pr --plan-run-root <dir> --stages 2,3 \\
+    --branch <b> --url <u>
+
+Exit codes: 0 ok / 1 자격·전제 위반 / 2 stage 간 merge 충돌(conflicts 동봉)
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const { code } = await runPythonModule({
+    module: "okstra_ctl.handoff",
+    args,
+  });
+  return code ?? 1;
+}