okstra 0.221.0 → 0.223.0

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

@@ -480,13 +480,50 @@
             }
           ]
         },
+        "correctionRounds": {
+          "type": "array",
+          "maxItems": 2,
+          "description": "Each implementation correction round's re-convergence of the verifiers' re-verification, projected from `convergence-correction-r<N>-<task-type>-<seq>.json`. Row ids continue the initial round's numbering so every row keeps its own anchor.",
+          "items": {
+            "type": "object",
+            "required": [
+              "round",
+              "consensus",
+              "differences"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "round": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 2
+              },
+              "roundHistory": {
+                "$ref": "#/properties/crossVerification/properties/roundHistory"
+              },
+              "consensus": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/$defs/ConsensusRow"
+                }
+              },
+              "differences": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/$defs/DifferenceRow"
+                }
+              }
+            }
+          }
+        },
         "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": {
@@ -501,6 +538,10 @@
             "unverified": {
               "type": "integer",
               "minimum": 0
+            },
+            "duplicate": {
+              "type": "integer",
+              "minimum": 0
             }
           }
         },

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

@@ -439,6 +439,7 @@ If `render-bundle` fails with a `PrepareError` containing `Recorded stage SHAs n
    - **Enter a different ref directly** — the user names a commit/branch/tag.
    - **Abort** — stop the run without recovering.
 3. Run `okstra git-reconcile … --apply --stage <N> --use-ref <ref>` with the chosen ref, then retry the failed `render-bundle` with the same arguments.
+   If that output carries a `Warning` naming the implementation anchor, the chosen head no longer contains the anchor: show the warning to the user and run its printed `--reset-anchor` command only after they confirm the new base, before the retry.
 
 If the anchor (`implementation_base_commit`) is reported unresolvable, run the same command's `--reset-anchor <ref>` after user confirmation. Correcting a confirm item without the picker is forbidden — the runtime also rejects a confirm correction without `--use-ref`.
 

package/runtime/templates/reports/html/base.template.html

@@ -70,7 +70,7 @@
     </section>
     {% endif %}
     {% set no_cross_model_check = taskType != "release-handoff" and (crossVerification.get("roundHistory") or {}).get("round2SkippedReason") == "single-analyser-only" %}
-    {% if crossVerification.get("consensus") or crossVerification.get("differences") or no_cross_model_check %}
+    {% if crossVerification.get("consensus") or crossVerification.get("differences") or crossVerification.get("correctionRounds") or no_cross_model_check %}
     <section data-report-section="cross-check">
       <h2>{{ t('base.cross-check') }}</h2>
       {% if no_cross_model_check %}<p class="section-lede">{{ t('base.no-cross-model-check') }}</p>{% endif %}
@@ -82,6 +82,11 @@
       <h3>{{ t('base.workers-disagreed') }}</h3>
       <div class="summary-grid">{% for row in crossVerification.differences %}<article class="summary-card tone-important" id="id-xv-{{ row.id }}"><p class="eyebrow">{{ row.id | inline_code }}</p><h3>{{ row.disagreement | inline_code }}</h3><p>{% for pos in row.get("workersPosition", []) %}{{ pos.worker | inline_code }} · {{ pos.position | inline_code }}{% if not loop.last %} · {% endif %}{% endfor %}</p><p class="evidence-refs">{{ t('macros.layout.evidence') }} {{ row.evidence | inline_code }}</p></article>{% endfor %}</div>
       {% endif %}
+      {% for correction in crossVerification.get("correctionRounds", []) %}
+      <h3>{{ t('base.cross-check-correction-round') | replace('{round}', correction.round | string) }}</h3>
+      {% if correction.consensus %}<div class="summary-grid">{% for row in correction.consensus %}<article class="summary-card" id="id-xv-{{ row.id }}"><p class="eyebrow">{{ row.id | inline_code }} · {{ t('base.agreed-across-workers') }}</p><h3>{{ row.statement | inline_code }}</h3><p class="evidence-refs">{{ t('macros.layout.evidence') }} {{ row.evidence | inline_code }}</p></article>{% endfor %}</div>{% endif %}
+      {% if correction.differences %}<div class="summary-grid">{% for row in correction.differences %}<article class="summary-card tone-important" id="id-xv-{{ row.id }}"><p class="eyebrow">{{ row.id | inline_code }} · {{ t('base.workers-disagreed') }}</p><h3>{{ row.disagreement | inline_code }}</h3><p>{% for pos in row.get("workersPosition", []) %}{{ pos.worker | inline_code }} · {{ pos.position | inline_code }}{% if not loop.last %} · {% endif %}{% endfor %}</p><p class="evidence-refs">{{ t('macros.layout.evidence') }} {{ row.evidence | inline_code }}</p></article>{% endfor %}</div>{% endif %}
+      {% endfor %}
     </section>
     {% endif %}
     {% if agentActivity %}

package/runtime/templates/reports/html/i18n/en.json

@@ -242,6 +242,7 @@
     "no-cross-model-check": "No cross-model check ran: fewer than two analysis workers were selected, so no other model verified these findings.",
     "agreed-across-workers": "Agreed across workers",
     "workers-disagreed": "Workers disagreed",
+    "cross-check-correction-round": "Re-converged after correction round {round}",
     "source": "Source",
     "confidence": "Confidence",
     "export-my-answers": "Export my answers",

package/runtime/templates/reports/html/i18n/ko.json

@@ -242,6 +242,7 @@
     "no-cross-model-check": "교차 모델 검증을 하지 않았습니다. 분석 작업자를 두 명 미만으로 골라 다른 모델이 이 결과를 검증하지 않았습니다.",
     "agreed-across-workers": "작업자 간 합의",
     "workers-disagreed": "작업자 간 이견",
+    "cross-check-correction-round": "수정 라운드 {round} 뒤 재수렴",
     "source": "출처",
     "confidence": "확신도",
     "export-my-answers": "내 답변 내보내기",

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."
             )
 
 
@@ -4854,8 +4855,10 @@ def _validate_convergence_group_provenance(run_dir, failures, suffix=None) -> No
 # provider token (`claude` vs `claude-worker`), depending on how the roster was
 # seeded — worker resolution below accepts both. `-reverify-r` never occurs
 # inside a slug, so the non-greedy slug capture stops at that literal anchor.
+# A correction round's re-convergence puts `correction-r<N>-` before
+# `reverify-r`, and its plans carry the same token before `<task-type>`.
 _REVERIFY_PROMPT_BASENAME_RE = re.compile(
-    r"^(?P<slug>[a-z][a-z0-9-]*?)-reverify-r(?P<round>\d+)"
+    r"^(?P<slug>[a-z][a-z0-9-]*?)(?:-(?P<scope>correction-r\d+))?-reverify-r(?P<round>\d+)"
     r"-(?P<task_type>[a-z][a-z-]*?)-(?P<seq>\d{3})\.md$"
 )
 
@@ -5318,8 +5321,9 @@ def _validate_reverify_prompt_matches_plan(run_dir, failures, suffix=None) -> No
         if match is None:
             continue
         round_n = match.group("round")
+        scope = f"{match.group('scope')}-" if match.group("scope") else ""
         plan_path = state_dir / (
-            f"convergence-round-{round_n}-plan-"
+            f"convergence-round-{round_n}-plan-{scope}"
             f"{match.group('task_type')}-{match.group('seq')}.json"
         )
         if not plan_path.is_file():

package/runtime/validators/validate_session_conformance.py

@@ -298,6 +298,18 @@ def _analysis_workers(team_state: Mapping[str, Any]) -> list[dict]:
     return [worker for worker in workers if not _is_report_writer(worker)]
 
 
+def _critic_worker_ids(team_state: Mapping[str, Any]) -> set[str]:
+    """`critic/*` 배정이 로스터에 남기는 행의 workerId (`render._critic_role_rows`)."""
+    assignments = team_state.get("invocationAssignments")
+    if not isinstance(assignments, Mapping):
+        return set()
+    return {
+        str(ref).rsplit("/", 1)[-1]
+        for ref in assignments
+        if str(ref).startswith("critic/")
+    }
+
+
 def _scan_one_jsonl(
     path: Path, since: str | None, until: str | None
 ) -> tuple[list[tuple[str, str, str]], dict[str, list[str]], str | None]:
@@ -1686,7 +1698,13 @@ def _check_progress_checkpoints(
         "`using implicit team` line, or the "
         "`skipped (concurrent-run)` variant in the concurrent-run path",
     )
-    _check_worker_checkpoint_lines(by_phase, analysis_workers, narration)
+    # critic 은 `critic` dispatch 로만 뜨고 `phase-5.6-critic` 으로 알린다.
+    critic_ids = _critic_worker_ids(team_state)
+    _check_worker_checkpoint_lines(
+        by_phase,
+        [w for w in analysis_workers if str(w.get("workerId", "")) not in critic_ids],
+        narration,
+    )
     convergence_ran = _convergence_rounds_ran(run_dir, suffix)
     require(
         "phase-5.5-convergence",