Skip to content
CAI
Software that uses CAICheck a score

gastownhall/beads

69.1

Adequate · 24 October 2026

416.7k

lines of production code

Go

primary language

6

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

Beads is a local-first, Git-integrated issue tracking system that manages tasks, dependencies, and workflows via a CLI and a public Go library. It supports remote connectivity through an HTTP API and integrates with external project management platforms like GitHub, GitLab, Jira, Linear, and Azure DevOps. The system is designed to be embeddable and extensible, offering robust tooling for AI agents and custom storage backends.

How it got here

2025 — AI agent integration and Dolt migration

43 changes.

The project shifted its default storage backend from SQLite to Dolt and introduced comprehensive support for AI coding agents through Model Context Protocol (MCP) servers, dedicated setup commands, and autonomous agent examples. This period also focused on architectural hardening, deterministic builds, and expanding the issue tracking capabilities with advanced workflows, compaction, and extensible hook systems.

2026 — multi-provider integration and infrastructure hardening

85 changes.

This period focused on expanding the project's integration capabilities by adding robust, bidirectional sync support for major issue trackers including GitLab, Jira, Azure DevOps, and GitHub, alongside a new recipe-based architecture for AI assistant configuration. Concurrently, the codebase underwent significant infrastructure hardening, introducing comprehensive OpenTelemetry telemetry, atomic file operations, and a public backend contract to support out-of-tree storage implementations. The work also established rigorous testing and release safety through new conformance suites, historical migration verification, and strict API wire-format guards.

Features

Add Go extension example demonstrating custom SQLite table integration

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

Add OpenAPI v0 specification and embedded spec package

The \internal/httpapi/spec\ package now contains the hand-written OpenAPI 3.0.3 document (\openapi.v0.yaml\) for the \/v0\ HTTP surface, embedded into the binary via \embed.go\. This document serves as the source of truth for the wire contract, enabling generated Go types and parity tests to validate against the actual shipped specification rather than disk copies. The package also exposes the raw YAML for external tooling, such as the \httpclient\ encode tests and the \repochecks\ drift tests, ensuring consistency between the spec and the generated client code.

internal/httpapi/spec · high confidence

Add hash-based ID generation for issues

The internal/idgen package now includes a new GenerateHashID function that creates stable, short identifiers for issues using SHA-256 hashing and base36 encoding. This allows the system to generate compact, human-readable IDs (e.g., 'bd-vju') based on issue metadata like title, description, creator, and timestamp, with support for variable lengths from 3 to 8 characters. The implementation includes corresponding unit tests to verify the output matches expected vectors.

internal/idgen · high confidence

Add molecules.jsonl catalog for read-only issue templates

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

Add scripts to reproduce production timeout scenarios and benchmark index performance

New scripts have been added to help diagnose and validate performance under production-like conditions. The \scripts/repro-dolt-prod-timeouts\ tool initializes a synthetic workspace with a large issue and dependency graph to run \bd\ CLI commands against, allowing users to reproduce and analyze timeout behaviors across various scenarios (ready, dependency, control, mixed, outage, and cycle detection). Additionally, \scripts/bench-ready-indexes\ provides a benchmarking utility to evaluate the performance impact of specific database indexes on query execution, supporting MySQL connections and configurable concurrency and iteration parameters.

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

Added Dolt hang reproduction script and incident report

Added a new Go-based reproduction tool (\scripts/repro-dolt-hang\) and an incident report (\INCIDENT-REPORT.md\) to help diagnose and verify fixes for a server hang issue. The script compares two transaction patterns under concurrent load: the 'old' pattern which redundantly calls \tx.Commit()\ after \DOLT\_COMMIT\, and the 'new' pattern which omits the redundant commit as recommended. The incident report documents the production hang, the environment configuration, and the investigation into the redundant commit causing raciness.

scripts/repro-dolt-hang · high confidence

Added example scripts for manual, automated, and threshold-based database compaction

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

Added startup hook script for automatic AI agent upgrade awareness

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

Authenticated historical release catalog tooling

Added a new Go-based catalog tool and its Bazel build rules in the migration-test directory to manage a pinned, authenticated universe of 127 historical module versions (v0.9.1 through v1.3.1). The tool provides commands to generate the catalog from live Go proxy and GitHub APIs or validate an existing manifest against strict schema, provenance, and SHA-256 identity checks. This ensures that regression, migration, and cross-version tests run against a finite, reproducible, and integrity-verified set of release assets rather than downloading binaries dynamically.

scripts/migration-test/catalog · high confidence

Centralized debug and quiet-mode logging in internal/debug

The internal/debug package now provides a unified logging API for the application. Users can enable verbose debug output via the BD\_DEBUG environment variable or the SetVerbose function, and suppress non-essential informational output using the SetQuiet function. The package exposes Logf and Printf for debug messages (only shown when debug is enabled) and PrintNormal/PrintlnNormal for standard output (suppressed when quiet mode is active).

internal/debug · high confidence

Comprehensive OpenTelemetry instrumentation for all storage operations

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

Events journal activation, auto-pruning, and record schema

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. When enabled, the journal records every mutating actor on each row and automatically prunes old entries based on configurable retention floors (time and volume thresholds) to keep the ledger bounded. The published record format is standardized across the CLI and HTTP API, ensuring consumers receive a consistent envelope with sequence, timestamp, operation, actor, and payload data.

internal/eventsjournal · high confidence

Explicit role configuration and improved user role detection

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

Formula engine gains control flow, expansion, and advice operators

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

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

HTTP client encoder with divergence-ledger refusal policy

The \internal/httpclient/encode\ package introduces a strict client-side policy for the v0 HTTP wire: request fields that cannot be expressed as query parameters are refused (raising \ErrRefused\) rather than silently dropped, preventing invisible result-set widening. This is enforced by a machine-readable divergence ledger (\ledger.go\) that catalogs every inexpressible field with a reason and a pinned test, and a reflection-based bijection gate (\bijection\_test.go\) that ensures the encoder tables, the ledger, and the OpenAPI specification remain in sync. The package also provides the encoding logic for operations like \listReadyWork\, \listIssues\, and \getIssue\, mapping request structs to URL parameters while handling specific constraints such as the \issues.list.filters\ capability token.

internal/httpclient/encode · high confidence

Initial release of beads-mcp server with context engineering and multi-repo support

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

Introduce AI-powered issue compaction with Claude Haiku

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

Introduce Git environment routing and scrubbing logic

Added the \internal/gitenv\ package to define and enforce boundaries for Git-related environment variables. The new \routing.go\ implementation identifies Git routing keys (such as \GIT\_DIR\, \GIT\_CEILING\_DIRECTORIES\, and config paths) and provides functions to scrub them from the environment. It distinguishes between standard routing scrubbing, which preserves explicit null config suppression (e.g., \GIT\_CONFIG\_NOSYSTEM=1\), and authority-boundary scrubbing that removes these suppressions to prevent privilege escalation via config blinding. The package handles OS-specific key semantics, including case-insensitivity on Windows, and includes tests to verify correct filtering behavior across POSIX and Windows environments.

internal/gitenv · high confidence

Introduce a simple query language for complex filtering

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

Introduce bearer token authentication via file-backed rotation

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

Introduce durable mutation journal package for replayable event streams

The \journalops\ package provides the core interface and data structures for the workspace's durable mutation journal, which records every committed bead mutation in sequence order. This enables external consumers and internal tools (like \bd events tail\ and the \/v0/beads/events\ API) to replay the history of a single clone to rebuild their own graph state. The package defines the \Journal\ interface with a \ReadEventsJournalPage\ method that supports checkpoint-based polling, ensuring consumers can detect when their checkpoint has fallen below the retained window via a specific \TruncatedError\ rather than silently missing data. It also introduces the \Row\ struct to carry mutation details including the acting actor, ensuring auditability for deletes and dependency removals.

journalops · high confidence

Introduce historical SQLite workspace detection

Added the \internal/historicalsqlite\ package to identify legacy SQLite workspaces (pre-Dolt \.beads\ directories) by checking for specific on-disk layouts and configuration settings. This enables the \bd doctor\ command and workspace admission guards to correctly recognize these legacy structures and avoid interfering with their SQLite databases.

internal/historicalsqlite · high confidence

Introduce issueops library to centralize issue lifecycle operations

The issueops package now provides a unified library surface for all issue operations, replacing scattered implementations with a role-based architecture. This change introduces dedicated interfaces for batch operations (BatchApplier, BatchCreator, BatchCloser, BatchGetter), dependency management (EdgeReader, CycleDetector, TreeWalker), and state management (BlockingAnnotator, BlockedLister, StatsReporter). Users benefit from consistent transactional guarantees, such as atomic batch creates and non-atomic batch closes, and improved blocking state consistency where blocked flags are settled within the same transaction as the mutation. The library also standardizes error handling and validation across CLI and HTTP surfaces, ensuring that operations like close, update, and delete are enforced through a single, auditable code path.

issueops · high confidence

Introduce local remote database caching with secure URL validation

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

Introduce memoryops package for persistent workspace memories

A new \memoryops\ package provides the core interface for the workspace's persistent memory plane, enabling users to store, 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: memories are user data under a reserved namespace (\kv.memory.\*\) that converges on pull during merges, whereas settings do not. The package defines the \Memories\ interface with four methods (\Remember\, \Recall\, \Forget\, \List\) and handles request validation (aliasing \beadserrors.ErrValidation\) and result-based not-found semantics (using \Found\ booleans instead of \ErrNotFound\) to align with the underlying storage constraints. The implementation is marked experimental and is conformance-tested across three backends.

memoryops · high confidence

Introduce native binary distribution for the npm package

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

Introduce process-birth identity for safe child process management

The new \internal/procid\ package provides a platform-specific mechanism to generate and verify a unique 'birth token' for child processes, enabling safe reattachment and signaling while mitigating PID-reuse races. On Linux, it utilizes \pidfd\ (with a fallback to verify-then-signal on older kernels), while macOS and Windows use process creation time and handle-based verification respectively. Unsupported platforms return a clear error, preventing unsafe operations. This capability is designed for internal use by lifecycle managers (such as \dbproxy\) to ensure that signals are sent to the intended process instance.

internal/procid · high confidence

Introduce recipe-based AI tool integration architecture

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

Introduce shared Beads plugin package for Claude, Codex, and Copilot

The Beads plugin is now available as a shared package supporting Claude, Codex, and Copilot. It consolidates plugin manifests and a common skill tree, with specific configuration files for each platform (e.g., \.claude-plugin/\, \.codex-plugin/\, \.copilot-plugin/\). For Codex users, the plugin exposes lifecycle hooks (SessionStart, PreCompact, PostCompact, UserPromptSubmit) that integrate with \bd codex-hook\ to manage context refresh and memory injection. The package is built using Bazel and includes a Go library to embed the Copilot manifest, ensuring consistent plugin distribution across supported AI assistants.

plugins/beads · high confidence

Introduce shared, namespace-neutral error vocabulary

A new \beadserrors\ package provides a common set of error types (such as \ErrValidation\, \ErrNotFound\, \ErrNotInitialized\, and the \ErrUnsupported\ struct) that are re-exported by all role-specific leaves. This allows callers to classify refusals and validation failures using standard \errors.Is\/\errors.As\ checks without needing to import specific domain packages, while keeping the package dependency-free and marked as experimental.

beadserrors · high confidence

Introduce spec-generated Go types for the v0 HTTP API

The \internal/httpapi/apigen\ package now provides Go types generated from the \openapi.v0.yaml\ specification using \oapi-codegen\ (v2.7.1). This package contains only the data structures (types, enums, and parameters) required to interact with the v0 API surface; it does not include server stubs, routers, or request validation logic, which remain hand-written. The generated code ensures that the Go types stay in sync with the API contract, with build-time checks to detect drift between the spec and the generated output.

internal/httpapi/apigen · high confidence

Introduces Pydantic models for the Beads MCP server

Adds the \models.py\ file defining Pydantic data structures for the Beads MCP integration. This includes lightweight models (\IssueMinimal\, \BriefIssue\, \CompactedResult\) designed to reduce context window usage for list operations, as well as full issue models (\Issue\, \IssueBase\) and parameter models for creating and updating issues. The models support custom issue types, statuses, and dependency types, ensuring the MCP layer aligns with the \bd\ CLI's JSON output while providing validation for fields like priority.

beads-mcp · high confidence

Introduces a safety policy for worktree removal

The \internal/worktreeremove\ package now provides a side-effect-free safety policy that validates worktree removal requests before execution. It enforces rules such as preventing the removal of the primary or current worktree, requiring a clean state in normal mode, and verifying containment relative to a comparator. The policy supports a 'Force' mode that bypasses cleanliness and containment checks but still validates identity invariants, and it includes a revalidation step to ensure the target state has not changed between the initial check and the destructive mutation.

internal/worktreeremove · high confidence

Linear integration with OAuth, idempotency, and batch operations

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

Major schema expansion and structured error handling

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

Migration freeze gate and legacy SQLite reader

The migration subsystem now enforces a write-freeze gate: before any write command, the tool checks for a \MIGRATION-FREEZE\ marker file by walking the current directory and its ancestors (or a specific path via the \BD\_MIGRATION\_FREEZE\_FILE\ environment variable), refusing to proceed if the marker is found or unreadable. Additionally, a new \legacysqlite\ package provides an authenticated reader for legacy SQLite databases (versions 0.49.6 and 0.50.3), exporting their contents to canonical JSONL while validating schema integrity and rejecting unsafe or drifted sources.

internal/migration · high confidence

New AI agent integrations for Aider, Cursor, and Codex

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

New Bazel test infrastructure and CI tooling

This change introduces a suite of new Python scripts and Bazel build rules to the \tools/bazel\ directory to support a more robust, hermetic, and observable Bazel-based CI pipeline. Key additions include \check\_shard\_coverage.py\ and \check\_testcases.py\ to validate that Bazel shards run exactly the expected tests and that no tests are silently skipped or missed. The \ci\_analytics\_extract.py\ script and its tests provide a secure, redacted way to extract build metrics from Bazel's Build Event Protocol and execution logs for CI analytics. Additionally, \critpath.py\ offers critical-path analysis and budget enforcement for Bazel profiles, while \equivalence.py\ ensures parity between Bazel and legacy \go test\ execution. The \BUILD.bazel\ file defines the underlying infrastructure, including hermetic Dolt CLI pinning (\dolt.bzl\), cross-compilation rules (\release\_cross.bzl\), and wrapper scripts for various test environments (offline, pinned shards, manifest shards).

tools/bazel · high confidence

New CI tooling for shard balancing, cross-compilation, and complexity reporting

The CI pipeline gains several new scripts to improve test reliability and build coverage. A shared Python library (\_embedded\_shard\_manifest\_lib.py) and its generators (gen\_embedded\_cmd\_shard\_manifest.py) now cost-balance embedded Dolt test shards using measured durations or subtest counts, with incremental manifest updates to avoid merge conflicts. A new bash script (bazel-release-cross-compile.sh) replaces the previous go build job to verify that all pure-Go release targets compile across multiple platforms via Bazel. Additionally, a cyclomatic complexity reporter (complexity.sh) provides advisory and check-mode analysis against a baseline, and a package-gate detector (detect-package-gates.sh) optimizes CI runs by only triggering MCP/NPM package builds when relevant files change.

scripts/ci · high confidence

New GitHub Issues integration with robust rate-limit handling and push deduplication

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

New Go library usage example for Beads

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

New HTTP client implementation for OSS

The \internal/httpclient\ package has been introduced to provide an HTTP-based transport layer for the Beads backend, ported from the bd-enterprise codebase under the MIT license. This change adds a comprehensive set of role-based accessors (such as BatchApplier, BatchCloser, BatchCreator, and IssueReader) that map local operations to the v0 HTTP wire protocol, including client-side validation, capability negotiation via handshake snapshots, and credential resolution for multi-tenant scenarios. It also introduces a new \ProvidedCredential\ type to allow embedders to supply per-workspace authentication providers securely, ensuring that missing credentials in required modes result in explicit refusals rather than silent fallbacks.

internal/httpclient · high confidence

New ID generation, storage class validation, and readiness explanation logic

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

New Jira integration with API v2/v3 support and retry logic

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

New Python agent example for task management workflows

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

New \`bd doctor --agent\` mode for AI agent diagnostics

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

New \`bd doctor --fix\` capabilities for artifact cleanup, database integrity, and schema repair

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

New agent policy profiles and enhanced .beads directory security

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

New bash-based agent example for autonomous task management

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

New bazeltest utility for resolving repository paths in Bazel and Go test environments

Added the internal/testutil/bazeltest package, which provides helpers to resolve repository roots and runfile paths consistently across plain \go test\ and Bazel (including remote execution). The package detects the Bazel environment via \TEST\_SRCDIR\, resolves the workspace root from runfiles, and supports an explicit \BEADS\_TEST\_REPO\_ROOT\ override for debugging. It also includes utilities to resolve runfile-relative paths, locate caller directories, strip Bazel sharding environment variables to prevent interference in subprocesses, and resolve a prebuilt \bd\ binary path via \BEADS\_TEST\_BD\_BINARY\. The accompanying BUILD file defines the Go library and test targets, along with filegroups for repository documentation, Go sources, and test sources.

internal/testutil/bazeltest · high confidence

New beads extension API and centralized repository context

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

New cross-platform file locking primitives for concurrent access control

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

New devcontainer configuration for Go 1.24 development

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

New docsmint tool converts CLI docs to Mintlify format

A new Go-based post-processing tool (tools/docsmint) has been added to transform the vendor-neutral Markdown generated by the bd CLI into Mintlify-compatible MDX. This tool handles site-specific requirements such as converting HTML comments to JSX comments, rewriting relative links to extensionless routes, and updating the navigation array in docs/docs.json. It also includes a legacy compatibility layer to convert older Docusaurus-style pages and neutralizes lines starting with 'export' or 'import' to prevent MDX parsing failures.

tools/docsmint · high confidence

New dolt CLI discovery, version probing, and warning-only policy

The \internal/doltversion\ package now provides a hardened mechanism to locate and probe the external \dolt\ CLI used by managed proxied-server mode. It discovers the binary via a precedence chain (the \BEADS\_DOLT\_BIN\ environment variable, a sidecar config, or \PATH\), runs a bounded and memory-capped \dolt version\ probe, and enforces a recommended minimum version of 2.0.0. Instead of hard-failing on older or unverifiable versions, the system now emits a non-fatal advisory warning (deduplicated across processes for 24 hours) while still hard-failing on missing or broken binaries. A cross-process JSON cache speeds up repeated probes by skipping the subprocess fork when the binary fingerprint is unchanged.

internal/doltversion · high confidence

New embedded agent skill and template system for Beads integration

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

New extensible hook system for issue lifecycle events

Users can now define executable scripts in the \.beads/hooks/\ directory to run automatically after issue create, update, or close events. The system supports asynchronous execution with a 10-second per-hook timeout and process-group termination on Unix to prevent hung scripts from blocking the CLI. Hook output is captured and exposed via OpenTelemetry spans for observability. Execution is currently unsupported on js/wasm (with a warning) and has limited script support on Windows.

internal/hooks · high confidence

New integration test harness for multi-process server lifecycle and recovery scenarios

The \internal/testutil/integration\ package now provides shared infrastructure for integration tests, including a \ProcessRegistry\ that manages server process lifecycles (SIGTERM with 5-second escalation to SIGKILL), a \SubprocessRunner\ for compiling and executing test binaries (with Bazel-specific support via \BEADS\_TEST\_GO\_BINARY\), and a \StateCorruptor\ to simulate server state corruption (e.g., stale PIDs, truncated metadata) for testing recovery. A \Diagnostics\ collector automatically dumps relevant state files and process lists on test failure. These utilities are guarded by the \integration\ build tag and are only active when running with \--config=integration\.

internal/testutil/integration · high confidence

New internal atomic file write utility

Added the internal/atomicfile package, which provides a mechanism for writing files atomically by creating a temporary file in the same directory, fsyncing it, and then renaming it into place. This ensures that readers never see partial or truncated data, always seeing either the previous complete version or the new complete version. The package includes a Writer type for streaming writes and a WriteFile convenience function, along with comprehensive tests covering basic writes, overwrites, aborts, and concurrent access.

internal/atomicfile · high confidence

New internal markdown rendering package with terminal-aware styling and content preservation

The \internal/uimd\ package introduces a dedicated markdown renderer for CLI output that respects terminal capabilities, adapting ANSI color and hyperlink support based on environment settings. It fixes previous issues where shell globs (like \\*.txt\) were incorrectly interpreted as emphasis markers and where HTML-tag-shaped spans (like \\<placeholder\>\) were silently deleted by the underlying parser; the new renderer escapes these characters to preserve the original text. Additionally, it ensures the rendered body text matches the terminal's background brightness, preventing readability issues on light-mode terminals.

internal/uimd · high confidence

New internal metrics collection and background flusher subsystem

This change introduces the internal metrics package, which collects telemetry events and manages a background process to upload them. It adds a cache for the machine distinct ID to avoid slow platform probes on every invocation, implements a detached 'send-metrics' child process with strict environment pinning to prevent endpoint hijacking, and enforces queue bounds (TTL and size caps) to prevent disk exhaustion. The subsystem respects the DO\_NOT\_TRACK environment variable for opt-out and includes comprehensive tests for the cache, pruning logic, and process spawning/reaping.

internal/metrics · high confidence

New internal release version consistency checker

The repository now includes an internal Go-based tool (internal/versioncheck) that validates version consistency across release metadata surfaces. It checks that the canonical version in cmd/bd/version.go matches versions in Python (MCP pyproject.toml, \_\init\\_.py), JSON manifests (Claude, Codex, Copilot plugins, marketplace, npm package), Windows PE resources (winres.json), and XML manifests (manifest.xml). It also verifies version markers in .githooks scripts. This ensures that release version bumps are applied consistently across all integration points and prevents silent drift where some surfaces retain old versions.

internal/versioncheck · high confidence

New internal time-parsing library with layered relative-date support

The \internal/timeparsing\ package introduces a layered parser for relative date and time expressions, supporting compact durations (e.g., \+6h\, \-1d\, \+30min\), natural language inputs (e.g., \tomorrow\, \next monday\), and absolute formats (e.g., \2025-01-15\). The library normalizes all parsed timestamps to UTC and uses the \olebedev/when\ library for natural language parsing. This change adds the core parsing logic and associated tests, but does not expose new user-facing CLI flags or UI components in this location.

internal/timeparsing · high confidence

New migration-test harness for cross-era upgrade fidelity

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

New public format package for issue rendering

A new \format\ package has been added to provide public formatting functions for rendering beads issues. This allows consumers like the \gt\ tool to display issue output without depending on the internal \bd\ CLI. The package exposes functions to format issues in three views: \PrettyIssue\ for a standard one-line list, \CompactIssue\ for a detailed single-line view including assignees, labels, and dependencies, and \LongIssue\ for a full multi-line detail view. It also includes utilities for generating status icons, dependency information strings, and list summaries.

format · high confidence

New public schema package for database migrations

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 beads database over a standard \database/sql\ connection, including functions to check the latest and current schema versions, detect schema skew errors, and apply pending migrations with locking. The package is marked as EXPERIMENTAL and is not yet covered by the project's compatibility promise.

schema · high confidence

New rrc\_verify.py tool to validate Bazel remote repo contents cache integrity

Added a new Python script, tools/bazel/rrc\_verify.py, that verifies the integrity of Bazel's remote repo contents cache by comparing cached repository trees against cold fetches. This tool detects poisoned cache entries or incorrectly marked reproducible repositories by walking the action cache and comparing marker files and directory trees, ensuring that the cache skips only valid, reproducible work.

python · high confidence

New wire-shape drift gate for HTTP API contracts

A new internal package, \internal/httpapi/wireshape\, has been added to enforce backward compatibility of the HTTP API wire format. It computes a canonical digest of all response members, request-body members, and operation parameters (including serialization details like style and explode) from the OpenAPI specification. A CI test (\TestWireShapeDigest\) compares this digest against a committed golden file (\testdata/golden.json\), failing if any existing member or parameter changes type, format, enum, required-ness, nullability, or serialization style without a corresponding bump to \CurrentWireRevision\. This ensures that breaking changes to the HTTP contract are explicitly reviewed and versioned.

internal/httpapi/wireshape · high confidence

OSS HTTP client wire layer with credential rotation and connection resilience

The \internal/httpclient/wire\ package introduces the core transport layer for the OSS HTTP backend, ported from bd-enterprise under the MIT license. It provides a client that enforces workspace identity via a \Bd-Project-Id\ header, manages credential rotation with exactly one retry on 401 responses, and improves connection resilience by bounding response-header waits and retrying stalled reads on a new connection. The client also refuses HTTP redirects to prevent token leakage and caps response body sizes to prevent memory exhaustion.

internal/httpclient/wire · high confidence

Optional JSONL interaction audit trail

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

Pager support, terminal sanitization, and adaptive styling

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

Public HTTP backend for remote workspace connectivity

Users can now connect local workspaces to a remote \bd serve\ instance via the \bd connect\ command, which activates the new HTTP backend. This change introduces the \backend/http\ package, providing the \Attach\ and \Connect\ functions to handle workspace activation, server handshakes, and credential management (including per-open credentials). It also adds comprehensive end-to-end tests verifying that core CLI commands—such as \bd blocked\, \bd export\, \bd list\, and \bd gate\—function correctly over the HTTP connection against a served backend.

backend/http · high confidence

Public backend contract for out-of-tree storage implementations

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, and sentinel errors as aliases, ensuring that external implementations see identical types and that \errors.Is\ works across module boundaries. The package includes a registration mechanism (\Register\) for plugging in external backends and provides a conformance suite to verify that an implementation behaves correctly. This enables embedders to supply their own workspace-creation and storage logic while remaining compatible with the core system.

backend · high confidence

Support for external credential helpers with fail-closed resolution

The internal credential resolution system now includes a CommandSource that executes an external helper command to retrieve credentials, supporting standard formats like kubectl ExecCredential, AWS credential\_process, and bare tokens. This source is integrated into a priority-based resolution ladder that fails closed, meaning if a configured command helper fails, the system will not silently fall back to lower-priority sources like environment variables. The implementation includes process-level caching to avoid repeated command execution and handles platform-specific shell execution differences between POSIX and Windows.

internal/creds · high confidence

Two-level cooperative workspace and physical-root gate

A new internal workspace gate enforces cross-process coordination for workspace and physical-root operations. Normal commands acquire a shared lock for the lifetime of their store or provider, while maintenance operations (such as mode migration, restore, or destructive repair) acquire an exclusive lock to ensure no other work is active. The gate uses OS advisory locks placed in stable locations outside the gated directories to survive directory replacements, and includes fairness mechanisms so that exclusive maintenance requests are not starved by a stream of short-lived shared commands.

internal/workspacegate · high confidence

Removals

Removal of Beads CLI command modules

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

Architecture

Enforce architectural boundaries and deterministic builds via linting and build flags

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

Introduce internal/workapi as the shared query and operation contract

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

Behavioural changes

Automated enforcement of RBE worker environment pinning

Added a new synchronization toolchain to ensure the local RBE worker environment (tools/rbe/worker-env.txt and its platform pin) remains identical to the upstream gascity reference. The new worker-env-sync script compares the local pin against gascity's main branch and fails CI runs immediately if they diverge, while the worker-env-sync-issue script automatically opens or updates a tracked issue for nightly maintenance, preventing remote build actions from queuing on unserved workers.

tools/rbe · high confidence

Centralized config file handling and new server infrastructure

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

Default storage backend switched from SQLite to Dolt

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

Go linting and vetting now runs via nogo in Bazel

The repository has replaced external \go vet\ and \golangci-lint\ invocations with a unified \nogo\ target that executes during every Go compile. This change integrates standard vet passes (such as \printf\, \buildtag\, and \slog\) alongside specific linters including \depguard\, \errcheck\, \forbidigo\, \gosec\, \misspell\, \sloglint\, \unconvert\, and \unparam\. All checks are configured via the existing \.golangci.yml\ file, ensuring that exclusion rules, path-based exemptions, and settings are preserved. As a result, build failures will now immediately surface linting and vetting issues found in first-party code, while third-party modules and test fixtures remain excluded.

tools/nogo · high confidence

Improved Dolt remote URL normalization and canonicalization

The internal/doltremote package now provides stricter handling of remote URLs. It explicitly recognizes native Dolt schemes (such as s3://, aws://, and gs://) and ensures they are not incorrectly parsed as SCP-style git remotes, preventing corruption of URLs containing '@' in their paths. SCP-style URLs (like git@host:path) are consistently converted to the git+ssh:// format, including support for user-less dotted hosts. Additionally, CanonicalForComparison now folds host casing and strips embedded credentials to ensure reliable equality checks between different URL representations.

internal/doltremote · high confidence

Introduces per-store versioned history activation with deferred config reads

The \internal/versionedhistory\ package now controls whether issue-version history is recorded on a per-store basis, resolving a previous bug where the \bd config set\ command wrote to the database but the code read from environment/YAML, causing the feature to remain silently off. The switch is now a property of the store itself (read from the workspace config table) and is OR'd with the process-wide \BD\_VERSIONED\_HISTORY\_ENABLED\ environment variable. To improve performance, the read of the store's config setting is deferred until the first write transaction, avoiding unnecessary database reads for commands that only list or show data.

internal/versionedhistory · high confidence

New Git hooks enforce Go linting, version consistency, and Beads integration

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

Notion sync reimplementation with REST data sources and secure token handling

The Notion integration has been reimplemented to sync via REST data sources, introducing a new client that supports pagination, configurable query page limits, and Retry-After header respect. Authentication now prioritizes the \notion.token\ key in \config.yaml\ over legacy database storage or environment variables, ensuring the token is kept out of the Dolt database to prevent accidental replication. The sync logic also drops the \in\_trash\ field from data-source queries to resolve 400 errors, and includes a new field mapper and schema validation for the dedicated Notion beads schema.

internal/notion · high confidence

PreToolUse hooks block API rate-limiting commands and interactive file operations

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

Preserve CRLF line endings when appending to gitignore files

The gitignore module now includes helpers to detect and preserve the line-ending style (CRLF vs LF) of existing gitignore files when appending new rules. This ensures that users on Windows or those with CRLF-configured repositories will not see their line endings unexpectedly converted to LF when the tool modifies their .gitignore files, maintaining consistency with their existing file conventions.

internal/gitignore · high confidence

Prevent inherited file descriptors from leaking into spawned child processes

The new \internal/fdhygiene\ package ensures that file descriptors inherited from the parent process (such as locks held by CI harnesses or shell scripts) are not passed to long-lived children like the managed dolt sql-server. On Unix systems, the package scans open descriptors above standard I/O and marks them with the close-on-exec flag before spawning, preventing issues where a detached server incorrectly holds locks from the caller. On Windows, this is a no-op as handles are not inheritable by default. Tests verify that leaked descriptors are sanitized and that standard I/O remains unaffected.

internal/fdhygiene · high confidence

Startup performance: limit Go runtime parallelism during initialization

The application now temporarily limits the Go runtime's GOMAXPROCS to 4 during package initialization to reduce stop-the-world pauses caused by garbage collection on multi-core systems. This optimization shortens startup time (e.g., 'bd version') by avoiding expensive global GC cycles that occur when initializing many packages on all available CPUs. After initialization completes, the runtime's parallelism is restored to its original setting, ensuring normal execution performance is unaffected.

internal/initprocs · high confidence

Test infrastructure modernized with containerized Dolt servers and improved isolation

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

Third-party patches for Bazel bzlmod compatibility and pure-Go builds

This change introduces a new set of patches in third\_party/patches to resolve build issues when migrating to Bazel's bzlmod system and to support pure-Go (no-CGO) compilation. The patches modify dolt dependencies (dolt\_go\_serial, eventsapi\_schema\_build, flatbuffers\_v23) by stripping out WORKSPACE-era build targets (such as pkg\_tar and proto generation) that are incompatible with go\_deps, replacing them with pre-generated source libraries. Additionally, a patch for gozstd adds CGO-constrained stubs to prevent panics in pure-Go binaries, while patches for rules\_go and x\_tools enhance the nogo linter to correctly handle golangci-lint nolint directives and recognize standard library no-return functions.

_third\party/patches · high confidence

Tracker sync engine gains robust testing, rate-limit handling, and selective sync

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

Fixes

Centralized validation logic with improved ID prefix and actor identity handling

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

Fix foreign key constraint failures in AddComment and ApplyCompaction

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

Fix issue ID parsing and path canonicalization in internal/utils

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

Hermetic LLVM toolchain now uses a reproducible, members-only archive slice

The hermetic C/C++ toolchain in tools/cc\_toolchain now builds its LLVM distribution from a deterministic, members-only .tar.zst slice rather than extracting the full upstream release. A new repack\_llvm.sh script and llvm\_members.txt file define exactly which binaries and libraries (e.g., clang, lld, builtins) are included, ensuring reproducible builds and reducing CI download/extract overhead by only pulling the necessary components for the x86\_64-linux target.

_tools/cc\toolchain · high confidence

Improved Dolt server lifecycle management and configuration handling

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

Improved Git worktree and Jujutsu support with path normalization

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

Replace shell-based version checks with a Go implementation

The \scripts/check-versions\ tool is now implemented in Go (\main.go\) and built via Bazel (\BUILD.bazel\), replacing the previous shell-based approach. This change ensures consistent version validation across release surfaces and integrates with the pre-push hook, which now relies on the Go checker for drift detection and remedy guidance. The new implementation includes comprehensive tests (\main\_test.go\, \pre\_push\_hook\_test.go\) that verify version alignment, MCP uv.lock freshness, and correct behavior under system Bash, ensuring the hook works reliably on macOS and other environments.

scripts/check-versions · high confidence

Stabilizes Dolt push/fetch by disabling git hooks and scrubbing trace output

This change introduces two new internal packages, \githooksenv\ and \gittraceenv\, to prevent user environment settings from breaking Dolt operations that run git commands inside the application process. \githooksenv\ disables client-side git hooks (via \GIT\_CONFIG\_PARAMETERS\) to prevent pre-push hooks from failing when operating on bare repositories. \gittraceenv\ scrubs stderr-directed git tracing variables (like \GIT\_TRACE=1\) that would otherwise pollute the output buffer and cause fatal parsing errors during remote transfers. Both packages support nested and concurrent calls, ensuring that these environment modifications are temporary and safely restored.

internal/githooksenv · high confidence

Test coverage

Added Bazel test for git hook timeout backend compatibility; Added Bazel test infrastructure for historical migration upgrades; Added Bazel test targets for gitattributes policy validation; Added Bazel tests for PR lint and formatting scripts; Added Bazel-based upgrade smoke tests; Added HTTP corpus test suite for served command fidelity; Added Oracle A differential conformance test harness; Added Oracle A refactor-safety conformance tests; Added comprehensive test suite for beads-mcp integration; Added docsync guard tests to validate documentation integrity; Added integration tests for the npm package; Added portable credential-command test fixtures for shell-boundary testing; Added reproduction script for the 12-second slow path on bd commands; Added test to prevent TestMain cleanup leaks; Added tests to verify public embedder API stability; Comprehensive script-based integration tests for the bd CLI; Introduce Bazel-based testing and policy enforcement for repository scripts; 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; Pin command tree and representative --help output; Regression test suite for SQLite-to-Dolt migration with snapshot-based parity checks; Updated golden test fixtures for bd init and bd setup claude.

Dependencies

Add Go extension and library usage examples

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.

How this codebase got here

Score

  • CAI 69 → 69 (-0.1)

Lenses

  • Code Health 60 → 60 (-0.0)
  • Architecture 97 → 97 (-0.5)
  • Maturity 84 → 79 (-4.8)
  • Readiness 70 → 71 (+0.7)
  • Security 80 → 82 (+2.1)
  • Performance 87 → 87 (+0.0)

Resolved (161)

  • Critical CVE: [GHSA redacted] (integrations/beads-mcp/uv.lock)
  • Duplicated block (10 lines × 2) (backend/conformance/ready_claimer_contract.go)
  • Duplicated block (10 lines × 2) (cmd/bd/bootstrap.go)
  • Duplicated block (10 lines × 2) (cmd/bd/defer.go)
  • Duplicated block (10 lines × 2) (cmd/bd/doctor/fix/label_whitespace.go)
  • Duplicated block (10 lines × 2) (cmd/bd/gate_proxied_server.go)
  • Duplicated block (10 lines × 2) (scripts/ci/gen_proxied_shard_manifest.py)
  • Duplicated block (10 lines × 3) (cmd/bd/backend_support.go)
  • Duplicated block (10–12 lines × 2) (internal/storage/issueops/persistence.go)
  • Duplicated block (11 lines × 2) (cmd/bd/mol_proxied_server.go)
  • Duplicated block (12 lines × 2) (cmd/bd/mol_current.go)
  • Duplicated block (12–15 lines × 2) (internal/httpclient/bridge.go)
  • Duplicated block (12–17 lines × 2) (cmd/bd/doctor/claude.go)
  • Duplicated block (13 lines × 3) (scripts/ci/gen_embedded_cmd_shard_manifest.py)
  • Duplicated block (13–14 lines × 2) (cmd/bd/ready.go)
  • Duplicated block (13–14 lines × 2) (cmd/bd/store_factory.go)
  • Duplicated block (14 lines × 2) (cmd/bd/kv.go)
  • Duplicated block (14 lines × 2) (cmd/bd/setup/claude.go)
  • Duplicated block (14 lines × 5) (cmd/bd/assign.go)
  • Duplicated block (15–16 lines × 2) (internal/storage/dolt/dependencies.go)
  • …and 141 more

New (311)

  • ADR has no Consequences section (engdocs/adr/0003-provenance-event-log.md)
  • ADR has no Context section (engdocs/decisions/2026-07-10-mintlify-docs-overhaul.md)
  • ADR not followed: ADR-0001: Multi-Remote Approach (engdocs/adr/0001-multi-remote-approach.md)
  • ActionResult.decode (cognitive 17) (tools/bazel/rrc_verify.py)
  • ActionResult.decode (cyclomatic 17) (tools/bazel/rrc_verify.py)
  • Change coupling: doltserver_provider.go ↔ external_doltserver_provider.go (internal/storage/uow/doltserver_provider.go)
  • ClassTooLong: Store (internal/storage/externaldeps/decorator.go)
  • Client.roundTripOnce (cognitive 18) (internal/httpclient/wire/client.go)
  • Client.roundTripOnce (cyclomatic 16) (internal/httpclient/wire/client.go)
  • DoltStore.stageAndCommit (cognitive 19) (internal/storage/dolt/store.go)
  • Duplicated block (10 lines × 2) (cmd/bd/gate.go)
  • Duplicated block (10 lines × 2) (internal/doltserver/doltserver.go)
  • Duplicated block (10 lines × 2) (internal/httpclient/blockedlister.go)
  • Duplicated block (10 lines × 2) (internal/storage/dolt/epoch_cas.go)
  • Duplicated block (10 lines × 2) (internal/storage/externaldeps/batch_closer.go)
  • Duplicated block (10 lines × 3) (backend/conformance/blocked_lister_contract.go)
  • Duplicated block (10 lines × 3) (cmd/bd/setup/claude.go)
  • Duplicated block (11 lines × 2) (internal/storage/uow/notifying.go)
  • Duplicated block (11 lines × 2) (issueops/molecule.go)
  • Duplicated block (12 lines × 3) (cmd/bd/backend_support.go)
  • …and 291 more

Changes since last survey

  • 180 commits — 72 feature/other, 108 fixes

By area

  • cmd/bd — 84 commits
  • internal/storage — 30 commits
  • internal/httpclient — 14 commits
  • (root) — 11 commits
  • .github/workflows — 7 commits
  • backend/http — 6 commits
  • tests/oracle-a — 4 commits
  • tools/bazel — 4 commits
  • internal/config — 3 commits
  • internal/httpapi — 3 commits
  • scripts/bazel_dolt_int_test.go — 2 commits
  • .claude/skills — 1 commit
  • .github/actions — 1 commit
  • .github/scripts — 1 commit
  • examples/bd-example-extension-go — 1 commit
  • examples/library-usage — 1 commit
  • integrations/beads-mcp — 1 commit
  • internal/query — 1 commit
  • internal/utils — 1 commit
  • internal/workspacegate — 1 commit

Notable commits

  • fix: build(deps): Dolt 2.5.1 engine and pins + go-deps group, with compatibility fixes (#7646)
  • fix: fix(bazel): one nogo-validating lane per race configuration (F5 S1) (#7479)
  • fix: fix(bazel): re-vendor the BEP test-timing clamp from gascity (extractor 1.1.1) (#7477)
  • fix: fix(bazel): remove host-go dep from compact GC test; drop frozen shard blocks (#7478)
  • fix: fix(bazel): the root go_srcs glob skips Bazel's convenience symlinks, so //cmd/bd tests cache (#7714)
  • fix: fix(beads,storage): refuse an unsupported legacy config.json before writing (#7798)
  • fix: fix(beads-mcp): bump pyjwt to 2.15.1 and urllib3 to 2.8.0 for security advisories (#7466)
  • fix: fix(blocked): climb through a blocked parent with no reason row of its own (#7420)
  • fix: fix(bootstrap): clone through the Dolt port later commands dial (#7804)
  • fix: fix(bootstrap): cut the host part before stripping userinfo (mc-gcmer) (#7616)
  • fix: fix(build): build with Go 1.26.10 and uv 0.13.4 for the eMudhra CA distrust (#7732)
  • fix: fix(build): pair Darwin SDKs with the native Apple linker (#7460)
  • fix: fix(ci): never re-add the review label to an open worker-env sync PR (#7805)
  • fix: fix(ci-policy): close M19/M21 scanner gaps from #7491 review (#7492)
  • fix: fix(ci-policy): close review leftovers from #7485/#7486 (#7491)
  • fix: fix(cli): refuse backup init/sync/remove/restore and import under strict --readonly (#7673)
  • fix: fix(cli): refuse graph workspaces marked by graph-preview-format (#7722)
  • fix: fix(cli): refuse graph_mode workspaces and keep their metadata marker on save (#7671)
  • fix: fix(close): emit the --json failure report for a single refused id (bd-5yswb) (#7614)
  • fix: fix(cmd/bd): guarded close/update/assign that lose to a delete at pre-flight report precondition_failed (#7465)
  • …and 160 more

Architecture

  • Containers 0 added · 0 removed · contexts 1 added · 0 removed · edges 0 added · 0 removed

Added bounded contexts (1)

  • python

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

Survey your own repository

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.

About this page

  • The score is its most recent published measurement, taken on 24 October 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
  • Measured at commit ce8554ffb1bb7e70e2c04c739b11e72780cb9901 — the exact code this score is about.
  • Scored under rubric-2026.10.5 — the same rubric and the same method as every other entry in this index.
  • Measured by watchdog.canine.dev using codehealth-analyzer measure-2026.10.6+preprod-d36780c2d857.