[roodboi]

Root cause

Two gaps in the candidate guides (HACK-1315):

1. The candidate install guide told users not to run stable hack and hack-next against the same home at once, but it did not cover the stable hackd daemon. Stable hack global up (v4.2.0) runs hack daemon start whenever daemon.autoStart is on, which is the default (src/commands/global.ts, src/control-plane/sdk/config.ts). Other stable commands that talk to hackd also auto-start it (src/daemon/client.ts). So a user who stopped hackd and then ran hack global up to bring up routing had a stable daemon running on the same ~/.hack during the Compose candidate run.
2. Nothing in the candidate guides said not to commit .hack/.internal/. A project that tracks it gets a dirty working tree every time a newer generator rewrites files such as compose.override.yml.

Fix (docs only, no product behavior change)

• docs/guides/candidate-install.md: new subsection "Stop stable hackd before a Compose run" with the order hack global up, then hack daemon stop, then check that pgrep -fl "hack daemon start" prints nothing, and no stable hack commands while the candidate run uses the same ~/.hack. New subsection "Keep .hack/.internal/ out of Git" pointing at the existing hack doctor generated-files check and hack doctor --fix. The shared-state bullet list links to both.
• docs/guides/native-candidate.md (copied into the bundle as README.md): the hack-v5 Compose paragraph now gives the same order and the .hack/.internal/ rule.
• docs/guides/v5-dogfooding.md step 2: links to the new hackd subsection and repeats the order.
• docs/architecture.md: .hack/.internal is machine-local; do not hand-edit or commit it.

Doctor warning follow-up

No new code was needed. A doctor warning for tracked .hack/.internal/ files already exists: src/lib/doctor-generated-files.ts ("generated files" check, pathspec .hack/.internal), and it also ships in stable 4.2.1. The new guide text points users to it. src/commands/doctor.ts was not touched (in-flight PR #365).

Tests and evidence

• Bun 1.4.2 (mise x bun@1.4.2).
• Local focused: tests/cli-reference-docs.test.ts, tests/prerelease-plan.test.ts (checks native-candidate.md anchors), tests/doctor-generated-files.test.ts: 66 pass, 0 fail.
• bun run --cwd packages/cli typecheck exit 0; bun run --cwd packages/cli check exit 0 (warnings only, none new).
• Relative links and anchors in the 4 changed files: checked with an ad-hoc script, 0 broken. The script was proven to flag a bad anchor with a probe file.
• gitleaks 8.30.1 over origin/next..HEAD: no leaks.
• Full suite on the test host at exact head ea9b4ac8 (Bun 1.4.2): 7554 pass, 126 skip, 1 fail, across 540 files. The failure was tests/native-authored-project-recovery.test.ts "new no-host death uses real read-only quiescence facts and retires only its exact bound record" (Native process live-session observation refused (changed)). Serial reruns with --timeout 60000 failed twice on the M3 and once locally, and each also failed "new no-host recovery retains original bindings on last-await". The same 2 tests fail at bare next ec223cdb on the M3, so the failure already exists on next and is unrelated to this change. This test does not read any doc changed here. It is reported as a separate finding.
• No CLI surface or consumer agent guidance change, so docs:cli-reference and generate:agent-plugins do not apply. No unit tests were added, because this is a docs-only change.

Gaps

• I checked the commands against the source, not on a host with stable 4.2.0 installed: global up auto-start, daemon stop, and the daemon start --foreground argv that the pgrep pattern matches.
• A launchd-managed hackd normally exits 0 on SIGTERM, so launchd (KeepAlive.SuccessfulExit=false) should not restart it. The guide still tells users to re-check with pgrep before starting the candidate.

Refs HACK-1315

🤖 Generated with Claude Code

[linear-code]

HACK-1315