beads/docs
Julian Knutsen 2298c65173
docs(recovery): re-review init-safety playbooks; refresh the 90-day marker (#6411)
* docs(recovery): re-review init-safety playbooks; refresh the 90-day marker

The Last-reviewed marker crossed the 90-day freshness threshold on Sep 7,
turning 'Check doc flags freshness' (and with it PR Policy and the required
CI Gate) red for EVERY open PR — #6262 is merge-queued and UNSTABLE on
exactly this.

Reviewed against the declared freshness sources (init.go, init_safety.go,
init_safety_test.go, dolt.go), which changed materially since June
(notably the destructive-preflight replacement in #5310 and the
server-flag precedence work): the four playbooks' premises still hold —
--destroy-token/--reinit-local/--discard-remote all exist and are the
refusal remedies, the force-refusal-on-origin-history invariant is intact,
and the pk-fork-refused deep link from dolt.go:416 resolves. One drift
noted, not a correctness issue: the three init-* anchors are no longer
deep-linked from refusal messages post-#5310 (bd help init-safety links
the doc generically); a fuller playbook revalidation against the new
preflight wording is follow-up material, not a blocker.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(recovery): correct the init-safety exit-code mapping under the renewed marker

Maintainer review fixup for #6411. The marker bump renews a 90-day freshness
warranty asserting the four playbooks' premises still hold; review found one
that does not, so fix it rather than reset the clock over it.

init-local-exists was headed `Exit code: 11 (ExitLocalExistsRefused)` but led
with the "Refusing to destroy N issues in non-interactive mode." symptom,
which returns 12 (ExitDestroyTokenMissing, cmd/bd/init.go:2712-2715). Exit
11's only non-test site is the interactive typed-confirm decline
(cmd/bd/init.go:2696) — the same split cmd/bd/protocol/exit_codes_init_test.go
already documents. The section's recovery (`bd init --reinit-local`) also
dead-ended: runInitReinitPreflight gates on reinitLocal alone, so the
non-interactive caller the symptom names re-triggers the identical exit-12
refusal.

- doc: head init-local-exists with both codes, lead with the true exit-11
  interactive symptom, append --destroy-token to the non-interactive recovery,
  and add the refusal as a second symptom under init-token-missing, whose
  "Why this happens" attributed the token to --discard-remote alone.
- doc: scope the intro's "points here to a labeled anchor" claim to the
  post-#5310 reality the marker commit itself disclosed (only pk-fork-refused
  is still deep-linked).
- code: correct the ExitLocalExistsRefused and ExitDestroyTokenMissing
  comments, which are where the doc inherited its mapping error from, and
  widen the same --discard-remote-only framing in `bd help init-safety`.
- gate: add cmd/bd/dolt.go to check-doc-freshness.sh — the doc declares it a
  freshness source but the script did not enforce it, so drift in the pk-fork
  playbook's source never tripped the re-review duty.

Comment, doc, and help text only; no behavior change. Verified:
check-doc-freshness.sh PASSED 10/10 with the added source, go test ./scripts/,
the cmd/bd init-safety tests, and the cmd/bd/protocol exit-code contract tests.

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

* fix(ci): sync the doc-freshness test fixture with the init-safety source list

The maintainer review fixup for #6411 added `cmd/bd/dolt.go` to the
`docs/recovery/init-safety.md` entry of the DOCS array in
scripts/check-doc-freshness.sh (and to the doc's own `Freshness source:`
marker), but scripts/check_doc_freshness_test.go pins the same list in
`freshnessDocuments`, which it uses to build the fixture tree every
subtest runs the real script against. The fixture doc's marker line is
written from that pinned list, so the script -- correctly -- reported
`FAIL: Freshness source does not name cmd/bd/dolt.go` for every case.

That reds `.github/workflows/pr.yml`'s check-doc-freshness-platforms
matrix, which runs
`go test '-tags=integration,gms_pure_go' -count=1 -run '^TestDocFreshness' ./scripts`.
GitHub CI never saw it: the six workflows are green on the pushed head
94d76b5a4, which is the one-line marker bump alone, while the fixup that
edits the DOCS array has been local-only through the review loop.

Add `cmd/bd/dolt.go` to the pinned list so the mirror matches the script.

Validated in the adopted worktree:
- `go test '-tags=integration,gms_pure_go' -count=1 -run '^TestDocFreshness' ./scripts` -> ok
  (fails without this commit; passes at 94d76b5a4, so the break is fixup-introduced)
- `./scripts/check-doc-freshness.sh` -> PASSED against the real tree
- `go build ./...`, `go vet ./cmd/bd/... ./scripts/...` -> clean
- `go test ./test/docsync` (Mintlify nav/link guard) -> ok
- `go test ./cmd/bd/protocol -run Exit` -> ok
- the 14 `cmd/bd/init_safety_test.go` tests -> ok

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

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-09-08 10:23:04 -07:00
..
architecture docs: pin the Dolt version instead of steering users to releases/latest (ga-m0dlk) (#5899) 2026-08-20 22:41:24 -07:00
cli-reference 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
core-concepts fix(deps): enforce external capability blockers across ready/claim/close (#4769) (#4753) 2026-09-02 16:56:23 -07:00
diagrams docs: port the Excalidraw diagram pipeline (machinery only) 2026-07-12 10:37:17 -07:00
getting-started fix(upgrade-guard): parse the version witness as semver, and stop reading "unreadable" as "legacy" (#5650) 2026-08-25 00:29:17 -07:00
images docs: port user docs into the Mintlify site tree under docs/ 2026-07-12 10:37:07 -07:00
integrations docs: document ado.reconcile_interval and inventory every storage span 2026-08-07 21:20:41 +00:00
multi-agent fix(reclaim): correct the heartbeat re-home invariant's scope in the new docs (wy-sp2l4) 2026-08-13 04:30:30 -07:00
recovery docs(recovery): re-review init-safety playbooks; refresh the 90-day marker (#6411) 2026-09-08 10:23:04 -07:00
reference docs(config): document audit.enabled in configuration reference (#5940) 2026-09-02 18:11:08 -07:00
workflows fix(ui): stop using blocked ● for priority in CLI output (#5511) 2026-08-10 06:19:51 -07:00
cli-docs.pin chore(release): forward-port v1.2.2 to main (version record, retracts, recovery guide, gate record) (#5782) 2026-08-14 21:45:02 -07:00
CLI_REFERENCE.md 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
community-tools.md docs: add Beads Dashboard to Editor Extensions in community-tools.md (#5336) 2026-08-07 05:55:02 -07:00
docs.json chore(release): forward-port v1.2.2 to main (version record, retracts, recovery guide, gate record) (#5782) 2026-08-14 21:45:02 -07:00
index.md docs: align user docs and CLI reference with the v1.1.0 release (#4874) 2026-07-17 14:17:28 -07:00
RECOVERY.md docs(recovery): reduce the stub to a pure pointer 2026-07-17 18:56:33 -07:00
related-projects.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00