CLAUDE: codify iter-cycle and JOURNAL/DESIGN roles

Adds an "Iter cycle" top-level section: work clusters into named
iter families (18a–f, 19a–c, …); after each family closes, the
next iter is a non-optional tidy-iter that runs ailang-architect
over the surface and resolves every drift item by fixing,
ratifying in DESIGN.md, or recording acceptable drift in
JOURNAL.md. Skipping requires an explicit JOURNAL entry naming
the reason.

Also writes down the previously-implicit roles of DESIGN.md
(canonical spec; what AILang IS) and JOURNAL.md (decisions log;
HOW we got here, what's queued, rationale not in DESIGN.md). The
rule was practice for a stretch, then quietly evaporated when no
written rule kept it alive across sessions; codifying it here so
the next compaction doesn't lose it again.
This commit is contained in:
2026-05-08 10:05:59 +02:00
parent a91c3ffd94
commit 8d704cd9b5
+45
View File
@@ -21,6 +21,8 @@ designed to enforce (mandatory reading order, fixed output format,
explicit handoff between architecture / implementation / testing /
debugging).
See @agents/README.md
### What this means in practice
- **Plan, design, decide** — myself. Architectural choices, scope,
@@ -114,3 +116,46 @@ Bounce back to the user only when:
A summary of what shipped is fine and welcome — but in
autonomous mode, follow it with the next dispatch, not a
question.
## Iter cycle
Work is organised into **iters** — tightly scoped commits that
ship a feature, a refactor, or a tidy. Iters cluster into named
families (18af, 19ac, …) where each family advances one larger
concern (e.g. 18af together delivers the RC + uniqueness memory
model).
### Tidy-iter at family boundaries
After every named iter family closes, the next iter is a
**tidy-iter**: run `ailang-architect` over the whole surface, read
its drift report, and resolve every item by either (a) fixing the
drift, (b) updating DESIGN.md to ratify what shipped, or (c)
recording in JOURNAL.md that the drift is acceptable and why.
The tidy-iter is non-optional. Without a scheduled cleanup,
codebases grow by accretion — every iter adds, none tears out,
and the deferral compounds across families. Skipping a tidy-iter
requires an explicit JOURNAL entry naming the reason (e.g. a
sibling family is blocking, or the user has asked to defer).
### Roles of JOURNAL.md and DESIGN.md
- **DESIGN.md** is the canonical specification. It describes what
AILang *is*: schema, semantics, invariants, runtime contracts.
Every new feature must justify itself against DESIGN.md before
it can ship; if the feature requires changes to DESIGN.md,
those changes are part of the same iter. DESIGN.md is also the
artefact `ailang-architect` checks the code against during
drift review.
- **JOURNAL.md** is the decisions log. It records *why* the
project moved the way it did — alternatives considered and
rejected, lessons from past iters, queued options for future
work, and the rationale behind choices that does not belong in
DESIGN.md (rationale is about the choice, not about the
language).
Together they answer two questions: "what is the language right
now?" (DESIGN) and "how did we get here, and what's next?"
(JOURNAL).