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