STD-GC-002: BEADS & DOLT SCOPE TOPOLOGY & CONFIGURATION CONTRACT

Status: APPROVED & BINDING
Authority: Gas City / Beads Upstream Architecture Contract
Applies To: All Gas City Cities, Rigs, Workspaces, and Agent Execution Planes

---

1. Upstream Configuration Precedence & Scoping

Upstream bd searches configuration in this strict precedence hierarchy:

1. $BEADS_DIR/config.yaml         → Explicit runtime force (compatibility only)
2. <repo>/.beads/config.yaml      → Scope / Rig / City identity & endpoint contract
3. ~/.config/bd/config.yaml       → Shared user-level CLI preferences ONLY
4. ~/.beads/config.yaml           → Legacy user config (lowest priority)

~/.beads/config.yaml is legacy user-level fallback, NOT the canonical config for projects or rigs.

---

2. Canonical Scope Structure

Every Gas City scope (city and rig) maintains its own .beads/config.yaml and .beads/metadata.json. Scope isolation is achieved through unique issue_prefix and pinned logical database identity (dolt_database).

A. Mac / User Preferences (~/.config/bd/config.yaml)

Contains user-level CLI preferences only. Does NOT contain scope identity, issue prefixes, or database bindings.

json: true
validation:
  on-create: warn
backup:
  enabled: false

B. City Scope (<city>/.beads/)

• <city>/.beads/config.yaml:

  issue_prefix: hq
  dolt.auto-start: false
  dolt:
    disable-event-flush: true
  gc.endpoint_origin: city_canonical
  gc.endpoint_status: verified
  

• <city>/.beads/metadata.json:

  {
    "backend": "dolt",
    "dolt_mode": "server",
    "dolt_database": "hq",
    "dolt_server_host": "127.0.0.1",
    "dolt_server_port": 3308
  }
  

C. Rig Scope (<rig>/.beads/)

• <rig>/.beads/config.yaml:

  issue_prefix: <UNIQUE-RIG-PREFIX>
  issue-prefix: <UNIQUE-RIG-PREFIX>
  dolt.auto-start: false
  dolt:
    disable-event-flush: true
  gc.endpoint_origin: inherited_city
  gc.endpoint_status: verified
  

• <rig>/.beads/metadata.json:

  {
    "backend": "dolt",
    "dolt_mode": "server",
    "dolt_database": "<RIG-PINNED-DB-NAME>",
    "dolt_server_host": "127.0.0.1",
    "dolt_server_port": 3308
  }
  

---

3. Strict Operating Invariants

1. NO Global BEADS_DIR Overrides: Do NOT export BEADS_DIR=~/.beads for ordinary Gas City work. Global BEADS_DIR forces every repository into a single scope.
2. NO Symlinked Scope Configs: Do NOT symlink <repo>/.beads/config.yaml → ~/.beads/config.yaml.
3. NO Per-Rig Local Dolt Servers: One Dolt server per City (Oracle 127.0.0.1:3308). Rigs inherit city endpoint topology.
4. Preserve Pinned Database Identities: Existing dolt_database values in .beads/metadata.json (ad, bp, du, aao, hq, etc.) are pinned logical database identities and MUST NOT be renamed.
5. Governed Topology Mutations: All topology mutations MUST use standard Gas City CLI tools:
6. gc beads city use-external ...
7. gc rig set-endpoint <rig> --inherit

---

4. Summary Matrix

Level	File	Purpose	Shared / Uniform	Unique / Variable
User	~/.config/bd/config.yaml	CLI preferences	CLI flags	None
City	<city>/.beads/config.yaml	City endpoint authority	city_canonical	issue_prefix: hq
City	<city>/.beads/metadata.json	City Dolt binding	dolt_mode: server	dolt_database: hq
Rig	<rig>/.beads/config.yaml	Rig scope contract	inherited_city	issue_prefix: <rig>
Rig	<rig>/.beads/metadata.json	Rig Dolt database pin	dolt_mode: server	dolt_database: <rig>