From 4017e514f7ac91e79fd85af3c1d580e7e497a40e Mon Sep 17 00:00:00 2001 From: Brummel Date: Mon, 11 May 2026 11:24:58 +0200 Subject: [PATCH] iter or.1.3: repoint skill + agent reading lists to docs/journals/ --- skills/README.md | 14 +++++++------- skills/audit/SKILL.md | 2 +- skills/audit/agents/ailang-architect.md | 6 +++--- skills/audit/agents/ailang-bencher.md | 8 ++++---- skills/audit/agents/ailang-docwriter.md | 8 ++++---- skills/brainstorm/SKILL.md | 2 +- skills/debug/agents/ailang-debugger.md | 4 ++-- skills/fieldtest/agents/ailang-fieldtester.md | 14 +++++++------- skills/implement/agents/ailang-implementer.md | 4 ++-- skills/implement/agents/ailang-tester.md | 4 ++-- 10 files changed, 33 insertions(+), 33 deletions(-) diff --git a/skills/README.md b/skills/README.md index 54ed6d4..49fd571 100644 --- a/skills/README.md +++ b/skills/README.md @@ -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/.md` | Hard-gate before plan | | [`planner`](planner/SKILL.md) | New iteration within an open milestone | `docs/plans/.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/-fieldtest-.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. diff --git a/skills/audit/SKILL.md b/skills/audit/SKILL.md index ba023f7..20da919 100644 --- a/skills/audit/SKILL.md +++ b/skills/audit/SKILL.md @@ -46,7 +46,7 @@ Dispatch `ailang-architect` with the milestone scope (commit range from the previous milestone-close to `HEAD`): ``` -For milestone : read DESIGN.md, JOURNAL.md, the latest milestone +For milestone : read DESIGN.md, `docs/journals/INDEX.md` and the latest 1–3 referenced files, the latest milestone entries; git log/diff over ..HEAD; report drift. ``` diff --git a/skills/audit/agents/ailang-architect.md b/skills/audit/agents/ailang-architect.md index 59798cd..8c8451c 100644 --- a/skills/audit/agents/ailang-architect.md +++ b/skills/audit/agents/ailang-architect.md @@ -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/.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 ..HEAD` for the factual diff. diff --git a/skills/audit/agents/ailang-bencher.md b/skills/audit/agents/ailang-bencher.md index 5520063..2b613e0 100644 --- a/skills/audit/agents/ailang-bencher.md +++ b/skills/audit/agents/ailang-bencher.md @@ -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. diff --git a/skills/audit/agents/ailang-docwriter.md b/skills/audit/agents/ailang-docwriter.md index c86b32c..6ec7d2d 100644 --- a/skills/audit/agents/ailang-docwriter.md +++ b/skills/audit/agents/ailang-docwriter.md @@ -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 diff --git a/skills/brainstorm/SKILL.md b/skills/brainstorm/SKILL.md index 36ab6cb..4b77703 100644 --- a/skills/brainstorm/SKILL.md +++ b/skills/brainstorm/SKILL.md @@ -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. diff --git a/skills/debug/agents/ailang-debugger.md b/skills/debug/agents/ailang-debugger.md index bd9aa94..aa89f34 100644 --- a/skills/debug/agents/ailang-debugger.md +++ b/skills/debug/agents/ailang-debugger.md @@ -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. diff --git a/skills/fieldtest/agents/ailang-fieldtester.md b/skills/fieldtest/agents/ailang-fieldtester.md index 4b54d23..11b5353 100644 --- a/skills/fieldtest/agents/ailang-fieldtester.md +++ b/skills/fieldtest/agents/ailang-fieldtester.md @@ -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/.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` | `..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 diff --git a/skills/implement/agents/ailang-implementer.md b/skills/implement/agents/ailang-implementer.md index a7b264b..367ced7 100644 --- a/skills/implement/agents/ailang-implementer.md +++ b/skills/implement/agents/ailang-implementer.md @@ -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/.md` or `docs/specs/.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 diff --git a/skills/implement/agents/ailang-tester.md b/skills/implement/agents/ailang-tester.md index 77ac84d..fb8b7b8 100644 --- a/skills/implement/agents/ailang-tester.md +++ b/skills/implement/agents/ailang-tester.md @@ -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 .: e2e for `). +5. Commit per existing journal style (`iter .: e2e for `). 6. Report. ## Status protocol