laundering

資金洗浄：検証と統合

概要

Heist は、「戦利品」を最終的かつ合法な形に精製して初めて完了します。資金洗浄では、統合、検証、クリーンアップ、組織の記憶の更新を行います。

トリガー

すべての Crew Lead が担当テリトリーの完了を報告し、Don が承認した後（The Hit 完了時）に実行します。

プロセス

ステップ 1：統合

すべてのテリトリーのブランチ／worktree を Heist ブランチにマージします。

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

競合を解決します。競合が軽微でない場合は、Underboss にエスカレーションしてミニ・グリルを行います。

ステップ 2：検証

完全な検証スイートを実行します。

# Run all tests
<project test command>

# Run linter
<project lint command>

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

すべてのチェックに合格する必要があります。 失敗があった場合：

1. どの Work Package が失敗を引き起こしたか特定します
2. 担当する Crew Lead が Worker を派遣して修正します
3. 検証を再実行します

gangsta:sweep-verification を使用してください。合格したという主張はすべて、新しいコマンド出力で裏付ける必要があります。

識別子スキャン（ブロッキングゲート）： docs/gangsta/ 外のプロジェクトファイルすべてを対象に、パターン \b(FR|NFR|WP)-\d+\b（FR-001、NFR-042、WP-007、FR-1 などに一致）を使って、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

• 一致するものはすべてブロッキング欠陥です。成果物から識別子を削除し、Heist に問題がないと宣言する前にスキャンを再実行します。
• 例外：一致したものが Gangsta の計画とは無関係な正当なプロジェクト識別子である場合は、一致した文字列、ファイルパス、1文の根拠をこの資金洗浄チェックポイントに記録します。ゲートを解除するには、チェックポイントのレビュー承認の一環として Don が例外を必ず承認する必要があります。

ステップ 3：技術的負債の監査

ブロッキングゲートです。5つのサブチェックがあります。違反はすべて必ず修正するか、Don の明示的な承認を得て、文書化された例外（出典：ファイル、行、根拠）として記録する必要があります。例外の手順は識別子スキャンと同じです。

Consigliere のアーキテクチャレビューより先に実行し、Consigliere が生の検出結果ではなく、整理済みのコードを確認できるようにします。

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（最小ブロックサイズを超える重複を許容しない）

最小値を超えるクローンクラスターは、すべてブロッキング欠陥です。共通コードの抽出、差異のパラメーター化、または不要な重複の削除によって修正します。重複が構造上避けられない場合（例：形状が同じで実際には異なる2つの型）は、ファイルパス、クローンクラスター ID、1文の根拠を記録し、例外承認のため Don に提示します。

3.2 長いファイル

Hit 中に作成または変更したすべてのファイルについて、ソース行数を数えます（空行とコメントは除外します）。

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

しきい値：

• 300行以下： 問題ありません。
• 301～500行： レビュー対象です。Underboss がファイル名を挙げ、「この長さを正当化する単一の責務があるか」と尋ねます。ある場合は、その根拠を文書化します。ない場合は、先にモジュールを抽出します。
• 500行超： ブロッキング対象です。責務ごとに分割し、より小さなモジュールにリファクタリングします。例外は、単一ファイルを義務付ける Contract 条項（例：ベンダー提供 SDK のシム）があり、Don が明示的に承認した場合に限られます。

リファクタリング後の行数をチェックポイントに記録します。

3.3 テストカバレッジ

プロジェクトのカバレッジコマンドを実行します。プロジェクトにカバレッジツールがない場合は、注記してスキップしてください。存在しないツールを作り出してはいけません。

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

確認事項は2つです。

1. 最低基準： プロジェクトのカバレッジ設定にしきい値が定義されている場合（例：jest.config.* の --coverageThreshold、.coveragerc の fail_under）、実行結果はその値を満たす必要があります。未達はブロッキング欠陥です。しきい値を満たすまでテストを追加してください。
2. 差分： 新規または変更されたコードによって、プロジェクト全体のカバレッジを Heist 前のベースラインより低下させてはいけません。Resource Development の手順でベースラインの数値を記録してください（記録がない場合は git stash して再実行してください）。変更行のカバレッジが低下している場合は、先に不足しているテストを作成してください。

最終的なカバレッジ数値をチェックポイントに記録してください。

3.4 クリーンアーキテクチャ監査

Consigliere が Step 4 でアーキテクチャ面から確認します。このサブチェックは、機械的な事前フィルターです。変更した各ファイルについて、以下を確認してください。

1. 依存関係の方向： ファイルがインポートするのは、より下位のレイヤーのみであること（ドメイン → アプリケーション → インフラストラクチャ → デリバリー）。上位レイヤーから下位レイヤーへのインポートは、Contract で依存関係の逆転が明示的に承認されていない限り、ブロッキング欠陥です。
2. デリバリーレイヤーまたはインフラストラクチャレイヤーにビジネスロジックを置かない： コントローラー、CLI ハンドラー、ルートバインディング、DB アダプター、ネットワーククライアントには、マーシャリングと委譲のみを含めてください。ビジネスルールはドメインまたはアプリケーションのコードに置きます。
3. 単一責任： ファイル名が単一の責任を示し、ファイルの内容もそれに従っていること。無関係な処理を2つ行うファイルは、ブロッキング欠陥です。

プロジェクトに正式なレイヤー構成がない場合、このサブチェックはデフォルトで合格とし、チェックポイントに「このプロジェクトには正式なアーキテクチャレイヤーがありません」と記載してください。

3.5 クリーンコード監査

まず自動修正を無効にしてプロジェクトのリンターを実行し、違反を確認してください。

<project lint command — no auto-fix>

リンターの確認に加えて、変更したファイルをスキャンし、以下の機械的なクリーンコード違反がないか確認してください。

1. デッドコード： 未使用のインポート、到達不能な分岐、コメントアウトされたコード、未使用のプライベート関数は削除してください。（デバッグログの処理は Step 4 のクリーンアップで行います。ここでは残存した足場コードを対象とします。）
2. 長い関数： 空行とコメントを除いて50行を超える関数はすべて指摘対象です。各関数が単一の処理を行うまで、サブ関数を抽出してください。50行以上でも実際に単一の処理である関数（例：テーブル駆動型のテストケース）は、インラインで説明してください。
3. 深いネスト： ネスト（if／for／while／try）が4レベルを超えるコードパスは、ブロッキング欠陥です。早期リターン、ガード節、またはヘルパーの抽出によってフラット化してください。
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]

Step 4：Consigliere による最終レビュー

統合されたコードのアーキテクチャ監査のため、gangsta:the-consigliere を呼び出してください。

• 実装は Contract に準拠していますか？
• アーキテクチャ上のリグレッションはありますか？
• 最終コードのセキュリティレビュー
• 統合について懸念はありますか？

Consigliere が CRITICAL な懸念を示した場合は、次に進む前に修正してください。 CONCERNS の場合は、Don に提示して判断を仰いでください。 APPROVE の場合は、次に進んでください。

Consigliere によるアーキテクチャ評価と並行して、コードレベルの独立したレビューを行うには、gangsta:audit-review をディスパッチしてください。

Step 5：自動クリーンアップ

• プロジェクトのフォーマッター／リンターを自動修正付きで実行する
• The Hit 中に追加したデバッグログを削除する
• 本番環境で不要な一時テスト用フィクスチャをクリーンアップする

ステップ 6：証拠の処分

作業上の成果物を削除します：

• The Hit の実行中に作成された一時ファイル
• Worker のディスパッチによる内部実行ログ
• 下書き／中間チェックポイントファイル（最終状態のみを残します）

削除してはいけないもの：

• The Contract（docs/gangsta/<heist-name>/specs/YYYY-MM-DD-contract.md）
• The Execution Plan（docs/gangsta/<heist-name>/plans/YYYY-MM-DD-execution-plan.md）
• The Reconnaissance Dossier（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 が実装と Contract の一致を確認します
• 可用性の規則：成果物の完全な一覧を含む最終チェックポイント
• 予算の規則：最終的なリソース消費量を Don に報告します
• 技術的負債の監査：5 つのサブチェックすべてを実行します（または理由を記録してスキップします）。ブロッキング違反は修正するか、Don の承認を得て例外扱いにし、監査出力をチェックポイントに記録します