From f7237c4b4bb0ae35c0c6c8828dddfaa7f7506ceb Mon Sep 17 00:00:00 2001 From: mintaka Date: Tue, 25 Aug 2026 22:52:18 -0400 Subject: [PATCH] docs(designs): apply DL-254/255/256 at RIG-2717 freeze MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Linear Agent Session responder record (RIG-2717, #625) froze on merge; apply its declared Ledger-impact rows to the canonical ledger. New 'Linear agent responder' section: - DL-254 — POST /webhooks handler on the network TLS door, fail-closed HMAC-SHA256, ack-before-async. - DL-255 — route on the recorded forge ownership index, never a text-parsed header. - DL-256 — Option B dumb-link return path (thought + externalUrls deep link), new linear_agent_sessions table, not 1-1 session<->topic. Next-free id re-verified against current main (max was DL-253). design-ledger-gate green (227 rows), markdownlint clean. Co-authored-by: Matt Wilkinson --- docs/designs/DECISIONS.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/designs/DECISIONS.md b/docs/designs/DECISIONS.md index dbb03a29..fa76dbd0 100644 --- a/docs/designs/DECISIONS.md +++ b/docs/designs/DECISIONS.md @@ -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) |