docs(product): forge scope enforcement — API writes + git operations (RIG-2679 B)

[rigel-mintaka]

The deferred A8 forge scope control, in two enforcement legs sharing one per-account allowlist (account_forge_scopes).

A1-A4 — forge-API write chokepoint

requireForgeScope in every write arm of ExecuteForgeCallAsAccount — after coordinate resolution, on create arms after the F3 idempotency-memo check, before any provider call — rejecting out-of-scope targets as the in-band ForgeCallError{code:"not_found"}, byte-identical to the 403/404 flatten (no probe oracle). Gated by ForgeConfig.EnforceScopes: off for Dogfood, mandatory for Beta.

A5 / T4-T5 — git clone/push/pull scope (Matt's 2026-08-26 expansion)

Scope the credential, not the git call: mint a GitHub App installation token narrowed via the repositories field to the workstream repo + the account's granted repo set, so an out-of-scope git push/clone fails at GitHub itself — zero enforcement code inside the agent-controlled container. The self-clone invariant keeps the agent's own workstream repo always clonable (else provisioning succeeds but the agent is dead on arrival); zero/insufficient-grant provision fails loud. Both credential surfaces (.git-credentials + gh-CLI hosts.yml) carry the narrowed token from provision (t=0), not only after first refresh. A new T4.5 (proto) task carries the minted token across the Server→Runner process boundary (ProvisionAgentWorkspaceRequest carries no credential today) with a server-driven refresh push keyed by a per-live-container scheduler registry; T5 hardens refresh (margin, backoff, keep-old-token-on-failure, atomic rewrite, both surfaces).

Review history

Prior design-critic + code-review passes on the forge-API core (A1-A4) folded. Git-op leg (A5/T4/T4.5/T5) added; a design-critic red-team folded (self-clone invariant, Server→Runner wire path, loud PAT-fallback); then a three-round code-review loop reached all-clear at the high+medium floor — round 1 (1 high / 3 med / 2 low: SEA-1527 miscitation → OQ-8, hosts.yml refresh surface, refresh-scheduler state, read/write asymmetry, 404/403, owner-alias), round 2 (provision-time hosts.yml gap + co-resident gh-host preservation + projection phrasing), round 3 all-clear. Sub-floor items (same-host token precedence, citation normalization) dispositioned inline.

Open questions deferred to the freeze gate (Matt)

• OQ-1 (load-bearing): enforcement default fail-open vs fail-closed.
• OQ-6 (load-bearing): git-op mechanism (credential-narrowing rec) + PAT fallback (fine-grained-PAT option (c) + loud-Warn) + docs(product): rework forge agent-notification to webhook-only (RIG-2732) #634 sequencing sub-fork (recommend contingent split).
• OQ-7 (load-bearing): git-op allowlist = write set + implicit workstream read, vs a distinct read superset (carries the clone-narrowing regression against SEA-1527 as first-class).
• OQ-8 (load-bearing, new): where the workstream-repo input comes from — the git-op leg requires re-introducing a per-agent workstream-repo association SEA-1527 removed (provision/spawn field, agent_accounts column, or store-side spawn-target record); reverses a prior Matt ruling, so it is his call. Blocks T4/T4.5/T5.

Status: at freeze gate pending the OQ rulings above.

Ledger-impact: deferred to freeze (adds one Comms & tools row; amends DL-200's inherited no-scope-rejection A8 clause without superseding it). Driver assigns the row id at freeze (≥ DL-264 on current main).

Refs RIG-2679
Spec-impact: none

[linear-code]

RIG-2679

[github-actions]

Compass engineering docs preview: https://compass-server-rig-2679-forg.compass-eng-docs.pages.dev

Deployed from compass-server/rig-2679-forge-scope-enforcement at 40cd38d.

Changed pages:

• docs/designs/product/compass-forge-scope-enforcement/design.md

[rigel-mintaka]

Heads up from RIG-2577 T10 (#832, now open): that PR removed the transitional docs/designs/product/ bucket entirely — it's dissolved, the directory is deleted, and product is no longer in the design-ledger-gate's GOVERNED_ROOTS.

This PR adds docs/designs/product/compass-forge-scope-enforcement/design.md, which after a rebase onto current main lands in a deleted, ungoverned bucket. Two consequences:

1. The record would sit outside GOVERNED_ROOTS, so the design-ledger-gate would not govern its Status: header or ledger-coupling — a silent governance escape.
2. It's mis-filed against the pre-reorg flat taxonomy anyway: compass-forge-* is a server-domain surface, so post-reorg it belongs under docs/designs/server/.

Before merge, please re-point the record to docs/designs/server/compass-forge-scope-enforcement/design.md (and any DECISIONS.md Record cell / inbound links with it). Rebasing onto main will also surface the removed product/ dir.