okstra 0.205.1 → 0.206.1

package/runtime/python/okstra_ctl/phases/final_verification/target.py

@@ -0,0 +1,296 @@
+"""final-verification 이 검증할 대상을 고른다.
+
+단일 stage 검증은 그 stage 의 worktree 를 읽기만 한다. 전체 작업 검증은 완료된
+stage 전부를 담은 stage 브랜치가 있으면 그것을 쓰고, 없으면 task 브랜치에 통합한
+결과를 쓴다. 원장·registry·Git·통합은 공통 모듈이 제공하고, 여기서는 어느 것을
+언제 부를지만 정한다. 전체 과정은 task 키 잠금 하나 안에서 돈다.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any
+
+from okstra_project.dirs import okstra_home
+from okstra_project.slug import slugify
+
+from okstra_ctl import worktree_registry
+from okstra_ctl.consumers import (
+    backfill_done_from_carry,
+    latest_done_by_stage,
+    read_stage_consumer_state,
+)
+from okstra_ctl.locks import worktree_provision_mutex
+from okstra_ctl.plan_run_root import plan_run_root_from_approved_plan
+from okstra_ctl.prepare_error import PrepareError
+from okstra_ctl.stage_integrate import IntegrateResult
+from okstra_ctl.stage_reconcile import auto_reconcile_best_effort
+from okstra_ctl.stage_targets import (
+    FinalVerificationTarget,
+    StageTargetError,
+    _resolve_and_integrate_whole_task_unlocked,
+    containing_stage,
+    relocate_nested_stage_worktrees,
+)
+from okstra_ctl.worktree import _git, is_dirty_excluding_okstra
+
+
+@dataclass(frozen=True)
+class FinalVerificationTargetRequest:
+    """Semantic inputs needed to acquire one final-verification target."""
+
+    project_root: Path
+    project_id: str
+    task_group: str
+    task_id: str
+    work_category: str
+    approved_plan_path: Path
+    stage: int | None
+    stage_map: tuple[dict[str, Any], ...]
+
+
+@dataclass(frozen=True)
+class FinalVerificationTargetAcquisition:
+    """Resolved target facts returned to the prepare adapter."""
+
+    target: FinalVerificationTarget
+    worktree_branch: str
+    integration_result: IntegrateResult | None
+    # whole-task 진입이 task worktree 안에서 꺼낸 중첩 stage worktree.
+    # `{"stage": N, "from": <old path>, "to": <new path>}` 행.
+    relocations: tuple[dict[str, Any], ...] = ()
+
+
+def _resolve_single_stage_target(
+    *,
+    requested_stage: int,
+    done_rows: list[dict[str, Any]],
+    stage_base: str,
+    stage_worktree_path: str,
+    stage_head: str,
+    stage_dirty: bool,
+) -> FinalVerificationTarget:
+    """Resolve single-stage final-verification target, enforcing all gates."""
+    n = requested_stage
+    done_by_stage = latest_done_by_stage(done_rows)
+    if n not in done_by_stage:
+        raise StageTargetError(
+            f"final-verification(single-stage): stage {n} not done — "
+            f"run implementation --stage {n} first"
+        )
+    if not stage_worktree_path:
+        raise StageTargetError(
+            f"final-verification(single-stage): stage worktree not found for "
+            f"stage {n} (torn down?) — use whole-task mode (--stage auto)"
+        )
+    if stage_dirty:
+        raise StageTargetError(
+            "final-verification: worktree has uncommitted source changes "
+            "(outside .okstra/) — commit or stash before verifying"
+        )
+    return FinalVerificationTarget(
+        scope="single-stage",
+        base=stage_base,
+        head=stage_head,
+        worktree_path=stage_worktree_path,
+        stages=[n],
+        reports=[done_by_stage[n].get("report_path", "")],
+    )
+
+
+def _read_final_verification_done_rows(
+    request: FinalVerificationTargetRequest,
+    registry_coordinates: tuple[str, str, str],
+) -> list[dict[str, Any]]:
+    plan_run_root = plan_run_root_from_approved_plan(request.approved_plan_path)
+    backfill_done_from_carry(plan_run_root)
+    project_id, task_group, task_id = registry_coordinates
+    auto_reconcile_best_effort(
+        replace(
+            request,
+            project_id=project_id,
+            task_group=task_group,
+            task_id=task_id,
+        ),
+        plan_run_root,
+    )
+    return read_stage_consumer_state(plan_run_root).done_rows
+
+
+def _final_verification_registry_coordinates(
+    request: FinalVerificationTargetRequest,
+) -> tuple[str, str, str]:
+
+    def segment(value: str) -> str:
+        return slugify(value) or "_"
+
+    return (
+        segment(request.project_id),
+        segment(request.task_group),
+        segment(request.task_id),
+    )
+
+
+def _acquire_single_stage_target(
+    request: FinalVerificationTargetRequest,
+    done_rows: list[dict[str, Any]],
+    registry_coordinates: tuple[str, str, str],
+) -> FinalVerificationTargetAcquisition:
+    stage = request.stage
+    assert stage is not None
+    row = worktree_registry.get_stage_row(*registry_coordinates, stage)
+    worktree_path = (row or {}).get("worktree_path", "")
+    head = ""
+    if worktree_path and Path(worktree_path).is_dir():
+        head_result = _git(worktree_path, "rev-parse", "HEAD")
+        if head_result.returncode == 0:
+            head = head_result.stdout.strip()
+    if not head:
+        worktree_path = ""
+    target = _resolve_single_stage_target(
+        requested_stage=stage,
+        done_rows=done_rows,
+        stage_base=(row or {}).get("base_ref", ""),
+        stage_worktree_path=worktree_path,
+        stage_head=head,
+        stage_dirty=(
+            is_dirty_excluding_okstra(worktree_path) if worktree_path else False
+        ),
+    )
+    return FinalVerificationTargetAcquisition(
+        target=target,
+        worktree_branch=(row or {}).get("branch", ""),
+        integration_result=None,
+    )
+
+
+def _acquire_tip_stage_target(
+    request: FinalVerificationTargetRequest,
+    done_rows: list[dict[str, Any]],
+    registry_coordinates: tuple[str, str, str],
+) -> FinalVerificationTargetAcquisition | None:
+    """전체를 담은 단일 stage 브랜치가 있으면 그것을 whole-task 검증 대상으로
+    삼는다 — 머지 없이. 없거나 그 워크트리가 쓸 수 없으면 None 을 돌려 기존
+    task 브랜치 통합 경로로 넘긴다."""
+    done = latest_done_by_stage(done_rows)
+    planned = [int(s["stage_number"]) for s in request.stage_map]
+    if any(n not in done for n in planned):
+        return None  # 미완 stage 의 거부 메시지는 기존 경로가 낸다
+    tip = containing_stage(request.project_root,
+                          {n: done[n] for n in planned})
+    if tip is None:
+        return None
+    row = worktree_registry.get_stage_row(*registry_coordinates, tip) or {}
+    worktree_path = row.get("worktree_path", "")
+    if not worktree_path or not Path(worktree_path).is_dir():
+        return None
+    head_result = _git(worktree_path, "rev-parse", "HEAD")
+    if head_result.returncode != 0:
+        return None
+    head = head_result.stdout.strip()
+    if head != done[tip].get("head_commit", ""):
+        # 브랜치 tip 이 done 기록과 갈라져 있다. 검증 대상이 무엇인지 모호하므로
+        # 판정을 기존 경로로 넘긴다.
+        return None
+    if is_dirty_excluding_okstra(worktree_path):
+        raise StageTargetError(
+            "final-verification: worktree has uncommitted source changes "
+            "(outside .okstra/) — commit or stash before verifying"
+        )
+    anchor_base = worktree_registry.get_implementation_base(
+        *registry_coordinates) or ""
+    stages = sorted(planned)
+    return FinalVerificationTargetAcquisition(
+        target=FinalVerificationTarget(
+            scope="whole-task",
+            base=anchor_base,
+            head=head,
+            worktree_path=worktree_path,
+            stages=stages,
+            reports=[done[n].get("report_path", "") for n in stages],
+        ),
+        relocations=(),
+        worktree_branch=row.get("branch", ""),
+        integration_result=None,
+    )
+
+
+def _acquire_whole_task_target(
+    request: FinalVerificationTargetRequest,
+    done_rows: list[dict[str, Any]],
+    registry_coordinates: tuple[str, str, str],
+) -> FinalVerificationTargetAcquisition:
+    tip = _acquire_tip_stage_target(request, done_rows, registry_coordinates)
+    if tip is not None:
+        return tip
+
+    project_id, task_group, task_id = registry_coordinates
+    entry = worktree_registry.lookup(project_id, task_group, task_id)
+    worktree_path = (
+        entry.worktree_path if entry is not None else str(request.project_root)
+    )
+    relocations = (
+        relocate_nested_stage_worktrees(
+            project_id, task_group, task_id, worktree_path,
+            stages=[int(row["stage_number"]) for row in request.stage_map],
+        )
+        if entry is not None
+        else []
+    )
+    whole = _resolve_and_integrate_whole_task_unlocked(
+        project_id=project_id,
+        task_group=task_group,
+        task_id=task_id,
+        task_worktree_path=worktree_path,
+        stage_map=list(request.stage_map),
+        done_rows=done_rows,
+        anchor_base=(
+            worktree_registry.get_implementation_base(
+                project_id, task_group, task_id
+            )
+            or ""
+        ),
+        # 정리는 판정 뒤로 미룬다(Phase 7 `teardown-stages`). 되돌릴 수 없는 정리를
+        # 판정 앞에 두면, 재작업이 가장 필요한 blocked 판정에서 stage 작업물이 이미
+        # 사라져 있다. 여기서는 통합만 하고 worktree/registry 키는 남긴다.
+        teardown=False,
+    )
+    return FinalVerificationTargetAcquisition(
+        target=whole["target"],
+        relocations=tuple(relocations),
+        worktree_branch=entry.branch if entry is not None else "",
+        integration_result=whole["integrate_result"],
+    )
+
+
+def acquire_final_verification_target(
+    request: FinalVerificationTargetRequest,
+) -> FinalVerificationTargetAcquisition:
+    """Acquire a stable final-verification target behind one task-key lock."""
+    try:
+        with worktree_provision_mutex(
+            okstra_home(),
+            request.project_id,
+            slugify(request.task_group),
+            slugify(request.task_id),
+        ):
+            registry_coordinates = _final_verification_registry_coordinates(request)
+            done_rows = _read_final_verification_done_rows(
+                request,
+                registry_coordinates,
+            )
+            if request.stage is not None:
+                return _acquire_single_stage_target(
+                    request,
+                    done_rows,
+                    registry_coordinates,
+                )
+            return _acquire_whole_task_target(
+                request,
+                done_rows,
+                registry_coordinates,
+            )
+    except PrepareError:
+        raise
+    except (OSError, RuntimeError, StageTargetError, ValueError) as exc:
+        raise PrepareError(str(exc)) from exc

package/runtime/python/okstra_ctl/phases/final_verification/validation.py

@@ -0,0 +1,190 @@
+"""final-verification 이 소유하는 보고서 내용 판정.
+
+추가 표면·판정·검증 범위의 일관성과, 보고서가 준비된 검증 대상을 그대로
+비추는지를 본다. 이동 적합성은 공통 검증이 이어서 본다. 이 모듈은 공통 실행 조립부를
+가져오지 않는다.
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from pathlib import Path
+
+from okstra_ctl.verification_target import TARGET_FIELD_RES, read_verification_target
+
+_ADDED_SURFACE_NO_CALLER_RE = re.compile(r"^\s*none\b", re.IGNORECASE)
+
+
+def validate_final_verification_content(data: dict, failures: list[str]) -> None:
+    """판정·차단 항목·검증 범위가 서로 맞는지 본다. 다른 작업 유형은 건너뛴다."""
+    if (data.get("header") or {}).get("taskType") != "final-verification":
+        return
+    _validate_added_surface_audit(data, failures)
+    _validate_verdict_consistency(data, failures)
+    _validate_verification_scope(data, failures)
+
+
+def _validate_added_surface_audit(data: dict, failures: list[str]) -> None:
+    """Every surface the diff added is traced to a requirement, exempted, or paid for.
+
+    The coverage table proves each requirement reached the diff. Nothing proved
+    the reverse — that each thing the diff added answers a requirement — so work
+    nobody asked for passed every gate. This check reads the reverse table and
+    refuses a row that calls itself over-delivery without the blocker or
+    condition it became: a caller-less surface is an acceptance blocker, and a
+    surface with callers but no requirement is a conditional-acceptance
+    condition (ADR-0009 grades the two differently on purpose).
+    """
+    fv = data.get("finalVerification")
+    if not isinstance(fv, Mapping):
+        return
+    rows = fv.get("addedSurfaceAudit")
+    if not isinstance(rows, list):
+        return
+    blocker_ids = _row_ids(fv.get("acceptanceBlockers"))
+    condition_ids = _row_ids(
+        (data.get("finalVerdict") or {}).get("conditionalAcceptanceConditions")
+    )
+    for row in rows:
+        if isinstance(row, Mapping):
+            failures.extend(_added_surface_row_failures(row, blocker_ids, condition_ids))
+
+
+def _row_ids(rows: object) -> set[str]:
+    if not isinstance(rows, list):
+        return set()
+    return {str(row.get("id")) for row in rows if isinstance(row, Mapping)}
+
+
+def _added_surface_row_failures(
+    row: Mapping,
+    blocker_ids: set[str],
+    condition_ids: set[str],
+) -> list[str]:
+    row_id = str(row.get("id") or "<id 없음>")
+    disposition = str(row.get("disposition") or "")
+    note = str(row.get("note") or "")
+    if disposition == "traced" and not str(row.get("requirement") or "").strip():
+        return [
+            f"final-verification: addedSurfaceAudit {row_id} is `traced` but "
+            "names no requirement — a surface is traced to something the "
+            "brief asked for, or it is not traced."
+        ]
+    if disposition != "over-delivery":
+        return []
+    caller_less = bool(_ADDED_SURFACE_NO_CALLER_RE.match(str(row.get("callers") or "")))
+    expected, known = ("AB", blocker_ids) if caller_less else ("CA", condition_ids)
+    cited = set(re.findall(rf"\b{expected}-\d{{3,}}\b", note))
+    if not cited:
+        detail = (
+            "a caller-less surface is an acceptance blocker"
+            if caller_less
+            else "a surface with callers but no requirement is a "
+                 "conditional-acceptance condition"
+        )
+        callers = "none" if caller_less else "recorded"
+        return [
+            f"final-verification: addedSurfaceAudit {row_id} is "
+            f"`over-delivery` with callers {callers}, so its note MUST cite "
+            f"the `{expected}-NNN` row it became — {detail}."
+        ]
+    missing = sorted(cited - known)
+    if missing:
+        return [
+            f"final-verification: addedSurfaceAudit {row_id} cites "
+            f"{missing}, which the report does not carry."
+        ]
+    return []
+
+
+def _validate_verdict_consistency(data: dict, failures: list[str]) -> None:
+    verdict = data.get("finalVerdict") or {}
+    token = (verdict.get("verdictToken") or "").strip().lower()
+    blockers = (data.get("finalVerification") or {}).get("acceptanceBlockers") or []
+    conditions = verdict.get("conditionalAcceptanceConditions") or []
+    if token == "accepted" and blockers:
+        failures.append(
+            "final-verification: verdict `accepted` but acceptanceBlockers is "
+            "non-empty — an accepted verdict must have zero blockers."
+        )
+    if token == "blocked" and not blockers:
+        failures.append(
+            "final-verification: verdict `blocked` but acceptanceBlockers is "
+            "empty — a blocked verdict must list at least one blocker."
+        )
+    if token == "conditional-accept" and not conditions:
+        failures.append(
+            "final-verification: verdict `conditional-accept` but "
+            "conditionalAcceptanceConditions is empty — list every condition."
+        )
+
+
+def _validate_verification_scope(data: dict, failures: list[str]) -> None:
+    scope = data.get("verificationScope", "whole-task")
+    if scope not in ("whole-task", "single-stage"):
+        failures.append(
+            f"final-verification: verificationScope must be `whole-task` or "
+            f"`single-stage`, got {scope!r}."
+        )
+
+
+def validate_verification_target_match(
+    data: dict,
+    run_manifest: dict,
+    project_root: Path,
+    failures: list[str],
+) -> None:
+    """The verification report must mirror the target it was prepared against.
+
+    `verificationScope`, the worktree, and the base/head refs were entirely
+    self-declared: the schema required the fields to exist but nothing compared
+    them to the digest-verified snapshot written at prep time. That matters
+    because both `handoff.compute_eligibility` and the `release-handoff`
+    routing check read `verificationScope` — a single-stage run that writes
+    `whole-task` passes both, and an `accepted` verdict can be rendered against
+    a worktree or head nobody verified.
+    """
+    # 스냅샷의 다이제스트 규칙과 파싱은 `okstra_ctl.verification_target` 한 곳이
+    # 쥔다. 조립도 같은 파일을 읽어 `verificationScope` 를 기록한다.
+    # 최상위 `verificationTargetPath` 가 run 매니페스트의 실물 키다(render.py).
+    # `instructionSet` 블록은 active-run-context 의 것이라 여기서 읽으면 검사가
+    # 통째로 건너뛰어졌다(실측 2026-09-06, dev-10626 final-verification 001).
+    relative = str(run_manifest.get("verificationTargetPath") or "").strip()
+    if not relative:
+        return
+    target = read_verification_target(project_root, relative)
+    if target is None:
+        return
+
+    source = (data.get("finalVerification") or {}).get("sourceImplementationReport") or {}
+    declared = {
+        "scope": str(data.get("verificationScope") or "").strip(),
+        "worktree": str(source.get("worktreePath") or "").strip(),
+        "base": str(source.get("implementationBaseRef") or "").strip(),
+        "head": str(source.get("capturedHeadSha") or "").strip(),
+    }
+    for key, expected in ((k, target[k]) for k in TARGET_FIELD_RES):
+        actual = declared[key]
+        if expected and actual and actual != expected:
+            failures.append(
+                f"final-verification report declares {key} `{actual}` but the "
+                f"prepared verification target says `{expected}` "
+                f"(`{relative}`). The report must mirror the target it was "
+                "prepared against — `verificationScope` in particular gates "
+                "both stage-group eligibility and release-handoff routing, so "
+                "a self-declared value lets a run be judged as something it "
+                "was not."
+            )
+
+    declared_stages = {
+        row.get("stage")
+        for row in ((data.get("finalVerification") or {}).get("stageReports") or [])
+        if isinstance(row, dict) and isinstance(row.get("stage"), int)
+    }
+    if target["stages"] and declared_stages and declared_stages != target["stages"]:
+        failures.append(
+            f"final-verification report covers stages {sorted(declared_stages)} "
+            f"but the prepared target names {sorted(target['stages'])} "
+            f"(`{relative}`). A verdict must not be rendered for a stage set "
+            "nobody prepared evidence for."
+        )

package/runtime/python/okstra_ctl/phases/final_verification/wizard.py

@@ -0,0 +1,38 @@
+"""final-verification 이 위저드의 stage 선택에 거는 조건."""
+from __future__ import annotations
+
+
+def whole_task_verification_allowed(
+    *,
+    stage_numbers: tuple[int, ...],
+    done_stages: set[int],
+) -> bool:
+    """승인된 계획의 stage 가 전부 done 일 때만 전체 작업 검증을 고를 수 있다."""
+    if not stage_numbers:
+        return False
+    return all(number in done_stages for number in stage_numbers)
+
+
+class StageAnswerError(ValueError):
+    """stage 선택 답이 final-verification 이 받을 수 있는 값이 아니다."""
+
+
+def validate_stage_answer(
+    answer: str, *, whole_task_token: str, whole_task_allowed: bool
+) -> str:
+    """전체 작업 토큰 또는 stage 번호 하나만 받는다. 여러 개나 auto 는 받지 않는다."""
+    if not answer:
+        raise StageAnswerError("value required")
+    if answer == whole_task_token:
+        if not whole_task_allowed:
+            raise StageAnswerError(
+                "whole-task verification requires final-verification "
+                "with all stages done")
+        return answer
+    try:
+        int(answer)
+    except ValueError:
+        raise StageAnswerError(
+            f"answer must be whole-task or a stage number, got {answer!r}"
+        ) from None
+    return answer

package/runtime/python/okstra_ctl/phases/implementation/__init__.py

@@ -0,0 +1 @@
+"""implementation 단계의 실행 정책과 자산."""

package/runtime/python/okstra_ctl/phases/implementation/boundary.json

@@ -0,0 +1,17 @@
+{
+  "allowed": "  - approved-plan reference and quoted user-approval evidence\n  - commit list with SHA, message, and the plan step each commit satisfies\n  - `git diff --stat <base>..HEAD` summary plus per-file one-line change summary\n  - `Out-of-plan edits` block listing every file touched outside the approved plan with rationale (empty block preferred)\n  - validation evidence: actual stdout/stderr and exit code for every pre / mid / post command from the plan (no paraphrased \"tests pass\")\n  - TDD evidence for TDD-applicable steps: failing-test output before implementation commit and passing-test output after, with framing SHAs\n  - per-verifier sections for every verifier in the resolved roster, with an independent verdict (PASS / CONCERNS / FAIL) and cited diff snippets; dissent is preserved by the Okstra lead\n  - rollback verification (advisory, never blocks — record the revert path for a human; `result` is ok / not-applicable / advisory — human-run)\n  - routing recommendation as the `routingRecommendation` object `{target, rationale}`: `target` is one of `final-verification`, `error-analysis`, `implementation-planning`, `implementation`, and `rationale` is why that one and nothing else. Prose alone does not route the task — Phase 7 projects `workflow.nextRecommendedPhase` from `target`",
+  "forbidden": [
+    "any Edit/Write or state-mutating Bash before the pre-implementation gate passes (gate requires --approved-plan pointing to a final-report.md whose frontmatter has `approved: true`)",
+    "`git push` of any kind (including `--dry-run` against a real remote that produces side-effects), `npm publish` / `cargo publish` / `pip publish`, `gh release`, `docker push`",
+    "real database migrations, schema changes against shared environments, or writes to non-local datastores",
+    "production credentials, deploy commands, infra mutation (`terraform apply`, `kubectl apply` against non-local cluster, etc.)",
+    "external API write calls (POST/PUT/PATCH/DELETE) to third-party services other than localhost test fixtures",
+    "source edits or Bash mutations performed by any verifier role (`Antigravity verifier`, `Codex verifier`, `Claude verifier` are read-only — recommend, do not apply)",
+    "dispatching parallel sub-agents beyond the required worker roster",
+    "silent scope expansion: every file edited outside the approved plan list MUST appear in the `Out-of-plan edits` block with rationale",
+    "leaving placeholders such as TBD / TODO / \"implement later\" / \"handle edge cases\" in newly-added lines of this run (check via `git diff <base>..HEAD | grep -E '^\\+[^+].*\\b(TBD|TODO|FIXME|XXX|implement later|handle edge cases|similar to|placeholder)\\b'`; pre-existing strings in untouched regions are out of scope)",
+    "lead substituting its own verdict when every verifier present in the resolved roster returned a non-result terminal status (`timeout`/`error`/`not-run`); in that case the run MUST end as `blocked` with routing recommendation back to `error-analysis`, never with a lead-only verdict",
+    "declaring overall task acceptance — that is `final-verification` ownership; this phase reports only \"ready for final-verification\" or \"needs new planning loop\"",
+    "delegating the self-review pass — the Okstra lead must run it"
+  ]
+}

package/runtime/python/okstra_ctl/{implementation_stage.py → phases/implementation/entry.py}

@@ -7,17 +7,18 @@ isolated stage worktree, and record the started event.
 from __future__ import annotations
 
 import datetime as _dt
+import re
 import subprocess
 import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
-from . import stage_targets
-from .design_prep import DesignPrepDecision, DesignPrepError, resolve_design_prep
-from .final_report_paths import final_report_data_path
-from .stage_reconcile import auto_reconcile_best_effort
-from .worker_prompt_policy import IMPLEMENTATION_STAGE_HEADER
+from okstra_ctl import stage_targets
+from okstra_ctl.design_prep import DesignPrepDecision, DesignPrepError, resolve_design_prep
+from okstra_ctl.final_report_paths import final_report_data_path
+from okstra_ctl.stage_reconcile import auto_reconcile_best_effort
+from okstra_ctl.worker_prompt_policy import IMPLEMENTATION_STAGE_HEADER
 
 
 class ImplementationStageError(Exception):
@@ -87,9 +88,9 @@ def claim_implementation_stage_run(
     callers can compute stage-specific run paths after this function resolves
     the selected stage.
     """
-    from .consumers import backfill_done_from_carry
-    from . import worktree as _worktree
-    from . import worktree_registry as _reg
+    from okstra_ctl.consumers import backfill_done_from_carry
+    from okstra_ctl import worktree as _worktree
+    from okstra_ctl import worktree_registry as _reg
 
     plan_run_root = Path(inp.approved_plan_path).resolve().parents[1]
     backfill_done_from_carry(plan_run_root)
@@ -201,7 +202,7 @@ def claim_implementation_stage_run(
             base_commit=stage_base,
         )
     except RuntimeError as exc:
-        from .git_reconcile import guidance
+        from okstra_ctl.git_reconcile import guidance
 
         hint = guidance(
             plan_run_root=plan_run_root,
@@ -234,7 +235,7 @@ def _record_stage_run_claim_started(
     plan_run_root: Path,
     claim: StageRunClaim,
 ) -> None:
-    from .consumers import append_consumer
+    from okstra_ctl.consumers import append_consumer
 
     now = _dt.datetime.now(_dt.timezone.utc).isoformat()
     append_consumer(
@@ -275,3 +276,14 @@ def publish_stage_run_claim(
         ctx["EXECUTOR_WORKTREE_BASE_REF"] = claim.worktree_base_ref
         ctx["EXECUTOR_WORKTREE_STATUS"] = claim.worktree_status
         ctx["EXECUTOR_WORKTREE_NOTE"] = claim.worktree_note
+
+
+def resolve_instruction_paths(text: str, asset_root: Path) -> str:
+    """리드가 직접 여는 보조 지침은 설치 형태에 맞는 실제 경로로 기록한다."""
+    from okstra_ctl.phases.catalog import profile_sidecar
+
+    return re.sub(
+        r"(?:prompts/profiles|scripts/okstra_ctl/phases/implementation/instructions)/_implementation-[\w-]+\.md",
+        lambda match: str(profile_sidecar(asset_root, match.group(0))),
+        text,
+    )

package/runtime/{prompts/host-orchestration/implementation.md → python/okstra_ctl/phases/implementation/host-rules.md}

@@ -54,7 +54,7 @@ If the anchor (`implementation_base_commit`) is reported unresolvable, run the s
 Because of the dependency closure, the chain queue **may include a stage that another implementation run has occupied as started/reserved.** That stage's `render-bundle` is rejected with `--stage N already in progress or reserved by another run` (StageTargetError). This is **not** an exception gate needing human judgment but a "next stage not yet ready" situation. On this rejection, **terminate the chain normally** and report the remaining queue to the user (e.g. `remaining queue: stage 4, 5 — resume with okstra-run after occupancy is released`). This is a different branch from the exception gate below (data corruption·concurrent-occupancy conflict confirmation).
 
 ### Stage ended FAIL — stop the queue and report (not an exception gate)
-When a stage's synthesised verdict is `FAIL`, Phase 6 writes no carry sidecar and appends a `status:"failed"` row in place of `done` (`prompts/profiles/_implementation-deliverable.md` "Lead post-stage persistence"). **Stop the queue at that stage** and report the failed stage, its report path, and the remaining queue (e.g. `stage 1 FAIL — remaining queue: stage 2, 3, 5; re-enter with okstra-run --stage 1 after the fix`). Do **not** continue to the next stage even when that stage is dependency-independent: an unattended chain that keeps building past a confirmed regression stacks later work on top of it. The `failed` row releases the stage's occupancy, so `--stage <N>` re-enters the same stage on its preserved worktree and branch — there is nothing to unblock by hand.
+When a stage's synthesised verdict is `FAIL`, Phase 6 writes no carry sidecar and appends a `status:"failed"` row in place of `done` (`scripts/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md` "Lead post-stage persistence"). **Stop the queue at that stage** and report the failed stage, its report path, and the remaining queue (e.g. `stage 1 FAIL — remaining queue: stage 2, 3, 5; re-enter with okstra-run --stage 1 after the fix`). Do **not** continue to the next stage even when that stage is dependency-independent: an unattended chain that keeps building past a confirmed regression stacks later work on top of it. The `failed` row releases the stage's occupancy, so `--stage <N>` re-enters the same stage on its preserved worktree and branch — there is nothing to unblock by hand.
 
 ### Exception gate during chaining
 If `render-bundle` raises Step 5's concurrent-run conflict detection (concurrent-run branch) or git stale-SHA reconciliation (git-reconcile branch), **stop the chain at that stage** and present the gate to the user exactly as Step 5 prescribes. Once the user resolves the gate, resume the chain in place (continue with the remaining queue). Data corruption·concurrent-occupancy conflicts are confirmed by a human — this is the safety boundary of unattended chaining. (Unlike the "not ready" rejection above, these two branches do not discard the queue; they wait for user resolution.)

package/runtime/{prompts/profiles → python/okstra_ctl/phases/implementation/instructions}/_implementation-deliverable.md

@@ -37,7 +37,7 @@ are collected and convergence finished. Phase 1-5 do not need it.
   evidence and add one `recommendedNextSteps` item with environment
   prerequisites and the expected `QA-RESULT`. This is user-owned verification;
   do not route back or fail implementation solely for this advisory.
-- **Routing recommendation**: `implementation.routingRecommendation` is an **object** with exactly two fields — `target`, one of `final-verification`, `error-analysis`, `implementation-planning`, `implementation`, and `rationale`, one or two sentences on why that target and nothing else. It is not a prose note: Phase 7 projects `workflow.nextRecommendedPhase` from `target` alone, so a phase named only in the prose does not route the task. Pick `final-verification` when this stage's plan items landed and validation passed; `error-analysis` when a failure's cause is not understood; `implementation-planning` when the approved plan itself no longer fits the evidence; `implementation` when work remains inside this stage and the next run is a fix run. **Enforced:** `schemas/final-report-v2.0.schema.json` rejects a `target` outside the enum, a missing `rationale`, and a string in place of the object.
+- **Routing recommendation**: `implementation.routingRecommendation` is an **object** with exactly two fields — `target`, one of `final-verification`, `error-analysis`, `implementation-planning`, `implementation`, and `rationale`, one or two sentences on why that target and nothing else. It is not a prose note: Phase 7 projects `workflow.nextRecommendedPhase` from `target` alone, so a phase named only in the prose does not route the task. Record the stage completion, validation outcome, failure-cause certainty, and plan-fit evidence; the lead chooses the destination using `prompts/lead/phase-routing.md` §implementation. **Enforced:** `schemas/final-report-v2.0.schema.json` rejects a `target` outside the enum, a missing `rationale`, and a string in place of the object.
 - **Follow-up tasks (Section 4 of the final report)**: every item discovered during this run that was *not* delivered MUST appear in the final report's `## 4. 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 unresolved `## 1. Clarification Items` row carried over from the approved plan (`Status` ∈ `{open, answered}` at approval time). An empty section is acceptable but only when expressed as the single line `- No follow-up tasks.` — 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 3. Recommended Next Steps` so the user knows to act manually.
 
 ## Self-review pass before finalising the report (the Okstra lead runs this; do not delegate it)