Sync docs with repo state, add Claude session log

ARCHITECTURE.md

@@ -52,17 +52,17 @@ data/
 ├── traps.yaml           # 14 analytical traps with session extensions
 ├── observations.yaml    # 30 observations with status tracking
 ├── scenarios.yaml       # 12 scenarios (wartime W1-W5 + legacy)
-├── sessions.yaml        # 21 session logs
+├── sessions.yaml        # 20 session log entries (sessions 1-21)
 ├── modules.yaml         # Module registry (code, file, version, level)
 ├── index_meta.yaml      # Static content for master index template
-├── content/             # ITB/ISA module prose (19 files)
-│   ├── itb_a_core.yaml
-│   ├── itb_a1.yaml
+├── content/             # ITB/ISA module prose (22 files)
+│   ├── itb_a.yaml
+│   ├── itb_a6.yaml
 │   ├── itb_b.yaml
 │   └── ... (one file per module)
-└── briefs/              # Convergence brief content (14 files)
-    ├── brief_01.yaml
-    ├── brief_02.yaml
+└── briefs/              # Convergence brief content (17 files)
+    ├── b01.yaml
+    ├── b02.yaml
     └── ... (one file per brief)
 ```
 
@@ -181,7 +181,7 @@ Renders entity reports and content modules. Uses a single Jinja2 environment
 | `traps` | `output/ISA_TRAPS.md` |
 | `scenarios` | `output/ISA_SCENARIOS.md` |
 | `index` | `output/00_MASTER_INDEX.md` |
-| `content` | All 19 content module files |
+| `content` | All 22 content module files |
 | `--validate` | Runs validate.py first, aborts on failure |
 
 ### `build_briefs.py`
@@ -210,7 +210,7 @@ Exec summary → Introduction → Briefs 01-13 → Emergency brief → 4-table r
 appendix (variables, gaps, traps, observations). Clickable TOC. Public audience.
 
 **Tier 2 — `ITP-Reference-v{date}.pdf`**
-All Tier 1 content + all 19 ITB/ISA content modules. Two-part TOC. Research audience.
+All Tier 1 content + all 22 ITB/ISA content modules. Two-part TOC. Research audience.
 
 PDF rendering stack: Python `markdown` → HTML with embedded CSS → `weasyprint` → PDF.
 A4, Georgia serif, running page numbers. Brief assembly order controlled by
@@ -285,8 +285,8 @@ reliably. Avoid echo-based approaches for multi-line content.
 |-------|--------|-------------|
 | 0 | Complete | Variables, Gaps — build pipeline proven |
 | 1 | Complete | Traps, Observations, Scenarios, Sessions, Modules |
-| 2 | Complete | 19 ITB/ISA module prose files in `data/content/` |
-| 3 | Complete | 14 convergence briefs in `data/briefs/` |
+| 2 | Complete | 22 ITB/ISA module prose files in `data/content/` |
+| 3 | Complete | 17 convergence briefs in `data/briefs/` |
 | 3e | Complete | Testing, cleanup, index wiring |
 | PDF | Complete | `build_pdf.py` two-tier release builder |
 

CLAUDE_CODE_INSTRUCTIONS.md

@@ -16,21 +16,21 @@ framework/
 │   ├── traps.yaml           # ISA-TRAPS analytical traps (14 entries)
 │   ├── observations.yaml    # Project observations (30 entries)
 │   ├── scenarios.yaml       # Scenario matrix (12 entries)
-│   ├── sessions.yaml        # Session log (21 entries)
+│   ├── sessions.yaml        # Session log (20 entries)
 │   ├── modules.yaml         # Module registry (28 entries)
 │   ├── index_meta.yaml      # Master index semi-static content
-│   ├── content/             # MODULE PROSE (19 modules)
-│   │   ├── itb_a_core.yaml
+│   ├── content/             # MODULE PROSE (22 modules)
+│   │   ├── itb_a.yaml
 │   │   ├── itb_b.yaml
 │   │   └── ... (one file per module)
-│   └── briefs/              # CONVERGENCE BRIEFS (14 files)
+│   └── briefs/              # CONVERGENCE BRIEFS (17 files)
 │       ├── b01.yaml - b13.yaml  # Numbered briefs
 │       ├── eb01.yaml            # Emergency Brief
 │       ├── es.yaml              # Executive Summary
 │       ├── intro.yaml           # Introduction
 │       └── supp_psc.yaml        # Supplemental
 │
-├── schemas/                 # VALIDATION RULES (10 schemas)
+├── schemas/                 # VALIDATION RULES (9 schemas)
 │   ├── variable.schema.json
 │   ├── gap.schema.json
 │   ├── trap.schema.json
@@ -39,8 +39,7 @@ framework/
 │   ├── session.schema.json
 │   ├── module.schema.json
 │   ├── content.schema.json
-│   ├── brief.schema.json
-│   └── index_meta.schema.json
+│   └── brief.schema.json
 │
 ├── templates/               # REPORT TEMPLATES (Jinja2)
 │   ├── app_variables.md.j2
@@ -57,7 +56,9 @@ framework/
 │   ├── migrate_variables.py
 │   ├── migrate_gaps.py
 │   ├── migrate_content.py
-│   └── migrate_all_briefs.py
+│   ├── migrate_all_briefs.py
+│   ├── migrate_b03.py
+│   └── cleanup_variables.py
 │
 ├── output/                  # GENERATED MARKDOWN (gitignored — never edit)
 ├── releases/                # GENERATED PDFs (gitignored — attach to GitHub Releases)
@@ -67,7 +68,13 @@ framework/
 ├── build.py                 # YAML → Markdown: entity reports + content modules
 ├── build_briefs.py          # YAML → Markdown: convergence briefs
 ├── build_pdf.py             # Markdown → PDF: two-tier release bundles
+├── ARCHITECTURE.md          # Database design and pipeline documentation
+├── README.md                # Project overview and quickstart
+├── CONTRIBUTING.md          # Contribution standards and CLA
+├── GOVERNANCE.md            # Mission constraint and succession plan
+├── CLAUDE_SESSION_LOG.md    # Claude-to-Claude coordination log
 ├── RELEASE_NOTES_TEMPLATE.md
+├── LICENSE
 └── CLAUDE_CODE_INSTRUCTIONS.md  # This file
 ```
 
@@ -424,6 +431,33 @@ Then create a GitHub Release tagged `v{YYYY-MM-DD}` and attach the PDFs from
 
 ---
 
+## Claude-to-Claude Coordination
+
+Analytical research happens in **Claude Chat** sessions; repository maintenance
+happens in **Claude Code** sessions. The two coordinate via `CLAUDE_SESSION_LOG.md`.
+
+### Workflow
+
+1. **Chat** completes an analytical session and appends an Integration Request to
+   the log — listing new entities, updated fields, filled gaps, session number, and
+   any ambiguities.
+2. **Code** reads the log, translates the request into YAML edits, validates, builds,
+   and commits. Then appends an Integration Complete entry.
+3. **Code** prunes resolved request/confirmation pairs on subsequent sessions.
+   Git preserves full history.
+
+### Rules
+
+- Both sides append; neither edits the other's entries.
+- Only Code deletes resolved entries.
+- Integration requests must reference session numbers and entity IDs, not dump
+  large prose blocks into the log.
+- When in doubt, the human owner resolves conflicts.
+
+See `CLAUDE_SESSION_LOG.md` for the full protocol and entry format.
+
+---
+
 ## Mojibake Handling
 
 All current YAML content files are clean. If mojibake appears in rendered output,
@@ -449,8 +483,8 @@ Common patterns:
 |-------|-------------|
 | 0 | Variables, Gaps — pipeline proven |
 | 1 | Traps, Observations, Scenarios, Sessions, Modules |
-| 2 | 19 ITB/ISA module prose files in `data/content/` |
-| 3 | 14 convergence briefs in `data/briefs/` |
+| 2 | 22 ITB/ISA module prose files in `data/content/` |
+| 3 | 17 convergence briefs in `data/briefs/` |
 | 3e | Testing, cleanup, index wiring |
 | PDF | `build_pdf.py` two-tier release builder |
 

CLAUDE_SESSION_LOG.md

@@ -0,0 +1,46 @@
+# Claude-to-Claude Session Log
+
+Coordination log between **Claude Chat** (analytical research sessions) and
+**Claude Code** (repository maintenance). Both may append entries. Only Claude Code
+may delete entries that are fully resolved. Git tracks all history.
+
+---
+
+## Protocol
+
+### Entry format
+
+```
+### YYYY-MM-DD — [Source] — [Type]
+
+Body text.
+```
+
+- **Source:** `Chat` or `Code`
+- **Type:** one of:
+  - `Integration Request` — Chat asks Code to commit analytical output to the database
+  - `Integration Complete` — Code confirms an integration request has been applied
+  - `Question` — either side asks the other for clarification
+  - `Note` — informational, no action required
+  - `Cleanup` — Code signals that resolved entries above have been pruned
+
+### Rules
+
+1. **Append only** — new entries go at the bottom, above the `<!-- END LOG -->` marker.
+2. **Never edit another side's entries** — respond with a new entry instead.
+3. **Code owns cleanup** — after an integration is confirmed and verified, Code may
+   remove the request + confirmation pair on a subsequent session. Git preserves history.
+4. **Keep entries concise** — link to session numbers or entity IDs rather than
+   duplicating large blocks of content.
+5. **Integration requests must include:**
+   - Session number
+   - Summary of changes (new entities, updated fields, filled gaps, etc.)
+   - Any ambiguities or decisions that need human confirmation
+
+---
+
+## Log
+
+*(No entries yet.)*
+
+<!-- END LOG -->

README.md

@@ -29,10 +29,10 @@ For database design and build pipeline details, see [ARCHITECTURE.md](ARCHITECTU
 ```
 /
 ├── data/                        # YAML source-of-truth files
-│   ├── content/                 # ITB/ISA module prose (19 files)
-│   ├── briefs/                  # Convergence brief content (14 files)
+│   ├── content/                 # ITB/ISA module prose (22 files)
+│   ├── briefs/                  # Convergence brief content (17 files)
 │   └── *.yaml                   # Variables, gaps, traps, observations, scenarios, sessions
-├── schemas/                     # JSON Schema definitions (10 schemas)
+├── schemas/                     # JSON Schema definitions (9 schemas)
 ├── templates/                   # Jinja2 rendering templates
 ├── scripts/                     # One-time migration utilities
 ├── .github/workflows/           # CI configuration
@@ -77,7 +77,7 @@ PDF bundles are published as [GitHub Releases](../../releases). Each release inc
 
 | Component | Coverage | Status |
 |-----------|----------|--------|
-| Iran Transition Baseline (ITB) | 8 pillars, 19 modules | Active |
+| Iran Transition Baseline (ITB) | 8 pillars, 22 modules | Active |
 | Iran Stress Architecture (ISA) | Traps, observations, scenarios | Active |
 | Policy briefs | 13 published + supplementals | Active |
 | Analytical variables | 86 tracked | Active |