From 52be6043a795f6d8e8007ff894112cd27225b756 Mon Sep 17 00:00:00 2001 From: mintaka Date: Mon, 31 Aug 2026 13:26:22 -0400 Subject: [PATCH] docs(concepts): tighten managed-boundary naming rule + capability-vs-product-end-state (RIG-3153) The public compass repo must not carry the managed product's end-state or rollout, and must never name or point at the private repo as a place. Tighten the ratified convention: - self-host-and-managed.md: ban repo place-pointers (was: explicitly permitted "the private monorepo"); add the capability-vs-product-end-state rule (managed capability in the core is fine, framed as core capability; the managed product's end-state/rollout stays out). - oss-core-managed-boundary: scrub place-pointers from framing, boundary-test No-branch, and examples-table column (-> "managed plane, out of tree"). Pairs with skill://compass-managed-boundary (the agent trigger). Spec-impact: none. Refs RIG-3153 Co-authored-by: Matt Wilkinson --- docs/concepts/self-host-and-managed.md | 30 ++++++++++++++----- .../meta/oss-core-managed-boundary/design.md | 23 +++++++------- 2 files changed, 34 insertions(+), 19 deletions(-) diff --git a/docs/concepts/self-host-and-managed.md b/docs/concepts/self-host-and-managed.md index 03a517bf..bac91c40 100644 --- a/docs/concepts/self-host-and-managed.md +++ b/docs/concepts/self-host-and-managed.md @@ -18,8 +18,8 @@ feature may make about its environment. forking it**, and adds the control plane the core does not have (tenant orchestration, billing, cross-tenant fleet health, and inter-tenant isolation as a product - requirement). It runs at **`compass.rigel.build`**. Its code lives in a - **private monorepo**, not this one. **It does not exist yet — it is a + requirement). It runs at **`compass.rigel.build`**. It is built **out of + tree**, as a separate private product. **It does not exist yet — it is a near-future buildout** — but designs land now with it in view so the core stays a clean base for it. @@ -33,17 +33,31 @@ built on top of it, out of tree. resolve against this repo; its tasks land here. - **Managed control-plane concerns are out of scope for this repo — name them, then defer.** Tenant orchestration, billing, cross-tenant analytics, the - hosted control surface, and multi-tenant scheduling live in the private - monorepo. When a design touches one, state that it is managed-plane and - out of scope; do not design it here. + hosted control surface, and multi-tenant scheduling are managed-plane + concerns. When a design touches one, state that it is managed-plane and out + of scope; do not design it here, and do not point at where it is designed. +- **The managed product's end-state and rollout stay out of this repo.** + Managed *capability* implemented in the core belongs here, framed as core + capability (what it does for the self-hosted product). But the managed + *product's* end-state, deployment shape, and rollout sequencing — "the + managed deployment drops X at the first-external-tenant milestone," "the + managed service's sole runtime is Y" — are private product roadmap, not core + capability. Build the seam the managed product can extend and describe the + core default; do not describe or sequence the out-of-tree end-state. - **The core must not assume it is single-tenant, nor assume it is managed.** Prefer a seam the managed service can extend over a choice that only fits one product. A store, an endpoint, or a URL is configured at deploy, never hardcoded to one product's shape. -- **Do not name the private monorepo.** Refer to "the private monorepo" or "the - managed multi-tenant service" — never a repo proper name (applies the +- **Never name or point at the private repo.** Do not name it, and do not + point at it as a place — no "the private monorepo," no "designed there," no + "built in the private monorepo." When the other product must be referred to + at all, say **"the managed service"** (the product, as a consumer/operator + of the core) — generically, and only when unavoidable; prefer describing the + core capability directly so it need not be named. `moon run + orion-ref-gate:check` catches the literal repo name; the place-pointer ban is + broader and is on the author and reviewer. (Applies the describe-behavior-directly principle from [`AGENTS.md`](../../AGENTS.md) - Hygiene). + Hygiene.) ## Deploy-time differences the core already carries diff --git a/docs/designs/meta/oss-core-managed-boundary/design.md b/docs/designs/meta/oss-core-managed-boundary/design.md index 630d846f..60eaead8 100644 --- a/docs/designs/meta/oss-core-managed-boundary/design.md +++ b/docs/designs/meta/oss-core-managed-boundary/design.md @@ -15,8 +15,9 @@ the Server↔Runner topology, and the NATS eventing substrate are the live example (the RIG-2861 record, `docs/designs/infra/runtime/compass-managed-multitenancy/design.md`). Without a stated convention, agents do not know what belongs in the public -`RigelBuild/compass` core versus the private monorepo, and public -records risk "managed-service" framing for what is really core capability. +`RigelBuild/compass` core versus the managed plane (built out of tree), and +public records risk "managed-service" framing for what is really core +capability. ## Approach @@ -29,10 +30,10 @@ that is literally true and makes the OSS product better. The managed service is a **consumer and operator** of that core, never the subject of the record. This is the parent record's "one architecture, two products" seam (`docs/designs/infra/runtime/compass-elastic-session-runtime/design.md:71-101`), -which already draws the line: "**This record designs a change to the OSS -core.** … Nothing in the managed control plane (tenant orchestration, -billing, the hosted control surface, all of which live in the private -monorepo) is designed here." +which already draws the line: this record designs a change to the OSS core, +and nothing in the managed control plane (tenant orchestration, billing, the +hosted control surface) is designed here — those are managed-plane concerns, +built out of tree. ### Boundary test @@ -41,8 +42,8 @@ monorepo) is designed here." - **Yes** → OSS core (`RigelBuild/compass`, records under `docs/designs/` here). - **No, because it needs cloud infrastructure, billing, or - tenant-provisioning orchestration** → the private monorepo (never - mirrored public). + tenant-provisioning orchestration** → managed plane, out of tree (built as a + separate private product; not designed or mirrored here). ### Examples @@ -52,9 +53,9 @@ monorepo) is designed here." | OSS core | Server↔Runner connection topology | | OSS core | NATS eventing substrate | | OSS core | The single-binary embedded-NATS default | -| Private monorepo | AWS/EKS deployment IaC (Pulumi, Kubernetes manifests) | -| Private monorepo | Tenant provisioning and billing orchestration | -| Private monorepo | Operational runbooks for the hosted service | +| Managed plane (out of tree) | Cloud deployment IaC (Pulumi, Kubernetes manifests) | +| Managed plane (out of tree) | Tenant provisioning and billing orchestration | +| Managed plane (out of tree) | Operational runbooks for the hosted service | The RIG-2861 tenancy record is the worked example of core-capability-under-managed-motivation: motivated by the managed product,