ADR Records

Published Architecture and Development Decision Records for this project.

This page and linked ADR pages are generated from docs/decisions/*.yaml by task docs:export-adr-markdown.

• Total ADRs: 87
• Accepted ADRs: 76

ADR List

• ADR 001: Go as primary implementation language (architecture, accepted)
• ADR 002: Taskfile for development automation (development, accepted)
• ADR 003: AI agents as first-class developers (development, accepted)
• ADR 004: Live integration tests as primary correctness gate (development, accepted)
• ADR 005: Minimum coverage and integration testing policy (development, superseded)
• ADR 006: Conventional commits with hook enforcement (development, accepted)
• ADR 007: Manual GitHub release workflow (development, superseded)
• ADR 008: Layered Go architecture and package boundaries (architecture, accepted)
• ADR 009: Transport policy for Bitbucket API calls (architecture, accepted)
• ADR 010: Go model validation and schema export (architecture, accepted)
• ADR 011: Error taxonomy and CLI exit contract (architecture, accepted)
• ADR 012: Git backend abstraction for repository operations (architecture, accepted)
• ADR 013: CLI framework and command tree standard (architecture, accepted)
• ADR 014: Output contract for human and machine modes (architecture, superseded)
• ADR 015: Live test harness and deterministic seeding (development, accepted)
• ADR 016: Test classification and execution policy (development, accepted)
• ADR 017: Undocumented behavior registry via live tests (development, accepted)
• ADR 018: Supported Bitbucket version policy (architecture, superseded)
• ADR 019: Configuration and secret handling policy (development, accepted)
• ADR 020: Execgit as default Git backend (architecture, accepted)
• ADR 021: Persistent auth configuration and keyring storage (architecture, accepted)
• ADR 022: Auth mode priority and token-first policy (architecture, accepted)
• ADR 023: Long-term planning via GitHub issues (development, accepted)
• ADR 024: Use .tmp directory for agent temporary files (development, accepted)
• ADR 025: Git discipline and branch management (development, accepted)
• ADR 026: PR readiness and auto-merge criteria (development, accepted)
• ADR 027: Atlassian 9.4 docs as API reference source (architecture, superseded)
• ADR 028: OpenAPI fix registry and parity enforcement (development, accepted)
• ADR 029: Network Isolation during Unit Testing (development, accepted)
• ADR 030: Linear rebase workflow with generated coverage artifacts (development, superseded)
• ADR 031: Top-level search command tree for discovery (architecture, accepted)
• ADR 032: Refactor CLI root into command packages (architecture, accepted)
• ADR 033: Automated Conventional Commit release on main (development, accepted)
• ADR 034: Unified dry-run planning engine for server mutating commands (architecture, accepted)
• ADR 035: Dry-run capability signaling and test strategy policy (development, superseded)
• ADR 036: CLI identity bb and BB namespace (architecture, accepted)
• ADR 037: Versioned docs via MkDocs Material and mike (development, accepted)
• ADR 038: bb ai subcommand as AI-first tooling namespace (architecture, accepted)
• ADR 039: Built-in MCP server with explicit host scoping and token capability restriction (architecture, accepted)
• ADR 040: Agent skill distribution via static npx packaging and dynamic CLI generation (development, accepted)
• ADR 041: Host aliases and clone URL discovery for server contexts (architecture, accepted)
• ADR 042: Track the newest containerisable Bitbucket version (architecture, accepted)
• ADR 043: Provision the live test instance with the Atlassian Plugin SDK (architecture, accepted)
• ADR 044: Supply git credentials through a credential helper rather than persisting them (architecture, accepted)
• ADR 045: Compute coverage measurements, commit only verifiable baselines (development, accepted)
• ADR 046: Emit a JSON error envelope on the failure path (architecture, accepted)
• ADR 047: Credential input paths and enforceable keyring storage (architecture, accepted)
• ADR 048: Documented commands are validated against the command tree (development, accepted)
• ADR 049: Build tooling stays outside the coverage gate but not outside testing (development, accepted)
• ADR 050: Frequently-used commands get a shallow alias, and the deep path stays canonical (architecture, accepted)
• ADR 051: bb does not manage server-side hooks (architecture, accepted)
• ADR 052: Layer-boundary testing policy and HTTP mock elimination (development, superseded)
• ADR 053: Raw API escape hatch for uncovered endpoints and version gaps (architecture, accepted)
• ADR 054: Strict non-interactive CLI contract and fail-fast validation invariant (architecture, superseded)
• ADR 055: Documented release versions are validated and synchronized (development, superseded)
• ADR 056: Pull request reviewer automation, default reviewers, and CODEOWNERS (architecture, accepted)
• ADR 057: Documented release version is injected at build time (development, accepted)
• ADR 058: System-wide configuration and administrative policy enforcement (architecture, accepted)
• ADR 059: Enterprise update controls and release mirror support (architecture, accepted)
• ADR 060: Mutual TLS (mTLS) client certificate authentication (architecture, accepted)
• ADR 061: The MCP surface runs on the official SDK and every tool names its payload (architecture, accepted)
• ADR 062: The MCP server can be confined to a workspace, and records what agents attempt there (architecture, accepted)
• ADR 063: Offline release signature verification and update trust policy (architecture, accepted)
• ADR 064: Machine output carries no contract version; breaking payload changes ride the release major (architecture, accepted)
• ADR 065: What the quality apparatus measures, and why each part exists (development, accepted)
• ADR 066: Every change integrates on next, and only main releases (development, accepted)
• ADR 067: Governance tests are verified by breaking them (development, accepted)
• ADR 068: The vendored API reference is derived from the harness release (architecture, accepted)
• ADR 069: Dependabot updates merge themselves, except where held for a person (development, accepted)
• ADR 070: Every command is explicitly classified for dry-run, and unknown means refuse (architecture, accepted)
• ADR 071: Tests must not reconfigure the repository they run in (development, accepted)
• ADR 072: Interactivity is decided in one place, and the escape hatch costs nothing per call (architecture, accepted)
• ADR 073: Interactive when a person is there, explicit when not (architecture, accepted)
• ADR 074: A service takes a cap, never a page size (architecture, accepted)
• ADR 075: A machine-mode command emits one document, and a failed run is named by its id (architecture, accepted)
• ADR 076: Machine output field names are camelCase, matching the Bitbucket API (architecture, accepted)
• ADR 077: Comment endpoints are views, not collections (architecture, accepted)
• ADR 078: Dry-run confidence is derived from a tier, not written by the author (development, accepted)
• ADR 079: Unit tests do not simulate Bitbucket (development, accepted)
• ADR 080: Bitbucket resolves CODEOWNERS, not bb (architecture, accepted)
• ADR 081: An issue closes when its fix ships, not when it merges (development, proposed)
• ADR 082: A unit test process inherits nothing (development, accepted)
• ADR 083: No flag carries a secret (architecture, accepted)
• ADR 084: A removed flag warns for one major before it stops working (architecture, accepted)
• ADR 085: A test fixture is named at random, not from the clock (development, accepted)
• ADR 086: bb doctor reports the configuration without loading it (architecture, accepted)
• ADR 087: Quoted messages are checked against the source that prints them (development, accepted)