From 40aceb18551c8b76ddc72d1086507f29bed43bb2 Mon Sep 17 00:00:00 2001 From: mintaka Date: Mon, 31 Aug 2026 19:16:55 -0400 Subject: [PATCH 1/2] =?UTF-8?q?refactor(design-docs):=20dissolve=20product?= =?UTF-8?q?/=20into=20meta/=20=E2=80=94=20process/method=20records=20(RIG-?= =?UTF-8?q?2577=20T8)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move the four process/method records that govern the corpus and the product's engineering posture out of the dissolving product/ bucket into the ruled top-level meta/ bucket (RIG-2577 §Approach 2): - compass-architecture-lineage/ - compass-design-ledger/ - compass-test-strategy/ - compass-tier3-scope-gate/ meta/ is already a governed root (tools/design-ledger-gate GOVERNED_ROOTS), so the records stay governed across the move; no Status normalization is needed (product records already carry gate-grammar headers). Same-PR link integrity (RIG-2577 Global Constraints): - 40 DECISIONS.md Record cells re-pointed product// -> meta// (row count unchanged at 277; pure relocation, no decision changed). - 2 inbound cross-bucket body links from product/ records re-pointed to the stable ../../meta/compass-architecture-lineage/design.md form. - External citation sweep: gate header/message strings (tools/design-ledger-gate), 2 UI test comment/message strings, and 3 other-bucket record prose citations (infra/runtime, observability, product) re-pointed to meta/. Verified: design-ledger-gate OK (277 rows, 119 headers); eng-docs gather 73/73; UI design-citations + identity tests 14/14; no dangling product/ refs to moved records remain. Ledger-impact: records relocated within governance, no decision changed Co-authored-by: Matt Wilkinson --- apps/ui/src/design-citations.test.ts | 4 +- apps/ui/src/identity.test.ts | 2 +- docs/designs/DECISIONS.md | 80 +++++++++---------- .../compass-managed-multitenancy/design.md | 4 +- .../compass-architecture-lineage/design.md | 0 .../compass-design-ledger/design.md | 0 .../compass-test-strategy/design.md | 2 +- .../compass-tier3-scope-gate/design.md | 0 .../design.md | 2 +- .../product/compass-ade-shell/design.md | 2 +- .../compass-agent-comms-tools/design.md | 2 +- .../product/compass-command-palette/design.md | 4 +- .../design.md | 12 +-- tools/design-ledger-gate/index.ts | 4 +- 14 files changed, 59 insertions(+), 59 deletions(-) rename docs/designs/{product => meta}/compass-architecture-lineage/design.md (100%) rename docs/designs/{product => meta}/compass-design-ledger/design.md (100%) rename docs/designs/{product => meta}/compass-test-strategy/design.md (99%) rename docs/designs/{product => meta}/compass-tier3-scope-gate/design.md (100%) diff --git a/apps/ui/src/design-citations.test.ts b/apps/ui/src/design-citations.test.ts index c8f70491c..5059bd934 100644 --- a/apps/ui/src/design-citations.test.ts +++ b/apps/ui/src/design-citations.test.ts @@ -1,7 +1,7 @@ // Source-hygiene gate: no retired-milestone design citations survive in shipped // UI source. The early Compass milestone records (v0.3 through v0.8) were // retired (RIG-2453); their still-true rationale was consolidated into -// `docs/designs/product/compass-architecture-lineage/design.md` and every +// `docs/designs/meta/compass-architecture-lineage/design.md` and every // shipped citation re-pointed there. // // A vintage provenance tag naming a retired milestone — `design compass-0.6`, @@ -73,7 +73,7 @@ describe("design-citation hygiene (no retired-milestone design refs)", () => { expect( violations, violations.length > 0 - ? `Retired-milestone design citations found in shipped source — re-point to the architecture-lineage record (docs/designs/product/compass-architecture-lineage/design.md):\n${report}` + ? `Retired-milestone design citations found in shipped source — re-point to the architecture-lineage record (docs/designs/meta/compass-architecture-lineage/design.md):\n${report}` : "", ).toEqual([]); }); diff --git a/apps/ui/src/identity.test.ts b/apps/ui/src/identity.test.ts index 1495dc0f5..6af1e3d59 100644 --- a/apps/ui/src/identity.test.ts +++ b/apps/ui/src/identity.test.ts @@ -14,7 +14,7 @@ import { STUB_AGENTS, STUB_ISSUES } from "./stub-data"; import { testQueryClient } from "./test-support"; // T1 — Agent identity: separate co-addressed types + fixture reconciliation -// (design record `docs/designs/product/compass-architecture-lineage/design.md`, +// (design record `docs/designs/meta/compass-architecture-lineage/design.md`, // T1 §282-400). RED-FIRST: this suite is authored against T1's specified surface // — the account-kind `Agent`/`Account` in stub-data.ts (design.md:325-362), the // cached `account.homeChannelId` (:339,367-369), the derived `STUB_ACCOUNTS` diff --git a/docs/designs/DECISIONS.md b/docs/designs/DECISIONS.md index c62372c69..4de3cf4f6 100644 --- a/docs/designs/DECISIONS.md +++ b/docs/designs/DECISIONS.md @@ -17,7 +17,7 @@ and flipped, never frozen. The rules that keep it honest (append-only rows, immutable `Decision` cells, the same-PR flip that a design PR owes its ledger delta) live in the design record and `AGENTS.md`; the `design-ledger-gate` CI check enforces the mechanical half. Full rationale: -[the design-ledger record](product/compass-design-ledger/design.md). +[the design-ledger record](meta/compass-design-ledger/design.md). ## Conventions @@ -38,33 +38,33 @@ check enforces the mechanical half. Full rationale: | ID | Decision | Status | Record | | --- | --- | --- | --- | -| DL-001 | Compass is an agent development environment: named workstream agents supervised by a Dispatcher, gated by a Warden | Superseded by DL-239 (Matt, 2026-08-21) | [architecture lineage](product/compass-architecture-lineage/design.md) | -| DL-002 | OMP is the default/reference agent, carried as an external OSS fork; Compass builds on it, does not rebuild it | Active (Matt, 2026-07-01) | [architecture lineage](product/compass-architecture-lineage/design.md) | -| DL-003 | seal is scoped to hosting the Warden, not the whole runtime | Retired (Matt, 2026-08-21) | [architecture lineage](product/compass-architecture-lineage/design.md) | -| DL-004 | Adopt Cotal as the coordination substrate behind a thin Compass-owned seam | Superseded by DL-005 (Matt, 2026-07-04) | [architecture lineage](product/compass-architecture-lineage/design.md) | -| DL-005 | The NATS/JetStream substrate is kept, but Cotal moves from adopted dependency to reference implementation; comms is first-party behind a Compass seam | Superseded by DL-021 (Matt, 2026-07-04) | [architecture lineage](product/compass-architecture-lineage/design.md) | -| DL-006 | Upstream contribution to OMP is a distribution channel, not a governance dependency | Active (Matt, 2026-07-01) | [architecture lineage](product/compass-architecture-lineage/design.md) | +| DL-001 | Compass is an agent development environment: named workstream agents supervised by a Dispatcher, gated by a Warden | Superseded by DL-239 (Matt, 2026-08-21) | [architecture lineage](meta/compass-architecture-lineage/design.md) | +| DL-002 | OMP is the default/reference agent, carried as an external OSS fork; Compass builds on it, does not rebuild it | Active (Matt, 2026-07-01) | [architecture lineage](meta/compass-architecture-lineage/design.md) | +| DL-003 | seal is scoped to hosting the Warden, not the whole runtime | Retired (Matt, 2026-08-21) | [architecture lineage](meta/compass-architecture-lineage/design.md) | +| DL-004 | Adopt Cotal as the coordination substrate behind a thin Compass-owned seam | Superseded by DL-005 (Matt, 2026-07-04) | [architecture lineage](meta/compass-architecture-lineage/design.md) | +| DL-005 | The NATS/JetStream substrate is kept, but Cotal moves from adopted dependency to reference implementation; comms is first-party behind a Compass seam | Superseded by DL-021 (Matt, 2026-07-04) | [architecture lineage](meta/compass-architecture-lineage/design.md) | +| DL-006 | Upstream contribution to OMP is a distribution channel, not a governance dependency | Active (Matt, 2026-07-01) | [architecture lineage](meta/compass-architecture-lineage/design.md) | | DL-095 | The agent tree is Compass's organizing primitive — Compass is a tool to build and manage agent trees: `AgentAccount` carries `parent_agent_id` (field 4; empty = root, set at creation — the spawning agent, or user choice — and editable thereafter via a `ReparentAgent` mutation, so users iterate hierarchy without teardown), the workspaces sidebar and board views derive from and filter by the tree, REPLACING the user-defined folder organization (replace, not coexist); channels (RIG-1622) and roles (RIG-1623) compose onto the tree later | Active (Matt, 2026-08-01) | [agent trees §Approach](product/compass-agent-trees/design.md#approach) | -| DL-239 | Compass is an agent development environment: named workstream agents supervised by a Dispatcher (the corrected ADE core definition — the Warden security-auditor concept of DL-001 is scrapped, so the gate-by-a-Warden clause is dropped; the ADE, named-workstream-agents, and Dispatcher legs stand) | Active (Matt, 2026-08-21) | [architecture lineage](product/compass-architecture-lineage/design.md) | +| DL-239 | Compass is an agent development environment: named workstream agents supervised by a Dispatcher (the corrected ADE core definition — the Warden security-auditor concept of DL-001 is scrapped, so the gate-by-a-Warden clause is dropped; the ADE, named-workstream-agents, and Dispatcher legs stand) | Active (Matt, 2026-08-21) | [architecture lineage](meta/compass-architecture-lineage/design.md) | ## Topology & tiers | ID | Decision | Status | Record | | --- | --- | --- | --- | -| DL-007 | Architecture is three tiers: Client → Server → Runner, with the communication layer as the spine | Active (Matt, 2026-07-04) | [architecture lineage](product/compass-architecture-lineage/design.md) | -| DL-008 | Evolve `compass.v1` from a local daemon contract into the Client↔Server contract (multi-user) | Active (Matt, 2026-07-04) | [architecture lineage](product/compass-architecture-lineage/design.md) | -| DL-009 | The Server tier realizes the reserved hosted-mode transport seam | Active (Matt, 2026-07-04) | [architecture lineage](product/compass-architecture-lineage/design.md) | -| DL-010 | Multi-agent orchestration (Supervisor + Bridge) is in the MVP; single-agent is the first build increment | Active (Matt, 2026-07-04) | [architecture lineage](product/compass-architecture-lineage/design.md) | -| DL-011 | The Server tier is built by promoting `compass-daemon` in place, not a new server crate | Active (Matt, 2026-07-08) | [architecture lineage](product/compass-architecture-lineage/design.md) | -| DL-012 | The authenticated network door is rustls-via-tonic TLS + bearer-token accounts (in-memory token store for T2) | Active (Matt, 2026-07-08) | [architecture lineage](product/compass-architecture-lineage/design.md) | +| DL-007 | Architecture is three tiers: Client → Server → Runner, with the communication layer as the spine | Active (Matt, 2026-07-04) | [architecture lineage](meta/compass-architecture-lineage/design.md) | +| DL-008 | Evolve `compass.v1` from a local daemon contract into the Client↔Server contract (multi-user) | Active (Matt, 2026-07-04) | [architecture lineage](meta/compass-architecture-lineage/design.md) | +| DL-009 | The Server tier realizes the reserved hosted-mode transport seam | Active (Matt, 2026-07-04) | [architecture lineage](meta/compass-architecture-lineage/design.md) | +| DL-010 | Multi-agent orchestration (Supervisor + Bridge) is in the MVP; single-agent is the first build increment | Active (Matt, 2026-07-04) | [architecture lineage](meta/compass-architecture-lineage/design.md) | +| DL-011 | The Server tier is built by promoting `compass-daemon` in place, not a new server crate | Active (Matt, 2026-07-08) | [architecture lineage](meta/compass-architecture-lineage/design.md) | +| DL-012 | The authenticated network door is rustls-via-tonic TLS + bearer-token accounts (in-memory token store for T2) | Active (Matt, 2026-07-08) | [architecture lineage](meta/compass-architecture-lineage/design.md) | | DL-312 | Servers are stateless L7-load-balanced instances (any Server handles any client request); Runners are individually subject-addressable over a message-bus fabric (one FABRIC connection per party — plus the reduced Connect authn/RPC edge per DL-316), never single-Server-owns-Runners and never an N×M direct-stream mesh; delivery to a live client routes over a per-connection subject to the one Server holding the socket; session→Runner routing truth stays durable in Postgres (`agent_placements` + session bindings), and the Runner remains a pure forwarder with Server-side fail-closed account resolution | Active (Matt, 2026-08-31) | [multi-tenancy & NATS substrate](infra/runtime/compass-managed-multitenancy/design.md#q2--serverrunner-connection-topology-load-balanced-servers-subject-addressable-runners) | ## Transport | ID | Decision | Status | Record | | --- | --- | --- | --- | -| DL-013 | Transport is gRPC everywhere (Client↔Server and Runner↔Server), authenticated by per-Runner provisioned tokens | Superseded by DL-316 (Matt, 2026-08-31) | [architecture lineage](product/compass-architecture-lineage/design.md) | -| DL-014 | NATS/JetStream is not a Client/Runner-facing transport; it is comms-internal only | Superseded by DL-313 (Matt, 2026-08-31) | [architecture lineage](product/compass-architecture-lineage/design.md) | +| DL-013 | Transport is gRPC everywhere (Client↔Server and Runner↔Server), authenticated by per-Runner provisioned tokens | Superseded by DL-316 (Matt, 2026-08-31) | [architecture lineage](meta/compass-architecture-lineage/design.md) | +| DL-014 | NATS/JetStream is not a Client/Runner-facing transport; it is comms-internal only | Superseded by DL-313 (Matt, 2026-08-31) | [architecture lineage](meta/compass-architecture-lineage/design.md) | | DL-015 | The in-container agent talks to the Runner alone (Runner-sole topology), off stdio, over a `RunnerCallTransport` seam | Active (Matt, 2026-07-21) | [agent↔Runner transport §Decisions](product/compass-agent-runner-transport/design.md#decisions-frozen-by-matt--not-reopened-below) | | DL-016 | The concrete agent↔Runner transport is a per-container Unix socket, 1:1 with a session; network transport is a future additive | Superseded by DL-017 (Matt, 2026-07-21) | [agent↔Runner transport §The concrete impl](product/compass-agent-runner-transport/design.md#the-concrete-impl-unix-socket-per-container) | | DL-017 | Consolidate agent↔Runner onto socket streams: telemetry via `Publish` client-stream, control via `Control` server-stream on `AgentGateway`; retire the protocol stdio pipe | Active (Matt, 2026-07-22) | [transport consolidation §What is superseded](product/compass-agent-transport-consolidation/design.md#what-is-superseded-exactly) | @@ -76,10 +76,10 @@ check enforces the mechanical half. Full rationale: | ID | Decision | Status | Record | | --- | --- | --- | --- | -| DL-019 | Postgres is the store of record; transcript bodies live in object storage behind a blob seam; JetStream is comms-only | Superseded by DL-314 (Matt, 2026-08-31) | [architecture lineage](product/compass-architecture-lineage/design.md) | -| DL-020 | Postgres is the substrate and is not swappable; the in-memory event bus is a cache/fan-out ring, not a second store | Active (Matt, 2026-07-06) | [architecture lineage](product/compass-architecture-lineage/design.md) | -| DL-021 | The comms substrate is Postgres write-through fan-out, not a swappable NATS-backed seam | Superseded by DL-313 (Matt, 2026-08-31) | [architecture lineage](product/compass-architecture-lineage/design.md) | -| DL-022 | Config distribution is a Runner-mediated pull into a read-only mount; agent binary + base image ride versioned OCI pulls | Active (Matt, 2026-07-04) | [architecture lineage](product/compass-architecture-lineage/design.md) | +| DL-019 | Postgres is the store of record; transcript bodies live in object storage behind a blob seam; JetStream is comms-only | Superseded by DL-314 (Matt, 2026-08-31) | [architecture lineage](meta/compass-architecture-lineage/design.md) | +| DL-020 | Postgres is the substrate and is not swappable; the in-memory event bus is a cache/fan-out ring, not a second store | Active (Matt, 2026-07-06) | [architecture lineage](meta/compass-architecture-lineage/design.md) | +| DL-021 | The comms substrate is Postgres write-through fan-out, not a swappable NATS-backed seam | Superseded by DL-313 (Matt, 2026-08-31) | [architecture lineage](meta/compass-architecture-lineage/design.md) | +| DL-022 | Config distribution is a Runner-mediated pull into a read-only mount; agent binary + base image ride versioned OCI pulls | Active (Matt, 2026-07-04) | [architecture lineage](meta/compass-architecture-lineage/design.md) | | DL-052 | Only the Server holds forge write credentials, as a `server_only` declared secret filtered out of container injection — a NEW scoping mechanism this record introduces, since none exists in the tree. The agent keeps a push-scoped git credential. The boundary that creates is half enforced (the filter, which Compass controls and tests) and half operator hygiene (the agent token's scope, which Compass neither mints nor inspects); closing the second half would require Compass to hold secret values, which today it deliberately never does | Active (Matt, 2026-07-27) | [ownership layer §Decision 4](product/compass-server-ownership-layer/design.md#decision-4--the-servers-forge-credential-is-a-declared-secret-resolved-not-stored) | | DL-053 | Forge subscriptions are Server-side Postgres rows with a per-artifact FETCH cursor (advanced on any 200) split from a per-subscriber DELIVERY cursor (advanced only on that subscriber's own successful notify), change-detected by conditional polling in v1 (webhooks are an additive accelerator), delivered by account on the existing `Sessions` → `AgentGateway.Control` push path | Active (Matt, 2026-07-27) | [ownership layer §Decision 5](product/compass-server-ownership-layer/design.md#decision-5--subscriptions-server-stored-poll-based-in-v1-delivered-on-the-existing-push-path) | | DL-055 | Compass stores a row per artifact it authored (coordinate + agent + owner + session, written with the stamp), so agent ownership queries and the Bridge boards are local index scans over Server-recorded truth rather than forge-wide searches of untrusted header text; it is an ownership index, never a mirror of forge content | Active (Matt, 2026-07-27) | [ownership layer §OQ-8](product/compass-server-ownership-layer/design.md#oq-8-ruled-2026-07-27-matt--recommendation-reversed--does-a-compass-authored-artifact-need-a-compass-side-record) | @@ -123,12 +123,12 @@ check enforces the mechanical half. Full rationale: | ID | Decision | Status | Record | | --- | --- | --- | --- | -| DL-023 | The in-container agent is a first-party program on the OMP SDK, emitting `compass.v1` natively | Active (Matt, 2026-07-06) | [architecture lineage](product/compass-architecture-lineage/design.md) | -| DL-024 | Each agent runs in a per-agent container on the Runner for blast-radius isolation, not credential avoidance | Active (Matt, 2026-07-06) | [architecture lineage](product/compass-architecture-lineage/design.md) | +| DL-023 | The in-container agent is a first-party program on the OMP SDK, emitting `compass.v1` natively | Active (Matt, 2026-07-06) | [architecture lineage](meta/compass-architecture-lineage/design.md) | +| DL-024 | Each agent runs in a per-agent container on the Runner for blast-radius isolation, not credential avoidance | Active (Matt, 2026-07-06) | [architecture lineage](meta/compass-architecture-lineage/design.md) | | DL-025 | Container base image is self-contained; the agent manages its own devenv | Active (Matt, 2026-07-15) | [agent container runtime §Decision 1](product/compass-agent-container-runtime.md#decision-1--self-contained-base-image-the-agent-manages-its-own-devenv) | | DL-026 | Secrets are a Server-side SecretSpec + keyring store with inject-all, no repo manifest | Active (Matt, 2026-07-15) | [agent container runtime §Decision 2](product/compass-agent-container-runtime.md#decision-2--secrets-store-secretspec--keyring-server-side-no-repo-manifest-inject-all) | | DL-027 | No in-container supervisor for the MVP | Active (Matt, 2026-07-15) | [agent container runtime §Decision 4](product/compass-agent-container-runtime.md#decision-4--no-in-container-supervisor-for-mvp) | -| DL-047 | The agent is integrated via ACP/BYOA over stdio, with OMP as the external default over ACP and other agents as BYOA citizens | Superseded by DL-023 (Matt, 2026-07-06) | [architecture lineage](product/compass-architecture-lineage/design.md) | +| DL-047 | The agent is integrated via ACP/BYOA over stdio, with OMP as the external default over ACP and other agents as BYOA citizens | Superseded by DL-023 (Matt, 2026-07-06) | [architecture lineage](meta/compass-architecture-lineage/design.md) | | DL-078 | Agent config (skills/extensions/MCP configs) is declared into a Server-side FLEET-WIDE bundle store (one bundle all agents get) via new operator-scoped CompassService RPCs, never pushed as provision-request fields; the recommended MVP authoring workflow is a version-controlled config repo published via a CI `compass config put` step; persona/role-keyed bundles and native GitOps pull (Server reconciles a config repo) are the named post-MVP seams | Active (Matt, 2026-07-30) | [config delivery §Decision CD-1](product/compass-agent-config-delivery/design.md#decision-cd-1--declaration-surface-a-server-side-fleet-wide-bundle-store) | | DL-079 | Config carriage is Runner-fetch — a server-STREAMING `FetchAgentConfig` RPC + a `ConfigVersion` signal on the Sessions response stream (signal-then-pull over the frozen dial-out inversion; no inbound Server→Runner route) | Active (Matt, 2026-07-30) | [config delivery §Decision CD-2](product/compass-agent-config-delivery/design.md#decision-cd-2--carriage-streaming-runner-fetch-over-the-frozen-inversion) | | DL-080 | Config injection is a Runner-local read-only bind mount of the parent config dir at `/run/compass/agent-config` (agent reads through `current/`); env-vars ride RIG-1327's secret surface exclusively; MVP forbids credentials in MCP configs (RIG-1576 tracks the post-MVP credentialed path) | Active (Matt, 2026-07-30) | [config delivery §Decision CD-3](product/compass-agent-config-delivery/design.md#decision-cd-3--injection-per-config-type) | @@ -213,8 +213,8 @@ check enforces the mechanical half. Full rationale: | ID | Decision | Status | Record | | --- | --- | --- | --- | -| DL-030 | UI: the communication layer is the primary surface (comms-primary shell) | Superseded by DL-031 (Matt, 2026-07-06) | [architecture lineage](product/compass-architecture-lineage/design.md) | -| DL-031 | UI shell is board-primary: channel chat lives inside the board-primary workspace, not as the top-level surface | Active (Matt, 2026-07-12) | [architecture lineage](product/compass-architecture-lineage/design.md) | +| DL-030 | UI: the communication layer is the primary surface (comms-primary shell) | Superseded by DL-031 (Matt, 2026-07-06) | [architecture lineage](meta/compass-architecture-lineage/design.md) | +| DL-031 | UI shell is board-primary: channel chat lives inside the board-primary workspace, not as the top-level surface | Active (Matt, 2026-07-12) | [architecture lineage](meta/compass-architecture-lineage/design.md) | | DL-032 | Compass state is canonical; the tracker is a projection of it | Superseded by DL-129 (Matt, 2026-08-04) | [ADE shell §D2](product/compass-ade-shell/design.md#d2--compass-state-is-canonical-the-tracker-is-a-projection) | | DL-033 | The workstream lifecycle is Backlog→Todo→Queued→Blocked⇄In Progress→In Review→Done | Active (Matt, 2026-07-10) | [ADE shell §D1](product/compass-ade-shell/design.md#d1--workstream-state-model) | | DL-034 | The right sidebar mirrors Orca; fleet + workstream conversations live there | Active (Matt, 2026-07-10) | [ADE shell §D5](product/compass-ade-shell/design.md#d5--right-sidebar-mirrors-orca) | @@ -250,9 +250,9 @@ check enforces the mechanical half. Full rationale: | ID | Decision | Status | Record | | --- | --- | --- | --- | -| DL-038 | The session trace is a dedicated OMP-native opaque session stream, rendered by OMP's own renderer | Superseded by DL-039 (Matt, 2026-07-20) | [architecture lineage](product/compass-architecture-lineage/design.md) | -| DL-039 | Compass builds a first-party typed session renderer; session events cross a typed gRPC stream, not opaque bytes and explicitly not ACP | Active (Matt, 2026-07-20) | [architecture lineage](product/compass-architecture-lineage/design.md) | -| DL-040 | Threaded replies use a Slack-style side-thread panel keyed by a deterministic root id | Superseded by DL-098 (Matt, 2026-08-02) | [architecture lineage](product/compass-architecture-lineage/design.md) | +| DL-038 | The session trace is a dedicated OMP-native opaque session stream, rendered by OMP's own renderer | Superseded by DL-039 (Matt, 2026-07-20) | [architecture lineage](meta/compass-architecture-lineage/design.md) | +| DL-039 | Compass builds a first-party typed session renderer; session events cross a typed gRPC stream, not opaque bytes and explicitly not ACP | Active (Matt, 2026-07-20) | [architecture lineage](meta/compass-architecture-lineage/design.md) | +| DL-040 | Threaded replies use a Slack-style side-thread panel keyed by a deterministic root id | Superseded by DL-098 (Matt, 2026-08-02) | [architecture lineage](meta/compass-architecture-lineage/design.md) | | DL-041 | The message surface is a virtualized thread list with streaming markdown (solid-markdown + Shiki), mention-first composition | Superseded by DL-098 (Matt, 2026-08-02) | [message surface rendering §Approach](product/compass-message-surface-rendering/design.md#approach) | | DL-098 | Compass adopts Zulip's threading model: a channel is a collection of named topics and every message belongs to exactly one topic (`messages.topic_id NOT NULL`) and stores only that topic id — never a channel id; the channel is reached through `topics.channel_id` (so moving a topic between channels is a single-row update). `parent_message_id` and the message's channel container are removed outright (pre-dogfood: no reserved tombstone, field numbers reused). Topics are first-class (proto `Topic` + `topics` table), named, id-stable, in exactly one channel; posting is topic-mandatory via `topic_name` get-or-create (one call); there is no default, general, or catch-all topic anywhere — channels carry zero messages directly. Rename-to-existing merges topics; the delivery cursor stays per-(agent,channel) with topic as deliver-op metadata, its channel resolved through the topic join (clarifies DL-072). The pre-dogfood SQL migrations collapse to a single baseline (no data conversion). UI is Zulip two-level drill-in: a channel shows its topic index (no composer), a topic shows its messages + composer (no nested threading), the left sidebar lists a channel's recent topics. Reverses DL-040 (Slack side-thread panel) and DL-041 (virtualized thread list, re-pointed at the topic list) | Active (Matt, 2026-08-02) | [Zulip threading model §Decisions](product/compass-zulip-threading-model/design.md#decisions-ratified) | | DL-099 | An agent's streamed turn does not write to comms at all: the RIG-1364 T3 conversation write-through (streamed-turn → home-channel comms auto-post) is removed. A comms `Message` is created only by an explicit `comms_post_message(topic)` call (agents) or the human client's PostMessage — the comms tool is the only agent comms-write path, and it carries a mandatory topic. The streamed turn survives in full on the session/trace surface (`SessionFrame.typed_event`). Structural enforcement of on-topic posting: an agent cannot flood a channel by talking, only by deliberately posting | Active (Matt, 2026-08-02) | [Zulip threading model §D7](product/compass-zulip-threading-model/design.md#d7--one-comms-write-path-the-streaming-write-through-is-removed-supersedes-rig-1364-t3) | @@ -261,7 +261,7 @@ check enforces the mechanical half. Full rationale: | ID | Decision | Status | Record | | --- | --- | --- | --- | -| DL-042 | The UI pivots around the communication layer; the frozen single-question `compass.v1.Ask` is D5's contract child | Superseded by DL-043 (Matt, 2026-07-04) | [architecture lineage](product/compass-architecture-lineage/design.md) | +| DL-042 | The UI pivots around the communication layer; the frozen single-question `compass.v1.Ask` is D5's contract child | Superseded by DL-043 (Matt, 2026-07-04) | [architecture lineage](meta/compass-architecture-lineage/design.md) | | DL-043 | Reshape `compass.v1.Ask` to `repeated AskQuestion` (Option A, buf-breaking), carrying all native axes + free-text | Active (Matt, 2026-07-15) | [ask typed derivation §Approach](product/compass-ask-typed-derivation.md#approach--option-a-reshape-ask--repeated-askquestion-buf-breaking) | | DL-213 | Outbound realization of an ask moves off the dead AgentFrame conversation-frame path onto the live comms `PostMessage` lane: the `mapping.ts #deriveAsk` → AgentFrame derivation the ask-typed-derivation record specified is superseded by citation (the outbound `AgentFrame` oneof has no conversation/Ask variant — fields 1-2 REMOVED per F9, `agent.proto:46-85` — and `mapping.ts` has no ask arm). DL-043's `Ask = repeated AskQuestion` SHAPE stays Active and live — it is exactly the shape both lanes of DL-211 ride (`comms.proto:361-427`); only the derivation MECHANISM is dead | Active (Matt, 2026-08-18) | [ask comms round-trip §AgentFrame reconciliation](product/compass-ask-comms-roundtrip/design.md#the-agentframe-reconciliation-dl-043) | @@ -326,14 +326,14 @@ check enforces the mechanical half. Full rationale: | DL-159 | One UI codebase renders in two hosts — the Wails v3 desktop app (primary) and the browser (the managed/hosted product at `compass.rigel.build`) — over the same transport-agnostic UI above the `connection.ts` provider seam; the layout is fluid within its window/viewport (a dense supervision surface that reflows, not a fixed-pixel canvas and not a mobile redesign) (D6/§Global Constraints 2) | Active (Matt, 2026-08-05) | [ux foundation §D6](product/compass-ux-foundation/design.md#d6--rendering-the-frozen-ia-surface-by-surface-composition) | | DL-160 | The desktop app is first-class multi-window: every top-level surface (Bridge, a channel, an agent workspace, Backlog/Done, Settings) is an independently mountable window-scoped view (own DL-127 route, own focus zones + command scope, no sibling region required); compass-native spawns/manages OS windows, this record owns the decomposition; in-window tabs (Linear-style) and split views are deferred to the Beta milestone (RIG-1808), admitted by the same decomposition without rework (D6.1) | Active (Matt, 2026-08-05) | [ux foundation §D6](product/compass-ux-foundation/design.md#d6--rendering-the-frozen-ia-surface-by-surface-composition) | | DL-184 | Token adoption is a FULL CUTOVER, not the DL-157 incremental strangler: a pre-dogfood codebase has no live users to protect, so the legacy `:root` tier is deleted and every consumer flips to `--cx-*` in one atomically-merged migration (canvas → Night Owl, base.css un-shadowed, state dots recolored, D7 stylelint guard wired directly at error), proven by a Playwright visual-smoke harness Matt reviews | Active (Matt, 2026-08-07) | [DS token cutover](product/compass-ds-token-cutover/design.md) | -| DL-174 | Compass test coverage is a differential-oracle pyramid: every seam carries a hermetic in-memory reference in the default gate plus a `pgtest` suite proving the real Postgres backend obeys the same contract; Postgres is the one live dependency the strategy gates on (D1) | Active (Matt, 2026-08-07) | [test strategy §Decisions](product/compass-test-strategy/design.md#decisions) | -| DL-175 | The real-Postgres `pgtest` suites run INLINE as a step in the one existing `CI` job — no separate CI job, lane, or moon task; one required check, hermetic moon `test` stays dependency-free via the build tag (D-A1, overruling the internal monorepo ancestor's separate `test-pg` lane; Matt: "trimmed but no extra CI job, it goes in the same existing job") | Active (Matt, 2026-08-07) | [test strategy §A1](product/compass-test-strategy/design.md#a1--one-ci-job-pgtest-inline-no-separate-lane-amends-the-ancestor-records-d2dl-049) | -| DL-176 | CI Postgres is the shipped GitHub Actions SERVICE CONTAINER — digest-pinned `postgres:16-alpine`, health-gated, URL-form TCP DSN, digest kept equal to `pgtest.go`'s image pin — not the internal monorepo ancestor's per-step embedded `postgresql_18` postmaster, which solved a Woodpecker constraint compass does not have (D-A2) | Active (Matt, 2026-08-07) | [test strategy §A2](product/compass-test-strategy/design.md#a2--postgres-provisioning-in-ci-the-shipped-service-container-amends-the-ancestor-records-d4) | -| DL-177 | Require-live teeth live in the harness: `COMPASS_REQUIRE_LIVE=1` (set by the CI pgtest step) turns `RequireDSN`'s no-DSN skip path into `t.Fatal` at the one policy seam every suite passes through — layered with, not replacing, the workflow-level skipped-suite assert step (D2/S1) | Active (Matt, 2026-08-07) | [test strategy §Decisions](product/compass-test-strategy/design.md#decisions) | -| DL-178 | Whole-flow scope is one thin composing test: `runner.Dial` over TLS with a real minted Runner-kind token through the production `RunnerService` door built by `buildNetworkServer` — the one seam no suite on `main` composes; a full smoke rebuild is rejected as re-describing shipped work (D3/S2) | Active (Matt, 2026-08-07) | [test strategy §Decisions](product/compass-test-strategy/design.md#decisions) | -| DL-179 | The `podman`-tagged surface (runtime lifecycle suites and the `go/e2e/` dogfood legs) stays skip-if-absent and out of this record's gate; its CI promotion is owned by the dogfood-e2e/infra lane (D4) | Active (Matt, 2026-08-07) | [test strategy §Decisions](product/compass-test-strategy/design.md#decisions) | -| DL-180 | No browser e2e in the test pyramid: the whole-flow level is a Go/`pgtest` composing test; the UI transport is contract-tested at the frame level and the generated client factory over the bun contract lane once it lands (D5) | Active (Matt, 2026-08-07) | [test strategy §Decisions](product/compass-test-strategy/design.md#decisions) | -| DL-181 | The bun TS-client↔Go-server contract lane is filed as a follow-up feature against the compass-dogfood-e2e harness scope (it consumes that harness's bring-up and served door rather than duplicating them); it is not built from this record (D6/S3) | Active (Matt, 2026-08-07) | [test strategy §Decisions](product/compass-test-strategy/design.md#decisions) | +| DL-174 | Compass test coverage is a differential-oracle pyramid: every seam carries a hermetic in-memory reference in the default gate plus a `pgtest` suite proving the real Postgres backend obeys the same contract; Postgres is the one live dependency the strategy gates on (D1) | Active (Matt, 2026-08-07) | [test strategy §Decisions](meta/compass-test-strategy/design.md#decisions) | +| DL-175 | The real-Postgres `pgtest` suites run INLINE as a step in the one existing `CI` job — no separate CI job, lane, or moon task; one required check, hermetic moon `test` stays dependency-free via the build tag (D-A1, overruling the internal monorepo ancestor's separate `test-pg` lane; Matt: "trimmed but no extra CI job, it goes in the same existing job") | Active (Matt, 2026-08-07) | [test strategy §A1](meta/compass-test-strategy/design.md#a1--one-ci-job-pgtest-inline-no-separate-lane-amends-the-ancestor-records-d2dl-049) | +| DL-176 | CI Postgres is the shipped GitHub Actions SERVICE CONTAINER — digest-pinned `postgres:16-alpine`, health-gated, URL-form TCP DSN, digest kept equal to `pgtest.go`'s image pin — not the internal monorepo ancestor's per-step embedded `postgresql_18` postmaster, which solved a Woodpecker constraint compass does not have (D-A2) | Active (Matt, 2026-08-07) | [test strategy §A2](meta/compass-test-strategy/design.md#a2--postgres-provisioning-in-ci-the-shipped-service-container-amends-the-ancestor-records-d4) | +| DL-177 | Require-live teeth live in the harness: `COMPASS_REQUIRE_LIVE=1` (set by the CI pgtest step) turns `RequireDSN`'s no-DSN skip path into `t.Fatal` at the one policy seam every suite passes through — layered with, not replacing, the workflow-level skipped-suite assert step (D2/S1) | Active (Matt, 2026-08-07) | [test strategy §Decisions](meta/compass-test-strategy/design.md#decisions) | +| DL-178 | Whole-flow scope is one thin composing test: `runner.Dial` over TLS with a real minted Runner-kind token through the production `RunnerService` door built by `buildNetworkServer` — the one seam no suite on `main` composes; a full smoke rebuild is rejected as re-describing shipped work (D3/S2) | Active (Matt, 2026-08-07) | [test strategy §Decisions](meta/compass-test-strategy/design.md#decisions) | +| DL-179 | The `podman`-tagged surface (runtime lifecycle suites and the `go/e2e/` dogfood legs) stays skip-if-absent and out of this record's gate; its CI promotion is owned by the dogfood-e2e/infra lane (D4) | Active (Matt, 2026-08-07) | [test strategy §Decisions](meta/compass-test-strategy/design.md#decisions) | +| DL-180 | No browser e2e in the test pyramid: the whole-flow level is a Go/`pgtest` composing test; the UI transport is contract-tested at the frame level and the generated client factory over the bun contract lane once it lands (D5) | Active (Matt, 2026-08-07) | [test strategy §Decisions](meta/compass-test-strategy/design.md#decisions) | +| DL-181 | The bun TS-client↔Go-server contract lane is filed as a follow-up feature against the compass-dogfood-e2e harness scope (it consumes that harness's bring-up and served door rather than duplicating them); it is not built from this record (D6/S3) | Active (Matt, 2026-08-07) | [test strategy §Decisions](meta/compass-test-strategy/design.md#decisions) | | DL-219 | The keyboard spine lands minimal-first (Fork A-minimal): a `CommandRegistry` implementation + a `DEFAULT_KEYMAP` dispatcher + a `createRovingGroup` one-tab-stop primitive, with the Bridge board as first consumer; zone cycling, the escape ladder, pane focus, and the palette stay contracts-only until their consuming lanes flip. The spine's movement API is command-id routing through a `RovingGroupHandle`, a second surface beside the frozen 1-D `FocusZoneController.moveWithinGroup(RovingDirection)` — a later zone-controller lane delegates `moveWithinGroup` into the handle or amends `zones.ts` additively. Refines DL-151/152 (the D4/D5 focus + keymap contracts) with their first runtime. | Active (Matt, 2026-08-21) | [bridge keyboard-nav §Resolved decisions](product/compass-bridge-keyboard-nav/design.md#resolved-decisions) | | DL-220 | The Bridge 2-D cursor model — stops are cards + gutter heads (gutter = column −1, swimlane only, non-null agents), never cells; empty (`dim`) cells skipped; Up/Down column-flattened through card stacks, Left/Right row-wise with an `indexInCell` clamp (a named non-reversible asymmetry), Home/End = column first/last, edges clamp (no wrap); focus is distinct from selection (cursor moves focus, Enter selects); no ARIA `grid` role on the sparse board — stops stay `