docs(compass): migrate the design corpus, decision ledger, and ledger gate from sealed - #179
Merged
Conversation
… gate from sealed Executes eng-docs T4/T5 (folded from SEA-1794 per Matt's ruling) against the frozen `docs/designs/repo/compass-eng-docs/design.md`. compass becomes the source of truth for Compass design records; review continues here, not in sealed. ## What lands - **The sanitized design corpus** — 42 `docs/designs/product/compass-*` records + `compass.md`, plus 3 `docs/designs/platform/compass-*`. Each ran through the frozen T4 four-class sanitizer (`tools/docs-migrate/migrate.ts`): linear.app tracker links → bare `SEA-<n>` ids, `oss/compass/` path prefixes stripped, private `seal-*.md` links de-linked to prose, security sections kept verbatim. - **The decision ledger** — `docs/designs/product/DECISIONS.md`, 123 rows (the full ledger minus the two seal-product rows DL-045/046, which stay in a sealed-side residual ledger; frozen Q1). The `## Seal` section is dropped here. - **The ledger gate** — `tools/design-ledger-gate/` ported verbatim (`PRODUCT_DIR` unchanged), registered as a moon project in `.moon/workspace.yml`; swept by compass's single `moon run :ci`. - **The specs** — `docs/specs/product/compass.md` + a fresh Compass-only `README.md`. ## Ledger reconciliation (SEA-1738 batteries bundle) The `compass-batteries-included` record + its 8 ledger rows merged to sealed main (SEA-1738) after this migration's branch-cut, and its rows DL-135..142 collided with the migrating manager rows DL-135..139. Per Matt's ruling, the batteries rows are renumbered +5 → DL-140..147 (a uniform shift scoped strictly to the batteries record + its 8 rows), including the immutable in-cell cross-refs and the Record-cell anchor slugs; the manager rows keep DL-135..139. No id collision remains. ## Sanitizer gate fix The T4 gate flagged a bare `linear.app` hostname literal in a proto-field comment as residue, though the policy target is tracker *links* (`https://linear.app/…`), not a documented host string in fenced code. Narrowed the gate's linear check to the tracker-URL form the transforms strip — symmetric with the seal/oss checks — with two-sided red-green tests. ## Verification - `moon run design-ledger-gate:ci` green: gate OK — 123 ledger rows, 42 record headers valid; 71 unit tests pass; edge-clean (zero severed supersession edges, zero dangling Record links); zero duplicate ids. - `bun install --frozen-lockfile` clean; markdownlint 0 errors; biome clean. - NOTE: the eng-docs `gather.ts` is still a T1 stub (T2 unmerged), so the docsite renders a placeholder, not this corpus — the corpus is gated by design-ledger-gate + markdownlint; docsite rendering follows when T2 lands. This is PR 1 of 2. The companion sealed PR (delete side) must merge AFTER this one. Refs SEA-1794 Refs SEA-1767 Co-authored-by: Matt Wilkinson <matt@sealedsecurity.com>
seal-agent
force-pushed
the
designdocmigration-sea-1794-compass-records
branch
from
August 6, 2026 03:13
68c9fc9 to
7caaf0c
Compare
seal-agent
added a commit
that referenced
this pull request
Aug 7, 2026
…(SEA-1731) Corrects the frozen `compass-server-ownership-layer-amendment` record so its §A1 add-list matches the shipped A1 proto (PR #149): the forge notification/carrier types (`ForgeNotification`/`ForgeNotificationKind`, `ForgeArtifactKind`, `CommentRef`) live in a new internal-only leaf `proto/compass/v1/forge.proto` that imports only `compass.proto`, **not** in `agent_gateway.proto` as #995 T1 and this record's original text directed — that placement is a circular import (`agent_gateway.proto` already imports `agent.proto`, so `agent.proto` referencing an `agent_gateway.proto` type is a cycle `buf` rejects). The `ForgeCall*` carrier + op requests stay in `agent_gateway.proto`; the leaf is imported acyclically by `agent.proto`/`agent_gateway.proto`/`runner.proto`. Wire contract, field numbers, and generated names are unchanged — placement only. Rewrites the "one structural consequence" section to "two structural consequences" (the cross-file import **plus** the new leaf), updates the T1 add-list and the row-13 disposition, and adds the ledger row for the placement decision. This correction was originally authored as a sealed PR (#1095) against the design corpus while it lived in `sealedsecurity/sealed`. #179 (SEA-1794) migrated the corpus + decision ledger + ledger gate into this repo, so the correction is re-homed here and #1095 is closed. The decision takes **DL-148** — allocated above the current ledger max after the migration (DL-130 in this repo is an unrelated role-prompts decision). Refs SEA-1731 Co-authored-by: Matt Wilkinson <matt@sealedsecurity.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Executes eng-docs T4/T5 (folded from SEA-1794 per Matt's ruling) against the frozen
docs/designs/repo/compass-eng-docs/design.md. compass becomes the source of truth for Compass design records; review continues here, not in sealed.What lands
docs/designs/product/compass-*records +compass.md, plus 3docs/designs/platform/compass-*. Each ran through the frozen T4 four-class sanitizer (tools/docs-migrate/migrate.ts): linear.app tracker links → bareSEA-<n>ids,oss/compass/path prefixes stripped, privateseal-*.mdlinks de-linked to prose, security sections kept verbatim.docs/designs/product/DECISIONS.md, 115 rows (the full ledger minus the two seal-product rows DL-045/046, which stay in a sealed-side residual ledger next to the seal records they cite; frozen Q1). The## Sealsection is dropped here.tools/design-ledger-gate/ported verbatim (PRODUCT_DIRunchanged), registered as a moon project in.moon/workspace.yml; swept by compass's singlemoon run :ci(no meta.ts wiring).docs/specs/product/compass.md+ a fresh Compass-onlyREADME.md.Sanitizer gate fix
The T4 gate flagged a bare
linear.apphostname literal in a proto-field comment (compass-issue-model) as residue, though the policy target is tracker links (https://linear.app/…), not a documented SaaS host string in fenced code. Narrowed the gate's linear check to the tracker-URL form the transforms actually strip — symmetric with the seal/oss checks — with two-sided red-green tests (bare literal passes, a real tracker URL still reds).Verification
moon run design-ledger-gate:cigreen: gate OK — 115 ledger rows, 41 record headers valid; 71 unit tests pass. The cut is edge-clean (zero severed supersession edges, zero dangling Record links).bun install --frozen-lockfileclean; markdownlint 0 errors; biome clean.gather.tsis still a T1 stub (T2 unmerged), so the docsite renders a placeholder, not this corpus — the corpus is gated by design-ledger-gate + markdownlint; docsite rendering follows when T2 lands.This is PR 1 of 2. The companion sealed PR (delete side) must merge AFTER this one.
Refs SEA-1794
Refs SEA-1767
Co-authored-by: Matt Wilkinson matt@sealedsecurity.com