wade-cli 1.1.1__tar.gz → 1.1.2__tar.gz

{wade_cli-1.1.1 → wade_cli-1.1.2}/AGENTS.md

@@ -72,6 +72,13 @@ No circular dependencies. Models are pure data. Services orchestrate. **Never im
 > GitHub (PR/issue body markers, labels) and worktree files, **not** SQLite. The
 > code still exists but is inert; removal is tracked as #357 C5.
 
+> **Closing-review state** lives in worktree files, not the immutable session
+> bundle: binding-aware receipts are under `.wade/reviews/`, and an active
+> PR-comment feedback cycle is under `.wade/review-cycles/`. The cycle preserves
+> its pre-edit baseline and feedback history across refreshes and is cleared
+> only after a successful PR-comment completion; unsafe state must fall back to
+> a full review.
+
 > **Deterministic git-hook install/reconcile/build logic lives in `git/hooks.py`**
 > (git layer), not `skills/installer.py`. Packaged template-asset loaders
 > (prompt/skill/hook templates) live in `utils/templates.py`, a leaf module.

{wade_cli-1.1.1 → wade_cli-1.1.2}/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Conventional Commits](https://conventionalcommits.org/).
 
+## [v1.1.2] — 2026-09-08
+
+### Bug Fixes
+
+- make closing reviews converge on final incremental changes (#503) (5599fb1)
+
 ## [v1.1.1] — 2026-09-08
 
 ### Bug Fixes

{wade_cli-1.1.1 → wade_cli-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: wade-cli
-Version: 1.1.1
+Version: 1.1.2
 Summary: WADE — Workflow for AI-Driven Engineering
 Project-URL: Homepage, https://github.com/ivanviragine/wade
 Project-URL: Repository, https://github.com/ivanviragine/wade
@@ -325,7 +325,7 @@ WADE splits review into an **AI review pass** you or the agent can invoke, and
 | Command | What it reviews |
 |---------|-----------------|
 | `wade review plan <file>` | A plan file, before it becomes tasks |
-| `wade review implementation` | The current implementation diff (mandatory gate before `done`) |
+| `wade review implementation` | The current implementation change (mandatory gate before `done`) |
 | `wade review batch <N>` | Coherence across parallel implementation branches |
 | `wade review pr-comments <N>` | Starts a session to address human/bot PR comments |
 | `wade review trigger <N>` | Posts configured bot-review trigger comments on the task's PR |
@@ -341,10 +341,27 @@ implementation` exits successfully without launching another reviewer and direct
 you to `wade implementation-session done`. The dispatch cap does not block a
 valid `--ack-self-review`, which still writes its active-binding receipt.
 
+The first implementation review for a frozen reviewer binding receives the
+complete branch change. After a successful review and a new fix commit, a
+re-review receives only the committed delta since that successful same-binding
+review, plus any staged or unstaged changes and the local `PLAN.md` when safely
+available. This narrows repeated review work without weakening `done`: the final
+receipt is still written for the exact current commit. An unreadable record,
+changed binding, unreachable baseline, or merge on the baseline-to-HEAD path
+falls back to the complete branch change.
+
 To fetch the unresolved comments themselves during a review session, the agent
 runs `wade review-pr-comments-session fetch <N>`; it resolves individual threads with
 `wade review-pr-comments-session resolve`.
 
+When a PR-comment session starts, WADE records its pre-edit commit and a feedback
+snapshot under local `.wade/review-cycles/` state, outside the immutable session
+bundle. Re-fetching retains prior feedback while adding new feedback, but never
+advances that baseline. Its closing review receives the accumulated feedback and
+the cycle delta; unsafe, mismatched, stale, or merged lineage uses the full
+branch change instead. A successful `review-pr-comments-session done` clears
+the cycle so later feedback starts from the then-current PR head.
+
 ### The auto-launched review session
 
 The auto-launched **review session** — the one started when you pick **"Wait

{wade_cli-1.1.1 → wade_cli-1.1.2}/README.md

@@ -289,7 +289,7 @@ WADE splits review into an **AI review pass** you or the agent can invoke, and
 | Command | What it reviews |
 |---------|-----------------|
 | `wade review plan <file>` | A plan file, before it becomes tasks |
-| `wade review implementation` | The current implementation diff (mandatory gate before `done`) |
+| `wade review implementation` | The current implementation change (mandatory gate before `done`) |
 | `wade review batch <N>` | Coherence across parallel implementation branches |
 | `wade review pr-comments <N>` | Starts a session to address human/bot PR comments |
 | `wade review trigger <N>` | Posts configured bot-review trigger comments on the task's PR |
@@ -305,10 +305,27 @@ implementation` exits successfully without launching another reviewer and direct
 you to `wade implementation-session done`. The dispatch cap does not block a
 valid `--ack-self-review`, which still writes its active-binding receipt.
 
+The first implementation review for a frozen reviewer binding receives the
+complete branch change. After a successful review and a new fix commit, a
+re-review receives only the committed delta since that successful same-binding
+review, plus any staged or unstaged changes and the local `PLAN.md` when safely
+available. This narrows repeated review work without weakening `done`: the final
+receipt is still written for the exact current commit. An unreadable record,
+changed binding, unreachable baseline, or merge on the baseline-to-HEAD path
+falls back to the complete branch change.
+
 To fetch the unresolved comments themselves during a review session, the agent
 runs `wade review-pr-comments-session fetch <N>`; it resolves individual threads with
 `wade review-pr-comments-session resolve`.
 
+When a PR-comment session starts, WADE records its pre-edit commit and a feedback
+snapshot under local `.wade/review-cycles/` state, outside the immutable session
+bundle. Re-fetching retains prior feedback while adding new feedback, but never
+advances that baseline. Its closing review receives the accumulated feedback and
+the cycle delta; unsafe, mismatched, stale, or merged lineage uses the full
+branch change instead. A successful `review-pr-comments-session done` clears
+the cycle so later feedback starts from the then-current PR head.
+
 ### The auto-launched review session
 
 The auto-launched **review session** — the one started when you pick **"Wait

{wade_cli-1.1.1 → wade_cli-1.1.2}/docs/dev/architecture.md

@@ -87,6 +87,7 @@ src/wade/
 │   ├── skill_invocation_service.py # Bind methods to bounded operation contracts
 │   ├── skill_diagnostics_service.py # Discovery and precedence diagnostics
 │   ├── review_record_service.py # Binding-aware durable review outcomes
+│   ├── review_cycle_service.py # Safe PR-comment feedback-cycle context
 │   ├── documentation_receipt_service.py # Current-commit documentation decision
 │   ├── batch_review_service.py      # Batch issue review
 │   ├── deps_service.py  # Dependency analysis
@@ -809,6 +810,22 @@ still records the current binding receipt because it acknowledges work already
 performed rather than dispatching a reviewer. Plan and PR-comment reviews are
 uncapped.
 
+Review input converges without weakening completion evidence. The first mapped
+implementation review uses the full branch diff; later reviews may select the
+nearest satisfying record for the same frozen REVIEW binding that is an ancestor
+of `HEAD`, then inspect only the delta from that commit. A Git error, malformed
+or foreign record, non-ancestor, or merge on that ancestry path forces the full
+branch diff. Staged and unstaged changes remain separate inputs in either case,
+and every review writes its ordinary exact-HEAD receipt.
+
+`review_cycle_service.py` stores the PR-comment session's issue/PR identity,
+pre-edit baseline, and normalized feedback in `.wade/review-cycles/`, outside
+the immutable session bundle. Re-fetching retains prior feedback and adds new
+feedback while preserving the baseline; a successful PR-comment `done` removes
+it. The closing review receives the accumulated feedback and cycle delta only
+after safe state, identity, ancestry, and merge-path checks. Any failed check
+emits a diagnostic and reviews the complete branch diff instead.
+
 The capability remediation is intentionally tool-neutral: retain the sandbox
 and grant only the worktree Git metadata paths, GitHub credential/API route, or
 local staging path named by the failure. Codex uses the resolved `ai.sandbox`
@@ -918,7 +935,7 @@ includes the active binding's pass count. The structured worktree records under
 `.wade/reviews/` provide deterministic gate evidence; the PR-body projection is
 the durable human-readable outcome.
 
-Binding-aware review records and documentation receipts use the descriptor-safe
+Binding-aware review records, review-cycle contexts, and documentation receipts use the descriptor-safe
 state primitives in `utils/safe_state.py`: `.wade` and intermediate directories
 must be real directories, final files are opened relative to trusted directory
 handles, and malformed/symlinked/unreadable state is treated as absent. Record

{wade_cli-1.1.1 → wade_cli-1.1.2}/docs/dev/workflows-and-skills.md

@@ -175,6 +175,14 @@ An implementation-to-PR-comment transition is a new session and replaces the
 manifest/workflow. Durable review records survive outside the session bundle,
 but apply only if the new session's review binding is identical.
 
+The implementation and PR-comment definitions currently use workflow revision
+2. Their authoritative order is verification, documentation decision, knowledge,
+then closing method review; an old frozen revision is rejected until an explicit
+refresh replaces it. Expected tracked documentation and knowledge changes are
+therefore normally present in the final review. If a review finding creates a
+new tracked commit, the session repeats affected verification/documentation work
+and reviews that new final commit.
+
 ## Bounded invocation contract
 
 `skill_invocation_service.py` composes bounded prompts structurally in this
@@ -228,7 +236,25 @@ active binding. Switching A to B preserves A's history but makes it inapplicable
 switching back to byte-identical A at the same commit reuses its record. Refresh
 of only WORK does not invalidate a REVIEW record.
 
-Manifest, review, and documentation-gate state uses descriptor-relative,
+The first implementation review for a REVIEW binding uses the full branch diff.
+A later one may use the nearest same-binding satisfying record that is a safe
+ancestor of `HEAD`, reviewing only its committed delta while retaining staged and
+unstaged sections. Git errors, malformed or other-binding records, non-ancestors,
+and any merge on the selected ancestry path fail open to the full branch diff.
+The record is only an input baseline: every completed review still writes the
+normal exact-`HEAD`, binding-aware receipt.
+
+PR-comment cycles persist separately at
+`.wade/review-cycles/review-cycle@<issue>.json`, rather than in immutable
+`.wade/session/` methodology snapshots. A cycle captures the open PR identity,
+the pre-edit baseline, and normalized fetched feedback. Starting or resuming a
+cycle preserves its baseline and retains prior feedback while adding newly
+fetched feedback; successful `review-pr-comments-session done` removes the
+context. The closing review uses that accumulated feedback plus the cycle delta
+only after identity, ancestry, and merge-path validation; unreadable, mismatched,
+malformed, or unsafe state falls back to a full diff.
+
+Manifest, review, review-cycle, and documentation-gate state uses descriptor-relative,
 no-follow filesystem operations. Unsafe/malformed/unreadable state is absent for
 gate purposes and fails toward re-review, never toward completion. SHA marker
 files are never accepted as review evidence. The completion classifier also

{wade_cli-1.1.1 → wade_cli-1.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wade-cli"
-version = "1.1.1"
+version = "1.1.2"
 description = "WADE — Workflow for AI-Driven Engineering"
 readme = "README.md"
 license = "MIT"

{wade_cli-1.1.1 → wade_cli-1.1.2}/src/wade/__init__.py

@@ -1,3 +1,3 @@
 """WADE (Workflow for AI-Driven Engineering) — AI-agent-driven git workflow management CLI."""
 
-__version__ = "1.1.1"
+__version__ = "1.1.2"

{wade_cli-1.1.1 → wade_cli-1.1.2}/src/wade/git/repo.py

@@ -686,6 +686,18 @@ def diff_between_checked(repo_root: Path, base: str, head: str) -> str:
     return _run_git("diff", f"{base}...{head}", cwd=repo_root).stdout
 
 
+def has_merge_commit_between(repo_root: Path, base: str, head: str) -> bool:
+    """Return whether the ancestry path from *base* to *head* contains a merge.
+
+    Callers first establish that ``base`` is an ancestor of ``head``.  Keeping
+    this query in the git layer lets review-input selection fail open when git
+    cannot establish a trustworthy incremental lineage.
+    """
+
+    result = _run_git("rev-list", "--merges", f"{base}..{head}", cwd=repo_root)
+    return bool(result.stdout.strip())
+
+
 def diff_worktree(repo_root: Path, *, staged: bool = False) -> str:
     """Return ``git diff`` output for the working tree (or the staged index).
 

wade_cli-1.1.2/src/wade/models/review_cycle.py

@@ -0,0 +1,69 @@
+"""Persisted PR-comment review-cycle context."""
+
+from __future__ import annotations
+
+import json
+import re
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+REVIEW_CYCLE_SCHEMA_VERSION = 1
+# A persisted context includes JSON syntax and other fields, so its actual
+# serialized byte length remains the authoritative limit.
+MAX_REVIEW_CYCLE_PAYLOAD_BYTES = 256 * 1024
+MAX_REVIEW_FEEDBACK_CHARS = MAX_REVIEW_CYCLE_PAYLOAD_BYTES
+_COMMIT_RE = re.compile(r"^[0-9a-f]{7,64}$")
+
+
+class ReviewCycleContext(BaseModel, frozen=True):
+    """The immutable baseline and mutable feedback snapshot for one PR cycle."""
+
+    schema_version: int = Field(default=REVIEW_CYCLE_SCHEMA_VERSION)
+    issue_number: str
+    pr_number: int = Field(gt=0)
+    baseline_commit: str
+    feedback: str = Field(min_length=1, max_length=MAX_REVIEW_FEEDBACK_CHARS)
+
+    @field_validator("schema_version")
+    @classmethod
+    def _schema(cls, value: int) -> int:
+        if value != REVIEW_CYCLE_SCHEMA_VERSION:
+            raise ValueError(f"Unsupported review-cycle schema {value}")
+        return value
+
+    @field_validator("issue_number")
+    @classmethod
+    def _issue_number(cls, value: str) -> str:
+        normalized = value.strip().lstrip("#")
+        if not normalized.isdigit() or int(normalized) <= 0:
+            raise ValueError("Review-cycle issue number must be positive")
+        return str(int(normalized))
+
+    @field_validator("baseline_commit")
+    @classmethod
+    def _commit(cls, value: str) -> str:
+        if not _COMMIT_RE.fullmatch(value):
+            raise ValueError("Review-cycle baseline must be a lowercase hexadecimal git object id")
+        return value
+
+    @field_validator("feedback")
+    @classmethod
+    def _feedback(cls, value: str) -> str:
+        normalized = value.replace("\r\n", "\n").replace("\r", "\n").strip()
+        if not normalized:
+            raise ValueError("Review-cycle feedback cannot be empty")
+        return normalized
+
+    def serialized_payload(self) -> bytes:
+        """Return the exact UTF-8 state-file representation for this context."""
+
+        return (
+            json.dumps(self.model_dump(mode="json"), indent=2, sort_keys=True, ensure_ascii=True)
+            + "\n"
+        ).encode("utf-8")
+
+    @model_validator(mode="after")
+    def _serialized_payload_fits_state_file(self) -> ReviewCycleContext:
+        if len(self.serialized_payload()) > MAX_REVIEW_CYCLE_PAYLOAD_BYTES:
+            raise ValueError("Review-cycle serialized payload exceeds the 256 KiB limit")
+        return self

{wade_cli-1.1.1 → wade_cli-1.1.2}/src/wade/models/workflow.py

@@ -178,7 +178,7 @@ SESSION_DEFINITIONS: dict[SessionKind, SessionDefinition] = {
         kind=SessionKind.IMPLEMENTATION,
         ai_command=AICommandKey.IMPLEMENT,
         workflow_template="implementation.md",
-        workflow_revision=1,
+        workflow_revision=2,
         launch_prompt="implement-context.md",
         session_phase=SessionPhase.IMPLEMENT,
         steps=(
@@ -187,9 +187,9 @@ SESSION_DEFINITIONS: dict[SessionKind, SessionDefinition] = {
             "understand-plan",
             "implement",
             "verify",
-            "method-review",
             "documentation",
             "knowledge",
+            "method-review",
             "pr-summary",
             "sync",
             "done",
@@ -214,7 +214,7 @@ SESSION_DEFINITIONS: dict[SessionKind, SessionDefinition] = {
         kind=SessionKind.REVIEW_PR_COMMENTS,
         ai_command=AICommandKey.REVIEW_PR_COMMENTS,
         workflow_template="review-pr-comments.md",
-        workflow_revision=1,
+        workflow_revision=2,
         launch_prompt="review-pr-comments.md",
         session_phase=SessionPhase.REVIEW,
         steps=(
@@ -223,9 +223,9 @@ SESSION_DEFINITIONS: dict[SessionKind, SessionDefinition] = {
             "verify-feedback",
             "address-feedback",
             "verify",
-            "method-review",
             "documentation",
             "knowledge",
+            "method-review",
             "pr-summary",
             "sync",
             "resolve-threads",

{wade_cli-1.1.1 → wade_cli-1.1.2}/src/wade/services/implementation_service/done.py

@@ -46,6 +46,7 @@ from wade.services.implementation_service.lifecycle import (
     _strip_summary_section,
 )
 from wade.services.implementation_service.usage_tracking import IMPL_USAGE_MARKER_START
+from wade.services.review_cycle_service import clear_review_cycle
 from wade.services.review_record_service import (
     count_binding_passes,
     has_other_satisfying_binding,
@@ -387,6 +388,18 @@ def done(
         # block + skip-worktree still in place) so the user can fix and re-run.
         return False
 
+    if session_type == "review-pr-comments" and not clear_review_cycle(
+        worktree_root, issue_number=issue_number
+    ):
+        # The PR may already be finalized, but completion remains retryable
+        # until the active review-cycle state is gone or durably invalidated.
+        # Otherwise a later feedback cycle could inherit an obsolete baseline.
+        console.error(
+            "Could not clear the completed PR-comment review-cycle state safely; "
+            "restore filesystem access and re-run done."
+        )
+        return False
+
     # Success only: strip the worktree gitignore block and restore .gitignore
     # visibility now that there is nothing left to retry. The PR is already
     # updated at this point, so a filesystem cleanup failure (read-only file,

wade_cli-1.1.2/src/wade/services/review_cycle_service.py

@@ -0,0 +1,192 @@
+"""Safe PR-comment review-cycle state outside immutable session bundles."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from wade.models.review_cycle import ReviewCycleContext
+from wade.utils.safe_state import (
+    MAX_STATE_FILE_BYTES,
+    atomic_write_state_file,
+    delete_state_file,
+    read_state_file,
+    state_file_present,
+)
+
+_DIRECTORIES = ("review-cycles",)
+_INVALIDATION_DIRECTORIES = ("review-cycle-invalidations",)
+_PREFIX = "review-cycle@"
+_FEEDBACK_SECTION = re.compile(r"(?m)(?=^### )")
+
+
+@dataclass(frozen=True)
+class ReviewCycleLookup:
+    """A context lookup that preserves an unsafe-state diagnostic."""
+
+    context: ReviewCycleContext | None
+    diagnostic: str | None = None
+
+
+def review_cycle_filename(issue_number: str) -> str:
+    """Return the one canonical context filename for an issue's active cycle."""
+
+    normalized = issue_number.strip().lstrip("#")
+    if not normalized.isdigit() or int(normalized) <= 0:
+        raise ValueError("Review-cycle issue number must be positive")
+    return f"{_PREFIX}{int(normalized)}.json"
+
+
+def read_review_cycle(
+    root: Path,
+    *,
+    issue_number: str,
+    pr_number: int,
+) -> ReviewCycleLookup:
+    """Read a current identity-matched cycle, never trusting malformed state."""
+
+    try:
+        filename = review_cycle_filename(issue_number)
+    except ValueError as exc:
+        return ReviewCycleLookup(None, str(exc))
+    if state_file_present(root, _INVALIDATION_DIRECTORIES, filename):
+        return ReviewCycleLookup(
+            None,
+            "PR-comment review-cycle state was invalidated after an unsafe update",
+        )
+    raw = read_state_file(root, _DIRECTORIES, filename)
+    if raw is None:
+        if state_file_present(root, _DIRECTORIES, filename):
+            return ReviewCycleLookup(
+                None,
+                "PR-comment review-cycle state is unreadable or unsafe",
+            )
+        return ReviewCycleLookup(None)
+    try:
+        context = ReviewCycleContext.model_validate_json(raw)
+    except (ValidationError, ValueError):
+        return ReviewCycleLookup(None, "PR-comment review-cycle state is malformed")
+    if context.issue_number != str(int(issue_number.lstrip("#"))):
+        return ReviewCycleLookup(None, "PR-comment review-cycle issue identity does not match")
+    if context.pr_number != pr_number:
+        return ReviewCycleLookup(None, "PR-comment review-cycle PR identity does not match")
+    return ReviewCycleLookup(context)
+
+
+def _feedback_sections(feedback: str) -> tuple[str, ...]:
+    """Return individually rendered review entries from a feedback snapshot."""
+
+    return tuple(
+        section.strip() for section in _FEEDBACK_SECTION.split(feedback)[1:] if section.strip()
+    )
+
+
+def _merge_feedback(existing_feedback: str, refreshed_feedback: str) -> str:
+    """Retain feedback already addressed while adding new feedback from a refresh."""
+
+    if refreshed_feedback in existing_feedback:
+        return existing_feedback
+
+    refreshed_sections = _feedback_sections(refreshed_feedback)
+    if refreshed_sections:
+        existing_sections = set(_feedback_sections(existing_feedback))
+        additions = [section for section in refreshed_sections if section not in existing_sections]
+        if not additions:
+            return existing_feedback
+        return f"{existing_feedback}\n\n## Feedback added during refresh\n\n" + "\n\n".join(
+            additions
+        )
+
+    return f"{existing_feedback}\n\n{refreshed_feedback}"
+
+
+def initialize_or_refresh_review_cycle(
+    root: Path,
+    *,
+    issue_number: str,
+    pr_number: int,
+    baseline_commit: str,
+    feedback: str,
+) -> ReviewCycleLookup:
+    """Create a cycle or retain its baseline and all feedback across refreshes."""
+
+    try:
+        filename = review_cycle_filename(issue_number)
+    except ValueError as exc:
+        return ReviewCycleLookup(None, f"Could not validate PR-comment review-cycle state: {exc}")
+    invalidation = _discard_invalidated_review_cycle(root, filename)
+    if invalidation is not None:
+        return ReviewCycleLookup(None, invalidation)
+
+    existing = read_review_cycle(root, issue_number=issue_number, pr_number=pr_number)
+    if existing.diagnostic is not None:
+        return existing
+    try:
+        context = (
+            ReviewCycleContext(
+                **(
+                    existing.context.model_dump()
+                    | {"feedback": _merge_feedback(existing.context.feedback, feedback)}
+                )
+            )
+            if existing.context is not None
+            else ReviewCycleContext(
+                issue_number=issue_number,
+                pr_number=pr_number,
+                baseline_commit=baseline_commit,
+                feedback=feedback,
+            )
+        )
+    except (ValidationError, ValueError) as exc:
+        return ReviewCycleLookup(None, f"Could not validate PR-comment review-cycle state: {exc}")
+    payload = context.serialized_payload()
+    if len(payload) > MAX_STATE_FILE_BYTES:
+        return ReviewCycleLookup(
+            None,
+            "Could not persist PR-comment review-cycle state: serialized payload exceeds "
+            "the 256 KiB limit",
+        )
+    if not atomic_write_state_file(root, _DIRECTORIES, filename, payload):
+        if clear_review_cycle(root, issue_number=issue_number):
+            return ReviewCycleLookup(
+                None,
+                "Could not persist PR-comment review-cycle state safely; the prior state was "
+                "invalidated",
+            )
+        return ReviewCycleLookup(None, "Could not persist PR-comment review-cycle state safely")
+    return ReviewCycleLookup(context)
+
+
+def clear_review_cycle(root: Path, *, issue_number: str) -> bool:
+    """Remove an active cycle, or durably invalidate it when removal is unsafe."""
+
+    try:
+        filename = review_cycle_filename(issue_number)
+    except ValueError:
+        return False
+    if not state_file_present(root, _DIRECTORIES, filename):
+        return True
+    if delete_state_file(root, _DIRECTORIES, filename):
+        return True
+    # A successful marker makes every later read fail closed, even if the old
+    # regular JSON file remains readable after a failed deletion.  It lives in
+    # a sibling directory so a read-only review-cycles directory can still be
+    # invalidated through its writable .wade parent.
+    return atomic_write_state_file(root, _INVALIDATION_DIRECTORIES, filename, b"")
+
+
+def _discard_invalidated_review_cycle(root: Path, filename: str) -> str | None:
+    """Clear a previous invalidation before beginning a fresh feedback cycle."""
+
+    if not state_file_present(root, _INVALIDATION_DIRECTORIES, filename):
+        return None
+    if state_file_present(root, _DIRECTORIES, filename) and not delete_state_file(
+        root, _DIRECTORIES, filename
+    ):
+        return "Could not discard invalidated PR-comment review-cycle state safely"
+    if not delete_state_file(root, _INVALIDATION_DIRECTORIES, filename):
+        return "Could not clear PR-comment review-cycle invalidation safely"
+    return None