beads/engdocs
Julian Knutsen b81fdc0b20
fix(init): #5791 follow-up — name --recreate-missing without a paste-ready command; align help, playbook and ADR 0004 (#7070)
* fix(init): name --recreate-missing in the refusal without a paste-ready command

The missing-server-database refusal added in #5791 ended with a complete
`bd init --recreate-missing --prefix <prefix>` line. ADR 0002 Invariant 4
keeps complete destructive invocations out of bd error output, and this
refusal also fires when the server merely could not be reached: a stopped
server, a wrong port and a wrong data dir all look the same from here, and
recreating in any of them strands the real data behind an empty database of
the same name. The line also echoed the raw --prefix flag value, so a run
without --prefix printed `--prefix ` with nothing after it.

The refusal now names the flag and points to `bd help init-safety`, which
keeps the full invocation behind the diagnosis it requires. The unused
prefix parameter stays as `_` so the guard call sites are unchanged.

Also:
- --force / --reinit-local flag help, `bd help init-safety` and the init
  guard comment now say neither flag authorizes recreating a missing
  server-mode database; the --recreate-missing stanza says to rule out a
  stopped server or wrong port/data dir and restore first.
- bootstrap.go comments no longer describe #5791 as open and unmerged.
- TestInitGuardMissingServerDBMessage_RefusalTextNoEcho pins the wording
  for both evidence arms, with and without a prefix.
- TestInitGuard_RecreateMissingE2ECreatesMissingServerDB runs the real
  binary against a live server lacking the database: refused without the
  flag, created with it. The unit tests flip initAllowRecreateMissing
  directly, so nothing exercised the documented command end to end.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(recovery): init-missing-server-db covers both evidence arms and the flag limits

The init-missing-server-db section described only the project_id arm of the
guard. Under --reinit-local or --force a workspace that predates project_id
is also refused when its local Dolt data directory survives, and the refusal
then cites that directory instead of metadata.json. "What happened" now
covers both arms.

"Limits worth knowing" replaces the stale "fails open" bullet with a table
of which local state meets the refusal under bd init and under
--reinit-local / --force, and what --recreate-missing changes. The
init-force-refused section now says --force / --reinit-local bypass only the
local data-safety guard, not this refusal or the remote one, and step 3 says
why the refusal names --recreate-missing without printing the command
(ADR 0002 Invariant 4).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(adr): mark ADR 0004 Accepted now that #5791 has landed

ADR 0004 (the missing-database guard signal) still read "Proposed" after the
guards implementing it merged in #5791, and its Consequences said
checkExistingBeadsDataAt "does not change" although the same PR gave it the
Tier 1 probe ahead of project_id. Record the acceptance and say what the PR
already changed; DOC_INVENTORY.md follows the status.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Eddie the Engineer <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 07:22:49 -07:00
..
adr fix(init): #5791 follow-up — name --recreate-missing without a paste-ready command; align help, playbook and ADR 0004 (#7070) 2026-10-01 07:22:49 -07:00
decisions docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
design fix(externaldeps): guard explicit claims and batch closes (#6738) 2026-10-01 01:35:54 -07:00
staged-for-removal docs: pin the Dolt version instead of steering users to releases/latest (ga-m0dlk) (#5899) 2026-08-20 22:41:24 -07:00
ADDING_AN_ISSUEOPS_ROLE.md feat(journalops): the mutation journal becomes the third facade namespace (#5552) 2026-08-10 10:58:05 -07:00
AGENT_SIGNING.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
ATTRIBUTION.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
BDP_BEAD_GRAPH_PLAN.md BDP bead-graph plan and W-arch design docs (P-1 rulings complete; docs-only) (#6154) 2026-09-28 22:12:19 -07:00
BDP_GRAPH_ARCHITECTURE.md BDP bead-graph plan and W-arch design docs (P-1 rulings complete; docs-only) (#6154) 2026-09-28 22:12:19 -07:00
BDP_GRAPH_CLI_AND_STORAGE_SPEC.md BDP bead-graph plan and W-arch design docs (P-1 rulings complete; docs-only) (#6154) 2026-09-28 22:12:19 -07:00
CI_CLEANUP_PLAN.md fix(preflight): share checkout lint authority (#5780) 2026-09-30 22:41:55 -07:00
CI_REQUIRED_CHECK_TOPOLOGY.md ci(bazel): fork PRs use rbe-west's anonymous read-only cache (#7065) 2026-10-01 05:24:06 -07:00
CI_TEST_SURFACE_AUDIT.md Fix: test suites fail closed instead of open on the ambient Dolt port when no test container is started (be-napos) (#5885) 2026-10-01 05:21:49 -07:00
CLAUDE.md docs(test): make TESTING.md canonical (bd-mrs20) (#5226) 2026-08-01 02:30:21 -07:00
COLLISION_MATH.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
complexity-baseline.txt ci: add advisory cyclomatic complexity reporting (#6081) 2026-08-30 19:05:17 -07:00
COMPLEXITY_TRACKING.md ci: add advisory cyclomatic complexity reporting (#6081) 2026-08-30 19:05:17 -07:00
CONTRIBUTOR_NAMESPACE_ISOLATION.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
DOC_INVENTORY.md fix(init): #5791 follow-up — name --recreate-missing without a paste-ready command; align help, playbook and ADR 0004 (#7070) 2026-10-01 07:22:49 -07:00
ERROR_HANDLING.md docs: port user docs into the Mintlify site tree under docs/ 2026-07-12 10:37:07 -07:00
EXCLUSIVE_LOCK.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
EXTENDING.md perf(storage): SearchIssueSummaries narrow-projection foundation (be-nu4.3) (#3458) 2026-10-01 01:19:24 -07:00
ICU-POLICY.md fix(ci): require direct workflow build tags (#5679) 2026-10-01 01:24:03 -07:00
INTEGRATION_CHARTER.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
INTERNALS.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
LINTING.md fix(preflight): share checkout lint authority (#5780) 2026-09-30 22:41:55 -07:00
messaging.md fix(doctor): recommend 'bd prune' instead of nonexistent 'bd cleanup' (#5829) 2026-08-20 05:30:47 -07:00
PERFORMANCE_TESTING.md docs(engdocs): point storage test and bench references at the Dolt packages 2026-07-18 02:43:57 +00:00
PROJECT_CHARTER.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
README_TESTING.md docs(test): make TESTING.md canonical (bd-mrs20) (#5226) 2026-08-01 02:30:21 -07:00
RELEASE-STABILITY-GATE.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
RELEASING.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
REPO_CONTEXT.md fix(context): resolve from .beads when outside a git repository (#4772) (#4792) 2026-10-01 07:08:12 -07:00
RULES_AUDIT_DESIGN.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
SECURITY-DEPENDENCY-EXCEPTIONS.md Bump Go to 1.26.5 (#4942) 2026-07-23 18:54:32 -07:00
SERVE_RUNBOOK.md docs: the ext-api-store documentation tranche — post-#5516 auth sweep, wave doc coherence, role checklist refresh (#5545) 2026-08-10 08:05:07 -07:00
TESTING.md Fix: test suites fail closed instead of open on the ambient Dolt port when no test container is started (be-napos) (#5885) 2026-10-01 05:21:49 -07:00
TESTING_PHILOSOPHY.md docs(test): make TESTING.md canonical (bd-mrs20) (#5226) 2026-08-01 02:30:21 -07:00
UI_PHILOSOPHY.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00