beads/docs/DOC_INVENTORY.md

116 lines
8.7 KiB
Markdown

# Documentation Disposition Inventory
Reviewed: 2026-05-08
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` | 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`. |
| `CONFIG.md` | `Last reviewed:` marker tied to `cmd/bd/main.go`, `cmd/bd/config.go`, and `internal/configfile/`. |
| `SETUP.md` | `Last reviewed:` marker tied to `cmd/bd/setup*.go` and `internal/recipes/`. |
| `ADO_CONFIG.md` | `Last reviewed:` marker tied to `cmd/bd/ado*.go` and `internal/ado/`. |
| `JSON_SCHEMA.md` | `Last reviewed:` marker tied to `cmd/bd/output.go`, `cmd/bd/errors.go`, and protocol tests. |
| `RECOVERY.md` | `Last reviewed:` marker tied to `cmd/bd/init*.go` safety code and tests. |
| `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` and current lint output. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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_INTEGRATION.md` | Keep | User-facing integration guide. |
| `DEPENDENCIES.md` | Keep | Behaviour doc for graph semantics. |
| `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. |
| `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 | Stale fixed-count wording removed; marker tied to current lint output. |
| `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` | Consolidated pointer | Old duplicate staged; active path points to `TESTING.md` and `TESTING_PHILOSOPHY.md`. |
| `RECOVERY.md` | Keep with freshness | Runtime recovery playbooks; marker tied to init safety constants/tests. |
| `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. |
| `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. |
| `SYNC_SETUP.md` | Revise | Links now point at canonical `DOLT.md`. |
| `TESTING.md` | Revise/canonical | Canonical test-running guide; stale line/test-count and stale skip entry removed. |
| `TESTING_PHILOSOPHY.md` | Keep | Canonical test-design guidance; duplicate/historical links removed. |
| `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`](staged-for-removal/MANIFEST.md) with original
path, reason, missing evidence, and rescue criteria.