iter or.1.3: repoint skill + agent reading lists to docs/journals/

2026-05-11 11:24:58 +02:00
parent c069087573
commit 4017e514f7
10 changed files with 33 additions and 33 deletions
@@ -8,7 +8,7 @@ established practice without explicitly violating a named rule.

 The system was bootstrapped on 2026-05-09. See
 `docs/specs/2026-05-09-skill-system.md` for the design and
-`docs/JOURNAL.md` ("Skill system live") for the rationale.
+`docs/journal-archive.md` ("Skill system live") for the rationale.

 ## The six skills

@@ -16,7 +16,7 @@ The system was bootstrapped on 2026-05-09. See
 |-------|---------|--------|------------|
 | [`brainstorm`](brainstorm/SKILL.md) | New milestone starting | `docs/specs/<milestone>.md` | Hard-gate before plan |
 | [`planner`](planner/SKILL.md) | New iteration within an open milestone | `docs/plans/<iteration>.md` | Hard-gate before implement |
-| [`implement`](implement/SKILL.md) | Plan exists | Code + tests + per-task commits + JOURNAL entry | Standard iteration path |
+| [`implement`](implement/SKILL.md) | Plan exists | Code + tests + per-task commits + per-iter journal entry | Standard iteration path |
 | [`audit`](audit/SKILL.md) | Milestone closing OR baseline drift suspected | Drift report + bench-regression report + rustdoc audit | **Mandatory** at milestone close |
 | [`fieldtest`](fieldtest/SKILL.md) | After audit closes a milestone that touched user-visible surface | 2-4 `.ailx` example fixtures + `docs/specs/<date>-fieldtest-<milestone>.md` | Standard milestone-close path; skipped only for purely internal milestones |
 | [`debug`](debug/SKILL.md) | Bug encountered (failing test, segfault, wrong stdout) | RED-test commit + cause analysis | **Mandatory RED-first** for any bug |
@@ -78,7 +78,7 @@ Every agent file follows the same superpowers-derived template:
 - **What this role is for:** one short paragraph naming the failure mode
  the agent exists to prevent.
 - **Standing reading list:** the always-binding documents (CLAUDE.md,
-  DESIGN.md, JOURNAL.md tail, plus role-specific anchors).
+  DESIGN.md, latest per-iter journals, plus role-specific anchors).
 - **Carrier contract:** what the controller hands the agent (`task_text`,
  `diff`, `hypothesis`, etc.). Agents do NOT open `docs/plans/` or
  `docs/specs/` directly — context curation lives at the skill level.
@@ -136,14 +136,14 @@ dispatch can find them by `subagent_type`:

 - **No orphan agents.** Every agent lives under the skill that
  dispatches it. If a recurring need does not fit any skill, raise
-  the question in `docs/JOURNAL.md` before adding the agent.
+  the question via a per-iter journal entry before adding the agent.
 - **Agents do not call other agents.** The dirigierende skill
  composes (e.g. `implement` dispatches implementer, then a separate
  spec-compliance reviewer, then a code-quality reviewer).
 - **Standing reading list stays in the agent file.** The skill provides
  the carrier (task text, bug symptom, drift focus, hypothesis) on top
-  of the agent's standing reading list (CLAUDE.md, DESIGN.md, JOURNAL.md
-  tail, role-specific anchors). Agents do NOT open `docs/plans/` or
+  of the agent's standing reading list (CLAUDE.md, DESIGN.md, latest per-iter journals,
+  role-specific anchors). Agents do NOT open `docs/plans/` or
  `docs/specs/` directly — context curation lives at the skill level.
 - **Skill and agent definitions are reviewable code.** Edits go
  through git. Commit messages name why the role shifted.
@@ -168,4 +168,4 @@ dispatch can find them by `subagent_type`:
 3. Update the agent roster above and the dispatching skill's
   "Cross-references" section.
 4. If the agent is genuinely standalone (no skill dispatches it),
-   raise the question in `docs/JOURNAL.md` first.
+   raise the question via a per-iter journal entry first.
@@ -46,7 +46,7 @@ Dispatch `ailang-architect` with the milestone scope (commit range
 from the previous milestone-close to `HEAD`):

 ```
-For milestone <X>: read DESIGN.md, JOURNAL.md, the latest milestone
+For milestone <X>: read DESIGN.md, `docs/journals/INDEX.md` and the latest 1–3 referenced files, the latest milestone
 entries; git log/diff over <prev-close>..HEAD; report drift.
 ```

@@ -30,7 +30,7 @@ fixes; your authority ends at *naming the problem*.
 2. `docs/DESIGN.md` — the canonical specification. Drift is measured against
   this document, in full. Skim is not enough; read every section that the
   recent diff might have touched.
-3. `docs/JOURNAL.md` — the full log, with focus on the milestone you're
+3. `docs/journals/INDEX.md` + the per-iter files for the milestone you're
   reviewing. The latest entry is the current claimed state; your job
   includes asking whether the claim is true.
 4. `docs/specs/<milestone>.md` if one exists for this milestone — the
@@ -97,7 +97,7 @@ If `milestone_scope` is empty, return a structural error and stop.
 ```
 DIAGNOSE ONLY. NAME THE PROBLEM, NOT THE FIX.
 DRIFT IS DRIFT EVEN IF "MINOR" — THE ORCHESTRATOR DECIDES PRIORITY.
-NO EDITS. NOT TO CODE, NOT TO DESIGN.MD, NOT TO JOURNAL.MD.
+NO EDITS. NOT TO CODE, NOT TO DESIGN.MD, NOT TO ANY JOURNAL FILE.
 ```

 Your tools include `Read, Glob, Grep, Bash` — but `Bash` is for read-only
@@ -106,7 +106,7 @@ to fix one).

 ## The Process

-1. Read the standing list, in this order: CLAUDE.md → DESIGN.md → JOURNAL
+1. Read the standing list, in this order: CLAUDE.md → DESIGN.md → `docs/journals/INDEX.md` + the per-iter files
   tail → spec (if any) → recent diff.
 2. `git log --oneline -30` and `git diff <prev-milestone-close>..HEAD` for
   the factual diff.
@@ -37,10 +37,10 @@ don't paper over it with a chart.
 1. `CLAUDE.md` — orchestrator framing.
 2. `docs/DESIGN.md`, especially Decision 9 (Boehm transitional) and
   Decision 10 (RC + uniqueness).
-3. `docs/JOURNAL.md` — most recent entries are the current state of
+3. `docs/journals/INDEX.md` + the latest 3 referenced files — current state of
   the memory-management infrastructure. Read at minimum the latest
   18-arc entries to know what RC actually supports today.
-4. `bench/run.sh` and any prior bench results recorded in JOURNAL.
+4. `bench/run.sh` and any prior bench results recorded in the per-iter journals.
 5. `runtime/rc.c` and `runtime/bump.c` — the allocator implementations
   you are benchmarking.

@@ -50,7 +50,7 @@ don't paper over it with a chart.
 |-------|---------|
 | `hypothesis` | The orchestrator's falsifiable claim, in one sentence |
 | `decision_unblocked_by` | What orchestrator decision the answer enables (e.g. "retire Boehm", "ratify the regression on metric X") |
-| `prior_data` | Pointer to existing JOURNAL bench entries that frame this question, or `none` |
+| `prior_data` | Pointer to existing per-iter-journal bench entries that frame this question, or `none` |
 | `constraints` | Optional: timebox, available fixtures, instrumentation budget |

 If `hypothesis` is vague ("is Boehm slow?"), return `NEEDS_CONTEXT` —
@@ -145,7 +145,7 @@ is a side experiment, not the headline.

 - New allocator strategies, new memory-model features, fixes to leaks, or
  any "while I was in there" code changes. Those are implementer territory.
- DESIGN.md / JOURNAL.md edits. The orchestrator writes those based on
+- DESIGN.md / journal edits. The orchestrator writes those based on
  your report.
 - Verdict statements like "Boehm should be retired" or "RC is the winner".
  You report data and what it implies; the orchestrator decides.
@@ -32,7 +32,7 @@ that's a finding for the orchestrator — not a rename you make on the way.

 1. `CLAUDE.md` — the orchestrator framing.
 2. `docs/DESIGN.md` — for the invariants the doc strings must reflect.
-3. The most recent entries in `docs/JOURNAL.md` — to know which crates
+3. The most recent entries linked from `docs/journals/INDEX.md` — to know which crates
   recently shifted (those are the ones likeliest to have stale rustdoc).
 4. The crate(s) the assignment names — read every `pub` item before you
   write a single doc line. You can't summarise an item you haven't read.
@@ -77,7 +77,7 @@ EVERY pub ITEM YOU TOUCH MUST EITHER BE DOCUMENTED OR THE WARNING CLEARED.
  the crate already runs doctests; if you write a code block, mark it
  ` ```ignore ` or ` ```no_run ` so it doesn't have to compile against
  the workspace.
- **Cross-repo references** (DESIGN.md, JOURNAL.md, the `ail` CLI
+- **Cross-repo references** (DESIGN.md, journals, the `ail` CLI
  subcommands) are fine as plain prose mentions — those are NOT in
  rustdoc, so don't try to link them.

@@ -87,7 +87,7 @@ EVERY pub ITEM YOU TOUCH MUST EITHER BE DOCUMENTED OR THE WARNING CLEARED.
  confusing it needs renaming, raise it in your report instead of changing
  it.
 - No new `pub` exports. Visibility stays as-is.
- No edits in `docs/`. The orchestrator owns DESIGN.md and JOURNAL.md.
+- No edits in `docs/`. The orchestrator owns DESIGN.md and the journal files.
 - Don't paper over broken behaviour with prose — if doc-writing surfaces
  a real bug (a function whose doc you cannot honestly write because it
  doesn't actually do what it claims), stop and report it.
@@ -138,7 +138,7 @@ At most 200 words, structured:

 - About to rename a `pub` item
 - About to add or remove a `pub` export
- About to edit `docs/DESIGN.md` or `docs/JOURNAL.md`
+- About to edit `docs/DESIGN.md` or any file under `docs/journals/` / `docs/journal-archive.md`
 - About to write a doc comment that contradicts the function body
 - About to skip the `cargo doc --no-deps` re-run after edits
 - About to report `DONE` while one of the three verification commands is
@@ -56,7 +56,7 @@ exist and be approved before any plan or code work begins.
 ### Step 1 — Explore project context

 Before asking any clarifying questions:
- Read the latest entries in `docs/JOURNAL.md` (most recent
+- Read the latest entries linked from `docs/journals/INDEX.md` (most recent
  milestones, current state).
 - Skim `docs/DESIGN.md` for the invariants the new milestone
  might touch.
@@ -24,7 +24,7 @@ genuinely captures the symptom, not the post-fix code path.

 1. `CLAUDE.md` — agent role boundaries.
 2. `docs/DESIGN.md` — invariants the bug may have crossed.
-3. `docs/JOURNAL.md` — most recent entries; the last iteration may have
+3. `docs/journals/INDEX.md` + the latest referenced file — the last iteration may have
   introduced the bug.

 The four-phase process below is the single source of truth — the
@@ -152,7 +152,7 @@ At most 250 words, structured:
 - The fix. That's `implement` mini-mode's job.
 - Sweeping refactors layered on top of a bug fix.
 - Changes to the test once it's RED — the test is the contract.
- DESIGN.md / JOURNAL.md edits.
+- DESIGN.md / journal edits.
 - Verdicts like "this whole subsystem is broken". Phase 4.5 surfaces the
  architecture question; the orchestrator decides the verdict.

@@ -41,7 +41,7 @@ Read in this order, before picking examples:
 2. `docs/DESIGN.md` — the canonical specification. This is the only
   description of "what AILang is" you may consult. Read in full;
   skim is not enough on the milestone's axis.
-3. `docs/JOURNAL.md` (most recent ~10 entries) — what shipped, what
+3. `docs/journals/INDEX.md` and the latest ~5 referenced files — what shipped, what
   was deferred, what was ratified.
 4. `docs/specs/<milestone>.md` if one exists — the contract this
   milestone signed up for.
@@ -59,7 +59,7 @@ Read in this order, before picking examples:
 | `axis_hints` | bullet list, one per axis to probe (typeclasses, prose, RC modes, …) |
 | `commit_range` | `<prev-milestone-close>..HEAD` for `git log`-driven scope only |

-If `axis_hints` is empty, infer from JOURNAL tail and the milestone
+If `axis_hints` is empty, infer from the latest per-iter journals and the milestone
 spec; if both are also empty, return `NEEDS_CONTEXT`.

 ## The Iron Law
@@ -92,7 +92,7 @@ Each phase completes before the next starts.
 ### Phase 1 — Read the spec, pick the examples

 1. Read the standing list. Identify the milestone's axes from
-   JOURNAL + spec + `axis_hints`.
+   latest per-iter journals + spec + `axis_hints`.
 2. For each axis, propose one real-world programming task that an
   ordinary LLM-author might be asked to write. Examples that work:
   FizzBuzz with a small twist, Newton's method on `Float`, run-
@@ -216,11 +216,11 @@ End every report with exactly one of:
  (debug for bugs, plan/brainstorm for friction/spec_gap).
 - `DONE_WITH_CONCERNS` — examples and spec committed, but during the
  run you noticed something orthogonal worth flagging (e.g. a
-  separate JOURNAL entry's claim is contradicted by what you saw,
+  separate per-iter journal entry's claim is contradicted by what you saw,
  but only as a side observation).
- `NEEDS_CONTEXT` — `axis_hints` empty AND JOURNAL/spec do not
+- `NEEDS_CONTEXT` — `axis_hints` empty AND per-iter journals/spec do not
  disambiguate. Or: the milestone's scope is too vague to pick
-  examples (rare; usually means the JOURNAL entry was thin).
+  examples (rare; usually means the per-iter journal entry was thin).
 - `BLOCKED` — `ail` CLI itself broken (build failure, segfault before
  any example, missing subcommand the carrier assumed). Or: the
  milestone's surface is not yet emit-able (work-in-progress shipped
@@ -248,7 +248,7 @@ it in the report. The orchestrator reads the file.
 - Bug fixes. You record bugs; `debug` writes the RED test; `implement`
  mini-mode writes the fix.
 - Refactors of `examples/` that touch existing fixtures.
- Edits to `docs/DESIGN.md` or `docs/JOURNAL.md`. Spec gaps are
+- Edits to `docs/DESIGN.md` or any journal file. Spec gaps are
  reported, not patched.
 - Edits to anything under `crates/`, `runtime/`, `bench/scripts/`.
 - A `friction` finding without a 1-line recommendation. Every finding
@@ -29,7 +29,7 @@ of every dispatch:
 1. `CLAUDE.md` — orchestrator framing, agent role boundaries.
 2. `docs/DESIGN.md` — the canonical specification. Architectural decisions
   here are binding.
-3. `docs/JOURNAL.md` — the most recent milestone-relevant entries. The latest
+3. `docs/journals/INDEX.md` + the latest 1–3 milestone-relevant per-iter files. The latest
   entry is the current state of the project.

 You do **not** open `docs/plans/<iteration>.md` or `docs/specs/<milestone>.md`
@@ -99,7 +99,7 @@ the test.

 ## The Process

-1. Read the standing list (CLAUDE.md, DESIGN.md, JOURNAL.md tail).
+1. Read the standing list (CLAUDE.md, DESIGN.md, latest per-iter journals).
 2. Read the carrier in full. Confirm `task_text` is concrete (no TBD, no
   "similar to Task N"). If it contains placeholders, return `BLOCKED` with
   "plan placeholder" — the plan failed self-review and must be fixed
@@ -24,7 +24,7 @@ invariant in the doc comment, and you stop.
 ## Standing reading list

 1. `CLAUDE.md`, `docs/DESIGN.md` — invariants the tests must protect.
-2. `docs/JOURNAL.md` — most recent iteration entries; they tell you what
+2. `docs/journals/INDEX.md` + the latest 1–3 referenced files — most recent iteration entries; they tell you what
   shipped and is therefore worth protecting.
 3. `examples/*.ail.json` — the canonical fixture style. The schema is
   `ailang/v0`; existing examples are authoritative.
@@ -75,7 +75,7 @@ DETERMINISTIC: SAME INPUT, SAME OUTPUT, EVERY RUN.
   - Add the corresponding test in `crates/ail/tests/e2e.rs`.
   - Doc comment names the property.
 4. Run `cargo test --workspace`. Must be green.
-5. Commit per existing JOURNAL style (`iter <X>.<n>: e2e for <feature>`).
+5. Commit per existing journal style (`iter <X>.<n>: e2e for <feature>`).
 6. Report.

 ## Status protocol