beads/docs/RECOVERY.md
Steven Syrek c6d0cc2fd9
fix(init): refuse --force when remote has Dolt history (#3455)
* fix(init): refuse --force when remote has Dolt history

bd init --force in a repo whose origin has refs/dolt/data silently
skipped the bootstrap-from-remote path and then wired origin as a Dolt
remote anyway. The next write auto-pushed an orphan history, failing
with "no common ancestor". Recovery options were all destructive.

This change:

- Adds --reinit-local (named-intent replacement for --force) and
  --discard-remote (explicit cross-boundary authorization).
- Routes --force to --reinit-local with a DeprecationWarning. --force
  continues to work for ≥2 releases.
- Refuses bd init --force / --reinit-local when origin has
  refs/dolt/data, unless --discard-remote is also passed. Exit code 10
  (ExitRemoteDivergenceRefused).
- Adds stable numeric exit codes for init refusals (10/11/12).
- Adds bd init-safety documenting the full flag surface and the
  destroy-token format.
- Adds an internal race-safety re-check: if remote state changes
  during the TTY confirmation window, abort rather than overwrite.
- Retrofits the existing destroy-token echo at init.go:231 to not
  print a copy-pasteable destructive invocation, matching the new
  error-text-no-echo ADR invariant.

Adds:
- cmd/bd/init_safety.go — CheckRemoteSafety chokepoint (pure fn).
- cmd/bd/init_safety_test.go — guard matrix (13 cases) + subprocess
  regression test with a synthetic refs/dolt/data fixture.
- docs/adr/0002-init-safety-invariants.md — ADR encoding the five
  invariants (single-source identity, scope-bound --force, central
  chokepoint, error-text-no-echo, race-safety).
- docs/RECOVERY.md — named recovery playbooks per refusal exit code.
- .github/CODEOWNERS — review ownership for init*.go pointing at the
  ADR so future flags must extend the guard matrix.

Historical pattern (git log for cmd/bd/init.go): 8+ prior commits
patched individual surfaces of this class without encoding the
invariant. The guard matrix test is the structural hedge — adding a
new flag or data source is a signal to extend the table, not to add
another `&& !someFlag` at the call site.

(bd-q83)

* fix(init): satisfy lint for origin safety helpers (bd-main-nwo)

---------

Co-authored-by: matt wilkie <maphew@gmail.com>
2026-04-24 09:01:35 -07:00

4 KiB

Recovery Playbooks

This document lives next to the ADRs and matches the structure of bd's error messages: each named refusal in bd init points here to a labeled anchor with step-by-step recovery instructions.

See also: bd help init-safety, and ADR 0002 — bd init safety invariants.

Table of contents


init-force-refused

Exit code: 10 (ExitRemoteDivergenceRefused)

Symptom

bd init refuses: remote 'origin' already has Dolt history (refs/dolt/data).
  Why: --force / --reinit-local bypasses only the LOCAL data-safety
       guard. ...

Why this happens

bd init --force (or --reinit-local) tells bd to bypass the local data-safety guard. 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.

Recovery paths

Pick the one that matches your intent.

1. You want to adopt the remote's history (most common)

bd bootstrap

This clones the remote's Dolt database into a fresh local .beads/. Your local state is ignored; the team's history becomes yours.

2. You want to diagnose what went wrong before deciding

bd doctor
bd dolt status

bd doctor walks the local + remote state and names concrete problems. bd dolt status shows the Dolt-level view. Neither modifies anything.

3. You intentionally want to overwrite the remote's history (destructive)

This is a cross-boundary operation that affects every collaborator. You need to pair --reinit-local with --discard-remote. In interactive mode bd will prompt for confirmation; in non-interactive mode you must supply a --destroy-token. See bd help init-safety for the token format.

After bd init --reinit-local --discard-remote, your next bd dolt push must be a history-replacing push. Coordinate with your team before doing this.


init-token-missing

Exit code: 12 (ExitDestroyTokenMissing)

Symptom

bd init refuses: --discard-remote requires an explicit destroy-token in non-interactive mode.

Why this happens

You're running non-interactively (CI, agent, piped input) and passed --discard-remote. Destructive cross-boundary operations cannot be authorized silently.

Recovery paths

1. Run interactively

Re-run in a TTY. bd init --reinit-local --discard-remote will prompt you to type the destroy-token at confirmation time.

2. Supply the token explicitly (CI/automation)

The token format is DESTROY-<issue-prefix>. For a project whose issue prefix is bd:

bd init --reinit-local --discard-remote --destroy-token=DESTROY-bd

Automation should template the token from project state, not from error output. See ADR 0002 — Invariant 4 for why the token is never echoed in bd's error messages.


init-local-exists

Exit code: 11 (ExitLocalExistsRefused)

Symptom

Refusing to destroy N issues in non-interactive mode.
  See 'bd help init-safety' for the required --destroy-token format.

Or, in interactive mode, you declined the typed destroy N issues confirmation.

Why this happens

Local .beads/ has existing issues. bd init --reinit-local would permanently destroy them.

Recovery paths

1. Export first, then proceed

bd export > backup.jsonl
bd init --reinit-local

backup.jsonl lets you re-import individual issues if needed.

2. Investigate why you hit this

If you did NOT expect bd init to be the right command here, run bd doctor first — you may be looking at a server config issue that a re-init won't fix.