workflow: replace per-iter journal system with git log + BLOCKED.md

The per-iter journal under docs/journals/ duplicated the iter commit
body's substance and accumulated as Verlauf-Doku with no Future-Use.
Sweep across all live control documents: CLAUDE.md, the 7 SKILL.md
files, the 11 agent files, design/INDEX.md and the contracts/models
that referenced journals, docs/roadmap.md, and the handful of source
comments + tests that pointed at journal files for rationale.

Mechanism changes:
- Standing-reading-lists in every agent now read `git log -N --format=full`
  for recent project state, never per-iter journal files. The architect
  reads `git log <prev-milestone-close>..HEAD --format=full` for audit
  scope.
- implement-orchestrator no longer writes a journal file. DONE outcomes
  emit just code + stats; the end-report is the per-task summary the
  Boss uses to write the commit body. PARTIAL/BLOCKED outcomes emit
  BLOCKED.md at the repo root — uncommitted by convention, Boss removes
  on repair or discard. New iron-law line + four-rationalisation row
  + red-flag bullet codify it.
- audit ratify mechanic: --update-baseline is now paired with an explicit
  ratify paragraph in the audit-close commit body, not a separate
  JOURNAL ratify entry.
- design/contracts/honesty-rule.md: "history and rationale lives in
  docs/journals/" → "lives in git log (iter and audit commit bodies)".
  Pinned phrase preserved verbatim.
- CLAUDE.md "Roles of …" section reframed: design/, git log,
  journal-archive.md (content-frozen), roadmap.md, specs/, plans/.
  No docs/journals/ slot anymore.
- roadmap.md context-lines that pointed at per-iter journals are
  dropped where the spec/commit already carries the rationale, or
  rephrased to "shipped in the <iter> iter commit" / "docs/journal-
  archive.md (<date> entry)" for pre-2026-05-11 references.

What stays (this commit):
- docs/journals/ directory and contents are NOT touched. Removing the
  contents is a separate follow-up.
- docs/journals/2026-05-19-design-decision-records.md still has live
  readers (docs_honesty_pin.rs Z 108 + parse.rs + duplicate_ctor_pin.rs
  + 3 roadmap mentions) — also follow-up.
- docs/journal-archive.md still exists; its self-pointer header has
  been updated to drop the "see docs/journals/INDEX.md" mention.

Workspace builds, full test suite green.
This commit is contained in:
2026-05-20 11:21:37 +02:00
parent 55ad0fa37f
commit 8e586f493f
28 changed files with 362 additions and 373 deletions
+35 -34
View File
@@ -43,7 +43,7 @@ it measurably improves correctness or removes redundancy.
| `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 |
| `design/` | The canonical contract ledger — `design/INDEX.md` (sole addressable spine: a typed Contracts + Models table), `design/contracts/` (prose-authoritative test-linked invariants), `design/models/` (onboarding whitepapers) |
| `docs/` | Specs and decisions log — `docs/journals/` (per-iter journals + `INDEX.md`; incl. the migrated design decision-records), `docs/journal-archive.md` (pre-2026-05-11 history), `docs/specs/` (per-milestone design specs), `docs/plans/` (per-iteration plans), `PROSE_ROUNDTRIP.md` |
| `docs/` | Specs and roadmap — `docs/specs/` (per-milestone design specs), `docs/plans/` (per-iteration plans), `docs/roadmap.md` (forward queue), `docs/journal-archive.md` (pre-2026-05-11 history, content-frozen), `PROSE_ROUNDTRIP.md`. Per-iter history lives in `git log`. |
| `skills/` | Project-local skill definitions and their agents. See `skills/README.md` for the skill table, agent roster, and discovery layout. |
## Skill system
@@ -75,8 +75,8 @@ 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/journals/` and the
`design/` ledger are my work product.
invariants, commit bodies, and the contents of the `design/`
ledger are my work product.
- **Implement, refactor, write tests, diagnose bugs** — by default,
delegated. `ailang-implementer` for code changes that follow a
fixed design, `ailang-tester` for E2E coverage, `ailang-debugger`
@@ -97,12 +97,14 @@ Two project-wide rules govern who touches git history and how:
brainstormer, planner, debugger, fieldtester, docwriter,
architect, bencher — runs `git commit`. Every agent writes its
output (spec, plan, code, tests, fixtures, rustdoc edits, RED
tests, journal files, stats, updated baselines) into the working
tree as unstaged changes. I inspect the result with
`git status` / `git diff`, decide commit shape (often one
cohesive iter-level commit; sometimes a few logical commits when
the changes genuinely cover separate concerns), and commit.
Per-task or per-phase commits are not a goal in themselves.
tests, stats, updated baselines; `BLOCKED.md` on PARTIAL/BLOCKED
iter outcomes) into the working tree as unstaged changes. I
inspect the result with `git status` / `git diff`, decide commit
shape (often one cohesive iter-level commit; sometimes a few
logical commits when the changes genuinely cover separate
concerns), and commit. Per-task or per-phase commits are not a
goal in themselves. `BLOCKED.md` is never committed by
convention — Boss removes it on repair or discard.
- **main HEAD is sacrosanct.** Nobody (including me) runs
`git reset` or `git revert` on main. main moves forward only via
my commits. The consequence is the working-tree-as-quarantine
@@ -114,8 +116,7 @@ Two project-wide rules govern who touches git history and how:
These rules supersede earlier mechanics that involved per-iter
branches and per-task agent commits. See `skills/README.md`
"Conventions" for the same rules in skill-system form, and the
2026-05-11 journal for the failure mode that motivated the change.
"Conventions" for the same rules in skill-system form.
### Authority over `skills/` and the agent roster
@@ -145,8 +146,8 @@ not as immutable scripture.
use approach X or Y?") — that is orchestrator work.
- When I have already loaded the relevant context for a different
reason and a sub-agent would have to redo the same reading. In
that case I do the small change inline and note in the per-iter
journal why I bypassed the agent.
that case I do the small change inline and note in the commit
body why I bypassed the agent.
### Design rationale ≠ implementation effort
@@ -167,8 +168,7 @@ equally, and even then it should be named as a tiebreaker, not as
the primary reason. The 18a "Type::Fn metadata vs. Type variant"
call is the canonical anti-example: the right reason was semantic
locality (modes belong to fn-parameter positions, not to types in
general), and I retroactively had to add it. JOURNAL entries from
2026-05-08 record the lesson.
general), and I retroactively had to add it.
### Feature acceptance: LLM utility
@@ -193,11 +193,12 @@ Work clusters into **milestones**, each subdivided into
→ fieldtest`), skipping rules, and bench-exit-code gating live in
`skills/README.md` and the per-skill `SKILL.md` files.
Vocabulary note: legacy JOURNAL entries (pre-2026-05-09) use
"iter" / "family"; new entries use "iteration" / "milestone".
Existing entries are not retroactively renamed.
Vocabulary note: legacy entries in `docs/journal-archive.md`
(pre-2026-05-09) use "iter" / "family"; current vocabulary is
"iteration" / "milestone". Existing archive entries are not
retroactively renamed.
## Roles of the `design/` ledger, `docs/journals/`, `docs/journal-archive.md`, `docs/roadmap.md`, `docs/specs/`, `docs/plans/`
## Roles of the `design/` ledger, `git log`, `docs/journal-archive.md`, `docs/roadmap.md`, `docs/specs/`, `docs/plans/`
- **The `design/` ledger** is the canonical specification. It
describes what AILang *is*: schema, semantics, invariants, runtime
@@ -209,18 +210,17 @@ Existing entries are not retroactively renamed.
feature requires changes to a contract, those changes are part of
the same iteration. The `design/` ledger is also the artefact
`ailang-architect` checks the code against during drift review.
The current-state-mirror discipline is unchanged, just re-homed:
a contract describes only the actual present state; forward intent
goes to `docs/roadmap.md`, history and rationale to
`docs/journals/` (see `design/contracts/honesty-rule.md`).
A contract describes only the actual present state; forward intent
goes to `docs/roadmap.md`, history and rationale to `git log`
(see `design/contracts/honesty-rule.md`).
- **`docs/journals/<YYYY-MM-DD>-iter-<id>.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 the `design/` ledger. Append-only
per file; new files are appended via `docs/journals/INDEX.md`.
`docs/journals/INDEX.md` is the chronological pointer list,
orchestrator-maintained, one line per iter.
- **`git log`** is the project history. Iter and audit commit
bodies carry the *why* — alternatives considered and rejected,
verification steps, ratify statements, lessons. The Boss writes
these bodies at commit time; they are the durable record. Read
recent state with `git log -5 --format=full`; chronological scan
with `git log --oneline -30`; per-milestone scope with
`git log <prev-milestone-close>..HEAD --format=full`.
- **`docs/journal-archive.md`** is the archived monolithic
decisions log for everything pre-2026-05-11. Content-frozen.
@@ -231,8 +231,8 @@ Existing entries are not retroactively renamed.
orchestrator owns this file and is responsible for keeping it
current: adding new entries, reprioritising, removing items
that are done or dropped. Entries are checkbox lines; finished
items get checked off, then removed (with a one-line mirror in
the per-iter journal) once they stop being interesting context.
items get checked off, then removed once they stop being
interesting context.
- **`docs/specs/<milestone>.md`** (since 2026-05-09): per-milestone
design spec produced by `skills/brainstorm`. Hard-gate before any
@@ -243,5 +243,6 @@ Existing entries are not retroactively renamed.
by `skills/implement`.
Together these answer three questions: "what is the language right
now?" (the `design/` ledger), "how did we get here?" (per-iter
journals, specs, plans), and "what's next?" (roadmap).
now?" (the `design/` ledger), "how did we get here?" (`git log`,
plus `docs/journal-archive.md` for pre-2026-05-11 context), and
"what's next?" (roadmap).