alissa-tools-github-revloop 0.31.16__tar.gz → 0.31.18__tar.gz

{alissa_tools_github_revloop-0.31.16/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.31.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-revloop
-Version: 0.31.16
+Version: 0.31.18
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera
@@ -46,6 +46,18 @@ The rule: a distribution owns a leaf package and declares only that subtree
 `__init__.py` at any namespace level would claim it for one distribution and
 shadow the others.
 
+## Discovery PRs are not reviewed
+
+A PR in a plans repository (`plan_repos`, `ALISSA_REVIEW_PLAN_REPOS`) whose
+body carries `<!-- alissa-discovery v1 -->` on a line of its own and whose
+every changed path is under `knowledge-base/` gets **no review round** — no
+reviewer session, no review task — and one activity-comment line per head
+saying why. A marked PR that touches anything else (or whose file list cannot
+be read in full) is reviewed under the code directive, unchanged. The fleet
+flag `discovery_review` (`ALISSA_REVIEW_DISCOVERY_REVIEW`, default off) turns
+the skip off: every discovery PR is then reviewed like any other. See
+*Discovery PRs* in the repository README.
+
 ## Install
 
 ```sh

{alissa_tools_github_revloop-0.31.16 → alissa_tools_github_revloop-0.31.18}/README.md

@@ -24,6 +24,18 @@ The rule: a distribution owns a leaf package and declares only that subtree
 `__init__.py` at any namespace level would claim it for one distribution and
 shadow the others.
 
+## Discovery PRs are not reviewed
+
+A PR in a plans repository (`plan_repos`, `ALISSA_REVIEW_PLAN_REPOS`) whose
+body carries `<!-- alissa-discovery v1 -->` on a line of its own and whose
+every changed path is under `knowledge-base/` gets **no review round** — no
+reviewer session, no review task — and one activity-comment line per head
+saying why. A marked PR that touches anything else (or whose file list cannot
+be read in full) is reviewed under the code directive, unchanged. The fleet
+flag `discovery_review` (`ALISSA_REVIEW_DISCOVERY_REVIEW`, default off) turns
+the skip off: every discovery PR is then reviewed like any other. See
+*Discovery PRs* in the repository README.
+
 ## Install
 
 ```sh

{alissa_tools_github_revloop-0.31.16 → alissa_tools_github_revloop-0.31.18}/src/main/alissa/tools/github/revloop/config.py

@@ -183,6 +183,7 @@ CONFIG_KEYS = (
     "authors",
     "plan_repos",
     "plan_authors",
+    "discovery_review",
     "operators",
     "agent_profile",
     "reviewer_login",
@@ -268,6 +269,15 @@ JANITOR_WARN_PCT_ENV = "ALISSA_REVIEW_JANITOR_WARN_PCT"
 PLAN_REPOS_ENV = "ALISSA_REVIEW_PLAN_REPOS"
 PLAN_AUTHORS_ENV = "ALISSA_REVIEW_PLAN_AUTHORS"
 PLAN_REPO_OWNER_PLACEHOLDER = "<owner>"
+
+# The discovery fleet flag (issue #171; build-discovery design §3.3, DS-7).
+# OFF by default: a DISCOVERY PR -- a plans repository, the discovery marker,
+# every changed path under `knowledge-base/` (loop.discovery_skip_reason) --
+# gets no review round at all, because its defence is the knowledge-base lint
+# of record, staleness, the plan refuter and the user's acceptance. ON, every
+# discovery PR is reviewed under the code directive like any other PR. Same
+# env > file > default precedence and boolean spellings as the janitor's rail.
+DISCOVERY_REVIEW_ENV = "ALISSA_REVIEW_DISCOVERY_REVIEW"
 DEFAULT_PLAN_REPO_NAME = "alissa-dark-factory-plans"
 DEFAULT_PLAN_REPOS: "tuple[str, ...]" = (
     f"{PLAN_REPO_OWNER_PLACEHOLDER}/{DEFAULT_PLAN_REPO_NAME}",
@@ -896,6 +906,10 @@ class Config:
     plan_repos: tuple[str, ...] = DEFAULT_PLAN_REPOS
     plan_authors: tuple[str, ...] = ()
 
+    # Review discovery PRs after all (issue #171); see DISCOVERY_REVIEW_ENV.
+    # False -- the default -- skips them.
+    discovery_review: bool = False
+
     # GitHub logins whose re-entry ack may raise a capped PR's effective cap
     # (loop.parse_reentry_ack). Empty -- the default -- means NO ack is ever
     # honoured: the lever fails closed, because anyone who can comment on a PR
@@ -1267,6 +1281,16 @@ class Config:
         env_plan_authors = env_plan_list(PLAN_AUTHORS_ENV, environ)
         if env_plan_authors is not None:
             raw["plan_authors"] = env_plan_authors
+        # The discovery flag (issue #171), same layer, same reason.
+        env_discovery = _env_bool(DISCOVERY_REVIEW_ENV, environ)
+        if env_discovery is not None:
+            raw["discovery_review"] = env_discovery
+        discovery_review = raw.get("discovery_review", cls.discovery_review)
+        if not isinstance(discovery_review, bool):
+            # A JSON string "false" is truthy; refused rather than read as on.
+            raise ValueError(
+                f"discovery_review must be true or false, got {discovery_review!r}"
+            )
 
         source = raw.get("repos_source", cls.repos_source)
         if source not in _REPOS_SOURCES:
@@ -1552,6 +1576,7 @@ class Config:
             authors=authors,
             plan_repos=plan_repos,
             plan_authors=plan_authors,
+            discovery_review=discovery_review,
             operators=operators,
             agent_profile=raw.get("agent_profile", "claude"),
             reviewer_login=raw.get("reviewer_login"),

{alissa_tools_github_revloop-0.31.16 → alissa_tools_github_revloop-0.31.18}/src/main/alissa/tools/github/revloop/ghclient.py

@@ -93,6 +93,12 @@ COMPARE_COMMITS_PER_PAGE = 1
 # gone?" probe would answer yes on every large PR and abandon real verdicts.
 PR_COMMIT_CAP = 250
 
+# GitHub's OWN cap on the pull-request files endpoint: it "lists a maximum of
+# 3000 files" (30 pages of 100). Past it the listing is silently short, so a
+# PR at the cap cannot prove that EVERY changed path is under some prefix --
+# which is the one question `pull_request_files` is asked (issue #171).
+PR_FILES_CAP = 3000
+
 # Environment variables `gh` reads a token from. Both are cleared before an
 # explicitly-routed call, so an inherited implementer credential cannot win by
 # being the one variable we did not think to overwrite.
@@ -783,6 +789,58 @@ class GitHub:
                 return out
             page += 1
 
+    def pull_request_files(self, owner: str, repo: str, number: int) -> list[str]:
+        """Every path the PR changes, paged to the end.
+
+        Read on ONE path: the discovery skip (issue #171), which asks whether
+        EVERY changed path is under `knowledge-base/`. That is an absence
+        question again -- "nothing outside the prefix" -- so a listing at
+        GitHub's PR_FILES_CAP is REFUSED (`TruncatedListing`) rather than
+        answered short, and the caller reviews the PR instead of skipping it.
+
+        A RENAME contributes BOTH names, for the reason `compare_files` gives:
+        `src/x.py` moved to `knowledge-base/x.py` changed a path outside the
+        prefix, and reading only the destination would make it look confined.
+        """
+        out: list[str] = []
+        seen: set[str] = set()
+        listed = 0
+        page = 1
+        while True:
+            data = (
+                self._api(
+                    "-X",
+                    "GET",
+                    f"repos/{owner}/{repo}/pulls/{number}/files",
+                    "-f",
+                    f"per_page={PER_PAGE}",
+                    "-f",
+                    f"page={page}",
+                )
+                or []
+            )
+            listed += len(data)
+            for entry in data:
+                for key in ("filename", "previous_filename"):
+                    name = str(entry.get(key) or "")
+                    if name and name not in seen:
+                        seen.add(name)
+                        out.append(name)
+            if listed >= PR_FILES_CAP:
+                log.warning(
+                    "%s/%s#%d reached GitHub's %d-file listing cap — the file "
+                    "list is not complete, so 'nothing outside the prefix' "
+                    "cannot be read from it",
+                    owner, repo, number, PR_FILES_CAP,
+                )
+                raise TruncatedListing(
+                    f"{owner}/{repo}#{number} reached GitHub's {PR_FILES_CAP}-file "
+                    f"listing cap; absence cannot be proven from it"
+                )
+            if len(data) < PER_PAGE:
+                return out
+            page += 1
+
     # -- CI check rollup ---------------------------------------------------
 
     def check_rollup(self, owner: str, repo: str, sha: str) -> CheckRollup:

{alissa_tools_github_revloop-0.31.16 → alissa_tools_github_revloop-0.31.18}/src/main/alissa/tools/github/revloop/loop.py

@@ -1246,6 +1246,51 @@ def plan_id_of(pr: PullRequest) -> "str | None":
     return match.group(1) if match else None
 
 
+# -- the discovery skip (issue #171; build-discovery design §3.2, §3.3, DS-7) --
+#
+# A DISCOVERY PR is a discovery task's output: findings written into the
+# plans repository's `knowledge-base/`. Its defence is the knowledge-base lint
+# of record, staleness, the plan refuter and the user's acceptance (§3.3), so a
+# judgment review per discovery task would only double the subscription cost
+# -- revloop starts NO round on it, which is what leaves it without a review
+# task (the reviewer session is what creates one, CR2).
+#
+# All THREE signals, or it is not a discovery PR: the repository is in
+# `plan_repos`, the body carries the discovery marker on a line of its own,
+# and EVERY changed path is under `knowledge-base/` (the PR's files, paged).
+# A marked PR that touches anything else -- or whose files cannot be read in
+# full -- is reviewed under the CODE directive, unchanged: the safe reading.
+# The fleet flag `discovery_review` (config.DISCOVERY_REVIEW_ENV) turns the
+# skip off, and every discovery PR is then reviewed like any other.
+DISCOVERY_MARKER = "<!-- alissa-discovery v1 -->"
+DISCOVERY_PREFIX = "knowledge-base/"
+
+
+def discovery_marked(config: Config, pr: PullRequest) -> bool:
+    """The two signals readable without a GitHub call: the plans repository
+    and the marker on a line of its own (the plan marker's rule)."""
+    if not config.is_plan_repo(pr.full_name):
+        return False
+    body = pr.body.replace("\r\n", "\n")
+    return any(line.strip() == DISCOVERY_MARKER for line in body.split("\n"))
+
+
+def outside_discovery_prefix(paths: "list[str]") -> "list[str]":
+    """The changed paths NOT under `knowledge-base/`. An empty diff answers
+    with a placeholder rather than nothing: "every path is confined" must not
+    hold vacuously for a PR that changes no path at all."""
+    if not paths:
+        return ["(no changed files)"]
+    return [p for p in paths if not p.startswith(DISCOVERY_PREFIX)]
+
+
+def discovery_skip_kind(head_sha: str) -> str:
+    """The ping-ledger kind that dedupes the skip's activity line: one line
+    per head, since the review request stands and the skip is re-decided on
+    every poll."""
+    return f"activity-discovery-skip:{head_sha}"
+
+
 # The ORIGIN task a reviewer spawn is stamped with (`--task`, issue #153; the
 # Studio cost meter's lane L4). First from the review task's CR2 title --
 # `Review PR <org>/<repo>#<n> (TASK-<origin>)` -- then from the PR body, the
@@ -2640,6 +2685,12 @@ class ReviewWatcher:
         # hold a place forever.
         self._waiting: dict[tuple[str, int], Waiting] = {}
         self._wait_seq = 0
+        # The discovery skip's file reads (issue #171), keyed by (repo, PR,
+        # head): the changed paths outside `knowledge-base/` at that head. A
+        # skipped PR keeps its review request, so it is re-decided every poll,
+        # and a head's file list never changes -- one paged read per head, not
+        # one per poll. Only successful reads are kept; a failed one retries.
+        self._discovery_outside: "dict[tuple[str, int, str], list[str]]" = {}
         # Consecutive passes that deferred at least one round -- the summary
         # line's streak limiter, and ONLY that. It never escalates: a queue
         # that keeps draining is the gate working, and a wave permanently
@@ -3110,6 +3161,17 @@ class ReviewWatcher:
                 f"PR author {pr.author} is not in the authors allowlist",
             )
 
+        # THE DISCOVERY SKIP (issue #171) gates starting a round exactly as the
+        # authors filter does, and sits beside it for the same reasons: below
+        # every branch that FINISHES a round already started (a discovery PR
+        # reviewed while `discovery_review` was on still gets its verdict of
+        # record), above every one that numbers, records or starts one. Below
+        # the authors filter because it is the only one of the two that can
+        # cost a GitHub call.
+        skipped = self._discovery_skip(pr)
+        if skipped is not None:
+            return skipped
+
         # The effective cap is the configured one plus every re-entry an
         # operator has explicitly acked on THIS PR (issue #42). The sum is a
         # local read, so it costs nothing on the common path; the GitHub scan
@@ -3254,6 +3316,74 @@ class ReviewWatcher:
             stability=stability.notice,
         )
 
+    # -- the discovery skip (issue #171) -----------------------------------
+
+    def _discovery_skip(self, pr: PullRequest) -> Decision | None:
+        """A SKIPPED decision for a discovery PR, or None to review it.
+
+        None -- review under the code directive, the safe reading -- whenever
+        any of the three signals fails, the files cannot be read in full, or
+        the fleet flag `discovery_review` is on. The two cheap signals are read
+        first, so a PR that is not marked never costs a files read.
+
+        A skip appends ONE activity line per head (ledger-deduped, recorded
+        only once the append lands, so a dry run records nothing) and logs at
+        INFO only then; the re-decisions on later polls are DEBUG.
+        """
+        if not discovery_marked(self.config, pr):
+            return None
+        if self.config.discovery_review:
+            log.debug(
+                "%s carries the discovery marker but discovery_review is on — "
+                "reviewing under the code directive",
+                pr.slug,
+            )
+            return None
+
+        key = (pr.full_name, pr.number, pr.head_sha)
+        outside = self._discovery_outside.get(key)
+        if outside is None:
+            try:
+                paths = self.github.pull_request_files(pr.owner, pr.repo, pr.number)
+            except RateLimited:
+                # Throttling is not a fact about the diff (the stability
+                # guard's rule): raised on, so the poll backs off.
+                raise
+            except (CommandError, TruncatedListing) as exc:
+                log.warning(
+                    "%s carries the discovery marker but its changed files "
+                    "cannot be read in full — reviewing under the code "
+                    "directive: %s",
+                    pr.slug, exc,
+                )
+                return None
+            outside = outside_discovery_prefix(paths)
+            self._discovery_outside[key] = outside
+
+        if outside:
+            log.info(
+                "%s carries the discovery marker but changes %d path(s) outside "
+                "%s (first: %s) — reviewing under the code directive",
+                pr.slug, len(outside), DISCOVERY_PREFIX, outside[0],
+            )
+            return None
+
+        reason = (
+            f"discovery PR — plans repository, `{DISCOVERY_MARKER}` marker, "
+            f"every changed path under `{DISCOVERY_PREFIX}`; no review round "
+            f"(discovery_review is off)"
+        )
+        kind = discovery_skip_kind(pr.head_sha)
+        if not self.state.pinged(pr.full_name, pr.number, kind):
+            log.info("%s at %s: skipping review — %s", pr.slug, pr.head_sha[:8], reason)
+            if self._append_activity(
+                pr, f"- {_now()} — skipped at `{pr.head_sha[:8]}` — {reason}"
+            ):
+                self.state.record_ping(pr.full_name, pr.number, kind)
+        else:
+            log.debug("%s: %s", pr.slug, reason)
+        return Decision(Action.SKIPPED, reason)
+
     # -- the spawn gate ----------------------------------------------------
 
     def _gate_spawn(self, pr: PullRequest, round_: int) -> Decision | None:
@@ -6172,20 +6302,49 @@ class ReviewWatcher:
         #157): claim the spawn of this round's session against the drain
         flag, run `spawn` under the claim, and drop the claim however it ends.
 
-        The gate sits ABOVE every side effect of the spawn -- the hub add,
-        the `alissa tmux queue add`, the census bump, the ledger row, the
-        activity line -- so a drained seat touches nothing, and the round
-        stays owed: a QUEUED `drained` decision writes no spawn row, burns no
-        round number and spends no attempt, exactly like the slot gate. The
-        claim and the flag are read and written in one immediate transaction
-        on each side (`State.claim_spawn` / `State.set_drain`): a drain that
+        The gate sits ABOVE every side effect of the spawn but one -- the
+        `alissa tmux queue add`, the census bump, the ledger row and the
+        activity line all come after it -- and a round it stands down stays
+        owed: a QUEUED `drained` decision writes no spawn row, burns no round
+        number and spends no attempt, exactly like the slot gate. The claim
+        and the flag are read and written in one immediate transaction on
+        each side (`State.claim_spawn` / `State.set_drain`): a drain that
         lands while this spawn is between its gate and its ledger write sees
-        the claim and refuses itself, so a park can never race a spawn. A
-        ledger that cannot answer stands the spawn down too -- a spawn that
-        cannot prove the seat is not drained does not happen.
+        the claim and refuses itself. A ledger that cannot answer stands the
+        spawn down too -- a spawn that cannot prove the seat is not drained
+        does not happen.
+
+        The claim only counts for `parking.SPAWN_CLAIM_TTL`, and the hub add
+        (`_ensure_hub`, a clone on a PR's first round) can outlast it. So
+        `_spawn_claimed` re-takes the claim (`_claim_spawn` again, issue
+        #173) between the hub add and the enqueue, which refreshes it and
+        re-reads the flag: a drain that held while the hub was provisioned
+        stands the round down there, the same QUEUED `drained` way. That late
+        re-check is the one stand-down that happens AFTER a side effect --
+        the hub is provisioned and stays -- which is harmless, because the
+        hub is a reusable cache the round's next spawn finds in place.
+        Together the two claims mean a park can never race a spawn, whatever
+        the drain's freshness rule allows.
 
         Dry-run READS the flag and claims nothing: it shares the production
         state path, and a dry pass must write no durable row."""
+        refused = self._claim_spawn(pr, round_, name)
+        if refused is not None:
+            return refused
+        try:
+            return spawn()
+        finally:
+            if not self.config.dry_run:
+                self.state.release_spawn(name)
+
+    def _claim_spawn(
+        self, pr: PullRequest, round_: int, name: str, *, late: bool = False,
+    ) -> "Decision | None":
+        """Claim (or, `late`, re-claim) the spawn of `name` against the drain
+        flag: None when the spawn may proceed, else the QUEUED `drained`
+        decision that stands the round down. Dry-run reads the flag and
+        claims nothing. See `_drain_gated`."""
+        where = " after its hub was provisioned" if late else ""
         try:
             if self.config.dry_run:
                 drain = self.state.drain()
@@ -6193,36 +6352,32 @@ class ReviewWatcher:
                 drain = self.state.claim_spawn(name)
         except sqlite3.Error as exc:
             log.warning(
-                "%s round %d: could not claim the spawn against the drain flag "
-                "(%s) — standing it down this pass", pr.slug, round_, exc,
-            )
-            return Decision(
-                Action.QUEUED,
-                f"round {round_} stood down — the state ledger could not prove "
-                f"the seat is not drained ({exc}); retrying next poll",
-                round_,
-                drained=True,
-            )
-        if drain is not None:
-            since = parking_mod.iso(drain["drained_at"])
-            until = parking_mod.iso(drain["expires_at"])
-            log.info(
-                "%s round %d: not spawning — the seat is drained for parking "
-                "since %s (until %s)", pr.slug, round_, since, until,
+                "%s round %d: could not claim the spawn against the drain flag%s "
+                "(%s) — standing it down this pass", pr.slug, round_, where, exc,
             )
             return Decision(
                 Action.QUEUED,
-                f"round {round_} held — the seat is drained for parking since "
-                f"{since} (until {until}: {drain['reason'] or 'no reason given'}); "
-                f"retrying once it is undrained",
+                f"round {round_} stood down{where} — the state ledger could not "
+                f"prove the seat is not drained ({exc}); retrying next poll",
                 round_,
                 drained=True,
             )
-        try:
-            return spawn()
-        finally:
-            if not self.config.dry_run:
-                self.state.release_spawn(name)
+        if drain is None:
+            return None
+        since = parking_mod.iso(drain["drained_at"])
+        until = parking_mod.iso(drain["expires_at"])
+        log.info(
+            "%s round %d: not spawning%s — the seat is drained for parking "
+            "since %s (until %s)", pr.slug, round_, where, since, until,
+        )
+        return Decision(
+            Action.QUEUED,
+            f"round {round_} held{where} — the seat is drained for parking since "
+            f"{since} (until {until}: {drain['reason'] or 'no reason given'}); "
+            f"retrying once it is undrained",
+            round_,
+            drained=True,
+        )
 
     def _spawn_claimed(
         self,
@@ -6297,6 +6452,14 @@ class ReviewWatcher:
             # provisioned -- unknown, never settled.
             return Decision(Action.SKIPPED, problem, round_, owed=True)
 
+        # The hub add can outlast the gate's claim (a clone on a PR's first
+        # round): re-take it, refreshing it and re-reading the drain flag, so
+        # a drain that landed meanwhile stands the round down here (issue
+        # #173). The claim is still released in `_drain_gated`'s finally.
+        refused = self._claim_spawn(pr, round_, name, late=True)
+        if refused is not None:
+            return refused
+
         self.alissa.enqueue_reviewer(
             session=name,
             directive=directive,

{alissa_tools_github_revloop-0.31.16 → alissa_tools_github_revloop-0.31.18}/src/main/alissa/tools/github/revloop/parking.py

@@ -26,7 +26,9 @@ handshake):
   reads every null as a refusal.
 * **The drain.** A flag with a TTL in `state.db` (`State.set_drain`), cleared
   when the daemon boots. While it holds, the round spawn stands down before
-  its first side effect (`ReviewWatcher._drain_gated`).
+  its first side effect (`ReviewWatcher._drain_gated`), or, when the drain
+  lands while the hub is provisioned, after the hub add and before the
+  enqueue (the post-hub re-claim).
 """
 
 from __future__ import annotations

{alissa_tools_github_revloop-0.31.16 → alissa_tools_github_revloop-0.31.18}/src/main/alissa/tools/github/revloop/state.py

@@ -39,6 +39,8 @@ from collections.abc import Callable, Iterable
 from dataclasses import dataclass
 from pathlib import Path
 
+from .parking import SPAWN_CLAIM_TTL
+
 log = logging.getLogger(__name__)
 
 # Poll-snapshot retention: the newest N rows are kept, older ones pruned on
@@ -2067,11 +2069,12 @@ class State:
 
     def set_drain(
         self, ttl: int, reason: str, now: "float | None" = None,
-        claim_ttl: int = 600,
+        claim_ttl: int = SPAWN_CLAIM_TTL,
     ) -> "tuple[dict, list[dict]]":
         """Raise the drain flag for `ttl` seconds and return it with the spawn
-        claims standing at that instant (younger than `claim_ttl` -- an older
-        one is a spawn whose process died mid-way, cleared at the next boot).
+        claims standing at that instant (younger than `claim_ttl`, by default
+        `parking.SPAWN_CLAIM_TTL` -- an older one is a spawn whose process
+        died mid-way, cleared at the next boot).
         ONE immediate transaction, so a spawn either claimed before this (and
         is in the list) or claims after it (and sees the flag). A drain that
         is already up is replaced: a re-drain restarts the TTL. Raises

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

@@ -0,0 +1 @@
+0.31.18

{alissa_tools_github_revloop-0.31.16 → alissa_tools_github_revloop-0.31.18}/src/main/alissa/tools/github/revloop/webui/server.py

@@ -332,7 +332,9 @@ class App:
             cleared = self.sources.clear_drain()
         except sqlite3.Error as exc:
             self._audit("undrain", {"ok": False, "error": str(exc)})
-            return 503, {"drained": True, "error": "state_unavailable"}
+            # The flag's state is unknown here, and unknown is never a value
+            # (D2): the 503 already says the undrain did not land.
+            return 503, {"drained": None, "error": "state_unavailable"}
         self._audit("undrain", {"ok": True, "cleared": cleared})
         return 200, {"drained": False, "cleared": cleared}
 

{alissa_tools_github_revloop-0.31.16 → alissa_tools_github_revloop-0.31.18/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.16
+Version: 0.31.18
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera
@@ -46,6 +46,18 @@ The rule: a distribution owns a leaf package and declares only that subtree
 `__init__.py` at any namespace level would claim it for one distribution and
 shadow the others.
 
+## Discovery PRs are not reviewed
+
+A PR in a plans repository (`plan_repos`, `ALISSA_REVIEW_PLAN_REPOS`) whose
+body carries `<!-- alissa-discovery v1 -->` on a line of its own and whose
+every changed path is under `knowledge-base/` gets **no review round** — no
+reviewer session, no review task — and one activity-comment line per head
+saying why. A marked PR that touches anything else (or whose file list cannot
+be read in full) is reviewed under the code directive, unchanged. The fleet
+flag `discovery_review` (`ALISSA_REVIEW_DISCOVERY_REVIEW`, default off) turns
+the skip off: every discovery PR is then reviewed like any other. See
+*Discovery PRs* in the repository README.
+
 ## Install
 
 ```sh

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

@@ -1 +0,0 @@
-0.31.16