diff --git a/AGENTS.md b/AGENTS.md index 34e91b06d0..a33cc31e75 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,13 +23,13 @@ against that direction. Scale validation to the change's risk and exercise the real workflow for user-visible or integration behavior when practical; green CI and runtime evidence answer different questions. -### Room and Object Model +### Channel and Object Model For changes involving projects, tasks, repositories, branches, documents, or -channel navigation, read [VISION_ROOMS.md](VISION_ROOMS.md). +channel navigation, read [VISION_CHANNELS.md](VISION_CHANNELS.md). -A room has one conversation and can have several object views. Each object has -one canonical room; a task and its branch can share the **same room**. Do not +A channel has one conversation and can have several object views. Each object has +one canonical channel; a task and its branch can share the **same channel**. Do not create a second conversation merely to add a view. Apply this model consistently across desktop, web, mobile, CLI, and agents. diff --git a/VISION.md b/VISION.md index c5686f9d42..ce2fa07880 100644 --- a/VISION.md +++ b/VISION.md @@ -152,9 +152,9 @@ Beyond chat: channels are workspaces. The relay hosts git repos. Smart HTTP — standard `git clone`, `git push`, nothing special. Your npub signs pushes. Same domain, same auth, same identity as everything else on the relay. -The target is **one room, many views**. Projects, tasks, repositories, branches, and documents resolve to canonical conversation rooms; a task and its branch can share the same channel UUID. Time-bound projects can span durable repositories, each with its own ongoing room. See [VISION_ROOMS.md](VISION_ROOMS.md) for the shared model, nested relationships, and backend specification. +The target is **one channel, many views**. Projects, tasks, repositories, branches, and documents resolve to canonical conversation channels; a task and its branch can share the same channel UUID. Time-bound projects can span durable repositories, each with its own ongoing channel. See [VISION_CHANNELS.md](VISION_CHANNELS.md) for the shared model, nested relationships, and backend specification. -In that model, creating a feature branch creates or reuses its room — CI results, review comments, and the merge decision belong there. A completed branch-only room can archive into a permanent record; merging a branch must not archive other active work sharing the room. +In that model, creating a feature branch creates or reuses its channel — CI results, review comments, and the merge decision belong there. A completed branch-only channel can archive into a permanent record; merging a branch must not archive other active work sharing the channel. See [VISION_PROJECTS.md](VISION_PROJECTS.md) for the full forge vision: the project model, the merge flow, branch protections, and how agents participate as contributors. diff --git a/VISION_ROOMS.md b/VISION_CHANNELS.md similarity index 52% rename from VISION_ROOMS.md rename to VISION_CHANNELS.md index ff267b3013..f0173359ee 100644 --- a/VISION_ROOMS.md +++ b/VISION_CHANNELS.md @@ -1,86 +1,89 @@ -# Buzz Rooms — One Conversation, Many Views +# Buzz Channels — One Conversation, Many Views ## The Model -A **room is a channel**: one stable channel UUID and one working conversation. -Projects, tasks (including subtasks), repositories, branches, and living documents -each have a canonical room. They are **facets** of that room, not mutually -exclusive room types. An ordinary conversation can have no object facets. +A **channel** is where people and agents discuss work. It has one stable UUID +and one shared conversation. Task details, documents, and code diffs are views +alongside that conversation, not separate chats. -One object has one conversation home. One room can be home to several objects. -A task and its implementation branch can therefore be two views of **the same -channel UUID**, not separate channels with synchronized messages. Switching from -task details to the diff changes the view, not the conversation. Adding a facet +Projects, tasks (including subtasks), repositories, branches, and living documents +each have one home channel. A channel can be home to several objects, or just +be a conversation with none. These objects do not impose mutually exclusive +channel types. + +For example, a task and its implementation branch can share **the same channel +UUID**. Switching from task details to the diff changes the view, not the +conversation. Opening either object leads back to that channel; adding a view does not create another chat. Object state stays in its own representation: a task has status and assignees, -a repository has refs, and a document has content. The room brings these views +a repository has refs, and a document has content. The channel brings these views and their conversation together. ## Projects and Repositories Projects organize a time-bound outcome. Repositories are durable homes for code and ongoing conversation. A project can span several repositories, and a -repository can support many projects over time or concurrently. Their rooms have +repository can support many projects over time or concurrently. Their channels have different purposes and do not normally share a one-to-one relationship. For example, a **Simplify sign-in** project spans the identity service and mobile app repositories: ```text -Project room: Simplify sign-in -├── Task room: Improve account recovery -│ ├── Room S: Fix recovery tokens [subtask + identity-service branch] -│ └── Room M: Add recovery screen [subtask + mobile-app branch] -└── Design room: Recovery experience [document] +Project channel: Simplify sign-in +├── Task channel: Improve account recovery +│ ├── Channel S: Fix recovery tokens [subtask + identity-service branch] +│ └── Channel M: Add recovery screen [subtask + mobile-app branch] +└── Design channel: Recovery experience [document] -Repository room: identity-service [ongoing code and maintenance discussion] -└── Branch view: fix-recovery-tokens → room S +Repository channel: identity-service [ongoing code and maintenance discussion] +└── Branch view: fix-recovery-tokens → channel S -Repository room: mobile-app [ongoing code and maintenance discussion] -└── Branch view: recovery-screen → room M +Repository channel: mobile-app [ongoing code and maintenance discussion] +└── Branch view: recovery-screen → channel M ``` -The subtask and branch in S open the same room; likewise for M. The repository -branch listings link to those rooms rather than creating new conversations. +The subtask and branch in S open the same channel; likewise for M. The repository +branch listings link to those channels rather than creating new conversations. Completing the sign-in project does not end either repository's ongoing work. -## Nested Rooms and Relationships +## Nested Channels and Relationships -Rooms nest to organize work: a project contains task rooms, a task contains -subtask rooms, and a document can have its own room or be a view of an existing -room. A channel canvas is the document view within a room. +Channels nest to organize work: a project contains task channels, a task contains +subtask channels, and a document can have its own channel or be a view of an existing +channel. A canvas is the channel’s document view. -A room has at most one containment parent. The navigation tree is not the entire -relationship model: a task's room can sit under its project while its branch +A channel has at most one containment parent. The navigation tree is not the entire +relationship model: a task's channel can sit under its project while its branch still belongs to a repository elsewhere. Project-to-repository links and branch-to-repository links remain available independently of that tree. Multiple -routes to a room all lead to the same conversation. +routes to a channel all lead to the same conversation. ## Access -A room and its object views should feel like one workspace. Someone admitted to +A channel and its object views should feel like one workspace. Someone admitted to that workspace should be able to read its conversation and the objects presented as part of it, rather than encountering an arbitrary inaccessible subset. The -same principle applies when presenting nested rooms as a shared project workspace. +same principle applies when presenting nested channels as a shared project workspace. Reading the work and permission to push, merge, or administer it are distinct capabilities. -The permissions design must make that experience consistent across linked rooms +The permissions design must make that experience consistent across linked channels and objects. For repositories, it must choose whether access is governed through -the canonical room relationship or through repository permissions coordinated -with the room. The model does not prescribe a separate, unrelated channel link +the canonical channel relationship or through repository permissions coordinated +with the channel. The model does not prescribe a separate, unrelated channel link just for Git authorization. The choice of permission authority and inheritance rules remains an explicit design decision; the required user experience is coherent access, not disconnected permission islands. ## Backend Specification -Persist room relationships on the channel: +Persist channel relationships on the channel: - `parent_channel_id`: nullable channel UUID, in the same community, indexed for child lookup. -- `object_bindings`: a list of typed object references stored as JSONB. A room +- `object_bindings`: a list of typed object references stored as JSONB. A channel can bind several objects, including a task and its branch. Bindings reference the object they represent: an issue ID for a task, an @@ -98,8 +101,8 @@ The relay validates management authority, bounded binding shapes, and an existin same-community parent. It rejects self-parenting and cycles, including concurrent moves that would create a cycle. -All clients use the same relationships to resolve an object's canonical room. -Creating another view reuses that room. Repeated creation requests must converge -on the same room rather than create parallel conversations. Conflicting bindings +All clients use the same relationships to resolve an object's canonical channel. +Creating another view reuses that channel. Repeated creation requests must converge +on the same channel rather than create parallel conversations. Conflicting bindings must be reconciled consistently across clients, not resolved by local discovery order. The metadata storage does not require a global unique-binding constraint. diff --git a/VISION_PROJECTS.md b/VISION_PROJECTS.md index 35fadec0e0..28d8d8e493 100644 --- a/VISION_PROJECTS.md +++ b/VISION_PROJECTS.md @@ -1,6 +1,6 @@ # 🐝 Buzz Projects — A Nostr-Native Forge -> Someone pushes a fix. Buzz creates or reuses the branch’s canonical room, which can already be the task’s room. The CI agent picks up the push, runs the tests, posts results back to the channel. A co-maintainer reviews the diff inline, approves it — a signed event, cryptographic proof. Merge. The workflow runs the integration. Once all work sharing the room is finished, it can archive into a permanent record of why that code exists. +> Someone pushes a fix. Buzz creates or reuses the branch’s canonical channel, which can already be the task’s channel. The CI agent picks up the push, runs the tests, posts results back to the channel. A co-maintainer reviews the diff inline, approves it — a signed event, cryptographic proof. Merge. The workflow runs the integration. Once all work sharing the channel is finished, it can archive into a permanent record of why that code exists. > > Bug report to merged patch. One place. One search index. One identity system. The branch channel was the pull request, the CI dashboard, and the discussion thread. @@ -10,10 +10,10 @@ This document is the software-forge slice of the broader Buzz platform. [VISION. ## The Project Model -The shared room contract is [VISION_ROOMS.md](VISION_ROOMS.md): a project, repo, -task, branch, or document is a facet of a canonical room, not an exclusive channel -type. Several facets may share one conversation. Projects organize time-bound -outcomes across repositories; repository rooms support ongoing code and +The shared channel contract is [VISION_CHANNELS.md](VISION_CHANNELS.md): a project, repo, +task, branch, or document has a home channel, not an exclusive channel +type. Several objects may share one conversation. Projects organize time-bound +outcomes across repositories; repository channels support ongoing code and maintenance discussion. A project lives on the relay. `myproject.com` in a browser shows the project home. Click a repo and you're at `repoa.myproject.com` — README rendered, file tree navigable, code syntax-highlighted, clone URL at the top. The same URL serves HTML to a browser and git protocol to `git clone`. Content negotiation. One URL, two audiences. @@ -84,9 +84,9 @@ The cost is stated plainly: a third-party NIP-34 client sees the member repos in A feature branch is a conversation. -When you create a branch, Buzz should create or reuse its canonical room. If the branch implements a task in an existing room, task details and the branch diff can be views of that same channel UUID. The branch's patches, review comments, CI results, and merge decision belong to that conversation, not a parallel branch chat. Room nesting preserves the task/subtask structure; a separate branch-to-repository reference preserves code ownership. +When you create a branch, Buzz should create or reuse its canonical channel. If the branch implements a task in an existing channel, task details and the branch diff can be views of that same channel UUID. The branch's patches, review comments, CI results, and merge decision belong to that conversation, not a parallel branch chat. Channel nesting preserves the task/subtask structure; a separate branch-to-repository reference preserves code ownership. -When a branch-only room's work finishes, it can archive as the permanent record of why that code exists. A merge must not automatically archive a shared room whose task or other facets are still active. The example below is the branch-only case. +When a branch-only channel's work finishes, it can archive as the permanent record of why that code exists. A merge must not automatically archive a shared channel whose task or other objects are still active. The example below is the branch-only case. ``` #feat-auth-fix @@ -134,7 +134,7 @@ Push CI Review Merge │ │ │ │ Merge to main │ │ │ │ kind:1631 │ │ │ │ - │ │ │ │ Branch-only room archives + │ │ │ │ Branch-only channel archives ``` The approval event is signed by the maintainer's npub. The merge status references the approval. The audit log chains them together. Cryptographic proof of who approved what. @@ -192,7 +192,7 @@ Every step traced. Every trace a signed event. Change the project CI once and ev ### Issues → Forum + NIP-34 -Bug reports and tasks retain their NIP-34 kind:1621 identity. In the target model, task details, forum presentation, and branch work can open the same canonical room; subtasks can have nested rooms. A forum is a view, not a reason to fork the conversation. +Bug reports and tasks retain their NIP-34 kind:1621 identity. In the target model, task details, forum presentation, and branch work can open the same canonical channel; subtasks can have nested channels. A forum is a view, not a reason to fork the conversation. Threaded comments use NIP-22 kind:1111. Labels, assignees, and milestones are nostr tags. Design discussions and RFCs use the forum's long-form async surface. @@ -200,8 +200,8 @@ NIP-34 clients can discover and interact with issues. Buzz's forum gives them a ### Docs → Canvases -A channel canvas is the initial document facet of a room. A document may share -its project's or task's room, or have a dedicated nested room; opening the +A canvas is the initial document view in a channel. A document may share +its project's or task's channel, or have a dedicated nested channel; opening the document should not create a parallel discussion stream. Living documents, collaboratively editable by humans and agents via MCP tools. Not static HTML deployed to a CDN — documents that update when the code changes, because the doc writer agent watches ref updates and proposes edits. diff --git a/VISION_SOVEREIGN.md b/VISION_SOVEREIGN.md index c173c1591f..ef6717cb18 100644 --- a/VISION_SOVEREIGN.md +++ b/VISION_SOVEREIGN.md @@ -79,8 +79,8 @@ They read the triage summary, confirm it's real, assign it. Thirty seconds of th time instead of five minutes. Someone picks up the bug. They create a branch. Buzz creates or reuses its -canonical room: `#feat-auth-fix`. The task and branch can be views of the same -channel UUID, as defined in [VISION_ROOMS.md](VISION_ROOMS.md). They work there. +canonical channel: `#feat-auth-fix`. The task and branch can be views of the same +channel UUID, as defined in [VISION_CHANNELS.md](VISION_CHANNELS.md). They work there. They push commits. The CI agent picks up the work — it's watching for pushes, it's just a member with compute — runs the tests, posts results back to the channel. Green. The patch lands in the channel as a reviewable diff. A co-maintainer reviews it inline, leaves a comment on line 45, @@ -88,7 +88,7 @@ approves it. The approval is a signed event — cryptographic proof of who said and when. Merge. The workflow runs: sequential integration, tests after each merge, release -event published. A finished branch-only room archives; a shared room stays active +event published. A finished branch-only channel archives; a shared channel stays active while its other work continues. The conversation is now the permanent record of why that code exists. Not a chat thread that scrolled away. Not a PR that might get deleted. The event log, on your relay, in your database. Someone reading that