* 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>
147 lines
4 KiB
Markdown
147 lines
4 KiB
Markdown
# 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](adr/0002-init-safety-invariants.md).
|
|
|
|
## Table of contents
|
|
|
|
- [init-force-refused — `bd init --force`/`--reinit-local` refused because origin has Dolt history](#init-force-refused)
|
|
- [init-token-missing — `--discard-remote` refused because `--destroy-token` is missing or wrong](#init-token-missing)
|
|
- [init-local-exists — `bd init` refused because local data already exists](#init-local-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](adr/0002-init-safety-invariants.md)
|
|
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.
|