iter or.1.2: repoint top-level docs to docs/journals/ + journal-archive.md

CLAUDE.md

@@ -37,7 +37,7 @@ it measurably improves correctness or removes redundancy.
 | `runtime/` | C glue around the RC runtime |
 | `bench/` | Regression harnesses (`check.py`, `compile_check.py`, `cross_lang.py`) and the throughput-and-latency runner (`run.sh`); `bench/reference/` holds the hand-C corpus for cross-language ratios |
 | `examples/` | AILang fixtures used by tests and benches |
-| `docs/` | Canonical specs and decisions log — `docs/DESIGN.md`, `docs/JOURNAL.md`, `docs/specs/` (per-milestone design specs), `docs/plans/` (per-iteration plans), `PROSE_ROUNDTRIP.md` |
+| `docs/` | Canonical specs and decisions log — `docs/DESIGN.md`, `docs/journals/` (per-iter journals + `INDEX.md`), `docs/journal-archive.md` (pre-2026-05-11 history), `docs/specs/` (per-milestone design specs), `docs/plans/` (per-iteration plans), `PROSE_ROUNDTRIP.md` |
 | `skills/` | Project-local skill definitions and their agents. See `skills/README.md` for the skill table, agent roster, and discovery layout. |
 
 ## Skill system
@@ -63,7 +63,7 @@ See @skills/README.md for the skill + agent roster.
 ### What this means in practice
 
 - **Plan, design, decide** — myself. Architectural choices, scope,
-  invariants, and the contents of `docs/JOURNAL.md` and
+  invariants, and the contents of `docs/journals/` and
   `docs/DESIGN.md` are my work product.
 - **Implement, refactor, write tests, diagnose bugs** — by default,
   delegated. `ailang-implementer` for code changes that follow a
@@ -188,7 +188,7 @@ up, nothing left to do for the user to react to), the procedure
 is two-step and the two outputs share one text:
 
 1. Append a new entry to `docs/WhatsNew.md` (newest at the bottom,
-   append-only — same chronological convention as `JOURNAL.md`).
+   append-only — same chronological convention as the per-iter journals).
 2. Send the same text via `~/.claude/notify.sh`.
 
 The text must be written for the **user-as-reader who did not
@@ -236,7 +236,7 @@ Vocabulary note: legacy JOURNAL entries (pre-2026-05-09) use
 "iter" / "family"; new entries use "iteration" / "milestone".
 Existing entries are not retroactively renamed.
 
-## Roles of `docs/DESIGN.md`, `docs/JOURNAL.md`, `docs/roadmap.md`, `docs/specs/`, `docs/plans/`
+## Roles of `docs/DESIGN.md`, `docs/journals/`, `docs/journal-archive.md`, `docs/roadmap.md`, `docs/specs/`, `docs/plans/`
 
 - **`docs/DESIGN.md`** is the canonical specification. It describes
   what AILang *is*: schema, semantics, invariants, runtime contracts.
@@ -246,12 +246,17 @@ Existing entries are not retroactively renamed.
   `docs/DESIGN.md` is also the artefact `ailang-architect` checks
   the code against during drift review.
 
-- **`docs/JOURNAL.md`** is the decisions log. It records *why* the
-  project moved the way it did — alternatives considered and
-  rejected, lessons from past iterations, and the rationale behind
-  choices that does not belong in `docs/DESIGN.md` (rationale is
-  about the choice, not about the language). It is chronological
-  and append-only; it does not carry the forward queue.
+- **`docs/journals/<YYYY-MM-DD>-iter-<id>.md`** is the decisions
+  log, one file per iter. Each file records *why* the iter moved
+  the way it did — alternatives considered and rejected, lessons,
+  rationale that does not belong in `docs/DESIGN.md`. Append-only
+  per file; new files are appended via `docs/journals/INDEX.md`.
+  `docs/journals/INDEX.md` is the chronological pointer list,
+  Boss-maintained, one line per iter.
+
+- **`docs/journal-archive.md`** is the archived monolithic
+  decisions log for everything pre-2026-05-11. Content-frozen.
+  Read it only when chasing long-tail history; do not append.
 
 - **`docs/roadmap.md`** (since 2026-05-10): the priority-ordered
   forward queue — milestones, features, todos, and ideas. The

docs/DESIGN.md

@@ -46,7 +46,7 @@ evolving in lockstep with the language:
   development methodology and are versioned with the codebase.
   See `skills/README.md`.
 - **Docs** (`docs/`): `DESIGN.md` (canonical state),
-  `JOURNAL.md` (chronological decisions log),
+  `docs/journals/` (per-iter decisions log; see `INDEX.md`) plus the archived `docs/journal-archive.md` for pre-2026-05-11 history,
   `roadmap.md` (forward queue), `specs/` (per-milestone design
   specs), `plans/` (per-iteration implementation plans).
 - **Tests**: unit tests per crate plus E2E in `crates/ail/tests/e2e.rs`. Every

docs/roadmap.md

@@ -11,7 +11,7 @@ work progresses.
   (work has started — a plan exists, a branch is open, or commits are
   landing); `- [x]` is done. A finished entry may stay briefly for
   context, then is removed (with a one-line mirror in
-  `docs/JOURNAL.md`).
+  `docs/journals/`).
 - Each entry is tagged by **kind** and lives under a **priority**
   bucket:
   - **\[milestone\]** — big chunk that will get a `docs/specs/<milestone>.md`.