feat(doctor): environment readiness pre-checks — Docker daemon and WSL credential-store traps

[PeterGuy326]

schemaVersion: requirement-record.v1
revision: R1
status: needs-design
priority: P0
productOwner: "@PeterGuy326"
technicalOwner: "Tech P9"
userOutcome: "Before any image pull or build side effect, a new user gets a one-command readiness verdict for Docker — including the two known Windows/WSL traps — with actionable next steps instead of a dead end."
requirements:
  - REQ-001
  - REQ-002
  - REQ-003
acceptanceCriteria:
  - AC-001
  - AC-002
  - AC-003
parent: null
dependencies: []
supersedes: []
lastDecisionAt: null

User problem and observable outcome

Ops dogfood hit two mandatory traps on the official doc up --build path (both reproduced and logged 2026-08-29): (1) Docker Desktop not running → docker unavailable, full stack cannot start; docs only say "requires Docker" without a readiness check; (2) WSL + Docker Desktop: ~/.docker/config.json credsStore: desktop.exe causes fork/exec docker-credential-desktop.exe: exec format error, breaking even public image pulls — doc up --build dies at step one; ops verified recovery after removing credsStore. Both traps apply to any WSL user running doc or mem. Implementation truth belongs to Tech P9.

Observable outcome: one readiness command decides Docker health; both trap patterns are detected with stable codes and actionable guidance; pre-checks run before the first side-effectful step.

Requirements

• REQ-001: Docker daemon readiness self-check — one command determines daemon availability; failure yields a stable code plus actionable guidance (start Docker Desktop / enable WSL integration), and onboarding docs carry the same precondition.
• REQ-002: WSL credential-store trap detection — the credsStore: desktop.exe exec-format failure pattern is detected (or the pull failure is diagnosed to it) with a stable code and actionable remediation (credsStore removal steps); troubleshooting docs carry the entry.
• REQ-003: Pre-effect ordering — readiness checks execute before the first side-effectful step of doc up --build (no partial pulls/builds before the verdict); fail-closed ordering is asserted.

Acceptance criteria

• AC-001: Daemon-down fixture — readiness check fails with stable code + actionable guidance; no side effects occur before the verdict.
• AC-002: CredsStore-trap fixture (simulated config) — detected with stable code + remediation guidance; the documented fix restores pulls (ops-verified recovery as evidence input).
• AC-003: Ordering fixture — a failing readiness state prevents the first pull/build step; docs/troubleshooting entries present.

Non-goals and forbidden shortcuts

• No Docker Desktop automation (no auto-start of the daemon); detection + guidance only.
• No changes to image composition or compose topology.

Lifecycle, status, priority, blockers, and open decisions

• status=needs-design; priority P0; technicalOwner=Tech P9.
• Blockers: none.
• Open decision: mem-side cross-link — the same traps hit mem onboarding; this record lives in doc (the doc doctor surface) and mem onboarding docs cross-reference it (see the mem onboarding companion issue), unless tech adjudication prefers a shared tooling home.

Evidence plan

• Fixtures plus docs entries; ops reproduction logs (docker_cfg_fix.log) as evidence input.

Decisions

• DEC-DOC-28-001 (2026-08-29T02:26:00Z): issue created per founder-approved dogfood intake (2026-08-29); ops reproduction logs are evidence input; implementation truth belongs to Tech P9.

Revision history

• R1 (2026-08-29T02:26:00Z): initial record created per founder-approved draft B (dogfood P0 environment readiness).

[PeterGuy326]

Implementation receipt (2026-08-31): PR #31 is on main at 37ebe94 and main CI run 33324075575 passed both test and docker-build. The PR records REQ-001..003 / AC-001..003, including 58/58 CLI tests and fail-before-pull/build ordering. This receipt does not close the issue: PR #31 was administrator-merged while REVIEW_REQUIRED and has no independent review. Remaining governance gate is an independent maintainer review of the merged diff/commit with an explicit acceptance record; no additional code or CI failure is currently observed.

[PeterGuy326]

Additional live-environment receipt (2026-08-31, shared WSL workspace): npm run doc -- doctor exited 0 with doctor: healthy; Docker 27.1.1, daemon reachable 27.1.1, Compose v2.29.1-desktop.1, and Compose configuration valid. The active Linux Docker config has no desktop.exe credsStore trap. This strengthens runtime evidence but does not replace the outstanding independent governance review noted above.

[PeterGuy326]

Evidence correction and product disposition for doc #28:

1. The authoritative main CI run is https://github.com/fullstack-ai-infra/doc/actions/runs/33324075575 at 37ebe942d7a3b0d1e2a1eae6d552fbbb740ea850. Its CLI result is 59/59, superseding the earlier 58/58 count.
2. The implementation home is the doc CLI (doc doctor / doc up).
3. The mem onboarding cross-link is a separate follow-up and is not represented by an existing public companion issue at this time. Do not claim such a locator until one exists.
4. The historical PR review gate remains unsatisfied. Closing feat(doctor): environment readiness pre-checks — Docker daemon and WSL credential-store traps #28 requires an independent post-merge review of the exact merged tree.
5. AC-002 live recovery may be accepted only if the independent reviewer can inspect a safe evidence locator or independently reproduce the recovery. docker_cfg_fix.log is not currently available at a public or shared-workspace locator, so it must not be treated as independently verified evidence.

Exact provenance for that review:

• PR base: c9334d37d8267351da989ab9ad7d701a7ac053ee
• PR head: 0e82bce431a108abc8dc0d1ffd9161405270b13b
• merged main: 37ebe942d7a3b0d1e2a1eae6d552fbbb740ea850
• identical PR-head/main tree: 66febcf2808da19fbf01ba1ac1c9c643134e9a13
• PR CI: https://github.com/fullstack-ai-infra/doc/actions/runs/33323591314
• main CI: https://github.com/fullstack-ai-infra/doc/actions/runs/33324075575

This corrects the acceptance record; it does not claim the historical protected-branch review gate was satisfied.

[waterbro-8]

Doctor/Docker readiness already landed: PR #31 merged 2026-08-30 (feat(doctor): Docker environment readiness pre-checks). Remaining is owner close vs any leftover WSL credsStore AC. I am not re-implementing doctor.

[waterbro-8]

独立 post-merge review 已针对 PR #31 的 exact merged tree 完成：PR head 0e82bce 与 merged main 37ebe94 的 tree 均为 66febcf2808da19fbf01ba1ac1c9c643134e9a13。git diff --check 通过；node --test packages/cli/test/docker-readiness.test.js 为 8/8 PASS，覆盖 daemon down、WSL desktop.exe、exec-format、native Windows 不误报，以及 doc up 在 pull/build 前 fail closed。

当前独立环境只有 Docker CLI 29.7.2，daemon socket 不存在；因此能复核 AC-001/003 和 AC-002 模拟诊断，不能诚实声称已独立复现移除 credsStore 后真实 pull 恢复。按本 issue 自己的证据门槛暂不关闭。剩余仅需提供可检查的 live recovery 证据 locator，或由另一台可控 WSL/Docker 环境完成一次修复前失败、修复后 pull 成功的复现。