* fix(show): flag comment_count as omitted when comments are not streamed
bd show --json's count-only default (be-ijck6q, pinned by
TestJSONContract_ShowOmitsOptInPayloadsByDefault) returns comment_count
with no comments key unless --include-comments is passed. A caller that
checks only `.comments` reads absence as "no comments" — wrong whenever
comment_count > 0. A caller that reads comment_count has no signal that
the array was left out on purpose rather than omitted by a client bug.
Add comments_omitted (bool, omitempty) to IssueDetails, set true only
when CommentCount > 0 and Comments was not populated. Leaves the
count-only default and its perf rationale untouched — this does not
revert cfcc95799/e538f2881, it makes the partial representation
self-announcing. Symmetric dependent_count/dependents case is a known,
separate gap left for a follow-up (not reported by ga-clgh, out of
scope here).
Did not bump JSONSchemaVersion / regen the golden corpus: this adds an
optional field via omitempty (no existing consumer's parse breaks,
no existing corpus fixture has comment_count > 0 for `show`), and
corpus-regen needs a live Dolt+Docker this sandbox doesn't have to
verify. Deferring that call to whoever can run `make corpus-regen` and
review the diff.
Fixes ga-clgh.
* fix(show): set comments_omitted on the proxied path too
The direct path flags comment_count as omitted when comments are not
streamed (ga-clgh); the proxied path silently left the flag unset. Mirror
the else-branch in proxiedBuildDetails, add proxied-path coverage for
present/included/zero cases, and document comments_omitted in the JSON
schema reference. No schema version bump: additive optional field already
emitted by the direct path.
Addresses the 2026-07-23 review on gastownhall/beads#4865.
Agent-Signature: claude-sonnet-5-medium on behalf of maphew
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
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).
- 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)
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/.