Commit graph

7 commits

Author SHA1 Message Date
Steve Yegge
a530479774 test(protocol): pin the §J interchange clauses; fix the bd import header gap (wy-ltox1)
WP2 of the beads protocol conformance corpus (PROPOSAL-beads-protocol-v0 §11).
Seven §J clauses had no test; the keystone one had no test anywhere.

cmd/bd/protocol/interchange_test.go pins:

  J6.6  export -> import into an EMPTY store -> export reproduces the stream.
        bd-go had same-DB byte-stability and per-field round-trip tests, but
        nothing asserted CROSS-store equivalence — the exact blind spot where an
        import that drops, defaults, or rewrites a field hides. The fixture
        spans P0 (the zero-value priority), every core issue_type, a closed
        issue with close_reason, labels, inline comments, both dep orientations,
        metadata, assignee, and memories.
  J1.2  unknown fields ignored — a record carrying future fields at the top
        level, inside a dependency, and inside a comment still imports cleanly.
  J1.3  `_schema` header records skipped, on both the file and stdin readers.
  J6.1  import never deletes: a partial stream does not remove the ids it omits.
  J6.3  a dependency whose target id is absent is skipped AND reported
        (skipped_dependencies in `bd import --json`).
  J6.5  `bd import -` reads a stream from stdin.
  J2.4  zero/unknown timestamps export as the Unix epoch, never year-0001
        (which json.Marshal refuses outright, failing the whole export).

J1.3 needed a code fix, not just a test. parseJSONLFile (the bootstrap reader)
skipped the header record, but the `bd import` reader loop — the one `bd import`
and `bd import -` both run through — did not: the header line fell through to
the issue path, unmarshaled into an empty Issue, and aborted the WHOLE import
with "validation failed for issue : title is required". So a canonical export
carrying a provenance header could not be imported at all. Verified against the
new test: it fails with exactly that error without the guard.

Two stale artifacts found during the extraction, fixed here:

  - TestCLI_Import_PrefixValidation_E2E asserted that import REJECTS a foreign
    id prefix without --skip-prefix-validation, a flag that no longer exists
    (every import path now passes SkipPrefixValidation). Being build-tagged out
    of CI (cgo && integration), it rotted unnoticed. Rewritten as
    TestCLI_Import_ForeignPrefix_E2E, pinning the behavior bd actually has —
    which the protocol requires anyway: §J6.6 round-trips through a store with
    its own prefix, and §J7.1 makes ids opaque.
  - docs/reference/json-schema.md claimed export emits schema_version per line.
    It does not (and must not): schema_version belongs to the --json command
    envelope; the interchange's version marker is the optional _schema header.
    The import --json summary field list was also missing five fields.

Gates: gofmt + go vet clean, go build ./... ok, full cmd/bd/protocol package
green (280s, -count=1).
2026-07-13 11:20:06 -07:00
Chris Sells
69e33099b8 docs: apply PR #4722 review feedback to user docs
- FAQ: fix bulk migration/export commands (tracker pull/push need explicit
  IDs; bulk lives on sync --pull-only / --pull / --push-only / --push) and
  correct the cross-project isolation claim (hydration + external targets)
- quickstart: replace the broken DOLT.md blob URL with site links
- installation: Quick Install Script heading matches its macOS/Linux/FreeBSD
  body
- rewrite 33 stale SCREAMING_CASE link labels to the target pages' titles
- add description frontmatter to the 55 authored pages missing it
- docs.json: wildcard redirects for the old /next/ and version-prefixed
  route spaces (1.0.0, 1.0.4, 1.0.5)
2026-07-12 11:06:57 -07:00
Chris Sells
5b660081ed docs: fix fact errors found by adversarial review
Every fix verified against the binary or a traced source call path:

- How Beads Works: parent-child DOES affect ready work (a blocked parent
  blocks its children — the blocked-state SQL inherits it), hash-ID
  inputs are title/description/creator/creation-time plus a collision
  nonce (live generator is internal/idgen, not the legacy one), and
  bead gates dropped from the gates bullet (currently unresolvable).
- Graph-link type strings are hyphenated (relates-to, replies-to);
  underscore forms are rejected by the parser. Fixed corpus-wide
  including the README feature bullet.
- upgrading.md: the version-era table's boundaries were refuted by git
  archaeology (embedded Dolt shipped in v0.60.0 and always used
  .beads/embeddeddolt/; nothing changed at the claimed v0.63.3
  boundary) — replaced with a layout-based identification table.
- Phantom .beads/dolt/sql-server.log path in sync-failures and the FAQ;
  the managed server writes .beads/dolt-server.log.
- FAQ: ID growth matches DefaultAdaptiveConfig (min 3, max 8,
  probability-driven), dependency-type wording no longer claims exactly
  four types, and unmeasured performance figures are hedged instead of
  stated as facts.
- quickstart: bd migrate --cleanup doesn't exist; init installs hooks
  by default (no prompt) and has no merge-driver step; ready output
  quote and bd restore recovery source corrected.
- formulas.md: step types map to issue types (task/bug/feature/epic/
  chore; anything else falls back to task — human/gate are not step
  types), and there is no built-in formula search tier.
- todo.md: bd update takes --set-labels, not --labels.
- graph-links.md: broken #dependencies fragment → #add-dependencies.
2026-07-12 10:37:17 -07:00
Chris Sells
cf2711f13e docs(nav): nest the CLI Reference under Reference
The 113-page generated CLI Reference moves from a top-level nav group to
a nested group inside Reference — Mintlify renders nested groups
collapsed by default, so the command list no longer dominates the
sidebar. The docsmint nav splice is depth-agnostic (indentation is
derived from the pages key's line), verified by regenerating and by
re-pointing its test fixture at the nested shape. Reference overview and
the beads-docs skill IA note updated.
2026-07-12 10:37:17 -07:00
Chris Sells
5c2fe0d496 docs: loss-check merge legacy docs/ originals into the site pages
Sixteen same-ground pairs reconciled: the ported website page won and every
fact living only in the older docs/ original was merged in before deleting
it (INSTALLING, SETUP, ARCHITECTURE, CONFIG, GIT_INTEGRATION, ADVANCED,
TROUBLESHOOTING, FAQ, MOLECULES, ROUTING, MULTI_REPO_AGENTS, and the five
agent-integration guides). The two divergent FAQs are now one canonical
FAQ with the comparison-first framing leading and pre-1.0 version gating
removed.

The routing pair inverted: the ported page described a routing system that
does not exist (bd routes, bd hydrate, .beads/routes.jsonl); the page was
rebuilt from the accurate sources (ROUTING.md + MULTI_REPO_AGENTS.md)
against the real surface (routing.mode config, role detection,
repos.primary/additional hydration, --repo override).

Every claim was verified against the Go source or the generated CLI
reference. Phantom surfaces removed across the corpus: bd pin/hook/pour/
wisp/routes/hydrate/reserve/lock/merge/stats, bd hooks status, bd vc
conflicts/log, bd dolt set shared-server, fictional beads_* MCP tool names
(real names taken from beads-mcp server.py), import.orphan_handling and
export.error_policy config keys, database.wal_mode/cache_size, stale
.beads/dolt/sql-server.log paths, and SQLite-era file paths. Notable
corrections: min_hash_length default is 3, .beads/metadata.json is
git-tracked, tombstone status is removed, wisps live in the main database
under an ephemeral flag.

Freshness markers moved with their content (configuration, ide-setup) and
the freshness gate + DOC_INVENTORY ledger now point at the new locations.
Load-bearing anchors preserved: #branchless-workflows-jujutsu--jj,
#circuit-breaker-server-appears-down-failing-fast, #extensible-database,
#multi-repo-hydration. Pointer stubs remain at docs/{SETUP,INSTALLING,
GIT_INTEGRATION}.md because released binaries print those paths
(allowlisted in the docsync guard).

Gates: go test ./test/docsync PASS; generate-cli-docs.sh --check PASS;
check-doc-freshness.sh PASS; mint broken-links: no broken links; mint dev
serves all sections (11 routes spot-checked at 200).
2026-07-12 10:37:07 -07:00
Chris Sells
54a7547b0d docs: canonical concept page, section overviews, and concept diagrams
- Rewrite docs/core-concepts/index.md as 'How Beads Works' — the one
  canonical concept page (modeled on Gas City's how-gas-city-works):
  problem-first framing, the bead -> dependencies -> ready-work loop, hash
  IDs, the formula -> proto -> molecule/wisp pipeline, gates, Dolt sync,
  federation, and storage modes, led by four mermaid diagrams. Other pages
  link here instead of re-deriving the model.
- Fact fixes caught while writing (verified against source/live help):
  hash IDs are content-derived SHA-256 (internal/types/id_generator.go),
  not random; bd pour/bd wisp/bd pin/bd hook are not commands (the real
  surface is bd mol pour, bd mol wisp, bd assign, bd update --claim);
  wisps are not stored in .beads-wisp/; cross-repo dependency syntax is
  external:<project>:<capability> (cmd/bd/dep.go); recovery index claimed
  SQLite errors in a Dolt product.
- Section overview pages: rewrite workflows/index, extend recovery,
  multi-agent, and integrations indexes to list every child with one-line
  summaries; add reference/index and put it in the nav.
- New concept diagrams: sequential-vs-hash ID merge collision
  (core-concepts/hash-ids) and embedded-vs-server mode
  (architecture/dolt).
- website/README.md: real build/verify instructions and parallel-run
  status for the Docusaurus site.
- Repoint example READMEs and page labels at the real quickstart page.
2026-07-12 10:37:07 -07:00
Chris Sells
a86a2c5dfc docs: port user docs into the Mintlify site tree under docs/
Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.

git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).

Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.

Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
2026-07-12 10:37:07 -07:00