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.
The 3020-line docs/DESIGN.md is replaced by the design/ ledger:
design/INDEX.md (sole addressable spine, typed Contracts+Models tables,
polymorphic links — prose file OR authoritative source //!), 14
design/contracts/*.md test-linked invariants + 3 source-link-only
contracts (mangling/env-construction/qualified-xref, no prose file —
code is SoT), 5 design/models/*.md whitepapers, and
docs/journals/2026-05-19-design-decision-records.md (the
relitigation-guard archive — every why/rejected/does-not-do/rollback/
empirical ### moved out at ###-granularity). Clean cut: git rm
docs/DESIGN.md, no stub.
RED-first crates/ailang-core/tests/design_index_pin.rs — the 4-clause
anti-regrowth spine (DESIGN.md-gone / every-INDEX-link-resolves /
every-contract-names-a-resolvable-ratifier /
contracts-carry-no-decision-record-prose) — demonstrably RED before,
GREEN after. Build-atomic by task ordering: design_schema_drift.rs's
include_str! (the only compile-time consumer) retargeted to
design/contracts/data-model.md BEFORE the deletion; its
## Data model/## Pipeline slicer dropped (a simplification the split
enables). 2 NoInstance diagnostics + 2 lockstep E2Es retargeted to
design/contracts/{float-semantics,typeclasses}.md. ~12 agent reading
lists + 5 SKILL bodies + CLAUDE.md + skills/README.md + ~25
code/C/.ail/spec comment xrefs retargeted; OQ7 dangling 'Iter 13b'
cite deleted (no forward target — a pointer would be fiction).
honesty-rule.md rewritten so the rule names the new home
(rationale->journals), resolving the recon-found internal
contradiction; the two docs_honesty_pin.rs:70,72 pinned phrases kept
verbatim+contiguous.
Boss-verified independently: cargo test --workspace 646 passed /
0 failed; design_index_pin 4/4; acceptance grep CLEAN of live
DESIGN.md refs (residuals = only the spec-mandated clause-4
deletion-enforcer). 2 DONE_WITH_CONCERNS routed to the mandatory
milestone-close audit: (a) str-abi.md:23 '(iter str-concat,
2026-05-13)' provenance stamp trips advisory architect_sweeps Sweep-1
— Boss-confirmed byte-identical to DESIGN.md@deeffb1:2062-2065, a
faithfully-migrated PRE-EXISTING anchor (regexes verbatim, only path
retargeted), NOT split-introduced — RATIFY-or-tidy at audit; (b) a
now stale-direction intra-prose 'see Str ABI below' cross-ref in
float-semantics.md — audit-adjudication candidate. Plan defect noted:
Task 9 Step 4's verbatim acceptance grep used a ^./ anchor not
matching the system's grep -rIn output; substance re-verified CLEAN.
Spec grounding-check PASS x2. Journals INDEX + decision-records
pointer appended (Boss-only).
Two project-wide rules are now explicit across every skill:
1. Only the Boss commits. No skill agent (implementer,
brainstormer, planner, debugger, fieldtester, docwriter,
architect, bencher) runs `git commit`. Agents write their
artefacts to the working tree as unstaged changes; the Boss
inspects, decides commit shape, and commits.
2. main HEAD is sacrosanct. No actor runs `git reset` or
`git revert` on main. Bad work stays in the working tree
where it is still discardable via `git checkout -- <paths>`.
Implement loses the `iter/<iter_id>` branch mechanic entirely;
Phase 0 of the orchestrator-agent now does a clean-tree check
and refuses to start on a dirty tree. Per-task agent commits
are removed everywhere; reviewers operate against
`git diff HEAD` instead of `pre_task_sha..head_sha`.
Motivation: 2026-05-11 iter 23.4 stranded prep2/prep3 commits on
an iter-branch that never integrated to main, then a corrected
spec falsely claimed those commits had shipped. Branch-per-iter
+ manual-Boss-merge + iter-stacking made the strand structurally
possible. See docs/journals/2026-05-11-iter-disc.1.md for the
full per-task notes and motivation.
The four-phase debug process and the five-phase fieldtest process
each lived twice — once in SKILL.md (orchestrator-facing) and once
in the dispatched agent's file (subagent-facing). The orchestrator
does not execute these phases; the subagent does. Duplicating them
in SKILL.md just bloated the orchestrator's main context with bytes
that only the subagent ever needs.
SKILL.md now carries only what the orchestrator must consult at
dispatch time: trigger gating, Iron Law as headline, the carrier
contract, the produced handoff, and cross-references. Iron Law in
operational form, full process, Common Rationalisations, Red Flags,
and (for fieldtest) the spec template now live solely in the agent
file. Net −160 LOC across the skills tree.
CLAUDE.md pointer for 'Bug fixes — TDD, always' updated to reflect
that the substantive discipline lives in the agent file, not the
skill file.
All six existing agents (implementer, tester, architect, bencher,
docwriter, debugger) restructured into the same superpowers-derived
layout the SKILL.md files use: Iron Law, Carrier contract, Standing
reading list, Status protocol (DONE / DONE_WITH_CONCERNS /
NEEDS_CONTEXT / BLOCKED), Common Rationalisations, Red Flags. Agents
now know about docs/specs/<milestone>.md and docs/plans/<iteration>.md
but do not open them directly — context curation lives at the skill
level (controller hands the agent task_text, hypothesis, etc.).
Implementer carries TDD as an independent discipline layer, mirroring
the superpowers split between subagent-driven-development (outer loop)
and test-driven-development (inner loop). RED-first applies even when
a plan task forgot to script the failing test.
Debugger scope corrected: RED-first only, hands GREEN to implement
mini-mode. Previously the agent self-applied the fix, which
contradicted skills/debug/SKILL.md Phase 4. The skill is the source
of truth; the agent now matches it.
Two new named reviewer agents:
- ailang-spec-reviewer: did the diff match the task text?
- ailang-quality-reviewer: is the diff well-built? (only after spec
is compliant)
Both replace the ad-hoc general-purpose dispatch in skills/implement
Step 2.3 and 2.4. With named agents, AILang quality conventions are
amortised across dispatches instead of being re-stated inline per
prompt.
skills/implement/SKILL.md updated to dispatch the new reviewers.
skills/README.md agent roster expanded; conventions clarified to
state that agents do not open plan/spec files directly.
The skills are functionally complete and standalone — superpowers
references were attribution-only. Removed so a reader without the
superpowers plugin loaded isn't sent chasing dead links.
Plus: .claude/skills/<name> symlinks so Claude Code's Skill tool can
invoke them by name (analogous to the existing .claude/agents/
symlinks). Discovery section in skills/README.md updated to cover
both symlink sets.
ailang-implementer/-tester -> skills/implement/agents/
ailang-architect/-bencher/-docwriter -> skills/audit/agents/
ailang-debugger -> skills/debug/agents/
agents/ now contains only README.md (rewritten in next commit as
roster of skill-bound agents).
Brummel