sendbird · astyfx · Aug 9, 2026 · Aug 9, 2026 · Aug 9, 2026
@@ -19,6 +19,11 @@ Stave is an installable product. Do not bake author-specific machine state into
 
 ## Git, PR, And Release Rules
 
+- Before the first edit in a task, establish three facts and report them: where `main` is (`git fetch origin && git rev-list --left-right --count origin/main...HEAD`), which PR already owns the current branch (`gh pr list --head "$(git branch --show-current)"`), and whether that PR is green (`gh pr view <n> --json mergeable,mergeStateStatus,statusCheckRollup`).
+- Rebase onto a moved `main` before doing substantial work, not after. A late rebase invalidates every verification already run, so the test suite gets paid for twice.
+- When an open PR already owns the branch, everything committed joins that PR. Unrelated work must not join it: create a new workspace and branch before the first edit.
+- Do not stack commits onto a red or conflicted PR. Fix it or branch away from it first.
+- Re-check `main` and the PR's checks immediately before pushing.
 - Use Conventional Commits for every commit.
 - Keep PR titles in Conventional Commits form and keep the subject lowercase.
 - Do not name competing or reference products as design or implementation inspiration in tracked files, code comments, tests, fixtures, commit messages, PR titles or bodies, issues, changelogs, or release notes.

@@ -31,14 +31,20 @@
       "id": "terminal-font-and-unicode",
       "title": "Terminal glyph and renderer addons are defensive",
       "invariant": "Unicode, link, search, and WebGL addons cannot prevent the DOM renderer from booting.",
-      "testFiles": ["tests/terminal-instance.test.ts"],
-      "assertionRefs": ["src/components/layout/useTerminalInstance.ts"]
+      "testFiles": [
+        "tests/terminal-instance.test.ts"
+      ],
+      "assertionRefs": [
+        "src/components/layout/useTerminalInstance.ts"
+      ]
     },
     {
       "id": "lens-component-capture",
       "title": "Lens keeps component context with element picks",
       "invariant": "A Lens element selection may include a parent-to-leaf React component chain without requiring it for non-React pages.",
-      "testFiles": ["tests/lens-element-message.test.ts"],
+      "testFiles": [
+        "tests/lens-element-message.test.ts"
+      ],
       "assertionRefs": [
         "electron/main/browser/browser-element-picker.ts",
         "src/lib/lens/lens-element-message.ts"
@@ -48,7 +54,9 @@
       "id": "review-feedback-to-agent",
       "title": "Diff comments can return to the active agent",
       "invariant": "A review comment retains its diff line anchor and can be submitted as the next agent prompt.",
-      "testFiles": ["tests/review-feedback.test.ts"],
+      "testFiles": [
+        "tests/review-feedback.test.ts"
+      ],
       "assertionRefs": [
         "src/lib/review-feedback.ts",
         "src/components/panes/surfaces/EditorSurfacePanel.tsx"
@@ -58,7 +66,9 @@
       "id": "codex-checkpoint-provenance",
       "title": "Codex turns expose checkpoint provenance",
       "invariant": "A normal Codex turn emits a checkpoint boundary with the current Git ref when available.",
-      "testFiles": ["tests/codex-app-server-runtime.test.ts"],
+      "testFiles": [
+        "tests/codex-app-server-runtime.test.ts"
+      ],
       "assertionRefs": [
         "electron/providers/codex-app-server-runtime.ts",
         "docs/providers/provider-runtimes.md"
@@ -99,7 +109,9 @@
       "id": "provider-utility-inference",
       "title": "Utility inference remains provider neutral",
       "invariant": "Task naming, route classification, and commit suggestions choose an explicit or active provider deterministically and degrade without blocking the primary task.",
-      "testFiles": ["tests/utility-inference.test.ts"],
+      "testFiles": [
+        "tests/utility-inference.test.ts"
+      ],
       "assertionRefs": [
         "electron/providers/utility-inference.ts",
         "src/lib/providers/utility-inference.ts",
@@ -135,6 +147,21 @@
         "src/components/layout/TaskExecutionSummarySurface.tsx",
         "src/store/app-notification-builders.ts"
       ]
+    },
+    {
+      "id": "agent-platform-boundaries",
+      "title": "Agent platform layers stay distinct",
+      "invariant": "A routine cannot target an existing task, the run ledger never imports execution runtimes, the secondary executor never writes ledger rows, utility inference stays mechanical, and the work queue assigns one lane per workspace.",
+      "testFiles": [
+        "tests/agent-platform-boundaries.test.ts",
+        "tests/fleet-sidebar-work-queue.test.ts"
+      ],
+      "assertionRefs": [
+        "docs/architecture/agent-platform-taxonomy.md",
+        "src/lib/fleet/sidebar-work-queue.ts",
+        "src/lib/providers/utility-inference.ts",
+        "src/lib/routines.ts"
+      ]
     }
   ]
 }
@@ -0,0 +1,102 @@
+# Agent Platform Taxonomy And Boundaries
+
+Stave grew several ways to make an agent do more work — Advisor, Worker, Fleet,
+Routines, the run ledger — and each was added for its own reason. This file
+fixes what each one is, what it is not, and which vocabulary the product uses,
+so the next capability lands in the right layer instead of beside a similar one.
+
+Read this before adding anything that runs work, schedules work, delegates
+work, or shows work.
+
+## Vocabulary
+
+Use these words in code, UI copy, and plans. Do not introduce synonyms.
+
+| Word | Means |
+| --- | --- |
+| Task | One conversation with one provider inside one workspace. The unit everything else attaches to. |
+| Turn | One request/response cycle inside a task. Ends with exactly one terminal event. |
+| Attention item | One thing that wants the user: a question, an approval, a failed run, a PR state. `FleetAttentionItem`. |
+| Action required | The lane and inbox heading for blocking attention items. Replaces the older "Needs me". |
+| Ledger | The durable runs/steps/receipts record in `src/lib/runs/`. It records; it never executes. |
+| Receipt | One bounded record of how something started or ended. Never transcript text, never secrets. |
+| Occurrence | One firing of a schedule. |
+
+Lane names for workspace state are fixed and ordered:
+`action-required` > `in-progress` > `in-review` > `idle`.
+
+## Three Layers
+
+Every concept belongs to exactly one layer, classified by scope (turn / task /
+fleet) and lifetime (ephemeral / durable).
+
+### Layer 1 — Turn runtime: help the current turn
+
+Ephemeral, turn-scoped, minimal product branding. These are task options.
+
+| Concept | Role | Does not |
+| --- | --- | --- |
+| Advisor | One read-only advice call before a turn, injected as context | Execute; persist |
+| Worker | Same-provider delegation inside a turn | Survive a restart; cross providers |
+| Utility inference | Mechanical meta calls: task name, route classification, commit message | Block the task; give advice |
+
+Boundary: Advisor produces *content* the user would recognize as an opinion.
+Utility inference produces *metadata* the user never argues with.
+
+### Layer 2 — Supervision: see everything, intervene from anywhere
+
+Fleet-scoped, read plus control, no new execution semantics.
+
+| Concept | Role |
+| --- | --- |
+| Fleet | The cross-workspace surface: attention inbox, workspace cards, task control |
+| Task control plane | Identity (`projectPath + workspaceId + taskId + turnId`) and staleness validation for remote actions |
+| Task execution summary | Provenance-tagged scorecard; missing data is never rendered as zero |
+| Sidebar work queue | The same lane model as one of the sidebar's two views (`Projects` / `Work queue`) |
+| Run ledger (run core) | Durable bookkeeping for delegated execution: runs, steps, receipts, idempotency, claims |
+
+The run ledger is shared machinery, not a feature. Compare Judge is its first
+client; durable child tasks are planned as its second. Widen it for a new
+client instead of building a second ledger beside it.
+
+### Layer 3 — Continuity: keep going without me
+
+Durable (SQLite), reconciled on restart, always carrying an explicit terminal
+reason. Two axes:
+
+| | Ephemeral (exists) | Durable (planned) |
+| --- | --- | --- |
+| Time — run again | — | Routine (new task per occurrence) / Heartbeat (same task, same session) |
+| Delegation — hand work off | Worker (Layer 1) | Child tasks (cross-provider, normal tasks + ledger receipts) |
+
+Routine is the only concept that lives outside a task: it mints tasks.
+Everything else in this layer attaches to one existing task.
+
+## Boundary Statements
+
+These are the statements that keep the layers from collapsing into each other.
+Each one is registered in `config/reliability-gates.json` and asserted by a test
+whose name repeats it.
+
+1. A routine never wakes an existing task; its definition cannot target one.
+2. A heartbeat never creates a task; it only adds a turn to one that exists.
+3. A worker never survives a restart; a child task always does.
+4. The ledger records and never executes; executors execute and never write
+   ledger rows except through coordinator transitions.
+5. Advisor advises content; utility inference computes metadata.
+6. The work queue assigns a workspace to exactly one lane, in fixed priority
+   order.
+
+Statements 2 and 3 are partly forward-looking: heartbeats and child tasks are
+not built yet. They are recorded here so the capability lands inside the
+boundary rather than beside it, and the gate test asserts the half that exists
+today.
+
+## Adding Something New
+
+1. Name the layer it belongs to. If it seems to span two, it is two things.
+2. Name its consumer. A module with no visible consumer does not ship — the run
+   ledger spent a year with exactly one client because that rule did not exist.
+3. Reuse the vocabulary above. A new synonym is a new concept to everyone
+   reading the code later.
+4. If it changes a boundary statement, change it here first, then the gate.
@@ -10,11 +10,12 @@ This file is the fast entrypoint for codebase orientation.
 4. `docs/providers/provider-runtimes.md` for provider-specific paths
 5. `docs/architecture/entrypoints.md` for task-to-file routing
 6. `docs/architecture/contracts.md` for multi-file contract checklists
-7. `docs/architecture/run-core.md` before adding durable secondary execution consumers
-8. `docs/architecture/workspace-integrity.md` before changing project/workspace/task ownership or hydration logic
-9. `docs/architecture/chat-message-rendering.md` before changing assistant message UI semantics
-10. `docs/architecture/agent-message-ux-catalog.md` for the provider-event-to-UX matrix and Preview baseline
-11. `docs/architecture/session-cursor.md` for provider switch-back delta history and safe fresh-session fallback
+7. `docs/architecture/agent-platform-taxonomy.md` before adding anything that runs, schedules, delegates, or displays work
+8. `docs/architecture/run-core.md` before adding durable secondary execution consumers
+9. `docs/architecture/workspace-integrity.md` before changing project/workspace/task ownership or hydration logic
+10. `docs/architecture/chat-message-rendering.md` before changing assistant message UI semantics
+11. `docs/architecture/agent-message-ux-catalog.md` for the provider-event-to-UX matrix and Preview baseline
+12. `docs/architecture/session-cursor.md` for provider switch-back delta history and safe fresh-session fallback
 
 ## Top-Level Layout
 

@@ -5,6 +5,11 @@ read-only background provider execution. Its first and current consumer is
 Compare Judge. It is not a generic workflow engine or a prerequisite for
 Fleet, Advisor, or Crane.
 
+The read-only limit belongs to the executor, not to the ledger: the ledger is
+shared bookkeeping and is meant to gain further clients rather than be copied.
+See `docs/architecture/agent-platform-taxonomy.md` for where it sits among the
+other layers.
+
 ## Ownership
 
 - The renderer owns user intent, presentation, and consumer-specific result

@@ -146,4 +146,4 @@ optional shortcuts on top of that.
 
 - [Notifications](notifications.md)
 - [Latest Turn Summary](workspace-latest-turn-summary.md)
-- [Sidebar Active Workspaces](sidebar-active-workspaces.md)
+- [Sidebar Views](sidebar-views.md)