beads/
├── cmd/bd/                  # CLI command layer (402+ files, 100+ subcommands)
│   ├── main.go              # Entry point (36,000+ lines)
│   ├── create.go            # Issue creation (--parent, --graph)
│   ├── ready.go             # Query ready work (auto-ready)
│   ├── dep.go               # Dependency management
│   ├── graph.go             # Graph loading/visualization
│   ├── graph_apply.go       # Atomic graph creation (since v1.0.0)
│   ├── batch.go             # Atomic batch processing (since v1.0.0)
│   ├── rules.go             # Rules audit/compact (since v1.0.0)
│   ├── ado.go               # Azure DevOps integration (since v1.0.0)
│   ├── context_cmd.go       # Backend context diagnostics (since v1.0.0)
│   ├── compact.go           # Semantic compaction
│   └── testdata/*.txt       # Script-based tests
│
├── internal/
│   ├── storage/
│   │   ├── storage.go       # Storage interface definition
│   │   ├── hook_decorator.go # Storage hook decorator (since v1.0.0)
│   │   ├── dolt/            # Dolt implementation
│   │   │   ├── schema.go    # DB schema (v11, was v9)
│   │   │   ├── store.go     # DoltStore struct
│   │   │   ├── issues.go    # Issue CRUD
│   │   │   ├── dependencies.go  # Dependency CRUD
│   │   │   └── queries.go   # Core queries: computeBlockedIDs, etc.
│   │   ├── schema/          # Unified schema package (SSOT, since v1.0.0)
│   │   ├── embeddeddolt/    # Embedded Dolt (VC, sync, Federation)
│   │   └── issueops/        # Shared issue operations (blocked, cycles, compaction, child_id)
│   │
│   ├── types/               # Core domain types (Issue, Dependency, Status, etc.)
│   │   ├── types.go         # Data struct definitions
│   │   └── id_generator.go  # Hash-based ID generation
│   │
│   ├── beads/               # Core domain logic (DB discovery, bootstrap)
│   ├── compact/             # Semantic compaction (compactor.go, haiku.go)
│   ├── config/              # Configuration system
│   ├── hooks/               # Git hooks integration
│   ├── molecules/           # Molecule workflows
│   ├── formula/             # Rules engine
│   ├── query/               # Query DSL
│   ├── git/                 # Git operations
│   ├── telemetry/           # OpenTelemetry instrumentation (full metrics added)
│   ├── {github,gitlab,linear,jira,ado,notion}/  # External service integrations
│   └── testutil/            # Test utilities
│
├── docs/                    # 55+ markdown documents
├── examples/                # 14 example projects
├── scripts/                 # 25+ utility scripts (bump-version.sh, release.sh, etc.)
├── website/                 # Documentation website
├── beads.go                 # Public API
├── beads_cgo.go             # CGO build: embedded + server mode (since v1.0.0)
├── beads_nocgo.go           # Non-CGO build: server mode only (since v1.0.0)
├── AGENT_INSTRUCTIONS.md    # Agent operating instructions (since v1.0.0)
├── Makefile                 # Build system
├── .goreleaser.yml          # Release configuration
└── .github/workflows/       # CI/CD (9+ workflows)

┌─────────────────────────────────────────────────────────┐
│                     CLI Layer (cmd/bd/)                   │
│  Cobra commands → --json support → direct DB access       │
└────────────────────────┬────────────────────────────────┘
                         │
                         v
┌─────────────────────────────────────────────────────────┐
│              Hook Decorator Layer (since v1.0.0)          │
│  HookFiringStore: fires hooks automatically on mutations  │
│  Propagates on_create, on_update, on_close events         │
└────────────────────────┬────────────────────────────────┘
                         │
                         v
┌─────────────────────────────────────────────────────────┐
│                   Dolt Database Layer                     │
│  Version-controlled SQL │ Cell-level merge │ Auto-commit  │
│  .beads/embeddeddolt/ (embedded, default)                 │
│  or dolt sql-server (server mode)                         │
└────────────────────────┬────────────────────────────────┘
                         │
                    Dolt push/pull
                   (or Federation)
                         │
                         v
┌─────────────────────────────────────────────────────────┐
│              Remote (DoltHub, S3, GCS, Git)               │
│  Cell-level merge resolves conflicts automatically        │
└─────────────────────────────────────────────────────────┘

bd create "New feature"
  → CLI parsing (Cobra)
  → HookFiringStore.CreateIssue() [hook_decorator.go — fires hooks]
  → DoltStore.CreateIssue() [internal/storage/dolt/issues.go]
  → issueops.CreateIssueInTx() [SQL INSERT]
  → Check if Wisp
    ├─ ephemeral/no_history → wisps table (skip DOLT_COMMIT)
    └─ regular issue →
         CALL DOLT_ADD('issues', 'events')
         CALL DOLT_COMMIT('-m', 'bd: create bd-xyz', '--author', ...)
         Cache invalidation
         Fire on_create hook (after transaction commit)

bd ready → SQL SELECT from ready_issues view → direct query against local Dolt DB

// Core interface (internal/storage/storage.go)
type Storage interface {
    CreateIssue(ctx, issue, actor)
    GetIssue(ctx, id)
    UpdateIssue(ctx, id, updates, actor)
    GetReadyWork(ctx, filter)
    GetBlockedIssues(ctx, filter)
    AddDependency(ctx, dep, actor)
    RunInTransaction(ctx, commitMsg, fn)
    // Added in v1.0.0
    SlotSet(ctx, issueID, key, value)     // per-issue metadata
    SlotGet(ctx, issueID, key)
    SlotClear(ctx, issueID, key)
    ListWisps(ctx, filter)                // list ephemeral wisps
    ReopenIssue(ctx, id, actor)           // reopen an issue
    UpdateIssueType(ctx, id, newType)     // change issue type
    // ...
}

type DoltStorage interface {
    Storage
    VersionControl    // Branch, checkout, commit history
    HistoryViewer     // AS OF, dolt_history_* tables
    RemoteStore       // Push, pull, remote management
    SyncStore         // High-level peer sync
    FederationStore   // Multi-repo support
    CompactionStore   // History compaction
    // ...
}

// New in v1.0.0: Hook Decorator
type HookFiringStore struct {
    inner DoltStorage
}
// CreateIssue → inner.CreateIssue + fire on_create hook
// UpdateIssue → inner.UpdateIssue + fire on_update hook
// Within a transaction: hooks fire only after commit, not on rollback

// beads.go — public API for external integrations
func OpenBestAvailable() (Storage, Unlocker, error)  // supports resource cleanup
func PrettyIssue(issue *Issue) string                 // exposes format package
func CompactIssue(issue *Issue) string
func LongIssue(issue *Issue) string

-- 5 core tables
issues           -- Issues/tasks (30+ columns)
dependencies     -- Relationship edges (19+ types)
labels           -- Tagging system
comments         -- Threaded discussion
events           -- Complete audit trail

-- Supporting tables
config                 -- Global key-value settings
metadata               -- Framework-level state (schema version, etc.)
child_counters         -- Hierarchical ID generation (parent.N)
issue_snapshots        -- Compaction snapshots
compaction_snapshots   -- Compaction state management
repo_mtimes            -- Multi-repo change detection
routes                 -- Prefix-to-path routing
issue_counter          -- Sequential ID mode (GH#2002)
interactions           -- Agent audit log
federation_peers       -- P2P sync credentials

-- New in v1.0.0 (schema v10–v11)
custom_statuses        -- Normalized custom statuses (name, category)
custom_types           -- Normalized custom types (name)

CREATE TABLE issues (
    -- Core identification
    id VARCHAR(255) PRIMARY KEY,          -- Hash-based ID (bd-a1b2)
    content_hash VARCHAR(64),             -- SHA256 for deduplication

    -- Issue content
    title VARCHAR(500) NOT NULL,
    description TEXT NOT NULL,
    design TEXT NOT NULL,
    acceptance_criteria TEXT NOT NULL,
    notes TEXT NOT NULL,

    -- Workflow
    status VARCHAR(32) DEFAULT 'open',    -- open, in_progress, blocked, deferred, closed, pinned, hooked
    priority INT DEFAULT 2,               -- 0=critical ~ 4=backlog
    issue_type VARCHAR(32) DEFAULT 'task', -- bug, feature, task, epic, chore, message,
                                          --   molecule, gate, spike, story, milestone (since v1.0.0)

    -- Assignment
    assignee VARCHAR(255),
    owner VARCHAR(255),
    estimated_minutes INT,

    -- Timestamps
    created_at DATETIME, updated_at DATETIME, closed_at DATETIME,

    -- Compaction metadata
    compaction_level INT DEFAULT 0,       -- 0: none, 1: Tier 1, 2: Tier 2
    compacted_at DATETIME,
    original_size INT,

    -- Messaging
    sender VARCHAR(255),
    ephemeral TINYINT(1) DEFAULT 0,       -- if true, not synced
    no_history TINYINT(1) DEFAULT 0,      -- stored in wisps table, not GC'd

    -- Gate (async coordination)
    await_type VARCHAR(32),               -- gh:run, gh:pr, timer, human, mail
    await_id VARCHAR(255),
    timeout_ns BIGINT,

    -- Scheduling
    due_at DATETIME,
    defer_until DATETIME,

    -- Extension
    metadata JSON DEFAULT (JSON_OBJECT()),
    -- + indexes: status, priority, issue_type, assignee, created_at, spec_id, external_ref
);

CREATE TABLE dependencies (
    issue_id VARCHAR(255) NOT NULL,       -- the dependent issue
    depends_on_id VARCHAR(255) NOT NULL,  -- the blocking issue (no FK — allows external refs)
    type VARCHAR(32) DEFAULT 'blocks',    -- 19+ relationship types
    created_at DATETIME,
    created_by VARCHAR(255),
    metadata JSON DEFAULT (JSON_OBJECT()), -- WaitsForMeta, AttestsMeta, etc.
    thread_id VARCHAR(255),               -- conversation thread grouping
    PRIMARY KEY (issue_id, depends_on_id)
);

ID format: prefix-{hash}
Examples:  bd-a1b2, bd-a1b2cd, bd-af78.1 (child)

bd-af78e9      → root (epic)
bd-af78e9.1    → child (task)
bd-af78e9.1.2  → grandchild (subtask)
Max depth: 3 levels, unlimited breadth (tested with 347+ children)

// Atomically allocates the next number from the child_counters table
func GetNextChildIDTx(ctx, tx, parentID) (string, error) {
    // 1. Look up last_child from child_counters
    // 2. Scan issues table to find existing children (handles JSONL imports)
    // 3. Determine new number as max(counter, existing) + 1
    // 4. UPSERT to update the counter
    return fmt.Sprintf("%s.%d", parentID, nextChild), nil
}

func (i *Issue) ComputeContentHash() string {
    // SHA256(title + description + design + acceptance_criteria + notes +
    //        spec_id + status + priority + issue_type + assignee + ...)
    // Excluded: ID, timestamps, compaction metadata
}

open ──→ in_progress ──→ closed
  ↓                         ↑
  └─────── reopen ──────────┘

Special statuses:
  blocked   : blocked (waiting for a blocker to be resolved)
  deferred  : intentionally paused
  pinned    : permanent context marker (not a work item)
  hooked    : actively claimed by a worker
  tombstone : soft delete

Custom statuses: managed via the custom_statuses table (categories: active, wip, done, frozen)

Default types:   bug, feature, task, epic, chore, message, molecule, gate
Added in v1.0.0: spike     — time-boxed investigation to resolve uncertainty
                 story     — user-facing feature description
                 milestone — marks completion of related issues (no work of its own)
Custom types:    managed via the custom_types table; any non-empty string up to 50 chars

1. Query active issues (excluding closed, pinned)
2. Query blocking dependencies (blocks, conditional-blocks)
3. Filter to only those where both sides are active
4. Process waits-for:
   - all-children: blocked if any child is still active
   - any-children: blocked until the first child closes
5. Store result in blockedIDsCacheMap (O(1) lookup)

{
  "commit_message": "Bootstrap auth epic",
  "nodes": [
    { "key": "epic", "title": "Auth System", "type": "epic", "priority": 1 },
    { "key": "design", "title": "Design API", "type": "task", "parent_key": "epic" },
    { "key": "impl", "title": "Implement API", "type": "task", "parent_key": "epic" },
    { "key": "tests", "title": "Write tests", "type": "task", "parent_key": "epic" }
  ],
  "edges": [
    { "from_key": "impl", "to_key": "design", "type": "blocks" },
    { "from_key": "tests", "to_key": "impl", "type": "blocks" }
  ]
}

Input:  Title, Description, Design, Acceptance Criteria, Notes
Output:
  **Summary:** 2-3 sentences (what was done and why)
  **Key Decisions:** key technical decisions
  **Resolution:** one-sentence final outcome

// Tier 1 eligible:
status == CLOSED
&& closed_at <= (now - 30 days)
&& compaction_level == 0

// Tier 2 eligible:
status == CLOSED
&& compaction_level == 1
&& closed_at <= (now - 90 days)

-- Metadata columns in the issues table:
compaction_level INT   -- 0 (none), 1 (Tier 1), 2 (Tier 2)
compacted_at DATETIME  -- time of compaction
compacted_at_commit VARCHAR(64)  -- Dolt commit hash at compaction
original_size INT      -- original size in bytes

-- Separate snapshot table:
compaction_snapshots (issue_id, compaction_level, snapshot_json, created_at)

bd compact --dolt --dry-run        # preview
bd compact --dolt --days 7 --force # squash history older than 7 days

bd dolt push    # push to origin remote
bd dolt pull    # pull from origin + auto cell-level merge
bd dolt commit -m "msg"  # commit changes

# Add a peer
bd federation add-peer team-beta dolthub://acme/team-beta-beads
bd federation add-peer partner https://partner.example.com/beads --sovereignty T3

# Sync
bd federation sync --peer team-beta --strategy ours
bd federation status

// Automatic URL conversion
gitURLToDoltRemote("https://github.com/org/repo.git")
  → "git+https://github.com/org/repo.git"

gitURLToDoltRemote("git@github.com:org/repo.git")
  → "git+ssh://git@github.com/org/repo.git"

bd backup init /path/to/backup   # configure backup target
bd backup sync                    # sync
bd backup restore --force /path   # restore

bd mol wisp (generate from template)
  → Wisp Issues (local-only work)
  → bd mol squash (compress into a permanent digest)

1. Built-in molecules (embedded in binary)
2. Town-level: $GT_ROOT/.beads/molecules.jsonl (orchestrator)
3. User-level: ~/.beads/molecules.jsonl
4. Project-level: .beads/molecules.jsonl

# Execute multiple operations from stdin
echo "close bd-a1b2 done
update bd-c3d4 status=in_progress
create task 1 New authentication module
dep add bd-e5f6 bd-c3d4 blocks" | bd batch

# Execute from a file
bd batch -f operations.txt

# Dry run
bd batch --dry-run -f operations.txt

bd rules audit              # check .claude/rules/*.md for contradictions
bd rules compact            # suggest merging duplicate rules

// Decorated methods:
CreateIssue  → fires on_create hook
UpdateIssue  → fires on_update hook
ReopenIssue  → fires on_update hook
CloseIssue   → fires on_close hook
// ...all mutation methods

// Transaction-safe: fires only after commit, not on rollback
// UnwrapStore(): for optional interface type assertions

bd slot set bd-a1b2 delegation_state "waiting_review"
bd slot get bd-a1b2 delegation_state
bd slot clear bd-a1b2 delegation_state

bd config set-many ado.state_map.open=New ado.state_map.closed=Closed gitlab.project=myproject

bd context --json
# {
#   "beads_dir": ".beads",
#   "backend": "embedded",
#   "dolt_mode": "embedded",
#   "bd_version": "1.0.0",
#   "project_id": "my-project",
#   ...
# }

bd ado sync          # sync ADO ↔ Beads
bd ado status        # check sync status
bd ado projects      # list ADO projects

# ===== Step 1: Create the epic =====
bd create "User Authentication System" -t epic -p 1 \
  -d "OAuth 2.0 + MFA support" --json
# → {"id": "bd-a3f8e9", "title": "User Authentication System", ...}

# ===== Step 2: Create child tasks =====
bd create "Design OAuth flow" --parent bd-a3f8e9 -p 1 --json
# → {"id": "bd-a3f8e9.1"}  ← automatic hierarchical ID

bd create "Implement OAuth provider" --parent bd-a3f8e9 -p 1 --json
# → {"id": "bd-a3f8e9.2"}

bd create "Add MFA support" --parent bd-a3f8e9 -p 2 --json
# → {"id": "bd-a3f8e9.3"}

bd create "Write integration tests" --parent bd-a3f8e9 -p 1 --json
# → {"id": "bd-a3f8e9.4"}

bd create "Write security documentation" --parent bd-a3f8e9 -p 2 --json
# → {"id": "bd-a3f8e9.5"}

# ===== Step 3: Add execution-order dependencies =====
bd dep add bd-a3f8e9.2 bd-a3f8e9.1 --type blocks   # implementation after design
bd dep add bd-a3f8e9.3 bd-a3f8e9.2 --type blocks   # MFA after OAuth implementation
bd dep add bd-a3f8e9.4 bd-a3f8e9.2 --type blocks   # tests after implementation
bd dep add bd-a3f8e9.5 bd-a3f8e9.4 --type blocks   # docs after tests

cat > auth-epic.json <<'EOF'
{
  "commit_message": "Bootstrap User Authentication System epic",
  "nodes": [
    {
      "key": "epic",
      "title": "User Authentication System",
      "type": "epic",
      "priority": 1,
      "description": "OAuth 2.0 + MFA support"
    },
    {
      "key": "design",
      "title": "Design OAuth flow",
      "type": "task",
      "priority": 1,
      "parent_key": "epic"
    },
    {
      "key": "oauth-impl",
      "title": "Implement OAuth provider",
      "type": "task",
      "priority": 1,
      "parent_key": "epic"
    },
    {
      "key": "mfa",
      "title": "Add MFA support",
      "type": "task",
      "priority": 2,
      "parent_key": "epic"
    },
    {
      "key": "tests",
      "title": "Write integration tests",
      "type": "task",
      "priority": 1,
      "parent_key": "epic"
    },
    {
      "key": "docs",
      "title": "Write security documentation",
      "type": "task",
      "priority": 2,
      "parent_key": "epic"
    }
  ],
  "edges": [
    {"from_key": "oauth-impl", "to_key": "design", "type": "blocks"},
    {"from_key": "mfa", "to_key": "oauth-impl", "type": "blocks"},
    {"from_key": "tests", "to_key": "oauth-impl", "type": "blocks"},
    {"from_key": "docs", "to_key": "tests", "type": "blocks"}
  ]
}
EOF

bd create --graph auth-epic.json --json
# → {
#     "ids": {
#       "epic": "bd-a3f8e9",
#       "design": "bd-a3f8e9.1",
#       "oauth-impl": "bd-a3f8e9.2",
#       "mfa": "bd-a3f8e9.3",
#       "tests": "bd-a3f8e9.4",
#       "docs": "bd-a3f8e9.5"
#     }
#   }

cat > epic-ops.txt <<'EOF'
create task 1 Design OAuth flow
create task 1 Implement OAuth provider
create task 2 Add MFA support
create task 1 Write integration tests
create task 2 Write security documentation
EOF

bd batch -f epic-ops.txt --message "Bulk-create epic child tasks"

# ===== Agent queries ready work =====
bd ready --parent bd-a3f8e9 --json
# Result: [{"id": "bd-a3f8e9.1", "title": "Design OAuth flow"}]
# → Only "design" is ready — it has no blocking dependencies

# ===== Design complete → unblock implementation =====
bd update bd-a3f8e9.1 --status in_progress
# ... do work ...
bd close bd-a3f8e9.1 --reason "OAuth design document approved"

bd ready --parent bd-a3f8e9 --json
# Result: [{"id": "bd-a3f8e9.2", "title": "Implement OAuth provider"}]
# → Closing "design" unblocked "implementation"

# ===== Implementation complete → MFA + tests both unblocked =====
bd update bd-a3f8e9.2 --status in_progress
# ... do work ...
bd close bd-a3f8e9.2 --reason "OAuth provider integrated"

bd ready --parent bd-a3f8e9 --json
# Result: [
#   {"id": "bd-a3f8e9.3", "title": "Add MFA support"},
#   {"id": "bd-a3f8e9.4", "title": "Write integration tests"}
# ]
# → Closing "implementation" unblocked both "MFA" and "tests" simultaneously (parallel work possible!)

# ===== Parallel work → sequential completion =====
bd close bd-a3f8e9.3 --reason "MFA implementation complete"
bd close bd-a3f8e9.4 --reason "All tests passing"

bd ready --parent bd-a3f8e9 --json
# Result: [{"id": "bd-a3f8e9.5", "title": "Write security documentation"}]

bd close bd-a3f8e9.5 --reason "API docs and security guide written"

# Check in-progress status
bd show bd-a3f8e9
# ┌──────────────────────────────────────┐
# │  bd-a3f8e9: User Authentication System │
# │  Type: epic  Status: open  P1          │
# │  Children: 5 total (2 closed, 3 open)  │
# │  Progress: ██████░░░░░░░ 40%           │
# └──────────────────────────────────────┘

# Graph visualization
bd graph bd-a3f8e9
# Layer 0:  [○ bd-a3f8e9.1 Design]
#              │
# Layer 1:  [◐ bd-a3f8e9.2 Implementation]
#            ┌──┤
# Layer 2:  [○ bd-a3f8e9.3 MFA]  [○ bd-a3f8e9.4 Tests]
#                                    │
# Layer 3:                        [○ bd-a3f8e9.5 Docs]

# Closing the last child → epic auto-closes
bd close bd-a3f8e9.5 --reason "done"
bd show bd-a3f8e9
# Status: closed ← automatically transitioned when all children complete

                    bd-a3f8e9 (epic: User Authentication System)
                    ├── .1 Design OAuth flow
                    │     ↓ blocks
                    ├── .2 Implement OAuth provider
                    │     ├── ↓ blocks
                    │     └── ↓ blocks
                    ├── .3 Add MFA support ←──────┘
                    ├── .4 Write integration tests ←────┘
                    │     ↓ blocks
                    └── .5 Write security documentation

Execution order:  .1 → .2 → (.3 + .4 in parallel) → .5

# MapReduce pattern: reduce waits until all map partitions finish
bd create "Data Pipeline" -t epic -p 1
# → bd-b2c3

bd create "Map Partition 1" --parent bd-b2c3
bd create "Map Partition 2" --parent bd-b2c3
# ... more can be added at runtime

bd create "Reduce & Aggregate" -t task -p 1
bd dep add reduce-id bd-b2c3 --type waits-for
# → "Reduce" is blocked until all children of bd-b2c3 are closed
# → New partitions added during the run are automatically detected