docs: mark superseded designs after the 2026-07-26 decisions - #2157
Conversation
|
Warning Review limit reached
Next review available in: 33 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (7)
📝 WalkthroughWalkthroughThe PR documents a scheduled, single-identity agent collaboration model and marks prior chat, transport, project-structure, and product-naming guidance as superseded or partially superseded. ChangesCollaboration and design alignment
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
|
PR Summary by QodoDocs: mark superseded designs after 2026-07-26 decisions
AI Description
Diagram
High-Level Assessment
Files changed (7)
|
Code Review by Qodo
1. Wrong member_id contract
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
| Each agent authenticates to the controller **as itself** - its own registry | ||
| identity, its own project-scoped token (Bearer, `project_tasks` scope). Never as | ||
| Jay's account, never as another agent, never sudo. Membership on the board is by | ||
| registry identity (already true: `project_members.member_id`). |
There was a problem hiding this comment.
2. Wrong member_id contract 🐞 Bug ≡ Correctness
docs/design/agent-collaboration-model.md claims project membership is "already" keyed by registry identity via project_members.member_id, but the runtime uses member_id for agent hex IDs / clone slugs and resolves those to names/handles for channel membership. This mismatch can cause new integrations to write/read membership rows using the wrong identifier type and fail membership resolution.
Agent Prompt
## Issue description
The new collaboration model doc states that board membership is already keyed by registry identity via `project_members.member_id`, but the codebase documents `project_members.member_id` as storing agent hex IDs (or clone slugs) that are later resolved to names/handles.
## Issue Context
This is a documentation contract problem: implementers may store canonical IDs / handles into `project_members.member_id` based on this doc, but the runtime expects a different identifier shape.
## Fix Focus Areas
- docs/design/agent-collaboration-model.md[36-44]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
| Each agent authenticates to the controller **as itself** - its own registry | ||
| identity, its own project-scoped token (Bearer, `project_tasks` scope). Never as | ||
| Jay's account, never as another agent, never sudo. Membership on the board is by | ||
| registry identity (already true: `project_members.member_id`). | ||
|
|
||
| - `@taOS-dev` (the lead session) authenticates as `@taOS-dev` - lead of the taOS | ||
| project `prj-5y722y`. | ||
| - Build lanes (`kilo-taos-*`, `stepflash-taos-*`, `nemotron-ultra-taos-*`) are | ||
| members; each authenticates as itself. |
There was a problem hiding this comment.
3. Handle vs canonical_id confusion 🐞 Bug ≡ Correctness
docs/design/agent-collaboration-model.md implies agents authenticate "as" their @handle and via a “project-scoped token”, but registry JWT auth is keyed by canonical_id in the JWT sub claim and project authorization is grant-based (the token’s project_id claim is advisory). This ambiguity can lead clients to use the wrong identifier in auth flows and misunderstand how project scoping is enforced.
Agent Prompt
## Issue description
The doc mixes three distinct identity concepts without naming them explicitly:
- `canonical_id` (JWT `sub`, used for authentication)
- `handle` (e.g. `@taOS-dev`, used for display / bus `from`)
- project scoping (enforced by per-project grants, not by a hard token pin)
## Issue Context
The runtime uses `canonical_id` for auth and separately forces bus messages to use the agent’s handle. Additionally, project access checks are grant-gated, and the JWT’s `project_id` claim is explicitly advisory.
## Fix Focus Areas
- docs/design/agent-collaboration-model.md[36-57]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/design/agent-collaboration-model.md`:
- Around line 23-32: Clarify the collaboration loop’s “Chat” step to align with
the A2A-as-conversation contract: state whether Chat is only the taOStalk view
of A2A or a separate channel. Update the surrounding “Three surfaces” summary
consistently so agents use one authoritative conversation state and do not
duplicate discussions.
- Around line 36-39: Update the per-operation scope contract in the agent
authentication section to distinguish board operations using project_tasks from
A2A send and receive operations using a2a_send and a2a_receive. Ensure cron
workers receive exactly the scopes required for each operation, without broader
privileges, while preserving authentication as the agent’s own registry
identity.
In `@docs/design/projects-nested-elements.md`:
- Around line 1-11: Make both supersession banners navigable: in
docs/design/projects-nested-elements.md lines 1-11, link the
one-project/one-repo rule to its authoritative current statement; in
docs/design/taos-council.md lines 1-9, convert jaylfc/taOS#2142 into a Markdown
link to the current statement or issue. Preserve the existing banner wording and
scope.
In `@docs/design/taos-council.md`:
- Around line 1-9: The document’s rename note must distinguish the taOS Teams
user-facing product from retained internal Council terminology. Update the
opening statement to explicitly preserve Council as the internal package/API
name, including tinyagentos/council and /api/council/*, as well as the benchmark
methodology; do not imply those existing contracts should be renamed.
In `@docs/design/taostalk-slice1.md`:
- Around line 1-8: The document preface must clarify whether A2A session-event
envelopes may still be translated into chat_messages rows and whether replies
may use a synthetic session channel. Update the superseded boundary to
explicitly approve this network-event path as an exception, or mark the affected
retained plan sections superseded so the document aligns with the A2A
thread-as-conversation model.
In `@docs/runbooks/framework-swap.md`:
- Around line 1-10: Define one authoritative chat migration and cutover contract
covering field mapping, ordering and ID rules, dual-write or freeze window,
validation, rollback, and the exact cutover point. In
docs/runbooks/framework-swap.md at lines 1-10, update the notice and carry-over
table to identify the authoritative store and link this procedure; in
docs/design/message-hub-core.md at lines 1-12, classify the legacy schema and
routes as migration-source-only and link the same contract.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: d0ccc08f-f276-42b8-a150-0ca130e7d089
📒 Files selected for processing (7)
docs/design/agent-collaboration-model.mddocs/design/message-hub-core.mddocs/design/projects-nested-elements.mddocs/design/taos-council.mddocs/design/taostalk-acp-bridge.mddocs/design/taostalk-slice1.mddocs/runbooks/framework-swap.md
| ### The one loop (every agent, every 30 min, via cron) | ||
|
|
||
| 1. **A2A** - read my channels for @mentions / requests; reply where warranted. | ||
| 2. **Chat** - project chat channels for questions/requests (if applicable). | ||
| 3. **Board** - for my projects: claim a suitable CLAIMABLE card, do it, open a | ||
| PR, update the card, post a note on A2A. | ||
| 4. **My open PRs** - address review feedback. | ||
| 5. Sleep until the next tick. | ||
|
|
||
| Three surfaces (A2A, chat, board), one loop, nothing live. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Align the loop with the A2A-as-conversation contract.
The current transport direction says the A2A thread is the conversation and taOStalk renders it, but this loop instructs agents to treat A2A and Chat as separate collaboration surfaces. Clarify whether “Chat” is only the taOStalk view of A2A or a distinct channel; otherwise agents may create duplicate or competing conversation state.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/design/agent-collaboration-model.md` around lines 23 - 32, Clarify the
collaboration loop’s “Chat” step to align with the A2A-as-conversation contract:
state whether Chat is only the taOStalk view of A2A or a separate channel.
Update the surrounding “Three surfaces” summary consistently so agents use one
authoritative conversation state and do not duplicate discussions.
| Each agent authenticates to the controller **as itself** - its own registry | ||
| identity, its own project-scoped token (Bearer, `project_tasks` scope). Never as | ||
| Jay's account, never as another agent, never sudo. Membership on the board is by | ||
| registry identity (already true: `project_members.member_id`). |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift
Document the correct scopes for each loop operation.
This section assigns project_tasks to the agent’s controller token, while the transport design requires a2a_send and a2a_receive for A2A collaboration. Align the per-operation scope contract so cron workers can perform both board and A2A work without either failing authorization or receiving broader privileges than necessary.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/design/agent-collaboration-model.md` around lines 36 - 39, Update the
per-operation scope contract in the agent authentication section to distinguish
board operations using project_tasks from A2A send and receive operations using
a2a_send and a2a_receive. Ensure cron workers receive exactly the scopes
required for each operation, without broader privileges, while preserving
authentication as the agent’s own registry identity.
| > **PARTIALLY SUPERSEDED 2026-07-26 — the one-board-many-repos premise no longer holds.** | ||
| > | ||
| > This design argues for collapsing taOS, taOSmd and the website into one project | ||
| > with one board spanning several repos. The operating rule is now **one project, | ||
| > one repo, one dedicated agent**: cross-repo work is a REQUEST to that repo's | ||
| > lead, who cards it on their own board and owns the merge, because the lead who | ||
| > owns a repo is accountable for what lands in it. | ||
| > | ||
| > Nested elements remain valid WITHIN a single repo's project. The multi-repo | ||
| > board is not the direction. | ||
| > |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add clickable links to both supersession banners.
The banners identify changed guidance but do not provide navigable replacement statements.
docs/design/projects-nested-elements.md#L1-L11: link the one-project/one-repo rule to its authoritative current statement.docs/design/taos-council.md#L1-L9: convertjaylfc/taOS#2142into a Markdown link to the current statement or issue.
📍 Affects 2 files
docs/design/projects-nested-elements.md#L1-L11(this comment)docs/design/taos-council.md#L1-L9
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/design/projects-nested-elements.md` around lines 1 - 11, Make both
supersession banners navigable: in docs/design/projects-nested-elements.md lines
1-11, link the one-project/one-repo rule to its authoritative current statement;
in docs/design/taos-council.md lines 1-9, convert jaylfc/taOS#2142 into a
Markdown link to the current statement or issue. Preserve the existing banner
wording and scope.
| > **PARTIALLY SUPERSEDED 2026-07-26.** | ||
| > | ||
| > Anything in this doc that translates a captured CLI session into synthetic chat | ||
| > rows is superseded — there is no session mirroring and no tmux capture. The | ||
| > content-block renderers and the taOStalk surface work remain valid. | ||
| > | ||
| > Current statement: jaylfc/taOS#2150. | ||
|
|
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Broaden or clarify the superseded boundary.
This preface rejects translating a captured CLI session into synthetic chat rows, but the retained plan still translates A2A session-event envelopes into chat_messages rows and forwards replies through a synthetic session channel. That conflicts with the current “A2A thread is the conversation” model unless this network-event path is explicitly an approved exception; state that contract or mark the affected sections superseded too.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/design/taostalk-slice1.md` around lines 1 - 8, The document preface must
clarify whether A2A session-event envelopes may still be translated into
chat_messages rows and whether replies may use a synthetic session channel.
Update the superseded boundary to explicitly approve this network-event path as
an exception, or mark the affected retained plan sections superseded so the
document aligns with the A2A thread-as-conversation model.
| > **PARTIALLY SUPERSEDED 2026-07-26.** | ||
| > | ||
| > This runbook states that chat history lives durably in the host `data/chat.db` | ||
| > and survives a framework swap. That is true today but is changing: chat moves | ||
| > onto the taOSmd bus, and **taOSmd is no longer swappable** — it becomes a | ||
| > required dependency, at minimum to power the bus. Other memory frameworks may | ||
| > replace or complement parts of it, but it stays present. | ||
| > | ||
| > Current statement: jaylfc/taOS#2150. | ||
|
|
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Define one authoritative chat migration and cutover contract.
The design notice announces migration to the taOSmd bus, while the operational runbook still preserves data/chat.db as the chat-history source. Publish the mapping, ordering/ID rules, dual-write or freeze window, validation, rollback, and exact cutover point once, then reference it from both documents.
docs/runbooks/framework-swap.md#L1-L10: update the runbook notice and carry-over table to reference the migration procedure and authoritative store.docs/design/message-hub-core.md#L1-L12: classify the legacy schema/routes as migration-source-only and link the same cutover contract.
📍 Affects 2 files
docs/runbooks/framework-swap.md#L1-L10(this comment)docs/design/message-hub-core.md#L1-L12
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/runbooks/framework-swap.md` around lines 1 - 10, Define one
authoritative chat migration and cutover contract covering field mapping,
ordering and ID rules, dual-write or freeze window, validation, rollback, and
the exact cutover point. In docs/runbooks/framework-swap.md at lines 1-10,
update the notice and carry-over table to identify the authoritative store and
link this procedure; in docs/design/message-hub-core.md at lines 1-12, classify
the legacy schema and routes as migration-source-only and link the same
contract.
Adds supersede banners rather than deleting, so the history stays readable: - taostalk-acp-bridge: proposes PTY capture and session mirroring, which was rejected. The A2A thread IS the conversation. This one is urgent - lanes are working taOStalk cards and could read it as current. - taostalk-slice1: the session-capture half only. - message-hub-core, framework-swap: chat moves onto the taOSmd bus and taOSmd becomes a required dependency rather than swappable. - projects-nested-elements: one board spanning several repos is not the model; one project, one repo, cross-repo work is a request. - taos-council: renamed to taOS Teams. - mac-app c1 design and plan: menubar client obsolete, taOSgo clients remade.
fe53d7e to
ce51d61
Compare
Review was right that the banner overstated the retirement. The runtime still ships tinyagentos/council and /api/council/*, so a blanket 'Council is retired' reads as though those identifiers are stale when they are not. The notice now scopes the rename to user-facing text and says explicitly that the package, route prefix and benchmark methodology keep the name, and that renaming them is a separate change. Also clears 31 pre-existing em dashes from the files this PR already touches. Character swap only; the whitespace pass that broke a YAML example earlier was not repeated.
|
Folded the findings that were right, and said why on the two I am not acting on now. Corrected: the Council rename scope. The finding is accurate. Cleared 31 em dashes from the files this PR already touches. Character swap only. Not acting on two, both real, both blocked on work that has not happened yet:
Both are worth doing once unblocked. Neither is a reason to hold a PR whose entire purpose is warning readers off superseded designs. The two findings on |
Code Review Roast 🔥Verdict: No New Issues Found | Recommendation: Address existing findings from other reviewers before merge Oh wait, I warmed up the flamethrower and there's nothing left to burn. The PR is a documentation sweep with supersede banners and em-dash hygiene — and the existing Qodo/CodeRabbit comments already roasted the 📊 Overall: Like arriving at a crime scene the morning after — the bodies are already tagged, I just verified no new ones appeared overnight. Files Reviewed (7 files)
Reviewed by kat-coder-pro-v2.5 · Input: 191.5K · Output: 16.2K · Cached: 255.6K |
1 participant
Adds supersede banners to eight docs that now contradict decisions made on 2026-07-26. Nothing is deleted - the banners point at the current statement and the docs stay readable as history.
Found by an audit sweep, not by chance, which is the point: these decisions were made in conversation and the docs kept saying the old thing.
The urgent one:
docs/design/taostalk-acp-bridge.md. It proposes mirroring a CLI session into taOStalk including PTY capture as a fallback - exactly the approach Jay rejected. Free lanes are working taOStalk cards tonight and could reasonably read it as the current plan and build the wrong thing. That is the reason this PR exists now rather than in the morning.taostalk-acp-bridge.mdtaostalk-slice1.mdmessage-hub-core.mdrunbooks/framework-swap.mdprojects-nested-elements.mdtaos-council.mdCurrent statements: #2150 (chat on bus, no mirroring), #2142 (Teams), and the one-board-one-repo rule.
doc-gate passes locally. No code changes.
Summary by CodeRabbit