beads/docs
Kevin Glynn 8518e71d66
feat: BD_JSON_ENVELOPE=1 opt-in for uniform JSON wrapping (#3393)
* feat: add BD_JSON_ENVELOPE=1 opt-in for uniform JSON wrapping

Follow-up to #3368 as discussed with @maphew. Adds the envelope format
that wraps all --json output as {"schema_version": N, "data": <payload>},
gated behind BD_JSON_ENVELOPE=1 to avoid breaking existing consumers.

Legacy mode (default): unchanged behavior from #3368 — objects get
schema_version injected inline, arrays pass through raw.

Envelope mode (BD_JSON_ENVELOPE=1): uniform wrapping for all types.
The original payload is untouched inside .data — no type corruption,
no field injection. A one-time deprecation notice is emitted to stderr
when --json is used without the env var.

Timeline: envelope becomes default in v2.0, with BD_JSON_ENVELOPE=0
as a temporary escape hatch for one release cycle.

Includes:
- wrapWithSchemaVersion dual-mode logic
- outputJSONError and buildJSONError envelope support
- Deprecation notice on stderr (once per process)
- Tests for both legacy and envelope modes
- Migration guide in docs/JSON_SCHEMA.md

* fix: suppress deprecation notice when stderr is not a TTY

Gate emitEnvelopeDeprecation() on ui.IsStderrTerminal() so the
"NOTE: bd --json output format will change in v2.0" message only
appears in interactive terminals. Test harnesses and pipelines
capture stderr via CombinedOutput(), and the trailing notice after
the JSON closing brace caused json.Unmarshal to fail with
"invalid character 'N' after top-level value" in 15 CI tests.

Follows the same TTY-gating pattern used by ShouldUseColor and
ShouldUseEmoji.

* fix: suppress gosec G304 false positive in hookWorkTreeRoot

The path is filepath.Join(os.Getenv("GIT_DIR"), "gitdir") — reading a
well-known git internal file from a trusted environment variable set by
git itself during hook execution. Not a user-controlled file inclusion.

This false positive causes the Lint CI check to fail on every PR in
the repo, masking real lint issues.
2026-04-21 13:24:17 -07:00
..
adr docs: add ADR-0001 for multi-remote approach decision (#3209) 2026-04-13 13:49:04 -07:00
design cleanup: remove remaining Gas Town terminology from help text, docs, and comments 2026-03-22 13:27:43 -07:00
dev-notes docs: remove stale daemon refs and bd sync --status/--merge references 2026-02-28 19:54:49 -07:00
ADAPTIVE_IDS.md feat: support issue_id_mode=counter for sequential IDs (#2013) 2026-02-22 23:49:46 -08:00
ADO_CONFIG.md Add ADO round-trip integration tests and config documentation (#3305) 2026-04-20 18:16:53 -07:00
ADVANCED.md refactor: remove gastown/Gas Town string references from beads code and docs (bd-1ue8) 2026-03-20 18:39:50 -07:00
AIDER_INTEGRATION.md docs: replace stale bd sync references with bd dolt push/pull (GH#2442, GH#2435) 2026-03-08 10:12:08 -07:00
ANTIVIRUS.md harden installers and docs for transparent trust model (GH#1857) 2026-03-15 12:02:56 -07:00
ARCHITECTURE.md /{README,cmd}: go back to init 2026-03-28 13:47:20 -07:00
ATTRIBUTION.md fix: remove dead 3-way merge config remnants (GH#2353) 2026-03-05 15:57:33 -08:00
audit-sync-mode-complexity.md fix: complete UUID primary keys cleanup across codebase 2026-03-14 10:12:04 -07:00
CLAUDE.md refactor: remove gastown/Gas Town string references from beads code and docs (bd-1ue8) 2026-03-20 18:39:50 -07:00
CLAUDE_INTEGRATION.md docs: document bd setup command 2025-12-16 01:08:42 -08:00
CLI_REFERENCE.md /{README,cmd}: go back to init 2026-03-28 13:47:20 -07:00
COLLISION_MATH.md docs: fix broken relative links across documentation 2025-12-16 00:46:08 -08:00
COMMUNITY_TOOLS.md add Thread to community tools - analytics and observability (#3329) 2026-04-20 18:20:30 -07:00
CONFIG.md fix: enable auto-export by default and add init prompt (GH#2973) (#3204) 2026-04-13 16:02:58 -07:00
CONTRIBUTOR_NAMESPACE_ISOLATION.md cleanup: remove remaining Gas Town terminology from help text, docs, and comments 2026-03-22 13:27:43 -07:00
COPILOT_INTEGRATION.md fix: replace stale 'bd sync' references with bd dolt push/commit (GH#2435) 2026-03-07 17:00:19 +01:00
DEPENDENCIES.md docs(deps): add DEPENDENCIES.md covering dependency system and gates 2026-02-27 10:09:05 -08:00
DOLT-BACKEND.md /{cmd,docs,internal}: more cleanup 2026-03-31 12:33:52 -07:00
DOLT.md /{cmd,docs,internal}: get bootstrap and init working correctly and remote agnostic 2026-04-10 14:37:49 -07:00
ERROR_HANDLING.md docs: remove stale daemon refs and bd sync --status/--merge references 2026-02-28 19:54:49 -07:00
EXCLUSIVE_LOCK.md docs(claim): standardize start-work semantics to --claim (#2070) 2026-02-24 22:11:39 -08:00
FAQ.md /{README,cmd}: go back to init 2026-03-28 13:47:20 -07:00
GETTING_STARTED_ANALYSIS.md Use getting started docs as bugs to fix (#3034) 2026-04-05 16:09:58 -07:00
GIT_INTEGRATION.md Follow up remaining runtime .beads fallbacks after GH#3124 (#3183) 2026-04-10 21:23:14 -07:00
graph-links.md refactor: remove Gas Town references from codebase 2025-12-30 14:13:32 -08:00
ICU-POLICY.md chore(build): codify the gms_pure_go build-tag policy (GH#3303) 2026-04-16 12:28:11 -07:00
INSTALLING.md feat: make CGO_ENABLED=0 the blessed go install path (GH#3303) 2026-04-16 12:06:31 -07:00
INTEGRATION_CHARTER.md Add Integration Charter: define scope boundary for tracker integrations 2026-03-30 09:12:28 -07:00
INTERNALS.md refactor: remove gastown/Gas Town string references from beads code and docs (bd-1ue8) 2026-03-20 18:39:50 -07:00
JSON_SCHEMA.md feat: BD_JSON_ENVELOPE=1 opt-in for uniform JSON wrapping (#3393) 2026-04-21 13:24:17 -07:00
LABELS.md cleanup: remove remaining Gas Town terminology from help text, docs, and comments 2026-03-22 13:27:43 -07:00
LINTING.md docs: remove stale JSONL references from ~73 markdown files (bd-9ni.4) 2026-02-22 22:18:02 -08:00
messaging.md refactor: remove gastown/Gas Town string references from beads code and docs (bd-1ue8) 2026-03-20 18:39:50 -07:00
METADATA.md docs: document issue.metadata field and reserved key prefixes 2026-02-06 02:14:10 -05:00
MOLECULES.md Keep regular epics open after the last child closes (#3276) 2026-04-17 15:10:38 -07:00
MULTI_REPO_AGENTS.md fix: add shared Dolt server mode for multi-repo/agent setups (GH#2416) 2026-03-10 17:38:00 -07:00
MULTI_REPO_MIGRATION.md docs: replace stale bd sync references with bd dolt push/pull (GH#2442, GH#2435) 2026-03-08 10:12:08 -07:00
OBSERVABILITY.md /{cmd,docs,internal}: more cleanup 2026-03-31 12:33:52 -07:00
PERFORMANCE_TESTING.md docs: update stale SQLite references to Dolt across 10 documentation files 2026-02-16 01:22:58 -08:00
PLUGIN.md docs: remove stale JSONL references from ~73 markdown files (bd-9ni.4) 2026-02-22 22:18:02 -08:00
pr-752-chaos-testing-review.md docs: remove stale daemon references from all documentation (GH#1982) 2026-02-22 17:57:53 -08:00
PROTECTED_BRANCHES.md fix(docs): purge stale bd sync/import/--branch refs + add CI doc validation (GH#2522) 2026-03-11 13:25:40 -07:00
QUICKSTART.md docs: unify quick start (site + stub) (#3032) 2026-04-05 22:16:00 -07:00
README_TESTING.md DOCTOR IMPROVEMENTS: visual improvements/grouping + add comprehensive tests + fix gosec warnings (#656) 2025-12-20 03:10:06 -08:00
RELEASE-STABILITY-GATE.md Add release stability gate for upgrade safety (GH#2951) (#2963) 2026-04-01 17:00:25 -07:00
RELEASING.md feat(docs): version Docusaurus site and align llms-full with snapshots (#3033) 2026-04-06 21:12:54 -07:00
REPO_CONTEXT.md docs: replace stale bd sync references with bd dolt push/pull (GH#2442, GH#2435) 2026-03-08 10:12:08 -07:00
ROUTING.md docs: remove stale JSONL references from ~73 markdown files (bd-9ni.4) 2026-02-22 22:18:02 -08:00
RULES_AUDIT_DESIGN.md Add bd rules audit and bd rules compact commands (#2810) 2026-04-02 20:29:34 -07:00
SETUP.md Follow up remaining runtime .beads fallbacks after GH#3124 (#3183) 2026-04-10 21:23:14 -07:00
SYNC_SETUP.md /{cmd,docs,internal}: remove file removal that can cause data corruption 2026-03-31 12:04:55 -07:00
TESTING.md Rename ICU-only test path to explicit opt-in workflow (bd-b18) (#3291) 2026-04-16 08:54:24 -07:00
TESTING_PHILOSOPHY.md fix: remove dead 3-way merge config remnants (GH#2353) 2026-03-05 15:57:33 -08:00
TODO.md docs: remove stale JSONL references from ~73 markdown files (bd-9ni.4) 2026-02-22 22:18:02 -08:00
TROUBLESHOOTING.md /{cmd,docs,internal}: get bootstrap and init working correctly and remote agnostic 2026-04-10 14:37:49 -07:00
UI_PHILOSOPHY.md docs: consolidate duplicate UI_PHILOSOPHY files (GH#745) 2025-12-27 18:01:59 -08:00
UNINSTALLING.md docs: remove stale JSONL references from ~73 markdown files (bd-9ni.4) 2026-02-22 22:18:02 -08:00
WORKTREES.md fix(docs): purge stale bd sync/import/--branch refs + add CI doc validation (GH#2522) 2026-03-11 13:25:40 -07:00