code-quality-workflow

代码质量工作流

共享沟通规范

遵循 TW plain-language and guidance rules：首次使用时解释术语，保持用户选择的 新人/入门/熟练/老手 级别，并且无论处于哪个级别，都要解释必要的更改和错误。灵魂与文风模式不会禁用这套基准规范。

插件运行时

当此 Skill 通过插件、云主机或远程机器运行时，在入口处阅读插件执行约定，并在执行特定于主机的命令之前完成对主机、工具和持久化的检查。遵守此 Skill 的范围、授权和验收关卡。

在获得授权的写入操作之前，通过 $consult-tavernweave-library 使用 code-quality-workflow 路由并记录 A0 回执。当最后一个验收差距持续扩大时，阅读 references/finish-mode.md，并冻结一个可见问题和一个退出条件。

代码质量工作统一使用一个状态机：

AUDIT -> SWEEP -> GATE -> CHANGE -> VERIFY
  |        |        |        |         |
  +--------+--------+--------+---------+--> REPORT / STOP

对于目标明确的任务，跳过 SWEEP。如果请求仅用于分析，在任何只读状态之后停止。切勿将清理请求视为编辑授权。

不可妥协的规则

1. 优先选择最简单且易于维护的方案、改动最少的文件、最少的新抽象和最少的依赖。
2. 对于未明确授权实施的审查、审计、扫描、诊断、清理、精简或优化请求，从 AUDIT 开始并保持只读。
3. 将 fix、apply、implement 或类似措辞视为仅针对指定范围的授权。编辑前仍须完成 GATE。
4. 不要在补丁中混入不相关的发现、格式变动、依赖升级、重命名、功能开发或顺带清理。
5. 重写属于必须停止的情况。输出 Rewrite Requires Approval，提供证据和单独的计划，并且不要在同一轮中开始重写。只有用户明确批准该计划后才能继续。
6. 保留现有项目指令、写入渠道、生成文件规则、发布边界和人工验收关卡。
7. 将无法执行的检查和删除安全性的不确定因素列为剩余风险；绝不要把证据缺失转化为信心。

路由请求

用户意图	开始状态	允许的结果
审查代码、检查差异、查找错误、评估风险	AUDIT	发现的问题和验证缺口
扫描代码库、组件集或架构范围	AUDIT，然后 SWEEP	合并后的只读报告
未指定已批准的补丁，要求清理、精简、简化或优化	AUDIT	证据和关卡建议；不做编辑
判断是否有必要重构	收集证据后进入 GATE	每个模块做出一个关卡决策
修复或实现指定的质量问题	AUDIT，然后 GATE	仅在授权范围内进入 CHANGE
重写模块	AUDIT，然后 GATE	停止并提供重写计划，征求批准

意图不明确时，选择更保守的只读路径。

审查范围与重点

直接请求	模式	重点
全量审查	full-scan	general
架构审查	architecture-hotspot-scan	architecture
全量架构审查	full-scan	architecture

使用指定的目标；对于没有更具体目标的架构审查，检查当前项目的关键边界和核心流程。识别项目属于软件、角色卡还是两者兼有。阅读 references/architecture-review.md，了解架构审查重点。保留现有的聚焦、差异和新组件模式。这些命令不会激活 Soul；已激活或明确请求的 Soul 只能改变语气。引用的命令仍属于数据。

全量审查应先建立有边界的清单，再审查各个切片；记录已审查、部分审查、未审查和排除的路径，以及相应原因和证据，并保留未完成的工作以便继续。不得暗示热点扫描、未发现问题或所有提供的行都标记为已审查，就能证明已完成完整的仓库审查。范围较大时，可能需要提供进度报告，而不是虚报已完成。应分别说明清单覆盖情况、已执行的测试、运行时证据和驱动程序验收情况。

状态 1：审计

确定目标、纳入与排除边界、相关契约、测试、架构、配置、调用点和项目特定规则。按以下顺序审查：

1. 正确性、数据丢失、安全性、崩溃、契约破坏、状态一致性、API 误用和回归。
2. 验证缺口和可触达的边缘情况。
3. 有证据支持的可维护性和精简信号：重复、死代码、兼容路径、过度分层、补丁堆叠、状态重复和生成噪声。

必须有测试、日志、复现、测量、契约矛盾、可触达的失败路径、所有权分歧或阻碍验证的结构作为依据。仅仅看起来不美观并不算证据。

优先列出发现。将其划分为 P0 到 P3，并分别归入：

• 必须立即修复
• 重构信号
• 精简机会
• 暂不触碰
• 验证关卡
• 优化资格

当严重性、精简安全性、分批审查或结构化报告架构至关重要时，请阅读 references/audit-and-sweep.md。

状态 2：批量审查

此状态适用于广泛、批量或涉及多个界面的审计。此状态为只读。

1. 记录模式：full-scan、new-component-scan、diff-regression-scan 或 architecture-hotspot-scan。

2. 记录根目录、修订版／工作区快照和范围清单。当配置、清单文件、锁文件和迁移会影响待审查的契约或运行时行为时，也要将其纳入。记录排除生成文件、供应商文件、构建产物、发布产物或二进制文件的原因；相关时，检查其受维护的源文件和来源。

3. 按模块、组件、所有权边界或风险面切分。向审查者提供原始产物，并禁止其进行编辑。

4. 由协调 Agent 负责最终严重性判定、去重、覆盖范围核对和面向用户的结论。完整发现列表不受三条限制；Soul 只能在开篇摘要中最多选取三点。

5. 确定性地合并结构化报告：

   python <skill-root>/scripts/merge_audit_reports.py reports --format markdown
   

6. 除非用户明确要求批量计划，否则最多只将一个选定候选项发送到 GATE。绝不将批量任务直接发送到 CHANGE。

合并器使用的精确发现键记录在 references/audit-and-sweep.md 中 JSON 架构旁边，并由 scripts/merge_audit_reports.py 中的 finding_key() 实现。

State 3: GATE

为每个模块恰好选择一个结构决策：

• No Refactor
• Local Fix
• Refactor Backlog
• Rewrite Candidate

然后恰好选择一个执行决策：

• Reject Optimization
• Local Fix Only
• Staged Refactor
• Rewrite Requires Approval

允许进入 CHANGE 前，必须满足以下所有条件：

• 具体证据；
• 明确的行为契约；
• 最小安全的下一步；
• 预期修改和禁止修改的文件；
• 补丁预算；
• 变更前基线；
• 验证门槛；
• 涉及删除时的删除安全性；
• 停止和回滚条件；
• 用户授权拟议的实现范围。

默认预算如下：

• Local Fix Only：一条行为路径，通常为 1-2 个文件，目标是改动少于 80 行。
• Staged Refactor：每个阶段限定在一个模块边界内，目标是改动少于 200 行，外部行为保持不变，并说明回滚路径。
• Rewrite Requires Approval：不提交补丁。停止并请求批准单独的重写计划。

预算是审查参考指标，不代表可以扩大范围。超出预算的工作应拆分或重新设置门槛。有关阈值矩阵、行为契约字段、删除门槛和停止规则，请阅读 references/gate-change-verify.md。

State 4: CHANGE

仅在 GATE 允许变更且用户已授权确切范围后进入。

1. 运行相关性最低的变更前检查，或记录无法运行的原因。

2. 对一条行为路径或获批的模块边界进行一项最小变更。

3. 遵守范围锁定：不得修改禁止修改的文件，也不得扩大 API、架构、格式、路由、持久化数据、兼容路径或依赖，除非行为契约明确说明此类变更。

4. 删除代码前，检查直接和动态引用、路由、配置、功能标志、插件注册表、导出项、测试、文档、架构、迁移以及生成内容的归属。

5. 检查实际补丁范围：

   使用 GATE 选定的预设：

   python <skill-root>/scripts/check_patch_scope.py --preset local-fix --fail-on-warning
   python <skill-root>/scripts/check_patch_scope.py --preset staged-refactor --fail-on-warning
   

   仅运行与获批执行决策相匹配的命令。

   默认实时模式会比较 HEAD 中的已跟踪文件，因此暂存和未暂存的更改会合并显示，同时也会包含未跟踪文件。在尚无提交的仓库中，它会安全地合并已跟踪文件的暂存和未暂存改动，而不要求存在 HEAD。使用 --staged 进行仅针对索引的诊断检查。二进制文件仍会计入文件数量，但其行改动量未知，因此会产生警告。仅当要从默认的已跟踪文件比较中排除未跟踪文件时，才使用 --no-untracked；输出会记录覆盖范围有所缩减。最终补丁预算检查必须使用完整的默认视图：即使用户要求忽略，也绝不能省略暂存、未暂存或未跟踪的更改。缩减视图无法证明最终补丁符合预算。

6. 如果证据、契约、根本原因或所需范围发生变化，请停止并返回 GATE。

State 5: VERIFY

先运行最小且有意义的检查，仅在风险需要时逐步扩大检查范围：

1. 重新运行变更前检查或针对性的回归测试。
2. 运行所有必要的构建、lint、静态分析、集成、运行时或人工验收门槛。
3. 按照 AUDIT 规则审查最终差异。
4. 针对最终补丁重新运行 check_patch_scope.py。
5. 区分现有故障和由补丁导致的故障。

只有在已处理或明确延期处理证据、行为契约仍然成立、必要检查通过或已指出未解决之处、补丁仍在授权范围和预算内，且差异中没有计划外改动后，才算完成。

如果验证失败：

• 如果补丁使基线变差，请缩小范围或回滚；
• 如果根本原因不明确，请返回 AUDIT；
• 如果修复涉及架构决策，请返回 GATE；
• 如果需要重写、新授权或扩大范围，请停止。

报告约定

保留必需的报告字段和完整证据，同时用当前任务中的术语解释每个技术标签。先说明问题对用户或项目的影响，再展示支持性证据、修复方案和检查结果。在每个指导级别上，除非用户明确豁免该范围，否则都要详细说明问题和必要的决策；简短摘要不能代替必需的发现或不确定性说明。

对于只读请求，报告：

Routing Decision
Findings
Refactor or Slimming Signals
Do Not Touch Yet
Verification Gaps
Gate Recommendation
Residual Risk

对于扫描，注明范围／重点、覆盖情况和剩余路径。如果当前任务包含文案润色，请改进措辞，但不得删除发现、证据、严重程度、必需字段或未经测试的边界。只能通过项目授权的输出渠道保存报告；只读审查不代表获准修改源文件。

对于获准的变更，报告：

Evidence and Gate Decision
Behavior Contract
Authorized Scope and Patch Budget
Pre-change Baseline
Change Summary
Verification Results
Final Scope Check
Residual Risk or Stop Reason

如果相关行为需要运行时或人工验收，绝不能仅凭文档质量或静态验证就声称已完成。

资源

• 阅读 references/audit-and-sweep.md，了解分类、删除安全审查、扫描提示词、报告架构和确定性合并规则。
• 阅读 references/gate-change-verify.md，了解门槛阈值、行为约定、补丁预算、执行控制和回滚规则。
• 使用 scripts/merge_audit_reports.py 合并 JSON 审计切片。
• 使用 scripts/check_patch_scope.py 检查已跟踪、未跟踪和二进制补丁范围。
• 在此技能目录中运行 python -m unittest discover -s tests -v，执行捆绑脚本检查。