alissa-tools-github-devloop 0.8.4__tar.gz → 0.8.5__tar.gz

{alissa_tools_github_devloop-0.8.4/src/main/alissa_tools_github_devloop.egg-info → alissa_tools_github_devloop-0.8.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-devloop
-Version: 0.8.4
+Version: 0.8.5
 Summary: ALISSA-TOOLS-GITHUB-DEVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_devloop-0.8.4 → alissa_tools_github_devloop-0.8.5}/src/main/alissa/tools/github/devloop/ghclient.py

@@ -135,6 +135,17 @@ class PullRequest:
     # instant that window runs from. Defaulted for the same reason as node_id:
     # the three spawn edges never ask, and neither do their fakes.
     closed_at: "int | None" = None
+    # The branch this PR would merge INTO (`base.ref`). Carried for the
+    # stacked-base guard: a PR based on a sibling task's branch rather than on
+    # the repository's default branch strands its diff the moment that parent
+    # merges -- GitHub retargets the child, the child merges into a branch that
+    # is no longer anywhere, and the PR reads "merged" while the default branch
+    # never receives the work (fahera-mx/studio.alissa.app#330/#333/#334).
+    # Empty when the payload carried no readable base: that reads as UNKNOWN,
+    # never as a mismatch, so a thin payload can never page an operator about a
+    # base nobody observed. Defaulted like node_id and closed_at -- the edges
+    # that only spawn never ask.
+    base_ref: str = ""
 
     @property
     def full_name(self) -> str:
@@ -160,6 +171,7 @@ def _pull_request_from(
     the listing reads it from each entry.
     """
     head = data.get("head") or {}
+    base = data.get("base") or {}
     # Users carry `login`, teams `slug`; both hold the review-response edge
     # closed -- a pending TEAM re-request still means the ball is in a
     # reviewer's court, so it must not read as "awaiting the author".
@@ -188,6 +200,7 @@ def _pull_request_from(
         requested_reviewers=requested,
         node_id=data.get("node_id") or "",
         closed_at=parse_github_timestamp(data.get("closed_at")),
+        base_ref=base.get("ref") or "",
     )
 
 
@@ -316,6 +329,10 @@ def _is_rate_limited(exc: proc.CommandError) -> bool:
 class GitHub:
     def __init__(self, login: str | None = None):
         self._login = login
+        # Memoised `default_branch()` answers, keyed (owner, repo). See that
+        # method for why a repository's default branch is cached for the
+        # process lifetime while `pull_request()` deliberately is not.
+        self._default_branches: "dict[tuple[str, str], str]" = {}
 
     def token_login(self) -> str:
         """Who the gh token actually belongs to. `gh api --jq` prints scalars
@@ -672,6 +689,36 @@ class GitHub:
         data = self._api(f"repos/{owner}/{repo}/pulls/{number}") or {}
         return _pull_request_from(data, owner, repo, number=number)
 
+    def default_branch(self, owner: str, repo: str) -> str:
+        """The repository's default branch, as GitHub reports it.
+
+        The stacked-base guard's reference point, and it is FETCHED rather than
+        assumed: `main` is a convention, not a fact. Forks keep whatever the
+        upstream had, repositories created before 2020 default to `master`, and
+        a house style of `develop` is ordinary -- comparing a PR's base against
+        a hardcoded literal would page every operator on such a repo about
+        every correctly-based PR, which is worse than the failure it guards.
+        Empty when the payload carries no readable `default_branch`; the guard
+        reads that as UNKNOWN and stands down, never as a mismatch.
+
+        MEMOISED for the process lifetime, keyed (owner, repo). Unlike
+        `pull_request()` -- deliberately uncached, because draft state and
+        review requests change under the daemon by the minute -- a default
+        branch is quasi-immutable: it changes on a deliberate repository-
+        settings edit, which is rare and operator-driven. Without the memo this
+        would be one extra GET per own open PR per poll, forever, on a
+        comparison whose answer never moves. The stale window a rename opens is
+        bounded and cheap: until the daemon restarts, PRs based on the NEW
+        default read as stacked and each raises its one advisory comment --
+        noisy, never an action, and the guard performs no remediation by
+        design.
+        """
+        key = (owner, repo)
+        if key not in self._default_branches:
+            data = self._api(f"repos/{owner}/{repo}") or {}
+            self._default_branches[key] = data.get("default_branch") or ""
+        return self._default_branches[key]
+
     def branch_pulls(
         self, owner: str, repo: str, head_ref: str
     ) -> "tuple[PullRequest, ...]":

{alissa_tools_github_devloop-0.8.4 → alissa_tools_github_devloop-0.8.5}/src/main/alissa/tools/github/devloop/loop.py

@@ -503,6 +503,30 @@ _FIX_DELIVERY_NOTE = (
     + _DELIVERY_NOTE_SECTIONS
 )
 
+# The base-branch rule (issue #78) -- the prevention half of the stacked-base
+# guard, whose detection half pages an operator after the fact. A worker whose
+# task depends on a sibling task's unmerged work is tempted to open its PR ON
+# that branch, and the temptation is reasonable: it makes the diff readable.
+# What it actually does is strand the work. When the parent merges first,
+# GitHub retargets the child onto a branch nothing reads any more; the child
+# then merges into that detached branch and reports success while the default
+# branch never receives the diff (fahera-mx/studio.alissa.app#330/#333/#334 --
+# re-landed by hand as a cherry-pick). The rule names the DEFAULT BRANCH rather
+# than `main` for the same reason the daemon-side check reads it from the API:
+# `main` is a convention, and a worker on a repo defaulting to `master` or
+# `develop` would follow the letter of a `main` rule straight into the failure.
+_DEFAULT_BASE = (
+    "One rule about the PR's BASE: open it against the repository's DEFAULT "
+    "branch (`gh repo view --json defaultBranchRef` if you are unsure) and "
+    "never against another task's branch. Basing on a sibling task's branch to "
+    "make your diff read cleanly is how work gets silently stranded: when that "
+    "parent merges first, GitHub retargets your PR onto a branch nothing reads "
+    "any more, your merge reports success, and the diff never reaches the "
+    "default branch. If your work depends on another task's, say so in the PR "
+    "body and let the operator sequence the merges — ordering between tasks is "
+    "release gating's job, not the PR graph's. "
+)
+
 # The approve-verdict rule (issue #68). An APPROVE hands the branch to the
 # operator, who may merge it the very next second -- observed live on
 # fahera-mx/studio.alissa.app#275: round 4 approved with three [minor]s
@@ -513,7 +537,9 @@ _FIX_DELIVERY_NOTE = (
 # The remedy is a rule about WHERE the work goes, not about how fast the worker
 # is: after an approve the branch is merge-racy BY DEFINITION, so no amount of
 # hurrying makes a push to it safe. Approval-attached [pursue] findings become a
-# fresh branch off main and a follow-up PR -- exactly the recovery that incident
+# fresh branch off the DEFAULT branch (issue #78: not off the approved branch,
+# and not off a sibling task's) and a follow-up PR -- exactly the recovery that
+# incident
 # improvised, made the FIRST move instead of the fallback -- and that PR gets
 # driven to a completed handoff in the same session, because a follow-up nobody
 # reviews is the orphan-draft half of this same issue.
@@ -527,8 +553,10 @@ _APPROVE_FOLLOWUP = (
     "branch. An approved branch is merge-racy by definition: the operator may "
     "merge it at any moment, and a commit pushed after the squash-merge is "
     "silently lost. Findings attached to an approve that you triage "
-    "`[pursue]` are implemented as a NEW branch off main and a FOLLOW-UP pull "
-    "request — never as another push to the approved branch — whose body names "
+    "`[pursue]` are implemented as a NEW branch off the repository's DEFAULT "
+    "branch (never off the approved branch, and never off another task's "
+    "branch) and a FOLLOW-UP pull request opened against that same default "
+    "branch — never as another push to the approved branch — whose body names "
     "the source PR and review round plus BOTH task refs (origin + "
     "implementation), and you drive that follow-up's handoff to completion in "
     "THIS session (ready + review re-request), never leaving it a draft. "
@@ -562,6 +590,7 @@ DEV_DIRECTIVE = (
     "AND your implementation task: the PR body is the canonical cross-actor "
     "record, and each actor's tasks live in its own partition — and attach "
     "the PR URL to the task as evidence. "
+    + _DEFAULT_BASE
     + _DELIVERY_NOTE
     + " Then drive the review handoff with "
     "the alissa-pr-review skill, requesting reviewer(s): {reviewers}. In "
@@ -857,6 +886,23 @@ ORPHAN_REJECTED_COMMENT = (
     "park the work."
 )
 
+STACKED_BASE_COMMENT = (
+    "**Dev loop: this pull request is not based on the default branch** — it "
+    "targets `{base}`, but `{full_name}`'s default branch is `{default}`. A PR "
+    "stacked on another task's branch strands its own work: when the parent "
+    "merges, GitHub retargets this PR onto a branch that no longer receives "
+    "anything, the merge reports success, and the diff never reaches "
+    "`{default}` (fahera-mx/studio.alissa.app#330 / #333 / #334 — the work had "
+    "to be re-landed by hand as a cherry-pick). The daemon has changed "
+    "NOTHING: retargeting a PR after its parent merged silently widens the "
+    "diff to everything the parent carried, so the disposition is yours. "
+    "Operator options: retarget this PR to `{default}` while the parent is "
+    "still open (`gh pr edit {number} --base {default}`), or let it merge into "
+    "the parent knowing the work lands only when the parent does, or close it "
+    "and re-open the branch against `{default}`. Ordering between tasks "
+    "belongs to release gating, not to the PR graph."
+)
+
 ASSIGNMENT_REJECTED_COMMENT = (
     "**Dev loop cannot start** — the daemon tried to self-assign this issue "
     "as its in-flight marker, but GitHub silently dropped the assignment: "
@@ -1004,6 +1050,19 @@ ESCALATION_ORPHAN = "orphan"
 ESCALATION_ORPHAN_READY = "orphan-ready"
 ESCALATION_ORPHAN_REJECTED = "orphan-rejected"
 
+# The stacked-base guard's operator page (issue #78). Keyed on the BARE kind --
+# once per PR for its whole life, not per head and not per base -- because the
+# page describes the PR's SHAPE, not an event on it: a mismatched base is one
+# standing condition with one operator decision behind it, and re-paging every
+# time the head moves would turn a structural warning into a per-push nag on a
+# PR whose operator is already engaged. The cost of the bare key is stated
+# rather than hidden: a PR retargeted from one non-default branch to another
+# does not page again, which is the right trade when the first page already
+# named the default branch and the risk. The `stacked-` prefix keeps these rows
+# from colliding with any issue-edge kind when an issue and a PR share a
+# number, like every other PR-side kind here.
+ESCALATION_STACKED_BASE = "stacked-base"
+
 # CR6 verdict words, spelled exactly as reviewloop's alissa.py spells them --
 # the envelope tie-breaker (see DevWatcher.envelope_verdict) must return
 # these strings, so the two daemons read one vocabulary.
@@ -2712,6 +2771,14 @@ class DevWatcher:
             pr = self.github.pull_request(issue.owner, issue.repo, int(tail))
             if pr.state != "open":
                 continue  # closed between the timeline walk and now
+            # The issue edge's own first sight: this is where a linked open PR
+            # is admitted into the daemon's evaluation, and the stacked-base
+            # guard rides the fetch that already happened. Placed ABOVE the
+            # resumability tests on purpose -- a PR that is not a resume
+            # candidate (handed off, foreign-shaped, another task's work) is
+            # still a PR whose base can strand it, and the guard's own author
+            # test is what keeps it off PRs that are not ours.
+            self._check_stacked_base(pr)
             if not pr.draft or pr.requested_reviewers:
                 log.info(
                     "%s: %s has been handed off (draft=%s, reviewers=%s) — "
@@ -2987,6 +3054,16 @@ class DevWatcher:
         if pr.state != "open":
             return Decision(Action.SKIPPED, "PR closed between search and fetch")
 
+        # FIRST SIGHT of an own open PR on this edge -- the earliest moment the
+        # daemon holds a fetched PR object, and therefore where the stacked-base
+        # guard belongs. Deliberately ABOVE the draft split: with the orphan
+        # sweep on (the default) the search returns drafts, so a PR opened
+        # against a sibling task's branch is paged on the first poll after it is
+        # opened, while retargeting is still free. It is advisory only -- it
+        # changes nothing about the decision below it, which is why its return
+        # value is not consulted here.
+        self._check_stacked_base(pr)
+
         # A draft is out of review by definition (same belt-and-braces as
         # reviewloop's CR1 re-check -- a PR can flip back to draft between
         # search and fetch even when the search excluded drafts). It is also
@@ -4410,6 +4487,102 @@ class DevWatcher:
             task_ref=task_ref,
         )
 
+    def _check_stacked_base(self, pr: PullRequest) -> bool:
+        """Page the operator ONCE when an own open PR is not based on the
+        repository's default branch. Returns whether the page was raised.
+
+        The 2026-07-30 studio incident in one line: a worker opened its PR with
+        base `TASK-1628865936-FORMS-T5` -- its parent task's branch -- instead
+        of the default branch. The parent merged first; GitHub retargeted the
+        child onto a branch nothing reads any more; the child then "merged"
+        into that detached branch, so the PR showed merged, the default branch
+        never received the diff, and the daemon's own accounting degraded to
+        "attempt has opened no pull request" (a PR merged into a branch is
+        invisible to its issue's edge). The work had to be re-landed by hand.
+
+        This guard is ADVISORY BY CONSTRUCTION. It comments and returns; it
+        never retargets, closes, parks, or changes what the calling edge
+        decides. Retargeting is the tempting remedy and the wrong one: after
+        the parent has merged, moving the base to the default branch re-opens
+        the diff against a different merge-base and silently widens the PR to
+        everything the parent carried. Which of the three dispositions is right
+        depends on facts only a human has, so the daemon states the risk and
+        stops.
+
+        Timing is the whole point: the page fires on FIRST SIGHT -- the first
+        poll on which any edge fetches the PR -- because every remedy is cheap
+        while the parent is still open and expensive afterwards. A check at
+        merge time would always be too late.
+
+        Three guards below it, all fail-safe:
+
+        * the PR must be OURS (`author == login`). The callers reach here with
+          own PRs by construction (`author:@me` search, and the resume probe
+          re-checks), but a foreign PR's base is a foreign author's business
+          and this must never comment on one;
+        * a base or a default branch that reads EMPTY is UNKNOWN, not a
+          mismatch. A thin payload, a repository fetch that came back without
+          `default_branch` -- neither is evidence of anything, and paging on
+          absent data is how a guard teaches operators to ignore it;
+        * the ledger row is checked BEFORE the default-branch fetch, so a PR
+          already paged costs nothing further per poll -- the steady state for
+          a stacked PR that the operator has decided to let ride.
+
+        Delivery contract: the row lands only AFTER the comment posts (the
+        stalled pings' contract, not the cap-outs'). This page is the only
+        signal an operator gets for a condition that is otherwise invisible,
+        and nothing else in the system will ever raise it again, so a transient
+        POST failure must retry on the next poll rather than be recorded as
+        delivered. Dry-run logs and records nothing, like every other page.
+        """
+        if pr.author != self.github.login:
+            return False
+        if not pr.base_ref:
+            return False  # no readable base: unknown, never a mismatch
+        if self.state.escalated(
+            pr.full_name, pr.number, ESCALATION_STACKED_BASE
+        ):
+            return False
+        default = self.github.default_branch(pr.owner, pr.repo)
+        if not default or pr.base_ref == default:
+            return False
+
+        log.error(
+            "STACKED BASE %s: the PR targets %r but %s's default branch is "
+            "%r — a PR based on another task's branch strands its work when "
+            "that parent merges; paging the operator on the PR (the daemon "
+            "changes nothing: the disposition is the operator's)",
+            pr.pr_slug,
+            pr.base_ref,
+            pr.full_name,
+            default,
+        )
+
+        body = STACKED_BASE_COMMENT.format(
+            base=pr.base_ref,
+            default=default,
+            full_name=pr.full_name,
+            number=pr.number,
+        )
+        if self.config.dry_run:
+            log.info("[dry-run] would comment on %s:\n%s", pr.pr_slug, body)
+            return False
+
+        try:
+            self.github.comment(pr.owner, pr.repo, pr.number, body)
+        except CommandError as exc:
+            log.error(
+                "could not post the stacked-base comment on %s: %s — not "
+                "recording the page; it retries next poll",
+                pr.pr_slug,
+                exc,
+            )
+            return False
+        self.state.record_escalation(
+            pr.full_name, pr.number, ESCALATION_STACKED_BASE
+        )
+        return True
+
     def _escalate_fix_cap(self, pr: PullRequest, round_: int, attempts: int) -> None:
         """Operator page for a fix cap-out, posted ON the PR (the issue
         edge's _escalate shape): log, comment (dry-run gated), and record

alissa_tools_github_devloop-0.8.5/src/main/alissa/tools/github/devloop/version

@@ -0,0 +1 @@
+0.8.5

{alissa_tools_github_devloop-0.8.4 → alissa_tools_github_devloop-0.8.5/src/main/alissa_tools_github_devloop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-devloop
-Version: 0.8.4
+Version: 0.8.5
 Summary: ALISSA-TOOLS-GITHUB-DEVLOOP
 Home-page: https://alissa.app
 Author: Fahera

alissa_tools_github_devloop-0.8.4/src/main/alissa/tools/github/devloop/version

@@ -1 +0,0 @@
-0.8.4