From 7496b00fc3ecd5f5ddabc2ad3652ccfad58a079a Mon Sep 17 00:00:00 2001 From: Brummel Date: Mon, 11 May 2026 11:17:09 +0200 Subject: [PATCH] iter or.1.2: repoint top-level docs to docs/journals/ + journal-archive.md --- CLAUDE.md | 25 +++++++++++++++---------- docs/DESIGN.md | 2 +- docs/roadmap.md | 2 +- 3 files changed, 17 insertions(+), 12 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8548bc7..a483210 100644 --- a/CLAUDE.md +++ b/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/-iter-.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 diff --git a/docs/DESIGN.md b/docs/DESIGN.md index 648e233..8b0d665 100644 --- a/docs/DESIGN.md +++ b/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 diff --git a/docs/roadmap.md b/docs/roadmap.md index fce9936..dc15d8d 100644 --- a/docs/roadmap.md +++ b/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/.md`.