From a834bc79d4133b471236cf205834e60ab514d340 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Tue, 30 Dec 2025 18:00:05 -0800 Subject: [PATCH] Document BD_ACTOR format convention (gt-6r18e.9) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add docs/identity.md with canonical BD_ACTOR format: - Town level: mayor, deacon - Rig level: {rig}/witness, {rig}/refinery - Workers: {rig}/crew/{name}, {rig}/polecats/{name} Also documents the attribution model: - GIT_AUTHOR_NAME = BD_ACTOR (agent identity) - GIT_AUTHOR_EMAIL = overseer email (work owner) - created_by = BD_ACTOR (beads field) Updates reference.md with expanded environment variables section and adds cross-reference from federation.md. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/federation.md | 3 +- docs/identity.md | 142 +++++++++++++++++++++++++++++++++++++++++++++ docs/reference.md | 6 ++ 3 files changed, 150 insertions(+), 1 deletion(-) create mode 100644 docs/identity.md diff --git a/docs/federation.md b/docs/federation.md index 8e677703..c9977e32 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -87,7 +87,8 @@ Distribute work across workspaces: ## Agent Provenance -Every agent operation is attributed: +Every agent operation is attributed. See [identity.md](identity.md) for the +complete BD_ACTOR format convention. ### Git Commits diff --git a/docs/identity.md b/docs/identity.md new file mode 100644 index 00000000..e8ea7eaa --- /dev/null +++ b/docs/identity.md @@ -0,0 +1,142 @@ +# Agent Identity and Attribution + +> Canonical format for agent identity in Gas Town + +## BD_ACTOR Format Convention + +The `BD_ACTOR` environment variable identifies agents in slash-separated path format. +This is set automatically when agents are spawned and used for all attribution. + +### Format by Role Type + +| Role Type | Format | Example | +|-----------|--------|---------| +| **Mayor** | `mayor` | `mayor` | +| **Deacon** | `deacon` | `deacon` | +| **Witness** | `{rig}/witness` | `gastown/witness` | +| **Refinery** | `{rig}/refinery` | `gastown/refinery` | +| **Crew** | `{rig}/crew/{name}` | `gastown/crew/joe` | +| **Polecat** | `{rig}/polecats/{name}` | `gastown/polecats/toast` | + +### Why Slashes? + +The slash format mirrors filesystem paths and enables: +- Hierarchical parsing (extract rig, role, name) +- Consistent mail addressing (`gt mail send gastown/witness`) +- Path-like routing in beads operations +- Visual clarity about agent location + +## Attribution Model + +Gas Town uses three fields for complete provenance: + +### Git Commits + +```bash +GIT_AUTHOR_NAME="gastown/crew/joe" # Who did the work (agent) +GIT_AUTHOR_EMAIL="steve@example.com" # Who owns the work (overseer) +``` + +Result in git log: +``` +abc123 Fix bug (gastown/crew/joe ) +``` + +**Interpretation**: +- The agent `gastown/crew/joe` authored the change +- The work belongs to the workspace owner (`steve@example.com`) +- Both are preserved in git history forever + +### Beads Records + +```json +{ + "id": "gt-xyz", + "created_by": "gastown/crew/joe", + "updated_by": "gastown/witness" +} +``` + +The `created_by` field is populated from `BD_ACTOR` when creating beads. +The `updated_by` field tracks who last modified the record. + +### Event Logging + +All events include actor attribution: + +```json +{ + "ts": "2025-01-15T10:30:00Z", + "type": "sling", + "actor": "gastown/crew/joe", + "payload": { "bead": "gt-xyz", "target": "gastown/polecats/toast" } +} +``` + +## Environment Setup + +The daemon sets these automatically when spawning agents: + +```bash +# Set by daemon for polecat 'toast' in rig 'gastown' +export BD_ACTOR="gastown/polecats/toast" +export GIT_AUTHOR_NAME="gastown/polecats/toast" +export GT_ROLE="polecat" +export GT_RIG="gastown" +export GT_POLECAT="toast" +``` + +### Manual Override + +For local testing or debugging: + +```bash +export BD_ACTOR="gastown/crew/debug" +bd create --title="Test issue" # Will show created_by: gastown/crew/debug +``` + +## Identity Parsing + +The format supports programmatic parsing: + +```go +// identityToBDActor converts daemon identity to BD_ACTOR format +// Town level: mayor, deacon +// Rig level: {rig}/witness, {rig}/refinery +// Workers: {rig}/crew/{name}, {rig}/polecats/{name} +``` + +| Input | Parsed Components | +|-------|-------------------| +| `mayor` | role=mayor | +| `deacon` | role=deacon | +| `gastown/witness` | rig=gastown, role=witness | +| `gastown/refinery` | rig=gastown, role=refinery | +| `gastown/crew/joe` | rig=gastown, role=crew, name=joe | +| `gastown/polecats/toast` | rig=gastown, role=polecat, name=toast | + +## Audit Queries + +Attribution enables powerful audit queries: + +```bash +# All work by an agent +bd audit --actor=gastown/crew/joe + +# All work in a rig +bd audit --actor=gastown/* + +# All polecat work +bd audit --actor=*/polecats/* + +# Git history by agent +git log --author="gastown/crew/joe" +``` + +## Design Principles + +1. **Agents are not anonymous** - Every action is attributed +2. **Work is owned, not authored** - Agent creates, overseer owns +3. **Attribution is permanent** - Git commits preserve history +4. **Format is parseable** - Enables programmatic analysis +5. **Consistent across systems** - Same format in git, beads, events diff --git a/docs/reference.md b/docs/reference.md index 33ce6e55..c567a35e 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -187,9 +187,15 @@ gt mol step done # Complete a molecule step | Variable | Purpose | |----------|---------| +| `BD_ACTOR` | Agent identity for attribution (see [identity.md](identity.md)) | | `BEADS_DIR` | Point to shared beads database | | `BEADS_NO_DAEMON` | Required for worktree polecats | +| `GIT_AUTHOR_NAME` | Set to BD_ACTOR for commit attribution | +| `GIT_AUTHOR_EMAIL` | Workspace owner email | | `GT_TOWN_ROOT` | Override town root detection | +| `GT_ROLE` | Agent role type (mayor, polecat, etc.) | +| `GT_RIG` | Rig name for rig-level agents | +| `GT_POLECAT` | Polecat name (for polecats only) | ## CLI Reference