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>
This commit is contained in:
Julian Knutsen 2026-10-01 07:22:49 -07:00 • committed by GitHub
commit b81fdc0b20
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 219 additions and 73 deletions

View file

@ -85,6 +85,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
no-op in shared-server mode, which is the topology of the 2026-08-11 loss.
User-visible wherever the data directory exists but the database is gone.
- **The missing-database refusal no longer prints a ready-to-paste
`bd init --recreate-missing` command line.** It names the flag and points
to `bd help init-safety`, which keeps the full invocation behind the
diagnosis it requires (ADR 0002 Invariant 4). The refusal also fires when
the server merely could not be reached, and a stopped server, a wrong port
or a wrong data dir all look the same from there; recreating in any of them
strands the real data behind an empty namesake. Run without `--prefix`, the
old line also printed `--prefix` with no value. The `--force` and
`--reinit-local` help, `bd help init-safety` and the recovery playbook now
say that neither flag authorizes recreating a missing server-mode database.
- **`BEADS_DOLT_POOL_READ_TIMEOUT` / `dolt.pool-read-timeout` (and the write
twins) now apply to every `bd` command in server mode.** The knobs shipped in
#5089, but their env/config ladder ran only for callers of `NewFromConfig*`;

View file

@ -664,7 +664,7 @@ func localFileRecoveryPlan(plan BootstrapPlan, beadsDir string) (BootstrapPlan,
// initialized (ProjectID set) and the configured server-mode database could
// not be confirmed to exist. Creating one here would strand the existing issue
// data behind a new, empty database of the same name — the same root cause
// PR #5791 (open, not yet merged) addresses for bd init.
// the be-5up5 guards in init.go address for bd init (PR #5791).
//
// Reaching the init fall-through already implies the database was not
// confirmed: existingBootstrapDBPlan returns a settled "none" plan whenever a
@ -1111,9 +1111,9 @@ func bootstrapMissingServerDBSummary(dbName, host string, port int, probeErr err
// workspace that was already initialized elsewhere. Per GH#2363, this must
// never suggest a destructive "recreate" action as an actionable next step.
//
// The equivalent guard for `bd init` is proposed in PR #5791, which is open
// and not yet merged; this wording is kept deliberately close to it so the
// two can share one message once that lands.
// The equivalent `bd init` refusal is initGuardMissingServerDBMessage, from
// PR #5791. This wording is kept deliberately close to it so the two can be
// folded into one message.
func bootstrapMissingServerDBRefusal(dbName, host string, port int, probeErr error) error {
var b strings.Builder
if probeErr != nil {
@ -1134,8 +1134,8 @@ func bootstrapMissingServerDBRefusal(dbName, host string, port int, probeErr err
// Every route here must be followable FROM this state. `bd backup restore`
// alone is not: it restores a Dolt-native snapshot, not a `bd export`
// JSONL, and it requires an initialized database — so it silently routes
// the operator back through `bd init`, the very unguarded door this
// refusal exists to keep shut (PR #5791). Name that precondition instead
// the operator back through `bd init`, the door this refusal exists to
// keep shut (PR #5791). Name that precondition instead
// of implying it, and lead with the routes that need no init at all.
b.WriteString("\nTo recover existing data, repopulate the database rather than creating fresh.\n")
b.WriteString("Routes that work from this state:\n")

View file

@ -807,7 +807,9 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
// --reinit-local both bypass this local-only guard; they do NOT
// authorize cross-boundary operations on remote history (see
// CheckRemoteSafety at cmd/bd/init_safety.go and
// engdocs/adr/0002-init-safety-invariants.md).
// engdocs/adr/0002-init-safety-invariants.md), nor recreating a
// missing server-mode database (guardMissingServerDatabase below;
// engdocs/adr/0004-missing-database-guard-signal.md).
if reinitLocal {
// be-5up5 round 2 (review of PR #5791): --reinit-local/--force skip
// checkExistingBeadsData entirely, and the typed confirmation below
@ -2258,8 +2260,8 @@ func init() {
initCmd.Flags().Bool("setup-exclude", false, "Configure .git/info/exclude to keep beads files local (for forks)")
initCmd.Flags().Bool("skip-hooks", false, "Skip git hooks installation")
initCmd.Flags().Bool("skip-agents", false, "Skip AGENTS.md and Claude/Codex/Cursor setup generation")
initCmd.Flags().Bool("force", false, "Deprecated alias for --reinit-local. Bypasses only the LOCAL data-safety guard; does NOT authorize remote divergence (see 'bd help init-safety').")
initCmd.Flags().Bool("reinit-local", false, "Re-initialize local .beads/ over existing local data. Does NOT authorize remote divergence; see --discard-remote.")
initCmd.Flags().Bool("force", false, "Deprecated alias for --reinit-local. Bypasses only the LOCAL data-safety guard; does NOT authorize remote divergence or recreating a missing server-mode database (see 'bd help init-safety').")
initCmd.Flags().Bool("reinit-local", false, "Re-initialize local .beads/ over existing local data. Does NOT authorize remote divergence (see --discard-remote) or recreating a missing server-mode database (see --recreate-missing).")
initCmd.Flags().Bool("discard-remote", false, "Authorize discarding the configured remote's Dolt history when re-initializing. Requires --destroy-token in non-interactive mode; see 'bd help init-safety'.")
initCmd.Flags().Bool("recreate-missing", false, "Explicitly authorize creating a fresh, empty database when this project's configured server-mode database is missing or unreachable. Opt-in per invocation only; never implied by --force, config, or env (see 'bd help init-safety').")
initCmd.Flags().Bool("from-jsonl", false, "Import issues from configured import.path; refuses remote history unless --discard-remote authorizes replacement")

View file

@ -141,7 +141,16 @@ var initAllowRecreateMissing bool
// project_id (GH#2372) and is proven only by its local Dolt storage. Naming
// metadata.json in that cell would assert evidence the caller does not have,
// misdirecting an operator who audits metadata.json mid-recovery.
func initGuardMissingServerDBMessage(dbName, host string, port int, prefix string, haveProjectID bool) error {
//
// The --recreate-missing opt-in is named by flag only, never as a paste-ready
// command line (ADR 0002 Invariant 4). This refusal also fires when the server
// merely could not be reached to confirm, so whoever reads it may not yet know
// which case they are in, and a one-liner copied out of the error skips the
// diagnosis it asks for. The full invocation lives in `bd help init-safety` and
// docs/recovery/init-safety.md. The blank string parameter is the raw --prefix
// value that one-liner used to echo; it is ignored now, and kept only so the
// guard call sites stay unchanged.
func initGuardMissingServerDBMessage(dbName, host string, port int, _ string, haveProjectID bool) error {
var b strings.Builder
fmt.Fprintf(&b, "\n%s Database %q not found on server at %s:%d (or the server could not be reached to confirm).\n", ui.RenderWarn("⚠"), dbName, host, port)
if haveProjectID {
@ -166,9 +175,9 @@ func initGuardMissingServerDBMessage(dbName, host string, port int, prefix strin
b.WriteString(" bd backup restore # if a local backup snapshot exists\n")
b.WriteString(" Check .beads/backup/ for a JSONL export you can import manually.\n")
b.WriteString("\nIf you are certain no recoverable data exists and want a fresh, empty database at\n")
b.WriteString("this name, opt in explicitly for this one invocation:\n")
fmt.Fprintf(&b, " bd init --recreate-missing --prefix %s\n", prefix)
b.WriteString("\nCreate a fresh, empty database at this name (only if you are certain no\n")
b.WriteString("recoverable data exists):\n")
b.WriteString(" See 'bd help init-safety' for the --recreate-missing workflow.\n")
b.WriteString("\nAborting.")
return errors.New(b.String())

View file

@ -7,6 +7,7 @@ import (
"os"
"os/exec"
"path/filepath"
"strconv"
"strings"
"testing"
)
@ -45,27 +46,10 @@ func TestInitGuard_ForceE2EDoesNotRecreateMissingServerDB(t *testing.T) {
// Port 1 is unreachable by construction, standing in for a server
// whose database has been lost.
env := []string{}
for _, kv := range os.Environ() {
switch {
case strings.HasPrefix(kv, "BEADS_DIR="),
strings.HasPrefix(kv, "BEADS_DB="),
strings.HasPrefix(kv, "BD_DB="),
strings.HasPrefix(kv, "BEADS_DOLT_SERVER_PORT="),
strings.HasPrefix(kv, "BEADS_DOLT_SERVER_DATABASE="):
continue
}
env = append(env, kv)
}
env = append(env,
"BEADS_DOLT_SERVER_PORT=1",
"BD_NON_INTERACTIVE=1",
)
// #nosec G204 -- bd is a locally built binary, flag is a literal
cmd := exec.Command(bd, "init", flag, "--prefix", "myproject", "--skip-hooks")
cmd.Dir = projectDir
cmd.Env = env
cmd.Env = initGuardE2EEnv(t, 1)
out, err := cmd.CombinedOutput()
if err == nil {
@ -80,3 +64,71 @@ func TestInitGuard_ForceE2EDoesNotRecreateMissingServerDB(t *testing.T) {
})
}
}
// TestInitGuard_RecreateMissingE2ECreatesMissingServerDB is the success-side
// twin of the test above. The unit tests that permit --recreate-missing flip
// initAllowRecreateMissing directly, so nothing else runs the documented
// recovery command itself through what follows the guard (remote safety, the
// metadata rewrite, CREATE DATABASE). This runs the real binary against a live
// server that lacks the configured database: refused without the opt-in, and
// with it, init succeeds and the database exists on that server.
func TestInitGuard_RecreateMissingE2ECreatesMissingServerDB(t *testing.T) {
beadsDir := startProjectServerModeGuardFixture(t, "myproject")
port, err := strconv.Atoi(os.Getenv("BEADS_DOLT_SERVER_PORT"))
if err != nil {
t.Fatalf("fixture must pin BEADS_DOLT_SERVER_PORT: %v", err)
}
// The legacy-upgrade guard runs before init's own guards and refuses a
// server workspace whose local Dolt storage has no current-era version
// witness; a workspace bd initialized has one.
if err := writeLocalVersion(filepath.Join(beadsDir, localVersionFile), Version); err != nil {
t.Fatalf("write local version: %v", err)
}
if check := checkDatabaseOnServer("127.0.0.1", port, "root", "", "myproject", false); !check.Reachable || check.Exists {
t.Fatalf("precondition: server must be reachable and lack the database, got %+v", check)
}
projectDir := filepath.Dir(beadsDir)
env := initGuardE2EEnv(t, port)
args := []string{"init", "--prefix", "myproject", "--skip-hooks", "--skip-agents"}
// Without the opt-in this exact workspace is refused, so the success below
// is the flag's doing rather than a fixture init would accept anyway.
out, err := runExternalServerBD(t, projectDir, env, args...)
if err == nil || !strings.Contains(out, "not found on server") {
t.Fatalf("precondition: bd init without --recreate-missing must be refused by the missing-database guard, got err=%v:\n%s", err, out)
}
out, err = runExternalServerBD(t, projectDir, env, append(args, "--recreate-missing")...)
if err != nil {
t.Fatalf("bd init --recreate-missing must create the missing database, got %v:\n%s", err, out)
}
if check := checkDatabaseOnServer("127.0.0.1", port, "root", "", "myproject", false); !check.Reachable || !check.Exists {
t.Fatalf("bd init --recreate-missing reported success but the database is not on the server: %+v\n%s", check, out)
}
}
// initGuardE2EEnv builds a bd child environment in which only the fixture's
// files and the given port choose the server. Every BEADS_DOLT_* setting
// (shared-server mode, data dir, mode, the TestMain container's port) and the
// BEADS_DIR, BEADS_DB, BD_DB and BEADS_SHARED_SERVER_DIR overrides are
// dropped, which is what startProjectServerModeGuardFixture pins in-process.
// The mode variables are dropped rather than set to "0":
// initModeExplicitlyRequested treats any non-empty value as an explicit mode
// choice, and init would then stop inheriting server mode from metadata.json.
func initGuardE2EEnv(t *testing.T, port int) []string {
t.Helper()
env := []string{}
for _, kv := range externalServerTestEnv(t) {
name, _, _ := strings.Cut(kv, "=")
switch name {
case "BEADS_DB", "BD_DB", "BEADS_SHARED_SERVER_DIR":
continue
}
env = append(env, kv)
}
return append(env,
"BEADS_DOLT_SERVER_PORT="+strconv.Itoa(port),
"BD_NON_INTERACTIVE=1",
)
}

View file

@ -458,16 +458,50 @@ func TestInitGuardServerMessage_DiagnosticsBeforeForce(t *testing.T) {
}
}
// be-5up5: 2026-08-11 fleet-wide data loss. In server mode there is NEVER a
// local dolt/ directory, whether this is a genuine fresh clone or an existing
// project whose server-side database was lost — doltDirExists==false alone
// (GH#2433's signal) cannot tell them apart. metadata.json's project_id is
// only written by a real prior init, so a non-empty project_id here is proof
// this is an existing project recovering from a missing database, not
// GH#2433's fresh-clone case (whose fixture carries no project_id — see
// TestInitGuard_FreshCloneWithMetadataJSON above). init must refuse and
// point at bd bootstrap, not silently recreate an empty database on the
// server (the missing-database state that reproduced the 2026-08-11 loss).
// TestInitGuardMissingServerDBMessage_RefusalTextNoEcho extends ADR 0002
// Invariant 4 (error-text-no-echo) to the missing-database refusal, which the
// TestCheckRemoteSafety_*NoEcho family does not reach. The refusal must name
// --recreate-missing, since that opt-in is the documented way out, but must not
// spell out a runnable invocation of it: it also fires when the server merely
// could not be reached, and a one-liner copied from the error skips the
// diagnosis the message asks for. Both evidence arms are covered, with an empty
// prefix too, because the guard runs before --prefix is resolved and so sees
// the raw flag value, which may be "".
func TestInitGuardMissingServerDBMessage_RefusalTextNoEcho(t *testing.T) {
for _, haveProjectID := range []bool{true, false} {
for _, prefix := range []string{"myproject", ""} {
msg := initGuardMissingServerDBMessage("myproject", "127.0.0.1", 3307, prefix, haveProjectID).Error()
for _, line := range strings.Split(msg, "\n") {
if strings.Contains(line, "--recreate-missing") &&
(strings.Contains(line, "bd init") || strings.Contains(line, "--prefix")) {
t.Errorf("haveProjectID=%v prefix=%q: refusal spells out a runnable --recreate-missing invocation %q:\n%s",
haveProjectID, prefix, line, msg)
}
}
if !strings.Contains(msg, "--recreate-missing") {
t.Errorf("haveProjectID=%v prefix=%q: refusal must still name the --recreate-missing opt-in:\n%s",
haveProjectID, prefix, msg)
}
if !strings.Contains(msg, "bd help init-safety") {
t.Errorf("haveProjectID=%v prefix=%q: refusal does not point to 'bd help init-safety':\n%s",
haveProjectID, prefix, msg)
}
}
}
}
// be-5up5: 2026-08-11 fleet-wide data loss. With no local Dolt storage for
// this project, the filesystem cannot tell a genuine fresh clone from an
// existing project whose server-side database was lost — doltDirExists==false
// (GH#2433's signal) is true of both. A non-empty project_id in metadata.json
// is taken as evidence of a prior init, so this is treated as an existing
// project recovering from a missing database, not GH#2433's fresh-clone case
// (whose fixture carries no project_id — see
// TestInitGuard_FreshCloneWithMetadataJSON above; ADR 0004 records why that
// signal is kept despite clones inheriting it). init must refuse and name a
// restore path rather than bd bootstrap, and must not silently recreate an
// empty database on the server (the state that reproduced the 2026-08-11
// loss).
func TestInitGuard_ExistingProjectMissingServerDB_Refuses(t *testing.T) {
testutil.RequireDoltBinary(t)
@ -568,7 +602,7 @@ func TestInitGuard_ExistingProjectMissingServerDB_RecreateMissingAllows(t *testi
return data
}
t.Run("server_reachable_db_missing (init.go:2566)", func(t *testing.T) {
t.Run("server_reachable_db_missing", func(t *testing.T) {
testutil.RequireDoltBinary(t)
oldServerMode := serverMode
@ -613,7 +647,7 @@ func TestInitGuard_ExistingProjectMissingServerDB_RecreateMissingAllows(t *testi
}
})
t.Run("server_unreachable (init.go:2578)", func(t *testing.T) {
t.Run("server_unreachable", func(t *testing.T) {
oldServerMode := serverMode
serverMode = true
defer func() { serverMode = oldServerMode }()
@ -1088,11 +1122,14 @@ func TestInitGuard_ExistingProjectMissingServerDB_DataDirPresent_Refuses(t *test
// TestInitGuard_RecreateMissing_ReachesOptIn_DataDirPresent is the blocker
// itself: four surfaces (the --recreate-missing flag help, `bd help
// init-safety`, docs/recovery/init-safety.md and the guard's own refusal text)
// tell the operator to run `bd init --recreate-missing --prefix <p>`. With the
// told the operator to run `bd init --recreate-missing --prefix <p>`. With the
// data directory present, that command could not reach its own opt-in and
// exited 1 with the false "already initialized" message — so the documented
// recovery was a dead end, and the only thing that worked (--reinit-local
// --recreate-missing) is named nowhere.
// --recreate-missing) was named nowhere. The refusal text has since stopped
// spelling the command out (it names the flag and routes to `bd help
// init-safety`; see TestInitGuardMissingServerDBMessage_RefusalTextNoEcho),
// but the other three surfaces still document it.
func TestInitGuard_RecreateMissing_ReachesOptIn_DataDirPresent(t *testing.T) {
oldServerMode := serverMode
serverMode = true

View file

@ -31,15 +31,18 @@ FLAG SURFACE
local data. Does NOT authorize discarding
remote history. If origin has Dolt data
this will refuse — pair with
--discard-remote to override.
--discard-remote to override. Nor does it
authorize recreating a missing server-mode
database; that takes --recreate-missing.
bd init --reinit-local \ Discard the remote's Dolt history and
--discard-remote replace it with the local reinit. First
bd dolt push after this will be a
history-replacing force-push.
bd init --force Deprecated alias for --reinit-local.
Kept working for ≥2 releases.
bd init --force Deprecated alias for --reinit-local, with
the same limits. Kept working for ≥2
releases.
bd init --recreate-missing Authorize creating a fresh, empty database
when this project's configured server-mode
@ -48,7 +51,14 @@ FLAG SURFACE
--force/--reinit-local, config, or env.
Without it, bd init REFUSES rather than
silently recreating a lost database as
empty (be-5up5).
empty (be-5up5). First rule out a stopped
server or a wrong port or data dir, and
restore if you can; the playbook is
init-missing-server-db in
docs/recovery/init-safety.md. Only when
nothing is recoverable:
bd init --recreate-missing --prefix <prefix>
bd init --from-jsonl Import from configured import.path. If
origin has Dolt data, this refuses unless

View file

@ -3,7 +3,7 @@ title: Recovery Playbooks
description: Step-by-step recovery for bd init and bd dolt push/pull refusals, including the primary-key fork playbook
---
Last reviewed: 2026-09-27
Last reviewed: 2026-10-01
Freshness source: `cmd/bd/init.go`, `cmd/bd/init_safety.go`,
`cmd/bd/init_safety_test.go`, `cmd/bd/init_safety_help.go`, and
@ -46,9 +46,11 @@ bd init refuses: remote 'origin' already has Dolt history (refs/dolt/data).
**Why this happens**
`bd init --force` (or `--reinit-local`) tells `bd` to bypass the local
data-safety guard. `bd init --from-jsonl` selects a local JSONL export as
the source. But the remote already has project history. Proceeding would
create an orphan local Dolt branch with no common ancestor on origin. The
data-safety guard, and only that guard: neither flag bypasses this refusal
or the [missing server-side database refusal](#init-missing-server-db).
`bd init --from-jsonl` selects a local JSONL export as the source. But the
remote already has project history. Proceeding would create an orphan local
Dolt branch with no common ancestor on origin. The
next `bd dolt push` would either fail (no common ancestor) or — worse, if
force-pushed — destroy the team's data.
@ -224,14 +226,17 @@ issue data behind a new, empty database of the same name.
**What happened**
This workspace is in server mode and `.beads/metadata.json` carries a
`project_id`, which is written only by a real prior `bd init`. So the project
was definitely initialized at some point — but its configured database is not
on the server, or the server could not be reached to confirm.
This workspace is in server mode and shows evidence of a prior `bd init`:
`.beads/metadata.json` carries a `project_id`, or (under `--reinit-local` or
`--force`) a workspace that predates `project_id` still has a local Dolt data
directory, in which case the message cites that instead of `metadata.json`.
Yet its configured database is not on the server, or the server could not be
reached to confirm.
That is a **recovery** situation, not a fresh clone, and the two are otherwise
indistinguishable from the local filesystem alone: in server mode there is
normally no local database directory either way. `bd init` used to resolve the
That is treated as a **recovery** situation, not a fresh clone, and the two are
otherwise indistinguishable from the local filesystem alone: this project's own
database directory is absent either way, because it was never created here or
because it was lost with the local storage. `bd init` used to resolve the
ambiguity by assuming "fresh clone" and creating the database. When the
assumption was wrong, the result was a new, empty database sitting at the name
the real one used to occupy — the 2026-08-11 fleet-wide data loss.
@ -274,12 +279,34 @@ bd init --recreate-missing --prefix myproject
by `--force`, `--reinit-local`, a config key, or an environment variable,
because it authorizes the one thing this guard exists to prevent.
The refusal names `--recreate-missing` but does not print this command: it also
fires when the server merely could not be reached, so it sends you through
steps 1 and 2 here instead of handing you a line to paste. See
[ADR 0002 — Invariant 4](https://github.com/gastownhall/beads/blob/main/engdocs/adr/0002-init-safety-invariants.md).
**Limits worth knowing**
- The guard keys on `project_id`, which was introduced by GH#2372. A workspace
initialized before that has no `project_id` and is indistinguishable from a
fresh clone, so it **fails open** — `bd init` will still create the database.
- The same `project_id` is inherited by a **fresh clone**, because
Whether a workspace meets this refusal depends on two pieces of local
evidence: whether this project's own database directory
(`<dolt-data-dir>/<database>/.dolt`) exists, and whether `metadata.json`
carries a `project_id` (introduced by GH#2372). With the configured database
missing from the server, or the server unreachable:
| Local Dolt storage | `project_id` | `bd init` | `bd init --reinit-local` / `--force` |
|---|---|---|---|
| This project's database directory present | Either | Refused as already initialized, not by this guard | Not this guard; the ordinary re-init path |
| Data dir present, database directory absent | Present | This refusal | This refusal |
| Data dir present, database directory absent | Absent | Refused as already initialized, not by this guard | This refusal |
| No Dolt data dir | Present | This refusal | This refusal |
| No Dolt data dir | Absent | Proceeds, as for a fresh clone | Proceeds, as for a fresh clone |
Adding `--recreate-missing` lifts every refusal in the last four rows,
including the third row's "already initialized". It changes nothing in the
first row, where this project's database is still on local disk. In
shared-server mode the data dir is machine-global (see below), so the last two
rows rarely apply there.
- `project_id` is also inherited by a **fresh clone**, because
`.beads/metadata.json` is git-tracked by default. Cloning a beads-managed
repo whose server-side database does not exist yet therefore meets this
refusal rather than a plain first init. It fails in the safe direction —
@ -290,11 +317,6 @@ because it authorizes the one thing this guard exists to prevent.
cannot tell "never initialized here" from "initialized here, storage since
lost"), and why `--recreate-missing` is the permanent resolution path rather
than a stopgap.
- The guard applies equally to `bd init`, `bd init --reinit-local` and
`bd init --force`. If your workspace predates `project_id` and its local
Dolt storage is gone, all three refuse until you pass `--recreate-missing`;
a workspace with no local Dolt storage at all is treated as a fresh clone by
all three.
- Server mode only, and shared-server mode counts as server mode — the guard
tests for *this project's* database directory under the resolved Dolt data
dir, not for the data dir itself, which in shared mode is the machine-global

View file

@ -53,7 +53,7 @@ Follow-up automation should replace marker-only checks with generated or
| `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. |
| `adr/0003-provenance-event-log.md` | Keep | ADR; historical decision record for the `provenance_events` table and `bd provenance` command group. Status: Proposed pending a maintainer post on issue 4460. |
| `adr/0004-missing-database-guard-signal.md` | Keep | ADR; settles the proof-of-prior-init signal for the missing-database init guards. Extends `adr/0002`. Status: Proposed. |
| `adr/0004-missing-database-guard-signal.md` | Keep | ADR; settles the proof-of-prior-init signal for the missing-database init guards. Extends `adr/0002`. Status: Accepted. |
| `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. |

View file

@ -2,7 +2,7 @@
## Status
Proposed — 2026-09-16.
Accepted — 2026-10-01, landed with #5791 (proposed 2026-09-16).
Extends [ADR 0002](0002-init-safety-invariants.md), which established the
`bd init` safety invariants and the scope-bound `--force` / `--reinit-local`
@ -133,7 +133,10 @@ would need new mechanism for no safety gain.
pre-GH#2372 workspace whose local database was lost was protected under
plain `bd init` but waved through under `--reinit-local` / `--force` — the
flags an operator reaches for in a panic were the weaker path.
- `checkExistingBeadsDataAt` does not change.
- `checkExistingBeadsDataAt` needs no further change for this decision. The
probe fix described under Context, which landed in the same PR (#5791),
already gave it the Tier 1 probe ahead of `project_id` and the
coarse-directory permit condition.
- The fresh-clone false positive (GH#2433) remains by design for the cells
where it is unavoidable.
- Both guards cite this ADR, so the question stops being re-litigated each