From 0773e6334e7ee1db0d069ae0c9befd4a7c7e4bba Mon Sep 17 00:00:00 2001 From: Julian Knutsen Date: Mon, 5 Oct 2026 01:43:53 -0700 Subject: [PATCH] docs(agents): contributor-only agent instructions and documented-issue intake (#7223) Makes the repo's agent and contributor surface describe developing beads, not using bd, and requires every PR to link a documented issue. - Contributor-only root AGENTS.md with a routing table; cmd/bd/AGENTS.md and engdocs/AGENTS.md seam files; CLAUDE.md symlinks so Claude Code loads nested files. - Bug and feature issue forms, a PR template that requires Closes #, CONTRIBUTING sections for the triage and pipeline labels, and the opt-in fork-cache during dev setup. - ROADMAP.md for 1.4: versioned beads (#6132), Graph Preview 2 (#7170), contributor onboarding (#7228). - docsync guards: root AGENTS.md at or under 20 KB; every AGENTS.md symlinked, routed, and with resolving links, paths, and guard-test names. Agent-Signature: claude-code-claude-opus-5-5-high on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 (1M context) --- .../beads-docs/references/terminology.md | 2 +- .../beads-docs/references/verification.md | 2 +- .claude/test-strategy.md | 103 ---- .github/ISSUE_TEMPLATE/bug_report.yml | 94 +++ .github/ISSUE_TEMPLATE/config.yml | 11 + .github/ISSUE_TEMPLATE/feature_request.yml | 108 ++++ .github/PULL_REQUEST_TEMPLATE.md | 23 +- .github/copilot-instructions.md | 147 +---- .github/workflows/docs-mintlify.yml | 4 + AGENTS.md | 409 +++++-------- AGENT_INSTRUCTIONS.md | 542 +----------------- BUILD.bazel | 2 + CLAUDE.md | 24 +- CONTRIBUTING.md | 94 ++- README.md | 3 +- ROADMAP.md | 69 +++ cmd/bd/AGENTS.md | 122 ++-- cmd/bd/BUILD.bazel | 7 + cmd/bd/CLAUDE.md | 1 + docs/integrations/github-copilot.md | 2 +- docs/reference/faq.md | 19 + engdocs/AGENTS.md | 45 ++ engdocs/CLAUDE.md | 94 +-- engdocs/DOC_INVENTORY.md | 2 +- engdocs/TESTING.md | 6 + engdocs/UI_PHILOSOPHY.md | 107 ++++ internal/storage/schema/BUILD.bazel | 6 + scripts/check-doc-flags.sh | 6 +- test/docsync/BUILD.bazel | 1 + test/docsync/agentfiles_test.go | 214 +++++++ test/docsync/docsync_test.go | 1 + tools/bazel/equivalence_allowlist.txt | 1 + 32 files changed, 1041 insertions(+), 1230 deletions(-) delete mode 100644 .claude/test-strategy.md create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml mode change 100644 => 120000 CLAUDE.md create mode 100644 ROADMAP.md create mode 120000 cmd/bd/CLAUDE.md create mode 100644 engdocs/AGENTS.md mode change 100644 => 120000 engdocs/CLAUDE.md create mode 100644 test/docsync/agentfiles_test.go diff --git a/.claude/skills/beads-docs/references/terminology.md b/.claude/skills/beads-docs/references/terminology.md index 3718007bd..e3f46d5dc 100644 --- a/.claude/skills/beads-docs/references/terminology.md +++ b/.claude/skills/beads-docs/references/terminology.md @@ -8,7 +8,7 @@ the binary still prints, the docs now lie. ## The discipline 1. **Survey first.** Count occurrences in `docs/`, `engdocs/`, `README.md`, - `AGENTS.md`, `AGENT_INSTRUCTIONS.md`, and `*.go`. Read enough to tell + every `AGENTS.md` (root and nested), and `*.go`. Read enough to tell *prose* (the concept) from *literals*. 2. **Rename prose only**, with judgment per occurrence — fix articles and grammar so it reads naturally. diff --git a/.claude/skills/beads-docs/references/verification.md b/.claude/skills/beads-docs/references/verification.md index 762154ce5..559bfb6f3 100644 --- a/.claude/skills/beads-docs/references/verification.md +++ b/.claude/skills/beads-docs/references/verification.md @@ -55,7 +55,7 @@ all of: 1. **Redirect** — add an entry to the `redirects` array in `docs/docs.json` from the old route to the new one. 2. **Rewrite inbound links** — grep the whole repo, not just `docs/`: - README.md, AGENTS.md, AGENT_INSTRUCTIONS.md, engdocs/, examples/, + README.md, every AGENTS.md (root and nested), engdocs/, examples/, npm-package/, plugins/, integrations/, scripts, and Go comments. 3. **Check bd's printed output** — if `bd` prints the old path (grep `cmd/` and `internal/templates/` for it), fix the Go source to print the new diff --git a/.claude/test-strategy.md b/.claude/test-strategy.md deleted file mode 100644 index 3b3709ec5..000000000 --- a/.claude/test-strategy.md +++ /dev/null @@ -1,103 +0,0 @@ -# Test Running Strategy for Claude Code - -## Critical Rules - -1. **ALWAYS use `./scripts/test.sh` instead of `go test` directly** - - It automatically skips broken tests from `.test-skip` - - Uses appropriate timeouts (3m default) - - Consistent with human developers and CI/CD - -2. **Use `-run` to target specific tests when developing features** - ```bash - # Good: When working on feature X - ./scripts/test.sh -run TestFeatureX ./cmd/bd/... - - # Avoid: Running full suite unnecessarily - ./scripts/test.sh ./... - ``` - -3. **Understand the bottleneck: COMPILATION not EXECUTION** - - 180s compilation time vs 3.8s actual test execution (cmd/bd) - - Running subset of tests doesn't save much time (still recompiles) - - But use `-run` anyway to avoid seeing unrelated failures - -## Common Commands - -```bash -# Full test suite (what 'make test' runs) -./scripts/test.sh - -# Test specific package -./scripts/test.sh ./cmd/bd/... -./scripts/test.sh ./internal/storage/embeddeddolt/... - -# Test specific feature -./scripts/test.sh -run TestCreate ./cmd/bd/... -./scripts/test.sh -run TestImport - -# Verbose output (when debugging) -./scripts/test.sh -v -run TestSpecificTest -``` - -## When Tests Fail - -1. **Check if it's a known broken test:** - ```bash - cat .test-skip - ``` - -2. **If it's new, investigate:** - - Read the test failure message - - Run with `-v` for more detail - - Check if recent code changes broke it - -3. **If unfixable now:** - - File GitHub issue with details - - Add to `.test-skip` with issue reference - - Document in commit message - -## Package Size Context - -The `cmd/bd` package is LARGE: -- 41,696 lines of code -- 205 files (82 test files) -- 313 individual tests -- Compilation takes ~180 seconds - -This is why: -- Compilation is slow -- Test script uses 3-minute timeout -- Targeting specific tests is important - -## Environment Variables - -Use these when needed: - -```bash -# Custom timeout -TEST_TIMEOUT=5m ./scripts/test.sh - -# Verbose by default -TEST_VERBOSE=1 ./scripts/test.sh - -# Run pattern -TEST_RUN=TestSomething ./scripts/test.sh -``` - -## Quick Reference - -| Task | Command | -|------|---------| -| Run all tests | `make test` or `./scripts/test.sh` | -| Test one package | `./scripts/test.sh ./cmd/bd/...` | -| Test one function | `./scripts/test.sh -run TestName` | -| Verbose output | `./scripts/test.sh -v` | -| Custom timeout | `./scripts/test.sh -timeout 10m` | -| Skip additional test | `./scripts/test.sh -skip TestFoo` | - -## Remember - -- The test script is in `.gitignore` path: `scripts/test.sh` -- Skip list is in repo root: `.test-skip` -- Full documentation: `engdocs/TESTING.md` -- Current broken tests: See GH issues #355, #356 diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 000000000..ab0b6b7f5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,94 @@ +name: Bug report +description: Report broken behavior in bd. +title: "bug: " +body: + - type: markdown + attributes: + value: | + Thanks for the report. This issue is the record a fix PR links to, so the more evidence here, the better. You can open a fix PR right away; no approval is needed first. + + **Agents filling in this form:** answer each question only from evidence you have. If you cannot answer a question from the evidence, write exactly `NOT_ENOUGH_INFO` instead of guessing. + + - type: checkboxes + id: checks + attributes: + label: Before you continue + options: + - label: I searched existing issues and did not find a duplicate. + required: true + - label: I reproduced this with stock `bd`, without an orchestrator or agent framework in the loop. + required: false + + - type: textarea + id: summary + attributes: + label: Summary + description: What is broken, in one or two sentences. + validations: + required: true + + - type: textarea + id: repro + attributes: + label: Steps to reproduce + description: Exact commands, starting from a fresh directory where possible. + render: shell + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual behavior + description: Include the full error output. + validations: + required: true + + - type: input + id: version + attributes: + label: bd version + description: Output of `bd version`. + validations: + required: true + + - type: dropdown + id: mode + attributes: + label: Storage mode + options: + - Embedded (default `bd init`) + - Server mode (`bd init --server`) + - Proxied server + - Not sure + validations: + required: true + + - type: input + id: os + attributes: + label: Operating system + placeholder: "macOS 15.5 (arm64), Ubuntu 24.04, Windows 11, ..." + validations: + required: true + + - type: textarea + id: impact + attributes: + label: Impact + description: Who is affected, how severe it is (data loss, blocked, workaround exists), and how often it happens. + validations: + required: true + + - type: textarea + id: context + attributes: + label: Additional context + description: Logs, `bd doctor` output, root-cause notes, or a proposed fix. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..f2904a2bb --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: Documentation + url: https://beads.gascity.com/ + about: Installation, concepts, CLI reference, and troubleshooting. + - name: Questions and ideas + url: https://github.com/gastownhall/beads/discussions + about: Ask usage questions or float an idea before it is ready to be an issue. + - name: Security vulnerability + url: https://github.com/gastownhall/beads/security/policy + about: Report security issues privately, never in a public issue. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 000000000..b850c6595 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,108 @@ +name: Feature request +description: Propose a change to bd, with the information needed to accept it. +title: "feat: " +body: + - type: markdown + attributes: + value: | + Every PR links a documented issue, and this form collects the context reviewers and future readers need. You can open your PR right after filing; no approval is needed first. Read the [project charter](https://github.com/gastownhall/beads/blob/main/engdocs/PROJECT_CHARTER.md) first — beads owns issue-tracking primitives, not orchestration policy or storage-engine behavior. + + **Agents filling in this form:** answer each question only from evidence you have. If you cannot answer a question from the evidence, write exactly `NOT_ENOUGH_INFO` instead of guessing. + + - type: checkboxes + id: checks + attributes: + label: Before you continue + options: + - label: I searched existing issues and pull requests and did not find a duplicate. + required: true + + - type: textarea + id: motivation + attributes: + label: Motivation + description: The problem, and who has it. Describe the pain, not the implementation you prefer. + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed change + description: The behavior, command, flag, or API you want. + validations: + required: true + + - type: textarea + id: impact + attributes: + label: Impact + description: Who is affected and how — users, agents, integrations, downstream consumers of the `--json` output. + validations: + required: true + + - type: textarea + id: risk + attributes: + label: Risk and compatibility + description: Schema or migration changes, wire or `--json` output changes, behavior changes for existing workspaces, and how to roll back. + validations: + required: true + + - type: textarea + id: verification + attributes: + label: Verification plan + description: How we will know it works end to end, beyond unit tests. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Current workarounds, issue metadata, an integration or plugin, or other designs. + + - type: dropdown + id: size + attributes: + label: Estimated size + options: + - XS (under 50 lines) + - S (under 200 lines) + - M (under 500 lines) + - L (under 1,000 lines) + - XL (more than 1,000 lines; likely needs splitting) + - Not sure + validations: + required: true + + - type: dropdown + id: intent + attributes: + label: Intent + options: + - I am opening or will open a PR + - I'm reporting the need; someone else would implement it + validations: + required: true + + - type: dropdown + id: ai + attributes: + label: AI assistance + description: Was an AI agent used to draft this issue? + options: + - "No" + - Yes, partly + - Yes, mostly + validations: + required: true + + - type: checkboxes + id: accountability + attributes: + label: Accountability + options: + - label: A human has read this issue and stands behind it. + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 540ff9950..a689ae380 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,16 +1,23 @@ -## What +Closes # - +## What changed -## Why + - +## Evidence it works -## Verification + - +## Checklist + +- [ ] The linked issue documents the problem (reproduction or motivation, impact, risk). +- [ ] Tests and lint selected per `engdocs/TESTING.md` pass locally. +- [ ] User-facing behavior changes are reflected in `docs/` or the generated CLI reference. +- [ ] If an invariant or rule changed, the owning `AGENTS.md` is updated. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 00a9b016f..7cd6744a5 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,138 +1,15 @@ -# GitHub Copilot Instructions for Beads +# GitHub Copilot instructions for beads -## Project Overview +The canonical contributor instructions for this repository are in +[AGENTS.md](../AGENTS.md); area-specific rules are in the nested `AGENTS.md` +files listed in its routing table. Read those, not this file, for workflow, +build, test, and scope rules. -**beads** (command: `bd`) is a Dolt-powered issue tracker designed for AI-supervised coding workflows. Git integration is optional. We dogfood our own tool for all task tracking. +The rules most often missed in review: -**Key Features:** -- Dependency-aware issue tracking -- Auto-sync via Dolt-native replication -- AI-optimized CLI with JSON output -- Dolt server mode for background operations -- MCP server integration for Claude and other AI assistants - -## Tech Stack - -- **Language**: Go 1.21+ -- **Storage**: Dolt (version-controlled SQL database) -- **CLI Framework**: Cobra -- **Testing**: Go standard testing + table-driven tests -- **CI/CD**: GitHub Actions -- **MCP Server**: Python (integrations/beads-mcp/) - -## Coding Guidelines - -### Testing -- Always write tests for new features -- Use `t.TempDir() in Go tests` to avoid polluting production database -- Run `go test -short ./...` before committing -- Never create test issues in production DB (use temporary DB) - -### Code Style -- Run `make ci-pr-lint` before committing changes to Go or lint-controlled files -- Follow existing patterns in `cmd/bd/` for new commands -- Add `--json` flag to all commands for programmatic use -- Update docs when changing behavior - -### Git Workflow -- Install git hooks: `bd hooks install` -- Use `bd dolt push` / `bd dolt pull` for remote sync -- Before implementing related work, opening a PR, or merging/closing a PR, run: - `scripts/pr-preflight.sh --search "" --repo gastownhall/beads` or - `scripts/pr-preflight.sh --repo gastownhall/beads` -- External contributor PRs have priority: build on them when possible, preserve - tests and attribution, and never close or replace them silently. - -## Issue Tracking with bd - -**CRITICAL**: This project uses **bd** for ALL task tracking. Do NOT create markdown TODO lists. - -### Essential Commands - -```bash -# Find work -bd ready --json # Unblocked issues -bd stale --days 30 --json # Forgotten issues - -# Create and manage (ALWAYS include --description) -bd create "Title" --description="Detailed context" -t bug|feature|task -p 0-4 --json -bd update --claim --json -bd close --reason "Done" --json - -# Search -bd list --status open --priority 1 --json -bd show --json - -# Sync (if remote configured) -bd dolt push # Push to Dolt remote -bd dolt pull # Pull from Dolt remote -``` - -### Workflow - -1. **Check ready work**: `bd ready --json` -2. **Claim task**: `bd update --claim` -3. **Work on it**: Implement, test, document -4. **Discover new work?** `bd create "Found bug" --description="What was found and why" -p 1 --deps discovered-from: --json` -5. **Complete**: `bd close --reason "Done" --json` -6. **Sync**: `bd dolt push` (push to Dolt remote if configured) - -**IMPORTANT**: Always include `--description` when creating issues. Issues without descriptions lack context for future work. - -### Priorities - -- `0` - Critical (security, data loss, broken builds) -- `1` - High (major features, important bugs) -- `2` - Medium (default, nice-to-have) -- `3` - Low (polish, optimization) -- `4` - Backlog (future ideas) - -## Project Structure - -``` -beads/ -├── cmd/bd/ # CLI commands (add new commands here) -├── internal/ -│ ├── types/ # Core data types -│ └── storage/ # Storage layer -│ └── dolt/ # Dolt implementation -├── integrations/ -│ └── beads-mcp/ # MCP server (Python) -├── examples/ # Integration examples -├── docs/ # Documentation -└── .beads/ - └── dolt/ # Dolt database (source of truth) -``` - -## Available Resources - -### MCP Server (Recommended) -Use the beads MCP server for native function calls instead of shell commands: -- Install: `pip install beads-mcp` -- Functions: `mcp__beads__ready()`, `mcp__beads__create()`, etc. -- See `integrations/beads-mcp/README.md` - -### Scripts -- `./scripts/bump-version.sh --commit` - Update all version files atomically -- `./scripts/release.sh ` - Complete release workflow -- `./scripts/update-homebrew.sh ` - Update Homebrew formula - -### Key Documentation -- **AGENTS.md** - Comprehensive AI agent guide (detailed workflows, advanced features) -- **AGENT_INSTRUCTIONS.md** - Development procedures, testing, releases -- **README.md** - User-facing documentation -- **docs/CLI_REFERENCE.md** - Complete command reference - -## Important Rules - -- ✅ Use bd for ALL task tracking -- ✅ Always use `--json` flag for programmatic use -- ✅ Use `bd dolt push` / `bd dolt pull` for remote sync -- ✅ Test with `t.TempDir() in Go tests` -- ❌ Do NOT create markdown TODO lists -- ❌ Do NOT create test issues in production DB -- ❌ Do NOT manually modify `.beads/dolt/` - ---- - -**For detailed workflows and advanced features, see [AGENTS.md](../AGENTS.md)** +- A PR must close a documented GitHub issue (filed before or alongside it). +- Build with `make install`, never `go build -o bd ./cmd/bd` or `go install ./cmd/bd`. +- `make ci-pr-lint` must pass with zero issues; choose tests with + [engdocs/TESTING.md](../engdocs/TESTING.md). +- Never create test issues in a production database; use `t.TempDir()`. +- CLI output uses small Unicode status symbols, never emoji icons. diff --git a/.github/workflows/docs-mintlify.yml b/.github/workflows/docs-mintlify.yml index 08f430798..6c4d7d953 100644 --- a/.github/workflows/docs-mintlify.yml +++ b/.github/workflows/docs-mintlify.yml @@ -19,6 +19,10 @@ on: - 'CLAUDE.md' - 'RELEASING.md' - 'PR_MAINTAINER_GUIDELINES.md' + - 'ROADMAP.md' + - '**/AGENTS.md' + - '**/CLAUDE.md' + - '.github/copilot-instructions.md' - '.github/scripts/docs-render-check.sh' - '.github/workflows/docs-mintlify.yml' diff --git a/AGENTS.md b/AGENTS.md index 18a5847d5..a0cec3a42 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,290 +1,191 @@ -# Agent Instructions +# Beads — Contributor Agent Instructions - +This file is for agents and humans **developing beads** (`bd`). If you are +using `bd` to track work in your own project, read the user docs instead: +[docs site](https://beads.gascity.com/) and +[IDE and agent setup](docs/getting-started/ide-setup.md). -See [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for full instructions. + -This file exists for compatibility with tools that look for AGENTS.md. +Nested `AGENTS.md` files hold area-specific rules; the routing table at the +end lists them. `CLAUDE.md` files are symlinks to their sibling `AGENTS.md`. -The marker above tells `bd doctor` that the intentional divergence between -this file and `CLAUDE.md` (different audiences, different reading orders) is -expected and should not be flagged. +## How work flows here -## Key Sections +GitHub Issues is the public tracker, and every PR links a documented issue. +The issue carries the context reviewers and future readers need: for a bug, +the reproduction, impact, and evidence; for a change, the motivation, impact, +risk, and verification plan. -- **Issue Tracking** - How to use bd for work management -- **Development Guidelines** - Code standards and testing -- **Project Scope** - Read [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding new feature surface area -- **Visual Design System** - Status icons, colors, and semantic styling for CLI output -- **Contributor Protection** - Read [CONTRIBUTING.md](CONTRIBUTING.md) before handling external PRs -- **Maintainer PR Guidelines** - Read [PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md) before triaging, landing, or closing PRs +1. Find or file the issue with the bug or feature form. It does not need + maintainer approval first; file it before or alongside the PR. +2. Work on a branch, open a PR against `main` whose body says + `Closes #`, and let CI and review run. +3. Maintainers triage issues with `status/needs-triage`, `status/needs-info`, + `status/needs-repro`, `status/needs-design`, and `status/accepted` + (confirmed); see [CONTRIBUTING.md](CONTRIBUTING.md). -## Project Scope +Maintainers also keep an internal bd ledger. It is optional for contributors +and not a substitute for the GitHub issue. -Before adding new feature surface area, read -[engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md). Beads owns issue tracking -primitives and should not encode orchestration-layer policy, become a storage -engine, or casually expand the database schema when metadata would work. +## Agent contribution policy -## PR Safety for Agents +- Every PR closes a documented issue. If none exists for your change, file + one with the bug or feature form fields, filling each from evidence and + answering `NOT_ENOUGH_INFO` where the evidence runs out, then link it from + the PR. +- A human reviews and stands behind every issue and PR an agent drafts. + Evidence that the change works end-to-end is required; "unit tests pass" + alone is not evidence. +- Before implementing work, opening a PR, or merging/closing a PR, run the PR + preflight: + ```bash + scripts/pr-preflight.sh --search "" --repo gastownhall/beads + scripts/pr-preflight.sh --repo gastownhall/beads + ``` + The preflight is the agent gate for PR handling; do not rely on + auto-discovery of CONTRIBUTING.md. +- Use `gh` for GitHub issues and PRs, not browser tools. Write PR, issue, + comment, and review bodies to a file, run `scripts/gh-body-lint `, + and pass the file with `gh ... --body-file`. Sign agent-written GitHub + comments and reviews per [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md). -Before triaging, reviewing, landing, closing, or otherwise maintaining PRs, read +## Contributor protection + +External contributor PRs have priority. Read [CONTRIBUTING.md](CONTRIBUTING.md) +— it contains promises we've made to contributors — and, before triaging, +reviewing, landing, closing, or otherwise maintaining PRs, [PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The maintainer policy is to maximize community throughput: find useful contributor value, absorb or transform it locally when practical, preserve attribution, and use request-changes only as a last resort. -Before implementing work, opening a PR, or merging/closing a PR, run the PR -preflight: -```bash -scripts/pr-preflight.sh --search "" --repo gastownhall/beads -scripts/pr-preflight.sh --repo gastownhall/beads -``` +Before implementing any feature or fix, check for existing open PRs on the +same topic. If one exists: -External contributor PRs have priority. Review and build on their branch when -possible, preserve their tests and attribution, and never close or supersede -their PR silently. If a rewrite is unavoidable, explain why on the original PR -and credit their design/tests. +1. **Review it first** — read the diff, understand the approach. +2. **Build on their work, don't rewrite it** — check out their branch, + fix/adapt as needed. +3. **Preserve their tests** — keep them unless they're wrong. +4. **Attribute properly** — `Co-authored-by:` in commits, reference their PR. +5. **Never close or supersede their PR silently.** If a rewrite is + unavoidable, explain why on the original PR and credit their design/tests. -## Visual Design Anti-Patterns +## Scope: where a change belongs -**NEVER use emoji-style icons** (🔴🟠🟡🔵⚪) in CLI output. They cause cognitive overload. +Read [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding +feature surface area. Beads owns issue tracking primitives and should not +encode orchestration-layer policy, become a storage engine, or casually expand +the database schema when metadata would work. Prefer, in order: issue +metadata over new fields, a flag on an existing command over a new command, +an integration or plugin over core, and leave orchestration policy to the +orchestration layer. -**ALWAYS use small Unicode symbols** with semantic colors (status uses symbols; priority uses labels): -- Status: `○ ◐ ● ✓ ❄` -- Priority: `P0`–`P4` label with color (no status glyph) +**Storage boundary.** Beads talks to storage through a driver interface +(`dolthub/driver` for Dolt). Do not add beads-side flocks, engine +introspection, storage-specific retry or crash-recovery logic, or public SDK +return types that leak driver internals. If the boundary is too narrow, widen +the interface or route the issue to the driver instead of patching around it +in beads. `bd doctor` support for embedded mode is enabled one subcommand at a +time, each human-vetted (GH#3794): do not lift the embedded-mode gate in +`cmd/bd/doctor.go` wholesale, and keep database-layer checks and fixes +server-gated until the driver interface covers them. -See [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for full development guidelines. +**Layering.** Schema → `internal/storage/issueops` → `cmd/bd`. Add new +primitives at the lowest layer first, one layer per PR, stacked when a fix +spans layers. See +[CONTRIBUTING_PR_GUIDELINES.md](CONTRIBUTING_PR_GUIDELINES.md). -## Storage Boundary - -The canonical storage boundary is in -[engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md#storage-boundary). In short: -Beads talks to storage through a driver interface (`dolthub/driver` for Dolt). -Do not add beads-side flocks, engine introspection, storage-specific retry or -crash-recovery logic, or public SDK return types that leak driver internals. -If the boundary is too narrow, widen the interface or route the issue to the -driver instead of patching around it in beads. - -A live application of this rule: `bd doctor` support for embedded mode is -enabled one subcommand at a time, each human-vetted (GH#3794). Do not lift the -embedded-mode gate in `cmd/bd/doctor.go` wholesale, and keep database-layer -checks and fixes server-gated until the driver interface covers them. - -## Agent Warning: Interactive Commands - -**DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use. - -Use `bd update` with flags instead: -```bash -bd update --description "new description" -bd update --title "new title" -bd update --design "design notes" -bd update --append-notes "additional notes" # --notes replaces existing notes and requires --force once notes are set -bd update --acceptance "acceptance criteria" - -# Use stdin for descriptions with special characters (backticks, !, nested quotes) -echo 'Description with `backticks` and "quotes"' | bd create "Title" --description=- -echo 'Updated text' | bd update --description=- -``` - -## Testing - -Use [engdocs/TESTING.md](engdocs/TESTING.md) for the canonical commands, -test-design guidance, and PR-readiness gates. - -## Non-Interactive Shell Commands - -**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts. - -Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input. - -**Use these forms instead:** -```bash -# Force overwrite without prompting -cp -f source dest # NOT: cp source dest -mv -f source dest # NOT: mv source dest -rm -f file # NOT: rm file - -# For recursive operations -rm -rf directory # NOT: rm -r directory -cp -rf source dest # NOT: cp -r source dest -``` - -**Other commands that may prompt:** -- `scp` - use `-o BatchMode=yes` for non-interactive -- `ssh` - use `-o BatchMode=yes` to fail instead of prompting -- `apt-get` - use `-y` flag -- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var - -## Landing the Plane (Session Completion) - -**When ending a work session** (or when the user says "let's land the -plane"), you MUST complete ALL steps below. Work is NOT complete until -`git push` succeeds. - -**MANDATORY WORKFLOW:** - -1. **File issues for remaining work** - Create issues for anything that needs follow-up -2. **Run quality gates** (if code changed): - - `make ci-pr-lint` (required zero-finding formatting and lint wrapper) - - `make test` (and `make test-icu-path` only if you intentionally need the ICU regex path) - - File a P0 issue if quality gates are broken -3. **Update issue status** - Close finished work, update in-progress items -4. **PUSH TO REMOTE** - This is MANDATORY: - ```bash - git pull --rebase - git push - git status # MUST show "up to date with origin" - ``` -5. **Clean up**: - ```bash - git stash clear # Remove old stashes - git remote prune origin # Clean up deleted remote branches - ``` -6. **Verify** - All changes committed AND pushed, no untracked files remain -7. **Hand off** - Choose a follow-up issue and give the user a prompt for - the next session, e.g. "Continue work on bd-X: [issue title]. [Brief - context about what's been done and what's next]" - -**CRITICAL RULES:** -- Work is NOT complete until `git push` succeeds -- NEVER stop before pushing - that leaves work stranded locally -- NEVER say "ready to push when you are" - YOU must push -- If push fails, resolve and retry until it succeeds - -Close with a summary for the user: what was completed this session, issues -filed for follow-up, quality-gate status, confirmation everything is pushed, -and the recommended prompt for the next session. - - -## Issue Tracking with bd (beads) - -**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods. - -### Why bd? - -- Dependency-aware: Track blockers and relationships between issues -- Git-friendly: Dolt-powered version control with native sync -- Agent-optimized: JSON output, ready work detection, discovered-from links -- Prevents duplicate tracking systems and confusion - -### Quick Start - -**Check for ready work:** +## Build, test, lint ```bash -bd ready --json +make install # build and install bd to ~/.local/bin (canonical) +make test # unit tests with the right build tags +make ci-pr-lint # required zero-finding formatting + lint contract +make check-docs # doc flag, freshness, and docsync checks +make bazel-sync # after adding/removing/renaming Go files or changing imports/go.mod ``` -**Create new issues:** +- **Do NOT** use `go build -o bd ./cmd/bd`, `go install ./cmd/bd`, or raw + `go run ./cmd/bd ...`: they bypass the canonical build path, leave stale + binaries, and raw `go run` misses the `gms_pure_go` tag. Use `make install`, + `./bd`, or `go run -tags gms_pure_go ./cmd/bd ...`. +- All new features need tests. Choose them with + [engdocs/TESTING.md](engdocs/TESTING.md); it is the canonical source for + commands, test design, and PR-readiness gates. +- **Never pollute a production database with test issues.** Use `t.TempDir()` + in Go tests and a disposable working directory for manual `bd` experiments. +- `make ci-pr-lint` must pass with zero issues; see + [engdocs/LINTING.md](engdocs/LINTING.md). +- **Optional shared Bazel cache (opt-in).** `--config=fork-cache` reads the + project's anonymous, read-only cache, so results CI already computed are + hits and nothing is uploaded. It is off by default; when setting up a dev + environment, ask your human before adding `build --config=fork-cache` to + `.bazelrc.local`. +- Without Bazel, let CI sync BUILD files: on same-repo PRs the bazel-autofix + workflow pushes the fix to your branch (pull before pushing again); fork PRs + get a comment with an apply recipe. +- If you changed behavior, update the user docs (`docs/`, via the + `beads-docs` skill) or README in the same PR. -```bash -bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json -bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json -``` +## Commits and PRs -**Claim and update:** +- Conventional Commits: `type(scope): summary` (`fix`, `feat`, `docs`, + `test`, `refactor`, `chore`, `ci`, `perf`). +- For agent-prepared commits, include the `Agent-Signature:` trailer described + in [engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md). Use + `unknown-model` or `unknown-reasoning` when reliable runtime metadata is + unavailable. +- Maintainers working from the internal ledger may also end the subject with + the bead ID, e.g. `(bd-abc)`, so `bd doctor` can detect orphaned issues. +- Work on a feature branch and open a PR against `main`; direct pushes to + `main` are reserved for releases and narrow operational fixes. +- When the user asks to bump the version, use `./scripts/bump-version.sh`; the + full release process is in [RELEASING.md](RELEASING.md). -```bash -bd update --claim --json -bd update bd-42 --priority 1 --json -``` +## Ending a session -**Complete work:** +Do not push to `main`. Before handing off: -```bash -bd close bd-42 --reason "Completed" --json -``` +1. Run the quality gates your change needs (`make ci-pr-lint`, the tests + [engdocs/TESTING.md](engdocs/TESTING.md) selects). If gates are broken on + `main`, report it as a P0 issue. +2. Record follow-up work as GitHub issues (or ledger beads, for maintainers). +3. Commit, push, or open a PR only when the person you are working for asked + you to. Report changed files, validation run, and anything left open. -### Issue Types +## CLI output -- `bug` - Something broken -- `feature` - New functionality -- `task` - Work item (tests, docs, refactoring) -- `epic` - Large feature with subtasks -- `chore` - Maintenance (dependencies, tooling) +**NEVER use emoji-style icons** (🔴🟠🟡🔵⚪) in CLI output. **ALWAYS use small +Unicode symbols** with semantic colors: status `○ ◐ ● ✓ ❄`; priority as a +`P0`–`P4` label with color (no status glyph). The full visual design system +and CLI design principles are in +[engdocs/UI_PHILOSOPHY.md](engdocs/UI_PHILOSOPHY.md). -### Priorities +## Non-interactive shell commands -- `0` - Critical (security, data loss, broken builds) -- `1` - High (major features, important bugs) -- `2` - Medium (default, nice-to-have) -- `3` - Low (polish, optimization) -- `4` - Backlog (future ideas) +Agents cannot answer prompts. Use `cp -f`, `mv -f`, `rm -f`, `rm -rf`, +`cp -rf` (these may be aliased to `-i`); `scp`/`ssh -o BatchMode=yes`; +`apt-get -y`; `HOMEBREW_NO_AUTO_UPDATE=1 brew`. **DO NOT use `bd edit`** — it +opens `$EDITOR`; use `bd update --title/--description/--design/--acceptance/--append-notes` +(pipe text with special characters via `--description=-`). -### Workflow for AI Agents +## Routing table -1. **Check ready work**: `bd ready` shows unblocked issues -2. **Claim your task atomically**: `bd update --claim` -3. **Work on it**: Implement, test, document -4. **Discover new work?** Create linked issue: - - `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:` -5. **Complete**: `bd close --reason "Done"` - -### Quality -- Use `--acceptance` and `--design` fields when creating issues -- Use `--validate` to check description completeness - -### Lifecycle -- `bd defer ` / `bd supersede ` for issue management -- `bd stale` / `bd orphans` / `bd lint` for hygiene -- `bd human ` to flag for human decisions -- `bd formula list` / `bd mol pour ` for structured workflows - -### Sync - -bd stores issue history in Dolt: - -- Each write auto-commits to Dolt history -- Use `bd dolt push`/`bd dolt pull` for remote sync -- Do not treat `.beads/issues.jsonl` as the sync protocol - -**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns. - -### Important Rules - -- ✅ Use bd for ALL task tracking -- ✅ Always use `--json` flag for programmatic use -- ✅ Link discovered work with `discovered-from` dependencies -- ✅ Check `bd ready` before asking "what should I work on?" -- ❌ Do NOT create markdown TODO lists -- ❌ Do NOT use external issue trackers -- ❌ Do NOT duplicate tracking systems - -For more details, see README.md and https://github.com/gastownhall/beads/blob/main/docs/getting-started/quickstart.md. - -## Agent Context Profiles - -The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions. - -- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands. -- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise. -- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins. - -## Session Completion - -This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions. - -1. **File issues for remaining work** - Create beads for anything that needs follow-up -2. **Run quality gates** (if code changed) - Tests, linters, builds -3. **Update issue status** - Close finished work, update in-progress items -4. **Handle git/sync by active profile**: - ```bash - # Conservative/minimal/default: report status and proposed commands; wait for approval. - git status - - # Team-maintainer opt-in only, unless current instructions forbid it: - git pull --rebase - bd dolt push - git push - git status - ``` -5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step - -**Critical rules:** -- Explicit user or orchestrator instructions override this Beads block. -- Do not commit or push without clear authority from the active profile or the current user request. -- If a required sync or push is blocked, stop and report the exact command and error. - - +| When you are touching… | Read first | +|---|---| +| `cmd/bd/` (commands, output, proxied-server routes) | [cmd/bd/AGENTS.md](cmd/bd/AGENTS.md) | +| `engdocs/` (contributor and internals docs) | [engdocs/AGENTS.md](engdocs/AGENTS.md) | +| `docs/` (the published user docs) | `.claude/skills/beads-docs/SKILL.md` | +| Any Go test | [engdocs/TESTING.md](engdocs/TESTING.md) | +| Lint failures or `.golangci.yml` | [engdocs/LINTING.md](engdocs/LINTING.md) | +| A new storage operation or issueops role | [engdocs/ADDING_AN_ISSUEOPS_ROLE.md](engdocs/ADDING_AN_ISSUEOPS_ROLE.md) | +| Schema migrations | [internal/storage/schema/migrations/README.md](internal/storage/schema/migrations/README.md) | +| Dolt concurrency, server vs embedded mode | [engdocs/design/dolt-concurrency.md](engdocs/design/dolt-concurrency.md) | +| Errors returned to users | [engdocs/ERROR_HANDLING.md](engdocs/ERROR_HANDLING.md) | +| The `bd serve` HTTP surface | [engdocs/SERVE_RUNBOOK.md](engdocs/SERVE_RUNBOOK.md) | +| A new example under `examples/` | `examples/README.md` — give the example its own README and link it there | +| Releases and version bumps | [RELEASING.md](RELEASING.md) | +| Scope questions | [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) | +| Planned work and priorities | [ROADMAP.md](ROADMAP.md) | diff --git a/AGENT_INSTRUCTIONS.md b/AGENT_INSTRUCTIONS.md index 3afc356e7..b00961736 100644 --- a/AGENT_INSTRUCTIONS.md +++ b/AGENT_INSTRUCTIONS.md @@ -1,537 +1,9 @@ -# Detailed Agent Instructions for Beads Development +# Agent Instructions -**For project overview and quick start, see [AGENTS.md](AGENTS.md)** +Contributor instructions for agents developing beads live in +[AGENTS.md](AGENTS.md). Area-specific rules live in nested `AGENTS.md` files +listed in its routing table. -This document contains detailed operational instructions for AI agents working on beads development, testing, and releases. - -## Development Guidelines - -### Code Standards - -- **Go version**: see `go.mod` for the required version (currently 1.26+) -- **Linting**: `make ci-pr-lint` must pass with zero issues; see - [engdocs/LINTING.md](engdocs/LINTING.md) -- **Testing**: All new features need tests; use [engdocs/TESTING.md](engdocs/TESTING.md) for command selection, test design, and PR readiness. -- **Documentation**: Update relevant .md files - -### File Organization - -``` -beads/ -├── cmd/bd/ # CLI commands -├── internal/ -│ ├── types/ # Core data types -│ └── storage/ # Storage layer -│ └── dolt/ # Dolt implementation -├── examples/ # Integration examples -└── *.md # Documentation -``` - -### Testing Workflow - -**IMPORTANT:** Never pollute the production database with test issues! - -For test commands, tier selection, and test-design guidance, use the canonical -[engdocs/TESTING.md](engdocs/TESTING.md). - -**For manual testing**, keep initialization and all experiments in a disposable -working directory. This safety example supplements the canonical testing guide: - -```bash -beads_manual_dir="$(mktemp -d)" -( - set -e - cd "$beads_manual_dir" - bd init --quiet --prefix test --skip-hooks --skip-agents - bd create "Test issue" -p 1 -) -rm -rf -- "$beads_manual_dir" -``` - -`BEADS_DB` alone does not redirect `bd init` workspace setup. Do not run manual -initialization from a production workspace even when selecting another database. - -**For automated tests**, use `t.TempDir()` in Go tests: - -```go -func TestMyFeature(t *testing.T) { - tmpDir := t.TempDir() - testDB := filepath.Join(tmpDir, ".beads", "beads.db") - s := newTestStore(t, testDB) - // ... test code -} -``` - -**Git test isolation:** For tests that create temporary git repos, force repo-local hooks: - -```bash -git config core.hooksPath .git/hooks -``` - -Do not rely on the developer's global git config. Global `core.hooksPath` can leak -into temp repos and produce flaky test behavior. - -**Warning:** bd will warn you when creating issues with a "Test" prefix in the -production database. The disposable working directory is the isolation -boundary for manual initialization and experiments. - -**Tmpfs hosts:** the `cmd/bd` test suite creates an isolated `$HOME` and several -test binaries under `$TMPDIR`. They are normally cleaned by the test process, -but a SIGKILLed or OOMed run can leave orphans behind. On hosts where `/tmp` -is tmpfs (e.g. Fedora Atomic / Bluefin), run `make clean-test-tmp` between -test runs if `du -sh /tmp/beads-* /tmp/bd-*` shows accumulation. See bd-3q2u. - -### Before Committing - -1. **Run tests**: follow [engdocs/TESTING.md](engdocs/TESTING.md). -2. **Run the required lint contract when its code surface changed**: - `make ci-pr-lint` -3. **Update docs**: If you changed behavior, update README.md or other docs -4. **Sync Bazel BUILD files** if you added, removed or renamed Go files, or - changed imports or `go.mod`: `make bazel-sync` (needs Bazel), then commit - the BUILD.bazel / MODULE.bazel changes. Without Bazel, let CI do it: on - same-repo PRs the bazel-autofix workflow pushes the fix for the packages - your PR changed to your branch (pull before pushing again); fork PRs get - a comment with an apply recipe. -5. **Commit**: With git hooks installed (`bd hooks install`), Dolt changes are auto-committed - -### Commit Message Convention - -When committing work for an issue, include the issue ID in parentheses at the end: - -```bash -git commit -m "Fix auth validation bug (bd-abc)" -git commit -m "Add retry logic for database locks (bd-xyz)" -``` - -This enables `bd doctor` to detect **orphaned issues** - work that was committed but the issue wasn't closed. The doctor check cross-references open issues against git history to find these orphans. - -For agent-prepared commits, also include the -`Agent-Signature:` trailer described in -[engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md). Use `unknown-model` or -`unknown-reasoning` when reliable runtime metadata is unavailable. - -### Git Workflow - -bd uses **Dolt** as its primary database. Changes are committed to Dolt history automatically (one Dolt commit per write command). - -**Install git hooks** for commit integration and legacy fallback behavior: -```bash -bd hooks install -``` - -### Git Integration - -**Dolt sync**: Dolt handles sync natively via `bd dolt push` / `bd dolt pull`. No export/import round-trip needed for normal sync. - -**Protected branches**: Dolt stores data under `refs/dolt/data`, separate from standard Git refs. See [docs/reference/protected-branches.md](docs/reference/protected-branches.md). - -**Git worktrees**: Work directly with Dolt — no special flags needed. See [docs/reference/advanced.md](docs/reference/advanced.md). - -**Merge conflicts**: Rare with hash IDs. Dolt uses cell-level 3-way merge for conflict resolution. - -## Git Workflow: PR by Default - -Crew workers use a PR-based workflow. Beads is a dependency of a downstream consumer, so we -defer to the standard PR flow to keep changes reviewable. - -- Work on a feature branch, push the branch, open a PR against `main` -- `gh pr create` is the normal path to land work -- Direct push to main is reserved for releases (tag + release commit) and - narrow operational fixes; prefer a PR when unsure -- When handling external contributor PRs, use fix-merge: checkout the PR - branch locally, fix/rebase onto main, merge via PR, then close the PR - -### Maintainer PR Guidelines - -Before triaging, reviewing, landing, closing, or otherwise maintaining PRs, -read [PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The -maintainer policy is to maximize community throughput: find useful contributor -value, absorb or transform it locally when practical, preserve attribution, and -use request-changes only as a last resort. - -Sign agent-written GitHub comments and reviews using -[engdocs/AGENT_SIGNING.md](engdocs/AGENT_SIGNING.md). - -### External Contributor PRs: Check Before You Build - -**Read [CONTRIBUTING.md](CONTRIBUTING.md)** — it contains promises we've made to contributors. Violating them damages trust and community. - -Run the read-only preflight before implementing related work, opening a PR, or -merging/closing a PR: - -```bash -scripts/pr-preflight.sh --search "" --repo gastownhall/beads -scripts/pr-preflight.sh --repo gastownhall/beads -``` - -**Before implementing any feature or fix, check for existing open PRs on the same topic:** - -```bash -gh pr list --repo gastownhall/beads --state open --search "" --json number,title,author,headRefName -``` - -**Contributor work gets priority.** If an external PR already exists: -1. **Review it first** — read the diff, understand the approach -2. **Build on their work, don't rewrite it** — checkout their branch, fix/adapt as needed -3. **Preserve their tests** — contributor tests are signal; keep them unless they're wrong -4. **Attribute properly** — use `Co-authored-by:` in commits, reference their PR number -5. **Never auto-close a contributor PR** by merging a rewrite — that discards their contribution silently - -If you must rewrite (e.g., fundamentally different approach needed), explain why on the original PR and credit the contributor's design/tests in your commits. - -Do not rely on auto-discovery of CONTRIBUTING.md; the preflight is the agent -gate for PR handling. - -## Landing the Plane - -See [AGENTS.md](AGENTS.md#landing-the-plane-session-completion) for the -canonical session-completion protocol (quality gates, mandatory `git push`, -cleanup, and next-session hand-off). - -## Agent Session Workflow - -**WARNING: DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use. Use `bd update` with flags instead: -```bash -bd update --description "new description" -bd update --title "new title" -bd update --design "design notes" -bd update --append-notes "additional notes" # --notes replaces existing notes and requires --force once notes are set -bd update --acceptance "acceptance criteria" -``` - -**Read execution metadata before prose.** When enacting a bd issue, inspect the -structured metadata before using description or notes to choose execution mode, -delegation, model, reasoning level, or parallel group: - -```bash -bd show --json | jq '.[0] | {id,title,metadata,description,notes}' -``` - -The execution metadata keys are: - -- `execution_agent_type` -- `execution_suggested_model` -- `execution_reasoning_effort` -- `execution_mode` -- `execution_parallel_group` - -When these keys are present, treat them as the authoritative execution hints. -Use `description` for the work scope and `notes` for rationale or fallback -context. Parent/orchestrator agents must read these fields before spawning -subagents because a running subagent cannot change its model or reasoning effort -after launch. - -**Use stdin for descriptions with special characters** (backticks, `!`, nested quotes): -```bash -# Pipe via stdin to avoid shell escaping issues -echo 'Description with `backticks` and "quotes"' | bd create "Title" --stdin -echo 'Updated description with $variables' | bd update --description=- - -# Or use --body-file for longer content -bd create "Title" --body-file=description.md -``` - -**GitHub body hygiene.** For GitHub PR, issue, comment, and review bodies, -write Markdown to a file and pass it with `gh ... --body-file`. Run -`scripts/gh-body-lint ` first to catch literal `\n` sequences and -non-linking `GH#123` references. - -**Example agent session:** - -```bash -# Make changes (each write auto-commits to Dolt) -bd create "Fix bug" -p 1 -bd create "Add tests" -p 1 -bd update bd-42 --claim -bd close bd-40 --reason "Completed" - -# Push Dolt data to remote if configured -bd dolt push - -# Now safe to end session -``` - -This installs: - -- **pre-commit** — Commits pending Dolt changes -- **post-merge** — Runs chained hooks and a legacy JSONL import fallback only when no Dolt remote is configured - -**Note:** Hooks are embedded in the bd binary and work for all bd users (not just source repo users). - -## Common Development Tasks - -### Visual Design System - -When adding CLI output features, follow these design principles for consistent, -cognitively friendly visuals. - -#### No Emoji-Style Icons - -Do not use large colored emoji icons like red/orange/yellow/blue/white circles -for priorities or status. They cause cognitive overload and break visual -consistency. - -Use small Unicode symbols with semantic colors applied via lipgloss: - -- Status: `○ ◐ ● ✓ ❄` -- Priority: `P0`–`P4` label with color (no status glyph) - -#### Status Icons - -Use these symbols consistently across all commands: - -```text -○ open - Available to work (white/default) -◐ in_progress - Currently being worked (yellow) -● blocked - Waiting on dependencies (red) -✓ closed - Completed (muted gray) -❄ deferred - Scheduled for later (blue/muted) -``` - -#### Priority Labels and Colors - -Format priority as the P-label with color only (no status glyph — `●` is blocked status): - -- `P0`: Red + bold (critical) -- `P1`: Orange (high) -- `P2`: Amber (elevated) -- `P3`–`P4`: Default text - -#### Issue Type Colors - -- `bug`: Red (problems need attention) -- `epic`: Purple (larger scope) -- Others: Default text - -#### Design Principles - -1. Small Unicode symbols only; avoid emoji blobs. -2. Semantic colors only for actionable items; do not color everything. -3. Closed items fade using muted gray. -4. Prefer icons over text labels for scanability. -5. Keep icons consistent across list, graph, show, and related commands. -6. Use tree connectors (`├──`, `└──`, `│`) for hierarchies. -7. Reduce cognitive noise; do not show `needs:1` when it is just the parent epic. - -#### Semantic Styles - -Use exported styles from `internal/ui/styles.go`: - -```go -// Status styles -ui.StatusInProgressStyle // Yellow - active work -ui.StatusBlockedStyle // Red - needs attention -ui.StatusClosedStyle // Muted gray - done - -// Priority styles -ui.PriorityP0Style // Red + bold -ui.PriorityP1Style // Orange - -// Type styles -ui.TypeBugStyle // Red -ui.TypeEpicStyle // Purple - -// General styles -ui.PassStyle, ui.WarnStyle, ui.FailStyle -ui.MutedStyle, ui.AccentStyle -ui.RenderMuted(text), ui.RenderAccent(text) -``` - -Example: - -```go -switch issue.Status { -case types.StatusOpen: - icon = "○" -case types.StatusInProgress: - icon = ui.StatusInProgressStyle.Render("◐") -case types.StatusBlocked: - icon = ui.StatusBlockedStyle.Render("●") -case types.StatusClosed: - icon = ui.StatusClosedStyle.Render("✓") -} -``` - -### CLI Design Principles - -**Minimize cognitive overload.** Every new command, flag, or option adds cognitive burden for users. Before adding anything: - -1. **Recovery/fix operations → `bd doctor --fix`**: Don't create separate commands like `bd recover` or `bd repair`. Doctor already detects problems - let `--fix` handle remediation. This keeps all health-related operations in one discoverable place. - For git hook marker migration specifically: use `bd migrate hooks --dry-run` to preview operations, and `bd doctor --fix` for the standard apply path. - -2. **Prefer flags on existing commands**: Before creating a new command, ask: "Can this be a flag on an existing command?" Example: `bd list --stale` instead of `bd stale`. - -3. **Consolidate related operations**: Related operations should live together. Version control uses `bd vc {log,diff,commit}`, not separate top-level commands. - -4. **Count the commands**: Run `bd --help` and count. If we're approaching 30+ commands, we have a discoverability problem. Consider subcommand grouping. - -5. **New commands need strong justification**: A new command should represent a fundamentally different operation, not just a convenience wrapper. - -### Adding a New Command - -1. Create file in `cmd/bd/` -2. Add to root command in `cmd/bd/main.go` -3. Implement with Cobra framework -4. Add `--json` flag for agent use -5. Add tests in `cmd/bd/*_test.go` -6. Document in README.md - -### Adding Storage Features - -1. Add Dolt SQL schema changes in `internal/storage/dolt/` -2. Add migration if needed -3. Update `internal/types/types.go` if new types -4. Implement in `internal/storage/dolt/` (queries, issues, etc.) -5. Add tests -6. Update export/import in `cmd/bd/export.go` and `cmd/bd/import.go` - -### Adding Examples - -1. Create directory in `examples/` -2. Add README.md explaining the example -3. Include working code -4. Link from `examples/README.md` -5. Mention in main README.md - -## Building - -```bash -# Build and install bd to ~/.local/bin (the canonical location) -make install - -# Verify installed binary -bd init --prefix test -bd create "Test issue" -p 1 -bd ready -``` - -For testing commands, test design, and PR-readiness gates, use -[engdocs/TESTING.md](engdocs/TESTING.md). - -> **WARNING**: Do NOT use `go build -o bd ./cmd/bd`, `go install ./cmd/bd`, -> or raw `go run ./cmd/bd ...`. -> These bypass the canonical build path, can create stale binaries in the -> working directory or `~/go/bin/`, and raw `go run` may miss the required -> `gms_pure_go` build tag. Always use `make install`, `./bd`, or -> `go run -tags gms_pure_go ./cmd/bd ...` when you explicitly need `go run`. - -## Version Management - -**IMPORTANT**: When the user asks to "bump the version" or mentions a new version number (e.g., "bump to 0.9.3"), use the version bump script: - -```bash -# Preview changes (shows diff, doesn't commit) -./scripts/bump-version.sh 0.9.3 - -# Auto-commit the version bump -./scripts/bump-version.sh 0.9.3 --commit -git push origin main -``` - -**What it does:** - -- Updates ALL version files (CLI, plugin, MCP server, docs) in one command -- Validates semantic versioning format -- Shows diff preview -- Verifies all versions match after update -- Creates standardized commit message - -**User will typically say:** - -- "Bump to 0.9.3" -- "Update version to 1.0.0" -- "Rev the project to 0.9.4" -- "Increment the version" - -**You should:** - -1. Run `./scripts/bump-version.sh --commit` -2. Push to GitHub -3. Confirm all versions updated correctly - -**Files updated automatically:** - -- `cmd/bd/version.go` - CLI version -- `plugins/beads/.claude-plugin/plugin.json` - Claude plugin version -- `plugins/beads/.codex-plugin/plugin.json` - Codex plugin version -- `.claude-plugin/marketplace.json` - Claude marketplace version -- `integrations/beads-mcp/pyproject.toml` - MCP server version -- `README.md` - Documentation version -- `PLUGIN.md` - Version requirements - -**Why this matters:** We had version mismatches (bd-66) when only `version.go` was updated. This script prevents that by updating all components atomically. - -See `scripts/README.md` for more details. - -## Release Process (Maintainers) - -See [RELEASING.md](RELEASING.md) for the complete release process, including -the automated `./scripts/release.sh ` script and the manual, -step-by-step channel-by-channel instructions. - -## Checking GitHub Issues and PRs - -**IMPORTANT**: When asked to check GitHub issues or PRs, use command-line tools like `gh` instead of browser/playwright tools. - -**Preferred approach:** - -```bash -# List open issues with details -gh issue list --limit 30 - -# List open PRs -gh pr list --limit 30 - -# View specific issue -gh issue view 201 -``` - -**Then provide an in-conversation summary** highlighting: - -- Urgent/critical issues (regressions, bugs, broken builds) -- Common themes or patterns -- Feature requests with high engagement -- Items that need immediate attention - -**Why this matters:** - -- Browser tools consume more tokens and are slower -- CLI summaries are easier to scan and discuss -- Keeps the conversation focused and efficient -- Better for quick triage and prioritization - -**Do NOT use:** `browser_navigate`, `browser_snapshot`, or other playwright tools for GitHub PR/issue reviews unless specifically requested by the user. - -## Telemetry - -`bd` collects anonymous command-usage metrics. Each event is a `cli_command` -record carrying only the command name; each batch also carries the bd version -and OS platform, keyed by a machine-derived, HMAC-protected distinct ID. No -email, repo path, remote URL, issue content, or user-supplied strings are -collected. Events are written under `~/.beads/eventsData` and POSTed to -`https://gastownhall-eventsapi.com/mp/collect`. - -Metrics are enabled by default (opt-out). The friendliest way to see or change -them is `bd metrics` (`bd metrics on` / `bd metrics off` / `bd metrics example`), -which takes effect on the next command with no restart. `BD_DISABLE_METRICS=1` -still works as a one-off, shell-scoped override. The cross-tool -[`DO_NOT_TRACK`](https://donottrack.sh/) standard is honored as a disable-only -opt-out: `DO_NOT_TRACK=1` opts out, while a falsey or empty value -(`DO_NOT_TRACK=0`, `false`, or unset-but-present) falls through to your saved -`bd metrics` preference instead of forcing metrics back on. `BD_DISABLE_METRICS` -is the bidirectional override and takes precedence when both are set. - -## Questions? - -- Check existing issues: `bd list` -- Look at recent commits: `git log --oneline -20` -- Read the docs: README.md, ADVANCED.md, docs/reference/configuration.md -- Create an issue if unsure: `bd create "Question: ..." -t task -p 2` - -## Important Files - -- **README.md** - Main documentation (keep this updated!) -- **ADVANCED.md** - Advanced features (rename, merge, compaction) -- **CONTRIBUTING.md** - Contribution guidelines -- **SECURITY.md** - Security policy +If you are using `bd` to track work in your own project, see the user docs: +[IDE and agent setup](docs/getting-started/ide-setup.md) and +[https://beads.gascity.com/](https://beads.gascity.com/). diff --git a/BUILD.bazel b/BUILD.bazel index 077a16413..f644db68c 100644 --- a/BUILD.bazel +++ b/BUILD.bazel @@ -81,6 +81,8 @@ filegroup( "engdocs/**", ]) + [ "integrations/beads-mcp/PYPI.md", + "//cmd/bd:AGENTS.md", + "//internal/storage/schema:migrations/README.md", "//scripts:README.md", ], visibility = ["//test/docsync:__pkg__"], diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 9f08e2027..000000000 --- a/CLAUDE.md +++ /dev/null @@ -1,23 +0,0 @@ -# Claude Code Entry Point for Beads - -This file is intentionally short. Do not copy workflow, build, storage, or UI -rules here; those details drift quickly when repeated across agent entrypoints. - -## Read First - -- **Workflow and safety**: [AGENTS.md](AGENTS.md) -- **Detailed agent operations**: [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) -- **Architecture orientation**: [engdocs/CLAUDE.md](engdocs/CLAUDE.md) -- **PR maintenance policy**: [PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md) - -## Current Ground Rules - -- Run `bd prime` before doing tracked work. -- Follow `go.mod` and [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for build - and test commands; do not hard-code toolchain versions here. -- Beads uses Dolt as the issue database. Use `bd dolt push` / `bd dolt pull` - for issue data sync; do not use export/import as a routine git workflow. -- The CLI Visual Design System lives in - [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md#visual-design-system). -- If this file conflicts with a linked source, trust the linked source and fix - this file by removing the duplicate. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 000000000..47dc3e3d8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bfd65e364..24d3e573f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,50 @@ Thank you for your interest in contributing to bd! This document provides guidelines and instructions for contributing. +## Issues and pull requests + +GitHub Issues is the public tracker, and every pull request links a +documented issue. The issue is where the context lives: why the change is +needed, what it affects, and how we will know it works. File it with the bug +or feature form before or alongside your pull request; it does not need +maintainer approval first. + +### Triage labels + +| Label | Meaning | Applied by | +|---|---|---| +| `status/needs-triage` | Awaiting initial triage. | Automation, on every new issue | +| `status/needs-info` | Waiting on essential information from the reporter. | Maintainers | +| `status/needs-repro` | Needs a reproducible bug report. | Maintainers | +| `status/needs-design` | The direction needs a design decision before work starts. | Maintainers | +| `status/accepted` | Confirmed and on our radar. | Maintainers | + +Issues left in `status/needs-info` or `status/needs-repro` are closed after 14 +days without a reply to the request; reply with the details and a +maintainer will reopen them. +Priority (`priority/p0`–`priority/p3`) and kind (`kind/bug`, `kind/feature`, +`kind/docs`, `kind/chore`) labels are set during triage. + +### Pull request pipeline labels + +These labels drive the maintainers' automated review and merge workflow. They +are applied by maintainers and automation; contributors don't need to set +them. + +| Label | Meaning | +|---|---| +| `status/needs-review` | Request the PR review workflow. | +| `status/needs-review-auto` | Request the automated PR review workflow. | +| `status/reviewing` | The PR review workflow is running. | +| `status/review-failed` | The PR review workflow failed before merge-ready. | +| `status/merge-ready` | The PR is ready for the merge workflow. | +| `status/merge-queued` | Queued for deterministic PR-review merge. | +| `status/merge-failed` | The merge queue needs operator attention. | +| `status/needs-bugflow` | Request the bugflow investigation workflow. | + +The current priorities are on the [roadmap](ROADMAP.md); work in a priority +area is reviewed first. + ## Development Setup ### Prerequisites @@ -29,6 +73,12 @@ make test make install ``` +Optional: if you use Bazel, opt in to the project's anonymous, read-only +build cache by adding `build --config=fork-cache` to your gitignored +`.bazelrc.local` (or pass `--config=fork-cache` per command). Results CI +already computed become cache hits, and nothing you build is uploaded. It is +off by default. + ## Project Structure ``` @@ -90,21 +140,23 @@ engine, or expand the database schema when issue metadata is sufficient. ### Workflow -1. Fork the repository -2. Create a feature branch (`git checkout -b feature/my-feature`) +1. Find or file a documented issue (see [Issues and pull requests](#issues-and-pull-requests)) +2. Fork the repository and create a feature branch (`git checkout -b feature/my-feature`) 3. Make your changes 4. Add tests for new functionality 5. Run tests and linter locally 6. Commit your changes with clear messages 7. Push to your fork -8. Open a pull request +8. Open a pull request whose description says `Closes #` ### Commit Messages -Write clear, concise commit messages: +Use [Conventional Commits](https://www.conventionalcommits.org/): +`type(scope): summary`, where type is one of `fix`, `feat`, `docs`, `test`, +`refactor`, `chore`, `ci`, or `perf`. ``` -Add cycle detection for dependency graphs +feat(dep): add cycle detection for dependency graphs - Implement recursive CTE-based cycle detection - Add tests for simple and complex cycles @@ -115,6 +167,10 @@ Add cycle detection for dependency graphs **One issue per PR, and one PR per issue.** No piggybacking or riders — each PR should address exactly one thing. +Read [CONTRIBUTING_PR_GUIDELINES.md](CONTRIBUTING_PR_GUIDELINES.md) for the +layering rules (schema → storage/issueops → cmd/bd, one layer per PR) and the +repro and benchmark evidence reviewers expect. + - Keep PRs focused on a single feature or fix - Do not include unrelated changes, cleanup, or "while I'm here" improvements - Do not include `.beads/` data (database, JSONL) in your PR @@ -178,22 +234,12 @@ round-trip paths should pattern-match on those tests. ## Feature Requests and Bug Reports -### Reporting Bugs - -Include in your bug report: -- Steps to reproduce -- Expected behavior -- Actual behavior -- Version of bd (`bd version` if implemented) -- Operating system and Go version - -### Feature Requests - -When proposing new features: -- Explain the use case -- Describe the proposed solution -- Consider backwards compatibility -- Discuss alternatives you've considered +Use the issue forms: [bug report](https://github.com/gastownhall/beads/issues/new?template=bug_report.yml) +or [feature request](https://github.com/gastownhall/beads/issues/new?template=feature_request.yml). +The feature form asks for the motivation, impact, risk and compatibility, +and verification plan up front, so a maintainer can accept the issue without +a round trip. Questions go to +[Discussions](https://github.com/gastownhall/beads/discussions). ## Your PR Will Not Be Overwritten @@ -309,11 +355,7 @@ dlv debug ./cmd/bd -- create "Test issue" (For maintainers) -1. Update version in code -2. Update CHANGELOG.md -3. Tag release: `git tag v0.x.0` -4. Push tag: `git push origin v0.x.0` -5. GitHub Actions will build and publish +Follow [RELEASING.md](RELEASING.md); it is the canonical release process. The pre-push version gate requires Go and validates each `v*` release tag against the checkout's canonical version. A batch containing different release diff --git a/README.md b/README.md index 6bc34354f..5526718f6 100644 --- a/README.md +++ b/README.md @@ -211,5 +211,6 @@ This is useful for: ## 📝 Documentation -* [Documentation site](https://beads.gascity.com/) | [Installing](docs/getting-started/installation.md) | [Sync Concepts](docs/core-concepts/sync-concepts.md) | [Agent Workflow](AGENT_INSTRUCTIONS.md) | [Copilot CLI Setup](docs/integrations/copilot-cli.md) | [Copilot VS Code MCP](docs/integrations/github-copilot.md) | [Articles](ARTICLES.md) | [Sync Branch Mode](docs/reference/protected-branches.md) | [Troubleshooting](docs/reference/troubleshooting.md) | [FAQ](docs/reference/faq.md) +* [Documentation site](https://beads.gascity.com/) | [Installing](docs/getting-started/installation.md) | [Sync Concepts](docs/core-concepts/sync-concepts.md) | [Agent Setup](docs/getting-started/ide-setup.md) | [Copilot CLI Setup](docs/integrations/copilot-cli.md) | [Copilot VS Code MCP](docs/integrations/github-copilot.md) | [Articles](ARTICLES.md) | [Sync Branch Mode](docs/reference/protected-branches.md) | [Troubleshooting](docs/reference/troubleshooting.md) | [FAQ](docs/reference/faq.md) +* Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) | [Roadmap](ROADMAP.md) | [Contributor agent instructions](AGENTS.md) * [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/gastownhall/beads) diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 000000000..214306136 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,69 @@ +# Beads Roadmap + +Last updated: 2026-10-05 · Owner: [@julianknutsen](https://github.com/julianknutsen) + +This page lists the areas the maintainers are prioritizing. It reflects +current thinking, not commitments or dates: priorities change as we learn, +and the live state of each item is its tracking issue on GitHub. + +## How this roadmap is used + +- **Priority areas get expedited review.** Issues and PRs that advance a + priority area below are triaged and reviewed first. +- **Every PR links a documented issue.** To propose work — inside or + outside a priority area — open an issue with the feature form, before or + alongside your PR; see + [CONTRIBUTING.md](CONTRIBUTING.md#issues-and-pull-requests). +- **Scope.** Proposals must fit the product boundary in + [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md). +- **Updates.** The owner rewrites this page at each minor release; the date + above says when it was last reviewed. + +## Priority areas for 1.4 + +### Versioned beads and history + +- **Goal:** every change to a bead is recorded as a version. Users can read + a bead's history and past versions, and writers can use `expectedRevision` + compare-and-swap to avoid lost updates. Everything ships behind a flag, off + by default, until the conformance suite and a production-corpus soak say + otherwise. +- **This period:** all six phases, enabled from the CLI by the end of the + period: conformance suite + ([#6133](https://github.com/gastownhall/beads/issues/6133)), additive + schema ([#6134](https://github.com/gastownhall/beads/issues/6134)), + dual-write history behind a flag + ([#6135](https://github.com/gastownhall/beads/issues/6135)), versioned + reads and CAS ([#6136](https://github.com/gastownhall/beads/issues/6136)), + production-corpus validation + ([#6137](https://github.com/gastownhall/beads/issues/6137)), and CLI + surfacing and enablement + ([#6138](https://github.com/gastownhall/beads/issues/6138)). +- **Tracking issue:** [#6132](https://github.com/gastownhall/beads/issues/6132); + design discussion stays on + [#5898](https://github.com/gastownhall/beads/issues/5898). + +### Beads Graph Preview 2 + +- **Goal:** ship Beads Graph Preview 2, the next public checkpoint for the + generic Bead-and-Link graph model: a coherent daily-use CLI journey in + graph mode that behaves like ordinary `bd`, backed by a complete, + reviewable CLI specification. +- **This period:** the reviewed graph CLI specification, a complete + daily-use Issue journey proven through the installed CLI on embedded and + shared-server Dolt, and editing around that Issue (labels, notes, Memory + and Link edits). +- **Tracking issue:** [#7170](https://github.com/gastownhall/beads/issues/7170) + +### Contributor onboarding + +- **Goal:** a new contributor, human or agent, finds the rules for the code + they are changing next to that code, understands its intent and + invariants, and lands a change with a documented issue and PR. +- **This period:** contributor-only agent instructions and documented-issue + intake ([#7223](https://github.com/gastownhall/beads/pull/7223)); + per-package `AGENTS.md` files for the storage packages, naming their + guard tests and lint rules; a package-doc linter and package docs for the + packages that have none; and a curated set of `help wanted` starter + issues. +- **Tracking issue:** [#7228](https://github.com/gastownhall/beads/issues/7228) diff --git a/cmd/bd/AGENTS.md b/cmd/bd/AGENTS.md index c5e09f399..5ddbc95f5 100644 --- a/cmd/bd/AGENTS.md +++ b/cmd/bd/AGENTS.md @@ -1,58 +1,90 @@ -# Agent Instructions +# cmd/bd — contributor notes -This project uses **bd** (beads) for issue tracking. Run `bd prime` for full workflow context. +`cmd/bd` is the `bd` CLI: one Go package (about 340 non-test files) plus the +`doctor/`, `setup/`, `protocol/`, `help_supplements/`, and `winres/` +subpackages. Commands decide what to do; storage work belongs below them in +`internal/storage/issueops` (see the layering rules in +[CONTRIBUTING_PR_GUIDELINES.md](../../CONTRIBUTING_PR_GUIDELINES.md)). -## Quick Reference +## File families -```bash -bd ready # Find available work (open, no blockers) -bd blocked # Show blocked issues and what blocks them -bd list # List all issues (with blocker annotations) -bd show # View issue details -bd update --claim # Claim work (atomic compare-and-swap) -bd close # Complete work -bd dolt push # Push to Dolt remote -``` +| Pattern | Meaning | +|---|---| +| `.go` | The Cobra command, its flags, and the mode-independent body. Registers itself with `rootCmd.AddCommand` in its own `init()` — `main.go` adds no commands. | +| `_proxied_server.go` | The proxied-server route for the same command. A command that touches the store on a proxied-server workspace needs one. | +| `capability_registry.go` | One table for every command path: what the pre-provider gate does with it on a proxied-server workspace. | +| `_embedded_test.go` | `cgo` tests against embedded Dolt. | +| `_integration_test.go` | Integration tests, usually `cgo && unix`. | +| `_proxied_test.go` | Proxied-server tests. | +| `_guard_test.go` | Policy and safety guards. | -**Dependency status**: `bd ready` and `bd blocked` are the authoritative -sources for whether work is blocked. `bd list` shows active blocker -annotations but use `bd ready`/`bd blocked` for accurate blocking status. +Which tier a test belongs in, and which command runs it, is decided by +[engdocs/TESTING.md](../../engdocs/TESTING.md). -## Agent Warning: Interactive Commands +## Adding a command -**DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use. +1. Create `cmd/bd/.go` with the Cobra command and register it in that + file's `init()`. +2. Add its row to `capability_registry.go`. + `TestProxyCapabilityRegistryCoversCommandTree` fails if a command path is + missing, and `TestProxyCapabilityRegistryHasNoStaleRows` fails on rows for + paths that no longer exist. +3. If the command uses the store on proxied-server workspaces, add + `_proxied_server.go`. +4. Support `--json` for agent use. The `--json` wire surface is pinned by the + golden corpus in `protocol/` (`TestCorpusGolden`; regenerate with + `make corpus-regen` and review the diff — see `protocol/CATALOG.md`). +5. Add tests in the right tier. +6. Regenerate the CLI reference with `scripts/generate-cli-docs.sh`; + `scripts/check-cli-docs-drift.sh` fails a PR whose command-surface change + leaves the generated docs stale. -Use `bd update` with flags instead: -```bash -bd update --description "new description" -bd update --title "new title" -bd update --design "design notes" -bd update --append-notes "additional notes" # --notes replaces existing notes and requires --force once notes are set -bd update --acceptance "acceptance criteria" -``` +Prefer a flag on an existing command over a new command, and route +recovery/repair operations to `bd doctor --fix`; see the CLI design principles +in [engdocs/UI_PHILOSOPHY.md](../../engdocs/UI_PHILOSOPHY.md). -## Landing the Plane (Session Completion) +## Boundaries enforced by lint -**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds. +From `.golangci.yml` (read the rule comments there before changing scope): -**MANDATORY WORKFLOW:** +- **`cmd-bd-role-constructors` (depguard, all of `cmd/bd/**`):** "a command + reaches the reader role through store.IssueReader(), never through the + constructor: the accessor is where each storage decorator adds its layer". + The same applies to `store.Counter()`, `store.WorkspaceConfig()`, + `store.VersionReconciler()`, `store.StatsReporter()`, + `store.ReadyCounter()`, and `store.Querier()`. +- **`cmd-bd-domain-boundary` (depguard, `label.go` and `state.go`):** "bd label + and bd state reach storage through an issueops role accessor, never through + the domain use cases - see openIssueLifecycle in cmd/bd/label.go". +- **forbidigo `LabelUseCase$`:** "reach the label plane through + issueops.Lifecycle (Patch.Labels) and issueops.Reader, never the domain use + case". +- **forbidigo `types.IssueFilter` / `types.WorkFilter`:** "do not write a + filter here: take one back from a builder in internal/workapi, or pass the + whole request to issueops.Reader". `cmd/bd` denies these by default; the + files allowed to build their own filters are listed, with reasons, in + `.golangci.yml`. +- **forbidigo `fmt.Print*` / `os.Stdout` in list/graph code:** "route format + output through the command writer; mark an intentional non-format path + locally". -1. **File issues for remaining work** - Create issues for anything that needs follow-up -2. **Run quality gates** (if code changed) - Tests, linters, builds -3. **Update issue status** - Close finished work, update in-progress items -4. **PUSH TO REMOTE** - This is MANDATORY: - ```bash - git pull --rebase - git push - git status # MUST show "up to date with origin" - ``` -5. **Clean up** - Clear stashes, prune remote branches -6. **Verify** - All changes committed AND pushed -7. **Hand off** - Provide context for next session +A deliberate exception is marked on its line with +`//nolint:forbidigo // `; the reason is expected (review checks it; +no linter enforces it). -**CRITICAL RULES:** -- Work is NOT complete until `git push` succeeds -- NEVER stop before pushing - that leaves work stranded locally -- NEVER say "ready to push when you are" - YOU must push -- If push fails, resolve and retry until it succeeds +## Guard tests +- `TestEveryStoreConstructionActivatesTheEventsJournal` — every store + construction site activates the events journal; new non-bead-writing sites + go in its exemption table with a reason. +- `TestProxyCapabilityRegistryCoversCommandTree` and the other + `TestProxyCapabilityRegistry*` tests — the registry stays complete and + consistent. +- `TestCobraParallelPolicyGuard` — a test that calls `t.Parallel()` must not + call the Cobra methods in `cobraParallelUnsafeMethods`; drop `t.Parallel()` + or serialize the call under `stdioMutex`. +- `TestCorpusGolden` (`protocol/`) — no unreviewed change to the `--json` + wire shapes. + +Fresh-workspace command fixtures call `isolateBeadsDirForTest(t)` before +setup or dispatch and must not use `t.Parallel()`. diff --git a/cmd/bd/BUILD.bazel b/cmd/bd/BUILD.bazel index 55b65d61f..a7098035f 100644 --- a/cmd/bd/BUILD.bazel +++ b/cmd/bd/BUILD.bazel @@ -1556,6 +1556,13 @@ exports_files( visibility = ["//test/docsync:__pkg__"], ) +# Contributor agent instructions; root AGENTS.md links them and +# //:docsync_files checks those links. +exports_files( + ["AGENTS.md"], + visibility = ["//:__pkg__"], +) + # Release-metadata surfaces gated by //internal/versioncheck's releaseSources # table: the canonical version and the Windows PE resource files. Aggregated # into //:release_metadata_files, which is what the tests declare as data. diff --git a/cmd/bd/CLAUDE.md b/cmd/bd/CLAUDE.md new file mode 120000 index 000000000..47dc3e3d8 --- /dev/null +++ b/cmd/bd/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/docs/integrations/github-copilot.md b/docs/integrations/github-copilot.md index 0ba03ffcd..045fff66b 100644 --- a/docs/integrations/github-copilot.md +++ b/docs/integrations/github-copilot.md @@ -207,4 +207,4 @@ This page covers VS Code. For JetBrains IDEs, check whether your IDE supports MC - [Copilot CLI](/integrations/copilot-cli) - Terminal-based Copilot integration - [Quickstart](/getting-started/quickstart) - bd command basics - [Installation](/getting-started/installation) - Full install guide -- [Agent Instructions](https://github.com/gastownhall/beads/blob/main/AGENT_INSTRUCTIONS.md) - Full agent workflow reference +- [IDE and Agent Setup](/getting-started/ide-setup) - Agent integration profiles and setup diff --git a/docs/reference/faq.md b/docs/reference/faq.md index 657a0ed50..af2ae995f 100644 --- a/docs/reference/faq.md +++ b/docs/reference/faq.md @@ -46,6 +46,25 @@ Nothing specific — it's a metaphor for linked work items, like beads on a stri Beads is a 1.x product used in production for AI-assisted development. The core functionality — create, update, dependencies, ready work, Dolt-backed sync — is stable, and releases follow semantic versioning. Data stays portable: `bd export` produces human-readable JSONL, and `bd backup` pushes Dolt-native backups. As with any tracker holding work you care about, keep normal backup hygiene (a Dolt remote or a `bd backup` destination). +### Does bd collect usage metrics? + +`bd` collects anonymous command-usage metrics. Each event is a `cli_command` +record carrying only the command name; each batch also carries the bd version +and OS platform, keyed by a machine-derived, HMAC-protected distinct ID. No +email, repo path, remote URL, issue content, or user-supplied strings are +collected. Events are written under `~/.beads/eventsData` and POSTed to +`https://gastownhall-eventsapi.com/mp/collect`. + +Metrics are enabled by default (opt-out). The friendliest way to see or change +them is `bd metrics` (`bd metrics on` / `bd metrics off` / `bd metrics example`), +which takes effect on the next command with no restart. `BD_DISABLE_METRICS=1` +still works as a one-off, shell-scoped override. The cross-tool +[`DO_NOT_TRACK`](https://donottrack.sh/) standard is honored as a disable-only +opt-out: `DO_NOT_TRACK=1` opts out, while a falsey or empty value +(`DO_NOT_TRACK=0`, `false`, or unset-but-present) falls through to your saved +`bd metrics` preference instead of forcing metrics back on. `BD_DISABLE_METRICS` +is the bidirectional override and takes precedence when both are set. + ## Architecture ### Why Dolt instead of plain SQLite or flat files? diff --git a/engdocs/AGENTS.md b/engdocs/AGENTS.md new file mode 100644 index 000000000..40fdbdcf2 --- /dev/null +++ b/engdocs/AGENTS.md @@ -0,0 +1,45 @@ +# engdocs/ — contributor notes + +`engdocs/` holds contributor and internals documentation. It is read on +GitHub, not published: local links must be exact relative file paths, and +`TestEngdocsAndRootMarkdownLinks` in `test/docsync` fails on any that do not +resolve. User-facing documentation lives in `docs/` (the Mintlify site) and +follows the `beads-docs` skill. + +## What lives where + +| Path | Contents | +|---|---| +| `PROJECT_CHARTER.md` | Product boundary: what belongs in core, an integration, or the orchestration layer. | +| `TESTING.md`, `LINTING.md` | Canonical test and lint policy. | +| `ERROR_HANDLING.md`, `UI_PHILOSOPHY.md` | Conventions for errors and CLI output. | +| `ADDING_AN_ISSUEOPS_ROLE.md` | How to add a storage operation end to end. | +| `EXTENDING.md`, `INTEGRATION_CHARTER.md` | Extension and integration boundaries. | +| `AGENT_SIGNING.md` | Signatures for agent-prepared commits, comments, and reviews. | +| `design/` | Design documents for subsystems (Dolt concurrency, `bd serve`, ownership hand-off, …). | +| `adr/` | Architecture decision records, `-.md`, each with a `## Status` section. Accepted ADRs are superseded by a new ADR, not rewritten. | +| `decisions/` | Dated decision records for the docs tooling. | +| `staged-for-removal/` | Docs that no longer meet the active-doc bar (see `staged-for-removal/MANIFEST.md`). Do not link to or update them. | + +## Code orientation + +- `cmd/bd/` — the CLI (see [cmd/bd/AGENTS.md](../cmd/bd/AGENTS.md)). +- `internal/workapi/` — the work-query contract shared by every bd frontend: + filter construction, defaults, validation, response shaping. +- `internal/httpapi/` — the `bd serve` HTTP surface + ([SERVE_RUNBOOK.md](SERVE_RUNBOOK.md)). +- `internal/storage/` — shared storage interface and value types, plus + `HookFiringStore` and its `hook_*.go` decorators, which fire + on_create/on_update/on_close hooks after successful mutations. +- `internal/storage/issueops/` — transaction-scoped SQL operations shared by + the server-mode (`internal/storage/dolt/`) and embedded + (`internal/storage/embeddeddolt/`) stores. +- `internal/storage/schema/` — schema and migrations + ([migrations/README.md](../internal/storage/schema/migrations/README.md)). +- `internal/doltserver/` — lifecycle of a local `dolt sql-server` process. +- `beads.go`, `backend/`, `issueops/`, `journalops/`, `memoryops/`, + `format/`, `beadserrors/` — the public Go API for extending bd and for + out-of-tree storage backends. + +Each package's doc comment (`go doc ./internal/`) is the authoritative +description; prefer it over prose here when they disagree, and fix this file. diff --git a/engdocs/CLAUDE.md b/engdocs/CLAUDE.md deleted file mode 100644 index c59967dd1..000000000 --- a/engdocs/CLAUDE.md +++ /dev/null @@ -1,93 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -**beads** (command: `bd`) is a Dolt-powered issue tracker for AI-supervised coding workflows. Git integration is optional — see `BEADS_DIR` + `--stealth` for git-free operation. We dogfood our own tool. - -**IMPORTANT**: See [AGENTS.md](../AGENTS.md) for complete workflow instructions, bd commands, and development guidelines. - -## Architecture Overview - -### Three-Layer Design - -1. **Storage Layer** (`internal/storage/`) - - **Dolt** in `storage/dolt/` — version-controlled SQL database with cell-level merge - - Common types and interfaces in `storage.go` - -2. **Database Runtime Layer** - - Embedded mode runs Dolt in-process through `internal/storage/embeddeddolt/` - - Server mode uses `internal/doltserver/` and `internal/storage/db/` - - Proxy and pidfile helpers live under `internal/storage/db/` - - Storage-facing server adapters live under `internal/storage/doltserver/` - -3. **CLI Layer** (`cmd/bd/`) - - Cobra-based commands (one file per command: `create.go`, `list.go`, etc.) - - Direct database access (embedded mode for standalone, server mode for orchestrator) - - All commands support `--json` for programmatic use - - Main entry point in `main.go` - -### Storage Architecture - -Beads uses **Dolt** as its storage backend — a version-controlled SQL database: - -``` -Dolt DB (.beads/dolt/) - ↕ Dolt commits (automatic per write) - ↕ Dolt push/pull (native sync) -Remote (Dolt remotes: DoltHub, S3, GCS, etc.) -``` - -- **Write path**: CLI → Dolt → auto-commit to Dolt history -- **Read path**: Direct SQL queries against Dolt -- **Sync**: Dolt handles versioning and sync natively via `bd dolt push` / `bd dolt pull` -- **Hash-based IDs**: Automatic collision prevention (v0.20+) - -Core implementation: -- Dolt storage: `internal/storage/dolt/` -- Embedded runtime: `internal/storage/embeddeddolt/` -- Server runtime: `internal/doltserver/`, `internal/storage/db/`, and `internal/storage/doltserver/` -- Sync commands: `cmd/bd/dolt_*.go`, `cmd/bd/sync_*.go` - -### Key Data Types - -See `internal/types/types.go`: -- `Issue`: Core work item (title, description, status, priority, etc.) -- `Dependency`: Four types (blocks, related, parent-child, discovered-from) -- `Label`: Flexible tagging system -- `Comment`: Threaded discussions -- `Event`: Full audit trail - -## Development Command Source - -Use the canonical [TESTING.md](TESTING.md) for test commands, test design, and -PR-readiness gates. This file should not duplicate command matrices or -version-management workflows. - -> **Do NOT** use `go build -o bd` or `go install` directly — they create -> stale binaries that shadow `~/.local/bin/bd`. Always use `make install`. - -## Testing - -Testing guidance lives in [TESTING.md](TESTING.md). Architecture-specific notes -for Claude are limited to where tests touch agent setup, hooks, or -instruction-file generation. - -## Important Notes - -- **Always read AGENTS.md first** - it has the complete workflow -- Check for duplicates proactively: `bd duplicates --auto-merge` -- Use `--json` flags for all programmatic use - -## Key Files - -- **AGENTS.md** - Complete workflow and development guide (READ THIS!) -- **README.md** - User-facing documentation -- **ADVANCED.md** - Advanced features (rename, merge, compaction) -- **docs/core-concepts/labels.md** - Complete label system guide -- **docs/reference/configuration.md** - Configuration system - -## When Adding Features - -See AGENTS.md "Adding a New Command" and "Adding Storage Features" sections for step-by-step guidance. diff --git a/engdocs/CLAUDE.md b/engdocs/CLAUDE.md new file mode 120000 index 000000000..47dc3e3d8 --- /dev/null +++ b/engdocs/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/engdocs/DOC_INVENTORY.md b/engdocs/DOC_INVENTORY.md index 21e77acfa..02ec666e1 100644 --- a/engdocs/DOC_INVENTORY.md +++ b/engdocs/DOC_INVENTORY.md @@ -63,7 +63,7 @@ Follow-up automation should replace marker-only checks with generated or | `BDP_GRAPH_ARCHITECTURE.md` | Keep | Graph-plane design record; ruled contracts and dated dependency sources, not runtime or merge clearance. | | `BDP_GRAPH_CLI_AND_STORAGE_SPEC.md` | Keep | Graph-plane design record; ruled contracts and dated dependency sources, not runtime or merge clearance. | | `CLAUDE_INTEGRATION.md` | Keep | Design/user guide for Claude setup; paired with `SETUP.md`. | -| `CLAUDE.md` | Revise | Kept as architecture orientation only; command/workflow duplication was reduced in favour of root `AGENTS.md` and `AGENT_INSTRUCTIONS.md`. | +| `AGENTS.md` (`CLAUDE.md` is a symlink to it) | Keep | Contributor orientation for `engdocs/`: verified pointers only; workflow rules live in the root `AGENTS.md`. | | `CLI_REFERENCE.md` | Keep/generated | Generated command reference from live help output. | | `CI_CLEANUP_PLAN.md` | Keep as maintainer context | Dated CI policy, measurements, and implementation roadmap; current commands live in workflows and the `Makefile`. | | `CI_REQUIRED_CHECK_TOPOLOGY.md` | Keep as maintainer context | Implemented workflow design record for aggregate-gate policy; branch-protection and ruleset adoption remain pending. Live job membership and display names come from `.github/workflows/*.yml` and their structural tests; copied wiring and rollout steps are historical snapshots. | diff --git a/engdocs/TESTING.md b/engdocs/TESTING.md index 2bff6b677..c4970caef 100644 --- a/engdocs/TESTING.md +++ b/engdocs/TESTING.md @@ -195,6 +195,12 @@ rm -rf -- "$beads_manual_dir" itself redirect `bd init` workspace setup. Never run a manual `bd init` from a production workspace merely because `BEADS_DB` points elsewhere. +**Tmpfs hosts:** the `cmd/bd` test suite creates an isolated `$HOME` and several +test binaries under `$TMPDIR`. They are normally cleaned by the test process, +but a SIGKILLed or OOMed run can leave orphans behind. On hosts where `/tmp` +is tmpfs (e.g. Fedora Atomic / Bluefin), run `make clean-test-tmp` between +test runs if `du -sh /tmp/beads-* /tmp/bd-*` shows accumulation. See bd-3q2u. + `testing.Short()` is for genuine runtime, stress, or large-fixture skips. It is not a substitute for declaring an integration, end-to-end, API, Docker, or external-dependency boundary. Keep new uses within the repository policy: diff --git a/engdocs/UI_PHILOSOPHY.md b/engdocs/UI_PHILOSOPHY.md index f7cf87c44..201e66f5c 100644 --- a/engdocs/UI_PHILOSOPHY.md +++ b/engdocs/UI_PHILOSOPHY.md @@ -106,6 +106,113 @@ Following Tufte's principle of layered information: 5. **Descriptions** - Plain, primary content 6. **Examples** - Plain, copy-paste friendly +## Visual Design System + +When adding CLI output features, follow these design principles for consistent, +cognitively friendly visuals. + +### No Emoji-Style Icons + +Do not use large colored emoji icons like red/orange/yellow/blue/white circles +for priorities or status. They cause cognitive overload and break visual +consistency. + +Use small Unicode symbols with semantic colors applied via lipgloss: + +- Status: `○ ◐ ● ✓ ❄` +- Priority: `P0`–`P4` label with color (no status glyph) + +### Status Icons + +Use these symbols consistently across all commands: + +```text +○ open - Available to work (white/default) +◐ in_progress - Currently being worked (yellow) +● blocked - Waiting on dependencies (red) +✓ closed - Completed (muted gray) +❄ deferred - Scheduled for later (blue/muted) +``` + +### Priority Labels and Colors + +Format priority as the P-label with color only (no status glyph — `●` is blocked status): + +- `P0`: Red + bold (critical) +- `P1`: Orange (high) +- `P2`: Amber (elevated) +- `P3`–`P4`: Default text + +### Issue Type Colors + +- `bug`: Red (problems need attention) +- `epic`: Purple (larger scope) +- Others: Default text + +### Design Principles + +1. Small Unicode symbols only; avoid emoji blobs. +2. Semantic colors only for actionable items; do not color everything. +3. Closed items fade using muted gray. +4. Prefer icons over text labels for scanability. +5. Keep icons consistent across list, graph, show, and related commands. +6. Use tree connectors (`├──`, `└──`, `│`) for hierarchies. +7. Reduce cognitive noise; do not show `needs:1` when it is just the parent epic. + +### Semantic Styles + +Use exported styles from `internal/ui/styles.go`: + +```go +// Status styles +ui.StatusInProgressStyle // Yellow - active work +ui.StatusBlockedStyle // Red - needs attention +ui.StatusClosedStyle // Muted gray - done + +// Priority styles +ui.PriorityP0Style // Red + bold +ui.PriorityP1Style // Orange + +// Type styles +ui.TypeBugStyle // Red +ui.TypeEpicStyle // Purple + +// General styles +ui.PassStyle, ui.WarnStyle, ui.FailStyle +ui.MutedStyle, ui.AccentStyle +ui.RenderMuted(text), ui.RenderAccent(text) +``` + +Example: + +```go +switch issue.Status { +case types.StatusOpen: + icon = "○" +case types.StatusInProgress: + icon = ui.StatusInProgressStyle.Render("◐") +case types.StatusBlocked: + icon = ui.StatusBlockedStyle.Render("●") +case types.StatusClosed: + icon = ui.StatusClosedStyle.Render("✓") +} +``` + +## CLI Design Principles + +**Minimize cognitive overload.** Every new command, flag, or option adds cognitive burden for users. Before adding anything: + +1. **Recovery/fix operations → `bd doctor --fix`**: Don't create separate commands like `bd recover` or `bd repair`. Doctor already detects problems - let `--fix` handle remediation. This keeps all health-related operations in one discoverable place. + For git hook marker migration specifically: use `bd migrate hooks --dry-run` to preview operations, and `bd doctor --fix` for the standard apply path. + +2. **Prefer flags on existing commands**: Before creating a new command, ask: "Can this be a flag on an existing command?" Example: `bd list --stale` instead of `bd stale`. + +3. **Consolidate related operations**: Related operations should live together. Version control uses `bd vc {log,diff,commit}`, not separate top-level commands. + +4. **Count the commands**: Run `bd --help` and count. If we're approaching 30+ commands, we have a discoverability problem. Consider subcommand grouping. + +5. **New commands need strong justification**: A new command should represent a fundamentally different operation, not just a convenience wrapper. + ## References - Tufte, E. (2001). *The Visual Display of Quantitative Information* diff --git a/internal/storage/schema/BUILD.bazel b/internal/storage/schema/BUILD.bazel index 5108ff37d..1975dfb22 100644 --- a/internal/storage/schema/BUILD.bazel +++ b/internal/storage/schema/BUILD.bazel @@ -179,6 +179,12 @@ filegroup( visibility = ["//internal/storage:__subpackages__"], ) +# Linked from the root and engdocs AGENTS.md; //:docsync_files checks those links. +exports_files( + ["migrations/README.md"], + visibility = ["//:__pkg__"], +) + # --- begin go_srcs (managed by tools/bazel/go_srcs.py; run `make bazel-sync`) --- filegroup( diff --git a/scripts/check-doc-flags.sh b/scripts/check-doc-flags.sh index 96ce8d39a..72d2bf3b9 100755 --- a/scripts/check-doc-flags.sh +++ b/scripts/check-doc-flags.sh @@ -67,7 +67,7 @@ echo "=== Check 1: Removed commands ===" SYNC_REFS=$(grep -rn 'bd sync\b' \ "$PROJECT_ROOT"/docs/*.md \ "$PROJECT_ROOT"/docs/*/*.md \ - "$PROJECT_ROOT"/AGENT_INSTRUCTIONS.md \ + "$PROJECT_ROOT"/cmd/bd/AGENTS.md \ "$PROJECT_ROOT"/AGENTS.md \ "$PROJECT_ROOT"/README.md \ "$PROJECT_ROOT"/npm-package/*.md \ @@ -108,7 +108,7 @@ fi BRANCH_REFS=$(grep -rn 'bd init.*--branch' \ "$PROJECT_ROOT"/docs/*.md \ "$PROJECT_ROOT"/docs/*/*.md \ - "$PROJECT_ROOT"/AGENT_INSTRUCTIONS.md \ + "$PROJECT_ROOT"/cmd/bd/AGENTS.md \ "$PROJECT_ROOT"/AGENTS.md \ "$PROJECT_ROOT"/README.md \ 2>/dev/null \ @@ -135,7 +135,7 @@ echo "=== Check 3: Legacy storage references ===" SQLITE_REFS=$(grep -rn 'beads\.db\|default\.db\|sqlite3.*\.beads\|\.beads/.*\.db' \ "$PROJECT_ROOT"/docs/*.md \ "$PROJECT_ROOT"/docs/*/*.md \ - "$PROJECT_ROOT"/AGENT_INSTRUCTIONS.md \ + "$PROJECT_ROOT"/cmd/bd/AGENTS.md \ "$PROJECT_ROOT"/AGENTS.md \ "$PROJECT_ROOT"/README.md \ 2>/dev/null \ diff --git a/test/docsync/BUILD.bazel b/test/docsync/BUILD.bazel index 08c49926b..20fb12ae9 100644 --- a/test/docsync/BUILD.bazel +++ b/test/docsync/BUILD.bazel @@ -3,6 +3,7 @@ load("@rules_go//go:def.bzl", "go_test") go_test( name = "docsync_test", srcs = [ + "agentfiles_test.go", "docsync_test.go", "doltpin_test.go", "init_safety_recovery_test.go", diff --git a/test/docsync/agentfiles_test.go b/test/docsync/agentfiles_test.go new file mode 100644 index 000000000..f37e53937 --- /dev/null +++ b/test/docsync/agentfiles_test.go @@ -0,0 +1,214 @@ +package docsync + +import ( + "bytes" + "io/fs" + "os" + "path/filepath" + "regexp" + "sort" + "strings" + "testing" + + "github.com/steveyegge/beads/internal/testutil/bazeltest" +) + +// rootAgentsMaxBytes caps the root AGENTS.md. Agent tools load it into every +// session, Codex stops reading project instructions at 32 KiB combined, and +// area-specific rules belong in nested AGENTS.md files instead. +const rootAgentsMaxBytes = 20000 + +// agentFileSkipDirs are repo-relative directories whose AGENTS.md/CLAUDE.md +// files are shipped to users (product assets), not contributor instructions. +var agentFileSkipDirs = map[string]bool{ + "plugins": true, + "internal/templates": true, +} + +// backtickPathRE matches a backticked token that names a repository file. +var backtickPathRE = regexp.MustCompile("`([A-Za-z0-9_./-]+\\.(?:md|go|sh|yml|yaml|json|txt))`") + +// backtickRepoPathRE matches a backticked repo-relative path under a top-level +// source or docs directory, with or without an extension (directories and +// extensionless scripts included). Globs and placeholders are skipped by the +// caller. +var backtickRepoPathRE = regexp.MustCompile("`((?:\\.github|backend|cmd|docs|engdocs|internal|issueops|scripts|test|tests)/[^`\\s]*)`") + +// backtickTestRE matches a backticked Go test name cited as a guard. +var backtickTestRE = regexp.MustCompile("`(Test[A-Z][A-Za-z0-9_]*)`") + +var goTestFuncRE = regexp.MustCompile(`(?m)^func (Test[A-Za-z0-9_]+)\(`) + +func TestRootAgentsFileWithinBudget(t *testing.T) { + info, err := os.Stat(filepath.Join(repoRoot(), "AGENTS.md")) + if err != nil { + t.Fatalf("stat AGENTS.md: %v", err) + } + if info.Size() > rootAgentsMaxBytes { + t.Errorf("AGENTS.md is %d bytes; keep it at or under %d and move area-specific rules into a nested AGENTS.md listed in its routing table", + info.Size(), rootAgentsMaxBytes) + } +} + +// contributorAgentFiles walks the checkout for AGENTS.md files outside the +// shipped product-asset directories, returning repo-relative paths. +func contributorAgentFiles(t *testing.T, root string) []string { + t.Helper() + var files []string + err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { + if err != nil { + return err + } + rel, _ := filepath.Rel(root, path) + rel = filepath.ToSlash(rel) + if d.IsDir() { + if path != root && (strings.HasPrefix(d.Name(), ".") || d.Name() == "node_modules" || d.Name() == "testdata" || agentFileSkipDirs[rel]) { + return filepath.SkipDir + } + return nil + } + if d.Name() == "AGENTS.md" { + files = append(files, rel) + } + return nil + }) + if err != nil { + t.Fatalf("walking checkout: %v", err) + } + sort.Strings(files) + return files +} + +// TestAgentInstructionFilesAreLinkedAndRouted: every contributor AGENTS.md has +// a sibling CLAUDE.md symlink (Claude Code skips AGENTS.md files when a +// CLAUDE.md exists above them), every nested one is listed in the root routing +// table, and every local link, backticked repo path, and backticked guard-test +// name in them resolves. Make targets are not checked. +func TestAgentInstructionFilesAreLinkedAndRouted(t *testing.T) { + if bazeltest.IsBazel() { + t.Skip("walks the source checkout; Bazel runfiles hold only declared data, so this runs under go test") + } + root := repoRoot() + agentFiles := contributorAgentFiles(t, root) + if len(agentFiles) < 2 { + t.Fatalf("found %d contributor AGENTS.md files; the walk or the skip list is wrong", len(agentFiles)) + } + rootAgents, err := os.ReadFile(filepath.Join(root, "AGENTS.md")) + if err != nil { + t.Fatalf("reading AGENTS.md: %v", err) + } + + for _, rel := range agentFiles { + agentsPath := filepath.Join(root, filepath.FromSlash(rel)) + claudePath := filepath.Join(filepath.Dir(agentsPath), "CLAUDE.md") + claudeRel := filepath.ToSlash(filepath.Join(filepath.Dir(rel), "CLAUDE.md")) + info, err := os.Lstat(claudePath) + switch { + case err != nil: + t.Errorf("%s has no sibling CLAUDE.md; add one with `ln -s AGENTS.md CLAUDE.md`", rel) + case info.Mode()&os.ModeSymlink == 0: + t.Errorf("%s is a regular file; replace it with a symlink to AGENTS.md", claudeRel) + default: + agents, aerr := os.ReadFile(agentsPath) + claude, cerr := os.ReadFile(claudePath) + if aerr != nil || cerr != nil || !bytes.Equal(agents, claude) { + t.Errorf("%s does not resolve to its sibling AGENTS.md", claudeRel) + } + } + if rel != "AGENTS.md" && !bytes.Contains(rootAgents, []byte("("+rel+")")) { + t.Errorf("%s is not linked from the routing table in the root AGENTS.md", rel) + } + } + + checked := append(agentFiles, filepath.ToSlash(filepath.Join(".github", "copilot-instructions.md"))) + tests := goTestFuncNames(t, root) + var broken []string + for _, rel := range checked { + path := filepath.Join(root, filepath.FromSlash(rel)) + data, err := os.ReadFile(path) + if err != nil { + t.Fatalf("reading %s: %v", rel, err) + } + content := stripCodeFences(string(data)) + for _, target := range extractMarkdownLinks(content) { + if isExternalLink(target) { + continue + } + if idx := strings.IndexAny(target, "#?"); idx >= 0 { + target = target[:idx] + } + if target == "" { + continue + } + if _, err := os.Stat(filepath.Join(filepath.Dir(path), filepath.FromSlash(target))); err != nil { + broken = append(broken, rel+" -> "+target) + } + } + for _, m := range backtickPathRE.FindAllStringSubmatch(content, -1) { + ref := filepath.FromSlash(m[1]) + if _, err := os.Stat(filepath.Join(filepath.Dir(path), ref)); err == nil { + continue + } + if _, err := os.Stat(filepath.Join(root, ref)); err == nil { + continue + } + broken = append(broken, rel+" -> `"+m[1]+"`") + } + for _, m := range backtickRepoPathRE.FindAllStringSubmatch(content, -1) { + ref := m[1] + if strings.ContainsAny(ref, "*{}<>$") { + continue + } + // "file.go:Symbol" cites a symbol inside a file; check the file. + ref, _, _ = strings.Cut(ref, ":") + if _, err := os.Stat(filepath.Join(root, filepath.FromSlash(ref))); err != nil { + broken = append(broken, rel+" -> `"+m[1]+"`") + } + } + for _, m := range backtickTestRE.FindAllStringSubmatch(content, -1) { + if !tests[m[1]] { + broken = append(broken, rel+" -> guard test "+m[1]+" does not exist") + } + } + } + if len(broken) > 0 { + sort.Strings(broken) + t.Errorf("agent instruction files reference paths that do not exist (%d):", len(broken)) + for _, b := range broken { + t.Errorf(" %s", b) + } + } +} + +// goTestFuncNames returns the names of every top-level Test function in the +// checkout's Go test files. +func goTestFuncNames(t *testing.T, root string) map[string]bool { + t.Helper() + names := make(map[string]bool) + err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { + if err != nil { + return err + } + if d.IsDir() { + if path != root && (strings.HasPrefix(d.Name(), ".") || d.Name() == "node_modules") { + return filepath.SkipDir + } + return nil + } + if !strings.HasSuffix(path, "_test.go") { + return nil + } + data, err := os.ReadFile(path) + if err != nil { + return err + } + for _, m := range goTestFuncRE.FindAllSubmatch(data, -1) { + names[string(m[1])] = true + } + return nil + }) + if err != nil { + t.Fatalf("collecting Go test names: %v", err) + } + return names +} diff --git a/test/docsync/docsync_test.go b/test/docsync/docsync_test.go index a8ed82773..df734e1f9 100644 --- a/test/docsync/docsync_test.go +++ b/test/docsync/docsync_test.go @@ -57,6 +57,7 @@ var rootDocFiles = []string{ "CLAUDE.md", "RELEASING.md", "PR_MAINTAINER_GUIDELINES.md", + "ROADMAP.md", } func collectMintPages(v any, out *[]string) { diff --git a/tools/bazel/equivalence_allowlist.txt b/tools/bazel/equivalence_allowlist.txt index 83e84b128..7d95926b5 100644 --- a/tools/bazel/equivalence_allowlist.txt +++ b/tools/bazel/equivalence_allowlist.txt @@ -30,6 +30,7 @@ scripts TestBazelNoRemoteEndpointsInTrackedFiles skip # scans git-tracked files scripts TestBazelTestTagsFollowTaxonomy skip # reads every BUILD file in the checkout; runs under go test scripts TestBazelTreeGoSrcsListsEveryPackage skip # walks the source checkout; runs under go test scripts TestCheckTestingShortPassesOnCleanRepoTree skip # walks the whole checkout; runs under go test +test/docsync TestAgentInstructionFilesAreLinkedAndRouted skip # walks the source checkout for every AGENTS.md; runs under go test scripts TestReleaseFormula* skip # .beads/ is in .bazelignore, so the formula cannot be data; runs under go test # Policy tests whose inputs (other packages' BUILD files, .github/scripts,