workflow-toolkit 1.0.1

package/.agents/skills/wtk-deep-review/references/state-and-learnings.md

@@ -0,0 +1,64 @@
+# State and Learnings
+
+The tracker that makes rounds incremental and the feedback loop that stops repeated mistakes.
+
+## Fingerprint — a result's identity
+
+```
+fp = first 16 hex of sha256("<result-kind>|<file>|<category>|<normalized title>")
+```
+
+`normalized title` = lowercase, alphanumerics and single spaces only. Line numbers are deliberately excluded — anchors drift between pushes; identity must survive that. The single implementation is `fingerprint()` in `scripts/_common.py` (applied by merge_findings.py); compute one by hand only when recovering fingerprints from a PR thread:
+
+```bash
+printf '%s' "defect|internal/store/queue.go|potential-issue|dont hard fail preferredmodel when config options are unrelated" \
+  | shasum -a 256 | cut -c1-16
+```
+
+## state.json (per target, in `<out>/`)
+
+```json
+{
+  "target": "pr:312",
+  "rounds": [{ "n": 2, "base": "<sha>", "head": "<sha>", "verdict": "FIX_BEFORE_SHIP", "reviewed_at": "<ISO-8601>" }],
+  "ledger": {
+    "<fp>": { "file": "...", "title": "...", "severity": "major", "result_kind": "defect", "status": "open",
+              "round": 1, "comment_id": 123456, "resolved_in": null }
+  }
+}
+```
+
+`status`: `open` → `resolved` only when an incremental review records an evidence-bearing `prior_findings` disposition; absence from new output never resolves it | `dismissed` (user rejected — capture a learning; never re-raised). `comment_id` only when published.
+
+## Round reconciliation (Step 4)
+
+Implemented by merge_findings.py (round status) and render_review.py (ledger update); this is the rule they follow. For each defect/advisory this round, compute `fp` and look it up:
+
+- **absent** (or previously `resolved`) → `new`; add to ledger as `open`.
+- **present, `open`** → `duplicate`; render once in the Duplicates section, keep ledger row.
+- **present, `dismissed`** → keep suppressed from the active results and expose it in the dismissed/suppression audit trail.
+
+Then sweep the ledger's `open` rows *not* re-found this round: a row whose `prior_findings` disposition says `resolved` becomes `resolved` (`resolved_in` = head; publish mode adds the ✅ edit); every other row, including an explicit `open` disposition or no disposition, stays `open`, is listed under Duplicates, and counts in the verdict.
+
+## learnings.md (at `.wtk-deep-review/learnings.md`, repo-committable)
+
+Append-only entries, one per correction:
+
+```markdown
+## <fp-or-slug> — <one-line rule>
+- Scope: <glob> (e.g. internal/store/**)
+- Rule: <the distilled instruction a future reviewer must follow, imperative>
+- Why: <the rationale the user gave — the invariant, the design intent>
+- Origin: <pr:312 | session, date>
+```
+
+**Capture triggers:** the user (or a PR reply from the author) rebuts a finding with a reason; the user says a class of findings is unwanted; a dismissal reveals a repo convention the rubric missed. Distill the *rule*, not the anecdote — "ReserveQueuedRun is the authoritative one-open-run enforcer; do not flag missing pre-checks in enqueue paths" beats a story about one PR.
+
+**Application:** learnings are rubric input (context-pack.md §2) for every later round, scoped by their glob. Path instructions outrank learnings on conflict; a learning that contradicts project instructions or a selected skill signals that doctrine needs editing — surface the conflict.
+
+## Storage conventions
+
+- `<out>` holds manifest.json, knowledge.json, rules.json, context-pack.md, plan.json, prompts/, jobs.json, agents/, runs/, walkthrough.md, findings.json, review-stats.json, review.md, review.html, state.json, and round.json.
+- When build_manifest.py starts a new round it archives everything except state.json/round.json/rounds/ into `<out>/rounds/round-<n>/` — the per-round audit trail; only state.json carries memory forward.
+- `.wtk-deep-review/learnings.md` is shared across targets and worth committing — it is team review doctrine.
+- Recommend adding `.wtk-deep-review/` to `.gitignore` with `!.wtk-deep-review/learnings.md` — suggest it once when the directory is first created; the decision belongs to the user.

package/.agents/skills/wtk-deep-review/references/subagent-runtimes.md

@@ -0,0 +1,33 @@
+# Subagent Runtimes (`--subagent`)
+
+How Step 3 review agents (defect cohorts, sweeps) execute. `native` — the default — uses the Workflow/Agent engines in orchestration.md; every other value runs the same materialized prompts cross-LLM through `compozy exec`, driven by the bundled runner. Step 2 context assembly stays orchestrator-side in every mode.
+
+## Runtime map
+
+| Value | Invocation |
+| --- | --- |
+| `claude-opus` | `compozy exec --ide claude --model opus --reasoning-effort max` |
+| `grok` | `compozy exec --ide cursor-agent --model 'grok-4.5[effort=high,fast=true]'` — effort/fast ride inside the model value (no reasoning flag); requesting `grok-4.5` resolves to the same advertised variant |
+| `codex` | `compozy exec --ide codex --model gpt-5.6-luna --reasoning-effort high` |
+
+## Invocation shape (per stage)
+
+The stage scripts already materialized every prompt (schema + output contract embedded — external runtimes have no schema-enforcement layer, so the output-file contract replaces it). Execute a stage's jobs with the bundled runner from the repo root:
+
+```bash
+python3 <skill-dir>/scripts/run_jobs.py --out <out> [--jobs-file <out>/<stage>-jobs.json] \
+  --command "compozy exec <runtime flags from the map> --format json --timeout 30m --prompt-file {prompt}"
+```
+
+The runner executes reviewer jobs with the concurrency bound pinned in the manifest (default `3`, maximum `6`). An adapter may append metrics flags to collect cumulative snapshots. The runner refills completed worker slots, keeps retries inside the owning slot, stops scheduling after a provider block while active attempts finish, and owns output validation, the source-freeze check, and resume (valid outputs are never re-run). Each job's output file is the agent's only product; JSONL/stderr logs are operational evidence — never parse them as review output.
+
+## Failure handling
+
+- **Runner exit 2 (blocked)** — a stream matched a block pattern (default `usageLimitExceeded`); `<out>/run-blocker.json` lists the pending jobs. Re-run the same command when the limit clears; add `--block-on <pattern>` for providers that phrase limits differently.
+- **Runner exit 1 with FAIL jobs** — the agent kept producing missing/invalid output through its attempts. Read `<out>/runs/<label>.attempt-*.err`, then run that one agent on the `native` path (orchestration.md engines) and record the substitution in review.md — the no-skip invariant outranks runtime purity.
+- **`model "X" is not available`** — the error lists the runtime's advertised options. Surface them and stop; never substitute a model silently (L-010).
+- **`did not advertise an ACP model option`**, or `compozy` missing from PATH — stop and name the gap; external review has no alternate transport.
+
+## Cost
+
+Every external invocation spends `compozy exec` credit — a large PR fans out dozens of agents. `native` fits exploratory runs; external runtimes earn their spend on gate rounds (e.g. loop Phase D's `codex` lane).

package/.agents/skills/wtk-deep-review/references/taxonomy.md

@@ -0,0 +1,70 @@
+# Review Taxonomy
+
+The grammar for defects, advisories, evidence, and objective suppressions. Every review uses one assertive posture: report every specific, actionable survivor regardless of size.
+
+## Result classes
+
+| Class | Categories | Verdict impact | Decision rule |
+| --- | --- | --- | --- |
+| **Defect** | `⚠️ Potential issue` | Critical/Major block SHIP | The change can produce a wrong result, crash, leak, vulnerability, broken contract, or failing-capable test gap under a concrete input/state. |
+| **Advisory** | `🛠️ Refactor suggestion`, `🧹 Nitpick` | Never | The code can remain functional, but a bounded change measurably improves maintainability, simplicity, clarity, naming, documentation, idiom, or conformance with a project rule/skill. |
+
+There is no advisory quota. A small advisory is valid when the premise is observed, the benefit is specific, and the fix is bounded. Formatter-owned style and vague preferences are suppressions, not advisories.
+
+## Severity
+
+| Badge | Class | Bar |
+| --- | --- | --- |
+| `🔴 Critical` | defect | Plausible production incident, data loss, or security compromise. |
+| `🟠 Major` | defect | Wrong behavior, user-visible degradation, unsafe rollout, or a bug awaiting a realistic trigger. |
+| `🟡 Minor` | defect or advisory | Narrow real defect, safety erosion, or a meaningful non-local maintainability improvement. |
+| `🔵 Trivial` | advisory | Cheap clarity, naming, documentation, small deduplication, or idiom improvement. |
+
+Severity measures impact if unfixed, not confidence or effort. Choose the lower level when between two levels.
+
+## Effort modifier
+
+`⚡ Quick win` means the fix is local and mechanical (roughly ≤15 lines at one site). A larger advisory remains reportable; effort never suppresses it.
+
+## Source attribution
+
+Every result names what produced it through evidence and optional rule ids: repository rule/skill, learning, linter interpretation, verification command, or direct code review. Quote bound rules verbatim through their registry ids and source paths.
+
+## Evidence certificates
+
+Defects start with a causal certificate:
+
+```text
+Premise: <observed fact at file:line> → Path: <named caller/input/control flow> → Verdict: <resulting failure>
+```
+
+Advisories start with an improvement certificate:
+
+```text
+Premise: <observed fact at file:line> → Improvement: <specific measurable benefit> → Fix: <bounded change>
+```
+
+Later evidence entries record one `command or file:line → what it showed` check each. Advisories do not invent a runtime failure to clear the defect evidence bar.
+
+## Outside-diff results
+
+A result on untouched lines is allowed only when the diff breaks that code or when a sibling path must mirror the changed invariant. Mark it `in_diff: false` and `hunk: null`; it belongs in the summary rather than an inline comment.
+
+## Objective suppressions
+
+When an investigated candidate is rejected, record it in `suppressions` with one of these reasons and a concrete note:
+
+1. `linter-overlap` — a linter/typechecker lane already reports it.
+2. `intentional` — an adjacent justified disable, ADR, comment, or behavior-locking test proves intent.
+3. `generated-vendored` — the manifest excludes ownership of generated/vendor code.
+4. `formatting` — a configured formatter owns the proposed change.
+5. `speculative` — a defect claim has no concrete failure path and no valid advisory premise.
+6. `pre-existing` — untouched debt satisfies neither outside-diff clause.
+7. `phantom-knowledge` — the claim depends on uninspected code or an irrelevant framework generality.
+8. `duplicate-within-job` — the candidate is represented by another result and its anchor appears under `also_applies`.
+
+Profile, volume, low severity, and personal taste are not suppression reasons.
+
+## Volume discipline
+
+There is no numeric cap. Find broadly, refute actively, report every survivor, and account for every investigated rejection. One root cause becomes one result; search every occurrence and list the rest under `also_applies`.

package/.agents/skills/wtk-deep-review/scripts/_common.py

@@ -0,0 +1,371 @@
+"""Shared contracts for the wtk-deep-review pipeline scripts (library, not a CLI).
+
+Single source for: path resolution, JSON I/O, the JSON-Schema-subset validator,
+job-output validation, finding fingerprints, hunk text, and the source-freeze
+snapshot. Every sibling script imports it; invoke them as files
+(python3 <path>/script.py) so Python puts this directory on sys.path.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+
+SKILL_DIR = Path(__file__).resolve().parent.parent
+ASSETS_DIR = SKILL_DIR / "assets"
+SEVERITY_RANK = {"trivial": 0, "minor": 1, "major": 2, "critical": 3}
+KNOWN_KINDS = {"cohort", "sweep"}
+
+
+# ---------- paths / IO ----------
+
+def repo_root() -> Path:
+    proc = subprocess.run(
+        ["git", "rev-parse", "--show-toplevel"], capture_output=True, text=True
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(f"not inside a git repository: {proc.stderr.strip()}")
+    return Path(proc.stdout.strip())
+
+
+def read_json(path: Path):
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        raise RuntimeError(f"missing artifact: {path}") from None
+    except json.JSONDecodeError as error:
+        raise RuntimeError(f"invalid JSON in {path}: {error}") from error
+
+
+def write_json(path: Path, payload) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+    )
+
+
+def rel(path: Path, repo: Path) -> str:
+    """Path as agents/prompts should type it: repo-relative when inside the repo."""
+    resolved = path.resolve()
+    try:
+        return str(resolved.relative_to(repo.resolve()))
+    except ValueError:
+        return str(resolved)
+
+
+def skill_rel(repo: Path) -> str:
+    return rel(SKILL_DIR, repo)
+
+
+def load_schema(name: str) -> dict:
+    return read_json(ASSETS_DIR / f"{name}.schema.json")
+
+
+def glob_to_regex(pat: str) -> re.Pattern:
+    out, i = [], 0
+    while i < len(pat):
+        c = pat[i]
+        if c == "*":
+            if pat[i : i + 3] == "**/":
+                out.append("(?:.*/)?")
+                i += 3
+            elif pat[i : i + 2] == "**":
+                out.append(".*")
+                i += 2
+            else:
+                out.append("[^/]*")
+                i += 1
+        elif c == "?":
+            out.append("[^/]")
+            i += 1
+        else:
+            out.append(re.escape(c))
+            i += 1
+    return re.compile("^" + "".join(out) + "$")
+
+
+# ---------- JSON-Schema subset validator ----------
+
+def schema_errors(value, schema: dict, path: str = "$") -> list[str]:
+    """Validates the subset the bundled schemas use: type (incl. unions),
+    required, properties, items, enum, maxLength, minItems."""
+    types = schema.get("type")
+    if types is not None:
+        allowed = types if isinstance(types, list) else [types]
+        if not any(_matches_type(value, t) for t in allowed):
+            return [f"{path}: expected {allowed}, got {type(value).__name__}"]
+    errors: list[str] = []
+    if "enum" in schema and value not in schema["enum"]:
+        errors.append(f"{path}: {value!r} not in enum")
+    if isinstance(value, dict):
+        for key in schema.get("required", []):
+            if key not in value:
+                errors.append(f"{path}: missing required key {key!r}")
+        for key, sub in (schema.get("properties") or {}).items():
+            if key in value:
+                errors.extend(schema_errors(value[key], sub, f"{path}.{key}"))
+    if isinstance(value, list):
+        if "minItems" in schema and len(value) < schema["minItems"]:
+            errors.append(f"{path}: needs at least {schema['minItems']} items")
+        items = schema.get("items")
+        if items:
+            for index, item in enumerate(value):
+                errors.extend(schema_errors(item, items, f"{path}[{index}]"))
+    if isinstance(value, str) and "maxLength" in schema and len(value) > schema["maxLength"]:
+        errors.append(f"{path}: exceeds maxLength {schema['maxLength']}")
+    return errors
+
+
+def _matches_type(value, name: str) -> bool:
+    if name == "object":
+        return isinstance(value, dict)
+    if name == "array":
+        return isinstance(value, list)
+    if name == "string":
+        return isinstance(value, str)
+    if name == "integer":
+        return isinstance(value, int) and not isinstance(value, bool)
+    if name == "number":
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    if name == "boolean":
+        return isinstance(value, bool)
+    if name == "null":
+        return value is None
+    raise RuntimeError(f"unsupported schema type {name!r}")
+
+
+# ---------- findings identity ----------
+
+def normalize_title(title: str) -> str:
+    return " ".join(re.sub(r"[^a-z0-9]+", " ", title.lower()).split())
+
+
+def fingerprint(finding: dict) -> str:
+    identity = "|".join(
+        [
+            finding.get("result_kind", "defect"),
+            finding["file"],
+            finding["category"],
+            normalize_title(finding["title"]),
+        ]
+    )
+    return hashlib.sha256(identity.encode()).hexdigest()[:16]
+
+
+# ---------- hunks ----------
+
+def hunk_text(hunk: dict) -> str:
+    start, lines = int(hunk["start"]), int(hunk["lines"])
+    return f"{hunk.get('side', 'new')}:{start}-{start + lines - 1}"
+
+
+def manifest_selected(manifest: dict) -> dict[str, dict]:
+    return {f["path"]: f for f in manifest["files"] if f["disposition"] == "selected"}
+
+
+# ---------- job outputs ----------
+
+def load_jobs(path: Path) -> list[dict]:
+    jobs = read_json(path)["jobs"]
+    labels = [job["label"] for job in jobs]
+    if len(labels) != len(set(labels)):
+        raise RuntimeError(f"{path}: duplicate job labels")
+    for job in jobs:
+        if job.get("kind") not in KNOWN_KINDS:
+            raise RuntimeError(f"{path}: {job.get('label')}: unknown kind {job.get('kind')!r}")
+    return jobs
+
+
+def validate_job_output(repo: Path, out: Path, job: dict) -> None:
+    """Raises ValueError when the job's output file is missing or breaks the
+    findings contract. Passing silently means the output is valid."""
+    path = repo / job["output"]
+    if not path.is_file():
+        raise ValueError(f"{job['label']}: missing output {job['output']}")
+    try:
+        payload = read_json(path)
+    except RuntimeError as error:
+        raise ValueError(f"{job['label']}: {error}") from error
+    errors = findings_contract_errors(payload)
+    if not errors:
+        errors.extend(job_contract_errors(payload, job))
+    if errors:
+        head = "; ".join(errors[:6])
+        tail = f" (+{len(errors) - 6} more)" if len(errors) > 6 else ""
+        raise ValueError(f"{job['label']}: {head}{tail}")
+
+
+CERTIFICATE_RE = re.compile(
+    r"^Premise:\s+.+\s+→\s+Path:\s+.+\s+→\s+Verdict:\s+.+$"
+)
+ADVISORY_CERTIFICATE_RE = re.compile(
+    r"^Premise:\s+.+\s+→\s+Improvement:\s+.+\s+→\s+Fix:\s+.+$"
+)
+
+
+def findings_contract_errors(payload: dict) -> list[str]:
+    """Validate the review-output schema plus class-specific certificates."""
+    errors = schema_errors(payload, load_schema("findings"))
+    if errors:
+        return errors
+    for index, finding in enumerate(payload["defects"]):
+        certificate = finding["evidence"][0].strip()
+        if not CERTIFICATE_RE.fullmatch(certificate):
+            errors.append(
+                f"$.defects[{index}].evidence[0]: expected "
+                "'Premise: ... → Path: ... → Verdict: ...' certificate"
+            )
+    for index, advisory in enumerate(payload["advisories"]):
+        certificate = advisory["evidence"][0].strip()
+        if not ADVISORY_CERTIFICATE_RE.fullmatch(certificate):
+            errors.append(
+                f"$.advisories[{index}].evidence[0]: expected "
+                "'Premise: ... → Improvement: ... → Fix: ...' certificate"
+            )
+    return errors
+
+
+def job_contract_errors(payload: dict, job: dict) -> list[str]:
+    """Validate lane ownership, hunk coverage, rule-id sanity, and
+    prior-finding dispositions (exactly one row per job.prior_fingerprints,
+    never a defect re-reported at a prior anchor)."""
+    errors: list[str] = []
+    lane = str(job.get("lane", ""))
+    expected_prior = set(job.get("prior_fingerprints", []))
+    actual_prior = [str(row.get("fingerprint")) for row in payload.get("prior_findings", [])]
+    if len(actual_prior) != len(set(actual_prior)):
+        errors.append("$.prior_findings: duplicate fingerprint rows")
+    if set(actual_prior) != expected_prior:
+        errors.append(
+            "$.prior_findings: disposition mismatch "
+            f"missing={sorted(expected_prior - set(actual_prior))[:6]} "
+            f"extra={sorted(set(actual_prior) - expected_prior)[:6]}"
+        )
+    prior_anchors = {
+        (str(row["file"]), row.get("line")): row["fingerprint"] for row in job.get("prior_anchors", [])
+    }
+    for index, item in enumerate(payload.get("defects", [])):
+        prior = prior_anchors.get((str(item.get("file")), item.get("line")))
+        if prior:
+            errors.append(
+                f"$.defects[{index}]: re-reports prior finding {prior}; disposition it in prior_findings instead"
+            )
+    expected_hunks = {
+        (str(row["file"]), str(row["hunk"])) for row in job.get("required_hunks", [])
+    }
+    rows = payload.get("coverage", {}).get("hunks", [])
+    actual_hunks = [(str(row.get("file")), str(row.get("hunk"))) for row in rows]
+    if len(actual_hunks) != len(set(actual_hunks)):
+        errors.append("$.coverage.hunks: duplicate file/hunk rows")
+    actual_set = set(actual_hunks)
+    if actual_set != expected_hunks:
+        errors.append(
+            "$.coverage.hunks: ownership mismatch "
+            f"missing={sorted(expected_hunks - actual_set)[:6]} "
+            f"extra={sorted(actual_set - expected_hunks)[:6]}"
+        )
+    coverage_check = str(job.get("coverage_check", ""))
+    if coverage_check:
+        for index, row in enumerate(rows):
+            if coverage_check not in row.get("checks", []):
+                errors.append(
+                    f"$.coverage.hunks[{index}].checks: missing required check {coverage_check!r}"
+                )
+
+    expected_rules = set(job.get("rule_ids", []))
+    rule_rows = payload.get("coverage", {}).get("rules", [])
+    actual_rules = [str(row.get("rule_id")) for row in rule_rows]
+    if len(actual_rules) != len(set(actual_rules)):
+        errors.append("$.coverage.rules: duplicate rule_id rows")
+    if set(actual_rules) != expected_rules:
+        errors.append(
+            "$.coverage.rules: assignment mismatch "
+            f"missing={sorted(expected_rules - set(actual_rules))[:6]} "
+            f"extra={sorted(set(actual_rules) - expected_rules)[:6]}"
+        )
+
+    cohort_hunks = {(str(row["file"]), str(row["hunk"])) for row in job.get("cohort_hunks", [])}
+    for result_kind in ("defects", "advisories"):
+        for index, item in enumerate(payload.get(result_kind, [])):
+            if not item.get("in_diff"):
+                continue
+            anchor = (item.get("file"), item.get("hunk"))
+            if lane == "defect" and anchor not in expected_hunks:
+                errors.append(f"$.{result_kind}[{index}]: in-diff anchor is outside job ownership")
+            spread = {ref.rsplit(":", 1)[0] for ref in item.get("also_applies") or []}
+            if lane == "sweep" and anchor in cohort_hunks and len(spread) < 2:
+                errors.append(f"$.{result_kind}[{index}]: single-cohort result belongs to the cohort lane")
+    assigned_rules = expected_rules
+    for result_kind in ("defects", "advisories", "suppressions"):
+        for index, item in enumerate(payload.get(result_kind, [])):
+            unknown = set(item.get("rule_ids") or []) - assigned_rules
+            if unknown:
+                errors.append(
+                    f"$.{result_kind}[{index}].rule_ids: unassigned ids {sorted(unknown)}"
+                )
+    return errors
+
+
+# ---------- source freeze ----------
+
+def freeze_snapshot(repo: Path, out: Path) -> str:
+    """Fingerprint of the reviewed checkout: HEAD + tracked worktree delta +
+    untracked file bytes, excluding review artifacts (.wtk-deep-review/ and <out>)."""
+    excludes = [".wtk-deep-review"]
+    out_rel = rel(out, repo)
+    if not Path(out_rel).is_absolute() and out_rel not in (".wtk-deep-review", "."):
+        excludes.append(out_rel)
+    digest = hashlib.sha256()
+    digest.update(_git_text(repo, "rev-parse", "HEAD").encode())
+    pathspec = [".", *[f":(exclude){item}" for item in dict.fromkeys(excludes)]]
+    digest.update(_git_bytes(repo, "diff", "--binary", "HEAD", "--", *pathspec))
+    untracked = _git_text(repo, "ls-files", "--others", "--exclude-standard").splitlines()
+    for path in sorted(untracked):
+        if any(path == item or path.startswith(item + "/") for item in excludes):
+            continue
+        file_path = repo / path
+        if file_path.is_symlink():
+            digest.update(path.encode())
+            digest.update(b"\0symlink\0")
+            digest.update(os.fsencode(os.readlink(file_path)))
+            continue
+        if not file_path.is_file():
+            continue
+        digest.update(path.encode())
+        digest.update(file_path.read_bytes())
+    return digest.hexdigest()
+
+
+def check_freeze(repo: Path, out: Path, stage: str) -> list[str]:
+    """Compare the checkout against manifest.worktree_snapshot; returns error lines."""
+    manifest = read_json(out / "manifest.json")
+    expected = manifest.get("worktree_snapshot")
+    if not expected:
+        return [f"{stage}: manifest has no worktree_snapshot (rebuild the manifest)"]
+    actual = freeze_snapshot(repo, out)
+    if actual != expected:
+        return [
+            f"{stage}: source drifted — snapshot {actual[:12]} != manifest {expected[:12]}; "
+            "findings would anchor to stale lines. Commit/stash the drift or restart the round."
+        ]
+    return []
+
+
+def _git_text(repo: Path, *args: str) -> str:
+    proc = subprocess.run(["git", *args], cwd=repo, capture_output=True, text=True)
+    if proc.returncode != 0:
+        raise RuntimeError(f"git {' '.join(args)} failed: {proc.stderr.strip()}")
+    return proc.stdout.strip()
+
+
+def _git_bytes(repo: Path, *args: str) -> bytes:
+    proc = subprocess.run(["git", *args], cwd=repo, capture_output=True)
+    if proc.returncode != 0:
+        raise RuntimeError(
+            f"git {' '.join(args)} failed: {proc.stderr.decode(errors='replace').strip()}"
+        )
+    return proc.stdout