alissa-tools-github-revloop 0.30.1__tar.gz → 0.31.1__tar.gz

{alissa_tools_github_revloop-0.30.1/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.31.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-revloop
-Version: 0.30.1
+Version: 0.31.1
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_revloop-0.30.1 → alissa_tools_github_revloop-0.31.1}/src/main/alissa/tools/github/revloop/alissa.py

@@ -233,6 +233,90 @@ _VERDICT_RE = re.compile(
     re.IGNORECASE,
 )
 
+# The envelope's merge-readiness judgment (issue #130). The alissa-code-review
+# skill writes it as one list line in the verdict envelope:
+#   - **Merge-Readiness:** auto
+#   - **Merge-Readiness:** operator — touches convex/schema.ts
+# Tolerant of the markdown around the label -- an optional bullet, optional
+# `**` bold around the label (with the colon inside or outside it), optional
+# bold around the value -- but NOT of the value's case: `Auto` is not a
+# judgment this daemon will carry, so it reads as missing and fails closed to
+# `operator` downstream. Line-anchored, first match wins, like the consumer's
+# own grammar; the reason runs to the end of the line and no further.
+READINESS_AUTO = "auto"
+READINESS_OPERATOR = "operator"
+_READINESS_RE = re.compile(
+    r"^[ \t]*(?:[-*+][ \t]+)?(?:\*\*)?[ \t]*Merge-Readiness[ \t]*:?[ \t]*(?:\*\*)?"
+    r"[ \t]*:?[ \t]*(?:\*\*)?(auto|operator)\b(?:\*\*)?"
+    r"(?:[ \t]*[—–-][ \t]*(.*?))?[ \t]*$",
+    re.MULTILINE,
+)
+
+# The reason lands in a GitHub review body (as a line-anchored trailer) and in
+# a log line, so it is bounded and flattened at the parser: one line, no
+# backticks (a fence would swallow the trailer and everything after it), and
+# no more than this many characters.
+MAX_READINESS_REASON_CHARS = 200
+
+
+def clean_readiness_reason(text: object) -> str:
+    """Flatten a Merge-Readiness reason to one bounded, backtick-free line."""
+    if not isinstance(text, str):
+        return ""
+    flat = " ".join(text.replace("`", "").split())
+    return flat[:MAX_READINESS_REASON_CHARS].rstrip()
+
+
+# The trailer's own grammar (issue #134) -- the bare-line sibling of
+# _READINESS_RE. This is the line a native review ENDS with, whoever wrote
+# it: the daemon's emitter (loop.readiness_trailer) when it posts the verdict
+# itself, or the reviewer session's own `gh pr review` on the normal path.
+# It is the consumer's grammar verbatim (README, "The `Merge-Readiness`
+# trailer"): line-anchored, no bullet, no bold, no backticks, first match
+# wins, value case-sensitive. The label is the ONE constant the emitter
+# builds from, so the two cannot drift: a line the emitter writes is, by
+# construction, a line this regex reads.
+READINESS_TRAILER_LABEL = "Merge-Readiness:"
+READINESS_MISSING = "missing"
+_TRAILER_RE = re.compile(
+    r"^" + re.escape(READINESS_TRAILER_LABEL)
+    + r"[ \t]*(auto|operator)(?:[ \t]*[—-][ \t]*(.+))?[ \t]*$",
+    re.MULTILINE,
+)
+
+
+def parse_trailer(body: object) -> "tuple[str | None, str]":
+    """`(value, reason)` from the first bare `Merge-Readiness:` line in a
+    review body, or `(None, "")` when no line matches the trailer grammar.
+
+    Strict where parse_readiness is tolerant: the line inside backticks
+    mid-sentence (studio #1258) and the envelope's `- **Merge-Readiness:**`
+    bullet both read as MISSING here, because the consumer's regex is what
+    decides whether the merge edge sees the judgment at all. CRLF bodies (a
+    review typed into the web form) are normalised first; the grammar itself
+    is unchanged.
+    """
+    if not isinstance(body, str):
+        return (None, "")
+    match = _TRAILER_RE.search(body.replace("\r\n", "\n"))
+    if match is None:
+        return (None, "")
+    return (match.group(1), clean_readiness_reason(match.group(2)))
+
+
+def parse_readiness(blob: object) -> "tuple[str | None, str]":
+    """`(value, reason)` from the first Merge-Readiness line in `blob`.
+
+    `value` is READINESS_AUTO / READINESS_OPERATOR, or None when no line
+    parses; `reason` is the cleaned trailing text (empty when there is none).
+    """
+    if not isinstance(blob, str):
+        return (None, "")
+    match = _READINESS_RE.search(blob)
+    if match is None:
+        return (None, "")
+    return (match.group(1), clean_readiness_reason(match.group(2)))
+
 
 @dataclass(frozen=True)
 class Task:
@@ -389,6 +473,23 @@ def _task_from_row(row: object) -> "Task | None":
     )
 
 
+@dataclass(frozen=True)
+class VerdictEnvelope:
+    """One parsed CR6 verdict envelope: the verdict, plus the merge-readiness
+    judgment the same envelope carries (issue #130).
+
+    `readiness` is READINESS_AUTO / READINESS_OPERATOR, or None when the
+    envelope has no parseable `Merge-Readiness` line -- the case the native
+    post fails closed on. `readiness_reason` is already one bounded,
+    backtick-free line (see clean_readiness_reason); empty when the envelope
+    gave none.
+    """
+
+    verdict: str
+    readiness: "str | None" = None
+    readiness_reason: str = ""
+
+
 @dataclass(frozen=True)
 class TaskDetail:
     """One task as `alissa task get` sees it: the task itself, plus everything
@@ -774,16 +875,29 @@ class Alissa:
         return matches[0]
 
     def latest_verdict(self, task_ref: str) -> str | None:
-        """The newest CR6 verdict envelope on a review task, or None.
+        """The newest CR6 verdict envelope's verdict on a review task, or None.
 
         Returns VERDICT_APPROVE / VERDICT_REQUEST_CHANGES. This is the verdict
         of record: reviewers post comment-mode reviews, so the GitHub review
         state is always COMMENTED and cannot express approval at all.
 
+        The word alone; `latest_envelope` returns the whole record (verdict
+        plus merge-readiness) off the same read for the caller that posts it.
+
         Never raises. The daemon polls forever and this runs inside every pass,
         so absent, empty or malformed evidence degrades to "no verdict" rather
         than taking the loop down.
         """
+        envelope = self.latest_envelope(task_ref)
+        return None if envelope is None else envelope.verdict
+
+    def latest_envelope(self, task_ref: str) -> "VerdictEnvelope | None":
+        """The newest CR6 verdict envelope on a review task, parsed, or None.
+
+        Same read and same tolerance as `latest_verdict`; this is the record
+        the native post carries onto GitHub (issue #130), so it needs the
+        envelope's Merge-Readiness line alongside the verdict word.
+        """
         try:
             data = run_json(["alissa", "task", "get", task_ref, "--json"], timeout=90)
         except CommandError as exc:
@@ -794,7 +908,7 @@ class Alissa:
             return None
 
         try:
-            return self._newest_verdict(data)
+            return self._newest_envelope(data)
         except Exception:  # pragma: no cover - defence in depth
             log.exception("could not parse verdict evidence for %s", task_ref)
             return None
@@ -839,10 +953,23 @@ class Alissa:
 
     @staticmethod
     def _newest_verdict(payload: object) -> str | None:
-        """Pick the newest parseable verdict out of a task's evidence array.
+        """The newest parseable verdict WORD out of a task's evidence array;
+        `_newest_envelope` with the readiness dropped, for the callers that
+        only decide on the word."""
+        envelope = Alissa._newest_envelope(payload)
+        return None if envelope is None else envelope.verdict
+
+    @staticmethod
+    def _newest_envelope(payload: object) -> "VerdictEnvelope | None":
+        """Pick the newest parseable verdict envelope out of a task's evidence
+        array, with the Merge-Readiness judgment it carries (issue #130).
 
         Every layer is optional by design -- the payload shape is whatever the
         CLI printed, and a task with no evidence is the normal round-1 case.
+
+        The readiness is read off the SAME evidence item as the verdict (its
+        body first, then its title), never off a neighbour: a stray line on an
+        older envelope must not decorate a newer round's verdict.
         """
         if not isinstance(payload, dict):
             return None
@@ -850,7 +977,7 @@ class Alissa:
         if not isinstance(evidence, list):
             return None
 
-        found: list[tuple[tuple[int, float], int, str]] = []
+        found: list[tuple[tuple[int, float], int, VerdictEnvelope]] = []
         for index, item in enumerate(evidence):
             if not isinstance(item, dict):
                 continue
@@ -861,10 +988,17 @@ class Alissa:
                     continue
                 match = _VERDICT_RE.search(blob)
                 if match:
+                    readiness, reason = parse_readiness(content)
+                    if readiness is None:
+                        readiness, reason = parse_readiness(title)
                     found.append(
                         (Alissa._created_key(item.get("createdAt")),
                          index,
-                         match.group(1).lower())
+                         VerdictEnvelope(
+                             verdict=match.group(1).lower(),
+                             readiness=readiness,
+                             readiness_reason=reason,
+                         ))
                     )
                     break
 

{alissa_tools_github_revloop-0.30.1 → alissa_tools_github_revloop-0.31.1}/src/main/alissa/tools/github/revloop/loop.py

@@ -22,14 +22,20 @@ from enum import Enum
 from pathlib import Path
 
 from .alissa import (
+    READINESS_AUTO,
+    READINESS_MISSING,
+    READINESS_OPERATOR,
+    READINESS_TRAILER_LABEL,
     VERDICT_APPROVE,
     VERDICT_REQUEST_CHANGES,
+    VerdictEnvelope,
     Alissa,
     ManagedSession,
     SessionRef,
     Task,
     TaskDetail,
     is_review_task_for,
+    parse_trailer,
     session_repo_slug,
 )
 from .alissa_client import AlissaClient
@@ -391,10 +397,54 @@ NATIVE_VERDICT_BODY = (
     "Submitted by the review daemon under the configured reviewer identity, so "
     "this round has a verdict of record on GitHub. The round's findings and "
     "reasoning are in the reviewer session's own comments on this PR{task_note}."
-    "{head_note}\n\n"
+    "{head_note}{readiness}\n\n"
     "{marker}"
 )
 
+# The merge-readiness trailer (issue #130). orcloop's opt-in merge edge merges
+# a PR only when the reviewer's APPROVE on the current head carries
+# `Merge-Readiness: auto`; the judgment is the reviewer session's (the
+# envelope's `- **Merge-Readiness:**` line) and this daemon only CARRIES it,
+# in a grammar the consumer can parse: one plain-text line, line-anchored,
+# the last non-empty line before the hidden verdict marker --
+#
+#   Merge-Readiness: auto
+#   Merge-Readiness: operator — <one-line reason>
+#
+# The rules that make it safe to consume: it is emitted on APPROVE events
+# ONLY (a request_changes envelope with a stray `auto` line carries nothing;
+# an approve the checks gate downgraded carries nothing), and an envelope
+# with no parseable line fails CLOSED to `operator`, with a reason that tells
+# the operator why the merge waited on them.
+#
+# The label and the grammar live in alissa.py (READINESS_TRAILER_LABEL,
+# parse_trailer): the emitter below builds from the label the regex is built
+# from, and _observe_session_readiness reads a session's own review with that
+# same regex (issue #134) -- one grammar, two writers, no drift.
+READINESS_MISSING_REASON = "envelope carries no Merge-Readiness line"
+
+
+def readiness_trailer(envelope: "VerdictEnvelope | None") -> str:
+    """The line the native APPROVE carries for `envelope`'s judgment.
+
+    The caller has already decided the event is an APPROVE; this only maps
+    the envelope onto the grammar. `auto` is emitted bare -- the consumer
+    keys on the value, and an operator reads a reason only when the merge is
+    theirs to make. A missing or unparseable judgment (None envelope, or one
+    whose readiness did not parse) is `operator` with a reason saying so.
+    """
+    if envelope is not None and envelope.readiness == READINESS_AUTO:
+        return f"{READINESS_TRAILER_LABEL} {READINESS_AUTO}"
+    if envelope is not None and envelope.readiness == READINESS_OPERATOR:
+        if envelope.readiness_reason:
+            return (
+                f"{READINESS_TRAILER_LABEL} {READINESS_OPERATOR} — "
+                f"{envelope.readiness_reason}"
+            )
+        return f"{READINESS_TRAILER_LABEL} {READINESS_OPERATOR}"
+    return f"{READINESS_TRAILER_LABEL} {READINESS_OPERATOR} — {READINESS_MISSING_REASON}"
+
+
 # Appended to the body when the round's review task is known.
 _VERDICT_TASK_NOTE = ", and the CR6 verdict envelope is on `{task_ref}`"
 
@@ -601,6 +651,30 @@ _RECORD_THE_CAP = (
     "from a stale template default. "
 )
 
+# The merge-readiness line (issue #130, #134). The verdict envelope is where
+# the reviewer's judgment lives. On the NORMAL path the session posts its own
+# native review, and that body passes through nothing -- so the session must
+# write the trailer itself, as the bare last non-empty line, in the consumer's
+# grammar (studio #1258 wrote it inside backticks mid-sentence and the merge
+# edge held the approve). The daemon copies the envelope's line onto a native
+# review only on the rounds where it posts the verdict itself, and an
+# envelope without the line posts as `operator` -- so a reviewer who skips it
+# has silently withheld auto-merge. The two grammar sentences are the
+# README's ("The `Merge-Readiness` trailer on a native approve"), verbatim.
+_MERGE_READINESS_LINE = (
+    "Your verdict envelope MUST carry the skill's `- **Merge-Readiness:** auto | "
+    "operator — <reason>` line, AND your OWN native review (every `gh pr review` "
+    "form and the reviews-API POST alike) MUST END with the bare line "
+    "`Merge-Readiness: auto` or `Merge-Readiness: operator — <one-line reason>` "
+    "as its last non-empty line — plain text at the start of the line, not in "
+    "backticks, not bold, not mid-sentence — byte-equal in value and reason to "
+    "the envelope's line; `auto` only on an APPROVE of the reviewed head. The "
+    "merge edge reads that line off the review and holds an approve without "
+    "it. The daemon copies the envelope's line onto a native review only when "
+    "it posts the verdict itself, and an envelope without the line posts as "
+    "`operator`. "
+)
+
 # -- the reviewer session's own CI gate (issue #84) ---------------------------
 #
 # _gate_on_checks (issue #58) gates the verdict the DAEMON posts. It cannot gate the
@@ -881,6 +955,7 @@ ROUND_1_DIRECTIVE = (
     "severity-tagged comments via gh pr review, record the verdict evidence, "
     "move the task to pending_validation. "
     + _RECORD_THE_CAP
+    + _MERGE_READINESS_LINE
     + "{credential}"
     + _CHECKS_BEFORE_VERDICT
     + "{checks}"
@@ -899,6 +974,7 @@ ROUND_K_DIRECTIVE = (
     "verify the fixes, sweep the new diff with the full rubric, record a "
     "round-{round} verdict envelope, move the task to pending_validation. "
     + _RECORD_THE_CAP
+    + _MERGE_READINESS_LINE
     + "{credential}"
     + _CHECKS_BEFORE_VERDICT
     + "{checks}"
@@ -2135,6 +2211,14 @@ class ReviewWatcher:
         # "that round has no native verdict", producing a duplicate post over a
         # session that closed its own round correctly.
         owed = completed - self.state.abandoned_rounds(pr.full_name, number)
+
+        # Observation only (issue #134): a session-posted APPROVE on the
+        # current head is looked at once for the Merge-Readiness trailer the
+        # merge edge reads. Above the native post and convergence because it
+        # decides nothing -- it reports; and it must run on the pass that
+        # converges, since a converged PR leaves the search set.
+        self._observe_session_readiness(pr, my_reviews, completed)
+
         if task is not None and owed > native:
             # Terminal for this pass either way. On a landed post the review
             # request it consumed drops the PR out of the search, so
@@ -3169,9 +3253,10 @@ class ReviewWatcher:
         Never raises past RateLimited: a broken post must stall this PR, not
         the whole poll pass.
         """
-        verdict = self.alissa.latest_verdict(task.ref)
+        envelope = self.alissa.latest_envelope(task.ref)
+        verdict = None if envelope is None else envelope.verdict
         if verdict not in (VERDICT_APPROVE, VERDICT_REQUEST_CHANGES):
-            # count_verdicts and latest_verdict read the same envelopes with
+            # count_verdicts and latest_envelope read the same envelopes with
             # the same pattern, so this is nearly unreachable -- but "I know a
             # round finished and cannot tell you its verdict" must never be
             # resolved by guessing one onto the PR.
@@ -3266,6 +3351,11 @@ class ReviewWatcher:
                 return gate.hold
             event = gate.event
 
+        # The trailer follows the EVENT, not the envelope: an approve the
+        # checks gate turned into a REQUEST_CHANGES or COMMENT carries none,
+        # because `auto` on anything but an APPROVE is exactly what the
+        # consumer must never see (issue #130).
+        trailer = readiness_trailer(envelope) if event == EVENT_APPROVE else ""
         body = gate.lead + NATIVE_VERDICT_BODY.format(
             round=round_,
             verdict=verdict,
@@ -3275,6 +3365,7 @@ class ReviewWatcher:
                 if moved
                 else ""
             ),
+            readiness=f"\n\n{trailer}" if trailer else "",
             marker=verdict_marker(round_),
         )
         try:
@@ -3312,14 +3403,20 @@ class ReviewWatcher:
         self.state.record_verdict(
             pr.full_name, pr.number, judged, int(time.time()), url or ""
         )
+        # The readiness carried on the post, in the same three records. Only
+        # an APPROVE carries one, so only an APPROVE names it.
+        readiness_value = trailer[len(READINESS_TRAILER_LABEL):].strip()
+        readiness_note = f" readiness={readiness_value}" if trailer else ""
         log.info(
-            "%s round %d closed: native %s review submitted as %s (%s)%s",
-            pr.slug, round_, event, self.github.login, url or "no url", gate_note,
+            "%s round %d closed: native %s review submitted as %s (%s)%s%s",
+            pr.slug, round_, event, self.github.login, url or "no url",
+            readiness_note, gate_note,
         )
         self._append_activity(
             pr,
             f"- {_now()} — round {round_} — native `{event}` review submitted "
-            f"as `{self.github.login}` (verdict of record){gate_note}",
+            f"as `{self.github.login}` (verdict of record){gate_note}"
+            + (f" — merge-readiness: `{readiness_value}`" if trailer else ""),
         )
         if event == EVENT_COMMENT:
             # A degraded verdict takes the PR out of the loop (the review
@@ -3973,6 +4070,95 @@ class ReviewWatcher:
             deferred=True,
         )
 
+    def _observe_session_readiness(
+        self, pr: PullRequest, my_reviews: list[Review], round_: int
+    ) -> None:
+        """Say whether the session's own APPROVE carries the trailer (issue #134).
+
+        The merge edge reads `Merge-Readiness:` off the reviewer identity's
+        APPROVE on the current head. On the normal path that review is the
+        SESSION's -- posted by its own `gh pr review`, passing through nothing
+        here -- so a body without the bare line (studio #1258 had it inside
+        backticks mid-sentence) is an approve the edge holds, silently. The
+        fix is the skill's and the directive's; this is the daemon SEEING it:
+        one WARNING and one activity row per (PR, head) when the trailer is
+        missing, the `readiness=auto|operator` term when it parses.
+
+        Observation only, by contract: never a review posted, never the
+        session's review edited, never a round re-run. Scoped to the newest
+        reviewer-identity APPROVED review on the current head -- the review the
+        merge edge reads, whatever the identity wrote after it (a round-k
+        reviewer that fell back to `--comment`, a follow-up write-up) -- and
+        NOT the daemon's own post: that one is emitter-built and already
+        reported `readiness=` at post time (a second row for it would be
+        noise). Once per (PR, head) via the ledger flag beside the verdicts
+        row: a new head re-arms, a re-poll of the same head is silent.
+
+        Emit, then record, like every other activity note here: the ledger
+        flag lands only after the activity row did, so a transient comment
+        failure retries next poll instead of losing the row; and never under
+        `--dry-run`, where the row cannot land and a durable flag would let a
+        diagnostic pass silence the daemon it was run to diagnose (see
+        `_warn_identity_drift`). The flag rides a verdict row that
+        `last_verdict_at` also reads, so it is stamped only with the review's
+        own time -- an unreadable GitHub stamp keeps the log line and skips
+        both the row and the flag rather than inventing a verdict at "now".
+        """
+        approves = [
+            r for r in my_reviews
+            if r.state == "APPROVED" and r.commit_id and r.commit_id == pr.head_sha
+        ]
+        newest = approves[-1] if approves else None
+        if newest is None or newest.verdict_round is not None:
+            return
+        if self.state.readiness_observed(pr.full_name, pr.number, pr.head_sha) is not None:
+            return
+
+        value, reason = parse_trailer(newest.body)
+        head7 = pr.head_sha[:7]
+        if value is None:
+            readiness = READINESS_MISSING
+            log.warning(
+                "%s approve at %s by %s carries no Merge-Readiness trailer — the "
+                "merge edge will hold it; the session must end its review body "
+                "with the line (see directive)",
+                pr.slug, head7, self.github.login,
+            )
+            line = (
+                f"- {_now()} — round {round_} — session-posted `APPROVE` review by "
+                f"`{self.github.login}` at `{head7}` — readiness=missing (no "
+                f"`{READINESS_TRAILER_LABEL}` trailer on the review body; the merge "
+                f"edge will hold it)"
+            )
+        else:
+            readiness = value
+            term = f"{value} — {reason}" if reason else value
+            log.info(
+                "%s approve at %s by %s carries readiness=%s",
+                pr.slug, head7, self.github.login, term,
+            )
+            line = (
+                f"- {_now()} — round {round_} — session-posted `APPROVE` review by "
+                f"`{self.github.login}` at `{head7}` — readiness={term}"
+            )
+
+        posted_at = _epoch(newest.submitted_at)
+        if posted_at is None:
+            # No stamp to key a verdict row on; the log line above is the
+            # whole report for this poll, and the next poll says it again.
+            log.debug(
+                "%s: approve at %s has no readable submitted_at; readiness row "
+                "and flag skipped", pr.slug, head7,
+            )
+            return
+        if not self._append_activity(pr, line):
+            return  # retried next poll, like every other activity note
+        if self.config.dry_run:
+            return
+        self.state.note_readiness(
+            pr.full_name, pr.number, pr.head_sha, int(posted_at), readiness, newest.url,
+        )
+
     def _convergence_reason(
         self, my_reviews: list[Review], resolved: "ResolvedTask", head_sha: str
     ) -> str | None:

{alissa_tools_github_revloop-0.30.1 → alissa_tools_github_revloop-0.31.1}/src/main/alissa/tools/github/revloop/state.py

@@ -106,12 +106,20 @@ CREATE TABLE IF NOT EXISTS grants (
 -- never passes through the daemon). Rows are never pruned -- one per verdict
 -- ever landed -- and a lost row costs nothing: GitHub's reviews list is read
 -- alongside it and the gate takes the newer of the two.
+--
+-- `readiness` (issue #134) is the once-per-(PR, head) flag for the
+-- Merge-Readiness observation: NULL until the loop has looked at a
+-- session-posted APPROVE on that head, then `auto` / `operator` / `missing`
+-- -- the last being the one the loop WARNs about, once, because the merge
+-- edge will hold an approve with no trailer. Lives beside the verdict row
+-- rather than in a table of its own: it is a fact about that verdict.
 CREATE TABLE IF NOT EXISTS verdicts (
     repo       TEXT    NOT NULL,
     number     INTEGER NOT NULL,
     head_sha   TEXT    NOT NULL,
     posted_at  INTEGER NOT NULL,
     review_url TEXT,
+    readiness  TEXT,
     PRIMARY KEY (repo, number, head_sha, posted_at)
 );
 
@@ -350,6 +358,9 @@ _ADDED_COLUMNS = {
         ("checks_pending_at", "INTEGER"),
         ("verdict", "TEXT"),
     ),
+    "verdicts": (
+        ("readiness", "TEXT"),
+    ),
 }
 
 
@@ -777,6 +788,51 @@ class State:
             f"recording the verdict on {repo}#{number} at {head_sha[:8]}",
         )
 
+    def readiness_observed(self, repo: str, number: int, head_sha: str) -> str | None:
+        """The Merge-Readiness observation already made on this head
+        (`auto` / `operator` / `missing`), or None when the loop has not yet
+        looked at a session-posted APPROVE on it (issue #134). The once-per-
+        (PR, head) guard for the WARNING and its activity row."""
+        row = self._db.execute(
+            "SELECT readiness FROM verdicts "
+            "WHERE repo=? AND number=? AND head_sha=? AND readiness IS NOT NULL "
+            "ORDER BY posted_at DESC LIMIT 1",
+            (repo, number, head_sha),
+        ).fetchone()
+        return str(row["readiness"]) if row and row["readiness"] is not None else None
+
+    def note_readiness(
+        self, repo: str, number: int, head_sha: str, posted_at: int,
+        readiness: str, review_url: str = "",
+    ) -> bool:
+        """TELEMETRY: flag the verdict row for `head_sha` at `posted_at` with
+        the readiness the loop observed on it, creating the row if GitHub's
+        list showed the review before the ledger did (issue #134). Absorbed
+        like note_observed_verdict: a flag the ledger cannot take costs one
+        repeated WARNING on the next poll, not a wrong decision -- nothing
+        downstream reads the `readiness` column but the dedupe. The ROW is
+        another matter: it is a verdict row, and `last_verdict_at` reads its
+        `posted_at` for the post-verdict cooldown, so `posted_at` must be the
+        review's own GitHub stamp -- never a synthetic "now". The caller skips
+        the write when it has no such stamp. True on success."""
+        def write() -> None:
+            self._db.execute(
+                "INSERT OR IGNORE INTO verdicts "
+                "(repo, number, head_sha, posted_at, review_url) VALUES (?,?,?,?,?)",
+                (repo, number, head_sha, int(posted_at), review_url),
+            )
+            self._db.execute(
+                "UPDATE verdicts SET readiness=? "
+                "WHERE repo=? AND number=? AND head_sha=? AND posted_at=?",
+                (readiness, repo, number, head_sha, int(posted_at)),
+            )
+            self._db.commit()
+
+        return self._write_telemetry(
+            write,
+            f"recording readiness={readiness} on {repo}#{number} at {head_sha[:8]}",
+        )
+
     def last_verdict_at(self, repo: str, number: int, head_sha: str) -> int | None:
         """When the newest verdict of record on this head landed (epoch
         seconds), or None when the ledger knows of none on it."""
@@ -794,7 +850,7 @@ class State:
         with the `verdicts` table this raises `no such table`, not `[]` --
         whoever wires it into the console first should guard for that."""
         return self._read_rows(
-            "SELECT repo, number, head_sha, posted_at, review_url FROM verdicts "
+            "SELECT repo, number, head_sha, posted_at, review_url, readiness FROM verdicts "
             "ORDER BY posted_at DESC, number DESC",
             limit,
         )

alissa_tools_github_revloop-0.31.1/src/main/alissa/tools/github/revloop/version

@@ -0,0 +1 @@
+0.31.1

{alissa_tools_github_revloop-0.30.1 → alissa_tools_github_revloop-0.31.1/src/main/alissa_tools_github_revloop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-revloop
-Version: 0.30.1
+Version: 0.31.1
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

alissa_tools_github_revloop-0.30.1/src/main/alissa/tools/github/revloop/version

@@ -1 +0,0 @@
-0.30.1