Merge branch 'main' into feat/bud-branch-overrides

Author: mickyarun

README.md

@@ -28,19 +28,11 @@ Self-hosted on your hardware. Your data stays local. Inference engine is your ch
 
 ### 📺 Watch the demo
 
-<a href="https://youtu.be/ot-BmKxRgRA"><img src="https://img.youtube.com/vi/ot-BmKxRgRA/maxresdefault.jpg" width="48%" alt="Setup walkthrough"></a>
-&nbsp;
-<a href="https://youtu.be/i8kZdcL1bME"><img src="https://img.youtube.com/vi/i8kZdcL1bME/maxresdefault.jpg" width="48%" alt="Slack triage & MCP tools"></a>
+<a href="https://youtu.be/OxoqBI7BNxU"><img src="https://img.youtube.com/vi/OxoqBI7BNxU/maxresdefault.jpg" width="80%" alt="Inside the virtual world"></a>
 
-<a href="https://youtu.be/YBwdTes0Fno"><img src="https://img.youtube.com/vi/YBwdTes0Fno/maxresdefault.jpg" width="48%" alt="Requirements & estimation"></a>
-&nbsp;
-<a href="https://youtu.be/lV71qhmfzzw"><img src="https://img.youtube.com/vi/lV71qhmfzzw/maxresdefault.jpg" width="48%" alt="Design phase & agent prompts"></a>
+**[▶ Inside the virtual world](https://youtu.be/OxoqBI7BNxU)** — the Living Tree, your org as a tended orchard.
 
-<a href="https://youtu.be/YjRihN_SKaw"><img src="https://img.youtube.com/vi/YjRihN_SKaw/maxresdefault.jpg" width="48%" alt="Development & retrospective"></a>
-&nbsp;
-<a href="https://youtu.be/OxoqBI7BNxU"><img src="https://img.youtube.com/vi/OxoqBI7BNxU/maxresdefault.jpg" width="48%" alt="Inside the virtual world"></a>
-
-**[Setup walkthrough](https://youtu.be/ot-BmKxRgRA)** &nbsp;·&nbsp; **[Slack triage & MCP tools](https://youtu.be/i8kZdcL1bME)** &nbsp;·&nbsp; **[Requirements & estimation](https://youtu.be/YBwdTes0Fno)** &nbsp;·&nbsp; **[Design phase & agent prompts](https://youtu.be/lV71qhmfzzw)** &nbsp;·&nbsp; **[Development & retrospective](https://youtu.be/YjRihN_SKaw)** &nbsp;·&nbsp; **[Inside the virtual world](https://youtu.be/OxoqBI7BNxU)**
+**More walkthroughs:** [Setup](https://youtu.be/ot-BmKxRgRA) &nbsp;·&nbsp; [Slack triage & MCP tools](https://youtu.be/i8kZdcL1bME) &nbsp;·&nbsp; [Requirements & estimation](https://youtu.be/YBwdTes0Fno) &nbsp;·&nbsp; [Design phase & agent prompts](https://youtu.be/lV71qhmfzzw) &nbsp;·&nbsp; [Development & retrospective](https://youtu.be/YjRihN_SKaw)
 
 ![Bodhiorchard Living Tree Dashboard](docs/images/livingtree.png)
 

backend/app/api/v1/bud.py

@@ -96,6 +96,7 @@
 from app.services.bud_assignment_actions import assign_bud, unassign_bud
 from app.services.bud_edit_policy import assert_section_editable
 from app.services.bud_estimation import estimate_bud_dates
+from app.services.bud_learning_alias_resolver import resolve_aliased_contributors
 from app.services.bud_timeline import record_event
 from app.services.job_queue import JOB_BUD_AGENT, create_job
 
@@ -544,7 +545,18 @@ async def get_bud_learning(
             status_code=status.HTTP_404_NOT_FOUND,
             detail="No learning recorded for this BUD yet",
         )
-    return BUDLearningRead.model_validate(learning)
+    read = BUDLearningRead.model_validate(learning)
+    # Apply the Settings → Members merge backlink to the stored
+    # contributor snapshot so deactivated / "(external)" rows fold into
+    # their currently-active target. The stored JSONB is left alone —
+    # the resolver runs on every fetch so later alias changes apply
+    # immediately without a backfill.
+    if read.metrics and read.metrics.get("contributors"):
+        contribs = await resolve_aliased_contributors(
+            db, current_user.org_id, read.metrics["contributors"]
+        )
+        read = read.model_copy(update={"metrics": {**read.metrics, "contributors": contribs}})
+    return read
 
 
 # Status transitions QA owns directly via PATCH. Matches the manual-testing

backend/app/api/v1/bud_prs.py

@@ -35,6 +35,7 @@
     ReleaseTimelineEvent,
 )
 from app.schemas.pull_request import PRChecklistItem, PullRequestRead
+from app.services.pr_auto_transition import pr_references_bud
 from app.utils.branch_matching import branch_matches
 
 router = APIRouter()
@@ -238,18 +239,31 @@ async def get_bud_release_stage(
         target_branch = bud_override or (
             (repo.uat_branch if typed_stage == "uat" else repo.main_branch) if repo else None
         )
-        if target_branch and branch_matches(pr.base_branch, target_branch):
-            seen_pr_ids.add(pr.github_pr_id)
-            open_prs.append(
-                ReleasePR(
-                    pr_number=pr.github_pr_number,
-                    repo_name=repo.name if repo else "",
-                    html_url=pr.html_url,
-                    title=pr.title,
-                    author_login=pr.author_github_login,
-                    merged_at=None,
-                ),
-            )
+        if not (target_branch and branch_matches(pr.base_branch, target_branch)):
+            continue
+        # Content guard for unlinked PRs (``bud_id IS NULL``): the
+        # release-PR fallback in the repository surfaces every PR
+        # targeting the stage branch on an impacted repo, but the
+        # release-stage tab must only show PRs that reference THIS BUD.
+        # ``pr_references_bud`` looks for ``bud-NNN`` in the head ref
+        # or title, so a release branch like
+        # ``release/bud-001-bud-004`` correctly appears on both BUD-001
+        # and BUD-004 tabs, while an unrelated PR to ``main`` does not
+        # leak through. Directly-linked PRs (``bud_id == bud_id``)
+        # short-circuit so the user-edited link wins over text matching.
+        if pr.bud_id != bud_id and not pr_references_bud(bud.bud_number, pr.head_branch, pr.title):
+            continue
+        seen_pr_ids.add(pr.github_pr_id)
+        open_prs.append(
+            ReleasePR(
+                pr_number=pr.github_pr_number,
+                repo_name=repo.name if repo else "",
+                html_url=pr.html_url,
+                title=pr.title,
+                author_login=pr.author_github_login,
+                merged_at=None,
+            ),
+        )
 
     return BUDReleaseStage(
         bud_id=str(bud_id),

backend/app/api/v1/learnings.py

@@ -29,7 +29,7 @@
 from fastapi import APIRouter, Depends
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.core.deps import get_current_user, get_db, require_permissions
+from app.core.deps import get_current_user, get_db
 from app.models.bud import BUDDocument
 from app.models.user import User
 from app.repositories.learnings_overview import LearningsOverviewRepository
@@ -188,10 +188,14 @@ def _build_top_contributors(
     ]
 
 
+# Intentionally no permission gate: every org member sees the org-wide
+# retrospective. The response is aggregate-only (velocity buckets, phase
+# drift, contributor leaderboard) and the repo is scoped to
+# current_user.org_id. If you ever add admin-only fields to
+# LearningsOverviewRead, re-introduce a require_permissions dependency.
 @router.get(
     "/overview",
     response_model=LearningsOverviewRead,
-    dependencies=[Depends(require_permissions("org:view_settings"))],
 )
 async def get_learnings_overview(
     current_user: User = Depends(get_current_user),

backend/app/mcp/handlers_hooks.py

@@ -21,7 +21,6 @@
 
 import asyncio
 import os
-import re
 import uuid
 
 import structlog
@@ -35,12 +34,15 @@
 from app.schemas.dev_activity import DevActivityHookRequest, DevActivityHookResponse
 from app.services.colyseus_bridge import publish_to_colyseus
 from app.services.event_bus import publish
+from app.services.pr_auto_transition import extract_bud_number
 from app.services.user_resolution import resolve_user_by_email
 from app.services.xp_service import check_and_award_streak
 
 logger = structlog.get_logger(__name__)
 
-_BUD_BRANCH_RE = re.compile(r"^bud-(\d+)/")
+# BUD number extraction is owned by ``pr_auto_transition.extract_bud_number``
+# so a single matcher governs PR linking, the dev-activity hook below, and any
+# future reuse — keeping branch heuristics from drifting between call sites.
 
 # Strong references to in-flight Colyseus publish tasks. ``asyncio.create_task``
 # only holds a weak reference to the task it returns, so without an external
@@ -297,13 +299,11 @@ async def _resolve_bud(
             return bud.id, bud.bud_number
 
     # Auto-detect from branch name: bud-001/feature → 1
-    if branch:
-        match = _BUD_BRANCH_RE.match(branch)
-        if match:
-            detected_num = int(match.group(1))
-            bud = await bud_repo.get_by_number(detected_num)
-            if bud:
-                return bud.id, bud.bud_number
+    detected_num = extract_bud_number(branch)
+    if detected_num is not None:
+        bud = await bud_repo.get_by_number(detected_num)
+        if bud:
+            return bud.id, bud.bud_number
 
     return None, None
 

backend/app/repositories/pull_request.py

@@ -17,7 +17,7 @@
 import uuid
 from datetime import datetime
 
-from sqlalchemy import func, or_, select
+from sqlalchemy import and_, func, or_, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.models.pull_request import PRState, PullRequest
@@ -172,22 +172,40 @@ async def list_open_for_bud_with_repo(
     ) -> list[tuple[PullRequest, TrackedRepository | None]]:
         """List open PRs for a BUD joined with their tracked repository.
 
-        When ``impacted_repo_ids`` is provided, the result includes any open
-        PR that is either linked to ``bud_id`` directly OR targets one of
-        the impacted repos. Used by release-stage views that need to surface
-        open PRs in repos affected by the BUD even if the PR forgot to set
-        a ``bud_id``.
+        Three-way predicate so the release-stage views (UAT / PROD tabs)
+        only surface PRs that genuinely relate to ``bud_id``:
+
+        * ``bud_id == X`` — the PR is directly linked to this BUD.
+        * ``bud_id IS NULL AND repo_id IN impacted_repo_ids`` — aggregate
+          release PRs like ``develop → main`` legitimately carry no single
+          owning BUD; we keep them visible on the impacted repo's stage tab
+          because the SHA-walk in the release detector uses them to attribute
+          merges back to multiple BUDs.
+
+        A plain ``OR(bud_id == X, repo_id IN impacted)`` would also let
+        through PRs linked to a **different** BUD that happens to touch the
+        same impacted repo — which is the over-matching bug this method now
+        prevents.
 
         Args:
             bud_id: The BUD UUID to filter on.
-            impacted_repo_ids: Additional repo UUIDs to include open PRs for.
+            impacted_repo_ids: Repo UUIDs whose unlinked release PRs should
+                stay visible. When ``None`` / empty, only directly-linked
+                PRs are returned.
 
         Returns:
             List of ``(PullRequest, TrackedRepository | None)`` tuples.
         """
-        filters = [PullRequest.bud_id == bud_id]
         if impacted_repo_ids:
-            filters.append(PullRequest.repo_id.in_(impacted_repo_ids))
+            bud_predicate = or_(
+                PullRequest.bud_id == bud_id,
+                and_(
+                    PullRequest.bud_id.is_(None),
+                    PullRequest.repo_id.in_(impacted_repo_ids),
+                ),
+            )
+        else:
+            bud_predicate = PullRequest.bud_id == bud_id
 
         stmt = self._scoped(
             select(PullRequest, TrackedRepository)
@@ -198,7 +216,7 @@ async def list_open_for_bud_with_repo(
             )
             .where(
                 PullRequest.state == PRState.OPEN,
-                or_(*filters),
+                bud_predicate,
             )
         )
         result = await self._db.execute(stmt)

backend/app/repositories/user.py

@@ -18,6 +18,7 @@
 from typing import Any
 
 from sqlalchemy import Select, and_, case, func, or_, select, true
+from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import aliased
 
@@ -711,6 +712,72 @@ async def add_email_alias(
         self._db.add(alias)
         return alias
 
+    async def create_stub_member(
+        self,
+        org_id: uuid.UUID,
+        *,
+        email: str,
+        name: str,
+        github_username: str,
+        password_hash: str,
+    ) -> User:
+        """Insert a stub User + ``OrgToUser`` membership in one shot.
+
+        Used to surface GitHub PR authors who don't yet have an account
+        so admins can merge them into a real member via Settings →
+        Members. Caller chooses ``password_hash`` — typically a random
+        bcrypt-hashed string so the account cannot authenticate.
+
+        Concurrent BUD closures may race on the same unknown
+        ``email`` — the insert is wrapped in a SAVEPOINT and, on the
+        ``uq_users_email`` violation, the loser re-fetches the winning
+        row instead of poisoning the outer transaction.
+        """
+        try:
+            async with self._db.begin_nested():
+                user = User(
+                    email=email,
+                    name=name,
+                    password_hash=password_hash,
+                    github_username=github_username,
+                    is_active=True,
+                )
+                self._db.add(user)
+                await self._db.flush()
+                self._db.add(OrgToUser(user_id=user.id, org_id=org_id))
+                await self._db.flush()
+            return user
+        except IntegrityError:
+            existing = await self.get_by_email_in_org(org_id, email)
+            if existing is None:
+                raise
+            return existing
+
+    async def find_user_by_alias_email(self, org_id: uuid.UUID, email: str) -> User | None:
+        """Return the user who has ``email`` listed as a UserEmailAlias.
+
+        Walks one hop of the Settings → Members merge backlink: when
+        member B is merged into A, B's primary email is recorded as an
+        alias on A. Given B's email, this returns A.
+
+        Returns the immediate target without filtering on ``is_active``
+        so multi-hop chains (A → B → C) can be traversed externally;
+        callers that need a guaranteed-active user must loop until
+        ``user.is_active`` is true.
+        """
+        if not email:
+            return None
+        result = await self._db.execute(
+            select(User)
+            .join(UserEmailAlias, UserEmailAlias.user_id == User.id)
+            .where(
+                UserEmailAlias.org_id == org_id,
+                UserEmailAlias.email == email,
+            )
+            .limit(1)
+        )
+        return result.scalar_one_or_none()
+
     async def list_aliases(self, user_id: uuid.UUID) -> list[UserEmailAlias]:
         """List all email aliases for a user.
 

backend/app/services/bud_closure.py

@@ -81,8 +81,14 @@ async def on_bud_closed(
     await _award_bud_shipped_sp(db, org_id, bud)
 
     if bud.status == BUDStatus.CLOSED:
+        # SAVEPOINT so a metrics-compute failure rolls back any side
+        # effects the compute introduced (stub members materialised by
+        # the contributor breakdown's PR-author provisioner,
+        # author_user_id backfills, the FeatureLearning upsert itself)
+        # without poisoning the outer close-handler transaction.
         try:
-            await compute_bud_metrics(db, org_id, bud)
+            async with db.begin_nested():
+                await compute_bud_metrics(db, org_id, bud)
         except Exception:
             logger.warning(
                 "bud_metrics_compute_failed",