From 1783fcb7f1be487341e2f6ea975dae8fbebce099 Mon Sep 17 00:00:00 2001 From: mintaka Date: Wed, 26 Aug 2026 22:16:15 -0400 Subject: [PATCH] =?UTF-8?q?docs(designs):=20dedup=20DL-264=20collision=20?= =?UTF-8?q?=E2=80=94=20renumber=20RIG-2794=20row=20to=20DL-268?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two decisions merged onto main both numbered DL-264: - DECISIONS.md:99 — RIG-2732 forge webhook transport (#634), which owns the documented contiguous DL-264..DL-267 block. - DECISIONS.md:367 — RIG-2794 Linear return-path indirection (#658). Both PRs were cut against a main topping out at DL-263 and each grabbed the next-free 264; both merged, colliding. design-ledger-gate scans the whole tree and fails closed on a duplicate id, so EVERY design PR in the repo was blocked. The forge record documents owning 264..267, so the single RIG-2794 row renumbers to the next free id DL-268. No decision prose changes — only the row id and the amendment record's own Ledger-impact reference. Gate green after. Co-authored-by: Matt Wilkinson --- docs/designs/DECISIONS.md | 2 +- .../design.md | 10 ++++++---- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/designs/DECISIONS.md b/docs/designs/DECISIONS.md index 8981bd286..dfd5ec020 100644 --- a/docs/designs/DECISIONS.md +++ b/docs/designs/DECISIONS.md @@ -364,4 +364,4 @@ check enforces the mechanical half. Full rationale: | 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) | -| DL-264 | The Linear return path's `externalUrls` link is a SERVER-RESOLVED INDIRECTION URL (Matt, RIG-2794), amending DL-256's link target only: on `created` the responder sets the session external URL ONCE, immediately, to the stable post-independent `https:///l/session/` (fits the 10s SLA; still exactly one emit per session, preserving DL-256's dumb link while removing its staleness failure mode), and a new read-only route `GET /l/session/` on the same DL-254 network TLS door reads the `linear_agent_sessions` association (for the issue coordinate only, never the stale created-time target) + resolves the DL-055 ownership index at CLICK time and 302s to the current best target (the dedicated routing channel while unrouted or issue-less, the resolved Manager's home channel once an ownership row exists); nothing rewrites the Linear session. All other DL-256 invariants survive (dumb link, no relay, no settle observation, no session-lifecycle machine, not-1-1 topic mapping). The #646 direct-link stage ships as-is; the resolver is the follow-on | Active (Matt, 2026-08-26) | [return-path indirection amendment §Approach](product/compass-linear-return-path-indirection-amendment/design.md#approach) | +| DL-268 | The Linear return path's `externalUrls` link is a SERVER-RESOLVED INDIRECTION URL (Matt, RIG-2794), amending DL-256's link target only: on `created` the responder sets the session external URL ONCE, immediately, to the stable post-independent `https:///l/session/` (fits the 10s SLA; still exactly one emit per session, preserving DL-256's dumb link while removing its staleness failure mode), and a new read-only route `GET /l/session/` on the same DL-254 network TLS door reads the `linear_agent_sessions` association (for the issue coordinate only, never the stale created-time target) + resolves the DL-055 ownership index at CLICK time and 302s to the current best target (the dedicated routing channel while unrouted or issue-less, the resolved Manager's home channel once an ownership row exists); nothing rewrites the Linear session. All other DL-256 invariants survive (dumb link, no relay, no settle observation, no session-lifecycle machine, not-1-1 topic mapping). The #646 direct-link stage ships as-is; the resolver is the follow-on | Active (Matt, 2026-08-26) | [return-path indirection amendment §Approach](product/compass-linear-return-path-indirection-amendment/design.md#approach) | diff --git a/docs/designs/product/compass-linear-return-path-indirection-amendment/design.md b/docs/designs/product/compass-linear-return-path-indirection-amendment/design.md index 52eb98340..f5c34b14a 100644 --- a/docs/designs/product/compass-linear-return-path-indirection-amendment/design.md +++ b/docs/designs/product/compass-linear-return-path-indirection-amendment/design.md @@ -213,10 +213,12 @@ record captures. ## Ledger-impact -Ledger-impact: adds DL-264 to `docs/designs/DECISIONS.md` under the "Linear -agent responder" section (highest row on current `main` is DL-263, -DECISIONS.md:258; the driver MUST re-verify the next-free id against current -main at freeze rather than trusting a session-time snapshot). DL-256 does NOT +Ledger-impact: adds DL-268 to `docs/designs/DECISIONS.md` under the "Linear +agent responder" section. (Originally authored as DL-264 against a `main` +topping out at DL-263; a concurrent forge-notification record, RIG-2732, also +claimed DL-264 and merged first, taking the contiguous DL-264..DL-267 block, so +this row was renumbered to the next free id DL-268 to clear the duplicate.) +DL-256 does NOT flip: its status cell stays `Active` and its frozen Decision-cell prose is untouched (rows are append-only, `tools/design-ledger-gate/index.ts:25-27`) — this amendment is its amending sibling, and the new row carries the delta,