## Summary
- make `VISION.md`, relevant `VISION_*.md`, and applicable testing
guides explicit planning and review inputs for non-trivial Buzz changes
- teach managed agents to load repository-root and path-local
`AGENTS.md` files after selecting a checkout
- distinguish CI evidence from exercising the live workflow for
user-visible and integration behavior
- turn repeatable mistakes into same-session durable lessons, keeping
only load-bearing rules in core memory and promoting shared lessons to
team guidance
- pin the new managed-agent prompt invariants in tests
- preserve the exact display name shown in Buzz when mentioning or
addressing someone; never infer or look up a surname merely to sound
more complete
### Related issue
None found after searching `block/buzz` issues and PRs for agent
instruction, vision, and product-intent routing.
### Testing
At commit `07ef705b42f58d3be6981165c6959d541ada0ba7`:
- `cargo fmt --all -- --check`
- `cargo test -p buzz-acp agent_draft_prompt_tests` (4 passed)
- mandatory pre-push hooks passed on the exact pushed head:
`branch-skew`, `desktop-check`, `desktop-typecheck`, `mobile-test`,
`desktop-test`, `rust-tests`, and `desktop-tauri-checks`
- `git diff --check origin/main...HEAD`
---------
Signed-off-by: Wes <wesbillman@users.noreply.github.com>
Co-authored-by: Carl <c7ebe626f000404285d3686e1dc74cc07cc60a9754a150041ba132e14bd3e2ec@buzz.block.builderlab.xyz>
The local pre-push gate ran biome (`desktop-check`) and node:test
(`desktop-test`) for desktop changes but never `tsc`, so TypeScript
errors surface no earlier than CI's `desktop-core` job (`just
desktop-build` = `tsc && vite build`). A branch with type errors passes
every local hook today.
This adds a `desktop-typecheck` pre-push command running `just
desktop-typecheck` (`tsc --noEmit`) with the same glob/exclude as
`desktop-check`, and updates the hook documentation in `AGENTS.md`. CI
is unchanged — it already typechecks via `desktop-build`.
Signed-off-by: Will Pfleger <pfleger.will@gmail.com>
## Summary
Gives Buzz-hosted git entities the same "GitHub-style" chat experience
GitHub links already get: rich preview cards, real titles, and
click-through — except clicks navigate **in-app** to the Projects view
instead of a browser.
- **Spec**: `docs/buzz-entity-links.md` — link scheme, slices, and
deferred work (`buzz://project`, OS deep links, web routes).
- **Canonical `buzz://` deep links**: new
`desktop/src/shared/lib/entityLink.ts` with builders + strict parser for
`buzz://pr?id=…&owner=…&d=…`, `buzz://issue?…`, and
`buzz://repo?owner=…&d=…`, mirrored by a Rust module
(`crates/buzz-cli/src/links.rs`) with a shared golden-format test so the
two implementations can't drift.
- **Preview cards**: `linkPreview.ts` recognizes `buzz://` entity links
*and* HTTPS relay clone URLs (`{origin}/git/<pubkey>/<repo>`, the shape
agents paste today). Both normalize onto the canonical `buzz://` href,
so the two spellings of a repo dedupe to one `Buzz`-provider card
(`BuzzMark` logo) rendered by `link-preview-attachment.tsx`.
- **Title enrichment**: PR/issue cards fetch the real subject from the
relay event (`subject` tag or first content line) via
`useResolvedLinkPreviews.ts`; the cache is community-scoped and reset in
`resetCommunityState()`.
- **In-app navigation**: clicking a card or inline anchor (including
HTTPS relay clone URLs whose origin matches the active relay) routes to
the canonical `30617:<owner>:<d>` coordinate via `goProject()`
(`markdown/entityLinks.tsx`). **Merge dependency: #4671 must merge
first** — route resolution for `30617:` coordinates is implemented on
that branch (`feat/multi-repository-projects`). Entity-link and
external-anchor logic were extracted out of `markdown.tsx` to stay under
the file-size ratchet.
- **Agent side**: `buzz pr open`, `buzz issues create`, and `buzz repos
create` now return a ready-made `link` field (omitted when the relay
returns `accepted: false`), and `base_prompt.md` instructs agents to
paste it verbatim when announcing work.
## Test plan
- [x] Desktop unit tests: pass, including new `entityLink.test.mjs` and
`linkPreview.test.mjs` coverage (golden formats, malformed-link
rejection, clone-URL/`buzz://` dedupe, origin-gated anchor behavior,
label-must-win invariant, cache epoch)
- [x] Rust: `cargo test -p buzz-cli` golden-format test +
accepted/rejected link guard assertions, clippy + fmt clean
- [x] Biome + `tsc --noEmit` clean; pre-push hooks
(desktop-tauri-checks, rust-tests, desktop-test) pass
- [ ] Manual: paste a relay clone URL and a `buzz://pr` link in a
channel — verify one card each, real PR title, and in-app navigation to
the Projects view
Related: [#4671](https://github.com/block/buzz/pull/4671)
---------
Signed-off-by: Thomas Petersen <thomasp@squareup.com>
Signed-off-by: Will Pfleger <pfleger.will@gmail.com>
Co-authored-by: npub1g8493u0xfsjrvflg4n08ezd7vec99mnwzlv0qgwpr9d7gvjwhuzqx59rhw <41ea58f1e64c243627e8acde7c89be667052ee6e17d8f021c1195be4324ebf04@buzz.block.builderlab.xyz>
Co-authored-by: Will Pfleger <pfleger.will@gmail.com>
## Summary
- document exact-head trusted approval as the only desktop tagging
authorization
- explicitly require `desktop_ref=desktop-v<version>` for the internal
desktop handoff
- replace the stale `squareup/sprout-releases` repository name with
`squareup/buzz-releases`
## Audit coverage
Compared `block/buzz` release documentation and automation with
`squareup/buzz-releases` `main`
(`5b09e5c5d71c80a0849a33458f4e45695df515d7`), including its README,
agent guide, Buildkite field hint, desktop validator, release validation
tests, and protected updater promotion instructions.
## Validation
- `bash scripts/test-release-ref-contract.sh`
- `git diff --check origin/main...HEAD`
Signed-off-by: Wes <wesbillman@users.noreply.github.com>
Co-authored-by: Carl <c7ebe626f000404285d3686e1dc74cc07cc60a9754a150041ba132e14bd3e2ec@buzz.block.builderlab.xyz>
The channel scoping note in `AGENTS.md` reads as universal:
> **Channel scoping**: Channels use `h` tags (NIP-29 group tag), not `e`
tags.
> Filters and queries must scope to `h` tags when operating within a
channel.
It holds for events inside a channel, but not for the addressable events
that
describe one. kind:39000, kind:39001 and kind:39002 carry the channel id
in
their `d` tag, which is what `get_channels` already reads.
Taking the existing wording at face value while working on kind:39002
produces
an empty result rather than an error, since those events do carry `h`
tags in
other flows, so the mistake is quiet and costs a debugging cycle. Came
up while
working on #4023.
Four lines, no behaviour change.
Signed-off-by: Szymon Tanski <szymontanski8@gmail.com>
## Why
The Inbox mixed overlapping feed categories with personal work queues,
so **All** was not actually comprehensive and several filters did not
make it clear why an item appeared. Threads and DMs could produce one
row per event instead of one row per conversation, drafts were hidden
until selected, and reminders appeared through multiple competing
presentations.
This refactor makes the **Inbox** a focused, conversation-oriented place
to catch up on work relevant to you. It is intentionally not a mirror of
every unread event in every channel.
## What changed
- Keep the destination named **Inbox** and use the standard Lucide bell
icon.
- Refocus **All** on DMs, mentions, thread replies, needs-action items,
replies from agents the user owns or controls, due reminders, and active
drafts.
- Exclude generic top-level channel traffic and updates from agents the
user does not own or control.
- Group each thread or DM into one row, sorted by latest activity.
- Resume an unread conversation at its oldest unread message while
opening the full thread or DM in the detail pane.
- Reuse the existing **New** divider at the unread boundary.
- Make the detail title a direct link to the canonical conversation.
- Give Reminders and Drafts the same list/detail interaction and
location metadata as conversation rows.
- Separate Reminders and Drafts from message filters with a subtle
divider, without adding another labeled section.
- Put reminder and draft counts beside their corresponding filter labels
instead of on the generic filter button.
- Preserve the selected conversation when switching filters if it
remains valid; otherwise select a valid replacement without flashing
stale detail.
- Use filter-specific empty states and rename the options toggle to
**Show unread only**.
- Ship the focused behavior directly. The earlier experiment gate,
Custom view, and default-view controls have been removed from this PR to
keep the first pass focused.
## Filter model
| Filter | What appears |
| --- | --- |
| **All** | One row per personally relevant conversation, plus due
reminders and active drafts. Includes DMs, mentions, thread replies,
explicit needs-action items, and replies from agents the current user
owns or controls. Excludes generic top-level channel traffic, other
agents' updates, and reminders that are not due yet. |
| **Mentions** | Conversations containing a direct mention. Each
conversation appears once and opens with full context. |
| **Threads** | Conventional threaded replies, grouped to one row per
thread. Broadcast replies are not treated as conventional thread
replies. |
| **Needs action** | Feed items explicitly classified as requiring
action. |
| **Agents** | Conversations whose representative response was authored
by an agent the current user owns or controls, including top-level DM
responses. If a human replies afterward, the conversation leaves this
filter until an owned agent responds again. |
| **Reminders** | All pending reminders, including upcoming reminders
that stay out of **All** until they are due. |
| **Drafts** | Active drafts, ordered by their last real edit time. |
## Grouping, ordering, and state
- A thread or DM creates one Inbox row rather than one row per event.
- An unread conversation resumes at its oldest unread message so
intervening context is not skipped.
- Conversation rows still sort by their latest activity.
- The detail pane opens the full available conversation and shows the
shared **New** divider before the first unread message.
- Upcoming reminders appear only in **Reminders**.
- When a reminder becomes due, it enters **All** at its trigger time. If
its source conversation is already represented, the reminder state
merges into that row instead of creating a duplicate; otherwise it
appears as a standalone reminder row.
- A due reminder can enrich a row in another relative filter when that
conversation already qualifies for the filter. Reminder lifecycle
remains separate from message read state.
- Drafts appear in **All** by their last real edit time. Opening an
unchanged draft does not move it to the top.
- Reminder and draft rows show their location as `In #channel` or `In DM
with <name>`.
- **Show unread only** hides reminder and draft work queues because they
do not share message unread semantics.
## Removed or narrowed
- **Remove the old Activity filter.** It overlapped with All while still
omitting items All now includes.
- **Narrow Agents.** It no longer gathers every agent participating in a
shared thread or subsequent human follow-ups.
- **Remove duplicate reminder presentations.** The aggregate
pending-reminders jump and duplicate generic feed rows are replaced by
one list/detail model.
- **Remove Custom and default-view settings from this pass.** They added
considerable state and UI before the core model had been validated.
- **Do not add section labels for Reminders and Drafts.** A divider
communicates the distinction without creating another hierarchy in the
menu.
## Risk assessment
Medium implementation risk because this changes composition, grouping,
ordering, read behavior, and personal queues in a primary desktop view.
The implementation is scoped to the desktop UI and its local feed
projection; it does not change relay schemas or public APIs.
## Testing
- Desktop formatting, lint, file-size, text-size, and TypeScript checks
passed.
- Desktop unit suite: **3,663 passed, 0 failed**.
- Desktop E2E production build passed.
- Playwright smoke coverage across every spec touching this surface
(`channels`, `smoke`, `profile`, `project-inbox`, `community-rail`,
`integration`, `drafts-screenshots`): **118 passed, 0 failed**.
- Full Playwright smoke project: **732 passed, 1 skipped**. Three local
failures were investigated and cleared — `community-rail` keyboard
reorder passed on re-run (flaky), while `relay-reconnect:97` and
`video-attachment:223` are untouched by this commit (the only change to
shared `tests/helpers/bridge.ts` is a comment) and pass in CI.
- Unit coverage includes focused All matching, owned-agent filtering,
conversation grouping, oldest-unread selection, selection stability,
chronological reminder/draft composition, trigger-time reminder
ordering, and duplicate reminder suppression.
## Update: July 27, 2026
The naming decision is settled: the surface stays **Inbox**. An earlier
pass in this branch had renamed it to **Activity**; that rename has been
reverted in `9c00d2d6e`, which is naming-only and changes no behavior.
The revert covers file names, component/hook/type/constant identifiers,
the sidebar label and tooltip, the `Inbox options` and `Filter inbox:`
aria-labels, and the corresponding test names, test ids, and fixture
ids.
Three things were deliberately left as `activity`:
- **The feed API contract** — the `activity` / `agent_activity`
categories, the `feed.activity` and `feed.agentActivity` keys, and the
`types=` query parameter. These are the server's names, not the
surface's.
- **Plain-noun usage** — empty states such as "No activity yet", plus
`latestActivityAt` and `PROJECT_ACTIVITY_KINDS`.
- **Pre-existing agent, project, and profile activity code**, which
refers to a different concept entirely.
The earlier experiment-gate approach has also been dropped, so
`tests/helpers/bridge.ts` no longer claims that an Activity preview
feature exists — `preview-features.json` has no such entry and the seed
helper enables every desktop feature.
Generated with Codex
---------
Signed-off-by: Clay Delk <clay.delk@gmail.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
**Category:** improvement
**User Impact:** Developers can identify which worktree produced a
mobile debug app, keep a bounded set of worktree builds installed side
by side, and preserve each worktree app's login and local state while
switching branches.
**Problem:** Mobile debug builds from every checkout currently appear as
the same “Buzz” app and share one application identity, so the running
source is ambiguous and one worktree build replaces another. A
branch-keyed identity would avoid replacement but create stale installs
and fresh app state on every branch switch.
**Solution:** Give each linked worktree a stable Debug-only application
identity derived from its sanitized directory name. Show the sanitized
branch name (or short commit SHA when detached) in the display label,
persist generated native overrides for direct IDE builds, and leave
Release/Profile identities unchanged. Worktree defaults remain lower
precedence than a developer's iOS `AppOverrides.xcconfig`. `just
mobile-clean` provides a safe cleanup path for suffixed worktree
installs while preserving production Buzz.
<details>
<summary>File changes</summary>
**.github/workflows/ci.yml**
Runs the expanded worktree override contract when relevant mobile or
native configuration changes.
**AGENTS.md**
Documents worktree-aware mobile development and cleanup for contributors
and agents.
**Justfile**
Generates overrides before mobile development and Android debug builds,
and exposes `just mobile-clean`.
**mobile/README.md**
Explains stable per-worktree identities, branch/SHA labels, direct IDE
usage, cleanup, and Release/Profile guarantees.
**mobile/android/.gitignore**
Ignores generated worktree properties.
**mobile/android/app/build.gradle.kts**
Loads and validates generated properties, then applies the application
ID suffix and display label to Android Debug only.
**mobile/android/app/src/main/AndroidManifest.xml**
Resolves the Android app label through an overridable string resource.
**mobile/ios/.gitignore**
Ignores generated iOS worktree settings.
**mobile/ios/Flutter/Debug.xcconfig**
Loads generated worktree defaults before developer `AppOverrides`, so
personal signing overrides retain precedence.
**mobile/ios/Flutter/Release.xcconfig**
Pins the production display name and bundle identifier for
Release/Profile builds.
**mobile/ios/Runner/Info.plist**
Resolves the visible iOS app name from build settings.
**scripts/mobile-worktree-overrides.sh**
Detects linked worktrees, derives a stable directory-keyed identity,
sanitizes branch/SHA display context, writes native Debug overrides, and
removes stale overrides in the main checkout.
**scripts/mobile-worktree-clean.sh**
Lists or removes suffixed Buzz worktree installs from booted iOS
simulators and connected Android emulators without matching production
IDs; supports `--dry-run`.
**scripts/test-mobile-worktree-overrides.sh**
Covers worktree detection, branch-switch identity stability, detached
HEAD fallback, special-character sanitization, iOS override precedence,
brace-aware Release/Profile purity, cleanup safety, ignores, and command
integration.
</details>
## Reproduction steps
1. From a linked worktree, activate the repository toolchain and run
`just mobile-dev`.
2. Inspect the running app: its label should be `Buzz
(<sanitized-branch>)`, while its application ID suffix is derived from
the worktree directory.
3. Switch branches in the same worktree, rerun the override script, and
confirm the application ID remains stable while the display label
updates. In detached HEAD, confirm the label uses a short SHA.
4. Build Debug from a second worktree and confirm both apps remain
installed side by side with independent state.
5. Build from Xcode after setting `AppOverrides.xcconfig` and confirm
developer overrides still win over generated worktree defaults.
6. Run `just mobile-clean --dry-run`, then `just mobile-clean`, and
confirm suffixed worktree installs are targeted while the production app
is preserved.
7. Build Release/Profile and confirm the production name and application
identity remain unchanged.
8. Run `scripts/test-mobile-worktree-overrides.sh`, `just mobile-check`,
`just mobile-test`, and `just mobile-build-android`.
## Screenshots / demos
| iOS — labeled app switcher | iOS — side-by-side installs |
| --- | --- |
| <img width="360" alt="Buzz worktree label in the iOS app switcher"
src="https://github.com/user-attachments/assets/4bcae067-7ce5-4333-bb11-2803c4107663"
/> | <img width="360" alt="Buzz production and worktree debug apps
installed side by side on iOS"
src="https://github.com/user-attachments/assets/08a107b5-fdf2-463a-8a4c-81d41d7bf5e7"
/> |
| Android — side-by-side installs | Android — labeled app switcher |
| --- | --- |
| <img width="360" alt="Buzz production and worktree debug apps
installed side by side on Android"
src="https://github.com/user-attachments/assets/4f5841a1-adae-42da-ae84-47c09ec85fb9"
/> | <img width="360" alt="Buzz worktree label in the Android app
switcher"
src="https://github.com/user-attachments/assets/0546ff51-efcc-4cb6-a4bd-2a3af26cd60f"
/> |
---------
Signed-off-by: Taylor Ho <taylorkmho@gmail.com>
Co-authored-by: npub1223z34hd7vtwc6qj4s7flsxkj644nlre2nthu7lrrmkumhu3xddsrx9r6w <52a228d6edf316ec6812ac3c9fc0d696ab59fc7954d77e7be31eedcddf91335b@buzz.block.builderlab.xyz>
`DCO Check` is a required status check on this repo and the top failing
check on open contributor PRs, but nothing documented it and nothing
surfaced it locally — a missing `Signed-off-by` trailer only showed up
as a red check after the PR was already open.
## `lefthook.yml`
New `commit-msg` hook that appends the `Signed-off-by` trailer:
```yaml
commit-msg:
commands:
signoff:
run: 'git interpret-trailers --if-exists doNothing --trailer "Signed-off-by: $(git var GIT_COMMITTER_IDENT | sed ''s/ [0-9]* [+-][0-9]*$//'')" --in-place {1}'
```
`GIT_COMMITTER_IDENT` is the identity that performed the commit, which
is what a DCO sign-off certifies and what native `git commit -s` uses.
Committing someone else's work with `--author` or `git commit -C`
therefore signs off as you, not as the original author.
`--if-exists doNothing` makes it idempotent: `git commit -s` still
yields exactly one trailer, and an existing sign-off from a different
signer is preserved rather than supplemented. An empty commit message
still aborts — the hook does not turn one into a commit body containing
only a trailer.
Git runs `commit-msg` for `git commit` and `git merge` only. Other flows
bypass it and need their own sign-off flag — `git rebase --signoff`,
`git cherry-pick -s`. Note `-s` is `--strategy` on `git rebase`, so only
the long flag works there. The header comment and both docs state the
scope rather than promising blanket coverage. Installed by `just hooks`;
`commit-msg` carries no `glob` because it rewrites the message, not
files.
## `CONTRIBUTING.md`
`Before You Open a PR` gains a paragraph on sign-off: commit with `git
commit -s`, what the trailer certifies, that the required `DCO Check`
blocks merge without it, `git rebase --signoff main` to repair
already-pushed commits, and what the hook does and does not cover.
`CI Gate` gains one sentence pointing at `just fix-all` for
formatting-only failures.
## `AGENTS.md`
`Quality Gates` gains the same requirement framed for agents, including
the sequencer caveat and the reminder to include `-s` in
programmatically built commit commands.
## Related issue
none found
---------
Signed-off-by: npub1mn7jgtj4w2pd0g0zeuhxsa6jy6p0rewxz4kujt98my82ahfmp72sxjexk7 <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz>
Signed-off-by: Will Pfleger <pfleger.will@gmail.com>
Co-authored-by: npub1mn7jgtj4w2pd0g0zeuhxsa6jy6p0rewxz4kujt98my82ahfmp72sxjexk7 <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@buzz.block.builderlab.xyz>
## Summary
- Activate lefthook pre-commit and pre-push hooks that have existed in `lefthook.yml` since the initial desktop app but were never wired up.
- Add `just hooks` recipe: sets `core.hooksPath = .hooks` and runs `lefthook install --force` to generate hook scripts.
- Wire hook installation into `scripts/dev-setup.sh` so hooks activate automatically on `just setup`.
- Enable `parallel: true` for pre-commit hooks (pre-push already had it) — all 5 format/lint checks run simultaneously.
- Add `just mobile-fmt` recipe (`dart format .`) and `just fmt-all` recipe (Rust root + Tauri Rust + Dart) as one-shot formatters.
- `.hooks/` is gitignored since lefthook generates machine-specific scripts.
- Update `AGENTS.md`: document pre-commit/pre-push hooks in Quality Gates, add `just fmt-all` and `just hooks` usage, upgrade worktree fmt gotcha from CI note to commit blocker, add `just mobile-fmt` to mobile commands; also backfill CLI-first updates (`SPROUT_AUTH_TAG`, complete exit codes, `--format compact` flag position, two new gotchas).
All hook commands delegate to `just` recipes as the single source of truth.
