okstra 0.223.0 → 0.224.0

package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py

@@ -54,6 +54,14 @@ from okstra_ctl.plan_items import (
     with_response_format,
 )
 from okstra_ctl.paths import RunRef
+from okstra_ctl.plan_item_evidence import (
+    capture_review_inputs,
+    dependency_scopes,
+    reusable_item_ids,
+    review_fingerprint,
+    review_files_unchanged,
+)
+from okstra_ctl.plan_review_context import render_review_context
 from okstra_ctl.stage_ledger import build_stage_ledger
 from okstra_ctl.claim_reproduction import NOT_RUNNABLE, reproduce
 from okstra_ctl.final_report_schema import load_schema_version
@@ -118,13 +126,39 @@ def _queue_for(
     run_manifest: Path | None,
     previous_hashes: Mapping[str, str] | None = None,
     tied_ids: Sequence[str] | None = None,
+    previous_rows: Sequence[Mapping[str, Any]] = (),
+    review_inputs: Mapping[str, Any] | None = None,
 ) -> list[str]:
     ledger = _merged_ledger(planning, run_manifest)
     if tied_ids is not None:
         return tie_vote_item_ids(items, ledger, tied_ids)
+    inputs = review_inputs or _review_inputs(items, planning, run_manifest, previous_rows)
+    reusable = reusable_item_ids(previous_rows, inputs)
+    candidates = set(dispatch_item_ids(items, ledger))
     if previous_hashes:
-        return reverify_item_ids(items, previous_hashes, ledger)
-    return dispatch_item_ids(items, ledger)
+        candidates.update(reverify_item_ids(items, previous_hashes, ledger))
+    return [item["id"] for item in items if item["id"] in candidates - reusable]
+
+
+def _review_inputs(
+    items: list[dict[str, Any]], planning: Mapping[str, Any],
+    run_manifest: Path | None, rows: Sequence[Mapping[str, Any]],
+) -> dict[str, Any]:
+    if run_manifest is None:
+        return {}
+    authority = validated_run_authority(run_manifest)
+    return capture_review_inputs(items, planning, authority.payload, authority.project_root, rows)
+
+
+def _checked_review_inputs(run_manifest: Path | None) -> dict[str, Any]:
+    root = _probe_project_root(run_manifest)
+    if root is None:
+        return {}
+    path = _prepared_items_path(run_manifest)
+    inputs = _load_json_object(path).get("reviewInputs", {}) if path.is_file() else {}
+    if not review_files_unchanged(inputs, root):
+        raise PlanItemContractError("review evidence changed during dispatch; prepare and verify again")
+    return inputs
 
 
 def _queue_kwargs(args: argparse.Namespace) -> dict[str, Any]:
@@ -133,7 +167,9 @@ def _queue_kwargs(args: argparse.Namespace) -> dict[str, Any]:
         if state is None:
             raise PlanItemContractError("--tie-vote requires --state")
         return {"tied_ids": _tied_ids(state)}
-    return {"previous_hashes": _previous_hashes(getattr(args, "state", None))}
+    state = getattr(args, "state", None)
+    rows = _state_plan_body_items(_load_json_object(state), state) if state and state.is_file() else []
+    return {"previous_hashes": _previous_hashes(state), "previous_rows": rows}
 
 
 def _tied_ids(state_path: Path) -> list[str]:
@@ -170,8 +206,8 @@ def _parser() -> argparse.ArgumentParser:
     prepare.add_argument(
         "--state",
         type=Path,
-        help="previous plan-body state; when it carries verifiedContentHash "
-        "rows the dispatch queue shrinks to the self-fix reverify set, and "
+        help="previous plan-body state; only matching body and complete "
+        "evidence fingerprints shrink the self-fix reverify queue, and "
         "each queued item's recorded votes and selfFixNote are carried "
         "into the prompt as its `**Prior round dissent**` block",
     )
@@ -251,8 +287,8 @@ def _parser() -> argparse.ArgumentParser:
         "--prior-state",
         type=Path,
         help="the previous run's plan-body-verification-<task-type>-<seq>.json. "
-        "A newly seeded item whose contentHash still equals that run's "
-        "verifiedContentHash inherits its verdicts and is tagged "
+        "A newly seeded item with matching body and complete evidence "
+        "fingerprints inherits its verdicts and is tagged "
         "carriedForwardFromSeq, so round 1 does not re-judge text nobody "
         "changed. Requires --state, refuses a state file belonging to "
         "another task, and never carries on a matching id alone",
@@ -474,12 +510,21 @@ def _prepare(args: argparse.Namespace) -> dict[str, Any]:
                 + "; correct the narrative in this run, then retry plan-items prepare"
             )
     envelope = _envelope(source)
+    kwargs = _queue_kwargs(args)
+    envelope["reviewInputs"] = _review_inputs(
+        envelope["items"], _planning(source), args.run_manifest,
+        kwargs.get("previous_rows", []),
+    )
     envelope["dispatchQueue"] = _queue_for(
         envelope["items"],
         _planning(source),
         args.run_manifest,
-        **_queue_kwargs(args),
+        **kwargs,
+        review_inputs=envelope["reviewInputs"],
     )
+    envelope["reusedItems"] = sorted(reusable_item_ids(
+        kwargs.get("previous_rows", []), envelope["reviewInputs"],
+    ))
     if getattr(args, "tie_vote", False):
         envelope["dispatchKind"] = "critic-tie"
         envelope["tieSplits"] = _tie_splits_from_state(
@@ -998,6 +1043,7 @@ def _render_inputs(run_manifest: Path) -> str:
 
 
 def _prompt(args: argparse.Namespace) -> str:
+    inputs = _checked_review_inputs(args.run_manifest)
     envelope = _load_json_object(
         _prepared_items_path(args.run_manifest, require_regular=True)
     )
@@ -1021,6 +1067,11 @@ def _prompt(args: argparse.Namespace) -> str:
         line("Item count", len(items)),
         _render_inputs(args.run_manifest),
     ]
+    authority = validated_run_authority(args.run_manifest)
+    rows.append(render_review_context(
+        [item["id"] for item in items], inputs, authority.payload, authority.project_root,
+    ))
+    _checked_review_inputs(args.run_manifest)
     for index, item in enumerate(items, 1):
         if not isinstance(item, Mapping):
             continue
@@ -1075,6 +1126,12 @@ def _validate_prepared(args: argparse.Namespace) -> dict[str, Any]:
     )
     if actual.get("dispatchQueue") != expected_queue:
         raise PlanItemContractError("prepared dispatch queue does not match")
+    current_inputs = _review_inputs(
+        expected["items"], _planning(source), args.run_manifest,
+        _queue_kwargs(args).get("previous_rows", []),
+    )
+    if actual.get("reviewInputs") != current_inputs:
+        raise PlanItemContractError("prepared review evidence changed; prepare again")
     if not getattr(args, "tie_vote", False):
         # 라운드 2+ 의 반대 의견 반입은 여기서만 검사된다. 봉투에서 빠지면
         # 프롬프트에도 빠지고, 반대한 워커는 자기 판정을 그대로 다시 적는다.
@@ -1134,6 +1191,7 @@ def _verdict_row(worker: str, block: VerdictBlock) -> dict[str, Any]:
         ("fixability", block.fixability),
         ("note", block.note),
         ("explanation", block.explanation),
+        ("dependencies", block.dependencies),
     ):
         if value:
             row[key] = value
@@ -1367,24 +1425,6 @@ def _carry_prior_run_verdicts(
     added: list[dict[str, Any]],
     hashes: Mapping[str, str],
 ) -> _PriorRunCarry | None:
-    """직전 run 이 같은 본문에 내린 판정을 새로 시드된 행에 옮긴다.
-
-    실패한 계획 run 을 다시 돌면 판정이 하나도 넘어오지 않았다. 이월은 답변된
-    clarification 이 있는 경로에만 있고(`incremental_scope.decide_scope` 는
-    답변된 `C-NNN` 이 없으면 `full` 을 되돌려 `incremental_carry` 를 도달 불가로
-    만든다), 그래서 아무도 고치지 않은 문장이 매 재실행마다 다시 채점됐다.
-
-    행 모양은 `incremental_carry._stamp_carried` 와 같다 — `verdicts` 를 그대로
-    옮기고, `carriedForwardFromSeq` 에 직전 seq 를 찍고, `verifiedContentHash` 를
-    이번 추출 해시로 맞춘다. 그 해시가 시드의 `dispatchQueue` 계산에 그대로
-    들어가므로(`_queue_for` → `reverify_item_ids`), 이월된 행은 라운드 1 큐에서
-    빠진다. 큐를 따로 줄이지 않는 이유가 이것이다: incremental 경로가
-    `incremental_carry._recompute_dispatch_queue` 에서 쓰는 것과 같은 장치다.
-
-    id 만 같은 행은 절대 이월하지 않는다. `P-*` id 는 위치에서 나오므로 계획이
-    한 줄만 밀려도 같은 번호가 다른 문장을 가리킨다. 해시가 같아야 그 문장이
-    같은 문장이다.
-    """
     prior = getattr(args, "prior_state", None)
     if prior is None:
         return None
@@ -1420,9 +1460,17 @@ def _carry_prior_run_verdicts(
         current_hash = hashes.get(item_id)
         if not current_hash or previous.get("verifiedContentHash") != current_hash:
             continue
+        manifest = getattr(args, "run_manifest", None)
+        inputs = (
+            _load_json_object(_prepared_items_path(manifest)).get("reviewInputs", {})
+            if manifest is not None else {}
+        )
+        if item_id not in reusable_item_ids([previous], inputs):
+            continue
         row["verdicts"] = copy.deepcopy(verdicts)
         row["carriedForwardFromSeq"] = prev_seq
         row["verifiedContentHash"] = current_hash
+        row["verifiedReviewHash"] = previous["verifiedReviewHash"]
         count += 1
     return _PriorRunCarry(prev_seq, count)
 
@@ -1526,6 +1574,7 @@ def _seed(args: argparse.Namespace) -> dict[str, Any]:
         _planning(source),
         getattr(args, "run_manifest", None),
         previous,
+        previous_rows=recorded,
     )
     verification["gating"] = (
         verification.get("gating") is True
@@ -1609,8 +1658,21 @@ def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
             f"gate is re-derived from that table, so a verdict with nowhere to "
             f"land would be scored as if it were never cast"
         )
+    review_inputs = _checked_review_inputs(getattr(args, "run_manifest", None))
     if args.round_number < 1:
         raise PlanItemContractError("--round must be 1 or greater")
+    _write_round_verdicts(args, data, recorded, rows, review_inputs)
+    if requires_plan_repair(verification):
+        verification["gating"] = True
+    _validate_advisory_round(verification, args.round_number)
+    write_json_atomic(target, data)
+    return {"ok": True, "operation": "apply-verdicts", "path": str(target)}
+
+
+def _write_round_verdicts(
+    args: argparse.Namespace, data: Mapping[str, Any], recorded: list[dict[str, Any]],
+    rows: Mapping[str, list[dict[str, Any]]], review_inputs: Mapping[str, Any],
+) -> None:
     project_root = _probe_project_root(getattr(args, "run_manifest", None))
     append = bool(getattr(args, "append", False))
     replaces_critic = append and any(
@@ -1627,18 +1689,20 @@ def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
             rows,
             data.get("roundHistory"),
             args.round_number,
-            target,
-            discard_open_rounds=discard_open_rounds,
+            args.state or args.data,
+            discard_open_rounds=bool(getattr(args, "discard_open_rounds", False)),
         )
     writer = _append_item_verdicts if append else _replace_item_verdicts
     for item in recorded:
         if isinstance(item, Mapping) and item.get("id") in rows:
             writer(item, rows[item["id"]], args.round_number, project_root)
-    if requires_plan_repair(verification):
-        verification["gating"] = True
-    _validate_advisory_round(verification, args.round_number)
-    write_json_atomic(target, data)
-    return {"ok": True, "operation": "apply-verdicts", "path": str(target)}
+    review_inputs = {**review_inputs, "dependencies": dependency_scopes(recorded)}
+    for item in recorded:
+        if isinstance(item, Mapping) and item.get("id") in rows:
+            item.pop("verifiedReviewHash", None)
+            fingerprint = review_fingerprint(item, review_inputs)
+            if fingerprint is not None:
+                item["verifiedReviewHash"] = fingerprint
 
 
 def _stamped_verdicts(
@@ -2110,6 +2174,7 @@ def _reject_unbacked_self_fix_stop(
 
 
 def _complete_round(args: argparse.Namespace) -> dict[str, Any]:
+    _checked_review_inputs(args.run_manifest)
     if args.round_number < 1:
         raise PlanItemContractError("--round must be 1 or greater")
     data, current, audit, history = _round_inputs(args)

package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md

@@ -413,11 +413,11 @@ round before any host or provider process starts.
 
 For contract 3.0, `prepare` checks the selected-direction draft with the same semantic validator as publication before writing the queue. Correct all reported references, coverage rows and planned commands through the writer correction procedure, then retry in this run. **Enforced:** `report_assembly.validate_plan_draft` and `plan_items_cli._prepare`; `tests/report/test_report_assembly.py` checks that invalid coverage creates no prepared queue.
 
-1. Lead runs `okstra plan-items prepare --narrative <report-writer-narrative.md> --run-manifest <run-manifest>`, places the fixed output of `okstra plan-items prompt --run-manifest <run-manifest>` verbatim in every verifier prompt, then runs `okstra plan-items validate-prepared --narrative <report-writer-narrative.md> --run-manifest <run-manifest>`. After a self-fix rewrite, pass `--state <plan-body-verification.json>` on prepare and validate-prepared so the dispatch queue is the changed items plus their stage closure, not the full extract, and so each re-dispatched item carries the previous round's dissent (§"Re-verification rounds (round 2+)"). Python resolves the one convergence-owned state path from that run identity. Dispatch only after that exact-match validation succeeds. The prompt is the dispatch queue: `observed` / `deferred` stages are omitted; plan-wide items (`P-Dir-1`, `P-Var-*`, `P-Dep-*`, `P-Opt-*`) stay. Unscoped `P-Val-*` / `P-Req-*` / `P-Rb-*` stay on the first round, then only when their own `contentHash` changed — a neighbour rewrite must not resweep them. **Enforced:** `okstra_ctl.plan_items.dispatch_item_ids` / `reverify_item_ids`. After `okstra incremental-carry`, the carry copies unchanged checklist verdicts, rewrites `dispatchQueue`, and updates the sibling `plan-items-*.json` so the next `okstra plan-items prompt` does not re-score a carried row.
+1. Lead runs `okstra plan-items prepare --narrative <report-writer-narrative.md> --run-manifest <run-manifest>`, places the fixed output of `okstra plan-items prompt --run-manifest <run-manifest>` verbatim in every verifier prompt, then runs `okstra plan-items validate-prepared --narrative <report-writer-narrative.md> --run-manifest <run-manifest>`. After a self-fix rewrite, pass `--state <plan-body-verification.json>` on prepare and validate-prepared. The runtime reuses a verdict only when its body, complete declared evidence closure, shared analysis packet, plan metadata, reviewer assignments and review contract have the same fingerprint. A missing or uncertain dependency declaration, unresolved reference, non-result or executable fact probe stays in the re-verification queue. Detailed verdicts and their original rounds remain unchanged for reused items. File dependencies cover whole files; step items also include preceding steps; plan-wide and preparation items include all plan items. Python resolves the one convergence-owned state path from that run identity. Dispatch only after exact-match validation succeeds. `observed` / `deferred` stages remain omitted. An empty queue opens no worker dispatch and creates no verification round. **Enforced:** `implementation_planning.authoring._queue_for`, `plan_item_evidence.review_fingerprint`, `_validate_prepared` and `tests/run/test_plan_items.py`. An incremental carry without evidence snapshots keeps active items queued until prepare can validate their dependencies.
 
    **Then seed the landing table (BLOCKING):** `okstra plan-items seed --narrative <report-writer-narrative.md> --state <plan-body-verification.json> --run-manifest <run-manifest.json>`. `apply-verdicts` in step 8 refuses a verdict whose item has no `planBodyVerification.planItems[]` row. The report writer never owns that state, so the deterministic seed is the only creator of its rows. The seed is idempotent by id and never touches existing verdicts, so it is safe to re-run between rounds and after a self-fix re-extraction. It does refresh `contentHash` from the current extract. Skipping it makes step 8 fail with `plan-body state has no row for [...]`.
 
-   **On a re-run, add `--prior-state <the previous run's plan-body-verification-<task-type>-<seq>.json>`.** A newly seeded item whose `contentHash` equals that run's `verifiedContentHash` for the same id inherits its verdicts, is tagged `carriedForwardFromSeq`, and drops out of round 1's `dispatchQueue` — in the state and in the sibling `plan-items-*.json` the next `okstra plan-items prompt` reads. Without it a re-run re-judges every line the previous run already settled, and the same dissent re-opens under a new `P-*` number. A matching id alone never carries: `P-*` ids are positional, so a plan that gained one line hands the old id to a different sentence. The flag requires `--state` and refuses a prior state file that sits under another task's root — a plan-body state carries no task identity of its own, so its path is the only identity there is. **Enforced:** `okstra_ctl.plan_items_cli._carry_prior_run_verdicts`.
+   **On a re-run, add `--prior-state <the previous run's plan-body-verification-<task-type>-<seq>.json>`.** A newly seeded item inherits verdicts only when its body and verified evidence fingerprint match the prepared snapshot for the same task. Reused rows carry `carriedForwardFromSeq`; their full verdicts are preserved. Legacy body-only records re-enter verification. A matching id alone never carries: `P-*` ids are positional. The flag requires `--state` and refuses another task's state. **Enforced:** `implementation_planning.authoring._carry_prior_run_verdicts` and `plan_item_evidence.reusable_item_ids`.
 
    **`--run-manifest` is what scopes the gate to the stage you are starting.** Seed uses it to overlay disk `done` / `active` onto `planBodyVerification.stageLedger`. The current plan's depends-on fills `ready` / `blocked` when no prior plan exists, so a first run does not treat every stage as in-scope. **Enforced:** `okstra_ctl.plan_items.planning_stage_ledger`.
 2. For each analyser worker in the roster, use `okstra plan-items prompt` output verbatim as the instruction body in the materialization sequence above. Read §"Re-verification rounds (round 2+)" before preparing a later round; read §"Plan-body reverify prompt" only when diagnosing a prompt-contract failure.
@@ -693,6 +693,23 @@ and a `- Plan narrative:` line from its `reportNarrativePath`. The worker's
 are what let a verifier read the requirement a selected-direction `P-Req-*` row
 names by `originalRequirementId`. The lead does not add them by hand.
 
+When a complete input snapshot is available, the renderer also provides inline
+review context. Read that context and the assigned payloads first. It preserves
+the packet except its navigation index and generated analysis Coverage Census,
+and carries plan metadata plus supporting items as lossless JSON. Supporting
+items are narrowed only when the previous dependency closure is complete and
+every body in that closure is unchanged; otherwise all other plan items are
+included. A changed body, missing declaration, unresolved reference or uncertain
+cross-item claim requires the full context or the original Inputs paths.
+Read those paths when the supplied context does not resolve a question, and
+record the additional dependencies. Omission never proves absence.
+Packets containing finding-like headings are quoted as source data, preserving
+their text without adding foreign items to the plan-verification queue.
+
+Enforcement: `render_review_context` in `okstra_ctl.plan_review_context` selects
+the context; `test_plan_review_context_preserves_facts_and_falls_back_for_unknown_dependencies`
+in `tests/run/test_plan_items.py` checks retained facts and conservative fallback.
+
 Carrying the packet does not license re-analysis. It is there so the verifier
 can resolve a plan item back to the requirement it claims to satisfy; the
 posture in §"Adversarial plan-body posture" still applies, and this round does
@@ -847,6 +864,9 @@ never recorded, and the round is scored on the items that remain.
 **Probe** (only when Claim is fact): <one line of JSON, e.g. {"kind": "path-absent", "path": "src/missing.ts"}>
 **Note**: <the falsification candidate considered and why it is excluded; required even for AGREE>
 **Explanation**: <2-3 sentences>
+**Dependencies**: {"complete": false, "itemIds": [], "paths": []}
+
+Keep the detailed Note and Explanation. Declare all direct and transitive plan-item and whole-file evidence dependencies. Set `complete` to true only when that boundary is known. Include source files behind references. External or dynamic evidence, unlisted narrative dependencies and unresolved references keep `complete` false. This declaration controls reuse eligibility, not the verdict itself. Missing and malformed declarations are treated as unknown by `verdict_blocks._block` and `plan_item_evidence.review_fingerprint`.
 
 ### P-Opt-2
 ...

package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py

@@ -68,6 +68,7 @@ from okstra_ctl.design_surfaces import DesignSurfaceError  # noqa: E402
 
 from okstra_ctl.plan_items import (  # noqa: E402
     content_hash,
+    PlanItemContractError,
     expected_plan_item_ids,
     extract_plan_items,
 )
@@ -2543,6 +2544,7 @@ def validate_plan_body_section(
     _validate_round_recorded_verdicts(data, failures)
     _validate_verdicts_match_current_subjects(data, failures)
     _validate_verdict_rounds_outlive_self_fix(data, failures)
+    _validate_review_evidence(data, report_path, failures)
     _validate_unresolved_tie_was_reverified(data, failures)
     _validate_advisory_plan_body_gating(data, failures)
     _validate_plan_item_extraction_completeness(data, failures)
@@ -2553,6 +2555,37 @@ def validate_plan_body_section(
     return [*_detect_self_fix_recurrence(pbv), *_detect_uniform_verifier(pbv)]
 
 
+def _validate_review_evidence(data: dict, report_path: Path, failures: list[str]) -> None:
+    from okstra_ctl.convergence import validated_run_authority, ConvergenceContractError
+    from okstra_ctl.plan_item_evidence import capture_review_inputs, review_fingerprint
+
+    planning = data.get("implementationPlanning") or {}
+    pbv = planning.get("planBodyVerification") or {}
+    rows = pbv.get("planItems") or []
+    if not any(row.get("verifiedReviewHash") for row in rows):
+        return
+    sequences = _manifest_seq_for_report(report_path, "manifests")
+    if len(sequences) != 1:
+        failures.append("plan review evidence has no unambiguous run manifest")
+        return
+    path = report_path.parent.parent / "manifests" / (
+        f"run-manifest-implementation-planning-{next(iter(sequences))}.json"
+    )
+    try:
+        authority = validated_run_authority(path)
+        inputs = capture_review_inputs(
+            extract_plan_items(planning), planning, authority.payload, authority.project_root, rows,
+        )
+    except (ConvergenceContractError, PlanItemContractError) as exc:
+        failures.append(f"cannot validate plan review evidence: {exc}")
+        return
+    stale = [row["id"] for row in rows if _item_stage_scope_bucket(row, pbv) == "in-scope"
+             and row.get("verifiedReviewHash")
+             and row["verifiedReviewHash"] != review_fingerprint(row, inputs)]
+    if stale:
+        failures.append(f"plan review evidence changed for {stale}; prepare and re-verify those items")
+
+
 def _gate_summary_item(
     item: dict,
     pbv: dict,

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

@@ -29,7 +29,7 @@ Report shapes remain in `schemas/final-report-v2.0.schema.json` and `schemas/fin
 
 `release-handoff` is the terminal phase that pushes already-committed implementation stages with a release-ready verdict, or hands them off as pull requests. **One stage is one PR.** The PR head is that stage's stack branch; the base comes from its `depends-on` — the release base for a stage with no live dependency, the predecessor's branch for a stage with one (a stacked PR), and a branch merging the predecessors for a stage with several.
 
-When a predecessor advances, `okstra_ctl.stage_rebase.synchronize_stage_stack` rebases downstream stages in dependency order rather than merging the predecessor into them. It records the new bases and completion commits, preserving prior heads under `refs/okstra/rebase-backups/`. Implementation entry and verification target acquisition use the same operation. PR planning stops after a stack change and requires fresh final-verification; the new completion rows invalidate earlier verification through `consumers.verified_accepted_stages`. Dirty or active stages, rewritten unproven predecessors, and rebase conflicts stop synchronization. The tests in `tests/worktree/test_stage_rebase.py` cover ordering, preservation, and verification invalidation. Origin divergence remains a delivery error, never a reason to merge old origin history into the rebased branch.
+When a predecessor advances, `okstra_ctl.stage_rebase.synchronize_stage_stack` rebases downstream stages in dependency order rather than merging the predecessor into them. It records the new bases and completion commits, preserving prior heads under `refs/okstra/rebase-backups/`. Implementation entry and verification target acquisition use the same operation. PR planning stops after a stack change and requires fresh final-verification; the new completion rows invalidate earlier verification through `consumers.verified_accepted_stages`. Dirty or active stages, rewritten unproven predecessors, and rebase conflicts stop synchronization. A completed stage whose predecessor was reopened, and so has no done row, is left unchanged; the first synchronization after that predecessor is done again rebases it. The tests in `tests/worktree/test_stage_rebase.py` cover ordering, preservation, and verification invalidation. Origin divergence remains a delivery error, never a reason to merge old origin history into the rebased branch.
 
 Because the PRs are a stack, they must be merged in dependency order with a merge commit or a rebase-merge. A squash replaces the commits the next PR's base points at, so the stack breaks — every PR body states this, and the lead never merges.
 

package/runtime/python/okstra_ctl/plan_item_evidence.py

@@ -0,0 +1,237 @@
+"""Conservative evidence snapshots for plan-verification verdict reuse."""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import stat
+from collections.abc import Mapping, Sequence
+from copy import deepcopy
+from pathlib import Path
+from typing import Any, TypedDict
+
+from .plan_items import content_hash, is_critic_worker
+from .paths import find_asset_root
+from .report_narrative import writer_owned_data
+
+
+class FileSnapshot(TypedDict):
+    path: str
+    hash: str
+    mode: int | None
+
+
+class ReviewInputs(TypedDict):
+    version: int
+    items: dict[str, dict[str, Any]]
+    files: dict[str, FileSnapshot | None]
+    dependencies: dict[str, list[dict[str, Any]]]
+    workers: list[str]
+    context: str
+    complete: bool
+    planContext: dict[str, Any]
+    priorReviewHashes: dict[str, str]
+
+
+def _digest(value: object) -> str:
+    return hashlib.sha256(
+        json.dumps(value, sort_keys=True, ensure_ascii=False).encode("utf-8")
+    ).hexdigest()
+
+
+def _file_snapshot(root: Path, name: str) -> FileSnapshot | None:
+    path = root / name
+    try:
+        resolved = path.resolve(strict=False)
+        if not resolved.is_relative_to(root.resolve()):
+            return None
+        before = path.stat()
+        if stat.S_ISREG(before.st_mode):
+            digest = hashlib.sha256(path.read_bytes()).hexdigest()
+            after = path.stat()
+            changed = any(getattr(before, field) != getattr(after, field) for field in (
+                "st_dev", "st_ino", "st_size", "st_mtime_ns", "st_ctime_ns", "st_mode",
+            ))
+            if changed or resolved != path.resolve(strict=False):
+                return None
+            return {"path": str(resolved), "hash": digest, "mode": stat.S_IMODE(before.st_mode)}
+    except FileNotFoundError:
+        if not path.is_symlink():
+            return {"path": str(path.resolve(strict=False)), "hash": "absent", "mode": None}
+    except (OSError, RuntimeError):
+        return None
+    return None
+
+
+def _payload_paths(value: object) -> set[str]:
+    if isinstance(value, str):
+        return {value} if value and not any(c in value for c in "\n`*") else set()
+    if isinstance(value, list):
+        return set().union(*(_payload_paths(entry) for entry in value))
+    if isinstance(value, Mapping):
+        return _payload_paths(value.get("path"))
+    return set()
+
+
+def capture_review_inputs(
+    items: Sequence[Mapping[str, Any]],
+    planning: Mapping[str, Any],
+    manifest: Mapping[str, Any],
+    root: Path,
+    previous_rows: Sequence[Mapping[str, Any]] = (),
+) -> ReviewInputs:
+    paths: set[str] = set()
+    for item in items:
+        payload = item.get("payload") or {}
+        paths.update(
+            match for match in re.findall(r"`([^`\s]+)`", json.dumps(payload))
+            if "/" in match or "." in match
+        )
+        for field in ("files", "plannedPaths"):
+            paths.update(_payload_paths(payload.get(field)))
+    for row in previous_rows:
+        for vote in row.get("verdicts", []):
+            dependencies = vote.get("dependencies")
+            if isinstance(dependencies, Mapping) and isinstance(dependencies.get("paths"), list):
+                paths.update(p for p in dependencies.get("paths", []) if isinstance(p, str))
+    packet = manifest.get("analysisPacketPath")
+    if isinstance(packet, str) and packet:
+        paths.add(packet)
+    metadata = writer_owned_data({"implementationPlanning": planning})["implementationPlanning"]
+    for field in ("planBodyVerification", "optionCandidates", "stepwiseExecution",
+                  "dependencyMigrationRisk", "validationChecklist", "rollbackStrategy",
+                  "requirementCoverage", "variationPointAnalysis"):
+        metadata.pop(field, None)
+    metadata["stages"] = [
+        {key: value for key, value in stage.items() if key != "stepwiseExecution"}
+        for stage in metadata.get("stages", [])
+    ]
+    contracts = find_asset_root(("agents", "common.json"))
+    contract_hashes = {
+        name: _file_snapshot(contracts, name) if contracts else None for name in (
+            "agents/common.json", "agents/roles/analyser.json",
+            "prompts/duties/reverification-worker.json",
+        )
+    }
+    package = Path(__file__).resolve().parent
+    contract_hashes.update({name: _file_snapshot(package, name) for name in (
+        "plan_items.py", "plan_item_evidence.py", "plan_review_context.py", "phases/implementation_planning/authoring.py",
+        "phases/implementation_planning/instructions/plan-body-verification.md",
+    )})
+    files = {name: _file_snapshot(root, name) for name in sorted(paths)}
+    return {
+        "version": 1,
+        "planContext": metadata,
+        "priorReviewHashes": {str(row["id"]): str(row.get("verifiedReviewHash", "")) for row in previous_rows},
+        "items": {str(item["id"]): dict(item) for item in items},
+        "files": files,
+        "dependencies": dependency_scopes(previous_rows),
+        "workers": [row["workerId"] for row in manifest.get("workerAssignments", [])
+                    if row.get("workerId") and not is_critic_worker(row["workerId"])
+                    and not row["workerId"].startswith("report-writer")],
+        "context": _digest([metadata, contract_hashes, manifest.get("workerAssignments"),
+                            manifest.get("agentContract"), manifest.get("invocationAssignments"),
+                            files.get(packet)]),
+        "complete": bool(packet and files.get(packet) and files[packet]["hash"] != "absent"
+                         and all(value and value["hash"] != "absent" for value in contract_hashes.values())),
+    }
+
+
+def dependency_scopes(rows: Sequence[Mapping[str, Any]]) -> dict[str, list[dict[str, Any]]]:
+    return {
+        str(row["id"]): deepcopy(row["verdicts"]) for row in rows
+        if isinstance(row.get("id"), str) and isinstance(row.get("verdicts"), list)
+        and row["verdicts"]
+    }
+
+
+def _vote_dependencies(votes: object, workers: Sequence[str]) -> tuple[set[str], set[str]] | None:
+    if (not isinstance(votes, list) or not votes or not workers
+            or any(not isinstance(vote, Mapping) for vote in votes)
+            or set(workers) - {vote.get("worker") for vote in votes}):
+        return None
+    item_ids, paths = set(), set()
+    for vote in votes:
+        dependencies = vote.get("dependencies")
+        if (vote.get("verdict") not in {"AGREE", "DISAGREE", "SUPPLEMENT"}
+                or vote.get("claimKind") == "fact"
+                or not isinstance(dependencies, Mapping)
+                or dependencies.get("complete") is not True):
+            return None
+        for field in ("itemIds", "paths"):
+            values = dependencies.get(field)
+            if not isinstance(values, list) or any(not isinstance(v, str) or not v for v in values):
+                return None
+        item_ids.update(dependencies["itemIds"])
+        paths.update(dependencies["paths"])
+    return item_ids, paths
+
+
+def _dependency_closure(row: Mapping[str, Any], inputs: Mapping[str, Any]) -> tuple[set[str], set[str]] | None:
+    items = inputs.get("items", {})
+    graph = {**inputs.get("dependencies", {}), str(row["id"]): row.get("verdicts")}
+    pending, item_ids, paths = [str(row["id"])], set(), set()
+    while pending:
+        key = pending.pop()
+        if key in item_ids:
+            continue
+        if key not in items:
+            return None
+        declared = _vote_dependencies(graph.get(key), inputs.get("workers", []))
+        if declared is None:
+            return None
+        if any(not inputs.get("files", {}).get(name)
+               or inputs["files"][name]["hash"] == "absent" for name in declared[1]):
+            return None
+        item_ids.add(key)
+        pending.extend(declared[0])
+        paths.update(declared[1])
+        payload = items[key].get("payload") or {}
+        if key.startswith(("P-Opt-", "P-Var-", "P-Dir-", "P-Dep-", "P-Prep-")):
+            pending.extend(items)
+            paths.update(inputs.get("files", {}))
+        elif key.startswith("P-Step-"):
+            pending.extend(
+                other_id for other_id, other in items.items()
+                if other_id.startswith("P-Step-") and other["payload"].get("stage") == payload.get("stage")
+                and other["payload"].get("step", 0) < payload.get("step", 0)
+            )
+        for field in ("files", "plannedPaths"):
+            paths.update(_payload_paths(payload.get(field)))
+    return item_ids, paths
+
+
+def review_fingerprint(row: Mapping[str, Any], inputs: Mapping[str, Any]) -> str | None:
+    items, files = inputs.get("items", {}), inputs.get("files", {})
+    item = items.get(row.get("id"))
+    if not inputs.get("complete") or not item or row.get("contentHash") != content_hash(item):
+        return None
+    closure = _dependency_closure(row, inputs)
+    if closure is None:
+        return None
+    item_ids, paths = closure
+    if any(name not in files or files[name] is None for name in paths):
+        return None
+    return _digest({
+        "context": inputs["context"],
+        "items": {key: content_hash(items[key]) for key in sorted(item_ids)},
+        "files": {name: files[name] for name in sorted(paths)},
+        "votes": row["verdicts"],
+    })
+
+
+def review_files_unchanged(inputs: Mapping[str, Any], root: Path) -> bool:
+    return all(
+        value == _file_snapshot(root, name)
+        for name, value in inputs.get("files", {}).items()
+    )
+
+
+def reusable_item_ids(
+    rows: Sequence[Mapping[str, Any]], inputs: Mapping[str, Any],
+) -> set[str]:
+    return {
+        str(row["id"]) for row in rows
+        if row.get("verifiedReviewHash")
+        and row["verifiedReviewHash"] == review_fingerprint(row, inputs)
+    }