* fix(preflight): share checkout lint authority
Move the Beads repository's native and Windows non-CGO lint policy into a checkout-owned Go driver. The supported Make/Bash wrapper and bd preflight now execute that same authority, while generic Go repositories retain their direct lint contract and formatting is rooted at the detected project.
Fixes #5300.
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
* docs(lint): clarify shared driver scope and timeout limits
Address PR #5780 review 5191123668. Document existing inherited-tag semantics and distinguish the wrapper/preflight driver from standalone workflow and pre-commit callers.
Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell
* fix(lint): prefer the selected Windows Go toolchain (#6865)
Keep per-pass toolchain requests and deadlines while avoiding the extra auto-selection launcher under the linter. Nonstandard SDKs retain their original PATH.
Agent-Signature: codex-tui-gpt-6-astra-max on behalf of Ewen Cuthiell
* fix(lint): retain PATH for SDK directories containing separators (#6865)
Agent-Signature: codex-tui-gpt-6-astra-max on behalf of Ewen Cuthiell
* test(preflight): declare lint fixture executable for Bazel (#5300)
Agent-Signature: codex-tui-gpt-6-astra-max on behalf of Ewen Cuthiell
* fix(bazel): keep cmd/bd/testdata out of gazelle's package scan
PR #5780 adds the compilable fixture cmd/bd/testdata/preflight-go.go. Left to
itself gazelle generates a BUILD.bazel for cmd/bd/testdata, which makes it its
own package and then (a) empties cmd/bd's data = glob(["testdata/**"]) under the
default allow_empty = False and (b) puts testdata/preflight-go.go across a
package boundary from the preflight_go_fixture target that lists it.
bazel.yml's "BUILD files in sync" step runs `make bazel-sync` and fails on any
resulting drift, and fork PRs always run that job, so this was a live red whose
prescribed remedy ("commit the result") would have broken the build further.
Exclude the directory instead, and take gazelle's ordering for the data list.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(preflight): bound the lint deadline and report each check's scope
Review iteration 1 for PR #5780. Synthesis and scorecard both approve (975/1000,
no blocker or major), so this addresses non-gating findings only.
Finding 4 (Resource Lifecycle) - the 13-minute deadline could not bound the call
it guards. CombinedOutput collects through a pipe every descendant inherits, so
Wait kept blocking on a surviving golangci-lint after the context killed the
direct `go run` child. Measured on the same process shape (direct child killed at
1s, descendant holding the pipe for 8s): without WaitDelay the call returned in
8.00s, with WaitDelay in 1.50s. Sets cmd.WaitDelay so the deadline is a real
bound and the "lint check exceeded" line can actually print.
Also gates that line on err != nil, which retires the claude lane's nit (a): a
child that exits cleanly as the deadline fires is a pass, not a timeout. Measured
at the crossover, 68 of 300 passing runs would have carried a false "exceeded"
line; 0 after the gate.
Finding 1 (Change Impact) and nit 7 (Debuggability), one remedy - the PR re-roots
lint and fmt at preflightProjectRoot() but leaves runTestCheck in the caller's
cwd, so a --check run from a subdirectory mixes a repo-wide verdict with a
subtree-only one "with nothing in the output distinguishing them", and the
reported command is only reproducible from the root. CheckResult now carries the
directory each check resolved to, and the report prints it.
Took the synthesis's second arm (state the scope split) rather than re-rooting
runTestCheck, because re-rooting is a behaviour change neither lane priced: it
widens a subdirectory user's test run from 5 packages to 128, including every
Dolt-dependent package, on a repo whose full test gate the PR body already
discloses as red. The stated hazard is that the scopes are indistinguishable,
which reporting the directory discharges directly.
Finding 2 (Architectural Consistency), second clause - adds
TestBuildFlagsContractMatchesShellSource, which parses .buildflags and pins the
driver constants to it. The existing mirror test asserts today's values from the
Go side only, so the files could drift silently; buildEnvironment overrides
rather than merges -tags, so a tag added to .buildflags alone would be dropped
with every test still green. Each of the three legs was mutation-proved to red.
Declined, with the measurements that decided it:
- Finding 2's first clause (route the key comparisons through
internal/execenv.KeyEqualForOS). The two are provably equivalent today -
execenv's keyIdentityForWindows is strings.ToLower for the same documented
reason - so this is de-duplication, not a defect, and the hazard it closes
(os/exec key-identity semantics changing) is far less live than the
.buildflags drift the second clause pins. The faithful swap means threading
goos through five driver functions and ~27 test call sites in this PR's
centerpiece file, and it would put a non-stdlib dependency into pr-lint_lib,
which the binary currently does not have. Worth doing on its own footing, not
inside a non-gating cleanup.
- Nit 6 (parse GOFLAGS into fields instead of a substring test). .buildflags:22
guards its own append with `!= *gms_pure_go*`, a substring test, and the Go
code is a deliberate mirror of it. Making only the Go side stricter would
manufacture exactly the drift finding 2 warns about: on
GOFLAGS=-tags=gms_pure_go_x the shell would skip its append while the driver
performed one. The fix belongs to .buildflags and the driver together, and
.buildflags is outside this PR. The new mirror test now pins that agreement.
- Nit 5 (probe golangci-lint as well as `go`). The claude lane examined the
LookPath target change and recorded it as deliberate, with the driver's own
missing-linter error as the mitigation. The suggested alternative - have the
driver emit preflight's `--skip-lint` hint - puts a bd-specific flag into a
driver that CI also invokes, where that advice is wrong.
- Finding 3 (two false PR-body claims). Correcting the body is outward-facing
and belongs to finalize; stamped for it. Swept the in-tree copies: the PR's own
LINTING.md sentence "Toolchain requests, formatting, and lint deadlines are
unchanged" is scoped to the Windows SDK-preference paragraph it sits in and is
true there, so it is graded rather than repaired. CHANGELOG.md contains no
pr-lint entry, so the remedy's CHANGELOG half has no target in this PR.
Validation: go build, go vet and gofmt clean on the changed packages;
./scripts/pr-lint/ 12 pass / 2 Windows-only skip; ./scripts/prlintmake/ pass;
cmd/bd preflight selector pass; scripts/check-doc-freshness.sh PASSED;
make bazel-sync idempotent and bazel test //scripts/pr-lint:pr-lint_test PASSED.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* test(prlintmake): inject the pr-lint wrapper's gofmt shim through GOFMT
The merge with #6294 (be-gx8) left runPRLintWrapper relying on a
code path #6294 made deliberately loud. The helper put its gofmt shim
on PATH. Since #6294, fmt-check.sh resolves gofmt through
scripts/ci/gofmt-bin.sh, which ignores a PATH gofmt by design.
Both TestPRLintWrapper* tests still passed, but only via the
resolver's fallback. The go shim answers `go env GOVERSION` and
`go env GOROOT` with nothing, so gofmt-bin.sh warns "could not resolve
a gofmt from go.mod's go1.26.7 toolchain" and falls back to whatever
gofmt is first on PATH, which happened to be the shim. With GOFMT set
in the environment, which is #6294's documented override, the
resolver uses that value instead. Both tests then fail: exit status
127 from fmt-check.sh, and a missing aggregate failure diagnostic
because pr-lint.sh stops before `go run`. At the pre-merge head
(7f37ba5165) the same ambient GOFMT=/nonexistent run passed all 5
tests.
Pass the shim through GOFMT, as main's runFmtCheck does, and keep it
off PATH so only the go shim is found there. gofmt-bin.sh now returns
the override immediately, and the go shim sees only `version <shim>`
and `run ... ./scripts/pr-lint`. Both wrapper assertions, on the
driver arguments and on the failure diagnostic, are unchanged.
go test ./scripts/prlintmake/: 9/9 pass by default and 9/9 pass with
GOFMT=/nonexistent in the environment. Before this change the second
run was 7/9.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
13 KiB
Documentation Disposition Inventory
Graph-plane design records added: 2026-09-10. Reviewed: 2026-07-07 (paths updated 2026-07-10 for the Mintlify port: user docs now live in the docs/ site tree; this ledger and other internal docs live in engdocs/)
CI cleanup entry added: 2026-05-28
Scope: every Markdown file under docs/, including adr/, design/,
design/otel/, and the staged-for-removal bin.
Evidence bar: retained factual claims must be backed by current CLI behaviour,
current tests, or code that is used by the product. Reference-shaped docs either
need generated/checkable maintenance, or an explicit Last reviewed: marker and
freshness source.
Canonical Seams
| Seam | Canonical docs | Rule |
|---|---|---|
| Architecture | ARCHITECTURE.md, INTERNALS.md, DOLT.md, adr/, design/ |
Durable structure, package boundaries, storage model, and invariants live here. |
| Behaviour/reference | CLI_REFERENCE.md, CONFIG.md, SETUP.md, JSON_SCHEMA.md, RECOVERY.md, ERROR_HANDLING.md, TROUBLESHOOTING.md |
CLI/config/runtime contracts live here and need generation or freshness review. |
| User-facing workflow | INSTALLING.md, QUICKSTART.md, FAQ.md, SYNC_SETUP.md, integration guides, WORKTREES.md, UNINSTALLING.md |
Task-oriented user docs live here; avoid duplicating implementation tables unless linked to reference docs. |
| Maintainer/operator | root RELEASING.md, RELEASE-STABILITY-GATE.md, LINTING.md, SECURITY-DEPENDENCY-EXCEPTIONS.md, PERFORMANCE_TESTING.md, CI_TEST_SURFACE_AUDIT.md, CI_CLEANUP_PLAN.md, SERVE_RUNBOOK.md |
Maintainer process docs stay active only when tied to current scripts/checks. |
| Historical/staged | staged-for-removal/ |
Resolved audits, stale duplicates, and unsupported snapshots are preserved here until deleted or rescued. |
Reference Freshness
| Doc | Freshness path |
|---|---|
CLI_REFERENCE.md |
Generated from bd help --all. |
plugins/beads/skills/beads/resources/CLI_REFERENCE.md |
Pointer-only doc: must link to live CLI help and canonical generated docs/CLI_REFERENCE.md; do not duplicate generated command tables. |
reference/configuration.md |
Last reviewed: marker tied to cmd/bd/main.go, cmd/bd/config.go, and internal/configfile/. (Mintlify port: absorbed CONFIG.md.) |
getting-started/ide-setup.md |
Last reviewed: marker tied to cmd/bd/setup*.go and internal/recipes/. (Mintlify port: absorbed SETUP.md.) |
integrations/azure-devops.md |
Last reviewed: marker tied to cmd/bd/ado*.go and internal/ado/. (Mintlify port: was ADO_CONFIG.md.) |
reference/json-schema.md |
Last reviewed: marker tied to cmd/bd/output.go, cmd/bd/errors.go, and protocol tests. (Mintlify port: was JSON_SCHEMA.md.) |
recovery/init-safety.md |
Last reviewed: marker tied to cmd/bd/init*.go safety code and tests. (Mintlify port: was RECOVERY.md.) |
ERROR_HANDLING.md |
Last reviewed: marker tied to current command error exits and JSON error helpers. |
LINTING.md |
Last reviewed: marker tied to .golangci.yml, scripts/ci/pr-lint.sh, scripts/pr-lint/, the Makefile wrapper, and CI workflow wiring. |
SERVE_RUNBOOK.md |
Last reviewed: marker tied to the operating-envelope constants in internal/httpapi/server.go and the log fields in its event/request emitters. |
CI_CLEANUP_PLAN.md |
Last reviewed: marker tied to the CI audit, workflow files, wrapper scripts, Makefile, package manifests, and maintainer decision review. |
design/otel/otel-data-model.md |
Last reviewed: marker tied to telemetry, Dolt storage, hooks, and AI call sites. |
Follow-up automation should replace marker-only checks with generated or
--check blocks where a clean code source exists.
Active Docs
| File | Disposition | Rationale and evidence |
|---|---|---|
ADAPTIVE_IDS.md |
Keep | Behaviour doc for hash ID scaling; verify against ID generation code before changing numeric claims. |
ADO_CONFIG.md |
Keep with freshness | ADO reference; marker points at ADO command/client code. |
AGENT_SIGNING.md |
Keep | Maintainer/operator convention for agent comment and commit signatures. |
adr/0001-multi-remote-approach.md |
Keep | ADR; historical decision record, not a live reference table. |
adr/0002-init-safety-invariants.md |
Keep | ADR backing RECOVERY.md and init safety code. |
adr/0003-provenance-event-log.md |
Keep | ADR; historical decision record for the provenance_events table and bd provenance command group. Status: Proposed pending a maintainer post on issue 4460. |
adr/0004-missing-database-guard-signal.md |
Keep | ADR; settles the proof-of-prior-init signal for the missing-database init guards. Extends adr/0002. Status: Proposed. |
ADVANCED.md |
Keep/revise as needed | User-facing advanced workflows; mixed command examples should defer to generated CLI reference when expanded. |
AIDER_INTEGRATION.md |
Keep | User-facing integration guide; evidence is setup/integration behaviour. |
ANTIVIRUS.md |
Keep | User-facing operational note; review vendor/version claims when touched. |
ARCHITECTURE.md |
Keep | Primary architecture overview; evidence is current package layout and Dolt-only storage path. |
ATTRIBUTION.md |
Keep | Attribution record for removed merge engine. |
BDP_BEAD_GRAPH_PLAN.md |
Keep | Graph-plane design record; ruled contracts and dated dependency sources, not runtime or merge clearance. |
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. |
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. |
CI_TEST_SURFACE_AUDIT.md |
Keep as historical snapshot | Dated test-surface inventory; current commands live in workflows and the Makefile. |
plugins/beads/skills/beads/resources/CLI_REFERENCE.md |
Keep pointer | Plugin skill resource intentionally points at live CLI sources to avoid duplicate generated command snapshots. |
CODEX_INTEGRATION.md |
Keep | User-facing Codex integration guide. |
COLLISION_MATH.md |
Keep | Mathematical background; low product drift. |
COMMUNITY_TOOLS.md |
Keep | Curated external tools list; external links need periodic review. |
CONFIG.md |
Keep with freshness | Reference doc; reviewed against config and env-var code. |
CONTRIBUTOR_NAMESPACE_ISOLATION.md |
Keep | Design/user guide for contributor routing and BEADS_DIR behaviour. |
COPILOT_CLI_INTEGRATION.md |
Keep | Design doc for GitHub Copilot CLI integration; paired with COPILOT_INTEGRATION.md (VS Code + MCP). |
COPILOT_INTEGRATION.md |
Keep | User-facing integration guide. |
DEPENDENCIES.md |
Keep | Behaviour doc for graph semantics. |
design/bd-serve-v0.md |
Keep | bd serve v0 contract and the decisions behind it; defers to internal/httpapi/spec/openapi.v0.yaml, internal/httpapi/doc.go and issueops/reader.go as sources of truth. |
design/dolt-concurrency.md |
Keep | Design note for Dolt concurrency. |
design/kv-store.md |
Keep | Draft design note; retain as design seam, not user reference. |
design/otel/otel-architecture.md |
Keep | Architecture/design doc for telemetry; reference tables should defer to data model. |
design/otel/otel-data-model.md |
Keep with freshness | Reference schema; reviewed against telemetry and emission code. |
DOC_INVENTORY.md |
Keep | This disposition and seam inventory. |
DOLT-BACKEND.md |
Consolidated pointer | Old duplicate staged; stable path points to canonical DOLT.md. |
DOLT.md |
Keep/canonical | Canonical Dolt backend guide. |
ERROR_HANDLING.md |
Keep with freshness | Pattern guide with code-linked examples; marker added. |
EXCLUSIVE_LOCK.md |
Keep | Behaviour/design doc for lock protocol. |
FAQ.md |
Revise | Opening wording now describes beads as Dolt-powered; stale pre-1.0 status removed. |
FEDERATION.md |
Keep/canonical | Canonical federation (peer-to-peer sync) guide; moved from root FEDERATION-SETUP.md, which is now a stable pointer. Absorbed the duplicate federation section previously in DOLT.md. |
GIT_INTEGRATION.md |
Keep | User-facing git/worktree/hook behaviour. |
graph-links.md |
Keep | Behaviour/design doc for graph links. |
ICU-POLICY.md |
Revise | Link updated to canonical Dolt doc. |
INSTALLING.md |
Keep | User-facing installation guide; install matrix needs periodic link/version review. |
INTEGRATION_CHARTER.md |
Keep | Scope-boundary policy. |
INTERNALS.md |
Keep | Internal architecture/runtime deep dive. |
JSON_SCHEMA.md |
Keep with freshness | JSON contract; marker tied to schema constant and tests. |
LABELS.md |
Keep | User-facing label philosophy plus examples; generated CLI handles command reference. |
LINTING.md |
Revise with freshness | Zero-issue wrapper contract and CI pin reviewed; marker tied to lint configuration, wrapper, and workflow wiring. |
messaging.md |
Keep | Design doc for messaging issue types. |
METADATA.md |
Keep | Behaviour doc for metadata field semantics. |
MOLECULES.md |
Keep | User-facing workflow concept doc. |
MULTI_REPO_AGENTS.md |
Keep | Agent workflow guide. |
MULTI_REPO_MIGRATION.md |
Keep | Human migration guide. |
OBSERVABILITY.md |
Keep | User-facing OTel guide; data-model reference owns schema tables. |
PERFORMANCE_TESTING.md |
Keep | Maintainer testing guide. |
PLUGIN.md |
Keep | User-facing plugin guide. |
PROJECT_CHARTER.md |
Keep | Canonical product scope and boundary policy. |
PROTECTED_BRANCHES.md |
Keep | User-facing protected-branch workflow. |
QUICKSTART.md |
Keep pointer | Short pointer to website quickstart; low drift. |
README_TESTING.md |
Compatibility pointer | Points to the sole canonical testing guide, TESTING.md. |
RECOVERY.md |
Keep with freshness | Runtime recovery playbooks; marker tied to init safety constants/tests. |
RELATED_PROJECTS.md |
Keep | Curated list of adjacent, non-integration projects; companion to COMMUNITY_TOOLS.md. |
RELEASE-STABILITY-GATE.md |
Keep | Maintainer release gate policy. |
RELEASING.md |
Consolidated pointer | Old duplicate staged; canonical process is root RELEASING.md. |
REPO_CONTEXT.md |
Keep | Architecture/behaviour doc for repo context. |
ROUTING.md |
Keep | Multi-repo auto-routing design. |
RULES_AUDIT_DESIGN.md |
Keep | Design doc for rules audit. |
SECURITY-DEPENDENCY-EXCEPTIONS.md |
Keep with freshness | Existing freshness-marker exemplar. |
SERVE_RUNBOOK.md |
Keep with freshness | Operator runbook for bd serve; the operating envelope it tabulates is constants in internal/httpapi/server.go and must be re-checked when they move. |
SETUP.md |
Keep with freshness | Setup reference; marker tied to setup commands and recipes. |
staged-for-removal/MANIFEST.md |
Keep | Staged removal process and per-file rationale. |
superpowers/plans/2026-05-03-unclaim-command.md |
Removed | PR-passenger planning artifact from a contributor's personal multi-agent rig, same class as the artifacts removed in commit 187ba85f3 (#4632); no readers in this repo, content stays in git history. |
superpowers/specs/2026-05-03-unclaim-command-design.md |
Removed | PR-passenger design-spec artifact paired with the plans file above; same removal rationale, content stays in git history. |
SYNC_CONCEPTS.md |
Keep/canonical | Sanctioned website-mirror source for the sync conceptual model (Dolt source of truth, wire format, JSONL export, anti-patterns); listed in deploy-docs.yml and linked from AGENTS.md, README.md, ARCHITECTURE.md, DOLT.md, GIT_INTEGRATION.md, and FAQ.md. |
SYNC_SETUP.md |
Revise | Links now point at canonical DOLT.md. |
TESTING.md |
Keep/canonical | Sole authority for test commands, test design, and PR-readiness guidance. |
TESTING_PHILOSOPHY.md |
Compatibility pointer | Points to the sole canonical testing guide, TESTING.md. |
TODO.md |
Keep | Behaviour/user guide for bd todo. |
TROUBLESHOOTING.md |
Keep | User-facing recovery guide; debug/env tables need freshness review when edited. |
UI_PHILOSOPHY.md |
Keep | Design philosophy. |
UNINSTALLING.md |
Keep | User-facing uninstall guide. |
WORKTREES.md |
Keep | User-facing worktree guide. |
Staged Docs
Every staged file is recorded in
staged-for-removal/MANIFEST.md with original
path, reason, missing evidence, and rescue criteria.