laundering

洗钱：验证与集成

概述

只有当“赃物”被提炼成最终合法形式时，一次成功的劫案才算完成。洗钱负责集成、验证、清理和更新组织记忆。

触发条件

所有地盘负责人报告地盘任务完成，且教父批准后触发（行动完成）。

流程

步骤 1：集成

将所有地盘分支/工作树合并到劫案分支：

# If using worktrees per territory
git merge territory/<name> --no-ff

解决所有冲突。如果冲突不简单，升级给副教父，进行一次小型审问。

步骤 2：验证

运行完整的验证套件：

# Run all tests
<project test command>

# Run linter
<project lint command>

# Run type checker (if applicable)
<project type check command>

所有检查都必须通过。 如果有任何检查失败：

1. 确定是哪个工作包引入了问题
2. 由负责的地盘负责人派遣一名工人进行修复
3. 重新运行验证

使用 gangsta:sweep-verification——每项通过声明都必须有最新命令输出作为依据。

标识符扫描（阻断门槛）： 使用模式 \b(FR|NFR|WP)-\d+\b（匹配 FR-001、NFR-042、WP-007、FR-1 等）扫描 docs/gangsta/ 以外的所有项目文件，查找 Gangsta 内部规范标识符。

grep -rn --include="*.md" --include="*.ts" --include="*.js" --include="*.py" --include="*.go" --include="*.rb" --include="*.java" --include="*.txt" -E "\b(FR|NFR|WP)-[0-9]+" . --exclude-dir=docs/gangsta

• 任何匹配项都是阻断性缺陷。从交付物中移除该标识符，并在宣布劫案干净之前重新扫描。
• 例外：如果匹配项是与 Gangsta 规划无关的合法项目标识符，请在此洗钱检查点记录匹配字符串、文件路径和一句话说明。教父必须在检查点审查签核时确认该例外，之后才能解除此门槛。

步骤 3：技术债务审计

这是一个阻断门槛，包含五项子检查。每项违规都必须修复，或在教父明确批准后作为有记录的例外（来源：文件、行号、理由）记录——例外流程与标识符扫描相同。

必须在顾问进行架构审查之前运行这些检查，以便顾问看到的是清理后的代码，而不是原始命中结果。

3.1 复制/粘贴检测（jscpd）

如果已安装 jscpd，请针对修改过的文件运行它。如果未安装，请运行等效的基于令牌的重复代码扫描；也可以跳过，但须在检查点注明未运行此子检查。

npx jscpd <modified file paths> --format "all" --ignore "**/*.md,**/*.json,**/docs/gangsta/**" --reporters json,console --threshold 0

默认值（如果存在项目的 .jscpd.json，则以其设置为准）：

• min-lines：5
• min-tokens：35
• threshold：0（超过最小代码块大小的重复率为零）

任何超过最小值的克隆簇都是阻断性缺陷。可通过提取共享代码、参数化差异部分或移除无用的重复代码来修复。如果重复在结构上无法避免（例如，两个确实不同的类型具有相同结构），请记录文件路径、克隆簇 ID 和一句话说明，并提交给教父签核例外。

3.2 长文件

统计行动期间创建或修改的每个文件的源代码行数（不包括空行和注释）：

for f in <modified files>; do wc -l "$f"; done

阈值：

• ≤ 300 行： 正常。
• 301–500 行： 标记以供审查。副教父需指出该文件并询问：是否存在足以证明文件较长的单一职责？如果有，请记录理由。如果没有，须先提取模块再继续。
• > 500 行： 阻断。将文件重构为更小的模块，按职责拆分。唯一例外是合约条款要求使用单个文件（例如，供应商 SDK 适配层），且教父明确批准。

在检查点记录重构后的行数。

3.3 测试覆盖率

运行项目的覆盖率命令。如果项目没有覆盖率工具，则跳过并注明原因——不要凭空编造命令。

<project coverage command — e.g. npm run test:coverage, pytest --cov, go test -cover>

两项检查：

1. **下限：**如果项目的覆盖率配置声明了阈值（例如 jest.config.* 中的 --coverageThreshold，或 .coveragerc 中的 fail_under），运行结果必须达到该阈值。未达标属于阻塞性缺陷——添加测试，直到达到阈值。
2. **增量：**新增或修改的代码不得导致项目整体覆盖率低于 Heist 前的基线。记录资源开发步骤中的基线数值（如果缺失，则运行 git stash 并重新测试）。如果修改行的覆盖率有所下降，则在继续之前补上缺失的测试。

在检查点中记录最终覆盖率数值。

3.4 清洁架构审计

Consigliere 会在第 4 步从架构层面进行审查——此子检查是机械式预筛。对每个修改过的文件，验证：

1. **依赖方向：**文件仅从较低层导入（domain → application → infrastructure → delivery）。除非 Contract 明确批准这种反转，否则从较高层向较低层导入属于阻塞性缺陷。
2. **交付层或基础设施层中不得包含业务逻辑：**控制器、CLI 处理程序、路由绑定、数据库适配器和网络客户端只能负责编组和委派。业务规则应属于 domain/application 代码。
3. **单一职责：**文件名应表明一项职责，内容也应符合该职责。一个文件承担两项无关工作属于阻塞性缺陷。

如果项目没有正式的分层结构，则默认通过此子检查——在检查点中注明“此项目没有正式的架构分层”。

3.5 清洁代码审计

先禁用自动修复，运行项目的代码检查工具并审查违规项：

<project lint command — no auto-fix>

除代码检查工具外，还要扫描修改过的文件，查找以下机械式清洁代码违规项：

1. **死代码：**未使用的导入、不可达分支、注释掉的代码、未使用的私有函数。应予以移除。（调试日志将在第 4 步清理；此处检查的是遗留脚手架代码。）
2. **过长函数：**任何超过 50 行的函数（不包括空行和注释）都会被标记。应提取子函数，直到每个函数只做一件事。如果 50 行以上的函数确实只执行一个操作（例如表驱动测试用例），则在代码中注明。
3. **嵌套过深：**任何嵌套层级超过 4 层（if/for/while/try）的代码路径都属于阻塞性缺陷。应使用提前返回、守卫子句或提取辅助函数来扁平化结构。
4. **魔法数字：**测试范围内的字面值没有问题；生产代码中未命名的字面值必须提取为具名常量或配置值。如果字面值所在的表达式已能自我说明其含义（例如 setTimeout(fn, 0)），则可豁免。
5. **命名：**任何需要注释来解释用途的标识符都属于阻塞性缺陷——应重命名。除广为人知的领域术语外，使用缩写也属于阻塞性缺陷。

除非 Contract 明确接受，否则任何违规项都属于阻塞性缺陷。在检查点中列出违规项、修复方式（或记录的例外情况）以及修复后的代码检查输出。

审计输出

## Technical Debt Audit

| Sub-check | Result | Details |
|-----------|--------|---------|
| Copy/Paste (jscpd) | PASS / N clone clusters fixed / SKIPPED (tool unavailable) | <details> |
| Long Files | PASS / N refactored / N documented | <files, before → after line counts> |
| Test Coverage | PASS / N threshold failures fixed | <baseline → final coverage %> |
| Clean Architecture | PASS / N violations fixed / No formal layers | <details> |
| Clean Code | PASS / N violations fixed | <lint output, before → after> |

### Documented Exceptions
- <file>:<line> — <sub-check> — <rationale> — [Don acknowledged: YES/NO]

第 4 步：Consigliere 最终审查

调用 gangsta:the-consigliere 对集成后的代码进行架构审计：

• 实现是否符合 Contract？
• 是否存在架构回退？
• 审查最终代码的安全性
• 集成是否存在任何问题？

如果 Consigliere 提出 CRITICAL 问题：先修复，再继续。 如果提出 CONCERNS：提交 Don 决定。 如果 APPROVE：继续。

此外，可调用 gangsta:audit-review，在 Consigliere 进行架构评估的同时开展独立的代码级审查。

第 5 步：自动清理

• 运行项目格式化工具或代码检查工具，并启用自动修复
• 移除在 The Hit 期间添加的任何调试日志
• 清理生产环境中不需要的临时测试夹具

第 6 步：证据销毁

移除操作产物：

• The Hit 期间创建的临时文件
• Worker 调度产生的内部运行日志
• 草稿／中间检查点文件（仅保留最终状态）

请勿移除：

• 合同（docs/gangsta/<heist-name>/specs/YYYY-MM-DD-contract.md）
• 执行计划（docs/gangsta/<heist-name>/plans/YYYY-MM-DD-execution-plan.md）
• 侦察档案（docs/gangsta/<heist-name>/recon/YYYY-MM-DD-recon-dossier.md）
• 这些是 Heist 的永久记录

第 7 步：更新账本

调用 gangsta:the-ledger，记录 Heist 的经验教训：

心得 — 对于发现的每个重要解决方案或模式：

• 写入 docs/gangsta/insights/YYYY-MM-DD-<topic>.md
• 更新章程，加入新的戒律

失败 — 对于遇到的每次失败、回归或错误：

• 写入 docs/gangsta/fails/YYYY-MM-DD-<topic>.md
• 更新章程，加入新的禁止事项

询问 Don：

“Heist 即将完成。有没有你想记录到账本中的心得或失败？”

第 8 步：Don 的最终批准

向 Don 呈报：

“Heist ‘’ 的洗白工作已完成。

• 所有测试均已通过
• 覆盖率：<baseline → final>
• 技术债审计：<已修复违规项列表；如有例外则注明>
• Consigliere 结论：[verdict]
• 账本已更新：[N] 条心得，[N] 条失败
• 代码整洁，已可用于生产环境

你宣布此 Heist 完成吗？”

Don 可以：

• 宣布完成 — Heist 已完成。进行最终提交，并可选择合并到 main。
• 要求修改 — 返回指定步骤。
• 终止 — 丢弃 Heist 分支。

最终检查点

---
heist: <heist-name>
phase: laundering
status: completed
timestamp: <ISO 8601>
next-action: Heist complete. Merge to main or archive.
artifacts:
  - docs/gangsta/<heist-name>/specs/YYYY-MM-DD-contract.md
  - docs/gangsta/<heist-name>/plans/YYYY-MM-DD-execution-plan.md
  - docs/gangsta/<heist-name>/recon/YYYY-MM-DD-recon-dossier.md
  - <all code files created/modified>
technical-debt-audit:
  copy-paste: PASS | N-fixed | SKIPPED <reason>
  long-files: PASS | N-refactored <files>
  test-coverage: <baseline% → final%>
  clean-architecture: PASS | N-fixed | no-formal-layers
  clean-code: PASS | N-fixed
  documented-exceptions: <file:line — sub-check — rationale>
---

Omerta 合规性

• 真实原则：验证结果必须是实际命令输出，而非口头声明
• 规范即法律：Consigliere 确认实现符合合同
• 可用性原则：最终检查点包含完整的产物清单
• 预算原则：向 Don 报告最终资源消耗
• 技术债审计：运行全部五项子检查（或记录跳过及原因）；修复违规阻塞项，或经 Don 签字批准作为例外；在检查点中记录审计输出