Skip to content

docs(designs): apply DL-254/255/256 at RIG-2717 freeze #635

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mattwilkinsonn merged 1 commit into from
Aug 26, 2026
+8 −0
Merged

docs(designs): apply DL-254/255/256 at RIG-2717 freeze #635

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/designs/DECISIONS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -345,3 +345,11 @@ check enforces the mechanical half. Full rationale:
| DL-190 | The case-2 brief carrier is a PER-PAIR manager↔peer DM channel (`ChannelKindDM`, 2 members: spawning manager + new peer, both owners carried by `expandOwnerMembership` so the operator retains visibility), auto-provisioned on the spawn edge (T-R0) — NOT the manager's coordination channel, which is a broadcast to all reports. Token-minimization: siblings do not receive briefs they don't need. UI channel-proliferation UX is a known deferred problem | Active (Matt, 2026-08-10) | [first-turn delivery §Approach](product/compass-first-turn-delivery/design.md#approach) |
| DL-191 | The `@compass` system-sender is a dedicated `system` account type — a third first-class account shape alongside user and agent (the `system = 12` proto case, not an unset-oneof discriminator), startup-seeded and reserved-handle-guarded at account creation, visible only to shared-channel co-members, and structurally never a deliver recipient nor present in directory/roster (no `agent_accounts` row) | Active (Matt, 2026-08-14) | [system-sender first turn §A](product/compass-system-sender-first-turn/design.md#a--compass-representation-a-dedicated-system-account-type-matt-ruled) |
| DL-192 | The root-manager Setup-thread first-turn flow: a `postSetupThread` step in `serve_seed.go` fired from `seedRootSupervisor` on BOTH up-arms after the supervisor seed, posting the embedded versioned `setup_thread.md` content as `@compass` into the supervisor's home channel, made idempotent by a supervisor-scoped `client_request_id` (content-invariant — the same supervisor id yields the same key, so a content revision never re-posts) | Active (Matt, 2026-08-14) | [system-sender first turn §B](product/compass-system-sender-first-turn/design.md#b--the-setup-thread-first-turn-flow) |

## Linear agent responder

| ID | Decision | Status | Record |
| --- | --- | --- | --- |
| DL-254 | The Linear Agent Session responder is a plain `POST /webhooks` `http.Handler` mounted on the compass-server network TLS door (inside `buildNetworkServer`, beside the Connect mounts, inheriting the G112/SEA-1298 guards; NOT a Connect service, NOT a dedicated ingress), fail-closed on the raw-body HMAC-SHA256 `Linear-Signature` check (bad/missing signature → 400; a stale-but-validly-signed `webhookTimestamp` is 200-with-drop, never a retry-burning 400), acking 200 before any work (Linear's 5s SLA) with all agent work async; the public base URL (webhook host + deep-link base) is a per-deployment config value, never hardcoded | Active (Matt, 2026-08-25) | [linear agent responder §Part 1](product/compass-linear-agent-responder/design.md#part-1--the-webhook-receiver-on-the-network-door) |
| DL-255 | A delegated Linear session is routed to a stable Compass Manager keyed on Compass's recorded forge ownership index (`forge_authored_artifacts`, DL-055/DL-205) — NEVER a header parsed from forge text (DL-050/DL-094 forbid it reaching a routing decision); an issue with no recorded ownership row routes to the supervisor/top-level Manager via a dedicated routing channel, which decides the lane and stamps it through the DL-050 write chokepoint so later events resolve directly | Active (Matt, 2026-08-25) | [linear agent responder §Part 2](product/compass-linear-agent-responder/design.md#part-2--routing-a-delegated-linear-session-to-a-stable-manager) |
| DL-256 | The Linear return path is a dumb link (Option B, Matt 2026-08-25): on `created` the responder emits one `thought` plus an `externalUrls` "Open in Compass" deep link to the resolved Manager's home channel and nothing else — NO activity relay, NO settle observation, NO Linear session-lifecycle machine. One Linear session is NOT forced 1-1 to a comms topic; the prompt lands in an issue-named topic (persisted in a new `linear_agent_sessions` table) delivered as `@linear`-authored deliver-rail messages deduped by `PostAsAccount`'s `client_request_id` on the `Linear-Delivery` UUID, but the deep link targets the home channel. Option C (coarse one-way status) is the ratified follow-up; Option A (full bidirectional relay) is off-table until Linear's activity vocabulary is configurable | Active (Matt, 2026-08-25) | [linear agent responder §Part 3](product/compass-linear-agent-responder/design.md#part-3--the-return-path-a-dumb-link-option-b) |
Loading