audit-project

目的

定期使用此技能，或在重大规划周期开始前使用，以确定项目是否仍与预期设计、已记录的行为、已交付功能历史记录及当前 Beads 状态相符。

共享信任约定

执行此工作流前，请阅读并遵循 ../dstack-core/references/TRUST-AND-AUTHORITY.md。此约定对本工作流具有规范效力。如果它与此技能冲突，请遵循限制更严格的规则，并报告冲突。

启动版本证据

在首次修改工作流之前，按照 ../dstack-core/references/SKILL-VERSION.md 中针对 audit-project 的说明操作。完成只读清点后，记录精确的单行输出，并在进行任何更正前将其纳入审计证据。stale 结果会提示使用 npx skills update；unavailable 表示记录未作新鲜度声明，且不会阻止离线工作。

审计专属权限：

• 自动更正仅限于明确无歧义的本地文档、导航和工作流状态协调。
• 代码、API、安全边界、架构策略或破坏性变更，均须获得用户明确批准或创建纠正性 Beads 问题。
• 审计子代理只能执行只读操作。

执行

1. 清点来源

运行：

bd prime
bd list --all --label workflow:feature --json
bd ready --json
bd blocked --json
uv run --no-project python scripts/check-docs.py

为每个 workflow:feature 根节点建立一条清点记录，包含其生命周期状态、设计路径、实现记录路径、路线图条目和迁移状态。检查每个关联工件、SUMMARY.md 中的每个持久页面，以及自上次审计以来有变更的代码、测试、配置、迁移和提交。记录排除的范围及原因。当 migration/workflow-migration.json 存在时，纳入未解决的迁移发现，并确认没有仍依赖 tasks.md 的活跃功能。

Git 证据边界

近期提交比较是必需的审计证据。使用只读 Git 检查（git status、git log、git show 和 git diff）确定比较范围并检查相关变更。不要创建提交、切换分支、合并、推送、重写历史或执行任何其他 Git 修改。bd prime 中的“Git workflow: stealth mode (no git ops)”之类提示，不能成为悄然省略这项必需证据的理由；也不得将其与此技能中的禁止推送分支规则混为一谈。

如果执行环境确实禁止只读 Git 检查，请报告 audit state: incomplete，并指出 Git 证据是阻断性限制。不要将其描述为仅仅被排除，也不要声称审计已完成。最终报告必须说明检查的确切提交范围，或说明审计因无法获取只读 Git 证据而未完成。

2. 比较系统

检查以下问题：

• Beads 功能缺少设计或必需的交付记录；
• 已关闭的功能仍标记为计划中或部分完成；
• 已实现功能页面没有对应的已交付 Beads 状态；
• 代码行为与面向读者的文档相矛盾；
• 实现违反已记录的边界或不变量；
• 设计决策发生变化但没有说明原因；
• 命令、配置、接口、架构、字段、状态、默认值、限制或术语已过时；
• 测试证明的是过时行为，或未能覆盖已记录的约定；
• 延后处理的工作被悄然实现、弃置或遗留为阻碍；
• 功能任务重复、冲突或无关联；
• SUMMARY.md 缺少持久页面；
• 存在旧版 tasks.md、使用 include 的功能页面，或未解决的迁移状态冲突。

3. 对偏差分类

使用：

intentional evolution requiring documentation reconciliation
implementation defect
stale documentation
stale feature design or delivery record
workflow-state mismatch
migration-state mismatch
unresolved design decision
missing validation evidence

4. 记录纠正工作

应用明确无误的本地文档修正。为剩余工作创建 Beads 问题，并根据情况使用 discovered-from、related 或 blocks 关联。包含确切文件、证据、预期解决方案、验收标准和严重程度。

对于与功能相关的偏差：

bd create "Reconcile <finding>" \
  --type task \
  --deps discovered-from:<feature-root-or-task> \
  --labels audit:drift \
  --json

仅当未解决的偏差会使后续交付不安全时，才使用阻塞依赖。

完成修正后，丢弃因这些编辑而过时的验证结果。针对最终文件重新运行 uv run --no-project python scripts/check-docs.py，以及所有受影响的格式化工具、linter、构建、测试、迁移和 功能专用检查。记录确切命令、结果、跳过的检查和限制。

不得根据修正前的结果报告已验证的修正。只有在每项发现都已修正并重新验证、关联到纠正问题，或明确接受为剩余风险时，审计才算完成。

5. 发布变更后的 Beads 状态

当审计创建或更新 Beads 记录时，调用 /audit-project 即授权向仓库已配置的原生 Dolt 远程端执行一次常规非强制发布， 前提是最终验证已完成：

bd dolt remote list --json
bd dolt push

此授权不包括创建或替换远程端、强制推送或推送 Git 分支。Beads 未发生变化时，不要推送。如果未配置原生远程端或推送失败，请保留本地记录并报告 audit publication blocked；不得声称纠正工作已共享。

按严重程度以及有意或意外的分类顺序返回发现，列出文件和 Beads ID、已应用的修正、创建的纠正问题、受阻工作、发布证据、Git 比较范围和建议的下一步操作。恰好包含一行明确的状态：仅当所有必需证据均已检查，且每项发现都已修正、关联到纠正问题或明确接受为剩余风险时，使用 audit state: complete；否则使用 audit state: incomplete，并指出缺失的证据或未解决的工作。Beads 发布成功绝不会将未完成的审计变为已完成。证据状态请使用以下格式：

Git evidence: compared <base>..<head> with read-only Git inspection.
Audit state: complete

如果无法检查 Git，请将第一行替换为 Git evidence: unavailable — <reason>，并使用 Audit state: incomplete；不要用一句话表示比较仅被排除。