alissa-tools-github-revloop 0.31.3__tar.gz → 0.31.4__tar.gz

{alissa_tools_github_revloop-0.31.3/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.31.4}/PKG-INFO

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

{alissa_tools_github_revloop-0.31.3 → alissa_tools_github_revloop-0.31.4}/src/main/alissa/tools/github/revloop/alissa.py

@@ -239,7 +239,7 @@ _VERDICT_RE = re.compile(
 # 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
+#   - **Merge-Readiness:** operator — schema-migration: removes users.legacyId
 # 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
@@ -255,21 +255,83 @@ _READINESS_RE = re.compile(
     re.MULTILINE,
 )
 
+# The operator reason's CLASS (issue #142). An `operator` judgment names WHY
+# the merge is a human's, and until now it did so in prose the merge edge
+# could not act on: of 14 operator verdicts on ~40 studio PRs, 3 named real
+# merge risk and 11 were "the PR body lists an unverified item" -- validation
+# work the human does at gate 2 anyway, not a reason to withhold the merge.
+# So the reason now LEADS with one token from this closed enum, in the
+# consumer's grammar:
+#
+#   Merge-Readiness: auto
+#   Merge-Readiness: operator — <class>: <one-line reason>
+#
+# The order below is the SEVERITY order: when more than one row applies, the
+# reviewer names the one nearest the top (the most severe wins), and exactly
+# one. `auto` never carries a class. An operator line whose reason does not
+# lead with a recognised token is still valid grammar -- it parses, value and
+# reason intact -- and reads as UNCLASSED (`klass=None`); the consumer treats
+# unclassed as a hard hold (fail closed), so a reviewer that forgets the
+# class loses throughput, never safety. The token is matched exactly as
+# written here (lowercase, hyphenated): `Schema-Migration:` is not a class
+# this daemon reads, for the same reason `Auto` is not a value it carries.
+READINESS_CLASSES: "tuple[str, ...]" = (
+    "schema-migration",   # schema shape changes needing a migration / removal / rename on live data
+    "data-backfill",      # one-off writes over existing rows (backfills, stored-shape version bumps)
+    "secrets-env",        # new / changed env vars, secrets, credentials the deploy must carry
+    "infra-deploy",       # Dockerfiles, workflows, Railway config, base-image pins -- what runs
+    "billing",            # credit charging, pricing, tiers, quotas
+    "security",           # auth, permission gates, redaction, sandboxing flagged operator-worthy
+    "unverified-ux",      # the PR body's operator gate is a human look at a screen / copy / mockup
+    "unverified-runtime",  # the PR body's operator gate is a live smoke / real-model run / replay
+    "release-act",        # the merge itself is a release (VERSION bump -> publish, tag, npm)
+)
+_READINESS_CLASS_RE = re.compile(
+    r"^(" + "|".join(re.escape(klass) for klass in READINESS_CLASSES) + r")[ \t]*:"
+)
+
 # 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.
+# no more than this many characters. The class prefix is PART of the reason
+# and survives the flattening untouched: the native trailer must stay
+# byte-equal to the envelope's line, class included.
 MAX_READINESS_REASON_CHARS = 200
 
 
 def clean_readiness_reason(text: object) -> str:
-    """Flatten a Merge-Readiness reason to one bounded, backtick-free line."""
+    """Flatten a Merge-Readiness reason to one bounded, backtick-free line.
+
+    The `<class>:` prefix, when present, is kept intact at the head of the
+    line -- classify_readiness_reason reads it off the cleaned reason, and the
+    emitter copies the cleaned reason whole.
+    """
     if not isinstance(text, str):
         return ""
     flat = " ".join(text.replace("`", "").split())
     return flat[:MAX_READINESS_REASON_CHARS].rstrip()
 
 
+def classify_readiness_reason(value: object, reason: object) -> "str | None":
+    """The READINESS_CLASSES token an `operator` reason leads with, or None.
+
+    None for `auto` (never classed), for an operator reason that leads with
+    no recognised token (UNCLASSED -- the consumer's hard hold), and for a
+    token in the wrong case or spelling. The reason itself is never altered:
+    the class is read off it, not cut out of it.
+    """
+    if value != READINESS_OPERATOR or not isinstance(reason, str):
+        return None
+    match = _READINESS_CLASS_RE.match(reason)
+    return match.group(1) if match else None
+
+
+def _classed(value: "str | None", raw_reason: object) -> "tuple[str | None, str, str | None]":
+    """The `(value, reason, klass)` triple both parsers hand back."""
+    reason = clean_readiness_reason(raw_reason)
+    return (value, reason, classify_readiness_reason(value, reason))
+
+
 # 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
@@ -288,37 +350,42 @@ _TRAILER_RE = re.compile(
 )
 
 
-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.
+def parse_trailer(body: object) -> "tuple[str | None, str, str | None]":
+    """`(value, reason, klass)` from the first bare `Merge-Readiness:` line in
+    a review body, or `(None, "", 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.
+    is unchanged. `klass` is the READINESS_CLASSES token an operator reason
+    leads with, or None (auto, or an unclassed operator -- issue #142).
     """
     if not isinstance(body, str):
-        return (None, "")
+        return (None, "", 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)))
+        return (None, "", None)
+    return _classed(match.group(1), match.group(2))
 
 
-def parse_readiness(blob: object) -> "tuple[str | None, str]":
-    """`(value, reason)` from the first Merge-Readiness line in `blob`.
+def parse_readiness(blob: object) -> "tuple[str | None, str, str | None]":
+    """`(value, reason, klass)` 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).
+    parses; `reason` is the cleaned trailing text (empty when there is none),
+    class prefix included; `klass` is the READINESS_CLASSES token that reason
+    leads with, or None when the value is `auto`, the reason is unclassed, or
+    nothing parsed (issue #142).
     """
     if not isinstance(blob, str):
-        return (None, "")
+        return (None, "", None)
     match = _READINESS_RE.search(blob)
     if match is None:
-        return (None, "")
-    return (match.group(1), clean_readiness_reason(match.group(2)))
+        return (None, "", None)
+    return _classed(match.group(1), match.group(2))
 
 
 @dataclass(frozen=True)
@@ -580,12 +647,17 @@ class VerdictEnvelope:
     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.
+    gave none. `readiness_class` is the READINESS_CLASSES token an operator
+    reason leads with (issue #142), or None: for `auto`, for an unclassed
+    operator reason, and for a missing line alike -- the reason keeps the
+    prefix either way, so the class is never lost between here and the
+    native trailer.
     """
 
     verdict: str
     readiness: "str | None" = None
     readiness_reason: str = ""
+    readiness_class: "str | None" = None
 
 
 @dataclass(frozen=True)
@@ -1086,9 +1158,9 @@ class Alissa:
                     continue
                 match = _VERDICT_RE.search(blob)
                 if match:
-                    readiness, reason = parse_readiness(content)
+                    readiness, reason, klass = parse_readiness(content)
                     if readiness is None:
-                        readiness, reason = parse_readiness(title)
+                        readiness, reason, klass = parse_readiness(title)
                     found.append(
                         (Alissa._created_key(item.get("createdAt")),
                          index,
@@ -1096,6 +1168,7 @@ class Alissa:
                              verdict=match.group(1).lower(),
                              readiness=readiness,
                              readiness_reason=reason,
+                             readiness_class=klass,
                          ))
                     )
                     break

{alissa_tools_github_revloop-0.31.3 → alissa_tools_github_revloop-0.31.4}/src/main/alissa/tools/github/revloop/loop.py

@@ -427,13 +427,21 @@ NATIVE_VERDICT_BODY = (
 # the last non-empty line before the hidden verdict marker --
 #
 #   Merge-Readiness: auto
-#   Merge-Readiness: operator — <one-line reason>
+#   Merge-Readiness: operator — <class>: <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 operator why the merge waited on them -- and NO class (issue #142): the
+# fallback is unclassed by construction, the consumer's hard hold.
+#
+# The operator reason leads with one token from alissa.READINESS_CLASSES
+# (issue #142) so the consumer can apply a POLICY to the hold instead of
+# holding every operator alike. The emitter copies the envelope's cleaned
+# reason whole, class prefix included, so the native line is byte-equal to
+# the envelope's; it never adds, drops or rewrites a class -- an unclassed
+# envelope posts unclassed, and the narration says so.
 #
 # 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
@@ -441,6 +449,21 @@ NATIVE_VERDICT_BODY = (
 # same regex (issue #134) -- one grammar, two writers, no drift.
 READINESS_MISSING_REASON = "envelope carries no Merge-Readiness line"
 
+# What the log line and the activity row say about an operator judgment whose
+# reason leads with no recognised class (issue #142). Named because it is a
+# state the merge policy acts on (hard hold), not an absence.
+READINESS_UNCLASSED = "unclassed"
+
+
+def readiness_class_term(value: "str | None", klass: "str | None") -> str:
+    """` class=<klass>` (or ` class=unclassed`) for an operator judgment, and
+    nothing at all for `auto` or a missing one -- `auto` never carries a
+    class, so naming one there would be noise the consumer must never read.
+    """
+    if value != READINESS_OPERATOR:
+        return ""
+    return f" class={klass or READINESS_UNCLASSED}"
+
 
 def readiness_trailer(envelope: "VerdictEnvelope | None") -> str:
     """The line the native APPROVE carries for `envelope`'s judgment.
@@ -449,7 +472,9 @@ def readiness_trailer(envelope: "VerdictEnvelope | None") -> str:
     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.
+    whose readiness did not parse) is `operator` with a reason saying so and
+    no class. The reason is copied whole, so an envelope's `<class>:` prefix
+    reaches the native line byte for byte (issue #142).
     """
     if envelope is not None and envelope.readiness == READINESS_AUTO:
         return f"{READINESS_TRAILER_LABEL} {READINESS_AUTO}"
@@ -679,18 +704,53 @@ _RECORD_THE_CAP = (
 # 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.
+#
+# The operator form carries a CLASS (issue #142): `operator — <class>:
+# <reason>`, one token from alissa.READINESS_CLASSES, so the merge edge can
+# apply a policy to the hold. The compact table below is the ONE place the
+# directive states the enum (each token exactly once -- test_readiness pins
+# it), in severity order with the most-severe rule and the reasoning the
+# reviewer needs to classify honestly: an unverified-* hold is validation
+# work, not merge risk, and saying so lets the policy merge it. The table's
+# rows are the README's, condensed; the README is the long form.
 _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`. "
+    "operator — <class>: <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 — <class>: <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, class "
+    "and reason to the envelope's line; `auto` only on an APPROVE of the "
+    "reviewed head. `<class>` is exactly ONE token from this closed enum, "
+    "lowercase and hyphenated, followed by a colon and the reason; the rows are "
+    "in severity order, most severe first: "
+    "`schema-migration` (schema shape changes that need a migration, removal or "
+    "rename on live data); "
+    "`data-backfill` (one-off writes over existing rows — backfills, version "
+    "bumps of stored shapes); "
+    "`secrets-env` (new or changed env vars, secrets or credentials the deploy "
+    "must carry); "
+    "`infra-deploy` (Dockerfiles, workflows, Railway config, base-image pins — "
+    "anything that changes what runs); "
+    "`billing` (credit charging, pricing, tiers, quotas); "
+    "`security` (auth, permission gates, redaction, sandboxing — anything the "
+    "rubric's third dimension flagged as operator-worthy); "
+    "`unverified-ux` (the PR body's operator gate is a human look at a screen, "
+    "copy or mockup); "
+    "`unverified-runtime` (the PR body's operator gate is a live smoke, "
+    "real-model run or replay the worker could not run); "
+    "`release-act` (the merge itself is a release — VERSION bump → publish, tag, "
+    "npm). "
+    "When more than one row applies, name the MOST SEVERE one — the row listed "
+    "first — and only it. Classify honestly, not defensively: an unverified-* "
+    "hold is validation work the human does at gate 2 anyway, not merge risk, "
+    "and the merge policy may merge it while it keeps holding every row above; "
+    "an operator line whose reason leads with no recognised token still parses "
+    "but reads as UNCLASSED — a hard hold that costs throughput, never safety. "
+    "`auto` never carries a class. 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` with no class. "
 )
 
 # -- the reviewer session's own CI gate (issue #84) ---------------------------
@@ -3732,9 +3792,14 @@ class ReviewWatcher:
             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.
+        # an APPROVE carries one, so only an APPROVE names it. The class is
+        # read BACK off the emitted line with the shared grammar (issue
+        # #142), so what the narration names is what the consumer will parse
+        # -- an unclassed operator says `class=unclassed`, the hard hold.
         readiness_value = trailer[len(READINESS_TRAILER_LABEL):].strip()
-        readiness_note = f" readiness={readiness_value}" if trailer else ""
+        posted_value, _, posted_class = parse_trailer(trailer)
+        class_term = readiness_class_term(posted_value, posted_class)
+        readiness_note = f" readiness={readiness_value}{class_term}" if trailer else ""
         log.info(
             "%s round %d closed: native %s review submitted as %s (%s)%s%s",
             pr.slug, round_, event, self.github.login, url or "no url",
@@ -3744,7 +3809,7 @@ class ReviewWatcher:
             pr,
             f"- {_now()} — round {round_} — native `{event}` review submitted "
             f"as `{self.github.login}` (verdict of record){gate_note}"
-            + (f" — merge-readiness: `{readiness_value}`" if trailer else ""),
+            + (f" — merge-readiness: `{readiness_value}`{class_term}" if trailer else ""),
         )
         if event == EVENT_COMMENT:
             # A degraded verdict takes the PR out of the loop (the review
@@ -4458,7 +4523,7 @@ class ReviewWatcher:
         if self.state.readiness_observed(pr.full_name, pr.number, pr.head_sha) is not None:
             return
 
-        value, reason = parse_trailer(newest.body)
+        value, reason, klass = parse_trailer(newest.body)
         head7 = pr.head_sha[:7]
         if value is None:
             readiness = READINESS_MISSING
@@ -4476,7 +4541,10 @@ class ReviewWatcher:
             )
         else:
             readiness = value
-            term = f"{value} — {reason}" if reason else value
+            # The class rides along (issue #142): `class=<token>` when the
+            # operator reason leads with one, `class=unclassed` when it does
+            # not, nothing for `auto`.
+            term = (f"{value} — {reason}" if reason else value) + readiness_class_term(value, klass)
             log.info(
                 "%s approve at %s by %s carries readiness=%s",
                 pr.slug, head7, self.github.login, term,

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

@@ -0,0 +1 @@
+0.31.4

{alissa_tools_github_revloop-0.31.3 → alissa_tools_github_revloop-0.31.4/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.31.3
+Version: 0.31.4
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

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

@@ -1 +0,0 @@
-0.31.3