* 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>
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 —
bd init --force/--reinit-localrefused because origin has Dolt history - init-token-missing —
--discard-remoterefused because--destroy-tokenis missing or wrong - init-local-exists —
bd initrefused because local data already exists
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.