syncade 0.6.2__py3-none-any.whl

syncade/persistence/handoff.py

@@ -0,0 +1,389 @@
+"""Loop-level handoff.md persistence.
+
+Writes ``<run_dir>/handoff.md`` — the structured operator handoff
+artifact when the loop terminates with work remaining. Auto-
+classifies remaining active blockers into a small set of disposition
+categories so the operator reading one file sees what's left, what
+the producer tried, and how to disposition each item.
+
+The classification is HEURISTIC. The rendered handoff says so
+explicitly; the operator's judgment owns the final call.
+
+the heuristic classifier + its phrase tables + category
+labels/descriptions live in :mod:`.handoff_classify`; this module renders
+handoff.md.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from syncade.synthesis import ConsolidatedFinding
+
+from ._atomic import atomic_write_text
+from ._markdown import _file_or_repo_wide
+from .handoff_classify import (
+    _HANDOFF_CATEGORY_DESCRIPTIONS,
+    _HANDOFF_CATEGORY_LABELS,
+    _classify_handoff_finding,
+)
+
+_HANDOFF_TERMINATION_REASON_LABELS: dict[str, str] = {
+    "ship": "SHIP",
+    "findings_present": "findings present",
+    "max_rounds_reached": "max rounds reached",
+    "producer_stalled": "producer stalled",
+    "producer_subprocess_error": "producer subprocess error",
+    "reviewer_failure": "reviewer failure",
+    "synth_failure": "synthesizer failure",
+    "test_subprocess_error": "test subprocess error",
+    "worktree_error": "worktree provisioning error",
+    "diff_malformed": "diff filter refusal (unidentifiable headers)",
+    "diff_too_large": "diff exceeds [loop] max_diff_bytes",
+    "prompt_too_large": "assembled reviewer prompt exceeds provider ceiling",
+    "parse_failure": "output parse failure",
+    "config_error": "config error",
+}
+
+
+def _handoff_producer_commit_subject(repo_root: Path | None, ending_sha: str) -> str:
+    """Look up the producer commit subject without importing loop_summary.
+
+    Handoff and loop_summary are peers in the top persistence layer, so
+    handoff keeps this small best-effort helper local to preserve the
+    documented acyclic layer direction.
+    """
+    if repo_root is None or not ending_sha:
+        return ""
+    try:
+        from syncade.process import run_subprocess
+
+        result = run_subprocess(
+            ["git", "log", "-1", "--pretty=format:%s", ending_sha],
+            cwd=repo_root,
+            timeout=5.0,
+        )
+    except Exception:
+        return ""
+    if result.returncode != 0:
+        return ""
+    return result.stdout.strip()
+
+
+def persist_handoff(
+    run_dir: Path,
+    *,
+    final_exit_code: int,
+    final_round: int,  # noqa: ARG001 — accepted for API symmetry with persist_loop_summary/manifest
+    termination_reason: str,
+    rounds: list,  # list[RoundResult]; typed as list to avoid circular import
+    max_rounds: int,
+    pr_doc_path: Path | None = None,
+    repo_root: Path | None = None,
+) -> Path | None:
+    """Write ``<run_dir>/handoff.md`` — structured operator handoff
+    when the loop terminates with work remaining.
+
+    Generated only when ``final_exit_code in (20, 30)`` AND the final
+    round's synthesizer surfaced at least one active (non-dismissed)
+    blocker. Returns ``None`` on any other path so the caller (the
+    orchestrator) can call this unconditionally and rely on the
+    function's own gate.
+
+    The handoff is APPEND, not REPLACE: ``loop-summary.md`` is still
+    written by :func:`persist_loop_summary` with its current shape
+    and role (high-level rollup). The handoff focuses narrowly on
+    "what's still blocking, here's what the producer tried, here's
+    how to disposition the remaining work" so the operator reading
+    one file gets the whole picture without grepping multiple
+    artifacts.
+
+    Auto-classification is HEURISTIC. The rendered handoff explicitly
+    documents this so the operator doesn't over-trust the
+    categorization. See :func:`_classify_handoff_finding` for the
+    classification rules and priority order.
+
+    Args:
+        run_dir: Top-level run directory
+            (``<repo>/.syncade/runs/<id>/``).
+        final_exit_code: The loop's final exit code. The handoff
+            fires only for ``20`` (max_rounds_reached) and ``30``
+            (findings present / producer stalled).
+        final_round: 0-indexed round that terminated the loop.
+        termination_reason: Categorical termination label (see
+            :data:`syncade.orchestrator.TerminationReason`).
+        rounds: List of :class:`syncade.orchestrator.RoundResult`,
+            one per round executed.
+        max_rounds: Configured ``[loop] max_rounds`` ceiling.
+        pr_doc_path: Path to the PR brief that drove the run. Used
+            by the auto-classifier to recognize "this finding's file
+            IS the PR brief" → category ``"P"``. ``None`` skips the
+            path-based check (phrase-based classification still
+            runs).
+        repo_root: Repo root, used for ``git log`` lookups when
+            rendering producer commit subjects. Optional — falls
+            back to the SHA-only form when missing.
+
+    Returns:
+        Path of the written ``handoff.md`` on the write path;
+        ``None`` when the exit code or active-blocker conditions
+        aren't met (no handoff to write).
+
+    Raises:
+        FileNotFoundError: If ``run_dir`` does not exist (caller
+            bug — the orchestrator creates it during run setup).
+    """
+    if not run_dir.is_dir():
+        raise FileNotFoundError(f"run_dir does not exist: {run_dir}")
+
+    # Gate 1: only fire on exit 20 / 30.
+    if final_exit_code not in (20, 30):
+        return None
+
+    # Gate 2: must have active blockers in the FINAL round's synth.
+    # The spec contract is: final_exit_code in (20, 30) AND
+    # active_blocker_count > 0. Zero-blocker exit-30 paths (e.g.
+    # producer_stalled after a clean synth) do not produce a handoff
+    # — there are no remaining blockers for the operator to action.
+    if not rounds:
+        return None
+    last_round = rounds[-1]
+    active_blockers: list[ConsolidatedFinding] = []
+    if last_round.synth_result is not None and last_round.synth_result.output is not None:
+        for f in last_round.synth_result.output.consolidated_findings:
+            if not f.dismissed and f.severity == "blocker":
+                active_blockers.append(f)
+
+    if not active_blockers:
+        return None
+
+    run_id = run_dir.name
+
+    # ---- Header ------------------------------------------------------
+    verdict_label = "NO-SHIP"
+    reason_label = _HANDOFF_TERMINATION_REASON_LABELS.get(termination_reason, termination_reason)
+
+    # SHA annotation. The handoff describes the FINAL round's
+    # outstanding blockers, so the SHA the operator (or future agent)
+    # needs is the FINAL round's snapshot SHA — what reviewers had as
+    # HEAD when they produced the findings under inspection. The
+    # empty-``rounds`` branch is defensive; the gate above returns
+    # ``None`` before we get here when no rounds ran.
+    last_round_sha = rounds[-1].snapshot.commit_sha if rounds else ""
+    if last_round_sha:
+        sha_line = (
+            f"**Generated against SHA:** `{last_round_sha[:12]}` (full: `{last_round_sha}`)  "
+        )
+    else:
+        sha_line = "**Generated against SHA:** (unknown — no rounds executed)  "
+
+    lines: list[str] = [
+        f"# Syncade run {run_id} — handoff",
+        "",
+        f"**Final verdict:** {verdict_label}  ",
+        f"**Final exit code:** {final_exit_code}  ",
+        f"**Termination reason:** {reason_label}  ",
+        sha_line,
+        f"**Rounds executed:** {len(rounds)} of {max_rounds}  ",
+        f"**Active blockers remaining:** {len(active_blockers)}",
+        "",
+        "> This handoff is generated automatically when the loop "
+        "terminates with work remaining. The disposition categories "
+        "below are HEURISTIC — the operator's judgment owns the "
+        "final call. See the per-blocker provenance for the raw "
+        "reviewer outputs.",
+        "",
+    ]
+
+    # ---- What's left -------------------------------------------------
+    # The zero-blockers path returns None at the gate above, so by here ``active_blockers`` is
+    # always non-empty. Classify and render directly.
+    lines.append("## What's left")
+    lines.append("")
+    classifications: list[tuple[ConsolidatedFinding, str]] = [
+        (f, _classify_handoff_finding(f, pr_doc_path=pr_doc_path)) for f in active_blockers
+    ]
+    for i, (finding, category) in enumerate(classifications, start=1):
+        first_line = finding.description.strip().splitlines()[0]
+        lines.append(f"### Blocker {i} — {first_line}")
+        lines.append("")
+        # File + provenance
+        file_md = _file_or_repo_wide(finding.file)
+        lines.append(f"- **File:** {file_md}")
+        provenance_md = ", ".join(
+            f"{p.reviewer_name} ({p.original_severity})" for p in finding.provenance
+        )
+        lines.append(f"- **Provenance:** {provenance_md}")
+        # Description body. Flatten newlines to spaces so a multi-line
+        # synthesizer description doesn't break the bullet list — mirrors
+        # findings_md.py's per-reviewer-description handling.
+        description = finding.description.strip().replace("\n", " ")
+        lines.append(f"- **Description:** {description}")
+        # Classification
+        cat_label = _HANDOFF_CATEGORY_LABELS.get(category, category)
+        lines.append(f"- **Suggested disposition category:** {category} — {cat_label}")
+        lines.append(f"- **Operator action:** {_HANDOFF_CATEGORY_DESCRIPTIONS.get(category, '')}")
+        lines.append("")
+
+    # ---- What the producer attempted --------------------------------
+    lines.append("## What the producer attempted")
+    lines.append("")
+    producer_rounds = [r for r in rounds if r.producer_result is not None]
+    if not producer_rounds:
+        lines.append("_(no producer rounds ran)_")
+        lines.append("")
+    else:
+        # Build round_idx → active blocker count for "Findings
+        # addressed" / "Remaining forwarded" heuristic rollup.
+        round_blocker_count: dict[int, int] = {}
+        for r in rounds:
+            count = 0
+            if r.synth_result is not None and r.synth_result.output is not None:
+                for f in r.synth_result.output.consolidated_findings:
+                    if not f.dismissed and f.severity == "blocker":
+                        count += 1
+            round_blocker_count[r.round_idx] = count
+
+        for r in producer_rounds:
+            pr = r.producer_result
+            if pr.outcome == "committed":
+                short_sha = pr.ending_sha[:12]
+                subject = _handoff_producer_commit_subject(repo_root, pr.ending_sha)
+                if subject:
+                    lines.append(
+                        f'- **Round {r.round_idx} producer commit:** `{short_sha}` ("{subject}")'
+                    )
+                else:
+                    lines.append(f"- **Round {r.round_idx} producer commit:** `{short_sha}`")
+                # Heuristic rollup: compare this round's synth blocker
+                # count to the next round's to approximate how many the
+                # producer addressed. "Heuristic" is surfaced explicitly
+                # so the operator doesn't over-trust the count.
+                k_before = round_blocker_count.get(r.round_idx, 0)
+                next_idx = r.round_idx + 1
+                if next_idx in round_blocker_count:
+                    k_after = round_blocker_count[next_idx]
+                    addressed = max(0, k_before - k_after)
+                    lines.append(
+                        f"- **Findings addressed:** (heuristic) ~{addressed} of {k_before}"
+                    )
+                    lines.append(
+                        f"- **Remaining findings forwarded to round {next_idx}:** {k_after}"
+                    )
+                else:
+                    lines.append(
+                        "- **Findings addressed:** (heuristic) unknown — no subsequent round synth"
+                    )
+                    lines.append(
+                        f"- **Remaining findings forwarded to round {next_idx}:** N/A (final round)"
+                    )
+            elif pr.outcome == "stalled":
+                lines.append(
+                    f"- **Round {r.round_idx} producer:** stalled "
+                    f"(no commit; HEAD stayed at `{pr.starting_sha[:12]}`)"
+                )
+            elif pr.outcome == "escalated":
+                # the handoff fires only on exit 20 / 30; an HONORED
+                # escalation exits 10 and never reaches here. So an escalated
+                # producer in the handoff was NOT honored — its escalation left
+                # active blocker(s) uncovered and the loop treated the round as
+                # a stall. Classify it as such.
+                lines.append(
+                    f"- **Round {r.round_idx} producer:** escalated but not honored "
+                    f"(left active blocker(s) uncovered → treated as stall; "
+                    f"HEAD stayed at `{pr.starting_sha[:12]}`)"
+                )
+            else:
+                err = type(pr.error).__name__ if pr.error else "Unknown"
+                lines.append(
+                    f"- **Round {r.round_idx} producer:** subprocess_error "
+                    f"({err}; HEAD stayed at `{pr.starting_sha[:12]}`)"
+                )
+        lines.append("")
+
+    # ---- Suggested next-step categories -----------------------------
+    lines.append("## Suggested next-step categories")
+    lines.append("")
+    lines.append(
+        "The operator-procedural pattern says some findings "
+        "self-resolve in the next commit, some are environment-bound, "
+        "some are real-code-defects. Below is the auto-classification "
+        "for THIS run's remaining blockers. The classification is "
+        "HEURISTIC — phrase-matching against synthesizer + reviewer "
+        "descriptions plus a file-path check for modified-file findings. "
+        "Treat it as a starting point, not a decision."
+    )
+    lines.append("")
+    # ``active_blockers`` is non-empty by the gate (see above), so
+    # ``classifications`` is always populated here. Group by category.
+    category_buckets: dict[str, list[tuple[int, ConsolidatedFinding]]] = {
+        c: [] for c in ("M", "F", "P", "A", "D")
+    }
+    for i, (finding, category) in enumerate(classifications, start=1):
+        category_buckets.setdefault(category, []).append((i, finding))
+    for cat in ("M", "F", "P", "A", "D"):
+        bucket = category_buckets.get(cat, [])
+        label = _HANDOFF_CATEGORY_LABELS[cat]
+        description = _HANDOFF_CATEGORY_DESCRIPTIONS[cat]
+        lines.append(f"### {cat} — {label}")
+        lines.append("")
+        lines.append(description)
+        lines.append("")
+        if not bucket:
+            lines.append("- _(none)_")
+        else:
+            for idx, finding in bucket:
+                first_line = finding.description.strip().splitlines()[0]
+                lines.append(f"- Blocker {idx}: {first_line}")
+        lines.append("")
+
+    # ---- Next steps -------------------------------------------------
+    lines.append("## Next steps")
+    lines.append("")
+    if termination_reason == "max_rounds_reached":
+        lines.append(
+            "- The loop ran the configured ``max_rounds`` without "
+            "converging. Address the M-category findings in a new "
+            "commit, then re-run with ``--max-rounds 1`` to verify "
+            "just the fixes. P-category findings self-resolve when "
+            "the operator commits the completion record. F-category "
+            "findings reflect brief/implementation drift — amend the "
+            "brief or add the convention to CLAUDE.md. A-category "
+            "findings require the operator to run the gate locally "
+            "and attest in the completion record."
+        )
+    elif termination_reason == "findings_present":
+        lines.append(
+            "- The single-pass run found remaining active blockers. "
+            "Address the findings manually, then re-run syncade to "
+            "verify the updated tree."
+        )
+    elif termination_reason == "producer_stalled":
+        lines.append(
+            "- The producer ran but didn't commit. Inspect the "
+            "final round's ``producer.stdout`` to see what it "
+            "attempted; common causes are under-specified findings "
+            "or the producer concluding the existing code is "
+            "already correct. Address the finding manually or "
+            "refine the producer prompt, then re-run."
+        )
+    elif termination_reason == "producer_subprocess_error":
+        lines.append(
+            "- The producer subprocess failed before it could "
+            "attempt a fix. Read the final round's "
+            "``producer.stderr`` and ``producer.error.txt`` for the "
+            "exception trace. Common causes: auth (run ``claude "
+            "login`` / ``codex login``), network errors, missing "
+            "CLI binary."
+        )
+    else:
+        lines.append(
+            f"- Loop terminated with reason ``{termination_reason}``. "
+            "Read the per-round artifacts under this run directory "
+            "for the failure shape."
+        )
+    lines.append("")
+
+    handoff_path = run_dir / "handoff.md"
+    atomic_write_text(handoff_path, "\n".join(lines))
+    return handoff_path

syncade/persistence/handoff_classify.py

@@ -0,0 +1,196 @@
+"""Heuristic blocker classification for handoff.md.
+
+Holds the disposition-category labels/descriptions, the phrase tables, and
+``_classify_handoff_finding`` — the heuristic that buckets a remaining active
+blocker into one of ``M | F | P | A | D``. ``handoff.py`` imports the classifier
+and the two category dicts it renders.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from syncade.synthesis import ConsolidatedFinding
+
+# Heuristic categories for auto-classifying remaining active blockers
+# when the loop terminates with work left. The labels are surfaced in
+# the rendered handoff.md so the operator knows what each category
+# means without consulting external docs. The handoff also states
+# explicitly that this is HEURISTIC — the operator's judgment owns
+# the final disposition.
+_HANDOFF_CATEGORY_LABELS: dict[str, str] = {
+    "M": "Manual fix needed",
+    "F": "False positive / convention mismatch",
+    "P": "Operator-procedural / self-resolving",
+    "A": "Operator-attested",
+    "D": "Dismiss with rationale",
+}
+
+_HANDOFF_CATEGORY_DESCRIPTIONS: dict[str, str] = {
+    "M": ("Real code defect. Operator addresses in a new commit."),
+    "F": (
+        "Implementation correctly follows established convention; brief "
+        "was imprecise. Operator amends the brief or adds the "
+        "convention to CLAUDE.md."
+    ),
+    "P": (
+        "Workflow-state finding (completion record absent, brief still "
+        "DRAFT, status header not yet updated, commit hashes still "
+        "`(to fill)`). Resolves when the operator commits the "
+        "completion record."
+    ),
+    "A": (
+        "Reviewer couldn't verify due to sandbox limitation (real-CLI "
+        "smoke, network, etc.). Operator runs the gate locally and "
+        "attests in the completion record with an "
+        "``Operator-attested: <run-id>`` rationale line."
+    ),
+    "D": ("Finding is structurally noise — empty repo state, harness-induced artifact, etc."),
+}
+
+# Phrase substrings (lowercase match). Order in the classification
+# helper matters because the first match wins; the rule set below
+# documents that order. See ``_classify_handoff_finding`` for the priority
+# order.
+_HANDOFF_OPERATOR_PROCEDURAL_PHRASES = (
+    "completion record",
+    "pr brief",
+    "status header",
+    "status line",
+    "commit hashes",
+    "to fill",
+)
+_HANDOFF_OPERATOR_ATTESTED_PHRASES = (
+    "sandbox",
+    "couldn't run",
+    "could not run",
+    "sandboxed environment",
+    "smoke not affirmatively verified",
+    "recursive `claude -p`",
+    "recursive `codex exec`",
+)
+_HANDOFF_CONVENTION_PHRASES = (
+    "convention mismatch",
+    "brief was imprecise",
+    "implementation correctly follows",
+    "implementation is more correct",
+    "intentional convention",
+)
+# Worktree-strip artifact phrases. Reviewer worktrees deliberately
+# strip CLAUDE.md (architectural invariant — reviewers must not see
+# project memory). Any PR that legitimately edits CLAUDE.md produces
+# a reviewer-side phantom "tracked deletion" finding that the cold
+# synth cannot dismiss (cannot-invent invariant blocks the dismissal
+# rationale). Routing these phrases to category F lets the operator see the
+# structural false positive at the top of the handoff rather than buried under
+# M-category defects.
+_HANDOFF_WORKTREE_STRIP_PHRASES = (
+    "deleted in the reviewed worktree",
+    "deleted from the reviewed worktree",
+    "tracked deletion",
+    "tracked file deletion",
+    "claude.md is deleted",
+    "claude.md is still deleted",
+)
+_HANDOFF_TEST_REGRESSION_PHRASES = (
+    "test caller broke",
+    "kwarg mismatch",
+)
+
+
+def _classify_handoff_finding(
+    finding: ConsolidatedFinding,
+    pr_doc_path: Path | None = None,
+) -> str:
+    """Heuristically classify one ``ConsolidatedFinding`` into a
+    disposition category for the handoff artifact.
+
+    Returns one of ``"M" | "F" | "P" | "A" | "D"`` (see
+    :data:`_HANDOFF_CATEGORY_LABELS` for the human-readable
+    labels). This is HEURISTIC — the operator's judgment owns the
+    final disposition. The handoff itself states this explicitly so
+    the categorization is treated as a hint, not a decision.
+
+    Priority order (first match wins):
+
+    1. ``file`` equals the PR brief itself (matched on basename to
+       tolerate relative-vs-absolute path mismatches) → ``"P"``.
+    2. Description (synth-consolidated + every provenance entry's
+       original_description) contains a workflow-state phrase
+       (``"completion record"``, ``"pr brief"``, ``"status
+       header"``, etc.) → ``"P"``.
+    3. Description contains an operator-attested phrase
+       (``"sandbox"``, ``"couldn't run"``, etc.) → ``"A"``.
+    4. Description contains a convention-mismatch phrase
+       (``"convention mismatch"``, ``"implementation correctly
+       follows"``, etc.) → ``"F"``.
+    5. Description contains a worktree-strip artifact phrase
+       (``"deleted in the reviewed worktree"``, ``"tracked
+       deletion"``, etc.) → ``"F"``. Reviewer worktrees strip
+       CLAUDE.md per the architectural invariant; any PR that
+       legitimately edits CLAUDE.md surfaces a phantom "tracked
+       deletion" finding the cold synth cannot dismiss.
+    6. ``file`` is under ``tests/`` AND description references a
+       producer-regression phrase (``"test caller broke"``, ``"kwarg
+       mismatch"``) → ``"M"``.
+    7. Default → ``"M"``.
+
+    The phrase lists cover observed reviewer-output shapes for each handoff
+    category and the worktree-strip pattern (rule 5). Future updates may extend the
+    phrase lists as new patterns emerge; the priority order above
+    is part of the contract and shouldn't be reordered without
+    re-checking the test fixtures.
+
+    The ``"D"`` (dismiss) category exists for completeness but is
+    never assigned by the heuristic — the cold synthesizer can't
+    dismiss findings (cannot-invent invariant), so a category-D
+    blocker would only ever land in the handoff if a future PR adds
+    a "dismiss this in the completion record" workflow.
+    """
+    file = finding.file or ""
+
+    # Combine synth description with every provenance's
+    # original_description so phrase matches catch the original
+    # reviewer's wording (which the synth may paraphrase). Lower-
+    # cased once for the substring scan.
+    desc_parts = [finding.description or ""]
+    for p in finding.provenance:
+        desc_parts.append(p.original_description or "")
+    combined_desc = " ".join(desc_parts).lower()
+
+    # Rule 1: modified path (basename match) → P.
+    if pr_doc_path is not None and file:
+        if Path(file).name == pr_doc_path.name:
+            return "P"
+
+    # Rule 2: workflow-state phrase → P.
+    if any(phrase in combined_desc for phrase in _HANDOFF_OPERATOR_PROCEDURAL_PHRASES):
+        return "P"
+
+    # Rule 3: operator-attested phrase → A.
+    if any(phrase in combined_desc for phrase in _HANDOFF_OPERATOR_ATTESTED_PHRASES):
+        return "A"
+
+    # Rule 4: convention-mismatch phrase → F.
+    if any(phrase in combined_desc for phrase in _HANDOFF_CONVENTION_PHRASES):
+        return "F"
+
+    # Rule 5: worktree-strip artifact phrase → F. Reviewer worktrees
+    # strip CLAUDE.md per the architectural invariant; any PR that
+    # legitimately edits CLAUDE.md surfaces a phantom "tracked
+    # deletion" finding the cold synth cannot dismiss. Route to F so
+    # the operator's disposition path is "annotate-as-FP in the
+    # completion record" rather than "fix CLAUDE.md" (which would
+    # double-write or no-op against the already-present file).
+    if any(phrase in combined_desc for phrase in _HANDOFF_WORKTREE_STRIP_PHRASES):
+        return "F"
+
+    # Rule 6: tests/ + producer-regression phrase → M (explicit
+    # path; same as the default but documented separately).
+    if file.startswith("tests/") and any(
+        phrase in combined_desc for phrase in _HANDOFF_TEST_REGRESSION_PHRASES
+    ):
+        return "M"
+
+    # Rule 7: default → M.
+    return "M"

syncade/persistence/last_reviewed.py

@@ -0,0 +1,67 @@
+"""Per-branch last-reviewed SHA persistence.
+
+``<repo>/.syncade/last-reviewed.json`` is **cross-run** state (a sibling of
+``runs/``, NOT under any single run dir) that records, per branch, the HEAD a
+completed review last covered. A subsequent ``--scope since-last-review`` bounds
+its diff to commits after that SHA, so each review covers only new work instead
+of re-reviewing the whole branch every run.
+
+It is per-machine run state — gitignored, never committed, never cross-branch.
+Shape::
+
+    { "<branch>": { "sha": "<reviewed-HEAD>", "run_id": "...", "recorded_at_utc": "..." } }
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ._atomic import atomic_write_json
+
+LAST_REVIEWED_FILENAME = "last-reviewed.json"
+"""Basename under ``<repo>/.syncade/`` of the per-branch last-reviewed record."""
+
+
+def _path(repo_root: Path) -> Path:
+    return repo_root / ".syncade" / LAST_REVIEWED_FILENAME
+
+
+def _load(repo_root: Path) -> dict:
+    path = _path(repo_root)
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def persist_last_reviewed(
+    repo_root: Path,
+    *,
+    branch: str,
+    sha: str,
+    run_id: str,
+    recorded_at_utc: str,
+) -> Path:
+    """Record ``sha`` as ``branch``'s last-reviewed HEAD, merging into the
+    existing file so other branches' records are preserved. Creates
+    ``<repo>/.syncade/`` if needed. Returns the written path."""
+    data = _load(repo_root)
+    data[branch] = {"sha": sha, "run_id": run_id, "recorded_at_utc": recorded_at_utc}
+    path = _path(repo_root)
+    atomic_write_json(path, data, sort_keys=True)
+    return path
+
+
+def read_last_reviewed(repo_root: Path, branch: str) -> str | None:
+    """Return the recorded last-reviewed SHA for ``branch``, or ``None`` when the
+    file is absent/unparseable or has no entry for that branch."""
+    entry = _load(repo_root).get(branch)
+    if isinstance(entry, dict):
+        sha = entry.get("sha")
+        if isinstance(sha, str) and sha:
+            return sha
+    return None