# 2026-06-26 Phase 3.7.2 Doctor POC

## 用户目标

- 用户认可推进顺序：先做 `3.7.2 doctor/preflight POC`，再做 `3.7.3 clean environment QA`，然后进入 `3.8 document lease / App write API`。
- 本轮目标是落地 Phase 3.7.2：提供一个 m4c 可复用的 Mindraw companion app doctor/preflight POC。

## 已完成事项

- 新增 `scripts/mindraw-doctor.mjs`：
  - 默认只读检测 `/Applications/Mindraw.app`。
  - 检测 bundle id、版本、`mindraw://` scheme 声明、`.mindraw` package document 声明。
  - 输出 m4c 可解析 JSON。
  - 缺 App、版本过低、scheme 缺失、document type 缺失、非 macOS 等场景返回明确诊断码。
  - `--smoke` 才执行 `open`，默认不会启动 App。
- 新增 `scripts/mindraw-doctor.test.mjs`，使用 Node 内置 test 覆盖核心诊断逻辑。
- 更新 `package.json`：
  - `doctor:mindraw`
  - `doctor:mindraw:test`
- 新增 QA 记录：`02-P/qa/mindraw-phase372-doctor-poc-check.md`。
- 更新 `02-P/plan-progress.markdown`，记录 Phase 3.7.2 已完成，下一步进入 3.7.3 clean environment QA gate。
- 更新 `CODEGRAPH.md` 和 `INDEX.md`，登记 doctor POC 入口和 QA 入口。
- 更新 3.7 契约文档状态，说明 POC 已实现，fresh machine QA 仍待补。

## 关键决策

- Doctor POC 默认只读，不修改 LaunchServices、不写 `/Applications`、不安装或升级 App。
- 当前本机 doctor 输出为 `warn`，唯一 warning 是 `MINDRAW_BUILD_UNKNOWN`，因为安装后的 App metadata 目前不暴露 release build。
- 真实 `open <file>.mindraw` 和 `open "mindraw://..."` 留在 `--smoke` 模式，不作为默认 doctor 行为。

## 文件变更

- `scripts/mindraw-doctor.mjs`
- `scripts/mindraw-doctor.test.mjs`
- `package.json`
- `02-P/qa/mindraw-phase372-doctor-poc-check.md`
- `02-P/qa/mindraw-phase37-companion-doctor-contract.md`
- `02-P/功能任务/companion-app-distribution-spec.md`
- `02-P/plan-progress.markdown`
- `CODEGRAPH.md`
- `INDEX.md`

## 验证结论

- `npm run doctor:mindraw:test`：PASS，7 个测试通过。
- `node --check scripts/mindraw-doctor.mjs`：PASS。
- `npm run doctor:mindraw -- --pretty`：PASS，输出本机 `warn` / `MINDRAW_BUILD_UNKNOWN`。
- `node scripts/mindraw-doctor.mjs --app /tmp/MissingMindraw.app --pretty`：PASS，输出 `fail` / `MINDRAW_APP_MISSING`，退出码 `1`。
- `git diff --check` 对本轮相关文件通过。

## 未决问题与后续建议

- 下一步是 Phase 3.7.3 clean environment QA gate：验证未安装、旧版、handler 错误、文件关联缺失和 `--smoke` 边界。
- 若未来需要 doctor 精确判断 build，Mindraw App 需要新增可读 build/capability metadata。
- 当前工作区仍有非本轮改动和未跟踪项，包括 Workflowy 文档、m4c 子项目、`ai-frame-workflow-prd.md` 等；本轮未回退、未纳入 doctor POC 结论。