okstra 0.222.0 → 0.223.0

package/docs/architecture.md

@@ -517,7 +517,7 @@ The PR base follows the stage's `depends-on`, after dropping predecessors alread
 | one | that stage's branch — a stacked PR | no |
 | several | a branch merging their recorded `done.head_commit`s, named `<work-category-namespace>/<task-id-segment>-g<n1>-<n2>` | yes, by `pr-plan` |
 
-A merge-base branch combines independent predecessors and is a base only, never a PR head. When a predecessor advances, `okstra_ctl.stage_rebase` rebases downstream stage branches in dependency order instead of merging the moving base into them. Implementation entry, verification target acquisition, and PR planning share this operation. Old heads are preserved under `refs/okstra/rebase-backups/`; registry bases and completion commits are updated, invalidating previous verification. PR planning stops after a stack change for fresh final-verification. Conflicts abort the current rebase, and dirty or active stages stop synchronization. A published branch that diverges from origin needs explicit delivery instructions; merging old origin history back into it is not recovery. Merge PRs in dependency order with a merge commit or rebase-merge; squashing replaces the commits the next PR's base points at.
+This derivation covers stacking inside one task. The release base must contain the task's implementation anchor base: a task built on another task's unmerged stage branch takes that branch as its release base. Prepare names it as the recommended Q2 option in `release-handoff-input.md`, and `pr-plan` refuses a release base that lacks the anchor, because the PR would also carry the other task's commits. A merge-base branch combines independent predecessors and is a base only, never a PR head. When a predecessor advances, `okstra_ctl.stage_rebase` rebases downstream stage branches in dependency order instead of merging the moving base into them. Implementation entry, verification target acquisition, and PR planning share this operation. Old heads are preserved under `refs/okstra/rebase-backups/`; registry bases and completion commits are updated, invalidating previous verification. PR planning stops after a stack change for fresh final-verification. Conflicts abort the current rebase, and dirty or active stages stop synchronization. A published branch that diverges from origin needs explicit delivery instructions; merging old origin history back into it is not recovery. Merge PRs in dependency order with a merge commit or rebase-merge; squashing replaces the commits the next PR's base points at.
 
 Entry is based on **task ID**, without a brief. Briefs are inputs to entry phases; for release-handoff, prepare determines eligibility from the approved plan's Stage Map + Stage Lifecycle Snapshot, then automatically creates an input document (`<task_root>/release-handoff-input.md`) that cites the verification reports. Stage selection comes from the okstra-run wizard's `handoff_stage_pick` multiselect or CLI `--stages <csv>`; an empty selection takes every eligible stage, and the result is exposed to the lead as `HANDOFF_STAGES` in run-context.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.222.0",
+  "version": "0.223.0",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.222.0",
-  "builtAt": "2026-10-21T15:15:40.772Z",
+  "package": "0.223.0",
+  "builtAt": "2026-10-22T04:17:27.258Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -117,6 +117,7 @@ def build_analysis_packet(
     has_selected_direction: bool = False,
     mcp_servers_text: str = "",
     technical_evidence_text: str = "",
+    verification_target_path: str = "",
 ) -> str:
     """Return the primary compact input for Claude/Codex/Antigravity analysers.
 
@@ -139,6 +140,9 @@ def build_analysis_packet(
 
     `technical_evidence_text` 는 carry-in 이 technical-verification 결과일 때
     `technical_evidence_packet_block` 이 렌더한 증거 위치 절이다.
+
+    `verification_target_path` 는 final-verification prepare 가 run 별로 기록한
+    검증 대상 스냅샷 경로(매니페스트 `verificationTargetPath` 와 같은 값)다.
     """
     brief_text = task_brief_path.read_text(encoding="utf-8")
     group_context_text = _read_optional(group_context_path) if group_context_path else ""
@@ -152,7 +156,7 @@ def build_analysis_packet(
     parts.extend(
         _intro_block(
             task_key,
-            task_type,
+            verification_target_path,
             instruction_set_relative_path,
             bool(clarification_response_path),
             bool(group_context_text),
@@ -354,7 +358,7 @@ def _packet_frontmatter(brief_text: str, task_key: str) -> str:
 
 def _intro_block(
     task_key: str,
-    task_type: str,
+    verification_target_path: str,
     instruction_set: str,
     has_clarification: bool,
     has_group_context: bool = False,
@@ -376,10 +380,8 @@ def _intro_block(
         f"- Analysis material: `{instruction_set}/analysis-material.md`",
         f"- Reference expectations: `{instruction_set}/reference-expectations.md`",
     ]
-    if task_type == "final-verification":
-        lines.append(
-            f"- Verification target: `{instruction_set}/verification-target.md`"
-        )
+    if verification_target_path:
+        lines.append(f"- Verification target: `{verification_target_path}`")
     if has_clarification:
         lines.append(
             f"- Clarification response: `{instruction_set}/clarification-response.md`"

package/runtime/python/okstra_ctl/phases/release_handoff/entry.py

@@ -12,7 +12,10 @@ from okstra_ctl.pr_template import PrTemplateError, resolve_pr_template_path
 from okstra_ctl.stage_map import parse_stage_map_for_prepare
 from okstra_ctl.phases.catalog import migrated_report_template
 from okstra_ctl.handoff_error import HandoffError
-from .operations import _require_eligible, compute_eligibility, _parse_stages_csv
+from .operations import (
+    DEFAULT_RELEASE_BASES, _parse_stages_csv, _require_eligible,
+    anchor_base_branches, compute_eligibility,
+)
 
 
 def _collect_handoff_source_report_rows(
@@ -74,6 +77,43 @@ def _select_handoff_stages(stage_map: list, rows: list, selection: str) -> list[
     return nums
 
 
+def _render_anchor_base_candidates(project_root: Path, inp) -> str:
+    """구현 기준 커밋을 담은 기본 후보가 없으면, 그 커밋에 있는 origin 브랜치를
+    Q2 의 첫 후보로 올린다. 다른 task 의 미병합 stage 위에 쌓인 task 는 기본
+    후보 어느 것을 base 로 잡아도 그 task 의 커밋까지 PR 에 실린다."""
+    from okstra_ctl import worktree_registry
+    from okstra_ctl.work_categories import resolve_work_category
+    from okstra_ctl.worktree import is_ancestor
+
+    anchor = worktree_registry.get_implementation_base(
+        inp.project_id, inp.task_group, inp.task_id) or ""
+    if not anchor:
+        return ""
+    if any(is_ancestor(project_root, anchor, f"refs/remotes/origin/{name}")
+           for name in DEFAULT_RELEASE_BASES):
+        return ""
+    work_category = resolve_work_category(
+        inp.work_category, project_root=project_root,
+        task_group=inp.task_group, task_id=inp.task_id)
+    branches = anchor_base_branches(project_root, anchor,
+                                    work_category=work_category, task_id=inp.task_id)
+    held = branches["at"] + branches["containing"]
+    defaults = ", ".join(f"`{name}`" for name in DEFAULT_RELEASE_BASES)
+    lines = [f"- Implementation anchor base: `{anchor}` — no default candidate "
+             f"({defaults}) contains it, so a PR on any of them would also carry "
+             "the commits of the work this task was built on."]
+    if held:
+        lines.append(f"- Recommended release base (offer first in Q2): `{held[0]}`")
+    else:
+        lines.append("- Recommended release base: none — no origin branch holds the "
+                     "anchor; push the branch it came from before release-handoff.")
+    lines.append("- origin branches at the anchor: "
+                 + (", ".join(f"`{n}`" for n in branches["at"]) or "none"))
+    lines.append("- origin branches containing the anchor: "
+                 + (", ".join(f"`{n}`" for n in branches["containing"]) or "none"))
+    return "\n".join(lines)
+
+
 def materialize_handoff_input(
     workspace_root: Path, project_root: Path, inp, *, install_hint: str,
 ) -> dict:
@@ -133,6 +173,7 @@ def materialize_handoff_input(
         "HANDOFF_STAGES": stages_csv,
         "HANDOFF_SOURCE_REPORTS": source_rows,
         "HANDOFF_CONDITIONS": source_conditions,
+        "HANDOFF_ANCHOR_BASE_CANDIDATES": _render_anchor_base_candidates(project_root, inp),
     })
     inp.brief_path = out
     return {"HANDOFF_STAGES": stages_csv}

package/runtime/python/okstra_ctl/phases/release_handoff/operations.py

@@ -123,6 +123,51 @@ def _merge_base_for(*, project_root, project_id, task_group, task_id,
         raise HandoffError(str(exc)) from exc
 
 
+# 입력 문서 `Candidate Release Base Branches` 의 기본 후보와 같은 목록이다.
+DEFAULT_RELEASE_BASES = ("staging", "preprod", "prod", "main", "dev")
+
+
+def _origin_branches(project_root, flag: str, commit: str, own_prefix: str) -> List[str]:
+    """`git branch -r <flag> <commit>` 중 origin 브랜치 이름. 이 task 자신의 stage
+    브랜치는 릴리스 base 가 될 수 없으므로 뺀다."""
+    res = _git(Path(project_root), "branch", "-r", "--format=%(refname)", flag, commit)
+    if res.returncode != 0:
+        return []
+    prefix = "refs/remotes/origin/"
+    names = [line.strip()[len(prefix):] for line in res.stdout.splitlines()
+             if line.strip().startswith(prefix)]
+    return [n for n in names if n != "HEAD"
+            and n != own_prefix and not n.startswith(own_prefix + "-")]
+
+
+def anchor_base_branches(project_root, anchor: str, *, work_category: str,
+                         task_id: str) -> Dict[str, List[str]]:
+    """구현 기준 커밋을 tip 으로 가진 origin 브랜치와 그 커밋을 담은 브랜치."""
+    own = compute_branch_name(work_category=work_category, task_id_segment=task_id)
+    at = _origin_branches(project_root, "--points-at", anchor, own)
+    containing = [n for n in _origin_branches(project_root, "--contains", anchor, own)
+                  if n not in at]
+    return {"at": at, "containing": containing}
+
+
+def _foreign_anchor_error(*, stage: int, base_branch: str, anchor: str,
+                          branches: Dict[str, List[str]]) -> HandoffError:
+    held = branches["at"] + branches["containing"]
+    if held:
+        fix = f"re-run pr-plan with --base {held[0]}"
+    else:
+        fix = ("no origin branch holds that commit — push the branch it came "
+               f"from, or wait until it is merged into origin/{base_branch}")
+    return HandoffError(
+        f"stage {stage} would target origin/{base_branch}, but this task was "
+        f"implemented on {anchor}, which origin/{base_branch} does not contain "
+        "— the PR would also carry every commit between them, which belong to "
+        "other work. pr-plan derives stacking within this task only; a task "
+        "built on another task's unmerged branch needs that branch as its "
+        f"release base. origin branches at {anchor}: {branches['at'] or 'none'}; "
+        f"containing it: {branches['containing'] or 'none'}. {fix}")
+
+
 def _resolve_stage_base(
     *, stage: int, deps: List[int], selected: List[int], pr_covered: set,
     done: Dict[int, Dict[str, Any]], project_root, base_branch: str,
@@ -135,6 +180,13 @@ def _resolve_stage_base(
             if not is_ancestor(project_root, _done_head(done, d),
                                f"origin/{base_branch}")]
     if not live:
+        if anchor_base and not is_ancestor(project_root, anchor_base,
+                                           f"origin/{base_branch}"):
+            raise _foreign_anchor_error(
+                stage=stage, base_branch=base_branch, anchor=anchor_base,
+                branches=anchor_base_branches(
+                    project_root, anchor_base, work_category=work_category,
+                    task_id=task_id))
         commit = _run_git(["rev-parse", f"origin/{base_branch}"],
                           project_root).stdout.strip()
         return {"base_kind": "release-base", "base_branch": base_branch,

package/runtime/python/okstra_ctl/phases/release_handoff/profile.md

@@ -31,13 +31,14 @@
       `okstra handoff local-checkout --project-root <project root> --project-id <id> --task-group <g> --task-id <t> --stage <N>`
       Exit 1 means a precondition failed (MAIN worktree dirty, registry entry missing, a run still holds the stage, the target branch already deleted, or checkout failed): show the error verbatim and re-ask the action selection. On success the okstra worktree for that stage no longer exists — if the lead's cwd was inside it, EVERY subsequent step (final-report authoring included) MUST use absolute paths or run from the MAIN worktree. Then route to the final-report self-review pass.
   2. **Release base branch** (only when the user picked `push + PR`) — present these options and capture exactly one:
+     - the `Recommended release base` from the input document's `## Candidate Release Base Branches`, when that section names one — first, marked recommended
      - `preprod`
      - `main`
      - `direct input` (free-form branch name; lead validates the name exists on origin via `git ls-remote --heads origin <name>` and re-asks on failure)
-     This is the release base for the run, not necessarily each PR's base: a stage that sits on another stage targets that stage's branch. The chosen base MUST NOT be one of the stage branches. If it is, re-ask.
+     This is the release base for the run, not necessarily each PR's base: a stage that sits on another stage of this task targets that stage's branch. The release base MUST contain the task's implementation anchor base. `pr-plan` derives stacking inside this task only; when the task was built on another task's unmerged stage branch, the release base is that predecessor task's stage branch, which prepare names as the recommended base. The chosen base MUST NOT be one of this task's stage branches. If it is, re-ask.
   2p. **PR plan** (only when the user picked `push + PR`) — run
       `okstra handoff pr-plan --plan-run-root <...> --approved-plan <...> --project-root <project root> --project-id <id> --task-group <g> --task-id <t> --work-category <c> --stages <HANDOFF_STAGES> --base <chosen-base>`.
-      It returns one row per stage with `head_branch`, `head_commit`, `base_kind` (`release-base` | `stage` | `merge-base`), `base_branch` and `base_commit`. Exit 2 means the predecessors of a multi-dependency stage conflict with each other: show the `conflicts` paths and stop (route: resolve manually, then retry). Exit 1 means an eligibility or dependency violation — most often a stage whose predecessor is neither in this run nor already PR'd nor merged into the release base: show the error verbatim and re-ask the action selection. On success these rows are authoritative for every subsequent step; the lead does not recompute a base by hand.
+      It returns one row per stage with `head_branch`, `head_commit`, `base_kind` (`release-base` | `stage` | `merge-base`), `base_branch` and `base_commit`. Exit 2 means the predecessors of a multi-dependency stage conflict with each other: show the `conflicts` paths and stop (route: resolve manually, then retry). Exit 1 means an eligibility or dependency violation — most often a stage whose predecessor is neither in this run nor already PR'd nor merged into the release base: show the error verbatim and re-ask the action selection. When the error says the release base does not contain the implementation anchor, the error names the `--base` that does: show it verbatim and re-ask Q2 with that branch first. **Enforced:** `okstra_ctl.phases.release_handoff.operations._resolve_stage_base` refuses the plan. On success these rows are authoritative for every subsequent step; the lead does not recompute a base by hand.
       A `merge-base` row means `pr-plan` created a branch merging that stage's predecessors. That branch is a PR base only — it is never a PR head — and it MUST be pushed before the PR that targets it.
       The output also carries `push_plan` and `warnings`. `push_plan` is every branch the PRs sit on, already in push order (each `merge-base` first, then the stage heads in dependency order), with the `commit` it must reach and an `action` of `create` (origin does not have it), `fast-forward` (origin is behind) or `up-to-date` (origin already has that commit — do not push it). GitHub resolves a PR's head and base by name on origin, so this list, not the local branch set, is what makes the stack real. A `warnings` row means `pr-plan` fast-forwarded a local branch to origin because origin was ahead: the commits origin adds are outside what this run verified. Quote every `warnings` row verbatim in Executed Commands and say so in the branch/PR explanation — the user is deciding whether to release commits this run did not verify. `pr-plan` refuses outright when a branch moved outside okstra or diverged from origin, since only a force push could deliver it.
   2b. **Pre-merge conflict probe** (only when the user picked `push + PR`) — before pushing, for each planned stage in dependency order:

package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md

@@ -48,7 +48,9 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Candidate Release Base Branches
 
-The user picks ONE release base for the whole run. Each stage's own PR base is then derived from its `depends-on` by `okstra handoff pr-plan`: a stage with no live dependency targets the release base, a stage with one targets that stage's branch (a stacked PR), and a stage with several targets a branch merging them.
+The user picks ONE release base for the whole run. Each stage's own PR base is then derived from its `depends-on` by `okstra handoff pr-plan`: a stage with no live dependency targets the release base, a stage with one targets that stage's branch (a stacked PR), and a stage with several targets a branch merging them. That derivation covers stacking inside this task only. The release base must contain the task's implementation anchor base; when this task was built on another task's unmerged stage branch, the release base is that branch, and `pr-plan` refuses a base that lacks the anchor.
+
+{{HANDOFF_ANCHOR_BASE_CANDIDATES}}
 
 - Default options offered to the user: `staging` | `preprod` | `prod` | `main` | `dev` | custom input
 - Repo-specific preference, if known (e.g. `main` is the integration branch):

package/runtime/python/okstra_ctl/phases/release_handoff/spec.md

@@ -141,7 +141,7 @@ stateDiagram-v2
 User interaction is exactly three steps.
 
 1. Q1 action: `local checkout`, `push + PR`, `skip`
-2. Q2 release base: a branch from the profile menu such as `staging`, `preprod`, `main`, or Enter directly
+2. Q2 release base: a branch from the profile menu such as `staging`, `preprod`, `main`, or Enter directly. When no default candidate contains the task's implementation anchor base (the task was built on another task's unmerged stage branch), prepare names the origin branch at the anchor as the recommended first option, and `pr-plan` refuses a release base that lacks the anchor
 3. Q3 PR title/body: every stage's draft in one question — `use as-is`, `edit then proceed`, `cancel`
 
 The merge-conflict probe happens only for `push + PR`, once per stage against that stage's own base.

package/runtime/python/okstra_ctl/report_projections.py

@@ -325,6 +325,7 @@ def project_convergence(
             "proposed": critic.get("gapsProposed", 0),
             "merged": critic.get("gapsMerged", 0),
             "unverified": critic.get("gapsUnverified", 0),
+            "duplicate": critic.get("gapsDuplicate", 0),
         }
     return result
 

package/runtime/python/okstra_ctl/run.py

@@ -3063,6 +3063,7 @@ def _write_instruction_set_sources(
             )
             if inp.clarification_response_path else ""
         ),
+        verification_target_path=ctx.get("VERIFICATION_TARGET_RELATIVE_PATH", ""),
     )
     if inp.task_type == "technical-verification":
         packet += materialize_technical_input_packet(

package/runtime/python/okstra_ctl/worktree/decisions.py

@@ -11,7 +11,12 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from .. import worktree_registry
-from .git_ops import _is_inside_non_main_worktree, is_git_work_tree
+from .git_ops import (
+    _branch_checkout_path,
+    _branch_exists,
+    _is_inside_non_main_worktree,
+    is_git_work_tree,
+)
 from .naming import _safe_segment, compute_branch_name, compute_worktree_path
 
 
@@ -24,11 +29,19 @@ class WorktreeDecision:
       - "reused": registry already has this task-key; existing path/branch returned
       - "skipped-in-worktree": project_root is itself a non-main worktree
       - "skipped-not-git": project_root has no .git
+
+    recovery (only when the active registry row no longer matches git):
+      - "restore-from-branch": status "reused"; the recorded branch survives but
+        is not checked out at the recorded path, so provision re-adds it there
+      - "replace-stale-row": status "new"; the recorded branch is gone, so
+        provision releases the row and creates a fresh worktree from the
+        requested base, or the recorded base when none is requested
     """
     status: str
     path: str              # worktree path (new: prospective; reuse: existing; skip: project_root)
     branch: str = ""       # new: prospective branch; reused: existing branch
     base_ref: str = ""     # new: requested base_ref; reused: existing base
+    recovery: str = ""
 
 
 def preview_worktree_decision(
@@ -54,11 +67,21 @@ def preview_worktree_decision(
     safe_group = _safe_segment(task_group_segment)
     safe_task = _safe_segment(task_id_segment)
     existing = worktree_registry.lookup(safe_project, safe_group, safe_task)
+    recovery = ""
     if existing is not None and existing.status == "active":
-        return WorktreeDecision(
-            status="reused", path=existing.worktree_path,
-            branch=existing.branch, base_ref=existing.base_ref,
-        )
+        if _is_checked_out_at(project_root, existing.branch, existing.worktree_path):
+            return WorktreeDecision(
+                status="reused", path=existing.worktree_path,
+                branch=existing.branch, base_ref=existing.base_ref,
+            )
+        if _branch_exists(project_root, existing.branch):
+            return WorktreeDecision(
+                status="reused", path=existing.worktree_path,
+                branch=existing.branch, base_ref=existing.base_ref,
+                recovery="restore-from-branch",
+            )
+        recovery = "replace-stale-row"
+        base_ref = base_ref or existing.base_ref
     return WorktreeDecision(
         status="new",
         path=str(compute_worktree_path(
@@ -66,9 +89,23 @@ def preview_worktree_decision(
             task_id_segment=safe_task)),
         branch=compute_branch_name(work_category=work_category, task_id_segment=safe_task),
         base_ref=base_ref,
+        recovery=recovery,
     )
 
 
+def _is_checked_out_at(project_root: Path, branch: str, worktree_path: str) -> bool:
+    """Whether git itself has `branch` checked out at `worktree_path`.
+
+    An `active` registry row only records what okstra reserved; the directory
+    can be removed by hand and the branch deleted after a merge without the
+    registry hearing about it.
+    """
+    checkout = _branch_checkout_path(project_root, branch)
+    if not checkout or not Path(worktree_path).is_dir():
+        return False
+    return Path(checkout).resolve() == Path(worktree_path).resolve()
+
+
 @dataclass
 class StageWorktreeDecision:
     """Side-effect-free decision for one concrete implementation stage."""

package/runtime/python/okstra_ctl/worktree/provision.py

@@ -141,6 +141,10 @@ def provision_task_worktree(
     safe_task = _safe_segment(task_id_segment)
 
     if decision.status == "reused":
+        restored = ""
+        if decision.recovery == "restore-from-branch":
+            _restore_task_worktree(project_root, Path(decision.path), decision.branch)
+            restored = "; restored from its branch (directory was not a worktree)"
         worktree_registry.touch_phase(safe_project, safe_group, safe_task, task_type)
         _seed_worktree_settings_symlink(Path(decision.path))
         drift = _sync_key_drift_note(
@@ -155,7 +159,7 @@ def provision_task_worktree(
             note=(
                 f"task worktree reused at {decision.path} on branch "
                 f"{decision.branch} (base {decision.base_ref[:12]}); phase {task_type}"
-                f"{drift}"
+                f"{restored}{drift}"
             ),
         )
 
@@ -163,6 +167,8 @@ def provision_task_worktree(
     worktree_path = Path(decision.path)
     branch = decision.branch
 
+    if decision.recovery == "replace-stale-row":
+        _remove_settings_seed_shell(worktree_path)
     if worktree_path.exists():
         raise RuntimeError(
             f"task worktree path already exists but is not in the registry: "
@@ -173,7 +179,7 @@ def provision_task_worktree(
         raise RuntimeError(_branch_exists_message(project_root, branch, "task"))
 
     main_root = main_worktree_path(project_root)
-    requested_base = (base_ref or "").strip()
+    requested_base = (decision.base_ref or "").strip()
     if not requested_base and require_base_ref:
         raise RuntimeError(
             "first-phase task worktree requires an explicit base ref; "
@@ -221,8 +227,15 @@ def provision_task_worktree(
         linked_parts.append(f"linked-files {', '.join(linked_files)}")
     if snapshot_files:
         linked_parts.append(f"snapshot {', '.join(snapshot_files)}")
+    if decision.recovery == "replace-stale-row":
+        linked_parts.append(
+            "replaced a stale registry row whose recorded branch no longer exists")
     linked_suffix = ("; " + "; ".join(linked_parts)) if linked_parts else ""
 
+    if decision.recovery == "replace-stale-row":
+        # The recorded branch is already deleted, so freeing its slot keeps the
+        # registry's "a free branch name is physically deleted" invariant.
+        worktree_registry.release(safe_project, safe_group, safe_task)
     try:
         worktree_registry.reserve(
             project_id=safe_project,
@@ -260,6 +273,40 @@ def provision_task_worktree(
     )
 
 
+def _remove_settings_seed_shell(path: Path) -> None:
+    """Remove a directory that holds nothing but okstra's settings seed.
+
+    Earlier prepares re-seeded `.claude/settings.local.json` into the recorded
+    path of a stale registry row, which left exactly this shell behind and made
+    every later prepare refuse the path. Anything else in the directory is
+    left alone.
+    """
+    seed = path / ".claude" / "settings.local.json"
+    if not path.is_dir() or not (seed.is_symlink() or seed.is_file()):
+        return
+    if [p.name for p in path.iterdir()] != [".claude"]:
+        return
+    if [p.name for p in (path / ".claude").iterdir()] != ["settings.local.json"]:
+        return
+    seed.unlink()
+    (path / ".claude").rmdir()
+    path.rmdir()
+
+
+def _restore_task_worktree(project_root: Path, path: Path, branch: str) -> None:
+    _remove_settings_seed_shell(path)
+    if path.exists():
+        raise RuntimeError(
+            f"task worktree path {path} exists but is not a worktree of branch "
+            f"{branch}; move it aside so okstra can re-add the worktree from "
+            "that branch."
+        )
+    # A directory deleted by hand stays registered in git until pruned, and
+    # `git worktree add` refuses a missing-but-registered path.
+    _git(main_worktree_path(project_root), "worktree", "prune")
+    restore_stage_worktree(project_root, str(path), branch)
+
+
 def restore_stage_worktree(project_root: Path, path: str, branch: str) -> None:
     target = Path(path)
     if target.exists():

package/runtime/schemas/final-report-v2.0.schema.json

@@ -481,11 +481,12 @@
         },
         "criticGaps": {
           "type": "object",
-          "description": "Coverage-critic gap accounting. `proposed - merged - unverified` is the count the voters judged and rejected, so a gap that vanished shows up as a mismatch instead of as nothing. Every `unverified` gap needs a matching `missingInformation` row with source `critic-unverified` (prompts/lead/convergence.md \"Gap verification\").",
+          "description": "Coverage-critic gap accounting. `proposed - merged - unverified - duplicate` is the count the voters judged and rejected, so a gap that vanished shows up as a mismatch instead of as nothing. `duplicate` counts gaps the critic declared duplicates of an existing finding; they are never verified. Every `unverified` gap needs a matching `missingInformation` row with source `critic-unverified` (prompts/lead/convergence.md \"Gap verification\").",
           "required": [
             "proposed",
             "merged",
-            "unverified"
+            "unverified",
+            "duplicate"
           ],
           "additionalProperties": false,
           "properties": {
@@ -500,6 +501,10 @@
             "unverified": {
               "type": "integer",
               "minimum": 0
+            },
+            "duplicate": {
+              "type": "integer",
+              "minimum": 0
             }
           }
         },

package/runtime/schemas/final-report-v3.0.schema.json

@@ -518,11 +518,12 @@
         },
         "criticGaps": {
           "type": "object",
-          "description": "Coverage-critic gap accounting. `proposed - merged - unverified` is the count the voters judged and rejected, so a gap that vanished shows up as a mismatch instead of as nothing. Every `unverified` gap needs a matching `missingInformation` row with source `critic-unverified` (prompts/lead/convergence.md \"Gap verification\").",
+          "description": "Coverage-critic gap accounting. `proposed - merged - unverified - duplicate` is the count the voters judged and rejected, so a gap that vanished shows up as a mismatch instead of as nothing. `duplicate` counts gaps the critic declared duplicates of an existing finding; they are never verified. Every `unverified` gap needs a matching `missingInformation` row with source `critic-unverified` (prompts/lead/convergence.md \"Gap verification\").",
           "required": [
             "proposed",
             "merged",
-            "unverified"
+            "unverified",
+            "duplicate"
           ],
           "additionalProperties": false,
           "properties": {
@@ -537,6 +538,10 @@
             "unverified": {
               "type": "integer",
               "minimum": 0
+            },
+            "duplicate": {
+              "type": "integer",
+              "minimum": 0
             }
           }
         },

package/runtime/validators/validate-run.py

@@ -4233,12 +4233,13 @@ def _validate_unverified_critic_gaps_recorded(data: dict, failures: list[str]) -
 
     proposed = critic.get("proposed")
     merged = critic.get("merged")
-    if isinstance(proposed, int) and isinstance(merged, int):
-        if merged + unverified > proposed:
+    duplicate = critic.get("duplicate")
+    if isinstance(proposed, int) and isinstance(merged, int) and isinstance(duplicate, int):
+        if merged + unverified + duplicate > proposed:
             failures.append(
                 "final-report data.json: crossVerification.criticGaps has "
-                f"merged({merged}) + unverified({unverified}) > proposed({proposed}) "
-                "— the accounting does not describe a real set of gaps."
+                f"merged({merged}) + unverified({unverified}) + duplicate({duplicate}) "
+                f"> proposed({proposed}) — the accounting does not describe a real set of gaps."
             )