docs(server): re-point forge scope-enforcement record to the governed server root (RIG-2679)

[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 — SIX load-bearing, four handed to Matt by name

Corrected: earlier status lines from me named only OQ-1 and OQ-6. Enumerated from the record's own bullet labels — 6 load-bearing / 2 not / 8 total.

• OQ-1 (load-bearing, deferred to Matt): enforcement default fail-open vs fail-closed.
• OQ-2 (load-bearing): grant surface for Beta operators. MVP ships the seeded/owner-grant path; the operator-facing surface is unspecified.
• OQ-3 (load-bearing): grant granularity — grants attach to the account, not to a session or task.
• OQ-6 (load-bearing, deferred to Matt): 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, deferred to Matt): git-op allowlist = write set + implicit workstream read, vs a distinct read superset (carries the clone-narrowing regression against RIG-1527 as first-class).
• OQ-8 (load-bearing, deferred to Matt): where the workstream-repo input comes from — requires re-introducing a per-agent workstream-repo association RIG-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.

Non-load-bearing, recorded not asked: OQ-4 (read arms stay ungated this slice) and OQ-5 (wildcard grammar).

Status: at freeze gate pending six rulings. A record cannot freeze with live load-bearing OQs.

Ledger-impact: none in this PR — the record is Status: Draft and proposes one Comms & tools row that lands at freeze, amending DL-200's inherited no-scope-rejection A8 clause without superseding it. DECISIONS.md is untouched here. Row id assigned at freeze: origin/main at c374bb98 carries 304 rows, max DL-337 (sort -n over a full extraction, not a rendering; POS-CTRL DL-337 present, NEG-CTRL DL-999 absent), which alone licenses next free ≥ DL-338 — DL-338..343 all measured absent on that tree. Folding in-flight mints raises it, but each belongs to a different tree and is stated as such: #900 at ad63e1b4 mints DL-340, and #913 at 15e86552 mints only DL-338/339 — #913 is stacked on #900 (baseRefName == #900's headRefName; merge-base --is-ancestor YES; the DL-340 row is byte-identical at both heads, md5 9159954a06ba), so its DL-340 is inherited, not double-minted. A stacked PR must be diffed against its base, not trunk, or its parent's rows are attributed to it. and DL-341 reported by #932's owner, which I have not measured — no local ref for that branch. So: ≥ DL-338 on main; ≥ DL-341 on the trees I verified; ≥ DL-342 only if #932's mint holds. Note the ledger is not id-ordered — 22 descents, last positional row DL-323 against a max of DL-337 — so an extremum must come from a full extraction, never from a prefix or a truncated listing.

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 b8b4cd7.

Changed pages:

• docs/designs/server/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.

[rigel-mintaka]

Update: #832 merged (4efa6faf, 2026-09-02). docs/designs/product/ is now deleted on main and product is out of GOVERNED_ROOTS — so the re-point to docs/designs/server/compass-forge-scope-enforcement/design.md is now required on this branch's next rebase, not optional. Rebasing will surface the removed dir.