iter or.1.tidy: audit-driven sweep of stale JOURNAL.md references in live docs

CLAUDE.md

@@ -105,8 +105,8 @@ not as immutable scripture.
   use approach X or Y?") — that is orchestrator work.
 - When I have already loaded the relevant context for a different
   reason and a sub-agent would have to redo the same reading. In
-  that case I do the small change inline and note in the JOURNAL
+  that case I do the small change inline and note in the per-iter
-  why I bypassed the agent.
+  journal why I bypassed the agent.
 
 ### Design rationale ≠ implementation effort
 
@@ -264,7 +264,7 @@ Existing entries are not retroactively renamed.
   current: adding new entries, reprioritising, removing items
   that are done or dropped. Entries are checkbox lines; finished
   items get checked off, then removed (with a one-line mirror in
-  JOURNAL) once they stop being interesting context.
+  the per-iter journal) once they stop being interesting context.
 
 - **`docs/specs/<milestone>.md`** (since 2026-05-09): per-milestone
   design spec produced by `skills/brainstorm`. Hard-gate before any
@@ -282,6 +282,7 @@ Existing entries are not retroactively renamed.
   rules (in particular: no internals, lead with the change).
 
 Together these answer three questions: "what is the language right
-now?" (DESIGN), "how did we get here?" (JOURNAL, specs, plans),
+now?" (DESIGN), "how did we get here?" (per-iter journals, specs,
-and "what's next?" (roadmap). `WhatsNew.md` is the user-facing
+plans), and "what's next?" (roadmap). `WhatsNew.md` is the
-mirror of the JOURNAL — the same history, told without internals.
+user-facing mirror of the journals — the same history, told without
+internals.

docs/WhatsNew.md

@@ -1,9 +1,9 @@
 # What's New in AILang
 
 A user-facing changelog. It runs in parallel to the technical
-`JOURNAL.md` and is written for the user-as-reader who did not watch
+per-iter journals (`docs/journals/`) and is written for the
-the work happen — no crate names, no iteration codes, no
+user-as-reader who did not watch the work happen — no crate names,
-implementation mechanics.
+no iteration codes, no implementation mechanics.
 
 Each entry corresponds to a done-state notification I sent to the
 user when he was away. The text is identical to what arrived on his
@@ -11,6 +11,6 @@ phone. New entries are appended at the bottom.
 
 What gets described here is **what changed in the project** — what
 is now possible, fixed, or visible. For the internals, see
-`JOURNAL.md`.
+`docs/journals/INDEX.md` and the per-iter journal files it points at.
 
 ---

docs/roadmap.md

@@ -22,9 +22,11 @@ work progresses.
   - **\[idea\]** — not yet decision-ready, no commitment.
 - Optional `depends on:` line names another entry that has to land
   first.
-- Optional `context:` line points to the JOURNAL entry where the
+- Optional `context:` line points to the journal entry (per-iter
-  rationale lives. The roadmap is intentionally terse; rationale
+  file under `docs/journals/` or, for pre-2026-05-11 entries, the
-  stays in JOURNAL.
+  archived `docs/journal-archive.md`) where the rationale lives.
+  The roadmap is intentionally terse; rationale stays in the
+  journals.
 - Priority buckets:
   - **P0** — in flight. Spec or plan already exists.
   - **P1** — next up. Decision made; not yet started.

skills/audit/agents/ailang-architect.md

@@ -57,7 +57,7 @@ If `milestone_scope` is empty, return a structural error and stop.
 - **Drift against the milestone spec** (if one exists). Does the code match
   the spec's *Components* and *Data flow* sections?
 - **Growing debt.** Heuristics where the schema is authoritative,
-  TODO/FIXME without a JOURNAL ticket, `#[allow(dead_code)]` spots that will
+  TODO/FIXME without a per-iter-journal ticket, `#[allow(dead_code)]` spots that will
   tip over long-term, magic numbers without named constants in hot paths.
 - **Consistency across crates.** AST changes that landed in one crate but
   not its mirror in another. Match arms that aren't exhaustive because a
@@ -67,15 +67,15 @@ If `milestone_scope` is empty, return a structural error and stop.
 - **Scaling break points.** Where will the next plausible step (modules,
   closures, GC retirement, nested patterns) be blocked? This is the early-
   warning channel.
-- **JOURNAL truthfulness.** Does the most recent JOURNAL entry match the
+- **Journal truthfulness.** Does the most recent per-iter journal entry
-  diff, or is it optimistic? An over-claiming JOURNAL is its own kind of
+  match the diff, or is it optimistic? An over-claiming journal entry
-  drift.
+  is its own kind of drift.
 - **DESIGN.md history-anchor regrowth.** Run
   `bash bench/architect_sweeps.sh` from the repo root. Exit 0 = clean.
   Exit 1 = at least one of the four sweeps from the
   design-md-consolidation milestone (2026-05-10) matched. Review each
-  match: a legitimate quote (e.g. a JOURNAL citation inside a block-
+  match: a legitimate quote (e.g. a journal-entry citation inside a
-  quote) is fine; a fresh history anchor / REVERTED narrative /
+  block-quote) is fine; a fresh history anchor / REVERTED narrative /
   workflow detail / stale cross-reference is drift to flag.
 - **Lockstep invariants across files.** Two known cross-file pairings
   must move together; a new arm in one without the matching update in
@@ -151,7 +151,7 @@ valid and welcome result.
 |--------|---------|
 | "I'll suggest the fix while I'm at it — orchestrator can ignore it" | The orchestrator can't unread a fix proposal. Once you name a fix, the design space is biased. Name the drift; stop. |
 | "This drift is trivial, no need to flag" | "Trivial" left unflagged trains the orchestrator to treat your reports as advisory. Five trivial items in, five out. |
-| "JOURNAL says the iteration cleaned this up, so it's fine" | The JOURNAL is a claim, not evidence. Read the diff; trust the diff. |
+| "The per-iter journal says the iteration cleaned this up, so it's fine" | A journal entry is a claim, not evidence. Read the diff; trust the diff. |
 | "DESIGN.md is fuzzy on this point, can't call drift" | Then flag the DESIGN.md gap as a separate item. The fix is to tighten DESIGN.md, but you don't write that fix — you name the gap. |
 | "I'll only review the changed files, faster" | Drift often shows up in unchanged files that NOW contradict a changed neighbour. Read the load-bearing neighbours too. |
 | "This bench-related observation is more bencher's job — skip" | If a perf claim contradicts DESIGN.md (e.g. "RC has bounded p99"), you flag the contradiction. Bencher gets the data; you call drift. |