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:
@@ -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 (18a–f, 19a–c, …) where each family advances one larger
|
||||
concern (e.g. 18a–f 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).
|
||||
|
||||
Reference in New Issue
Block a user