swain-doctor

Doctor

用于 swain 项目的会话启动健康检查。汇总脚本是所有检测的权威依据。此技能文件规定了如何运行脚本，以及如何修复每项检查发现的问题。

运行脚本

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-doctor.sh"

脚本会输出结构化 JSON，格式为 { checks: [...], summary: {...} }。每项检查都包含 name、status、message，以及可选的 detail。解析 JSON，并向操作人员展示汇总表。然后，仅针对状态为 warning 或 advisory 的检查，使用下面的修复说明；不要重新运行检测。

自动修复扁平文件产物：bash "$REPO_ROOT/.agents/bin/swain-doctor.sh" --fix-flat-artifacts

如果脚本不可用（例如，.agents/bin/ 符号链接尚未完成初始化），则回退到运行脚本源文件 skills/swain-doctor/scripts/swain-doctor.sh 中的检查。依次运行检查（每次只调用一次 Bash），绝不要并行运行；并行工具调用会在首次出错时级联取消。

预检集成

轻量级 shell 脚本（$REPO_ROOT/.agents/bin/swain-preflight.sh）会在调用完整 doctor 前执行快速检查。如果预检以 0 退出，本次会话将跳过 swain-doctor。如果以 1 退出，则正常运行 swain-doctor。

用户直接调用时（而非通过自动调用），无论预检状态如何，swain-doctor 都会运行。

治理内容参考

规范的治理规则位于 references/AGENTS.content.md。swain-doctor 和 swain-init 都会读取这一唯一事实来源。如果未来的 swain 版本更新了上游规则，请更新该文件并提升技能版本。

---

按检查名称修复

以下各节分别对应脚本输出的检查名称。仅当检查状态为 warning 或 advisory 时，才查看相关章节。

governance

注入（缺失）： 阅读 references/governance-injection.md，了解 Claude Code 和 Cursor 的注入流程。来源：references/AGENTS.content.md。

替换（过时）： 如果两个标记（和）都存在，脚本会自动修复过时的治理区块。如果自动修复失败（缺少标记），请阅读 references/governance-injection.md § 过时治理内容替换 了解手动替换方法。

legacy_skills

使用指纹检查清理已重命名和已停用的技能目录。阅读 references/legacy-cleanup.md 了解完整流程。数据来源：references/legacy-skills.json。

agents_directory

使用 mkdir -p .agents 创建 .agents/。此目录供 swain-do 存放配置，以及供 swain-design 脚本存放日志。

tickets

验证 .tickets/ 的健康状态，包括 YAML frontmatter 和过期锁。阅读 references/tickets-validation.md 了解修复流程。

beads_migration

如果存在 .beads/，则自动迁移至 .tickets/。阅读 references/beads-migration.md 了解迁移流程。

tools

必需工具：git、jq。可选工具：tk、uv、gh、tmux、fswatch。绝不自动安装。阅读 references/tool-availability.md 了解功能降级说明和安装指南。

settings

如果缺少 swain.settings.json，请使用默认内容创建。如果其中包含无效 JSON，请修正语法。用户设置位于 ${XDG_CONFIG_HOME:-$HOME/.config}/swain/settings.json。

script_permissions

脚本会自动修复技能目录树中 .sh 和 .py 文件缺失的执行权限。无需手动修复；状态为 advisory 表示权限已修复。

memory_directory

如果缺少记忆目录，脚本会自动创建。如果创建失败，请手动创建：

mkdir -p "$HOME/.claude/projects/$(echo "$REPO_ROOT" | tr '/' '-')/memory"

superpowers

当状态为 warning（缺失或部分安装）时，询问操作员：

Superpowers（obra/superpowers）未安装［或：仅部分安装］。它提供 TDD、头脑风暴、计划编写和验证技能，swain 会将这些技能串联起来。

现在安装 superpowers？（yes/no）

如果回答 yes：npx skills add obra/superpowers。如果回答 no，记录“Superpowers：已跳过”并继续。

epics_initiative

非阻塞提示。报告数量并建议：

有 N 个 Epic 带有 parent-vision，但没有 parent-initiative。添加 parent-initiative 链接为可选项，但建议添加。要运行引导式迁移，请询问：“run the initiative migration.”

完整的 6 步引导式迁移工作流请参阅 references/initiative-migration.md。

readme

报告：README.md missing — swain alignment loop has no public intent anchor. Run swain-init to seed one.

artifact_indexes

脚本会通过 rebuild-index.sh 自动修复过时的索引。如果重建脚本不可用或重建失败，请检查 .agents/bin/rebuild-index.sh 是否存在且可执行。修复符号链接后，重新运行 swain-doctor。

evidence_pools

如果存在 docs/evidence-pools/，运行 trove 迁移：

bash "$REPO_ROOT/.agents/bin/migrate-to-troves.sh" --dry-run  # preview
bash "$REPO_ROOT/.agents/bin/migrate-to-troves.sh"            # migrate

worktrees

过时的 worktree（分支已合并到 HEAD）可以清理：git worktree remove <path>。孤立的 worktree（目录缺失）可以清理：git worktree prune。过时的锁文件和未认领的 worktree 会在详细信息字段中报告。分类规则请参阅 references/worktree-detection.md。

worktree_context

验证当前会话的 worktree，而非所有关联的 worktree（后者由 worktrees 负责）。所有四项子检查都会以确定性方式自动修复——警告表示自动修复失败，提示表示自动修复成功。

位置不在 .worktrees/ 下（自动移动）：ADR-034 规定 .worktrees/ 为规范位置。脚本会通过 git worktree move <path> <main_root>/.worktrees/<branch> 自动移动 worktree。失败（警告）表示目标路径已存在或 git worktree move 失败——请手动解决。

缺少锁文件（自动创建）：脚本会使用 swain-lockfile.sh claim 在 .agents/worktrees/<branch>.lock 创建锁文件，或退回到直接写入锁文件。如果发生冲突（同一分支已有锁文件），则会创建带 PID 后缀的锁文件。提示 = 已自动创建；警告 = 创建失败。

分支名称违反 ADR-025（自动重命名）：脚本会自动重命名分支，并移动 worktree 文件夹以符合 ADR-025 的命名规则。如果有可用的用途描述，它会使用 swain-worktree-name.sh，否则退回到 session-<timestamp>。锁文件也会重命名。提示 = 已重命名；警告 = 重命名失败。

文件夹名称 != 分支名称（自动移动）：脚本会通过 git worktree move 自动移动 worktree 文件夹，使 basename 与分支名称一致。提示 = 已移动；警告 = 移动失败（目标已存在）。

lifecycle_dirs

ADR-003 三轨规范化之前遗留的阶段目录。检测命令、修复步骤和迁移脚本请参阅 references/lifecycle-migration.md。

tk_health

如果未找到随附的 tk 或其不可执行，请尝试运行 /swain update 以重新安装技能。预期路径为 <skills-root>/swain-do/bin/tk。

operator_bin_symlinks

脚本会自动修复缺失或过时的 bin/ 符号链接。发生冲突（bin/<name> 处存在实际文件）时需要手动解决——重命名或移除冲突文件，然后重新运行 doctor。

commit_signing

检测到 ~/.ssh/swain_signing 中存在签名密钥时，脚本会自动启用提交签名。如果没有密钥，请运行 /swain-keys 以配置一个。

ssh_readiness

运行 scripts/ssh-readiness.sh --check。问题会在 detail 字段中报告。常见修复方法：确认 ~/.ssh/config.d/ 包含项目专用的 SSH 别名，检查密钥权限（chmod 600），并确保密钥已添加到远程主机。

crash_debris

脚本会自动删除过期的 .git/index.lock 文件。其他崩溃残留物（孤立的临时文件、未完成的合并）会报告出来，需手动清理。查看 detail 字段中的具体文件路径，并在确认安全后将其删除。

agents_bin_symlinks

脚本会自动修复缺失和过期的 .agents/bin/ 符号链接。会删除失效的符号链接。冲突（实际文件）会报告出来，需手动解决。

flat_artifacts

扁平文件制品直接位于阶段目录中，而非各自的文件夹中。运行时添加 --fix-flat-artifacts 可自动迁移：bash "$REPO_ROOT/.agents/bin/swain-doctor.sh" --fix-flat-artifacts。每个制品都会获得一个名为 (<ID>)-<Title>/ 的文件夹。

swain_symlink

如果 bin/swain 符号链接缺失，但脚本位于 <skills-root>/swain/scripts/swain，请创建该链接：

ln -sf "$(python3 -c "import os,sys; print(os.path.relpath(sys.argv[1], sys.argv[2]))" "$SKILLS_ROOT/swain/scripts/swain" "$REPO_ROOT/bin")" "$REPO_ROOT/bin/swain"

如果符号链接失效（目标不存在），可能需要重新安装 swain 技能：/swain update。

branch_model

建议项——swain 推荐采用 trunk+release 分支模型（ADR-013）。trunk 是开发分支；release 是分发分支，在发布时通过 squash-merge 更新。若要采用此模型，请运行 .agents/bin/migrate-to-trunk-release.sh（或添加 --dry-run 以预览）。此项为可选——swain 适用于任何分支模型，但配置后，同步和发布功能会假定采用 trunk+release 模型。

platform_dotfolders

移除未安装的 Agent 平台对应的点文件夹占位项。检测和清理流程请参阅 references/platform-cleanup.md。需要 jq。脚本会报告哪些点文件夹已成为孤立项——移除前请确认其中仅包含安装程序创建的符号链接。

skill_gitignore

在使用方项目中，vendored swain 技能文件夹应加入 gitignore。修复流程请参阅 references/gitignore-skill-folders.md。将以下条目追加到 .gitignore：

.claude/skills/swain/
.claude/skills/swain-*/
.agents/skills/swain/
.agents/skills/swain-*/

在 swain 源代码仓库中运行时会自动跳过。

---

摘要报告

所有检查完成后，输出简洁的摘要表格：

swain-doctor summary:
  Governance ......... ok
  Legacy cleanup ..... ok (nothing to clean)
  Platform dotfolders  ok (nothing to clean)
  .agents directory .. ok
  .tickets/ .......... ok
  Stale .beads/ ...... ok (not present)
  Tools .............. ok (1 optional missing: fswatch)
  Settings ........... ok
  Script perms ....... ok
  Memory directory ... ok
  Superpowers ........ ok (6/6 skills detected)
  Epics w/o initiative advisory (3 epics — see note below)
  README ............. ok
  Artifact indexes ... ok
  Evidence pools ..... ok
  Worktrees .......... ok
  Worktree context ... ok
  Lifecycle dirs ..... ok
  tk health .......... ok
  Operator bin/ ...... ok
  Commit signing ..... ok
  SSH readiness ...... ok
  Crash debris ....... ok
  .agents/bin/ ....... ok
  Flat artifacts ..... ok
  swain symlink ...... ok
  Branch model ....... ok
  Skill gitignore .... ok

3 checks performed repairs. 0 issues remain.

使用以下状态值：

• ok — 无需处理。
• advisory — 已自动修复或仅提供信息（说明具体情况）。
• warning — 发现问题，建议用户采取操作（说明具体情况）。
• skipped — 无法运行检查（例如，缺少 jq，无法进行 JSON 验证）。

如果有任何检查显示警告，请在表格下方列出，并根据上述章节提供修复步骤。