gastownhall/beads

Beads is a local-first, Git-integrated issue tracking system that manages tasks, dependencies, and workflows using a Dolt SQL database. It provides a CLI and Go library for issue management, featuring bidirectional synchronization with external trackers like GitHub, GitLab, Jira, Linear, and Azure DevOps. The system is designed for AI agent integration, offering Model Context Protocol (MCP) support, structured agent skills, and automated context engineering to facilitate autonomous task management.

43 changes.

The project focused on enabling autonomous AI agent workflows through new MCP server integrations, dedicated agent examples, and automated setup routines for tools like Cursor and Aider. Simultaneously, it enforced strict architectural boundaries, standardized the Dolt storage backend, and introduced AI-powered issue compaction to manage data growth.

54 changes.

This period focused on expanding the project's integration capabilities by adding native support for GitLab, Jira, Azure DevOps, and Notion, alongside a structured recipe system for AI tool configuration. Concurrently, the team hardened the underlying storage and synchronization infrastructure, introducing robust rate-limit handling, atomic file writes, and a durable event journal to ensure data integrity and reliability across diverse backends.

The \examples/bd-example-extension-go\ directory now contains a complete Go-based example that shows how to extend a SQLite-backed \bd\ database with custom application-specific tables. The example introduces \example\_executions\ and \example\_checkpoints\ tables, linked to the core \issues\ table via foreign keys, and demonstrates dual-layer access by using the \beads\ Go API for issue management while directly querying the extension tables for execution tracking, checkpointing, and complex joined insights.

examples/bd-example-extension-go · high confidence

The internal ID generation module now supports creating hash-based IDs using base36 encoding (0-9, a-z) for improved information density. This new capability, implemented in internal/idgen/hash.go, allows generating stable, short identifiers by hashing input content (title, description, creator, timestamp, and nonce) and encoding the result. The system supports variable output lengths from 3 to 8 characters, with appropriate byte truncation to match the desired length. A test suite verifies the implementation against specific Jira import vectors to ensure compatibility.

internal/idgen · high confidence

Users can now define read-only issue templates in a separate molecules.jsonl catalog file, distinct from regular work items. These templates are loaded hierarchically from built-in, town-level, user-level, and project-level locations, with later sources overriding earlier ones. Templates are marked as read-only, excluded from the default list view, and can be viewed via the new molecule list command.

internal/molecules · high confidence

Added a new script at \scripts/repro-dolt-hang\ to reproduce and analyze a server hang issue caused by redundant \tx.Commit()\ calls after \DOLT\_COMMIT\ under concurrent load. The script compares transaction patterns (with and without the redundant commit) and includes an incident report documenting the environment, symptoms, and investigation findings.

scripts/repro-dolt-hang · high confidence

The examples/compaction directory now includes three shell scripts to help users automate or guide the database compaction process: workflow.sh for interactive, step-by-step manual compaction; cron-compact.sh for fully automated monthly runs via cron jobs; and auto-compact.sh for conditional compaction that only triggers when a configurable number of eligible issues exist. These scripts handle API key validation, candidate previewing, execution, and statistics reporting, providing ready-to-use templates for integrating compaction into manual workflows, CI/CD pipelines, or scheduled tasks.

examples/compaction · high confidence

A new shell script (bd-version-check.sh) and documentation have been added to the examples/startup-hooks directory to help AI coding agents detect and adapt to bd (beads) version upgrades. When sourced at the start of a session, the script compares the current bd version against the last-seen version stored in .beads/metadata.json; if an upgrade is detected, it automatically displays the 'what's new' changelog and updates any outdated git hooks. This allows agents to adjust their workflows immediately after an upgrade without manual intervention, supporting integration with environments like Claude Code, GitHub Copilot, and Cursor via shell initialization files.

examples/startup-hooks · high confidence

The Beads plugin package introduces native integration with Claude Code, Codex, and GitHub Copilot. It includes dedicated manifest files for each environment: \.claude-plugin/plugin.json\ and \.copilot-plugin/plugin.json\ register the \bd prime\ command to run on session start and pre-compaction, while \.codex-plugin/plugin.json\ and its associated hooks file define a broader set of lifecycle events (SessionStart, PreCompact, PostCompact, UserPromptSubmit) to manage context refresh and injection. The package also ships a comprehensive skill definition (\SKILL.md\) and a suite of command-specific documentation files to guide AI agents through issue tracking, dependency management, and workflow patterns.

plugins/beads · high confidence

The internal telemetry layer now wraps every storage role—including issue lifecycle, reading, claiming, batch operations, dependency editing, and memory access—with OpenTelemetry spans and metrics. This ensures that all guarded storage calls are consistently timed and traced, providing operators with accurate latency distributions and error visibility across the entire storage surface.

internal/telemetry · high confidence

Users can now explicitly set their user role (maintainer or contributor) via the \beads.role\ git configuration, which takes precedence over previous heuristics. The system also correctly detects roles in nested worktrees and secondary workspaces (such as jj secondary workspaces) by resolving the primary workspace's git context, and defaults to maintainer for local projects without a remote. This change replaces the deprecated URL-based heuristic with a more reliable configuration-driven approach.

internal/routing · high confidence

The formula system now supports advanced step transformations: loops (fixed-count, range, and conditional with runtime re-execution), branching (fork-join parallel execution), gates (conditional waits based on step status, output, aggregates, or external checks like file existence and environment variables), and advice operators (Lisp-style insertions of before/after/around steps with glob pattern matching). Additionally, expansion operators allow macro-style step replacement via expand and map rules with template variable substitution, protected by a default 5-level recursion depth limit. The parser also accepts TOML formula files alongside the existing JSON format, and includes a schema generation tool for type definitions.

internal/formula · high confidence

The \internal/httpapi/apigen\ package now contains Go types generated from the \openapi.v0.yaml\ specification using \oapi-codegen\. This introduces a types-only code generation layer that defines the data structures and enums for the v0 API surface (such as issue operations, dependency trees, and list sorting options), ensuring that the API contract is enforced at compile time while keeping the HTTP handlers hand-written and framework-free.

internal/httpapi/apigen · high confidence

This change introduces the internal GitLab tracker implementation, enabling full bidirectional synchronization of issues between Beads and GitLab. The new \internal/gitlab\ package provides a REST API client with automatic retry logic (including jitter and server Retry-After header support) and pagination for fetching issues. It includes a field mapper to translate GitLab labels and states into Beads' internal types for priority, status, and issue type, and supports optional group-level issue syncing via a configurable group ID. A key behavioral addition is the \LinkResolver\, which synchronizes issue dependency links (blocks, is\_blocked\_by, relates\_to) between the two systems, handling direction inversion and deduplication, while gracefully skipping blocking links if the GitLab instance lacks the required Premium/Ultimate license.

internal/gitlab · high confidence

Hook execution is now instrumented with OpenTelemetry, creating spans that track execution time, errors, and truncated stdout/stderr output for observability. The hook runner has been split into platform-specific implementations: Unix systems now use process groups to ensure descendant processes are killed on timeout, Windows uses best-effort process killing, and js/wasm explicitly rejects execution while still emitting an error span to keep refusals observable.

internal/hooks · high confidence

The beads-mcp integration is introduced as a new Model Context Protocol server for the Beads issue tracker, enabling AI agents to manage tasks via the bd CLI. This release includes context engineering optimizations—such as lazy tool schema loading, minimal issue models, and result compaction—that reduce context window usage by approximately 80%. It also adds new MCP tools for comments and notes, fixes a Pydantic validation crash for non-standard dependency types, and implements per-request workspace routing to support multi-repository setups.

integrations/beads-mcp · high confidence

The internal/compact package now provides a new Tier 1 compaction feature that uses the Claude Haiku model to summarize closed issues. The system checks issue eligibility, archives the original content via a snapshot before overwriting, and updates the issue description with a concise summary while clearing design, notes, and acceptance criteria fields. It supports concurrent batch processing, dry-run mode, and records compaction metadata including the current git commit hash. The AI client resolves API keys from environment variables (ANTHROPIC\_API\_KEY, MINIMAX\_API\_KEY) or config, supports retry logic with backoff, and emits OpenTelemetry metrics for token usage and request duration.

internal/compact · high confidence

This change adds the internal/ado package, providing the core infrastructure for syncing with Azure DevOps. It includes an HTTP client with retry logic and jitter, a field mapper for converting ADO work items to and from beads issues (including severity mapping for bugs and custom state/type overrides), and a link resolver that correctly maps ADO hierarchy and dependency relations to beads dependency types. A new bootstrap matcher handles initial sync deduplication by matching against external references, source system IDs, or opt-in heuristic matching (title, type, and creation time). Additionally, a reconciler is introduced to periodically scan for deleted or inaccessible work items.

internal/ado · high confidence

Added a new query language in the \internal/query\ package that allows users to filter issues using field comparisons (e.g., \status=open\), boolean operators (\AND\, \OR\, \NOT\), parentheses for grouping, and date-relative expressions (e.g., \updated\>7d\). The implementation includes a lexer, parser, and evaluator that convert query strings into efficient database filters or in-memory predicates, supporting fields like status, priority, labels, and timestamps.

internal/query · high confidence

The HTTP API now supports optional bearer token authentication using a file of accepted tokens. The \TokenFileAuth\ component reads tokens from a specified file, hashes them to SHA-256 digests to prevent credential leakage in memory, and reloads the file automatically (gated by a one-second interval) to allow for hitless token rotation and revocation without restarting the server. This mechanism is designed to be strict, refusing to start if the token file is unreadable, empty, or oversized, ensuring that the server never starts in an unauthenticated state or silently fails to enforce access control.

internal/httpapi · high confidence

The issueops package now exposes a set of distinct role interfaces—BatchApplier, BatchCloser, BatchCreator, BlockingAnnotator, Bootstrapper, Claimer, and Commenter—to replace monolithic accessors. This change structures issue operations into atomic, transactional boundaries (e.g., creating or closing multiple issues in a single durable act) and enforces a strict separation of concerns where each capability has its own interface and accessor. Users benefit from clearer transactional guarantees, such as all-or-nothing batch creation versus partial-success batch closing, and more precise control over identity bootstrapping and issue claiming.

issueops · high confidence

A new \journalops\ package provides a durable, sequence-ordered record of every committed mutation (bead changes, dependencies, comments) stored in the local \bd\_events\_journal\ table. This journal acts as a replay feed for external consumers and CLI tools like \bd events tail\ and \bd events export\, allowing them to rebuild their copy of the graph from a stored checkpoint. The implementation ensures data integrity by failing loudly with a \TruncatedError\ if a consumer's checkpoint falls below the retained window, preventing silent data loss during resumption. Each journal row now includes the \Actor\ identity of the mutating user, enabling accurate audit trails for deletes and cascading dependency removals. This package is marked experimental and is not yet covered by the project's compatibility promise.

journalops · high confidence

The new \memoryops\ package provides a dedicated interface for managing the workspace's persistent memory plane, supporting operations to remember, recall, forget, and list keyed notes (e.g., via \bd remember\, \bd recall\, \bd forget\, \bd memories\, and \bd prime\). This plane is distinct from settings, storing user data under the reserved \kv.memory\ namespace with its own merge resolution logic (auto-resolving conflicts with --theirs only if all keys carry the prefix) and a specific found/not-found contract where misses are result-carried rather than errors. The package is marked experimental and is not yet covered by the compatibility promise.

memoryops · high confidence

The new \internal/remotecache\ package provides a local caching layer for remote Dolt databases, automatically cloning or pulling remote repositories (supporting schemes like \s3://\, \az://\, \gs://\, \https://\, and \git+ssh://\) and storing them in the user's cache directory to speed up access. It includes strict security validation for remote URLs to prevent CLI flag injection and control character attacks, and ensures safe execution by scrubbing git tracing and disabling git hooks during remote transfers.

internal/remotecache · high confidence

The npm package now ships with pre-compiled native binaries for macOS, Linux, Windows, and Android/Termux, replacing the previous pure-JavaScript implementation. A new postinstall script automatically downloads the correct binary for the user's platform and architecture from GitHub releases, handling platform-specific details such as Windows file-locking race conditions and Unix executable permissions. The CLI entry point (bin/bd.js) now spawns this native binary, ensuring consistent performance and behavior across all supported operating systems.

npm-package/scripts · high confidence

The setup workflow now uses a structured recipe system to configure AI coding assistants, replacing ad-hoc logic with a unified model that supports file-based rules, JSON hook injection, and multi-file plugin manifests. Built-in recipes are provided for Cursor, Windsurf, Cody, Kilo Code, Kiro, Claude, Gemini, GitHub Copilot CLI, Factory.ai, Codex, Mux, OpenCode, Aider, and Junie. Users can now extend or override these configurations via a \.beads/recipes.toml\ file, allowing custom tool integrations without modifying the binary.

internal/recipes · high confidence

The Beads MCP integration now uses a dedicated set of Pydantic models to define the structure of issue data, dependencies, and operation results. This change establishes the data schema for the MCP layer, including lightweight models for list views to optimize context window usage, and ensures that status, type, and dependency values are handled as flexible strings to remain compatible with the CLI's source-of-truth validation.

python · high confidence

The Linear tracker now supports OAuth client-credentials authentication alongside the existing API key method, allowing for more secure and scalable token management. To prevent duplicate issues during sync interruptions, the system embeds deterministic idempotency markers in issue descriptions, enabling safe deduplication on retry. Performance for large syncs is improved by adopting Linear's issueBatchCreate and issueBatchUpdate GraphQL mutations. Additionally, the integration now handles parent-child relationships by reconciling them in a post-sync pass, supports multi-project filtering, and includes a rate-limit circuit breaker with jitter to handle API throttling gracefully.

internal/linear · high confidence

The Issue data model has been significantly expanded to support advanced workflows, including leasing (claim TTLs, heartbeats, and node-granting), concurrency guards (row-version tokens), and new issue types like molecules, gates, and templates. Additional fields now track creation attribution, close reasons, and external references. On the API surface, all non-2xx responses now conform to the RFC 9457 problem+json standard, providing machine-readable error codes and structured details for clients.

github.com/steveyegge/beads · high confidence

The migration subsystem now enforces a write-freeze mechanism: a new \internal/migration/freeze.go\ module detects a \MIGRATION-FREEZE\ marker file by walking the filesystem tree (or an explicit path via the \BD\_MIGRATION\_FREEZE\_FILE\ environment variable) and prevents write commands from proceeding when the marker is present. Additionally, a new \internal/migration/legacysqlite\ package provides an authenticated reader for legacy SQLite databases (versions 0.49.6 and 0.50.3), exporting their contents to JSONL while validating schema integrity and rejecting untrusted or mutated sources.

internal/migration · high confidence

The \bd setup\ command now includes dedicated installation routines for Aider, Cursor, and Codex. For Aider, it generates \.aider.conf.yml\ and instruction files to guide the AI through Beads issue-tracking workflows. For Cursor, it installs project-local rules (\.cursor/rules/beads.mdc\) with \alwaysApply\ and configures lifecycle hooks in \.cursor/hooks.json\ for session start and context recovery. For Codex, it installs a shared agent skill (\.agents/skills/beads\), project or global instructions, and native hooks. All integrations use managed markers to allow safe updates and removals.

cmd/bd/setup · high confidence

The CI pipeline now includes several new automation scripts in scripts/ci. A cyclomatic complexity advisor (complexity.sh) reports and can check Go function complexity against a baseline. Test execution is optimized with new sharding utilities (go-list-test-names, go-test-shard-names.sh, go-test-shard-packages.sh, gen\_proxied\_shard\_manifest.py) that distribute Go tests across shards based on package or estimated cost. Package validation gates for MCP (package-mcp.sh) and npm (package-npm.sh) have been added, along with a detector (detect-package-gates.sh) to trigger them only when relevant files change. The Go test environment is now more hermetic via lib/test-env.sh, and PR workflows use a 30-minute timeout for the -race lane (pr-core.sh) to prevent flaky timeouts. Dolt is pinned to version 2.2.0 (install-dolt.sh, pull-dolt-image.sh) to avoid regressions in DOLT\_RESET, and formatting checks are standardized (fmt-check.sh).

scripts/ci · high confidence

Users can now sync issues with GitHub repositories using a new tracker plugin that maps GitHub labels to internal priority, status, and type fields (including support for decision, spike, story, and milestone types). The integration includes a dedicated HTTP client that implements exponential backoff with jitter for transient errors and correctly classifies primary (header-driven) and secondary (body-driven) rate limits to avoid unnecessary retries. To prevent redundant API calls, the sync engine now uses content-based deduplication to skip updates when the local issue state already matches GitHub, and it supports both full GitHub issue URLs and a shorthand format (e.g., github:123) for external references.

internal/github · high confidence

Added an example in \examples/library-usage\ demonstrating how to integrate Beads as a Go library instead of using the CLI. The example shows programmatic access to the \beads.Storage\ interface, including opening a workspace, creating and updating issues, managing dependencies and labels, and retrieving statistics. It also includes tests to verify compilation and basic API functionality.

examples/library-usage · high confidence

This change introduces several new capabilities and validations within the types package. It adds a new deterministic hash-based ID generator that creates progressive 6-8 character hex IDs based on content, along with hierarchical child ID support and depth checking. It implements storage class validation, enforcing rules for versioned, unversioned, and ephemeral storage modes, including mutual exclusivity between ephemeral and no-history flags. Additionally, it adds a readiness explanation system that analyzes issues to report ready, blocked, and cyclic dependencies, and introduces an orphan detection interface for cross-repo consistency checks.

internal/types · high confidence

The Jira integration has been extracted into the internal/jira package, introducing a new HTTP client that supports both Jira REST API v2 and v3 (defaulting to v3) via the configurable jira.api\_version setting. The client includes robust retry logic with exponential backoff and jitter for transient 429 and 503 errors, along with pagination guards to prevent infinite loops. It supports multi-project queries, custom status/type/priority mappings, and custom field configuration, enabling users to sync issues between Beads and Jira Cloud or Server instances.

internal/jira · high confidence

Added a new Python-based agent example in the \examples/python-agent\ directory that demonstrates how to automate task management using the \bd\ CLI. The included \agent.py\ script and \README.md\ show users how to programmatically find ready work, claim and complete tasks, and discover new issues during execution, linking them back to parent tasks via dependencies. This serves as a reference implementation for integrating AI agents with the beads issue tracker.

examples/python-agent · high confidence

The \bd doctor\ command now includes a dedicated \--agent\ mode that runs a suite of checks specifically designed to verify the health and configuration of AI coding assistants (such as Claude Code, Cursor, and Copilot). This mode validates that the necessary plugins, MCP servers, and git hooks are correctly installed and configured, ensuring that AI agents have the proper context and permissions to interact with the Beads issue database. It also includes checks for stale circuit breaker files and consistency of the \is\_blocked\ state, providing actionable remediation steps to resolve integration issues that may hinder agent performance.

cmd/bd/doctor · high confidence

The \cmd/bd/doctor/fix\ package introduces a suite of automated repair commands for the \bd doctor --fix\ workflow. Users can now automatically clean stale classic artifacts (SQLite WAL/SHM files, backup databases, and JSONL leftovers) from \.beads\ directories, including cruft in redirect-expected locations. The tool can recover from Dolt database corruption by backing up the corrupt directory and reinitializing via \bd init\. It also repairs schema drift by re-linking foreign keys severed on clone-local tables during hard resets, re-keying dependency rows left over from the \#4259 rekey backfill, and correcting stale \is\_blocked\ flags through a full recomputation. Additionally, it fixes configuration mismatches, such as updating the \database\ field in \metadata.json\ when the backend is Dolt, and auto-detecting the correct SQLite database file name.

cmd/bd/doctor/fix · high confidence

The configuration system now supports explicit agent policy profiles (conservative, minimal, team-maintainer) via the \agent.profile\ config key and \BD\_AGENT\_PROFILE\ environment variable, allowing users to control the extent of an agent's git and commit authority. Additionally, the \.beads/\ directory and its state files are now strictly enforced to have owner-only permissions (0700 and 0600 respectively), with automatic repair logic to fix insecure permissions on Linux and warning messages on other platforms.

internal/config · high confidence

Added a new example in the \examples/bash-agent\ directory that demonstrates how to use the \bd\ CLI to build a pure bash AI agent. The \agent.sh\ script autonomously discovers ready work, claims tasks, simulates work execution, and can discover and link follow-up issues using the \discovered-from\ dependency type. The accompanying \README.md\ provides usage instructions, customization options (such as adjusting discovery probability or adding filters), and guidance on integrating with real LLM APIs.

examples/bash-agent · high confidence

The internal/beads package now exposes a public Go API for custom extensions, including functions to resolve .beads/redirect files and find databases, alongside a new RepoContext system that centralizes git repository path resolution to ensure commands run in the correct directory regardless of worktrees or BEADS\_DIR redirections.

internal/beads · high confidence

The internal/lockfile package now provides platform-specific file locking implementations (Unix, Windows, and WASM) that support both exclusive and shared locks in blocking and non-blocking modes. This introduces new error types (ErrLocked, ErrLockBusy) and an IsLocked helper to reliably detect lock contention across processes, ensuring that concurrent operations correctly handle existing locks without hanging or failing silently.

internal/lockfile · high confidence

The .devcontainer directory now provides a fully configured development environment using the mcr.microsoft.com/devcontainers/go:2-1.24-bookworm image. The setup script automatically builds and installs the bd CLI from source, initializes the project database (checking for .beads/beads.db), installs git hooks, and downloads Go module dependencies. The configuration also persists the gms\_pure\_go build tag in the Go environment and mounts the local .gitconfig to preserve user identity.

.devcontainer · high confidence

A new \docsmint\ tool in the \tools\ directory post-processes the generic Markdown output from \bd help --docs-root\ into Mintlify-compatible MDX. It converts HTML comments to JSX comments, rewrites relative links to extensionless routes, and updates the navigation in \docs/docs.json\. The tool also handles legacy Docusaurus-formatted pages from older \bd\ versions and neutralizes lines starting with \export\ or \import\ to prevent MDX parsing errors.

tools · high confidence

The \internal/templates\ package now provides Go-embedded templates and skill definitions for AI agents using the Beads issue tracker. This includes a \BeadsAgentSkill\ (with OpenAI metadata) and a structured \AGENTS.md\ template that features a one-line architecture summary, a \--claim\ workflow, and non-interactive shell command rules. The system supports two rendering profiles—\full\ (command-heavy) and \minimal\ (pointer-only)—and uses versioned, hashed markers to detect staleness and safely replace existing integration sections. It also conditionally omits \bd dolt push\ instructions when no remote is configured, ensuring agents only suggest sync commands when appropriate.

internal/templates · high confidence

A new public \schema\ package has been added to expose the internal schema migration engine for external use. This package provides a minimal API to create or upgrade a database using standard \database/sql\ connections, including functions to check the latest and current schema versions, detect schema skew errors, and apply pending migrations with process serialization via named locks. As this package is marked experimental before v1.3.0, its API may change in minor releases and is not covered by the project's compatibility promise.

schema · high confidence

The \scripts/migration-test\ directory now provides a comprehensive test harness to verify upgrade paths across historical versions of the product. This includes a \catalog\ tool that generates and validates an authenticated, pinned release catalog (122 versions) with strict SHA-256 identity checks to ensure reproducible test inputs. The harness features \historical-dolt-upgrade-test.sh\ for end-to-end verification of authentic historical upgrades (covering SQLite bridges and embedded Dolt versions from v0.9.1 through v1.2.2) and \legacy-bridge-test.sh\ for fast safety checks on the public sealed-copy SQLite bridge. It also introduces \lib/binary.sh\ for secure, isolated verification of historical release binaries and \lib/versions.sh\ to define the supported version matrix and platform-specific release assets for both Linux/amd64 and Darwin/arm64.

scripts/migration-test · high confidence

A new \format\ package has been added to provide public formatting functions for issue output, allowing consumers like the \gt\ CLI to render issues without depending on the internal \bd\ CLI. This package introduces functions to format issues in three distinct views: \PrettyIssue\ for a standard one-line list, \CompactIssue\ for a detailed single-line view including assignees, labels, and dependency info, and \LongIssue\ for a full multi-line detail view. It also includes utilities for generating status icons, dependency strings, and list summaries, along with a comprehensive test suite to verify the correctness of these rendering functions.

format · high confidence

The repository now includes a \scripts/\ directory containing a suite of maintenance and CI guard tools. This introduces \release.sh\ as a one-command release automation (version bump, tagging, Homebrew formula verification, and local upgrade), alongside \bump-version.sh\ for updating version strings across all components (though it is now deprecated in favor of the molecule-based release workflow). Several new guard scripts enforce project hygiene: \check-build-tags.sh\ ensures all Go invocations use the \gms\_pure\_go\ tag to prevent ICU regressions; \check-cli-docs-drift.sh\ and \check-doc-flags.sh\ validate that generated CLI documentation and references remain consistent with the live binary; \check-doc-freshness.sh\ enforces review markers on reference docs; \check-go-install-guidance.sh\ prevents unsupported installation instructions; \check-migration-hygiene.sh\ guards schema migrations against duplicates, nondeterminism, and frozen-file edits; and \check-testing-short.sh\ restricts the use of \testing.Short()\ to approved runtime/stress skips. Additionally, \build-examples.sh\ ensures example modules stay type-checkable and in sync with the parent dependency graph.

scripts · high confidence

Added \scripts/bench-ready-indexes\ to benchmark query performance across different index configurations on MySQL, and \scripts/repro-dolt-prod-timeouts\ to simulate production-shaped workloads and measure \bd\ command latency. The timeout reproduction script includes logic to scrub Windows environment variable keys case-insensitively when spawning subprocesses, ensuring consistent environment handling across platforms.

scripts/repro-dolt-prod-timeouts · high confidence

The internal/audit package now provides an optional append-only JSONL sidecar log (stored as .beads/interactions.jsonl) that records LLM calls, tool usage, and field changes. This feature is opt-in, controlled by the BD\_AUDIT\_ENABLED environment variable or the audit.enabled config setting, and uses atomic writes with 16-byte random IDs to ensure data integrity under concurrent access.

internal/audit · high confidence

The CLI now pipes long output to a system pager (defaulting to 'less') when the terminal is large enough, respecting the BD\_NO\_PAGER environment variable and --no-pager flag. External content displayed in the terminal is sanitized to strip ANSI escape sequences and control characters, preventing terminal injection attacks. Terminal styling has been updated to use the Ayu color theme with adaptive light/dark mode support, and color output is now correctly disabled in git hook contexts to prevent escape sequence leaks.

internal/ui · high confidence

The \backend\ package now exposes a public surface that allows external Go modules to implement custom storage backends. It re-exports the internal \DoltStorage\ engine interface, all related domain types, sentinel errors, and constants as type aliases, ensuring that external implementations see identical types to in-tree consumers. A registration system (\Register\) allows external backends to plug into the application at startup, and a conformance test suite is provided to verify that an external implementation behaves correctly against the reference Dolt backend.

backend · high confidence

The credential resolution system now supports sourcing secrets from external command-line helpers (such as kubectl ExecCredential, AWS credential\_process, or Vault). A new CommandSource rung executes a configured shell command, parses the output as a bare token or a JSON envelope (supporting fields like token, access\_token, and expirationTimestamp), and caches the result to avoid repeated executions. The resolution ladder is fail-closed, meaning a misconfigured or failing helper will abort the credential lookup rather than silently falling back to a lower-priority source.

internal/creds · high confidence

The internal time parsing logic now supports a layered approach for interpreting relative date and time inputs. Users can specify durations using compact syntax (e.g., +6h, -1d, +2w) or natural language phrases (e.g., tomorrow, next monday, in 3 days). The parser attempts to match compact durations first, followed by absolute date formats, and finally natural language expressions, ensuring consistent and predictable behavior for relative time inputs.

internal/timeparsing · high confidence

The \cmd/beads\ directory has been completely removed, deleting the \dep.go\, \main.go\, and \ready.go\ source files. This eliminates the Beads issue tracker CLI application, including all associated commands for managing issues (create, show, list), handling dependencies (add, remove, tree, cycles), and viewing work status (ready, blocked, stats).

cmd/beads · high confidence

The project now enforces strict architectural boundaries and build consistency through new configuration files. A \.buildflags\ script standardizes the Go build environment by defaulting to \CGO\_ENABLED=1\ and applying the \gms\_pure\_go\ tag to ensure the SQL engine uses the Go stdlib regex instead of ICU, preventing unnecessary runtime dependencies. A \.gitattributes\ file enforces LF line endings across the repository to guarantee deterministic text diffs and hook behavior. Additionally, \.golangci.yml\ (v2) introduces \depguard\ rules that enforce the 'Storage Boundary' (restricting direct Dolt engine access to specific adapter packages), the 'WorkAPI Boundary' (keeping the work-query contract frontend-agnostic), and the 'HTTPAPI Transport Boundary' (preventing HTTP handlers from building internal filters or bypassing use-case roles).

(repo-wide) · high confidence

The new internal/workapi package centralizes the logic for issue listing, counting, deletion, and detail retrieval, ensuring that the CLI and any other frontend interpret commands identically. It provides database-free validation and normalization for bootstrap, delete, and count requests, builds a single definition of the list filter (handling defaults, status exclusions, and ephemeral plane admission), and assembles the issue detail view with optional dependents and comments. By normalizing storage error sentinels and enforcing a strict frontend boundary, it prevents frontend implementations from drifting in their interpretation of query parameters and error states.

internal/workapi · high confidence

The system now uses an internal atomic file writing mechanism for command exports. This change ensures that file updates are performed safely by writing to a temporary file first, syncing it to disk, and then atomically renaming it to the target location. Users benefit from guaranteed data integrity, as readers will never see partial or truncated files during an update; they will only ever see the previous complete version or the new complete version.

internal/atomicfile · high confidence

The config system now uses metadata.json as the primary configuration file, with an automatic migration path from the legacy config.json. A new central server configuration (server.json) allows sharing Dolt server connection settings across projects, while credentials are now stored in a dedicated platform-specific file with secure permission warnings. The config schema has been expanded to support Dolt server mode with TLS, Unix domain sockets, and custom data directories, and includes centralized error messaging for removed backends that intelligently detects existing Dolt data to provide targeted recovery instructions.

internal/configfile · high confidence

The internal/debug package now provides a unified interface for controlling output verbosity. Users can enable debug logging via the BD\_DEBUG environment variable or programmatically via SetVerbose, and suppress non-essential informational output using the new quiet mode (SetQuiet/IsQuiet). This centralization standardizes how debug and normal output is handled across the application, ensuring consistent behavior for logging and informational messages.

internal/debug · high confidence

New projects now use Dolt as the default database backend instead of SQLite. The CLI automatically migrates existing SQLite databases to Dolt on the first command run, and the \bd doctor\ command includes validation checks to ensure the migration is correct.

cmd/bd · high confidence

The events journal is now configurable per workspace via the \events-journal\ setting in \config.yaml\ or the \BD\_EVENTS\_JOURNAL\ environment variable, with the environment variable taking precedence to allow process-wide overrides. The journal includes bounded-by-default auto-pruning that retains rows based on configurable time intervals and volume thresholds, ensuring the journal does not grow unbounded while preserving recent history. Additionally, the journal now records the mutating actor on every row, and a standardized \Record\ type ensures that both the CLI output and the HTTP API (\GET /v0/beads/events\) expose the same JSON structure, preventing data drift between consumers.

internal/eventsjournal · high confidence

The internal/doltversion package now provides a robust mechanism to locate and validate the external dolt binary used by managed proxied-server mode. Discovery follows a strict precedence: the BEADS\_DOLT\_BIN environment variable, a sidecar configuration, and finally the system PATH, with explicit paths validated for existence and executability before use. The version probe is hardened against hanging or malicious binaries via bounded timeouts (10s) and output caps (64KiB). Instead of failing hard on older or unverifiable versions, the system now issues a non-fatal warning if the dolt version is below the recommended minimum (2.0.0) or if the version string cannot be parsed, allowing operations to proceed while alerting the operator. Additionally, a cross-process JSON cache is introduced to store probe results keyed by binary fingerprint (path, size, mtime), significantly reducing the overhead of forking the dolt binary on every command invocation while ensuring cache validity via fingerprint checks.

internal/doltversion · high confidence

A new \beadserrors\ package has been added to centralize common error types (such as \ErrValidation\, \ErrNotFound\, and \ErrNotInitialized\) that are shared across different system roles. This change resolves circular import dependencies between sibling planes (like \memoryops\ and \issueops\) by providing a neutral location for these errors, which are then re-exported by individual role packages via Go aliases to maintain compatibility with existing error-checking logic. The package is marked as experimental and may change in minor releases.

beadserrors · high confidence

The \internal/worktreeremove\ package now includes a side-effect-free safety policy that validates worktree removal requests before execution. This policy enforces strict checks to prevent accidental deletion of the primary or current worktree, ensures the target is clean and contained within the repository (unless force mode is used), and manages cleanup of associated ignore entries. It also includes revalidation logic to ensure invariants hold immediately before the destructive mutation and failure classification to distinguish between complete and partial removal failures.

internal/worktreeremove · high confidence

The repository now installs a suite of Git hooks in .githooks that improve developer experience and release safety. The pre-commit hook automatically formats Go files with gofmt and runs golangci-lint (v2.10.1) with auto-fixes, pinning the Go toolchain to match go.mod to prevent local CI mismatches. The pre-push hook blocks release tag pushes if version constants are inconsistent, using scripts/check-versions.sh to catch drift before it reaches CI. Additionally, all hooks now integrate with the 'beads' database tool, supporting configurable timeouts and graceful fallbacks if the database is uninitialized or the tool is missing.

.githooks · high confidence

The Notion integration has been rewritten to sync via the Notion REST Data Sources API instead of the previous method. This change introduces a new client that interacts with data source endpoints (such as /data\_sources and /databases), enforces a specific Notion API version (2026-03-11), and includes a dedicated field mapper to convert between Notion page properties and internal issue types. Authentication now supports resolving tokens from configuration before falling back to environment variables, and the sync logic handles paginated queries against the data source to pull and push issues.

internal/notion · high confidence

Two new PreToolUse hooks have been added to prevent agent hangs and API quota exhaustion. The block-gh-watch.sh hook denies execution of \gh run watch\ and \gh run list --watch\, which previously consumed the GitHub API rate limit by polling every 3 seconds; users should instead use \gh run view \<run-id\>\ for status checks. The block-interactive-cmds.sh hook denies \cp\, \mv\, and \rm\ commands that lack the \-f\ flag, preventing indefinite hangs caused by macOS interactive aliases; users must explicitly use the \-f\ flag or prefix commands with \command\ to bypass aliases.

.claude/hooks · high confidence

The test utilities have been refactored to replace binary-spawned Dolt servers with testcontainers, introducing a new ContainerProvider for managing Docker-based Dolt SQL servers and enforcing branch-per-test isolation via dedicated Dolt branches. To prevent test suites from accidentally connecting to ambient shared servers, the infrastructure now includes port-mismatch firewalls and pins the DOCKER\_HOST environment variable from the active Docker context before swapping HOME. Additionally, test execution is hardened with suite-owned temporary directories for reliable cleanup, in-memory filesystem support for faster git-heavy tests, and explicit handling of git hook paths to ensure consistent behavior.

internal/testutil · high confidence

The tracker sync engine now includes a comprehensive conformance test suite to verify adapter behavior, ensuring consistent pull/push semantics across integrations. The engine itself has been hardened to abort the push loop immediately upon hitting a provider rate limit, preventing wasted API calls and surfacing warnings to the user. Additionally, a new IssueIDs filter allows users to perform selective syncs for specific issues, and the engine now correctly enforces close policies during pull operations to prevent status wedges.

internal/tracker · high confidence

The internal workspacegate package now implements a two-level cross-process fence using OS advisory locks to coordinate access to workspace and physical database roots. Normal commands acquire a shared gate for the lifetime of their store or provider, while maintenance operations (such as mode migration, restore, or destructive repair) acquire an exclusive gate to detect and refuse to run over concurrent activity. The gate files are placed in stable parent directories outside the roots they protect to ensure identity stability across directory replacements, and the system supports configurable wait times, polling intervals, and holder diagnostics to help users understand contention.

internal/workspacegate · high confidence

The internal validation package has been refactored to centralize validation logic into composable functions. Users will see improved handling of issue IDs with hyphenated prefixes (e.g., 'bead-me-up-3e9'), which are now correctly parsed instead of being truncated. Actor identity comparisons are now canonicalized, allowing different spellings of the same identity (using dots, underscores, or hyphens) to be treated as equivalent, while preventing silent cross-actor closes. Additionally, template validation now supports configurable per-type lint sections via the \lint.sections.\<type\>\ config, allowing users to add custom required sections to issue types like Epics.

internal/validation · high confidence

Resolves foreign key constraint violations that occurred when adding comments or applying compaction operations, preventing these actions from failing with database errors.

internal/storage · high confidence

This change consolidates and fixes core utility functions for issue ID resolution and path handling. It introduces a new \id\_parser.go\ that resolves partial issue IDs using a config-aware prefix system, correctly handling multi-hyphen prefixes (e.g., \hacker-news-ko4\), rejecting substring matches in favor of exact hash matches, and supporting cross-prefix lookups. It also adds \issue\_id.go\ with natural numeric sorting for issue IDs (fixing \bd-E.4\ vs \bd-E.10\ ordering) and robust prefix extraction that distinguishes hash-like suffixes from word-like suffixes. Additionally, \path.go\ and its platform-specific counterparts (\path\_case\_darwin.go\) implement \CanonicalizePath\ with a fast-path kernel query (\F\_GETPATH\) on macOS to resolve true filesystem case, preventing performance regressions on systems with many ancestor directory entries, while maintaining symlink resolution and cross-platform compatibility.

internal/utils · high confidence

The \bd show\ command now correctly renders markdown in bead descriptions and notes without corrupting the text. This change fixes several issues where plain-text content was being misinterpreted as markup: angle-bracket spans (like \\<PLACEHOLDER\>\ or comparison operators) are no longer silently deleted, and shell globs (like \\*.log\) are no longer treated as emphasis delimiters that vanish or turn into literal asterisks. Additionally, terminal capabilities are now properly gated, ensuring ANSI colors and hyperlinks are only applied when the terminal supports them, and agent mode returns raw markdown verbatim.

internal/uimd · high confidence

The internal Dolt server package now reads the server port from config.yaml listener.port in DefaultConfig, uses OS-assigned ephemeral ports by default to eliminate birthday-problem collisions, and adds comprehensive tests for stale PID/port recovery, process detection across Unix/Windows, and file descriptor hygiene. It also introduces GC config version probing with memoization and startup log rotation to prevent oversized log files.

internal/doltserver · high confidence

The system now more accurately recognizes and converts various Git remote URL formats, including SCP-style URLs without a username (e.g., host:path) and Windows drive paths, ensuring they are correctly mapped to Dolt's internal format. Additionally, remote URLs are now standardized for comparison by stripping embedded credentials and normalizing host case, which helps prevent duplicate remote entries caused by minor URL variations.

internal/doltremote · high confidence

The internal Git detection logic has been consolidated into a cached context that reliably identifies Git worktrees by comparing the git directory against the common directory. This ensures that operations like hook discovery and root detection work correctly in worktree environments. Additionally, the code now normalizes repository root paths by resolving symlinks and canonicalizing case on macOS, fixing issues where path mismatches prevented proper .beads discovery in nested worktrees. Tilde expansion in core.hooksPath is also handled correctly on Windows. New utilities have been added to detect Jujutsu (jj) repositories, including support for secondary workspaces, allowing the tool to recognize and operate within jj-based version control setups.

internal/git · high confidence

The internal metrics subsystem has been rewritten to address several critical issues. Performance is improved by caching the machine ID to avoid slow platform probes on every invocation, and by throttling the detached send-metrics child process to run at most every 5 minutes instead of on every command. Reliability is fixed by ensuring that even when telemetry is disabled, the detached child still prunes the queued event backlog to prevent disk space exhaustion (up to 15GB observed), and by properly reaping detached children to avoid zombie processes. Security is enhanced by pinning the metrics endpoint in the detached child to prevent hostile project configurations from redirecting telemetry data. Additionally, the system now honors the DO\_NOT\_TRACK environment variable as an opt-out mechanism.

internal/metrics · high confidence

Added Oracle A conformance test harness for bd CLI parity; Added Oracle A refactor-safety conformance tests for bd; Added comprehensive test suite for beads-mcp integration; Added documentation synchronization and consistency tests; Added integration tests for the npm package; Added reproduction script for the 12-second slow path on bd commands; Added structural regression test for TestMain cleanup leaks; Added tests for the Go formatting check script; Added tests for the gitattributespolicy EOL enforcement script; Comprehensive script-based integration tests for the bd CLI; Introduce OpenAPI v0 specification and embedded source of truth; Introduces a golden-JSON contract corpus to pin the bd CLI wire surface; New Dolt-based test fixtures for large-scale issue data; New conformance audit suite for reference implementation behaviors; New end-to-end conformance test suite for CLI and storage backends; New integration test infrastructure for server lifecycle and corruption recovery; Regression test suite for SQLite-to-Dolt migration with snapshot-based parity checks.

Added two new example modules—\examples/bd-example-extension-go\ and \examples/library-usage\—that demonstrate how to integrate the Beads library into Go applications. Both examples depend on \github.com/steveyegge/beads\ and include full \go.mod\ and \go.sum\ files with their respective dependency trees, providing a reference for developers building extensions or consuming the library directly.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 62 → 73 (+10.9)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 62 → 76 (+14.7)
• Architecture 100 → 98 (-2.3)
• Maturity 86 → 86 (-0.2)
• Readiness 71 → 81 (+9.2)
• Security 72 → 82 (+9.6)
• Domain Modelling 53 → 64 (+11.2)

• Coverage not included — suite not readable by the collector
• Critical vulnerability: [GHSA redacted] (go.mod)
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• DoltStore.DeleteIssues (cognitive 22) (internal/storage/dolt/issues.go)
• DoltStore.DeleteIssues (cyclomatic 16) (internal/storage/dolt/issues.go)
• DoltStore.UpdateIssueChecked (cognitive 16) (internal/storage/dolt/issues.go)
• DoltStore.filteredPushToPeer (cognitive 17) (internal/storage/dolt/federation.go)
• DoltStore.verifiedClaimWrite (cognitive 21) (internal/storage/dolt/claim_verify.go)
• DoltStore.verifiedReadyClaim (cognitive 33) (internal/storage/dolt/issues.go)
• DoltStore.verifiedReadyClaim (cyclomatic 20) (internal/storage/dolt/issues.go)
• Duplicated block (10 lines × 2) (cmd/bd/batch.go)
• Duplicated block (10 lines × 2) (cmd/bd/defer_proxied_server.go)
• Duplicated block (10 lines × 2) (cmd/bd/dep.go)
• Duplicated block (10 lines × 2) (cmd/bd/dep_proxied_server.go)
• Duplicated block (10 lines × 2) (cmd/bd/doctor/dolt.go)
• Duplicated block (10 lines × 2) (cmd/bd/gate.go)
• Duplicated block (10 lines × 2) (cmd/bd/import_shared.go)
• Duplicated block (10 lines × 2) (cmd/bd/linear.go)
• Duplicated block (10 lines × 2) (cmd/bd/list_input.go)
• Duplicated block (10 lines × 2) (format/format.go)
• …and 371 more

• Boundary-crossing change coupling: doc.go ↔ reader.go (internal/httpapi/doc.go)
• Change coupling: doc.go ↔ reads.go (internal/httpapi/doc.go)
• Change coupling: events.go ↔ rename.go (internal/storage/dolt/events.go)
• ClassTooLong: DoltStore (internal/storage/dolt/store.go)
• ClassTooLong: EmbeddedDoltStore (internal/storage/embeddeddolt/store.go)
• ClassTooLong: Engine (internal/tracker/engine.go)
• ClassTooLong: Evaluator (internal/query/evaluator.go)
• ClassTooLong: InstrumentedStorage (internal/telemetry/storage.go)
• ClassTooLong: Server (internal/httpapi/server.go)
• ClassTooLong: Tracker (internal/linear/tracker.go)
• ClassTooLong: dependencySQLRepositoryImpl (internal/storage/domain/db/dependency.go)
• ClassTooLong: doltTransaction (internal/storage/dolt/transaction.go)
• ClassTooLong: issueSQLRepositoryImpl (internal/storage/domain/db/issue.go)
• ClassTooLong: issueUseCaseImpl (internal/storage/domain/issue.go)
• Documentation: no contributor guidance (README.md)
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• DoltStore.deleteIssues (cognitive 19) (internal/storage/dolt/issues.go)
• DoltStore.withRetryTx (cognitive 17) (internal/storage/dolt/store.go)
• Duplicated block (10 lines × 2) (backend/conformance/batch_creator_contract.go)
• …and 1659 more

• 300 commits — 150 feature/other, 150 fixes

• cmd/bd — 100 commits
• internal/storage — 95 commits
• internal/httpapi — 20 commits
• .github/workflows — 13 commits
• backend/conformance — 10 commits
• (repo) — 7 commits
• (root) — 7 commits
• internal/metrics — 6 commits
• docs/reference — 4 commits
• scripts/ci — 3 commits
• scripts/migration-test — 3 commits
• integrations/beads-mcp — 2 commits
• internal/doltserver — 2 commits
• internal/hooks — 2 commits
• internal/uimd — 2 commits
• .github/scripts — 1 commit
• beadserrors/errors.go — 1 commit
• docs/architecture — 1 commit
• docs/core-concepts — 1 commit
• docs/multi-agent — 1 commit

• fix: Fix CRLF worktree gitignore matching (#5525) (#5605)
• fix: Fix E2BIG when runDoltSQL passes large schema SQL as a single argv (#5846)
• fix: Fix supersedes and other dependency types displaying as blockers (#5529)
• fix: Fix: CLI/runtime schema parity oracle ignored-column handling + pool-heal cherry-pick (be-krza3) (#5878)
• fix: Fix: check-testing-short.sh flags comments and misnames the offending function (round 2) (#5809)
• fix: Make the conformance obligation true: rewire the dolt_log probes, fix the doc that lied (#5449)
• fix: Merge pull request #5496 from gastownhall/fix/events-journal-shape-repair
• fix: fix(backup): stop attributing proxied auto-backup OFF to a missing git remote (#6694)
• fix: fix(bd): canonicalize actor==assignee comparisons in unclaim.go and AuthorizeAssigneeTransferWithPools (#5439)
• fix: fix(bd): canonicalize remaining actor==assignee comparisons in claim/heartbeat CAS (ga-v2k49) (#5479)
• fix: fix(bootstrap): probe git remotes for dolt data instead of rejecting; exit non-zero when bootstrap declines (#5743, #5663) (#6037)
• fix: fix(build): restore freebsd compilation with unsupported-platform stubs for procid + unverified-process (release v1.2.0 blocker) (#5661)
• fix: fix(ci): make a failed pinned-dolt download actually fail the job (#5935)
• fix: fix(ci): pin the Dolt CLI — 2.3.0 broke DOLT_RESET on fresh databases (ga-m0dlk) (#5894)
• fix: fix(ci): remove recursive Make from lint formatting (#5302) (#5320)
• fix: fix(circuit): stop the legacy sweep churning against live TMPDIR-less writers (#5640)
• fix: fix(cli): bd list --wisp-type cannot match a row — register the plane knob it needs (#6098)
• fix: fix(cli): accept --flat on bd ready as an alias for --plain (#5724)
• fix: fix(cmd/bd): label created_by as 'Created by:' instead of 'Owner:' (#5800)
• fix: fix(cmd/bd): restore os.Stdout via deferred idempotent restore so capture helpers survive t.Fatal (#5803)
• …and 280 more

• Unchanged — 0 containers · 2 contexts · 0 edges

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

gastownhall/beads was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.