docs: update public positioning for Gas Town

- Rewrite vision.md with enterprise cognitive processing framing - Expand README with comprehensive project overview - Remove internal strategic references from merge-queue-design.md - Position Gas Town as "IDE of 2026" for AI agent orchestration Key messaging: - Enterprise-grade cognitive processing machine - Molecules as structured workflow guardrails - Nondeterministic idempotence for crash recovery - Beads as unified control/data plane - Hierarchical auditability and observability 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-20 00:21:18 -08:00
parent 71d313ed60
commit f43c01de4e
4 changed files with 328 additions and 180 deletions
--- a/.beads/issues.jsonl
+++ b/.beads/issues.jsonl
@@ -77,6 +77,7 @@
 {"id":"gt-69l","title":"Hook system for event extensibility","description":"GGT needs hook system for extensibility like PGT.\n\n## Event Types\n```go\ntype Event string\nconst (\n    EventPreSessionStart  Event = \"pre-session-start\"\n    EventPostSessionStart Event = \"post-session-start\"\n    EventPreShutdown      Event = \"pre-shutdown\"\n    EventPostShutdown     Event = \"post-shutdown\"\n    EventOnPaneOutput     Event = \"on-pane-output\"\n    EventSessionIdle      Event = \"session-idle\"\n    EventMailReceived     Event = \"mail-received\"\n    EventWorkAssigned     Event = \"work-assigned\"\n)\n```\n\n## Hook Configuration\nFile: .claude/hooks.json or .gastown/hooks.json\n```json\n{\n  \"hooks\": {\n    \"pre-shutdown\": [\n      {\"type\": \"command\", \"cmd\": \"./scripts/pre-shutdown.sh\"}\n    ],\n    \"on-pane-output\": [\n      {\"type\": \"command\", \"cmd\": \"./scripts/activity-monitor.sh\"}\n    ]\n  }\n}\n```\n\n## Hook Types\n1. **Command**: Execute external script\n2. **Built-in**: Internal Go functions (pre-shutdown checks)\n\n## Hook Interface\n```go\ntype HookRunner struct {\n    config *HookConfig\n}\n\ntype HookResult struct {\n    Success bool\n    Message string\n    Block   bool  // For pre-* hooks: should operation be blocked?\n}\n\nfunc (r *HookRunner) Fire(event Event, ctx *HookContext) []HookResult\n```\n\n## CLI Commands\n```\ngt hooks list [\u003cevent\u003e]    # List registered hooks\ngt hooks fire \u003cevent\u003e      # Manually fire for testing\ngt hooks test [--all]      # Validate hook config\n```\n\n## Integration Points\n- internal/session/manager.go: Fire pre/post session hooks\n- internal/mail/router.go: Fire mail-received hook\n\n## New Package\ninternal/hooks/\n├── types.go    # Event, HookConfig, HookResult\n├── runner.go   # HookRunner, Fire()\n└── builtin.go  # Built-in hooks (pre-shutdown checks)\n\n## PGT Reference\ngastown-py/src/gastown/hooks/\n\n## Acceptance Criteria\n- [ ] Hook config loading from JSON\n- [ ] Command hooks execute subprocess\n- [ ] Pre-shutdown hook integration with session stop\n- [ ] CLI for listing and testing hooks","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-16T14:47:34.584907-08:00","updated_at":"2025-12-16T16:04:47.890588-08:00"}
 {"id":"gt-6db","title":"gt rig shutdown: Gracefully stop all rig agents","description":"Add 'gt rig shutdown \u003crig\u003e' command to gracefully stop all agents in a rig.\n\nShould:\n- Stop all polecat sessions\n- Stop refinery\n- Stop witness\n- Optionally wait for graceful shutdown with timeout","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-17T21:50:07.938698-08:00","updated_at":"2025-12-19T12:05:27.341209-08:00","closed_at":"2025-12-19T12:05:27.341209-08:00","dependencies":[{"issue_id":"gt-6db","depends_on_id":"gt-hw6","type":"blocks","created_at":"2025-12-17T22:23:43.179236-08:00","created_by":"daemon"}]}
 {"id":"gt-6k8","title":"Interrupt vs Queue mail semantics","description":"Add priority/delivery semantics to mail messages.\n\n## Semantics\n\n| Type | Delivery | Use Case |\n|------|----------|----------|\n| Interrupt | tmux send-keys | Lifecycle, URGENT, stuck detection |\n| Queue | Create message only | Normal mail, status, heartbeat |\n\n## Implementation\n\n- `bd mail send --interrupt` uses tmux send-keys notification\n- Default is queue (agent checks with `gt mail check`)\n- Urgent flag on messages for interrupt delivery\n\n## Agent Side\n\n- `gt mail check --quiet` - non-blocking check for queued mail\n- `gt mail wait` - block until mail arrives (for idle agents)\n- Heartbeats become queued, agent checks at natural breakpoints","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-18T14:19:28.408196-08:00","updated_at":"2025-12-19T17:22:52.555329-08:00","closed_at":"2025-12-19T16:31:00.450061-08:00","dependencies":[{"issue_id":"gt-6k8","depends_on_id":"gt-99m","type":"blocks","created_at":"2025-12-18T14:19:46.529252-08:00","created_by":"daemon"}]}
+{"id":"gt-6lt3","title":"Work on ga-rd4: Add gt polecat status command. Show detai...","description":"Work on ga-rd4: Add gt polecat status command. Show detailed polecat status including current issue, session state, last activity time. When done, submit MR (not PR) to integration branch for Refinery.","status":"closed","priority":2,"issue_type":"task","assignee":"gastown/rictus","created_at":"2025-12-19T22:58:26.320627-08:00","updated_at":"2025-12-19T23:23:07.448718-08:00","closed_at":"2025-12-19T23:23:07.448718-08:00","close_reason":"Implemented gt polecat status command with session info and activity time"}
 {"id":"gt-6t0","title":"gt swarm: Not discovering tasks from epic dependents","description":"gt swarm create/start shows '0 tasks loaded' even when epic has dependents.\n\nRepro:\n1. Create epic gt-hw6\n2. Create tasks and add deps: bd dep add gt-xxx gt-hw6\n3. gt swarm create gastown --epic gt-hw6 --worker Toast\n4. Swarm shows 'Tasks: 0'\n\nExpected: Swarm should discover tasks that depend on the epic.\nActual: Shows '(no tasks loaded)'","status":"closed","priority":0,"issue_type":"bug","created_at":"2025-12-17T22:25:41.653628-08:00","updated_at":"2025-12-17T22:31:58.848858-08:00","closed_at":"2025-12-17T22:31:58.848858-08:00"}
 {"id":"gt-6tf","title":"Implement gt harness create command","description":"Add scaffolding command to create a new harness:\n- gt harness create [path]\n- Creates config/, mayor/, .beads/redirect (optional)\n- Optionally initializes git\n- Generates CLAUDE.md with Mayor role\n- Could also offer a template repo alternative","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-17T17:15:34.342552-08:00","updated_at":"2025-12-17T17:20:36.774805-08:00","closed_at":"2025-12-17T17:20:36.774805-08:00","dependencies":[{"issue_id":"gt-6tf","depends_on_id":"gt-cr9","type":"blocks","created_at":"2025-12-17T17:15:51.845578-08:00","created_by":"daemon"}]}
 {"id":"gt-6z2","title":"Test Epic: GGT MVP Validation","description":"","status":"closed","priority":0,"issue_type":"epic","created_at":"2025-12-16T21:57:37.355269-08:00","updated_at":"2025-12-16T22:06:41.124727-08:00","closed_at":"2025-12-16T22:06:41.124727-08:00"}
@@ -100,6 +101,7 @@
 {"id":"gt-8j8e","title":"gt mail send: --priority flag should work like bd mail send","description":"UX inconsistency: gt mail send passes flags that bd mail send doesn't support.\n\n## Root Cause\n\nrouter.go line 42 passes `--priority` to bd:\n```go\nargs = append(args, \"--priority\", fmt.Sprintf(\"%d\", beadsPriority))\n```\n\nBut `bd mail send` only has `--urgent` (boolean), not `--priority`.\n\n## Fix Options\n\n1. Add `--priority` flag to `bd mail send` (preferred - more expressive)\n2. Change router to only use `--urgent` when priority=0\n\n## Also Affected\n\n- `--type` flag (line 46) - bd mail send doesn't have this\n- `--thread-id` flag (line 51) - bd mail send doesn't have this  \n- `--reply-to` flag (line 56) - bd mail send doesn't have this\n\nThe router assumes bd mail send has features it doesn't have.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-18T21:31:05.486487-08:00","updated_at":"2025-12-19T12:07:28.918346-08:00","closed_at":"2025-12-19T12:07:28.918346-08:00"}
 {"id":"gt-8lz","title":"Comprehensive help text and examples","description":"Improve help text with examples and cross-references.\n\n## Improvements\n\n### 1. Examples Section\nAdd to Long description:\n```go\nvar spawnCmd = \u0026cobra.Command{\n    Long: `Spawn a polecat with work assignment.\n\nExamples:\n  gt spawn gastown/Toast --issue gt-abc\n  gt spawn gastown --issue gt-def          # auto-select polecat\n  gt spawn gastown/Nux -m \"Fix the tests\"  # free-form task`,\n}\n```\n\n### 2. Cross-References\nReference related commands:\n```\nSee also:\n  gt polecat list    List available polecats\n  gt session attach  Attach to spawned session\n```\n\n### 3. Flag Descriptions\nMore detail on flags:\n```go\ncmd.Flags().StringVar(\u0026issue, \"issue\", \"\", \n    \"Beads issue ID to assign. The polecat will work on this issue.\")\n```\n\n### 4. Common Workflows\nAdd workflow docs to gt --help:\n```\nCommon Workflows:\n  Start a swarm:\n    gt swarm preflight\n    gt swarm create gastown --epic gt-abc --worker Toast --worker Nux --start\n    gt refinery start gastown\n    \n  Check status:\n    gt status\n    gt swarm status \u003cid\u003e\n```\n\n## Files to Update\nAll internal/cmd/*.go files\n\n## Acceptance Criteria\n- [ ] All commands have Examples\n- [ ] Related commands cross-referenced\n- [ ] Flags have detailed descriptions\n- [ ] Root help shows workflows","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-16T14:48:53.303016-08:00","updated_at":"2025-12-16T16:07:37.391195-08:00"}
 {"id":"gt-8mbz","title":"Town Doctor molecule for harness health checks","description":"Create a Town Doctor molecule that any Gas Town agent can run to diagnose and repair harness issues.\n\n## Concept\n\nInstead of just `gt doctor` as a CLI command with hardcoded checks, create a **molecule** (checklist workflow) that:\n- Any agent (Mayor, Witness, Polecat) can instantiate\n- Walks the agent through diagnostic steps\n- Agent uses judgment to fix issues found\n- Works as a structured troubleshooting guide\n\n## Why a Molecule?\n\n1. **Agent-driven**: The agent running it becomes \"the doctor\" temporarily\n2. **Extensible**: Add new checks by updating the molecule, not code\n3. **Contextual**: Agent can reason about issues, not just run scripts\n4. **Self-healing**: Agent can fix problems it finds, not just report them\n\n## Proposed Checks (molecule steps)\n\n1. Verify harness structure (mayor/, .beads/, CLAUDE.md exist)\n2. Validate config files (town.json, rigs.json parse correctly)\n3. Check beads health (bd doctor, redirect validity)\n4. Verify git state (clean working tree, proper remotes)\n5. Check rig integrity (each registered rig exists, has config.json)\n6. Validate agent clones (mayor/rig/, refinery/rig/ exist and are valid)\n7. Check for orphaned worktrees/branches\n8. Verify daemon state (if running)\n\n## Integration\n\n- `gt doctor` could instantiate the molecule for the current agent\n- Or agent can run `bd ready` and pick up doctor tasks when prioritized\n- Results logged to beads for audit trail\n\n## Related\n\n- gt-cr9: Harness Design \u0026 Documentation (completed)\n- Molecules design in architecture.md","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-19T13:03:22.688851-08:00","updated_at":"2025-12-19T13:03:22.688851-08:00"}
+{"id":"gt-8os8","title":"Work on ga-p6r: Add handoff protocol to spawn priming. En...","description":"Work on ga-p6r: Add handoff protocol to spawn priming. Ensure polecats receive handoff context when spawned. When done, submit MR (not PR) to integration branch for Refinery.","status":"closed","priority":2,"issue_type":"task","assignee":"gastown/furiosa","created_at":"2025-12-19T22:57:59.334003-08:00","updated_at":"2025-12-19T23:22:07.076974-08:00","closed_at":"2025-12-19T23:22:07.076974-08:00","close_reason":"Added handoff protocol to spawn priming: updated work assignment mail with handoff checklist, created gt done command for polecats"}
 {"id":"gt-8r7","title":"Enhance Mayor CLAUDE.md with GGT milestone tracking","description":"Update ~/ai/CLAUDE.md (Mayor startup context) with:\n\n1. GGT Self-Hosting Milestone section\n   - Track progress toward gt replacing town\n   - Key blockers: gt-h5n (merge queue), gt-974 (daemon)\n   - What \"self-hosting\" means (GGT working on itself)\n\n2. Recent Architecture Decisions\n   - Engineer = role, Refinery = place\n   - Merge queue in Beads (not branch discovery)\n   - Session restart protocol\n\n3. Transition Plan\n   - Current: use town commands (PGT)\n   - Target: use gt commands (GGT)\n   - Switch criteria: gt-b1g closed\n\nKeep it concise - Mayor context should be quick to scan.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-16T23:12:07.260653-08:00","updated_at":"2025-12-16T23:12:07.260653-08:00","dependencies":[{"issue_id":"gt-8r7","depends_on_id":"gt-h5n","type":"blocks","created_at":"2025-12-16T23:12:15.124842-08:00","created_by":"daemon"}]}
 {"id":"gt-8wf","title":"Polecat prompting: gt mq submit on completion","description":"Update Polecat CLAUDE.md prompting to:\n\n1. On task completion, run: gt mq submit --issue \u003cid\u003e\n2. This creates a merge-request bead in the queue\n3. Engineer will process it\n\nThe Polecat self-reports completion to the merge queue.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-16T23:02:39.914724-08:00","updated_at":"2025-12-16T23:02:39.914724-08:00","dependencies":[{"issue_id":"gt-8wf","depends_on_id":"gt-h5n","type":"blocks","created_at":"2025-12-16T23:02:55.930679-08:00","created_by":"daemon"},{"issue_id":"gt-8wf","depends_on_id":"gt-svi","type":"blocks","created_at":"2025-12-16T23:03:12.950782-08:00","created_by":"daemon"}]}
 {"id":"gt-92l","title":"Daemon: integration test with real lifecycle","description":"Need an end-to-end test that:\n1. Starts daemon\n2. Starts a test agent session\n3. Sends lifecycle request to daemon\n4. Verifies session was killed and restarted\n5. Cleans up\n\nCould use a mock 'agent' that's just a shell script.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-18T13:38:17.261096-08:00","updated_at":"2025-12-19T17:22:52.555739-08:00","closed_at":"2025-12-19T16:31:23.543204-08:00","dependencies":[{"issue_id":"gt-92l","depends_on_id":"gt-99m","type":"blocks","created_at":"2025-12-18T13:38:26.962642-08:00","created_by":"daemon"}]}
@@ -268,9 +270,11 @@
 {"id":"gt-ov2","title":"Refinery agent: merge queue processing loop","description":"The Refinery agent processes the merge queue, merging polecat work to main.\n\n## Interface\n\n```go\ntype Refinery struct {\n    rig    *Rig\n    queue  *MergeQueue\n    git    *Git\n    mail   *Mailbox\n    config RefineryConfig\n}\n\ntype RefineryConfig struct {\n    AutoMerge     bool          // Auto-merge passing MRs\n    RunTests      bool          // Run tests before merge\n    TestCommand   string        // Command to run tests\n    RequireReview bool          // Require review before merge (future)\n}\n\nfunc NewRefinery(rig *Rig, ...) *Refinery\n\n// Lifecycle\nfunc (r *Refinery) Start() error\nfunc (r *Refinery) Stop() error\nfunc (r *Refinery) IsRunning() bool\n\n// Processing\nfunc (r *Refinery) ProcessQueue() error\nfunc (r *Refinery) ProcessMR(mr *MergeRequest) error\n```\n\n## Processing Loop\n\n1. Check queue for pending MRs\n2. For each pending MR:\n   a. Fetch polecat branch\n   b. Attempt merge to refinery/rig (local main)\n   c. Run tests if configured\n   d. If pass: push to origin, mark merged\n   e. If fail: mark rejected, notify polecat\n3. Sleep, repeat\n\n## Merge Strategy\n\n- Fast-forward when possible\n- Merge commit when not\n- On conflict: reject MR, polecat must rebase\n\n## Test Integration\n\nIf tests configured:\n```bash\ncd refinery/rig\ngit merge polecat/branch\n\u003ctest_command\u003e  # e.g., go test ./...\n```\nResult determines merge/reject.\n\n## Notifications\n\nOn merge success:\n- Mail to polecat: \"Your work merged\"\n- Update bead if issue tracked\n\nOn merge failure:\n- Mail to polecat: \"Merge failed: \u003creason\u003e\"\n- Include conflict details if applicable\n\n## Dependencies\n\nNeeds: Rig management, Git wrapper, Mail system, Merge queue","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-15T23:22:08.498771-08:00","updated_at":"2025-12-16T14:20:35.032221-08:00","closed_at":"2025-12-16T14:20:35.032221-08:00","dependencies":[{"issue_id":"gt-ov2","depends_on_id":"gt-u1j.14","type":"blocks","created_at":"2025-12-15T23:22:21.801826-08:00","created_by":"daemon"},{"issue_id":"gt-ov2","depends_on_id":"gt-u1j.6","type":"blocks","created_at":"2025-12-15T23:22:21.89716-08:00","created_by":"daemon"}]}
 {"id":"gt-ox9","title":"Test from Mayor","description":"This is a test message via GGT mail","status":"closed","priority":2,"issue_type":"message","created_at":"2025-12-16T22:04:31.483843-08:00","updated_at":"2025-12-16T22:06:41.127633-08:00","closed_at":"2025-12-16T22:06:41.127633-08:00"}
 {"id":"gt-pio","title":"Plugin: merge-oracle (merge queue analysis)","description":"Example plugin that analyzes changesets before Refinery processes them. Builds overlap graph, classifies disjointness (parallel-safe vs needs-sequencing), uses LLM for semantic complexity, identifies high-risk patterns. Based on merge-orchestration proposal. See docs/architecture.md.","status":"open","priority":3,"issue_type":"feature","created_at":"2025-12-15T22:53:04.027073-08:00","updated_at":"2025-12-15T23:17:06.507108-08:00","dependencies":[{"issue_id":"gt-pio","depends_on_id":"gt-axz","type":"blocks","created_at":"2025-12-15T22:53:17.507459-08:00","created_by":"daemon"}]}
+{"id":"gt-pyqv","title":"Work on ga-ct2: Add MR workflow to polecat completion. Wh...","description":"Work on ga-ct2: Add MR workflow to polecat completion. When polecat completes work, auto-create MR to integration branch. When done, submit MR (not PR) to integration branch for Refinery.","status":"closed","priority":2,"issue_type":"task","assignee":"gastown/dementus","created_at":"2025-12-19T22:58:35.473928-08:00","updated_at":"2025-12-19T23:22:57.087792-08:00","closed_at":"2025-12-19T23:22:57.087792-08:00","close_reason":"Implemented auto-MR submission in gt handoff for polecats"}
 {"id":"gt-q8du","title":"Configuration in Beads: use pinned beads for rig/agent config","description":"## Summary\n\nMove configuration from JSON files into Beads data plane using pinned beads.\n\n## Motivation\n\n- Config becomes versionable and syncable like issues\n- Agents can read config via `bd show`\n- Unified data model for everything\n- Supports the 'Beads as Universal Data Plane' vision (gt-aqm)\n\n## Config Types to Migrate\n\n### Rig-level (pinned per rig)\n- Theme/colors for tmux status line\n- Default branch naming conventions\n- Merge queue settings\n- Witness thresholds\n\n### Agent-level (pinned per role)\n- Handoffs (already planned - gt-cu7r)\n- Agent preferences\n- Current focus/context\n\n### Town-level (pinned at town root)\n- Cross-rig settings\n- Federation config\n- Global themes\n\n## Implementation\n\n1. Implement StatusPinned (beads-6v2) ✓ in progress\n2. Create config pinned beads on rig init\n3. Add `bd config get/set` commands that read/write pinned beads\n4. Migrate existing config.json fields\n\n## Naming Convention\n\n```\n\u003cprefix\u003e-cfg-\u003cscope\u003e\ngt-cfg-theme      # gastown theme\nbd-cfg-merge      # beads merge settings\ngm-cfg-town       # town-level config\n```\n\n## Dependencies\n\n- beads-6v2: Add StatusPinned to beads schema\n- gm-w13: Pinned Beads epic","status":"open","priority":2,"issue_type":"epic","created_at":"2025-12-18T21:58:59.898116-08:00","updated_at":"2025-12-18T21:58:59.898116-08:00"}
 {"id":"gt-qaca","title":"Merge: gt-5af.2","description":"branch: polecat/Doof\ntarget: main\nsource_issue: gt-5af.2\nrig: gastown","status":"open","priority":1,"issue_type":"merge-request","created_at":"2025-12-19T17:29:36.838038-08:00","updated_at":"2025-12-19T17:29:36.838038-08:00"}
 {"id":"gt-qao","title":"CLI: mayor commands (start, attach, stop, status)","description":"Mayor management CLI commands.\n\n## Commands\n\n### gt mayor start\n```\ngt mayor start [--continue] [--agent AGENT]\n```\n- --continue: Resume from previous session (check for handoff mail)\n- --agent: claude (default) or other agent type\n\n### gt mayor attach\n```\ngt mayor attach\n```\nAttach to running Mayor session.\n\n### gt mayor stop\n```\ngt mayor stop [--grace-period N]\n```\nStop Mayor session with optional grace period.\n\n### gt mayor status\n```\ngt mayor status [--json]\n```\nShow Mayor running status.\n\n## Session Management\nSession name: `gt-mayor`\nWorking directory: `\u003ctown\u003e/mayor/rig/` or `\u003ctown\u003e/mayor/`\n\n## Implementation\nSimilar to session commands but for special Mayor context.\n\n```go\nfunc getMayorPath(townRoot string) string {\n    return filepath.Join(townRoot, \"mayor\")\n}\n\nfunc getMayorSessionName() string {\n    return \"gt-mayor\"\n}\n```\n\n## New File\ninternal/cmd/mayor.go\n\n## PGT Reference\ngastown-py/src/gastown/cli/mayor_cmd.py\n\n## Acceptance Criteria\n- [ ] gt mayor start launches Mayor session\n- [ ] gt mayor attach works\n- [ ] gt mayor stop with grace period\n- [ ] gt mayor status shows running state","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-16T14:47:54.721035-08:00","updated_at":"2025-12-16T16:05:45.226324-08:00"}
+{"id":"gt-qbdb","title":"Work on ga-lzh: Add gt witness attach command. Allow atta...","description":"Work on ga-lzh: Add gt witness attach command. Allow attaching to witness session for a rig, similar to gt mayor attach. When done, submit MR (not PR) to integration branch for Refinery.","status":"closed","priority":2,"issue_type":"task","assignee":"gastown/capable","created_at":"2025-12-19T22:58:44.945425-08:00","updated_at":"2025-12-19T23:19:24.42686-08:00","closed_at":"2025-12-19T23:19:24.42686-08:00","close_reason":"gt witness attach command already implemented and tested"}
 {"id":"gt-qh2","title":"Session cycling UX: smooth transitions via TUI wrapper","description":"## Problem\n\nCurrent CLI agent session cycling is painful:\n- Shell → CC starts → priming → context loads → ready → work → exit/crash → repeat\n- Each cycle is 30-60 seconds of cold boot\n- No continuity between shell and agent's inner state\n- Raw \"session not running, starting...\" loop is the baseline\n\n## GGT Advantages (already have)\n\n- Beads: Work state survives session death completely\n- Mail: Handoff notes from past-self to future-self  \n- Prime commands: Structured context reload\n\n## Gap: Transition Mechanics\n\nIdeas to explore when actively using CLI:\n\n1. **In-band cycling** - `/restart` or `/cycle` command, agent handles own restart without dropping to shell\n\n2. **Hot standby** - TUI maintains pre-warmed session in background, switch to already-primed agent\n\n3. **Persistent wrapper** - Bubbletea TUI stays running across session cycles, CC sessions come/go inside it\n\n4. **Session pooling** - Keep 2-3 primed sessions ready, never wait for cold start\n\n## Deferred\n\nDeliberately P4 until we're actively using the simpler CLI and feel the pain firsthand.","status":"open","priority":4,"issue_type":"task","created_at":"2025-12-15T20:38:12.660716-08:00","updated_at":"2025-12-15T23:17:34.27061-08:00"}
 {"id":"gt-qivm","title":"gt crew at: auto-prime when exec'ing Claude in-session","description":"When running 'gt crew at \u003cname\u003e' from inside the target session, we exec Claude directly. But this means we can't send 'gt prime' afterward since we ARE the process.\n\nPossible solutions:\n1. Claude startup hook that runs gt prime\n2. Pass prompt as argument to claude CLI\n3. Wrapper script approach\n\nRelated: crew resume prompt also can't be sent in this path.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-19T15:13:38.035775-08:00","updated_at":"2025-12-19T15:13:38.035775-08:00"}
 {"id":"gt-qn4l","title":"bd create should support molecule type","description":"gt molecule commands expect type=molecule but bd validates against bug|feature|task|epic|chore|merge-request only","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-19T18:25:31.591953-08:00","updated_at":"2025-12-19T18:41:15.654491-08:00","closed_at":"2025-12-19T18:41:15.654491-08:00","close_reason":"molecule type support added to bd in commit 46488d4f"}
@@ -328,6 +332,7 @@
 {"id":"gt-u82","title":"Design: Mayor session cycling and handoff","description":"Design for Mayor session cycling and structured handoff.\n\n## Overview\n\nMayor coordinates across all rigs and runs for extended periods. Needs session cycling pattern with structured handoff notes.\n\n## Key Elements\n\n1. Session cycling recognition (when to cycle)\n2. Handoff note format (structured state capture)\n3. Handoff delivery (mail to self)\n4. Fresh session startup (reading and resuming)\n\n## Subtasks (implementation)\n\n- gt-g2d: Mayor session cycling prompting\n- gt-sye: Mayor startup protocol prompting\n- gt-vci: Mayor handoff mail template\n- gt-1le: town handoff command (optional, P2)\n\n**Design complete.** Each subtask has full specification in its description.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-15T20:03:16.125725-08:00","updated_at":"2025-12-15T20:49:26.203276-08:00","closed_at":"2025-12-15T20:16:10.772149-08:00"}
 {"id":"gt-unrd","title":"Fix gt prime to give crew workers crew context","description":"gt prime currently gives Mayor context to all agents. Crew workers should get crew-specific context. Also extract shared theory of operation from mayor priming into shared context for all roles.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-19T15:37:49.671015-08:00","updated_at":"2025-12-19T17:22:52.551704-08:00","closed_at":"2025-12-19T15:41:38.806903-08:00"}
 {"id":"gt-us8","title":"Daemon: configurable heartbeat interval","description":"Heartbeat interval is hardcoded to 60s. Should be configurable via:\n- town.json config\n- Command line flag\n- Environment variable\n\nDefault 60s is reasonable but some deployments may want faster/slower.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-18T13:38:14.282216-08:00","updated_at":"2025-12-18T13:38:14.282216-08:00","dependencies":[{"issue_id":"gt-us8","depends_on_id":"gt-99m","type":"blocks","created_at":"2025-12-18T13:38:26.704111-08:00","created_by":"daemon"}]}
+{"id":"gt-v5hv","title":"Work on ga-y6b: Implement Refinery as Claude agent. Conve...","description":"Work on ga-y6b: Implement Refinery as Claude agent. Convert from shell to Claude agent that processes MRs in merge queue, runs tests, merges to integration branch. When done, submit MR (not PR) to integration branch for Refinery.","status":"closed","priority":2,"issue_type":"task","assignee":"gastown/slit","created_at":"2025-12-19T22:58:17.576892-08:00","updated_at":"2025-12-19T23:23:22.778407-08:00","closed_at":"2025-12-19T23:23:22.778407-08:00","close_reason":"Implemented Refinery as Claude agent"}
 {"id":"gt-v5k","title":"Design: Failure modes and recovery","description":"Document failure modes and recovery strategies for Gas Town operations.\n\n## Critical Failure Modes\n\n### 1. Agent Crash Mid-Operation\n\n**Scenario**: Polecat crashes while committing, Witness crashes while verifying\n\n**Detection**:\n- Session suddenly gone (tmux check fails)\n- State shows 'working' but no session\n- Heartbeat stops (for Witness)\n\n**Recovery**:\n- Doctor detects via ZombieSessionCheck\n- Capture any recoverable state\n- Reset agent state to 'idle'\n- For Witness: auto-restart via supervisor or manual gt witness start\n\n### 2. Git State Corruption\n\n**Scenario**: Merge conflict, failed rebase, detached HEAD\n\n**Detection**:\n- Git commands fail\n- Dirty state that won't commit\n- Branch diverged from origin\n\n**Recovery**:\n- gt doctor reports git health issues\n- Manual intervention recommended\n- Severe cases: remove clone, re-clone\n\n### 3. Beads Sync Conflict\n\n**Scenario**: Two polecats modify same issue\n\n**Detection**:\n- bd sync fails with conflict\n- Beads tombstone mechanism handles most cases\n\n**Recovery**:\n- Beads has last-write-wins semantics\n- bd sync --force in extreme cases\n- Issues may need manual dedup\n\n### 4. Tmux Failure\n\n**Scenario**: Tmux server crashes, socket issues\n\n**Detection**:\n- All sessions inaccessible\n- \"no server running\" errors\n\n**Recovery**:\n- Kill any orphan processes\n- tmux kill-server \u0026\u0026 tmux start-server\n- All agent states reset to idle\n- Re-spawn active work\n\n### 5. Claude API Issues\n\n**Scenario**: Rate limits, outages, context limits\n\n**Detection**:\n- Sessions hang or produce errors\n- Repeated failure patterns\n\n**Recovery**:\n- Exponential backoff (handled by Claude Code)\n- For context limits: session cycling (mail-to-self)\n- For outages: wait and retry\n\n### 6. Disk Full\n\n**Scenario**: Clones, logs, or beads fill disk\n\n**Detection**:\n- Write operations fail\n- git/bd commands error\n\n**Recovery**:\n- Clean up logs: rm ~/.gastown/logs/*\n- Remove old polecat clones\n- gt doctor --fix can clean some cruft\n\n### 7. Network Failure\n\n**Scenario**: Can't reach GitHub, API servers\n\n**Detection**:\n- git fetch/push fails\n- Claude sessions hang\n\n**Recovery**:\n- Work continues locally\n- Queue pushes for later\n- Sync when connectivity restored\n\n## Recovery Principles\n\n1. **Fail safe**: Prefer stopping over corrupting\n2. **State is recoverable**: Git and beads have recovery mechanisms\n3. **Doctor heals**: gt doctor --fix handles common issues\n4. **Emergency stop**: gt stop --all as last resort\n5. **Human escalation**: Some failures need Overseer intervention\n\n## Implementation\n\n- Document each failure mode in architecture.md\n- Ensure doctor checks cover detection\n- Add recovery hints to error messages\n- Log all failures for debugging","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T23:19:07.198289-08:00","updated_at":"2025-12-15T23:19:28.171942-08:00"}
 {"id":"gt-vc1n","title":"Tmux status line: rig color themes and worker identity display","description":"## Summary\n\nCustomize tmux status line for Gas Town workers with:\n1. Per-rig configurable color themes\n2. Clear worker name and role visibility\n\n## Current Problem\n\n- Only mayor shows in status line (and truncated)\n- Can't tell which rig/worker you're looking at\n- All sessions look the same\n\n## Proposed Design\n\n### Per-rig colors\n```yaml\n# In rig config or beads\ntheme:\n  primary: '#ff6600'    # Orange for gastown\n  secondary: '#333333'\n  accent: '#ffcc00'\n```\n\n### Status line format\n```\n[gastown/Rictus] polecat | gt-70b3 | branch: polecat/Rictus\n[beads/emma] crew | working | branch: main  \n[mayor] coordinator | idle\n```\n\n### Components\n- Rig name with rig color\n- Worker name\n- Role (polecat/crew/mayor/witness/refinery)\n- Current issue or status\n- Branch name\n\n## Configuration\n\nCould use pinned beads for this (see gm-w13, beads-6v2):\n- `bd show \u003crig\u003e-theme` returns theme config\n- Stored as pinned bead, always available\n- Part of 'config in beads data plane' initiative","notes":"Implementation complete. Core features: per-rig color themes, dynamic status line with issue/mail indicators, gt theme/issue commands. Ready for testing.","status":"in_progress","priority":2,"issue_type":"feature","created_at":"2025-12-18T21:58:58.547188-08:00","updated_at":"2025-12-19T14:25:02.135073-08:00"}
 {"id":"gt-vci","title":"Mayor handoff mail template","description":"Add MAYOR_HANDOFF mail template to templates.py.\n\n## Template Function\n\ndef mayor_handoff(\n    active_swarms: List[SwarmStatus],\n    rig_status: Dict[str, RigStatus],\n    pending_escalations: List[Escalation],\n    in_flight_decisions: List[Decision],\n    recent_actions: List[str],\n    delegated_work: List[DelegatedItem],\n    user_requests: List[str],\n    next_steps: List[str],\n    warnings: Optional[str] = None,\n    session_duration: Optional[str] = None,\n) -\u003e Message:\n    metadata = {\n        'template': 'MAYOR_HANDOFF',\n        'timestamp': datetime.utcnow().isoformat(),\n        'session_duration': session_duration,\n        'active_swarm_count': len(active_swarms),\n        'pending_escalation_count': len(pending_escalations),\n    }\n    # ... format sections ...\n    return Message.create(\n        sender='mayor/',\n        recipient='mayor/',\n        subject='Session Handoff',\n        body=body,\n        priority='high',\n    )\n\n## Metadata Fields\n\n- template: MAYOR_HANDOFF\n- timestamp: ISO format\n- session_duration: Human readable\n- active_swarm_count: Number of active swarms\n- pending_escalation_count: Number of escalations\n\n## Mail Priority\n\nUse priority='high' to ensure handoff is seen on startup.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T20:15:30.26323-08:00","updated_at":"2025-12-15T20:48:59.550689-08:00","dependencies":[{"issue_id":"gt-vci","depends_on_id":"gt-u82","type":"blocks","created_at":"2025-12-15T20:15:39.554108-08:00","created_by":"daemon"}]}
@@ -341,6 +346,7 @@
 {"id":"gt-w9o","title":"/restart: Personal slash command for in-place agent restart","description":"Create ~/.claude/commands/restart.md that restarts current Gas Town agent in place.\n\n## Detection\n- Read tmux session name: gt-mayor, gt-witness-*, gt-refinery-*, gt-polecat-*\n- Fallback: check GT_ROLE env var\n\n## Behavior by role\n- mayor: gt mayor restart (sends Ctrl-C, loop respawns)\n- witness: gt witness restart\n- refinery: gt refinery restart  \n- polecat: gt polecat restart (or witness-mediated)\n\n## Command format\nUses backticks for inline bash to detect context, then instructs Claude to run appropriate restart.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-18T18:32:30.043125-08:00","updated_at":"2025-12-18T18:43:17.182303-08:00","closed_at":"2025-12-18T18:43:17.182303-08:00"}
 {"id":"gt-wav5","title":"Merge: gt-a95","description":"branch: polecat/Ace\ntarget: main\nsource_issue: gt-a95\nrig: gastown","status":"closed","priority":1,"issue_type":"merge-request","created_at":"2025-12-19T14:53:30.210304-08:00","updated_at":"2025-12-19T18:26:14.103104-08:00","closed_at":"2025-12-19T18:26:14.103106-08:00"}
 {"id":"gt-wpg","title":"Replaceable notifications via Claude Code queue","description":"Leverage Claude Code's ability to replace queued text for notifications that supersede previous ones.\n\n## Problem\n\nIf daemon sends 10 heartbeats while agent is busy, agent returns to see 10 stacked messages. Wasteful and noisy.\n\n## Solution\n\nUse Claude Code's queue replacement for:\n- Heartbeat messages (only latest matters)\n- Status updates that supersede previous\n- Progress notifications\n\n## Implementation\n\nNotifications get a 'slot' identifier. New notification in same slot replaces old one:\n- Slot: 'heartbeat' → only one heartbeat queued at a time\n- Slot: 'status-\u003crig\u003e' → latest status per rig\n- No slot → stacks normally (for unique messages)\n\n## Research Needed\n\n- How does Claude Code expose queue replacement?\n- tmux send-keys behavior with pending input\n- Alternative: clear + resend pattern","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-18T14:19:29.821949-08:00","updated_at":"2025-12-18T14:19:29.821949-08:00","dependencies":[{"issue_id":"gt-wpg","depends_on_id":"gt-99m","type":"blocks","created_at":"2025-12-18T14:19:46.656972-08:00","created_by":"daemon"}]}
+{"id":"gt-xicq","title":"Work on ga-lue: Implement Witness as Claude agent. Conver...","description":"Work on ga-lue: Implement Witness as Claude agent. Convert from shell script to Claude agent that monitors polecats, nudges idle ones, handles escalations. When done, submit MR (not PR) to integration branch for Refinery.","status":"closed","priority":2,"issue_type":"task","assignee":"gastown/nux","created_at":"2025-12-19T22:58:08.310674-08:00","updated_at":"2025-12-19T23:24:36.692209-08:00","closed_at":"2025-12-19T23:24:36.692209-08:00","close_reason":"Implemented Witness as Claude agent with enhanced template, startup protocol, lifecycle processing, nudge/escalation protocols"}
 {"id":"gt-xkbm","title":"Merge: gt-g44u.1","description":"branch: polecat/Ace\ntarget: main\nsource_issue: gt-g44u.1\nrig: gastown","status":"closed","priority":0,"issue_type":"merge-request","created_at":"2025-12-19T16:04:14.367493-08:00","updated_at":"2025-12-19T17:35:38.210747-08:00","closed_at":"2025-12-19T17:35:38.210747-08:00"}
 {"id":"gt-xpq","title":"Add gt crew rename command","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-18T19:45:32.599846-08:00","updated_at":"2025-12-18T19:46:17.780981-08:00","closed_at":"2025-12-18T19:46:17.780981-08:00"}
 {"id":"gt-xqdk","title":"Add molecule to update local go binary on push to main","description":"When pushing to main branch, automatically rebuild and install the gt binary on the local machine so changes are immediately available.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-19T15:37:40.542228-08:00","updated_at":"2025-12-19T15:37:40.542228-08:00"}
--- a/README.md
+++ b/README.md
@@ -1,19 +1,138 @@
-# Gastown (Go)
+# Gas Town

-Go port of [Gas Town](https://github.com/steveyegge/gastown-py) - a multi-agent workspace manager.
+**Enterprise-grade cognitive processing for AI agent swarms.**
+
+Gas Town is a multi-agent workspace manager that coordinates AI coding agents working on software projects. It provides the infrastructure for spawning workers, processing work through structured workflows (molecules), and coordinating agents through a unified data plane (Beads).
+
+## The Idea
+
+Traditional AI coding assistants help you write code. Gas Town **writes code for you**.
+
+Instead of AI as autocomplete, Gas Town treats AI agents as workers:
+- **Polecats** implement features and fix bugs
+- **Refineries** review and merge code
+- **Witnesses** manage worker lifecycle
+- **Mayors** coordinate across projects
+
+Work flows through **molecules** - structured workflow templates that encode quality gates, dependencies, and recovery checkpoints. Any worker can continue any workflow from where another left off.
+
+## Key Features
+
+- **Nondeterministic Idempotence**: Workflows survive crashes, context compaction, and agent restarts
+- **Molecule-Based Quality**: Structured workflows with built-in gates, not prompt-based instructions
+- **Unified Data Plane**: All state in Beads (issues, messages, workflows) - queryable, auditable, persistent
+- **Hierarchical Coordination**: Mayor → Witness → Refinery → Polecat chain of command
+- **Federation Ready**: Multiple rigs across machines, coordinated through Beads sync
+
+## Quick Start
+
+```bash
+# Install
+go install github.com/steveyegge/gastown/cmd/gt@latest
+
+# Create a town (workspace)
+gt install ~/gt --git
+
+# Add a rig for your project
+gt rig add myproject --remote=https://github.com/you/myproject.git
+
+# Spawn a polecat to work on an issue
+gt spawn --issue myproject-123 --molecule mol-engineer-in-box
+```
+
+## Architecture
+
+```
+Town (~/gt/)
+├── Mayor (global coordinator)
+├── Rig: project-alpha
+│   ├── Witness (lifecycle manager)
+│   ├── Refinery (merge queue)
+│   └── Polecats (workers)
+│       ├── furiosa/
+│       ├── nux/
+│       └── slit/
+└── Rig: project-beta
+    └── ...
+```
+
+See [docs/architecture.md](docs/architecture.md) for comprehensive documentation.
+
+## Molecules
+
+Molecules are structured workflow templates:
+
+```markdown
+## Molecule: engineer-in-box
+Full workflow from design to merge.
+
+## Step: design
+Think carefully about architecture.
+Write a brief design summary.
+
+## Step: implement
+Write the code. Follow codebase conventions.
+Needs: design
+
+## Step: test
+Write and run tests. Cover edge cases.
+Needs: implement
+
+## Step: submit
+Submit for merge via refinery.
+Needs: test
+```
+
+Built-in molecules:
+- `mol-engineer-in-box` - Full quality workflow (design → implement → review → test → submit)
+- `mol-quick-fix` - Fast path for small changes (implement → test → submit)
+- `mol-research` - Exploration workflow (investigate → document)
+
+## Beads
+
+Gas Town uses [Beads](https://github.com/steveyegge/beads) for issue tracking and coordination:
+
+```bash
+bd ready              # Show work ready to start
+bd list --status=open # All open issues
+bd show gt-123        # Issue details
+bd create --title="Fix auth bug" --type=bug
+bd close gt-123       # Mark complete
+```
+
+## Commands
+
+```bash
+# Town management
+gt install <path>     # Create new town
+gt status             # Overall status
+gt doctor             # Diagnose issues
+
+# Rig management
+gt rig add <name>     # Add project rig
+gt rig list           # List rigs
+
+# Worker management
+gt spawn --issue <id> # Start polecat on issue
+gt polecat list <rig> # List polecats
+
+# Communication
+gt mail inbox         # Check messages
+gt mail send <addr>   # Send message
+```

 ## Status

 **Work in Progress** - This is the Go rewrite of the Python gastown tool.

-See the [Python version](https://github.com/steveyegge/gastown-py) for current functionality.
+See [gastown-py](https://github.com/steveyegge/gastown-py) for the Python version.

-## Goals
+## Documentation

- Single binary installation (`gt`)
- Self-diagnosing (`gt doctor`)
- Federation support (coordinate agents across VMs)
- Performance improvements over Python version
+- [Architecture](docs/architecture.md) - System design and concepts
+- [Vision](docs/vision.md) - Where Gas Town is going
+- [Federation](docs/federation-design.md) - Multi-machine coordination
+- [Merge Queue](docs/merge-queue-design.md) - Refinery and integration

 ## Development

@@ -21,11 +140,18 @@ See the [Python version](https://github.com/steveyegge/gastown-py) for current f
 # Build
 go build -o gt ./cmd/gt

-# Run
-./gt --help
+# Test
+go test ./...
+
+# Install locally
+go install ./cmd/gt
 ```

 ## Related

- [gastown-py](https://github.com/steveyegge/gastown-py) - Python version (current)
- [beads](https://github.com/steveyegge/beads) - Issue tracking for agents
+- [beads](https://github.com/steveyegge/beads) - Issue tracking for AI agents
+- [gastown-py](https://github.com/steveyegge/gastown-py) - Python version (reference)
+
+## License
+
+MIT
--- a/docs/merge-queue-design.md
+++ b/docs/merge-queue-design.md
@@ -348,25 +348,25 @@ bd list --type=merge-request --assignee=Nux
            └─────────────────┴─────────┘
 ```

-## Integration with HOP
+## Audit and Observability

-In the HOP framing, the merge queue is a **validation layer**:
+The merge queue creates a complete audit trail for all integrated work:

-| MQ Concept | HOP Concept |
-|------------|-------------|
-| Merge request | Work completion claim |
-| Engineer | Validator node |
-| Merge commit | Validation record |
-| Tests passing | Quality proof |
-| Rejection | Stake loss (reputation) |
+| MQ Event | Record Created |
+|----------|----------------|
+| Merge request submitted | Work completion claim with author |
+| Tests pass | Quality verification record |
+| Refinery approves | Validation with reviewer attribution |
+| Merge commit | Immutable integration record |
+| Rejection | Feedback record with reason |

 Every merge creates an immutable record:
- Who did the work (entity chain entry)
- Who validated it (Engineer attestation)
+- Who did the work (author attribution)
+- Who validated it (Refinery attestation)
 - When it landed (timestamp)
 - What changed (commit diff)

-This is the foundation for skill embeddings - successful merges build your chain.
+This enables full work attribution and quality tracking across the swarm.

 ## Configuration

--- a/docs/vision.md
+++ b/docs/vision.md
@@ -1,102 +1,93 @@
 # Gas Town Vision

 > Work is fractal. Every piece of work can contain other work, recursively.
-> Work history is proof of capability. Your CV is your chain.
+> The machine that processes this work must be equally fractal.

 ## The Big Picture

-Gas Town is more than an AI coding agent orchestrator. It's a **work execution engine** built on a universal ledger of work - where every task, every completion, every validation is recorded with cryptographic integrity.
+Gas Town is an **enterprise-grade cognitive processing machine**. It takes structured work in the form of molecules - arbitrarily complex guardrails that AI workers follow to completion - and processes that work with full auditability, crash recovery, and guaranteed progress.

-The system is designed to evolve from "coding agent coordinator" to "universal work allocation platform" without changing its fundamental architecture.
+Think of it as the **IDE of 2026**: not a text editor with AI autocomplete, but a complete execution environment where AI agents are first-class workers with proper lifecycle management, coordination protocols, and quality gates.

 ## Core Insights

-### 1. Git is Already a Blockchain
+### 1. Molecules Crystallize Workflows

-Git provides:
- **Merkle tree** - Cryptographic hashes linking history
- **Distributed consensus** - Push/pull with conflict resolution
- **Immutability** - History cannot be rewritten (without force)
- **Auditability** - Every change attributed to an author
+Every organization has processes that humans follow: code review checklists, release procedures, onboarding steps. These exist as tribal knowledge, wiki pages, or forgotten documents.

-We don't need to build a new blockchain. Git, combined with Beads, gives us the ledger infrastructure for free.
+**Molecules make these executable.** A molecule is a structured workflow template that:
+- Defines exactly what steps must happen
+- Encodes dependencies between steps
+- Specifies quality gates that must pass
+- Enables any worker to continue where another left off

-### 2. Work is a Universal Protocol
+```markdown
+## Molecule: engineer-in-box
+Full workflow from design to merge.

-Every piece of structured work can be expressed as:
- **Identity** - Who is doing the work
- **Specification** - What needs to be done
- **Acceptance criteria** - How we know it's done
- **Validation** - Who approved the completion
- **Provenance** - What work led to this work
+## Step: design
+Think carefully about architecture. Write a brief design summary.

-This applies equally to:
- Code commits and PRs
- Design documents
- Bug fixes
- Research tasks
- Any structured human or AI work
+## Step: implement
+Write the code. Follow codebase conventions.
+Needs: design

-### 3. Your Work History IS Your CV
+## Step: test
+Write and run tests. Cover edge cases.
+Needs: implement

-Instead of curated resumes:
- Every completed task is recorded
- Quality signals are captured (acceptance rate, revision count, review feedback)
- Skills are derived from demonstrated capability, not claimed expertise
- Reputation is earned through work, not credentials
-
-This is "proof-of-stake" for work:
- Stake = accumulated reputation
- Claim work → stake your reputation
- Complete well → reputation grows
- Fail → reputation diminished (but recoverable)
-
-### 4. Molecules Crystallize Workflows
-
-Molecules are reusable workflow patterns that encode:
- What steps a workflow contains
- How steps depend on each other
- What quality gates must pass
- How work can be parallelized
-
-Key properties:
- **Deterministic structure** - Same molecule, same step graph
- **Nondeterministic execution** - Any worker can execute any ready step
- **Idempotent progress** - Completed steps stay completed
-
-This enables the "engineer in a box" - AI agents that follow rigorous workflows with built-in quality gates, not just "do the task."
-
-### 5. Federation Creates the World Chain
-
-The recursive structure:
-```
-World
-├── Platform (GitHub, enterprise systems, ...)
-│   ├── Organization
-│   │   ├── Project
-│   │   │   ├── Epic
-│   │   │   │   └── Task chains
-│   │   │   │       └── Entity contribution records
+## Step: submit
+Submit for merge via refinery.
+Needs: test
 ```

-Each level has its own chain. Work rolls up. Skills aggregate. The world gets a unified view of capability.
+This isn't just documentation - it's a **contract** that Gas Town enforces.

-## The Technical Foundation
+### 2. Nondeterministic Idempotence

-### Beads as Ledger
+The key property that enables autonomous operation:

-| Concept | Beads Implementation |
-|---------|---------------------|
-| Transaction | Issue/task/work item |
-| Address | Entity identifier |
-| Smart Contract | Work specification + acceptance criteria |
-| Validation | Merge/review/approval |
-| Stake | Accumulated reputation chain |
-| Gas | Effort estimation |
+- **Deterministic structure**: Molecule defines exactly what steps exist
+- **Nondeterministic execution**: Any worker can execute any ready step
+- **Idempotent progress**: Completed steps stay completed

-### The OS Metaphor
+**Why this matters:**
+```
+Worker A picks up "design" step
+Worker A completes "design"
+Worker A crashes mid-"implement"
+Worker B restarts, queries ready work
+Worker B sees "implement" is ready (design done, implement pending)
+Worker B continues from exactly where A left off
+```

-Gas Town is an operating system for work:
+No work is lost. No state is in memory. Any worker can continue any molecule. This is what makes 24/7 autonomous operation possible.
+
+### 3. Beads: The Universal Data Plane
+
+Gas Town uses **Beads** as both control plane and data plane. Everything flows through Beads:
+
+| Data Type | Beads Representation |
+|-----------|---------------------|
+| Work items | Issues (tasks, bugs, features) |
+| Workflows | Molecules (type=molecule) |
+| Messages | Mail beads (type=message) |
+| Merge requests | Queue entries (type=merge-request) |
+| Agent state | Status on assigned issues |
+
+**Key architectural insight**: The control state IS data in Beads. Molecule steps, dependencies, and status ARE the control plane. Agents read Beads to know what to do next.
+
+This provides:
+- **Fault tolerance**: Control state survives agent crashes
+- **Observability**: `bd list` shows the full system state
+- **Decentralization**: Each agent reads its own state from Beads
+- **Recovery**: Restart = re-read Beads = continue from where you left off
+
+There is no separate orchestrator maintaining workflow state. Beads IS the orchestrator.
+
+### 4. The OS Metaphor
+
+Gas Town is an operating system for AI work:

 | OS Concept | Gas Town |
 |------------|----------|
@@ -108,117 +99,142 @@ Gas Town is an operating system for work:
 | Process templates | Molecules |
 | IPC | Mail beads |

-### Entity Chains
+Just as Unix made computer resources manageable through a consistent process model, Gas Town makes AI agent work manageable through a consistent work model.

-Every entity (human or agent) accumulates a work chain:
- Work they created
- Work they claimed
- Work they completed
- Work they validated
- Quality signals at each step
+### 5. Hierarchical Auditability

-Format: `entity://<platform>/<org>/<id>`
+All work is tracked in a permanent hierarchical ledger:

-Examples:
- `entity://gastown/steveyegge/polecat-nux`
- `entity://github/acme-corp/jane-doe`
+```
+Epic: Implement authentication
+├── Task: Design auth flow
+│   └── completed by polecat-nux, 2h
+├── Task: Implement OAuth provider
+│   └── completed by polecat-slit, 4h
+├── Task: Add session management
+│   └── completed by polecat-nux, 3h
+└── Task: Write integration tests
+    └── in_progress, polecat-capable
+```

-The chain IS the CV. Skills are derived from demonstrated work, not claimed.
+This enables:
+- **Audit trails**: Who did what, when, and how long it took
+- **Observability**: Real-time visibility into swarm progress
+- **Attribution**: Clear accountability for work quality
+- **Analytics**: Understand where time goes, identify bottlenecks

-### Skill Vectors
+### 6. Scalable Architecture

-Work items carry skill embeddings:
- What capabilities does this work demonstrate?
- What prior knowledge does it require?
- How complex is it?
+Gas Town scales through three mechanisms:

-Matching displaced workers to unmet demand becomes a vector similarity problem:
- Worker's demonstrated skills (from their chain)
- Job requirements (from work specification)
- Match = high similarity + acceptable reputation
+**Federation**: Multiple rigs across machines, coordinated through Beads sync
+```
+Town (global coordinator)
+├── Rig: project-alpha (16 polecats, local)
+├── Rig: project-beta (8 polecats, cloud VM)
+└── Rig: project-gamma (32 polecats, cluster)
+```

-## Public Framing
+**Tiering**: Hot work in active Beads, cold history archived
+- Active issues: instant queries
+- Recent history: fast retrieval
+- Archive: compressed cold storage

-These capabilities can be explained without revealing the full vision:
+**Temporal decay**: Ephemeral execution traces, permanent outcomes
+- Molecule step-by-step execution: memory only
+- Work outcomes: permanent record
+- Intermediate scaffolding: garbage collected

-| Capability | Public Explanation |
-|------------|-------------------|
-| Entity tracking | "Agent accountability and work attribution" |
-| Recursive structure | "Enterprise-scale hierarchical tracking" |
-| Skill vectors | "Capability-based task routing" |
-| Federation | "Multi-repo / org-wide visibility" |
-| Validation | "Review workflows and quality gates" |
-| Mail/threading | "Agent coordination for distributed teams" |
+## The Agent Hierarchy

-All true - just not the full story.
+### Overseer (Human)
+- Sets strategy and priorities
+- Reviews and approves output
+- Handles escalations
+- Operates the system

-## The Execution Model
+### Mayor (AI - Town-wide)
+- Dispatches work across rigs
+- Coordinates cross-project dependencies
+- Handles strategic decisions

-### Refineries as Validators
+### Witness (AI - Per-rig)
+- Manages polecat lifecycle
+- Detects stuck workers
+- Handles session cycling

-Refineries don't just merge code - they're validator nodes:
- Verify work meets acceptance criteria
- Record validation in the ledger
- Gate entry to the canonical chain (main branch)
+### Refinery (AI - Per-rig)
+- Processes merge queue
+- Reviews and integrates code
+- Maintains branch hygiene

-### Polecats as Workers
+### Polecat (AI - Workers)
+- Implements assigned work
+- Follows molecule workflows
+- Files discovered issues

-Polecats aren't just coding agents - they're work executors with chains:
- Each polecat has an identity
- Work history accumulates
- Success rate is tracked
- Demonstrated skills emerge
+## Quality Through Structure

-### Molecules as Contracts
+Gas Town enforces quality through molecules, not prompts:

-Molecules aren't just workflows - they're smart contracts for work:
- Specify exactly what must happen
- Encode acceptance criteria per step
- Enable deterministic verification
- Support nondeterministic execution
+**Without molecules:**
+- Agent is prompted with instructions
+- Works from memory
+- Loses state on restart
+- Quality depends on the prompt

-## Where This Goes
+**With molecules:**
+- Agent follows persistent workflow
+- State survives restarts
+- Quality gates are enforced
+- Any worker can continue

-### Phase 1: Gas Town v1 (Now)
- Coding agent orchestrator
- Beads-backed work tracking
- Molecule-based workflows
- Local federation ready
+The difference is like giving someone verbal instructions vs. giving them a checklist. Checklists win.

-### Phase 2: Federation
- Cross-machine outposts
- Multi-rig coordination
- Git-based sync everywhere
+## Why "IDE of 2026"?

-### Phase 3: Entity Chains
- Persistent agent identities
- Work history accumulation
- Skill derivation from work
+The IDE evolved from text editor → syntax highlighting → autocomplete → AI suggestions.

-### Phase 4: Platform of Platforms
- Adapters for external work sources
- Cross-platform skill matching
- The world chain emerges
+The next evolution isn't better suggestions - it's **AI as worker, not assistant**.
+
+| 2024 IDE | 2026 IDE (Gas Town) |
+|----------|---------------------|
+| AI suggests code | AI writes code |
+| Human reviews suggestions | Human reviews pull requests |
+| AI helps with tasks | AI completes tasks |
+| Single agent | Coordinated swarm |
+| Context in memory | Context in Beads |
+| Manual quality checks | Molecule-enforced gates |
+
+Gas Town is what happens when you treat AI agents as employees, not tools.

 ## Design Principles

-1. **Git as blockchain** - Don't build new consensus; use git
-2. **Federation not global consensus** - Each platform validates its own work
-3. **Skill embeddings as native** - Work items carry capability vectors
-4. **Human-readable** - Beads is Markdown; auditable, trustworthy
-5. **Incremental evolution** - Current architecture grows into the full vision
+1. **Work is data**: All work state lives in Beads, not agent memory
+2. **Molecules over prompts**: Structured workflows beat clever instructions
+3. **Crash-resistant by design**: Any agent can continue any work
+4. **Hierarchical coordination**: Mayor → Witness → Refinery → Polecat
+5. **Quality through structure**: Gates and checks built into molecules
+6. **Observable by default**: `bd list` shows the full picture

-## The Redemption Arc
+## Where This Goes

-The system doesn't judge - it tracks demonstrated capability and matches it to demand.
+### Now: Coding Agent Orchestrator
+- Multi-polecat swarms on software projects
+- Molecule-based quality workflows
+- Merge queue processing
+- Full audit trail

- Someone with a troubled past can rebuild their chain
- Skills proven through work matter more than credentials
- Every completion is a step toward redemption
- The ledger is honest but not cruel
+### Next: Knowledge Work Platform
+- Support for non-code work (documents, research, analysis)
+- Custom molecule libraries
+- Enterprise integrations

-This is capability matching at scale. The work speaks for itself.
+### Future: Enterprise Cognitive Infrastructure
+- Cross-team coordination
+- Organization-wide work visibility
+- Compliance and governance tooling

 ---

-*"Work is fractal. Money is crystallized labor. The world needs a ledger."*
+*"The best tool is invisible. It doesn't help you work - it works."*