the-ledger

Ledger：Gangsta Agents Family の組織的記憶

概要

Ledger は Gangsta Agents Family の永続メモリです。成功した推論経路（Insights）、記録された失敗（Fails）、蓄積されたガバナンスルール（Project Constitution）を保存します。すべての Heist は Ledger を読み書きします。

ディレクトリ構成

Ledger は gangsta パッケージではなく、対象プロジェクト内に配置されます。

docs/gangsta/
├── constitution.md             # Project Constitution (living document)
├── insights/                   # Repository of Insights (Good Catches)
│   └── YYYY-MM-DD-<topic>.md
└── fails/                      # Repository of Fails (Concrete Shoes)
    └── YYYY-MM-DD-<topic>.md

Ledger の初期化

対象プロジェクトに docs/gangsta/ が存在しない場合は、作成します。

mkdir -p docs/gangsta/insights docs/gangsta/fails

初期の docs/gangsta/constitution.md を作成します。

# Project Constitution

## Commandments (from Insights)
_No commandments yet. They will be added as Heists produce insights._

## Negative Constraints (from Fails)
_No constraints yet. They will be added as Heists document failures._

## Architectural Decisions
_No decisions recorded yet._

Insight の記録

基準： 複雑な制約を回避する解決策を見つけた場合、明白ではないアプローチを発見した場合、または新しい Project Commandment を定めた場合に記録します。

ファイル： docs/gangsta/insights/YYYY-MM-DD-<topic-slug>.md

---
date: YYYY-MM-DD
heist: <heist-name>
phase: <phase-where-discovered>
tags: [tag1, tag2, tag3]
---

# <Title: Short description of the insight>

## Discovery
<How the insight was found — which phase, what triggered it>

## Solution
<The successful reasoning pathway or creative solution>

## Project Commandment
<If applicable: a new rule to add to the Constitution>
<If not applicable: omit this section>

記録後、docs/gangsta/constitution.md を更新します。

• 該当する場合は、Commandments セクションに命令を追加します
• 出典を記載します：— Source: insights/YYYY-MM-DD-<topic>.md

Fail の記録

基準： あるアプローチがリグレッションやセキュリティ上の不備を引き起こした場合、時間を浪費した場合、または誤った実装につながった場合に記録します。

ファイル： docs/gangsta/fails/YYYY-MM-DD-<topic-slug>.md

---
date: YYYY-MM-DD
heist: <heist-name>
phase: <phase-where-occurred>
tags: [tag1, tag2, tag3]
severity: critical | high | medium | low
---

# <Title: Short description of the failure>

## What Happened
<Description of the failure and its observable impact>

## Cognitive Diagnosis
<Causal mechanism explaining WHY the failure occurred — not just what went wrong, but the reasoning error that led to it>

## Negative Constraint
<The explicit prohibition: "NEVER [prohibited pattern] because [reason]">

記録後、docs/gangsta/constitution.md を更新します。

• Negative Constraints セクションに否定的制約を追加します
• 出典を記載します：— Source: fails/YYYY-MM-DD-<topic>.md

Ledger の参照

Reconnaissance 中

insights/ と fails/ を検索し、現在の Heist のトピックに一致するタグが付いた項目を探します。関連する項目を Reconnaissance Dossier に提示します。

The Grilling 中

Devils-Advocate は、提案を受け入れる前にすべての Negative Constraints を必ず確認します。提案が Negative Constraint に違反する場合、自動的に却下されます。

The Sit-Down 中

Underboss は Contract の草案作成時に Commandments を参照します。関連する Commandment はすべて Contract に記載する必要があります。

The Hit 中

Workers は実装前に Negative Constraints を確認します。Work Package が制約に違反する可能性がある場合、Worker は Crew Lead にエスカレーションします。

Laundering 中

Heist で得られた新しい insights と fails を記録します。Constitution を更新します。

Omerta の遵守

• Rule of Truth：Ledger のすべての項目に、具体的なフェーズ、Heist、観察可能な証拠を記載します
• Rule of Availability：Ledger ファイルは更新のたびに git にコミットします
• Spec is Law：Constitution の Negative Constraints は、今後のすべての Heist で拘束力を持ちます