From c252b1aa2846b3c423cd40e7d9d131a7bb12970d Mon Sep 17 00:00:00 2001 From: Brummel Date: Mon, 11 May 2026 12:03:01 +0200 Subject: [PATCH] iter or.1.tidy: audit-driven sweep of stale JOURNAL.md references in live docs --- CLAUDE.md | 13 +++++++------ docs/WhatsNew.md | 8 ++++---- docs/roadmap.md | 8 +++++--- skills/audit/agents/ailang-architect.md | 14 +++++++------- 4 files changed, 23 insertions(+), 20 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1196fac..bf135e0 100644 --- a/CLAUDE.md +++ b/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 - why I bypassed the agent. + that case I do the small change inline and note in the per-iter + 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/.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), -and "what's next?" (roadmap). `WhatsNew.md` is the user-facing -mirror of the JOURNAL — the same history, told without internals. +now?" (DESIGN), "how did we get here?" (per-iter journals, specs, +plans), and "what's next?" (roadmap). `WhatsNew.md` is the +user-facing mirror of the journals — the same history, told without +internals. diff --git a/docs/WhatsNew.md b/docs/WhatsNew.md index adb3c02..ffcd660 100644 --- a/docs/WhatsNew.md +++ b/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 -the work happen — no crate names, no iteration codes, no -implementation mechanics. +per-iter journals (`docs/journals/`) and is written for the +user-as-reader who did not watch the work happen — no crate names, +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. --- diff --git a/docs/roadmap.md b/docs/roadmap.md index dc15d8d..625e415 100644 --- a/docs/roadmap.md +++ b/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 - rationale lives. The roadmap is intentionally terse; rationale - stays in JOURNAL. +- Optional `context:` line points to the journal entry (per-iter + file under `docs/journals/` or, for pre-2026-05-11 entries, the + 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. diff --git a/skills/audit/agents/ailang-architect.md b/skills/audit/agents/ailang-architect.md index f05e538..a59de79 100644 --- a/skills/audit/agents/ailang-architect.md +++ b/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 - diff, or is it optimistic? An over-claiming JOURNAL is its own kind of - drift. +- **Journal truthfulness.** Does the most recent per-iter journal entry + match the diff, or is it optimistic? An over-claiming journal entry + 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- - quote) is fine; a fresh history anchor / REVERTED narrative / + match: a legitimate quote (e.g. a journal-entry citation inside a + 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. |