refactor: remove Gas Town references from codebase

Replace Gas Town-specific terminology with generic orchestrator concepts:
- "Gas Town" → "orchestrator" or "multi-clone"
- Hardcoded ~/gt/ paths → GT_ROOT environment variable
- signalGasTownActivity → signalOrchestratorActivity
- GUPP → hook-based work assignment

Updated 21 files across CHANGELOG, cmd/bd/, internal/, docs/, scripts.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Executed-By: beads/crew/dave
Rig: beads
Role: crew

.gitignore

@@ -114,7 +114,7 @@ bd-trace-*.out
 # AI planning documents (ephemeral)
 history/
 
-# Gas Town agent state
+# Orchestrator agent state
 state.json
 .beads/redirect
 

CHANGELOG.md

@@ -41,16 +41,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Optional reason stored in activity log
   - Better traceability for issue cleanup
 
-- **`hooked` status** - GUPP work assignment
+- **`hooked` status** - Hook-based work assignment
   - New status for issues assigned to agent hooks
-  - Enables Gas Town Propulsion Principle
+  - Enables autonomous agent work pickup
 
 - **`mol_type` schema field** - Molecule classification
   - Track molecule type (patrol, work, etc.)
   - New migration (adds schema field)
 
 - **Agent ID canonical naming** - Validation update
-  - Updated validation for Gas Town naming conventions
+  - Updated validation for orchestrator naming conventions
   - Supports rig/role/name format
 
 ### Fixed
@@ -138,7 +138,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **`bd slot` commands** - Agent bead slot management
   - Track agent assignments with dedicated slot operations
-  - Supports Gas Town multi-agent workflows
+  - Supports multi-agent orchestration workflows
 
 - **`bd agent state` command** - ZFC-compliant state reporting
   - Report agent state in standardized format
@@ -221,13 +221,13 @@ and muscle memory before v1.0.0 to avoid breakage.
   - Move issues between epics with `bd update <id> --parent=<new-parent>`
   - Supports clearing parent with `--parent=none`
 
-- **Redirect info in `bd prime`** - Gas Town support
+- **Redirect info in `bd prime`** - Multi-clone support
   - Shows when database is redirected to another location
   - Improves visibility into routing behavior
 
 ### Fixed
 
-- **Doctor follows redirects** - Gas Town compatibility
+- **Doctor follows redirects** - Multi-clone compatibility
   - `bd doctor` now correctly follows database redirects
   - Prevents false negatives when running from rig roots
 
@@ -245,7 +245,7 @@ and muscle memory before v1.0.0 to avoid breakage.
 
 - **Database Redirects section** - ADVANCED.md
   - Comprehensive documentation for redirect feature
-  - Explains Gas Town integration patterns
+  - Explains multi-clone integration patterns
 
 - **Community Tools update** (GH#771) - README.md
   - Added opencode-beads to community tools list
@@ -282,8 +282,8 @@ and muscle memory before v1.0.0 to avoid breakage.
 
 - **Removed unused commands**
   - `bd pin`, `bd unpin`, `bd hook` removed
-  - Functionality covered by `gt mol` commands in Gas Town
+  - Functionality covered by orchestrator molecule commands
-  - Cleaner separation between beads (data) and gastown (orchestration)
+  - Cleaner separation between beads (data) and orchestration
 
 - **`bd doctor --check=pollution`** - Integrated test pollution check
   - Detects test artifacts left in production database
@@ -481,10 +481,10 @@ and muscle memory before v1.0.0 to avoid breakage.
   - JSON provides better tooling support and validation
   - Existing YAML formulas need migration
 
-- **Removed `bd mol run`** - Orchestration moved to Gas Town
+- **Removed `bd mol run`** - Orchestration delegated to orchestrator
-  - Molecule execution now handled by `gt` commands
+  - Molecule execution now handled by orchestrator commands
   - `bd` focuses on issue tracking primitives
-  - Use `gt mol run` for molecule orchestration
+  - Use orchestrator's molecule runner for execution
 
 - **Simplified wisp architecture** - Single database model
   - Wisps stored in main database with `Wisp=true` flag

cmd/bd/activity.go

@@ -456,7 +456,7 @@ func discoverRigDaemons() []rigDaemon {
 	// Find town beads directory (uses findTownBeadsDir from create.go)
 	townBeadsDir, err := findTownBeadsDir()
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "Error: not in a Gas Town (%v)\n", err)
+		fmt.Fprintf(os.Stderr, "Error: not in an orchestrator environment (%v)\n", err)
 		os.Exit(1)
 	}
 

cmd/bd/doctor/maintenance.go

@@ -311,8 +311,8 @@ func CheckCompactionCandidates(path string) DoctorCheck {
 }
 
 // resolveBeadsDir follows a redirect file if present in the beads directory.
-// This handles Gas Town's redirect mechanism where .beads/redirect points to
+// This handles the redirect mechanism where .beads/redirect points to
-// the actual beads directory location.
+// the actual beads directory location (used in multi-clone setups).
 // This is a wrapper around beads.FollowRedirect for use within the doctor package.
 func resolveBeadsDir(beadsDir string) string {
 	return beads.FollowRedirect(beadsDir)

cmd/bd/formula.go

@@ -32,7 +32,7 @@ The Rig → Cook → Run lifecycle:
 Search paths (in order):
   1. .beads/formulas/ (project)
   2. ~/.beads/formulas/ (user)
-  3. ~/gt/.beads/formulas/ (town)
+  3. $GT_ROOT/.beads/formulas/ (orchestrator, if GT_ROOT set)
 
 Commands:
   list   List available formulas from all search paths
@@ -48,7 +48,7 @@ var formulaListCmd = &cobra.Command{
 Search paths (in order of priority):
   1. .beads/formulas/ (project - highest priority)
   2. ~/.beads/formulas/ (user)
-  3. ~/gt/.beads/formulas/ (town)
+  3. $GT_ROOT/.beads/formulas/ (orchestrator, if GT_ROOT set)
 
 Formulas in earlier paths shadow those with the same name in later paths.
 
@@ -359,8 +359,11 @@ func getFormulaSearchPaths() []string {
 	// User-level formulas
 	if home, err := os.UserHomeDir(); err == nil {
 		paths = append(paths, filepath.Join(home, ".beads", "formulas"))
-		// Gas Town formulas
+	}
-		paths = append(paths, filepath.Join(home, "gt", ".beads", "formulas"))
+
+	// Orchestrator formulas (via GT_ROOT)
+	if gtRoot := os.Getenv("GT_ROOT"); gtRoot != "" {
+		paths = append(paths, filepath.Join(gtRoot, ".beads", "formulas"))
 	}
 
 	return paths

cmd/bd/hooks.go

@@ -187,7 +187,7 @@ Installed hooks:
   - post-merge: Import JSONL after pull/merge
   - pre-push: Prevent pushing stale JSONL
   - post-checkout: Import JSONL after branch checkout
-  - prepare-commit-msg: Add agent identity trailers (for Gas Town agents)`,
+  - prepare-commit-msg: Add agent identity trailers (for orchestrator agents)`,
 	Run: func(cmd *cobra.Command, args []string) {
 		force, _ := cmd.Flags().GetBool("force")
 		shared, _ := cmd.Flags().GetBool("shared")
@@ -694,7 +694,7 @@ type agentIdentity struct {
 // detectAgentIdentity returns agent identity if running in agent context.
 // Returns nil if not in an agent context (human commit).
 func detectAgentIdentity() *agentIdentity {
-	// Check GT_ROLE environment variable first (set by Gas Town sessions)
+	// Check GT_ROLE environment variable first (set by orchestrator sessions)
 	gtRole := os.Getenv("GT_ROLE")
 	if gtRole != "" {
 		return parseAgentIdentity(gtRole)

cmd/bd/info.go

@@ -307,7 +307,7 @@ var versionChanges = []VersionChange{
 			"NEW: bd human command - Focused help menu for humans",
 			"NEW: bd show --short - Compact output mode for scripting",
 			"NEW: bd delete --reason - Audit trail for deletions",
-			"NEW: 'hooked' status - GUPP work assignment for Gas Town",
+			"NEW: 'hooked' status - Hook-based work assignment for orchestrators",
 			"NEW: mol_type schema field - Molecule classification tracking",
 			"FIX: --var flag allows commas in values (GH#786)",
 			"FIX: bd sync in bare repo worktrees (GH#785)",
@@ -327,7 +327,7 @@ var versionChanges = []VersionChange{
 			"NEW: bd where command - Show active beads location after following redirects",
 			"NEW: --parent flag for bd update - Reparent issues between epics",
 			"NEW: Redirect info in bd prime - Shows when database is redirected",
-			"FIX: bd doctor follows redirects - Gas Town compatibility",
+			"FIX: bd doctor follows redirects - Multi-clone compatibility",
 			"FIX: Remove 8-char prefix limit - bd rename-prefix allows longer prefixes",
 			"CHANGED: Git context consolidation - Internal refactor for efficiency",
 			"DOCS: Database Redirects section - ADVANCED.md documentation",

cmd/bd/mail.go

@@ -9,17 +9,17 @@ import (
 	"github.com/spf13/cobra"
 )
 
-// mailCmd delegates to an external mail provider (e.g., gt mail)
+// mailCmd delegates to an external mail provider.
 // This enables agents to use 'bd mail' consistently, while the actual
-// mail implementation is provided by the orchestrator (Gas Town, etc.)
+// mail implementation is provided by the orchestrator.
 var mailCmd = &cobra.Command{
 	Use:   "mail [subcommand] [args...]",
 	Short: "Delegate to mail provider (e.g., gt mail)",
 	Long: `Delegates mail operations to an external mail provider.
 
 Agents often type 'bd mail' when working with beads, but mail functionality
-is typically provided by an orchestrator like Gas Town (gt). This command
+is typically provided by the orchestrator. This command bridges that gap
-bridges that gap by delegating to the configured mail provider.
+by delegating to the configured mail provider.
 
 Configuration (checked in order):
   1. BEADS_MAIL_DELEGATE or BD_MAIL_DELEGATE environment variable

cmd/bd/main.go

@@ -147,8 +147,8 @@ var rootCmd = &cobra.Command{
 		// Set up signal-aware context for graceful cancellation
 		rootCtx, rootCancel = signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 
-		// Signal Gas Town daemon about bd activity (best-effort, for exponential backoff)
+		// Signal orchestrator daemon about bd activity (best-effort, for exponential backoff)
-		defer signalGasTownActivity()
+		defer signalOrchestratorActivity()
 
 		// Apply verbosity flags early (before any output)
 		debug.SetVerbose(verboseFlag)

cmd/bd/main_daemon.go

@@ -44,31 +44,15 @@ const (
 	GroupIntegrations = "integrations"
 )
 
-// signalGasTownActivity writes an activity signal for Gas Town daemon.
+// signalOrchestratorActivity writes an activity signal for orchestrator daemon.
 // This enables exponential backoff based on bd usage detection.
 // Best-effort: silent on any failure, never affects bd operation.
-func signalGasTownActivity() {
+func signalOrchestratorActivity() {
-	// Determine town root
+	// Determine town root from environment
-	// Priority: GT_ROOT env > detect from cwd path > skip
+	// Priority: GT_ROOT env > skip (no default path detection)
 	townRoot := os.Getenv("GT_ROOT")
 	if townRoot == "" {
-		// Try to detect from cwd - if under ~/gt/, use that as town root
+		return // Not in orchestrator environment, skip
-		home, err := os.UserHomeDir()
-		if err != nil {
-			return
-		}
-		gtRoot := filepath.Join(home, "gt")
-		cwd, err := os.Getwd()
-		if err != nil {
-			return
-		}
-		if strings.HasPrefix(cwd, gtRoot+string(os.PathSeparator)) {
-			townRoot = gtRoot
-		}
-	}
-
-	if townRoot == "" {
-		return // Not in Gas Town, skip
 	}
 
 	// Ensure daemon directory exists

cmd/bd/migrate_sync.go

@@ -20,8 +20,8 @@ var migrateSyncCmd = &cobra.Command{
 
 This command configures the repository to commit .beads changes to a separate
 branch (e.g., "beads-sync") instead of the current working branch. This is
-essential for multi-clone setups like Gas Town where multiple clones work
+essential for multi-clone setups where multiple clones work independently
-independently but need to sync beads data.
+but need to sync beads data.
 
 The command will:
   1. Validate the current state (not already configured, not on sync branch)

cmd/bd/mol_squash.go

@@ -34,7 +34,7 @@ The squash operation:
 
 AGENT INTEGRATION:
 Use --summary to provide an AI-generated summary. This keeps bd as a pure
-tool - the calling agent (Gas Town polecat, Claude Code, etc.) is responsible
+tool - the calling agent (orchestrator worker, Claude Code, etc.) is responsible
 for generating intelligent summaries. Without --summary, a basic concatenation
 of child issue content is used.
 

docs/CLI_REFERENCE.md

@@ -574,7 +574,7 @@ bd sync
 - `tombstone` - Deleted issue (suppresses resurrections)
 - `pinned` - Stays open indefinitely (used for hooks, anchors)
 
-**Note:** The `pinned` status is used by Gas Town for hook management and persistent work items that should never be auto-closed or cleaned up.
+**Note:** The `pinned` status is used by orchestrators for hook management and persistent work items that should never be auto-closed or cleaned up.
 
 ## Priorities
 

docs/MOLECULES.md

@@ -113,7 +113,7 @@ bd mol bond A B --type conditional # B runs only if A fails
 - Agent can continue from A into B seamlessly
 - The compound work graph can span days
 
-This is how Gas Town runs autonomous workflows - agents follow the dependency graph, handing off between sessions, until all work closes.
+This is how orchestrators run autonomous workflows - agents follow the dependency graph, handing off between sessions, until all work closes.
 
 ## Phase Metaphor (Templates)
 

docs/graph-links.md

@@ -9,7 +9,7 @@ Beads supports several types of links between issues to create a knowledge graph
 Creates message threads, similar to email or chat conversations.
 
 **Created by:**
-- `gt mail reply <id>` command (Gas Town handles messaging)
+- Orchestrator mail reply commands (orchestrator handles messaging)
 - `bd dep add <new-id> <original-id> --type replies_to` (manual linking)
 
 **Use cases:**
@@ -20,13 +20,13 @@ Creates message threads, similar to email or chat conversations.
 **Example:**
 
 ```bash
-# Original message (via Gas Town)
+# Original message (via orchestrator mail)
-gt mail send gastown/worker -s "Review needed" -m "Please review gt-xyz"
+# orchestrator mail send worker/ -s "Review needed" -m "Please review issue-xyz"
-# Creates: gt-a1b2
+# Creates: msg-a1b2
 
 # Reply (automatically sets replies_to)
-gt mail reply gt-a1b2 -m "Done! Approved with minor comments."
+# orchestrator mail reply msg-a1b2 -m "Done! Approved with minor comments."
-# Creates: gt-c3d4 with replies_to: gt-a1b2
+# Creates: msg-c3d4 with replies_to: msg-a1b2
 ```
 
 **Viewing threads:**
@@ -256,12 +256,12 @@ bd supersede bd-rfc2 --with bd-rfc3
 
 ### Message Threading
 
-Build conversation chains (via Gas Town):
+Build conversation chains (via orchestrator mail):
 
 ```bash
-gt mail send gastown/dev -s "Question" -m "How does X work?"
+# orchestrator mail send dev/ -s "Question" -m "How does X work?"
-gt mail reply gt-q1 -m "X works by..."
+# orchestrator mail reply msg-q1 -m "X works by..."
-gt mail reply gt-q1.reply -m "Thanks!"
+# orchestrator mail reply msg-q1.reply -m "Thanks!"
 ```
 
 ## Best Practices

internal/beads/beads.go

@@ -603,7 +603,7 @@ func findDatabaseInTree() string {
 // FindAllDatabases scans the directory hierarchy for the closest .beads directory.
 // Returns a slice with at most one DatabaseInfo - the closest database to CWD.
 // Stops searching upward as soon as a .beads directory is found,
-// because in multi-workspace setups (like Gas Town), nested .beads directories
+// because in multi-workspace setups, nested .beads directories
 // are intentional and separate - parent directories are out of scope.
 // Redirect files are supported: if a .beads/redirect file exists, its contents
 // are used as the actual .beads directory path.

internal/beads/beads_multidb_test.go

@@ -64,7 +64,7 @@ func TestFindAllDatabases(t *testing.T) {
 	databases := FindAllDatabases()
 
 	// Should find only the closest database (gt-bzd: stop searching when .beads found)
-	// Parent .beads directories are out of scope in multi-workspace setups like Gas Town
+	// Parent .beads directories are out of scope in multi-workspace setups
 	if len(databases) != 1 {
 		t.Fatalf("expected 1 database (closest only), got %d", len(databases))
 	}

internal/formula/parser.go

@@ -39,7 +39,7 @@ type Parser struct {
 
 // NewParser creates a new formula parser.
 // searchPaths are directories to search for formulas when resolving extends.
-// Default paths are: .beads/formulas, ~/.beads/formulas, ~/gt/.beads/formulas
+// Default paths are: .beads/formulas, ~/.beads/formulas, $GT_ROOT/.beads/formulas
 func NewParser(searchPaths ...string) *Parser {
 	paths := searchPaths
 	if len(paths) == 0 {
@@ -65,9 +65,11 @@ func defaultSearchPaths() []string {
 	// User-level formulas
 	if home, err := os.UserHomeDir(); err == nil {
 		paths = append(paths, filepath.Join(home, ".beads", "formulas"))
+	}
 
-		// Gas Town formulas
+	// Orchestrator formulas (via GT_ROOT)
-		paths = append(paths, filepath.Join(home, "gt", ".beads", "formulas"))
+	if gtRoot := os.Getenv("GT_ROOT"); gtRoot != "" {
+		paths = append(paths, filepath.Join(gtRoot, ".beads", "formulas"))
 	}
 
 	return paths

internal/molecules/molecules.go

@@ -8,7 +8,7 @@
 //
 // Molecules are loaded from multiple locations in priority order (later overrides earlier):
 //  1. Built-in molecules (shipped with bd binary)
-//  2. Town-level: ~/gt/.beads/molecules.jsonl (if Gas Town is detected)
+//  2. Town-level: $GT_ROOT/.beads/molecules.jsonl (if orchestrator detected via GT_ROOT)
 //  3. User-level: ~/.beads/molecules.jsonl
 //  4. Project-level: .beads/molecules.jsonl in the current project
 //
@@ -77,7 +77,7 @@ func (l *Loader) LoadAll(ctx context.Context, beadsDir string) (*LoadResult, err
 		}
 	}
 
-	// 2. Load town-level molecules (Gas Town: ~/gt/.beads/molecules.jsonl)
+	// 2. Load town-level molecules ($GT_ROOT/.beads/molecules.jsonl)
 	townPath := getTownMoleculesPath()
 	if townPath != "" {
 		if molecules, err := loadMoleculesFromFile(townPath); err == nil && len(molecules) > 0 {
@@ -220,15 +220,15 @@ func loadMoleculesFromFile(path string) ([]*types.Issue, error) {
 }
 
 // getTownMoleculesPath returns the path to town-level molecules.jsonl
-// if Gas Town is detected (~/gt/.beads/molecules.jsonl).
+// if an orchestrator is detected via GT_ROOT environment variable.
 func getTownMoleculesPath() string {
-	homeDir, err := os.UserHomeDir()
+	gtRoot := os.Getenv("GT_ROOT")
-	if err != nil {
+	if gtRoot == "" {
 		return ""
 	}
 
-	// Check for Gas Town installation
+	// Check for orchestrator molecules file
-	gtPath := filepath.Join(homeDir, "gt", ".beads", MoleculeFileName)
+	gtPath := filepath.Join(gtRoot, ".beads", MoleculeFileName)
 	if _, err := os.Stat(gtPath); err == nil {
 		return gtPath
 	}

internal/routing/routes.go

@@ -221,7 +221,7 @@ func ResolveToExternalRef(id, beadsDir string) string {
 
 // ResolveBeadsDirForID determines which beads directory contains the given issue ID.
 // It first checks the local beads directory, then consults routes.jsonl for prefix-based routing.
-// If routes.jsonl is not found locally, it searches up to the Gas Town root.
+// If routes.jsonl is not found locally, it searches up to the town root.
 //
 // Parameters:
 //   - ctx: context for database operations
@@ -273,7 +273,7 @@ func ResolveBeadsDirForID(ctx context.Context, id, currentBeadsDir string) (stri
 	return currentBeadsDir, false, nil
 }
 
-// findTownRoot walks up from startDir looking for a Gas Town root.
+// findTownRoot walks up from startDir looking for a town root.
 // Returns the town root path, or empty string if not found.
 // A town root is identified by the presence of mayor/town.json.
 func findTownRoot(startDir string) string {
@@ -294,7 +294,7 @@ func findTownRoot(startDir string) string {
 // findTownRoutes searches for routes.jsonl at the town level.
 // It walks up from currentBeadsDir to find the town root, then loads routes
 // from <townRoot>/.beads/routes.jsonl.
-// Returns (routes, townRoot). Returns nil routes if not in a Gas Town or no routes found.
+// Returns (routes, townRoot). Returns nil routes if not in an orchestrator town or no routes found.
 func findTownRoutes(currentBeadsDir string) ([]Route, string) {
 	// First try the current beads dir (works if we're already at town level)
 	routes, err := LoadRoutes(currentBeadsDir)
@@ -306,7 +306,7 @@ func findTownRoutes(currentBeadsDir string) ([]Route, string) {
 	// Walk up to find town root
 	townRoot := findTownRoot(currentBeadsDir)
 	if townRoot == "" {
-		return nil, "" // Not in a Gas Town
+		return nil, "" // Not in a town
 	}
 
 	// Load routes from town beads

scripts/bump-version.sh

@@ -29,16 +29,14 @@ set -e
 #   For guided, resumable releases with multiple agents:
 #   bd template instantiate bd-6s61 --var version=X.Y.Z --assignee <identity>
 #
-# IMPORTANT: In Gas Town, run from mayor/rig to avoid git conflicts with bd sync
+# IMPORTANT: In multi-clone setups, run from the main clone to avoid git conflicts
 # =============================================================================
 #
-# Gas Town agents share a beads database at mayor/rig/.beads/. The bd sync
+# Multi-clone setups share a beads database at a central location. The bd sync
 # command commits from that clone. Running version bumps from a different
-# clone (e.g., crew/dave) causes push conflicts when bd sync tries to push.
+# clone causes push conflicts when bd sync tries to push.
 #
-# Always run releases from the rig root:
+# Always run releases from the main clone (the one that owns the beads database).
-#
-#   cd ~/gt/beads/mayor/rig && ./scripts/bump-version.sh X.Y.Z --commit --tag --push --all
 #
 # =============================================================================