Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
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
110 changes: 55 additions & 55 deletions docs/designs/DECISIONS.md

Large diffs are not rendered by default.

6 changes: 3 additions & 3 deletions docs/designs/agent/compass-agent-forge-tools/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ its T3) and the lifecycle tools (`packages/compass-agent/src/lifecycle.ts`):
same broker shape, same identity model, same registration path. Everything
below the agent — the Server write chokepoint, the hub relay, the Runner
gateway leg, and the proto carrier — is COMPLETE and frozen elsewhere
([`compass-forge-write-path/design.md`](../../product/compass-forge-write-path/design.md));
([`compass-forge-write-path/design.md`](../../server/compass-forge-write-path/design.md));
this record consumes it and designs nothing on the Go side.

**Grounding.** This record and the code it describes live together in this
Expand Down Expand Up @@ -72,7 +72,7 @@ else.
in-band `unimplemented` until the writer lands.** The backend arms are
`CodeUnimplemented` stubs (`go/server/forge.go`) pending the
`agent_forge_subscriptions` store writer, which the poll-driver lane owns
([`compass-forge-poll-driver/design.md`](../../product/compass-forge-poll-driver/design.md),
([`compass-forge-poll-driver/design.md`](../../server/compass-forge-poll-driver/design.md),
DL-163: the tables land writer-less; that lane brings the writer). Matt
ruled build-all: the tools ship now so the surface is stable and complete;
the two arms simply error at runtime (rendered as a clean in-band
Expand Down Expand Up @@ -362,7 +362,7 @@ hard scope enforcement is A8's frozen deferral, not reopened here.
churn), and the runtime error is honest — the per-tool guidance states the
arm is not yet wired, so the model learns "not available yet", not "broken".
This composes with the poll-driver lane
([`compass-forge-poll-driver/design.md`](../../product/compass-forge-poll-driver/design.md),
([`compass-forge-poll-driver/design.md`](../../server/compass-forge-poll-driver/design.md),
DL-163: the tables land writer-less; that lane brings the writer).
- **Deferring the `ForgeRef` (provider/host) selector.** Considered and
OVERRULED by Matt: expose it now. The wave needs BOTH forges — it files
Expand Down
2 changes: 1 addition & 1 deletion docs/designs/agent/compass-agent-peer-dm/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ owner-pull. No new delivery rail, no new authz model.

Matt: ids are a leak; client UIs and agents address channels and topics only
by their actual name. The precedent is the merged handle-addressing cutover
(`docs/designs/product/compass-handle-addressing-cutover/design.md`, PR #698,
(`docs/designs/server/compass-handle-addressing-cutover/design.md`, PR #698,
RIG-2880), whose pattern this record mirrors exactly:

- **Request-INPUT** fields carry the name, resolved to an id at the service
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Status: Active
Tracker: SEA

> **Amends frozen contract (#1018, DL-091 / DL-032).** This record is a
> sibling amendment to `docs/designs/product/compass-issue-model/design.md`
> sibling amendment to `docs/designs/server/compass-issue-model/design.md`
> (merged in #1018) and composes with the DL-070 server projection it froze.
> It ratifies Matt's 2026-08-04 ruling that the board lifecycle is
> **agent-primary**: "i'm not sure we should even have the UI move cards? i
Expand Down
4 changes: 2 additions & 2 deletions docs/designs/agent/compass-agent-spawn-despawn/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ seams: the agent→Server lifecycle relay (spawn + despawn), the missing
agent-side tool pair. Companion records this composes with:
[`compass-agent-comms-tools/design.md`](../compass-agent-comms-tools/design.md)
(the agent-tool + relay pattern this mirrors, DL-028/DL-029),
[`compass-server-ownership-layer/design.md`](../../product/compass-server-ownership-layer/design.md)
[`compass-server-ownership-layer/design.md`](../../server/compass-server-ownership-layer/design.md)
(#995 — the Server as ownership layer; its DL-049 sibling-call-family precedent),
and [`compass-agent-container-runtime.md`](../compass-agent-container-runtime.md)
(the provisioning substrate the spawn drives).
Expand Down Expand Up @@ -193,7 +193,7 @@ exist inside it is the agent's business, so a spawned peer clones whatever it
has credentials for, after launch. This mirrors the same removal on
`ProvisionAgentWorkspaceRequest` (server-side auto-clone is deleted, not made
optional) — see the ownership record's OQ-4, superseded to *removed*
([`compass-server-ownership-layer/design.md`](../../product/compass-server-ownership-layer/design.md),
([`compass-server-ownership-layer/design.md`](../../server/compass-server-ownership-layer/design.md),
OQ-4). Post-MVP, an agent tool may clone on the agent's behalf so agents need
hold no git creds; until then the container's scoped credential stands.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Status: Active

Tracker: RIG-1611 — PR #75 review LOW #3, parked at review time ("no change for
MVP, multi-Runner only"). Provenance: the parent product record
`docs/designs/product/compass-notification-delivery/design.md` (RIG-1569 T3)
`docs/designs/server/compass-notification-delivery/design.md` (RIG-1569 T3)
ships the fan-out consumer whose head-of-line blocking motivates this record;
that record is frozen (`Status: Active`) and is cited, never edited. This is
the **SERVER-side counterpart** to the already-**MERGED** RUNNER-side work
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Status: Active
Tracker: SEA

> **Amends frozen contract (#1018, DL-068).** This record is a sibling
> amendment to `docs/designs/product/compass-issue-model/design.md` (merged in
> amendment to `docs/designs/server/compass-issue-model/design.md` (merged in
> #1018): the merged record is frozen, so a later change ADDS a record. It
> ratifies Matt's 2026-08-01 ruling that agent attribution is a plain display
> fact — not a trust claim — reversing DL-068's hedge-unless-verified board
Expand Down Expand Up @@ -135,7 +135,7 @@ Author this record; add DL-094 (the display-fact contract); flip DL-068 to
supersede is warranted (see §Ledger delta for the DL-092 judgment).

`Interfaces:` consumes the frozen records cited above; produces
`docs/designs/product/compass-attribution-simplification/design.md` and the
`docs/designs/server/compass-attribution-simplification/design.md` and the
`DECISIONS.md` delta (DL-094 + the DL-068 flip). Gate: `design-ledger-gate`.

### T2 — proto: slim `AgentAttribution` (compass repo; NOT this PR)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ Six threads:
app-actor is a delegation endpoint that cannot be *assigned* work
(responder record: "a delegation is routed to the right stable Compass
Manager … the Linear session is a doorway, not a home",
`docs/designs/product/compass-linear-agent-responder/design.md:42-45`), so
`docs/designs/server/compass-linear-agent-responder/design.md:42-45`), so
a live end-to-end delegation needs a user identity to perform the
human→app handoff.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -976,9 +976,9 @@ Proposed rows:

| 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/RIG-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, YYYY-MM-DD) | [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, YYYY-MM-DD) | [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, YYYY-MM-DD) | [linear agent responder §Part 3](product/compass-linear-agent-responder/design.md#part-3--the-return-path-a-dumb-link-option-b) |
| 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/RIG-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, YYYY-MM-DD) | [linear agent responder §Part 1](server/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, YYYY-MM-DD) | [linear agent responder §Part 2](server/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, YYYY-MM-DD) | [linear agent responder §Part 3](server/compass-linear-agent-responder/design.md#part-3--the-return-path-a-dumb-link-option-b) |

(The `YYYY-MM-DD` and attribution cells are the driver's to stamp at freeze;
the `ROW_ACTIVE_RE` grammar is `Active (<who>, YYYY-MM-DD)`,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Status: Active
Tracker: RIG-2794

> **Extends #625 (frozen).** This record is a sibling amendment to
> `docs/designs/product/compass-linear-agent-responder/design.md` (merged in
> `docs/designs/server/compass-linear-agent-responder/design.md` (merged in
> #625). The merged record is frozen; per house convention a later change ADDS
> a record. This amendment changes ONE thing in that record's Part 3 return
> path: WHERE the session's `externalUrls` link points — a stable
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Status: Active
Tracker: RIG-2717

> **Extends #625 (frozen).** This record is a sibling amendment to
> `docs/designs/product/compass-linear-agent-responder/design.md` (merged in
> `docs/designs/server/compass-linear-agent-responder/design.md` (merged in
> #625). The merged record is frozen; per house convention a later change ADDS
> a record. This amendment changes two things about the frozen record's Part 1 /
> T7 webhook receiver: (1) the mount **path** moves from bare `/webhooks` to
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ Status: Active
Tracker: SEA

> **Extends #995 (frozen).** This record is a sibling amendment to
> `docs/designs/product/compass-server-ownership-layer/design.md` (merged in
> `docs/designs/server/compass-server-ownership-layer/design.md` (merged in
> #995). The merged record is frozen; per sealed convention a later change ADDS
> a record. This amendment reconciles #995's forge-shaped proto type family to
> the single canonical `compass.v1` family frozen by
> `docs/designs/product/compass-issue-model/design.md` (#1018).
> `docs/designs/server/compass-issue-model/design.md` (#1018).

## Problem / Intent

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@ Status: Active
> (store + comms), compass-agent (tools), compass-ui, compass-runner (gateway).
> **Supersedes by citation** (never rewrites the merged records):
> `compass-0.8-threading-and-session-renderer` (retired, RIG-2453),
> [compass-threading-ui](../compass-threading-ui/design.md),
> [compass-slack-thread-rendering](../compass-slack-thread-rendering.md),
> [compass-threading-ui](../../product/compass-threading-ui/design.md),
> [compass-slack-thread-rendering](../../product/compass-slack-thread-rendering.md),
> ledger rows **DL-040** and **DL-041**, and **RIG-1364 T3's conversation
> write-through** (the streamed-turn → comms auto-post path — D7/T7);
> **clarifies** DL-037, DL-029, DL-028, DL-072. The ledger delta ships in this
Expand Down
2 changes: 1 addition & 1 deletion go/internal/forge/golden_capture_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ package forge

// Wire canonicalization + fixture derivation for the -update live-capture path
// (leg 2 of the forge integration-testing record,
// docs/designs/product/compass-forge-integration-testing/design.md §T2; RIG-2229).
// docs/designs/server/compass-forge-integration-testing/design.md §T2; RIG-2229).
//
// This file is UNTAGGED on purpose: the canonicalization logic and its
// invariants run in the normal credential-free `go test ./internal/forge/`
Expand Down
2 changes: 1 addition & 1 deletion go/internal/forge/golden_test.go
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package forge

// Golden-fixture replay (leg 1 of the forge integration-testing record,
// docs/designs/product/compass-forge-integration-testing/design.md §T1). A
// docs/designs/server/compass-forge-integration-testing/design.md §T1). A
// plain, untagged test that replays committed request/response fixtures from
// testdata/<provider>/ through the existing scriptedRoundTripper stub against
// the REAL forge clients, asserting BOTH halves of each exchange: the request
Expand Down
2 changes: 1 addition & 1 deletion go/internal/forge/livegithub_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
package forge

// Live-credentials oracle suite (leg 2 of the forge integration-testing record,
// docs/designs/product/compass-forge-integration-testing/design.md §T2). Guarded
// docs/designs/server/compass-forge-integration-testing/design.md §T2). Guarded
// by //go:build livegithub so a bare `go test ./internal/forge/` never compiles
// it — the untagged golden battery (golden_test.go) stays credential-free.
//
Expand Down
2 changes: 1 addition & 1 deletion go/internal/gen/compass/v1/forge.pb.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion go/internal/linearagent/routing.go
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package linearagent

// Responder routing resolution (RIG-2717 T4, design
// docs/designs/product/compass-linear-agent-responder/design.md §Part 2 / §T4).
// docs/designs/server/compass-linear-agent-responder/design.md §Part 2 / §T4).
//
// A Linear delegation or @mention names the Compass app, never a specific
// Manager, so the bridge must resolve which stable Manager runs the session.
Expand Down
2 changes: 1 addition & 1 deletion go/internal/store/forge_authored.go
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import (
)

// The DL-055 forge ownership index (design
// docs/designs/product/compass-forge-write-path/design.md §T7): the durable
// docs/designs/server/compass-forge-write-path/design.md §T7): the durable
// record of every forge artifact Compass AUTHORED on behalf of an agent. The
// write chokepoint (T4) records the row AND the F3 idempotency memo in one
// statement on a create success; a provider error records nothing. The dedup
Expand Down
2 changes: 1 addition & 1 deletion go/internal/store/forge_authored_pgtest_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
package store

// DL-055 forge ownership-index store contracts (design
// docs/designs/product/compass-forge-write-path/design.md §T7 test cycle, the
// docs/designs/server/compass-forge-write-path/design.md §T7 test cycle, the
// DL-174 pair: this pgtest suite plus the in-memory reference in
// forge_authored_test.go): the migration 0002 table shape, the idempotent
// coordinate upsert, the FK RESTRICT on agent/owner, the by-agent scan order,
Expand Down
2 changes: 1 addition & 1 deletion go/internal/store/forge_authored_test.go
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package store

// The hermetic default-gate half of the DL-174 pair for the DL-055 ownership
// index (design docs/designs/product/compass-forge-write-path/design.md §T7):
// index (design docs/designs/server/compass-forge-write-path/design.md §T7):
// the pure-Go contract that needs no Postgres — the pre-DB argument guards, the
// empty-clientRequestID always-miss short-circuit, and the NULL client_request_id
// mapping. The real-Postgres row contracts live in the pgtest sibling
Expand Down
2 changes: 1 addition & 1 deletion go/internal/store/forge_subscriptions.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ import (
)

// The DL-053 agent-notification subscription writer (RIG-2732 Piece 1, design
// docs/designs/product/compass-notification-delivery/design.md): the Server-side
// docs/designs/server/compass-notification-delivery/design.md): the Server-side
// Postgres row that records an agent's standing interest in one forge artifact.
// agent_forge_subscriptions is the per-subscriber DELIVERY-cursor table
// (delivered_revision/delivered_at); forge_artifact_cursors is the shared
Expand Down
2 changes: 1 addition & 1 deletion go/server/forge_e2e_pgtest_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
package server

// End-to-end T8 of the FROZEN Compass forge-write design
// (docs/designs/product/compass-forge-write-path/design.md §T8, acceptance
// (docs/designs/server/compass-forge-write-path/design.md §T8, acceptance
// :876-885): the WHOLE agent-initiated forge-WRITE wire, driven over a REAL
// per-container AgentGateway unix socket against a real Postgres + a real
// Runner-over-stub-engine, with the forge chokepoint mounted on the
Expand Down
2 changes: 1 addition & 1 deletion go/server/serve.go
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,7 @@ type ForgeConfig struct {

// ForgeAppConfig is the GitHub App credential the board webhook-ingestion lane
// runs on (RIG-2883, frozen surface at
// docs/designs/product/compass-forge-agent-notification/design.md:1035-1048).
// docs/designs/server/compass-forge-agent-notification/design.md:1035-1048).
// The lane runs iff AppID != 0 AND both AppPrivateKeySecret and
// AppWebhookSecretName are declared (mirrors validateForgeSecret's fail-fast);
// no App -> board ingestion hard-off with a boot Warn (Constraint #3).
Expand Down
2 changes: 1 addition & 1 deletion packages/compass-agent/src/gen/compass/v1/forge_pb.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// The compass.v1 forge notification + shared carrier leaf (RIG-1731 A1, design
// docs/designs/product/compass-server-ownership-layer-amendment/design.md §A1).
// docs/designs/server/compass-server-ownership-layer-amendment/design.md §A1).
//
// INTERNAL-ONLY surface. Like agent.proto / agent_gateway.proto / runner.proto,
// and unlike compass.proto / comms.proto (the public generated-client door
Expand Down
2 changes: 1 addition & 1 deletion proto/compass/v1/forge.proto
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// The compass.v1 forge notification + shared carrier leaf (RIG-1731 A1, design
// docs/designs/product/compass-server-ownership-layer-amendment/design.md §A1).
// docs/designs/server/compass-server-ownership-layer-amendment/design.md §A1).
//
// INTERNAL-ONLY surface. Like agent.proto / agent_gateway.proto / runner.proto,
// and unlike compass.proto / comms.proto (the public generated-client door
Expand Down
Loading