Fragment Registry as Constitutional Policy Substrate
Five frontier models converged independently on a single architecture for forge as multi-tenant, container-deployable, overseer-ready infrastructure. This is the substrate; everything else is built on top.
Plan summary
Option G+ — the intuitionToday, agent instructions live in five hand-maintained markdown files (CLAUDE.md / FORGE.md / AGENTS.md / GEMINI.md / GROK.md, ~1,400 lines combined) plus four package-level CLAUDE.md files. They drift. They duplicate. They cannot be customized per tenant without forking. They cannot be patched by an automated overseer. And they cannot be machine-validated for authenticity — the May 22 governance breach proved schema-valid attestations can be fully synthetic.
The locked architecture replaces handwritten markdown with a fragment registry. Typed YAML fragments are the source of truth — versioned, schema-validated, signed, evidence-bound. A dual-mode compiler renders them: physical markdown files for the central brain (Anthropic-SOTA tree-walk preserved), JIT context-injection for multi-tenant HyperCloud workspaces (no per-tenant disk write). Fragments configure not just instructions but panel.review composition, FSM guards, dispatch routing, and Modulum metadata. They become the next constitutional layer — protected with the same gates as .forge/machines/*.yaml.
Impact dashboard
Scope & completenessCurrent architecture
Today — handwritten + singleton + schema-trustedState as of 2026-05-22 · forge_track=forge-os · sprint FORGE_OS_v1_5
766 lines · 50KB] CMD --> FORGE_MD[FORGE.md
416 lines · binding] CMD --> AGENTS[AGENTS.md / GEMINI.md / GROK.md
57-82 lines each · duplicated] CMD --> PKG[4× package CLAUDE.md
36-267 lines each] CLAUDE -.drift.-> MEM[(.claude/memory
186 entries)] FORGE_MD -.duplicated-rule.-> AGENTS AGENTS -.duplicated-rule.-> CLAUDE CMD --> FCLI[forge CLI] FCLI --> ENGINE[engine.ts · 1522 lines
singleton per repo] FCLI --> CONV[convergence/orchestrator.ts
915 lines · in-process signer] FCLI --> REVIEW[".forge/reviews/{sha}.json
schema-trusted only"] REVIEW -.synthetic-attestation.-> BREACH[("2026-05-22 BREACH
4 commits reverted")] classDef bad fill:#94343a,stroke:#94343a,color:#fff,stroke-width:1px classDef warn fill:#d4a73a,stroke:#b88a2c,color:#1a1814 classDef ok fill:#2f4a5e,stroke:#1e3a5f,color:#ece6d8 class BREACH bad class CLAUDE,AGENTS,PKG warn class FCLI,ENGINE,CONV ok
Markdown files hand-maintained. Rules duplicated across CLAUDE/AGENTS/GEMINI/GROK. Memory entries drift from CLAUDE.md silently. Reviews trusted by schema, not authenticity — an agent can author forge review <sha> <model> --summary "..." with no dispatch proof. Engine is singleton per repo with no tenant identity. Track factory (FORGE_TRACK env var) gives per-project isolation but env vars drift across sessions.
Planned architecture
Option G+ · Fragment Registry as Policy SubstrateAfter substrate lock · dual-mode compiler · 4-level inheritance DAG · overseer-observable
constitutional · operational · product"] COMP["compiler/
render-target + jit-resolver"] ENGINE_NEW["engine + convergence orchestrator
+ TIER-1 signed dispatch evidence"] SERVICES[api-bridge · memory-router · patch-broker] end subgraph TENANT_MOUNT [tenant volume · per-workspace] direction TB WS_FRAG[workspace/fragments/
overrides only · cannot weaken] WS_STATE[state · memory · events · keys] WS_SPACES[spaces/...] end CMD --> COMP COMP -->|"Mode A · meta"| RENDER["physical files:
CLAUDE.md · FORGE.md · AGENTS.md · GEMINI.md · GROK.md"] COMP -->|"Mode B · tenant"| JIT["JIT context payload
injected into MCP request"] CORE_FRAG --> COMP WS_FRAG --> COMP RENDER -.tree-walk.-> AGENTS_LOAD[Agent reads nearest file] JIT --> HC_API["HC API · panel.review · ground · memory.*"] ENGINE_NEW --> RECEIPT["signed dispatch evidence
.forge/dispatch-evidence/{uuid}.json"] RECEIPT --> ATTEST["attestation v3
provenance chain"] OVERSEER[("Hermes Overseer · 18811
RL drift catalog · proposes patches")] ATTEST --> OVERSEER OVERSEER -.proposes.-> STAGE["proposed-memories/
proposed-fragments/"] STAGE -.human-confirm.-> CORE_FRAG STAGE -.workspace-auto.-> WS_FRAG classDef new fill:#5c7a4f,stroke:#5c7a4f,color:#fff,stroke-width:1px classDef hero fill:#d4a73a,stroke:#b88a2c,color:#1a1814 classDef immut fill:#1e3a5f,stroke:#1e3a5f,color:#ece6d8 classDef tenant fill:#a04826,stroke:#a04826,color:#fff class COMP,RENDER,JIT,CORE_FRAG hero class RECEIPT,OVERSEER,STAGE,ATTEST new class ENGINE_NEW,SERVICES immut class WS_FRAG,WS_STATE,WS_SPACES tenant
Fragments are the source of truth. Compiler renders Mode A (physical files, tree-walk preserved) or Mode B (JIT context payload, no per-tenant disk write). Tenant overrides cannot weaken constitutional invariants — only strengthen. Every review carries signed dispatch evidence; the overseer observes events and proposes fragment patches to staging.
Change-by-change breakdown
4 load-bearing changesforge review <sha> <model> --summary "..." accepts any text. The CLI trusts the operator to have actually dispatched the model.
Engine guard convergence_attested at engine.ts:848 is schema-trusted, not authenticity-trusted. v1 attestations accepted with warning at :853.
Result: 4 commits reverted 2026-05-22 (synthetic panel reviews).
Every forge review / forge attest requires --dispatch-id <uuid> pointing at .forge/dispatch-evidence/<uuid>.json.
Evidence file emitted ONLY by out-of-process signer (overwatchd), never agent-writable. Contains: endpoint URL, request hash, response hash, timestamps, response code, API-key fingerprint.
Engine cross-references reviewer → dispatch evidence. Missing → fail closed.
Rationale · Fragments without authenticity become another schema-trusted document system. The substrate's integrity guarantee depends on signed receipts existing FIRST. Codex defends this hardest: every other change either reinforces this or is wasted effort.
FORGE_TRACK env var at track.ts:56 isolates state under .forge/state/tracks/<track>/. Per-project lane only.
Memory router store at router.ts:107 accepts no StoreOpts — no namespace passed at write time.
Cross-session env contamination is a documented failure mode.
Explicit identity fields propagate through state · memory · events · dispatch metadata. Not env-driven; carried in request context.
Mode (meta vs tenant) is derived from presence of a tenant-config fragment in the loaded graph — not from an env var. Fragments are mechanically observable; env state is not.
Memory namespace enforced at store() time, not just get()/search().
Rationale · HC workspaces need first-class isolation. Env vars drift silently across sessions (incident class C3 in the retro). Fragment-presence is a deterministic, machine-observable signal.
5 root markdown files + 4 package-level. Hand-written. Rules duplicated.
CLAUDE.md = 766 lines / 50KB auto-loaded every session.
No machine-readable schema. Drift between CLAUDE.md and memory entries is a recurring incident class.
Fragments live at .forge/instructions/fragments/*.yaml.md with frontmatter (id, version, scope, audience, integrity, supersedes, depends_on, sync_group, owner, last_verified_event).
Compiler is dual-mode: Mode A renders physical markdown for meta-forge (Anthropic SOTA tree-walk). Mode B JIT-resolves into MCP payload for tenants (no disk write per workspace).
Compiler reuses existing patch-broker substrate per Gemini's catch — not a new compiler stack.
Rationale · Gemini surfaced the JIT requirement — physical files cannot scale to 10K concurrent HC spaces. Codex insisted compiler reuse patch-broker. Both fit naturally: fragments compile to disk for Mode A (jmw), to payload for Mode B (HC tenant).
Panel composition documented as prose across CLAUDE.md and FORGE.md §3. Hardcoded canonical 5-reviewer panel in convergence-audit SPEC.
Customers cannot configure their own panel without forking — and even if they could, the configuration would be plain prose, not validated.
Constitutional panel_config_base fragment ships the canonical 5-reviewer panel + same-round-no-new-findings + signed-receipt requirement.
Workspace tenants author panel_config_extension fragments to add reviewers, tighten convergence, or substitute with model-equivalence attestation. They cannot weaken.
Customer-visible receipt shows: resolved panel composition, fragment provenance chain, per-reviewer dispatch evidence IDs, per-round findings hash, convergence verdict. Auditable moat — nobody else has this.
Rationale · The MOAT must be configurable to be a product, but constitutional convergence must remain enforceable. Fragment inheritance is the only mechanism that supports both — strict floor + per-tenant extension.
Dependency & ripple analysis
What else moves7 affected subsystems (click to collapse)
| Subsystem | File | Coverage | Why it ripples |
|---|---|---|---|
| State machine engine | forge-core/src/engine.ts | Covered | Guard convergence_attested at :848 cross-references dispatch evidence under new contract |
| Convergence orchestrator | convergence/orchestrator.ts | Covered | signedBy at :567 must reference dispatch UUID, not in-process signer alone |
| Model dispatch routing | api-bridge/src/model-dispatch.ts | Adjacent fix needed | Unconditional Claude fallback at :269 contradicts FORGE.md opt-in; Grok/local/Modulum unimplemented at :330 (Codex flagged) |
| Memory router | memory-router/src/router.ts | Adjacent fix needed | store() at :107 doesn't accept StoreOpts — namespace enforcement only on read, must extend to write |
| Track factory | forge-core/src/track.ts | Covered | Slug pattern at :27 extends naturally; workspace/space identity composes on top |
| Patch broker (3600) | infrastructure/packages/patch-broker | Covered | Reused as fragment-application substrate (Gemini's catch — no new compiler stack) |
| Hermes Overseer (18811) | proposal · not yet built | Blocked by A0 | Tier 2 RL loop cannot ship until Tier 1 signed events exist · proposal §3, line 353 |
| HyperCloud panel.review | hypernym-cloud/ | Covered | Consumes panel fragments + emits receipts with fragment provenance chain |
| Memory entries (186) | ~/.claude/projects/.../memory/ | Migration | Memory Sync Protocol procedure converts to overseer-driven fragment lifecycle |
Risk assessment
5 risks · forge-specificA malformed promotion at the forge-base or HC-product-tier level cascades into every tenant simultaneously. Without staged rollout, a bad fragment update is a fleet-wide outage that bypasses convergence (because the panel reviewed an earlier version).
If the compiler renders incorrectly — silent bug erases constitutional clauses or scrambles audience tags — every rendered file across every deployment is wrong simultaneously. The panel that approved the fragments never saw the rendered output.
If fragments compile cleanly while their underlying claims drift from runtime reality, we've recreated the 2026-05-22 breach pattern at a new layer.
last_verified_event evidence pointer to runtime events / dispatch receipts. Overseer Tier 2 monitors and alerts on stale evidence.Shared drift catalog is the overseer's RL substrate, but unscoped event mirrors could leak tenant-specific metadata across workspaces.
A tenant tries to weaken convergence rules (e.g., 1-reviewer panel, no Grok) and is blocked by the floor. Could create UX friction.
Plan review
5-model panel · GBU analysissprint.yaml-equivalent protection. Mode derived from fragment graph (not env var). Canary rollout primitive non-negotiable.- 5-model independent convergence on the architectural pattern (round 2)Real convergence per FORGE.md §3 SPEC §3 — same-round-no-new-findings on the core shape
- Reuses existing patch-broker substrate — no new compiler infrastructureGemini's catch saves substantial implementation cost
- Authenticity-first sequencing closes the 2026-05-22 breach classCodex's MVU directly maps to retro P0-P6 mechanical fixes
- Track factory pattern already provides the isolation primitivePhase 3 v2.3 memory namespace extends cleanly to workspace scope
- Customer governance floor preserves the moatpanel.review configurable but not weakenable
- Migration path for existing 5 markdown files not yet specifiedRound 2 covered the target architecture, not the transition; SEED phase work
- Fragment schema not yet lockedCodex spec'd 9 frontmatter fields; needs concrete YAML schema definition
- Update model for deployed forge images is openWho is responsible for security patches across customer deployments? Auto-update via signed manifest?
- Test coverage strategy at fragment level still TBDPer-fragment schema tests + render-output diff tests need design
- The substrate becomes a compelling attack surfaceCompromised compiler or stolen signer key cascades fleet-wide
- Fragment registry is now load-bearing for HC, Modulum routing, panel.review, AND agent behaviorCoupling forge-core to customer-facing product mechanics
- Overseer's RL loop will discover bugs we don't yet know aboutProductive but means substrate must handle adversarial debug telemetry
- "Forge as service" pulls in operational concerns (uptime, billing, SLAs)jmw's central-brain orchestration becomes a product team responsibility
- Approve the customer governance floor as specified?Tenants CAN configure panel size, providers, budgets · CANNOT weaken signed provenance, quorum, mandatory Grok, namespace isolation
- Lock the sequencing: A0 (signed receipts) before B (registry)?This is the cost of saying "no more synthetic attestations"
- Authorize separate sprint for canary rollout primitive (step E)?Blocks Mode B production deployment to first external tenant
- Forge image update model: signed manifest with grace period, or customer-pulls-manually?Operational debt that must be answered before HC customer onboarding
Understanding gaps
Cognitive debt before implementationRecommendation · Before implementing, document the migration sequence for existing 5 markdown files into fragments. Each existing file becomes one or more fragment, but ordering matters: constitutional fragments must land first under cross-model panel review, then operational, then per-track. The plan covers target architecture; SEED phase must produce transition plan.
CTO sign-off
This is the substrate that makes the next phase possible — HyperCloud v1, Modulum routing, Hermes Overseer, multi-tenant forge deployment. Five frontier models converged independently in round 2 with full system + vision context. The architecture is locked at the pattern level; sequencing and migration are SEED-phase work.
- Approve · The locked architecture (Option G+ Fragment Registry as Policy Substrate) as the target shape for forge as deployable multi-tenant infrastructure.
- Approve · Authenticity-first sequencing — Tier 1 signed dispatch evidence (A0) blocks every other workstream. No fragment shipped before signing.
- Approve · Customer governance floor as specified — tenants extend, never weaken, constitutional invariants.
- Authorize · Start SEED on first sprint: Tier 1 Signed Dispatch Evidence (overwatchd, dispatch-evidence schema, forge-review/forge-attest CLI changes, engine cross-reference).
- Defer · Forge-image update model decision until Sprint A complete; can be answered before first external tenant onboards.