okstra 0.169.0 → 0.170.0

package/runtime/python/okstra_ctl/plan_items_cli.py

@@ -14,8 +14,15 @@ import sys
 from typing import Any
 
 from .convergence_store import write_json_atomic
+from .plan_derivations import extract_tokens, find_derivations
 from .plan_items import PlanItemContractError, extract_plan_items
-from .verdict_blocks import VerdictBlock, VerdictBlockError, parse_verdict_blocks
+from .user_response import parse_user_response_entries
+from .verdict_blocks import (
+    PLAN_ITEM_VERDICTS,
+    VerdictBlock,
+    VerdictBlockError,
+    parse_verdict_blocks,
+)
 
 
 def _load_json_object(path: Path) -> dict[str, Any]:
@@ -64,6 +71,20 @@ def _parser() -> argparse.ArgumentParser:
                          help="one worker's plan-verify result file (repeatable)")
     collect.add_argument("--items", type=Path, required=True)
     collect.add_argument("--output", type=Path, required=True)
+    derivations = commands.add_parser(
+        "derivations",
+        help="list plan statements an answered clarification may have falsified",
+    )
+    derivations.add_argument("--data", type=Path, required=True)
+    derivations.add_argument("--response", type=Path, required=True,
+                             help="the user-responses sidecar for this run")
+    derivations.add_argument("--clarification", default=None,
+                             help="only this C-id (default: every answered one)")
+    seed = commands.add_parser(
+        "seed",
+        help="create the planBodyVerification.planItems[] rows a round lands in",
+    )
+    seed.add_argument("--data", type=Path, required=True)
     apply_verdicts = commands.add_parser(
         "apply-verdicts",
         help="overwrite planBodyVerification.planItems[].verdicts in data.json",
@@ -112,8 +133,18 @@ def _assigned_item_ids(items_path: Path) -> list[str]:
 
 def _verdict_row(worker: str, block: VerdictBlock) -> dict[str, Any]:
     """One `planItems[].verdicts[]` row. Optional fields stay absent when empty
-    so the recorded table shows what the worker actually said."""
-    row: dict[str, Any] = {"worker": worker, "verdict": block.verdict}
+    so the recorded table shows what the worker actually said.
+
+    The verdict crosses a vocabulary boundary here: a worker answers
+    `UNVERIFIABLE`, and the schema persists that as `verification-error`
+    (`PLAN_ITEM_VERDICTS`). Writing the worker's token straight through produced
+    a data.json its own schema rejects, and the mapping the contract prescribes
+    had to be applied by hand every round.
+    """
+    row: dict[str, Any] = {
+        "worker": worker,
+        "verdict": PLAN_ITEM_VERDICTS[block.verdict],
+    }
     for key, value in (
         ("breakageKind", block.breakage_kind),
         ("fixability", block.fixability),
@@ -194,6 +225,84 @@ def _plan_body_items(data: dict[str, Any], data_path: Path) -> list[dict[str, An
     return items
 
 
+def _derivations(args: argparse.Namespace) -> dict[str, Any]:
+    """Candidate statements each answered clarification may have falsified.
+
+    Advisory by construction: it reports where a decision's subject is mentioned
+    and never which mentions are now wrong. Both contracts require the author to
+    enumerate before editing; this supplies the enumeration, which is the half
+    that was being skipped, and leaves the judgement where it belongs.
+    """
+    try:
+        sidecar = args.response.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise PlanItemContractError(
+            f"cannot read user-response sidecar {args.response}: {exc}"
+        ) from exc
+    planning = _planning(_load_json_object(args.data))
+    entries = [
+        entry for entry in parse_user_response_entries(sidecar)
+        if args.clarification is None or entry.response_id == args.clarification
+    ]
+    if args.clarification is not None and not entries:
+        raise PlanItemContractError(
+            f"{args.response} has no response block for {args.clarification}"
+        )
+    clarifications = []
+    for entry in entries:
+        tokens = extract_tokens(f"{entry.value}\n{entry.rationale or ''}")
+        clarifications.append({
+            "id": entry.response_id,
+            "disposition": entry.disposition,
+            "tokens": tokens,
+            "candidates": find_derivations(planning, tokens),
+        })
+    return {
+        "ok": True,
+        "operation": "derivations",
+        "advisory": True,
+        "clarifications": clarifications,
+    }
+
+
+def _seed(args: argparse.Namespace) -> dict[str, Any]:
+    """Create the `planBodyVerification.planItems[]` rows a round lands in.
+
+    `apply-verdicts` refuses a verdict whose item has no row — correctly, since
+    the gate is re-derived from that table and a verdict with nowhere to land
+    would score as never cast. But nothing created the rows: the report writer
+    leaves `planItems: []` (§5.5.9 is a lead substep that runs after it), and
+    there was no step, in code or in the contract, that filled them. Every round
+    had to be hand-seeded before the CLI would accept its own output.
+
+    Idempotent by id. An existing row keeps everything it carries — verdicts
+    already applied, `carriedForwardFromSeq`, `selfFixNote` — because a re-seed
+    between rounds must not erase the round before it.
+    """
+    extracted = _envelope(_load_json_object(args.data))["items"]
+    data = _load_json_object(args.data)
+    recorded = _plan_body_items(data, args.data)
+    known = {
+        item.get("id")
+        for item in recorded
+        if isinstance(item, Mapping)
+    }
+    added = [
+        {**item, "verdicts": []}
+        for item in extracted
+        if item["id"] not in known
+    ]
+    recorded.extend(added)
+    write_json_atomic(args.data, data)
+    return {
+        "ok": True,
+        "operation": "seed",
+        "path": str(args.data),
+        "seeded": len(added),
+        "existing": len(known),
+    }
+
+
 def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
     data = _load_json_object(args.data)
     incoming = _load_json_object(args.verdicts).get("planItems")
@@ -226,6 +335,8 @@ _HANDLERS = {
     "extract": _extract,
     "validate": _validate,
     "collect-verdicts": _collect_verdicts,
+    "derivations": _derivations,
+    "seed": _seed,
     "apply-verdicts": _apply_verdicts,
 }
 

package/runtime/python/okstra_ctl/run.py

@@ -68,6 +68,7 @@ from .domain.host import (
     ProviderUnavailable,
 )
 from .model_discovery import normalize_execution_for_dispatch
+from .worker_prompt_policy import ANALYSIS_DUTY_BY_TASK_TYPE
 from .models import (
     ModelAssignment,
     UnknownProviderError,
@@ -2523,7 +2524,12 @@ def _allowed_agent_audiences(
     elif inp.task_type == "final-verification":
         audiences.add("acceptance-verifier")
     else:
-        audiences.add("analysis-worker")
+        # Same map the prompt policy resolves the duty from. Allowing a
+        # different audience here than the one the policy will ask for makes
+        # every worker prompt in the phase fail materialization.
+        audiences.add(
+            ANALYSIS_DUTY_BY_TASK_TYPE.get(inp.task_type, "analysis-worker")
+        )
     if models.critic_choice not in {"", "off"}:
         audiences.update({"scope-critic", "acceptance-critic"})
     return sorted(audiences)

package/runtime/python/okstra_ctl/schema_excerpt.py

@@ -23,6 +23,7 @@ from __future__ import annotations
 
 import json
 import re
+from pathlib import Path
 
 from .report_contract import TASK_TYPE_DATA_PROPERTY
 
@@ -78,6 +79,39 @@ def excerpt_cut_from_version(excerpt: dict) -> str:
     return value if isinstance(value, str) else ""
 
 
+def excerpt_version_skew(excerpt_path: Path, installed: str) -> str:
+    """The version the bundle excerpt was cut from, when it is not *installed*.
+
+    Empty means no actionable skew: the file is absent or unreadable, carries no
+    stamp, or matches. A non-empty return is the older version, which the caller
+    turns into its own message.
+
+    The comparison used to live only in the renderer's error decorator, so it ran
+    in Phase 6 — after a worker had already authored a whole report against a
+    stale excerpt. The same two values are available much earlier, and the fix
+    (re-prepare the bundle) is the same either way.
+    """
+    if not installed:
+        return ""
+    try:
+        excerpt = json.loads(excerpt_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return ""
+    if not isinstance(excerpt, dict):
+        return ""
+    cut_from = excerpt_cut_from_version(excerpt)
+    return cut_from if cut_from and cut_from != installed else ""
+
+
+def bundle_excerpt_path(start: Path) -> Path | None:
+    """The task bundle's schema excerpt, found by walking up from *start*."""
+    for ancestor in Path(start).resolve().parents:
+        candidate = ancestor / "instruction-set" / "final-report-schema.json"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
 def build_schema_excerpt(schema: dict, task_type: str, cut_from_version: str = "") -> dict:
     """Return a task-type-scoped copy of *schema*.
 

package/runtime/python/okstra_ctl/verdict_blocks.py

@@ -38,6 +38,23 @@ ADVERSARIAL_VERDICTS = {
     "UNVERIFIABLE": "unverifiable",
     "VERIFICATION-ERROR": "verification-error",
 }
+# Plan-body verdicts persist in their own vocabulary, which is NOT the
+# convergence one above: the schema keeps the first three tokens uppercase
+# (`$defs/PlanBodyVerification/properties/planItems/items/properties/verdicts/
+# items/properties/verdict`) and has no `UNVERIFIABLE` member at all.
+# `plan-body-verification.md` §"Planning-time environment gap" states the
+# mapping — "Recording `UNVERIFIABLE` is the honest outcome — it is persisted as
+# `verification-error`" — and it lives here rather than inside the transcription
+# CLI so the worker-facing token and the persisted token are decided in one
+# place. Writing the raw token through put a value in data.json that its own
+# schema rejects.
+PLAN_ITEM_VERDICTS = {
+    "AGREE": "AGREE",
+    "DISAGREE": "DISAGREE",
+    "SUPPLEMENT": "SUPPLEMENT",
+    "UNVERIFIABLE": "verification-error",
+    "VERIFICATION-ERROR": "verification-error",
+}
 DISAGREE_BASES = frozenset({"counter-evidence", "burden-not-met"})
 
 _ITEM_RE = re.compile(r"^###[ \t]+(?P<id>[^\s:]+)[ \t]*:?.*$", re.MULTILINE)

package/runtime/python/okstra_ctl/worker_audit_check.py

@@ -12,7 +12,10 @@ import json
 import sys
 from pathlib import Path
 
-from okstra_ctl.worker_audit_ledger import check_worker_results_audit
+from okstra_ctl.worker_audit_ledger import (
+    check_worker_results_audit,
+    worker_result_files,
+)
 
 
 def _parser() -> argparse.ArgumentParser:
@@ -26,7 +29,8 @@ def _parser() -> argparse.ArgumentParser:
     parser.add_argument("--seq", required=True,
                         help="this run's 3-digit seq")
     parser.add_argument("--worker", default=None,
-                        help="check only this worker id (default: every worker)")
+                        help="check only this worker id, with or without the "
+                             "`-worker` suffix (default: every worker)")
     return parser
 
 
@@ -35,8 +39,26 @@ def main(argv: list[str] | None = None) -> int:
     failures = check_worker_results_audit(
         args.run_dir, args.task_type, args.seq, worker=args.worker
     )
-    print(json.dumps({"ok": not failures, "failures": failures},
-                     ensure_ascii=False, indent=2))
+    # A selector that narrows to nothing also produces no failures, so `ok`
+    # alone cannot tell a real pass from a check that judged zero files —
+    # a mistyped `--worker` used to read as a clean bill of health. The count
+    # is what makes the two distinguishable at a glance.
+    inspected = [
+        path.name
+        for path, _role, _seq in worker_result_files(
+            args.run_dir, args.task_type, args.seq, args.worker
+        )
+    ]
+    print(json.dumps(
+        {
+            "ok": not failures,
+            "inspected": len(inspected),
+            "inspectedFiles": inspected,
+            "failures": failures,
+        },
+        ensure_ascii=False,
+        indent=2,
+    ))
     return 2 if failures else 0
 
 

package/runtime/python/okstra_ctl/worker_audit_ledger.py

@@ -11,6 +11,7 @@ so the rules live here rather than inside either one — the same split
 from __future__ import annotations
 
 import re
+from dataclasses import dataclass
 from pathlib import Path
 
 from okstra_ctl.worker_prompt_headers import EVIDENCE_LEDGER_HEADER
@@ -148,26 +149,75 @@ def _ledger_path_hint(cited_path: str, read_paths: set[str]) -> str:
     )
 
 
-def _result_files(run_dir: Path, task_type: str, seq: str | None, worker: str | None):
+@dataclass(frozen=True)
+class WorkerResultName:
+    """The three fields a canonical worker-result basename carries."""
+
+    worker_role: str
+    task_type: str
+    seq: str
+
+
+def parse_worker_result_name(basename: str) -> WorkerResultName | None:
+    """Split `<role>-worker-<task-type>-<seq>.md`, or None when non-canonical.
+
+    Callers that already hold one worker's result path — the dispatcher settling
+    that worker — read the audit check's arguments from here instead of
+    re-deriving them from the manifest. The `worker_role` this returns carries
+    the `-worker` suffix, which is what `check_worker_results_audit(worker=...)`
+    matches on; a bare provider id like `claude` matches nothing.
+    """
+    if "-audit-" in basename:
+        return None
+    match = _WORKER_RESULT_BASENAME_RE.match(basename)
+    if match is None:
+        return None
+    return WorkerResultName(
+        worker_role=match.group("worker"),
+        task_type=match.group("task_type"),
+        seq=match.group("seq"),
+    )
+
+
+def normalize_worker_filter(worker: str | None) -> str | None:
+    """Accept a worker id the way every other okstra surface spells it.
+
+    Result files are named `<role>-worker-...`, so the filter matches
+    `claude-worker`. But `claude` is what a worker is called everywhere a lead
+    reads or types one — `--workers claude,codex`, `workerId`, the roster in the
+    profile — so `--worker claude` was the natural thing to pass, and it matched
+    nothing. A zero-match filter produces no failures, which the CLI reports as
+    `{"ok": true}` with exit 0: indistinguishable from a real pass, at exactly
+    the point `team-contract` tells the lead to run this check before deciding
+    whether to re-dispatch. Accepting both spellings removes the trap rather
+    than documenting it.
+    """
+    if worker is None or worker.endswith("-worker"):
+        return worker
+    return f"{worker}-worker"
+
+
+def worker_result_files(
+    run_dir: Path, task_type: str, seq: str | None, worker: str | None
+):
     """Every worker-results file in *run_dir* this check owns, in name order."""
+    worker = normalize_worker_filter(worker)
     for path in sorted((run_dir / "worker-results").glob("*.md")):
-        if "-audit-" in path.name:
-            continue
-        match = _WORKER_RESULT_BASENAME_RE.match(path.name)
+        match = parse_worker_result_name(path.name)
         if match is None:
             # Files that don't match the canonical pattern (e.g. ad-hoc notes
             # left by the operator) are out of contract scope.
             continue
-        if match.group("task_type") != task_type:
+        if match.task_type != task_type:
             # Cross-phase artifacts shouldn't appear here; skip rather than
             # fail to keep the check focused on the current phase.
             continue
-        if seq is not None and match.group("seq") != seq:
+        if seq is not None and match.seq != seq:
             # A prior run's artifact. Its contract was judged when it ran.
             continue
-        if worker is not None and match.group("worker") != worker:
+        if worker is not None and match.worker_role != worker:
             continue
-        yield path, match.group("worker"), match.group("seq")
+        yield path, match.worker_role, match.seq
 
 
 def check_worker_results_audit(
@@ -196,7 +246,7 @@ def check_worker_results_audit(
         # `release-handoff`, which is single-lead). Nothing to enforce.
         return failures
 
-    for path, worker_role, result_seq in _result_files(run_dir, task_type, seq, worker):
+    for path, worker_role, result_seq in worker_result_files(run_dir, task_type, seq, worker):
         rel = path.name
         try:
             content = path.read_text()

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -230,7 +230,9 @@ def validate_reverify_prompt(
         read_scope_position < 0 or read_scope_position > boundary_position
     ):
         errors.append("phase boundary block must follow the reverify anchor headers")
-    first_heading = re.search(r"(?m)^##\s+", normalized)
+    first_heading = re.compile(r"(?m)^##\s+").search(
+        normalized, _task_instructions_offset(normalized)
+    )
     if (
         boundary_position >= 0
         and first_heading is not None
@@ -240,6 +242,27 @@ def validate_reverify_prompt(
     return errors
 
 
+def _task_instructions_offset(text: str) -> int:
+    """Where the lead's own instruction body starts.
+
+    The `agent-prompt` materializer composes every prompt as anchors →
+    `## Duty Contract` → `## Task Instructions`, and convergence's
+    materialization gate makes that the only body a reverify dispatch may send.
+    The duty section's heading is therefore always the document's first `##`,
+    which left the check below with no satisfiable input: the composer writes a
+    heading above anything the lead can author, so a whole-document "first
+    heading" test failed every materialized prompt regardless of where the lead
+    put the phase boundary.
+
+    These rules judge what the lead wrote, so they start where the lead's text
+    starts — the same region `_validate_model_header` already reads. A prompt
+    without the marker is judged whole.
+    """
+    marker = "\n\n## Task Instructions\n\n"
+    index = text.find(marker)
+    return 0 if index < 0 else index + len(marker)
+
+
 def _section_values(text: str, header: str) -> list[str]:
     lines = text.splitlines()
     values: list[str] = []

package/runtime/python/okstra_ctl/worker_prompt_headers.py

@@ -91,7 +91,7 @@ def worker_prompt_headers(
         project_root,
         audit_source_rel or result_rel,
     )
-    errors_log_path = _errors_log_path(project_root, manifest, active_context)
+    errors_log_path = resolve_errors_log_path(project_root, manifest, active_context)
     errors_sidecar_path = _worker_errors_sidecar_path(
         project_root,
         manifest,
@@ -224,7 +224,7 @@ def _improvement_grilling_log_path(
     return path
 
 
-def _errors_log_path(
+def resolve_errors_log_path(
     project_root: Path,
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any],

package/runtime/python/okstra_ctl/worker_prompt_policy.py

@@ -58,6 +58,17 @@ SUPPORTED_TASK_TYPES = frozenset({
     "release-handoff",
     *ANALYSIS_TASK_TYPES,
 })
+# One duty per analysis ROLE, not per phase. Phases that ask their worker for the
+# same kind of judgement share a contract — requirements- and improvement-discovery
+# both hand over candidates they do not start — and a phase whose worker decides
+# something else gets its own. A task type absent from this map takes the
+# observational default below: describe the area, do not design for it.
+ANALYSIS_DUTY_BY_TASK_TYPE: dict[str, AgentAudience] = {
+    "requirements-discovery": "discovery-worker",
+    "improvement-discovery": "discovery-worker",
+    "error-analysis": "diagnosis-worker",
+    "implementation-planning": "planning-worker",
+}
 WORKER_PREAMBLE_FILENAME_BY_AUDIENCE = {
     "analysis": "worker-prompt-preamble.md",
     "implementation-executor": "implementation-worker-preamble.md",
@@ -113,7 +124,7 @@ def resolve_prompt_plan(
         if dispatch_kind == "critic"
         else "acceptance-verifier"
         if task_type == "final-verification"
-        else "analysis-worker"
+        else ANALYSIS_DUTY_BY_TASK_TYPE.get(task_type, "analysis-worker")
     )
     if task_type == "implementation" and not executor_worker_id:
         raise ValueError("implementation executor worker ID is required")

package/runtime/python/okstra_project/resolver.py

@@ -108,6 +108,40 @@ def resolve_architecture(project_root: Path | str) -> str:
     return style if style in _ARCHITECTURE_STYLES else "none"
 
 
+def resolve_review_rule_packs(project_root: Path | str) -> tuple[str, ...]:
+    """Return the project's declared review rule pack paths, else ``()``.
+
+    A review rule pack is a project's own review standard — the file a phase
+    reads before judging a diff. It used to reach a run only when the task
+    brief cited its exact path, so a team standard applied or not depending on
+    who wrote the brief. Declaring it here makes it apply to every run in the
+    project; the brief citation still works and the two are a union.
+
+    Mirrors resolve_architecture's failure posture: any read/parse problem or a
+    non-list value degrades to "none declared" rather than raising inside a run.
+    An entry that is not an absolute path is dropped, because workers run with
+    a worktree as cwd — a relative path would resolve against a tree that does
+    not contain the pack, and would mean a different file per worker.
+    """
+    try:
+        payload = json.loads(project_json_path(Path(project_root)).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return ()
+    if not isinstance(payload, dict):
+        return ()
+    declared = payload.get("reviewRulePacks")
+    if not isinstance(declared, list):
+        return ()
+    packs = []
+    for entry in declared:
+        if not isinstance(entry, str) or not entry.strip():
+            continue
+        candidate = Path(entry.strip()).expanduser()
+        if candidate.is_absolute():
+            packs.append(str(candidate))
+    return tuple(dict.fromkeys(packs))
+
+
 def upsert_project_json(project_root: Path, project_id: str, *,
                          now: Optional[str] = None) -> dict:
     """project.json 을 읽거나 새로 만든다.

package/runtime/skills/okstra-setup/references/project-config.md

@@ -252,3 +252,41 @@ rules from advisory to a binding planning + verification constraint:
 
 The full two-layer model lives in `docs/architecture.md` § Project
 self-registration.
+
+## G. Project review rule packs (`reviewRulePacks`)
+
+`reviewRulePacks` declares the review standards this project's phases read
+before they judge a plan or a diff — a team PR-review skill's `SKILL.md`, for
+example. Without it a pack reaches a run only when the task brief cites its
+exact path, so whether the team standard applied came down to who wrote the
+brief. A declared pack applies to every run in the project; the brief citation
+keeps working, and the two channels are a union.
+
+`okstra setup` never writes it. Hand-add it to `project.json` and the upsert
+preserves it:
+
+```json
+{
+  "reviewRulePacks": [
+    "/Users/me/.claude/skills/team-pr-reviewer/SKILL.md"
+  ]
+}
+```
+
+- **Absolute paths only.** A worker runs with a task worktree as its cwd, so a
+  relative path names a different file there — relative entries are dropped by
+  `scripts/okstra_project/resolver.py::resolve_review_rule_packs`, which also
+  falls back to "none declared" on an unreadable or malformed `project.json`.
+  A leading `~` is expanded.
+- **Who reads it.** `implementation-planning` (to plan away the findings before
+  the code exists), the implementation executor's coding-conventions preflight,
+  and the static review passes of the implementation verifier and
+  `final-verification`. Each reads only the declared file and the
+  `references/*.md` files it directly names — never a parent directory or a
+  host skill catalog.
+- **What is machine-checked.** `okstra doctor --phase <phase>` fails its
+  `review rule packs` check when a declared path is not a readable file,
+  because a stale path otherwise costs the whole pack in silence: the phase
+  records that it read no rules and the run still passes. Whether a pack that
+  does resolve was actually read and applied stays the phase's own
+  `project-review-rules:` record — no machine check reads a worker's reasoning.

package/runtime/validators/lib/fixtures.sh

@@ -544,6 +544,14 @@ if WORKSPACE_ROOT:
         link_agent_dispatch_result,
         record_verified_agent_dispatch,
     )
+    # The analysis duty depends on the task type, exactly as it does in a real
+    # run — a fixture that assumed one audience for every phase would be
+    # rejected by the manifest's own allowlist.
+    from okstra_ctl.worker_prompt_policy import ANALYSIS_DUTY_BY_TASK_TYPE
+
+    analysis_audience = ANALYSIS_DUTY_BY_TASK_TYPE.get(
+        str(run_manifest.get("taskType") or ""), "analysis-worker"
+    )
 
     lead_record = record_verified_agent_dispatch(
         project_root=project_root,
@@ -580,7 +588,7 @@ if WORKSPACE_ROOT:
             worker_id=worker_id,
             audience=(
                 "report-writer" if worker_id == "report-writer"
-                else "analysis-worker"
+                else analysis_audience
             ),
             assignment_ref=assignment_ref,
             purpose=None,

package/runtime/validators/validate-run.py

@@ -5470,6 +5470,27 @@ def _plan_verify_result_workers(report_path: Path, task_type: str) -> set[str] |
     return workers
 
 
+def _plan_verify_seq_near_misses(report_path: Path, task_type: str) -> list[str]:
+    """Plan-verify results in the directory that this run's seq filter excluded.
+
+    The seq comes from the report filename, and a run whose `reports` and
+    `workerResults` sequences differ makes the other one look equally plausible
+    to a lead naming the file by hand. Naming a near miss is the difference
+    between "the file is missing" and "the file is there under a different seq"
+    — the first sends a lead to re-dispatch two workers that already ran.
+    """
+    seq = _report_run_seq(report_path)
+    if not seq:
+        return []
+    directory = report_path.parent.parent / "worker-results"
+    matched = set(directory.glob(f"*-plan-verify-r*-{task_type}-{seq}.md"))
+    return sorted(
+        path.name
+        for path in directory.glob(f"*-plan-verify-r*-{task_type}-*.md")
+        if path not in matched
+    )
+
+
 def _validate_plan_body_verdict_provenance(
     data: dict,
     report_path: Path,
@@ -5514,14 +5535,28 @@ def _validate_plan_body_verdict_provenance(
             "final-report data.json: planBodyVerification records verdicts from "
             f"{unbacked} but no matching plan-body reverify result file exists "
             f"under `runs/{task_type}/worker-results/` "
-            f"(expected `<worker>-plan-verify-r<N>-{task_type}-<seq>.md`). "
-            "A vote the gate is computed from MUST trace back to a dispatch "
+            f"(globbed `*-plan-verify-r*-{task_type}-"
+            f"{_report_run_seq(report_path) or '*'}.md`, where the seq is the "
+            f"report's own — `final-report-{task_type}-<seq>` — not this run's "
+            f"`workerResults` sequence)"
+            + _near_miss_clause(report_path, task_type)
+            + ". A vote the gate is computed from MUST trace back to a dispatch "
             "that actually returned — otherwise the round can be skipped and "
             'the gate still read `passed` (plan-body-verification.md §"Round '
             'protocol" step 3).'
         )
 
 
+def _near_miss_clause(report_path: Path, task_type: str) -> str:
+    near = _plan_verify_seq_near_misses(report_path, task_type)
+    if not near:
+        return ""
+    return (
+        f"; the directory does hold {near}, which the seq filter excluded — "
+        f"rename to this run's report seq rather than re-dispatching"
+    )
+
+
 _UNIFORM_VERIFIER_MIN_ITEMS = 5