prd-01 — upstream intelligence: Buzz keeps the cohort aware of upstream

[tucktuck101]

Problem

block/buzz moves quickly enough that the Launchpad cohort cannot reasonably maintain useful awareness of upstream changes by watching commits alone.

Relevant information is fragmented across relay, desktop and mobile changelogs, releases, compare views, PRs, issues and CI. The relay is especially important because it is the component we operate, but a single relay release can span hundreds of repository commits.

Today, answering simple questions such as:

• What changed upstream?
• What has actually been released?
• What matters to our deployment?
• Is upstream already working on something we are considering?
• What should we look at before updating our fork?

requires someone to manually gather and synthesise information from several GitHub surfaces.

As launchpad-26/buzz diverges further, Git mergeability also stops being an adequate measure of upgrade safety. A change can merge cleanly while still affecting configuration, infrastructure, data, security or behaviour.

Buzz should help the cohort understand the Buzz project it is derived from.

Evidence

Upstream already provides useful but separate sources of truth:

• Relay changelog — crates/buzz-relay/CHANGELOG.md; the deployable server component.
• Desktop changelog — CHANGELOG.md.
• Mobile changelog — mobile/CHANGELOG.md.
• GitHub releases — published desktop and mobile builds.
• Compare views — the clearest mechanical record of what changed between release tags.
• Issues and PRs — active defects, planned work, implementation context and emerging product direction.
• CI/build state — whether upstream currently believes a change works.

For scale, relay-v0.2.0...relay-v0.2.1 spans 840 commits. Individual commit notification is therefore noise, not situational awareness.

The Launchpad fork is also beginning to establish its own deployment and product context. That creates a future need to understand upstream changes relative to our deployed version and local work rather than in isolation.

Success criteria

A cohort member using Buzz can quickly understand meaningful upstream activity without manually inspecting the upstream repository.

The first useful version proves this when Buzz can:

1. detect meaningful upstream release/change activity;
2. gather evidence from the appropriate upstream sources;
3. reduce low-value activity such as repetitive dependency churn;
4. synthesise the remaining information into a concise human-readable update;
5. publish that update into a designated Buzz channel; and
6. preserve links back to GitHub so claims can be verified at the source.

• A new upstream relay release tag is detected without anyone watching the repo manually
• Evidence is gathered from the relevant upstream sources (relay/desktop/mobile changelogs, releases, compare view, linked PRs and issues)
• Repetitive dependency churn is demonstrably reduced — a report covering a release with hundreds of dependency commits does not list them individually
• The result is a single human-readable update, not a commit list
• The update is published into a designated Buzz channel automatically
• Every claim in the update carries a link back to its GitHub source, and those links resolve
• The published report answers all four questions: what changed, which part of Buzz changed, why we might care, what to inspect for detail

A useful report should answer:

What changed?
Which part of Buzz changed?
Why might we care?
What should someone inspect if they want more detail?

Example:

Upstream — Relay v0.2.2

Major themes: authentication, agent infrastructure and observability.

🔐 Security — authentication behaviour changed
⚙️ Operations — new deployment configuration
🤖 Agents — managed-agent functionality changed

Launchpad relevance: Relay/deployment related; worth reviewing before our next upstream update.

Sources: relay changelog · compare · relevant PRs/issues

Success does not require Buzz to decide whether we should upgrade.

Non-goals

For this PRD:

• No automatic merging from block/buzz.
• No automatic deployment or upgrading of the Launchpad environment.
• No autonomous approval of upstream changes.
• No claim that LLM-generated analysis is authoritative.
• No requirement to analyse every commit individually.
• No replacement of GitHub as the source of truth.
• No full compatibility or upgrade-risk engine yet.
• No requirement to resolve upstream issues from the Launchpad fork.
• No requirement for Discord to become a second full user interface.

This PRD is about awareness and synthesis inside Buzz, not autonomous change management.

Impacted components

launchpad/upstream-intel/   collection, reduction and synthesis tooling
.github/workflows/          scheduled trigger (launchpad-* prefix)
Buzz channel                publication target for the report — channel not yet chosen
upstream sources (read)     crates/buzz-relay/CHANGELOG.md, CHANGELOG.md,
                            mobile/CHANGELOG.md, GitHub releases, compare views, PRs/issues

Security implications

Draft — agent-inferred from the rulings above, not authored by a human. Correct or replace before relying on it.

• Synthesis sends upstream repository content to an LLM provider. All of it is public
  (block/buzz is a public repo), so no confidential data leaves the boundary — but the
  provider choice and any API credential become part of this repo's security surface.
  Credentials must live in Actions secrets or an Environment, never in tracked files.
• Reports are generated text published into a Buzz channel. Ruling 3 (traceability to
  source evidence) is the control that keeps a fabricated claim detectable — provenance
  links are a security property here, not a nicety.
• Read-only against upstream. This capability observes block/buzz; it neither writes
  to it nor merges from it (see Non-goals). No write credential to upstream is required.
• The scheduled workflow needs no repository write access beyond publishing its report,
  and should declare minimal permissions: explicitly rather than inheriting defaults.

Rulings

Ruling 1 — upstream intelligence is a Buzz capability

The primary user experience lives inside the class Buzz environment.

Buzz should be capable of reporting meaningful upstream activity into a designated channel and, as the capability matures, answering questions about that upstream state.

This is product functionality in launchpad-26/buzz, not an unrelated external monitoring bot.

Ruling 2 — Buzz reports changes at meaningful product boundaries, not commit frequency

Relay, desktop and mobile are treated as distinct upstream product/release streams.

Release tags, changelogs and compare boundaries form the primary units of analysis. Commits, changed files, PRs and issues provide supporting evidence.

A burst of fifty commits does not imply fifty notifications.

Ruling 3 — upstream claims remain traceable to source evidence

LLM synthesis may explain and compress upstream information, but it must not become the source of truth.

Reports retain links or identifiers for the changelogs, releases, compare views, PRs and issues from which their conclusions were produced.

A cohort member must be able to move from:

summary → evidence

without searching for the evidence again.

Ruling 4 — collection and factual reduction happen before LLM synthesis

The model is not responsible for discovering basic Git facts that can be determined mechanically.

Buzz first gathers and structures information such as:

• versions and tags;
• changelog entries;
• changed components and paths;
• relevant PRs;
• issues;
• release state;
• CI state; and
• obvious maintenance/dependency activity.

LLM inference is then used for semantic tasks such as classification, summarisation, correlation and explaining why changes may matter.

The intent is to use reasoning where reasoning adds value rather than feeding an uncontrolled repository-sized context to a model.

Ruling 5 — synthesis is provider/model configurable

The upstream-intelligence capability must not depend on one specific inference model.

The MVP may use OpenRouter as the inference path, allowing an appropriate model to be selected for cost and reasoning quality without changing the product behaviour.

Detailed provider boundaries and implementation contracts belong in an ADR if they become architectural commitments.

Ruling 6 — Discord is an out-of-band fallback, not the primary product

Important upstream notifications may additionally be delivered to Discord.

This exists so that awareness of Buzz releases or failures does not depend entirely on the class Buzz deployment being healthy.

Buzz remains the primary interface; Discord is the independent fallback path.

Ruling 7 — fork-aware intelligence is the next maturity step, not part of the MVP

Once the Launchpad fork contains meaningful local divergence, upstream evidence can be evaluated against:

• our currently deployed upstream version;
• local code changes;
• deployment and infrastructure configuration;
• Launchpad issues;
• planned work;
• tests and CI state.

This enables advisory analysis of the difference between Git merge risk and operational upgrade risk.

For example:

Git merge risk: LOW
Deployment risk: HIGH
Behavioural risk: MEDIUM
Feature overlap: LOW
Security urgency: HIGH

A clean merge must never be presented as proof of a safe upgrade.

Ruling 8 — the capability matures incrementally

The intended progression is:

1. Upstream awareness — detect, synthesise and publish meaningful upstream activity inside Buzz.

2. Upstream intelligence — correlate releases, changelogs, PRs, issues, compare data and CI.

3. Fork awareness — understand our deployed version and local divergence.

4. Upgrade intelligence — provide advisory compatibility and risk analysis.

5. Interactive upstream ChatOps — answer questions such as:

   • @upstream what changed this week?
   • @upstream what changed since our relay version?
   • @upstream does upstream overlap with anything we are building?
   • @upstream why is this upgrade considered risky?

Only the first maturity step is required to satisfy this PRD.

Open questions

• What event should trigger the first MVP report: a new release/tag, scheduled polling, or both?
• Should Phase 1 cover all three product streams immediately, or start with the relay because that is what we deploy?
• What level of issue/PR activity is significant enough to surface outside a release?
• Where should generated upstream reports persist so later questions can reason over historical change rather than re-fetching everything?
• What minimum Discord fallback is sufficient: release alerts only, or the same digest sent to Buzz?
• What parts of provider/model configuration should become an ADR rather than remain implementation detail?

[tucktuck101]

All six open questions in this PRD have been raised as ADR issues and parented here, per the
convention added to launchpad/AGENTS.md in #14: a PRD's open questions become ADR issues rather
than staying in the body, where they get decided by accident inside whichever task hits them first.

ADR	Question
#48	What event triggers the first MVP report
#49	Whether Phase 1 covers all three product streams or starts with the relay
#50	What level of issue/PR activity is significant outside a release
#51	Where generated reports persist
#52	The minimum Discord fallback
#53	What provider/model configuration becomes an ADR

All six are open with their outcome blank — no human has decided them.

Two findings from drafting that bear on this PRD directly, both verified against the GitHub API:

• block/buzz publishes no GitHub Release for the relay. GET /repos/block/buzz/releases/tags/relay-v0.2.1 returns 404. Relay versions exist only as git tag refs. A detector built on the Releases API would never fire for the component this cohort actually operates.
• There are 840 commits between relay-v0.2.0 and relay-v0.2.1, which is the concrete case for reporting at release boundaries rather than per commit.

#53 was reshaped: the question as written is meta ("what should become an ADR"), so it is drafted as the substantive decision underneath it — the inference provider boundary and how its credential is handled.

_{Comment by an AI agent (Claude Opus 5) on behalf of @tucktuck101.}