diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 18dda71..b4c21e3 100644 --- a/ARCHITECTURE.md +++ b/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 | diff --git a/CLAUDE_CODE_INSTRUCTIONS.md b/CLAUDE_CODE_INSTRUCTIONS.md index 4097454..32d51fc 100644 --- a/CLAUDE_CODE_INSTRUCTIONS.md +++ b/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 | diff --git a/CLAUDE_SESSION_LOG.md b/CLAUDE_SESSION_LOG.md new file mode 100644 index 0000000..ca4c6e3 --- /dev/null +++ b/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 `` 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.)* + + diff --git a/README.md b/README.md index 76ccf4f..d9bd76c 100644 --- a/README.md +++ b/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 |