Pure crate rename, zero behavioural change. ailang-kernel-stub becomes
the ailang-kernel family-crate: a re-export hub (src/lib.rs) plus one
submodule per kernel-tier module (today only kernel_stub:
src/kernel_stub/{mod.rs, source.ail}). raw-buf.3 plugs raw_buf in as a
sibling submodule; this iter only builds the home.
Task 1 (atomic — the rename breaks the build until every site is
threaded):
- git mv crates/ailang-kernel-stub → crates/ailang-kernel.
- Carved the STUB_AIL Form-A body verbatim (byte-identical, verified
via diff against HEAD's raw string) into src/kernel_stub/source.ail,
loaded by mod.rs via include_str!. The answer (intrinsic) fn is
byte-preserved — its INTERCEPTS bijection partner stays pinned.
- lib.rs is now the hub: `pub use kernel_stub::SOURCE as STUB_AIL;`.
The public symbol STUB_AIL is preserved, so ailang-surface and the
bijection test bind to it unchanged.
- 8 compile sites threaded across 6 files: Cargo package name,
workspace member + dep-alias, ailang-surface dep, loader.rs
use-paths (ailang_kernel_stub → ailang_kernel). Cargo.lock
auto-regenerated.
Task 2 (doc/ledger honesty, no build impact):
- design/INDEX.md, CLAUDE.md code-layout row + lockstep-pair row,
design/models/0007 ×2 — crate-path strings updated to the new
ailang-kernel/src/kernel_stub path.
- Scope note: the spec's raw-buf.2 Components row named only
design/INDEX.md + the CLAUDE.md code-layout row. plan-recon found two
more present-tense crate-path refs (CLAUDE.md:312 lockstep row,
model 0007:8/235). Folded them in per the honesty-rule — a rename
that leaves stale present-state paths is an incomplete rename.
Path-only; the retirement narrative stays for raw-buf.4.
The AILang module name kernel_stub (the Form-A string + parse_kernel_stub
fn) is deliberately unchanged — only the crate identifier moved.
Verification (orchestrator, this session): cargo build --workspace
clean; cargo test --workspace 669 passed / 0 failed / 2 ignored
(baseline held exactly — no test added/removed). Carve byte-identity
confirmed by diff; no stale ailang-kernel-stub / ailang_kernel_stub
refs remain in-tree (git grep, excl. history + lockfile). The four
rename-invisible ratifiers (kernel_stub_module_round_trips,
intercepts_bijection_with_intrinsic_markers, .ll snapshots,
workspace_pin) all green via the preserved re-export.
Milestone close for intrinsic-bodies (.1 mechanism 52ff873 + .2
migration/lock caa3618). Architect drift review over c42034b^..caa3618
plus the regression scripts. Both gates assessed; four drift items
resolved (3 fixed inline here, 1 filed to backlog).
Regression: both scripts exit 0.
bench/check.py → 34 metrics, 0 regressed, 2 improved beyond
tolerance (bench_hof_pipeline.bump_s -10.76%,
bench_list_sum_explicit.bump_s -12.27%), 32 stable.
bench/compile_check.py → 24 metrics, 0 regressed, 24 stable.
The milestone is behaviour-preserving; the two throughput improvements
are noise within the bench's run-to-run band, not a milestone effect.
Drift items (architect):
1. [FIXED] examples/prelude.ail — the 13 migrated defs' doc strings
still said "Body is placeholder for round-trip stability" and named
`try_emit_primitive_instance_body` (the pre-raw-buf.1 dispatch fn).
Post-migration the body IS an honest (intrinsic) marker, not a
placeholder, and dispatch is `intercepts::lookup`. The docs lied
about the very artefact the milestone exists to de-lie — an active
honesty-rule infraction on main. Rewritten to present-tense
"compiler-supplied (intrinsic) body; codegen emits <IR> via the
intercept registry" across all 13 (7 Eq/Ord instance methods +
6 float_* fns).
2. [FIXED] design/models/0007-kernel-extensions.md — claimed the
`try_emit_primitive_instance_body` hardcoded list is "not yet
migrated into a plugin registry ... deferred to the Series
milestone". Stale since raw-buf.1 (the registry shipped) and
intrinsic-bodies (the (intrinsic) marker + bijection pin). Rewritten
to the present state: the registry exists, (intrinsic) declares
membership, the bijection pin locks marker<->entry, and the
optimisation-only class is named.
3. [FIXED] CLAUDE.md "Lockstep-invariant pairs" — added the third pair:
INTERCEPTS entries <-> (intrinsic) markers, guarded by
intercepts_bijection_with_intrinsic_markers, with the
optimisation-only allowlist carve-out. Same class as the two existing
tabled pairs; ships silently broken if one side moves without the
other.
4. [BACKLOG #41, label idea] INTERCEPTS conflates two concepts —
intrinsic-backed (compiler-supplied body) vs optimisation-of-a-
real-body (the 5 *__Int icmp family). The .2 bijection pin contains
it with a hardcoded OPTIMISATION_ONLY allowlist + a stale-allowlist
guard; a structural split (an Intercept kind field) is the
forward direction but is its own focused change, out of scope here.
What holds (architect confirmed): data-model contract matches the
shipped Term::Intrinsic (design_schema_drift gates it); no INDEX row
needed (data-model addition, not a new contract); both existing
lockstep pairs untouched (answer lowers via the ordinary qualified-fn
path, no new lower_app arm; no Pattern::Lit reject); 0007-honesty-rule
correctly needed no edit (general rule, never named the dummies).
RATIFY — baseline move: the prelude module hash pin
(crates/ailang-surface/tests/prelude_module_hash_pin.rs) moves
2ea61ef21ebc1913 -> b1373a2c69e70a3f. Cause: this tidy's 13 doc-string
rewrites (item 1). doc is part of the canonical JSON, so the module
hash shifts; behaviour is unchanged. The 6 mono eq/compare def-hashes
do NOT move (synthesise_mono_fn sets doc: None, so instance-method docs
never reach the synthesised symbol). Full workspace test green
post-rebaseline.
Milestone intrinsic-bodies is closed. It unblocks the raw-buf.2 redo
(the polymorphic kernel-tier fns RawBuf needs now have an honest body
form). raw-buf (#7) remains parked; resuming it is a fresh decision.
Audit Step 3 fix path. Architect drift review at milestone close
surfaced 8 items (3 high, 4 medium, 1 low). Resolved 7 inline as
mechanical text rewrites + 2 source-rustdoc cleanups; the 1 low
(cycle-avoidance pattern documentation in design ledger) is
deferred — architect flagged it "Note, do not push" because the
pattern is implementation mechanism, not language semantics,
and is already documented in the load-bearing place
(`crates/ailang-kernel-stub/src/lib.rs //!`).
CLAUDE.md (2 sites):
- Lead paragraph: "this file carries [...] in-tree skill system"
→ reframe to "this file carries [...] orchestrator discipline
(the skill system itself lives in the ~/dev/skills/ plugin
and is wired in via .claude/dev-cycle-profile.yml)".
- Code-layout table: new row for `crates/ailang-kernel-stub/`
documenting the zero-dep leaf design, the parse-hop location
in `ailang-surface`, and the planned retirement at raw-buf
landing.
design/INDEX.md (2 sites):
- Project-ecosystem "Skills" bullet: in-tree `skills/` path +
`skills/README.md` reference → `~/dev/skills/` plugin +
in-tree per-project profile. Also added `docwriter` and
`boss` to the enumerated skill list (8 in total) for
completeness.
- kernel-extensions row 111: added stub-retirement plan to the
annotation so the spine names the future state, not just the
in-tree reader of `lib.rs //!`.
design/models/0007-kernel-extensions.md (3 sites):
- § "Migration policy" subsection: 4 bullets transitioned
forward → present-state per honesty-rule. References to
`loader.rs:98-108` / `workspace.rs:308-311, 467, 2655` as
if hardcoded paths still existed → described as past state
that has been replaced by the generic flag-filter. Codegen-
intercept-migration bullet kept forward-looking because the
`try_emit_primitive_instance_body` migration is *actually*
still pending (deferred to Series milestone per spec
§ Out-of-scope).
- § "Feature-acceptance argument": "the bounded push-only
mutation surface — gated by the `Series` effect" — internal
contradiction with three earlier statements that "Series
carries no separate algebraic effect; mutation is mode-
tracked, not effect-tracked". Re-framed to "gated by
uniqueness mode-tracking on the owned `Series` value (not by
an algebraic effect; see §"Coexistence" below)".
- § "Coexistence" "Algebraic effects" bullet: "Reused
unchanged. The `Series` effect is a new name" — same
contradiction. Re-framed to "Not extended by Series.
Mutation discipline lives in the uniqueness/mode system; the
algebraic-effects set is unchanged".
Source rustdoc (2 sites):
- `crates/ailang-core/tests/design_index_pin.rs:117` comment
"skills/**/SKILL.md" → "any in-tree project-discipline
document (e.g. CLAUDE.md)" — the allowlist comment now
matches what the test actually does (no allowlist enforced
in code; any existing path passes).
- `crates/ailang-core/tests/design_schema_drift.rs:419`
rustdoc: "RED until `skills/implement` mini-mode adds it"
→ "RED until the `implement` skill (mini-mode dispatch)
adds it" — same skill, post-plugin-migration framing.
Architect items not addressed in this tidy:
- 0007 § "The plugin contract (consolidated)" forward-intent
reference to `try_emit_primitive_instance_body` migration —
architect flagged as edge-case-acceptable per the explicit
STATUS carve-out (the migration IS still pending). No
change.
- Cycle-avoidance pattern documentation (low): deferred per
architect recommendation.
Tests green (664/0); workspace_pin module-count assertion picked
up from a844de3 carries through.
The skill system migrated to a standalone plugin
(http://192.168.178.103:3000/Brummel/Skills.git, local clone at
~/dev/skills/) during this branch's earlier commits. AILang now
consumes the plugin via:
- ~/.claude/skills/<name> and ~/.claude/agents/<name> symlinks
created by ~/dev/skills/install.sh (user-level, installed
once, visible from any project).
- A project profile at .claude/dev-cycle-profile.yml declaring
paths, commands, vocabulary, naming policy, issue tracker,
notification command, and pipeline customisations.
Changes:
- ADD .claude/dev-cycle-profile.yml — AILang's profile against
the plugin's schema (paths spec_dir/plan_dir/design_ledger/
design_contracts/design_models/code_roots/bench_dir/
public_interface/fieldtest_examples; counter-prefix naming
policy; cargo build/test/doc commands; bench/check.py +
compile_check.py + cross_lang.py as regression; bench/
architect_sweeps.sh as architect sweep; milestone/iteration/
contract vocabulary; design-ledger walk + git-log standing
reading; bencher gets concrete RC/bump reading paths;
Gitea issue-tracker URL + tea list_cmd; ~/.claude/notify.sh
as notification command; the full eight-skill pipeline).
- REMOVE skills/ in-tree (21 files: 7 SKILL.md + 13 agent files
+ skills/README.md). All eight skills + all twelve agents
now live in ~/dev/skills/ as generic prose that reads slots
from the profile.
- REMOVE .claude/skills/ + .claude/agents/ symlinks (15
symlinks). User-level ~/.claude/skills/ + ~/.claude/agents/
installed by the plugin take over discovery.
- UPDATE CLAUDE.md:
* Skill-system section rewritten to point at ~/dev/skills/
+ the profile file.
* "My role: orchestrator" agent names dropped the ailang-
prefix (implementer, tester, debugger, architect).
* "Authority over `skills/`" became "Authority over the
skill plugin" — naming where plugin edits vs profile vs
CLAUDE.md edits live.
* Bug-fixes-TDD pointer updated to ~/dev/skills/debug.
* Milestone-cycle section notes the cycle/iteration
vocabulary mapping the profile carries.
* design-ledger-roles paragraph dropped the `ailang-`
prefix on the architect agent name.
* Code-layout table's `skills/` row replaced with a row
describing .claude/dev-cycle-profile.yml.
* ADDED a new "Lockstep-invariant pairs" section
enumerating AILang's two known cross-file pairings
(Pattern::Lit::* / pre_desugar_validation;
lower_app / is_static_callee) — the architect agent's
drift walk and plan-recon's cross-reference column both
consult this section per the plugin's
templates/CLAUDE.md.fragment shape.
After this commit, AILang no longer ships any skill files in
its own tree. All discipline lives in ~/dev/skills/; all
project-specific calibration lives in
.claude/dev-cycle-profile.yml plus CLAUDE.md.
With ~/dev/CLAUDE.md now carrying the cross-project dev rules
(English-in-repos, closes #N convention, label vocabulary,
milestone-as-container), the AILang CLAUDE.md no longer needs
to repeat them. Two changes:
- Add an inheritance note at the top spelling out which
user-level CLAUDE.md files this file extends, so the reader
knows what is intentionally absent (and where to find it).
- Remove the closes #N sentence from the git-log bullet in the
"Roles of …" section — that convention lives in ~/dev/CLAUDE.md
now, where it applies to every project under ~/dev/.
The orchestrator-discipline sections (only-Boss-commits, main
sacrosanct, when-not-to-delegate, design-rationale ≠ effort,
TDD-for-bugs) stay verbatim — they are project-calibrated
scaffolding, not literal duplicates of the templates fragment.
All 176 files in the four accumulating directories now use a
zero-padded 4-digit counter prefix that reflects creation order
(`NNNN-slug.md`). The counter is assigned per directory in strict
git-log creation order; ties broken alphabetically by original name.
The old `YYYY-MM-DD-` prefix on docs/specs/ and docs/plans/ files is
dropped — the date is recoverable from git log and the counter
carries the ordering.
A file's counter is stable for the life of the file: never reassigned,
never reused, never compacted. Deleted files retire their counter;
subsequent files do not fill the gap. This is the property that lets
cross-references stay literal — refs use the full filename including
the counter (`design/contracts/0007-honesty-rule.md`) so they grep
cleanly and resolve directly without a glob step.
313 cross-references updated across .md/.rs/.toml/.c/.json files
(test pins, include_str! paths, design-INDEX entries, baseline notes,
runtime C comments, inter-contract markdown links incl. bare basename
and `../models/foo.md` forms).
CLAUDE.md gets a new "File-naming convention" section spelling out
the rule and rationale. skills/brainstorm/SKILL.md and
skills/planner/SKILL.md updated so new spec/plan creation produces
counter-prefixed names from the start.
The full test suite (cargo test --workspace) passes.
Consolidate Gitea issue tracking information into CLAUDE.md and simplify
its references in skills/boss/SKILL.md. The Gitea issue tracker section
was removed from CLAUDE.md as it was redundant and the information is
now more clearly presented in skills/boss/SKILL.md.
New label for "core functionality broken" — the only category
with a hard precedence rule baked into the skill system, not a
judgement call. No issues carry it today; the label and the
skills must know about it so that the first time one is filed,
the orchestrator handles it without a one-off "what now?"
exchange.
In-tree changes:
- CLAUDE.md: Gitea-issues bullet introduces a "precedence order
matters" note and lists `BLOCKER` first.
- skills/boss/SKILL.md: Step 1 gains a dedicated `BLOCKER`
precedence paragraph — every queue read starts with
`tea issues ls --labels BLOCKER --state open`; if hit, it's
the next dispatch (RED-first via skills/debug), preempting
whatever else is in flight. The "finish the current agent
call first, don't strand a working tree mid-edit" caveat is
written in.
- skills/brainstorm/SKILL.md: Step 7.5 tea-create template
flags that BLOCKER can stack on top of the kind label.
Universal bug-fix mechanics (RED-first TDD via skills/debug)
are unchanged — BLOCKER is a precedence tag, not a new
workflow. The /boss "Direction freedom" section continues to
gate cross-milestone hops; BLOCKER is an in-milestone preempt
that doesn't bounce back to the user (it has the orchestrator's
implicit authority by definition).
Verification: cargo test --workspace 647/0/2, architect_sweeps
exit 0.
New label for observable misbehaviour distinct from
additive-feature work and clean-up tasks. The /boss pickup
order treats a bug differently from a feature (a bug typically
gets RED-first TDD via skills/debug, a feature goes through
brainstorm), so the label earns its keep.
Tagged in Gitea (6 of 24 issues):
- #7 io/print_float always-emit-.0
(surface vs runtime printer inconsistent)
- #9 ailang-plan-recon site-undercount
(tool under-counted 4× across two milestones)
- #10 design_schema_drift.rs fidelity widening
(test produces false negatives on §"Data model" gaps)
- #12 Zero-arg `(app f)` rejected at parse
(parser disagrees with the AST schema)
- #15 *.bump_s throughput baseline stale
(bench false-positive on environmental drift)
- #16 check.py RC-latency *.max_us
(bench false-positive: 3-of-3 null changes)
Borderline cases left unlabelled (diagnostic usability,
load_workspace limitation, dormant constraint-drop, advisory
Sweep-5 wart) — they aren't observable wrong behaviour, just
suboptimal.
In-tree changes:
- CLAUDE.md: Gitea-issues bullet adds `bug` to the label set
with the same description string Gitea carries.
- skills/boss/SKILL.md: Step 1 filter snippet includes `bug`.
- skills/brainstorm/SKILL.md: Step 7.5 tea-create template
--labels choice set includes `bug`.
Distribution after tagging: 3 feature + 6 bug + 5 idea + 10
unlabelled = 24 open issues. Verification: cargo test
--workspace 647/0/2, architect_sweeps exit 0.
The `milestone` label was a dead duplicate of Gitea's first-class
milestone container. Zero issues carried it (the three actual
big-chunks — Flat array, Iteration-totality, Stateful islands —
live as Gitea milestone containers, not as labelled issues).
Same pattern as `prio:p1`: a slot that never gets used because
the concept it tries to label lives somewhere else.
Label deleted in Gitea. Remaining labels: `feature`, `idea`,
`in-progress` (three, all semantic, no taxonomy noise). Big-
chunk work continues to live as Gitea milestone containers
(reached via `tea milestones ls --repo Brummel/AILang`).
In-tree changes:
- CLAUDE.md: Gitea-issues bullet describes the three-label
shape; explicit note that milestone is a Gitea container,
not a label.
- skills/boss/SKILL.md: Step 1 filter set drops `milestone`,
adds `tea milestones ls` for the container view; direction-
freedom "new milestone" trigger reworded around the
container, not the label.
- skills/brainstorm/SKILL.md: Step 7.5 tea-create template
drops `milestone` from the choice set; adds a note that
spec-needing deferred work should be filed as a Gitea
milestone container via `tea milestones create` instead.
Verification: cargo test --workspace 647/0/2, architect_sweeps
exit 0, zero residual `milestone`-as-label refs in live docs
(grep skip-listed legitimate "Gitea milestone (container)"
prose).
`todo` and `feature` were semantically near-identical ("do it, no
spec needed") and the boss-pickup decision treated both the same.
Collapsing the larger one into "no label" cuts the tag-noise on
16 of 24 issues; the 3 `feature` issues retain the label as a
deliberate "substantive but no full spec" marker against the
unlabelled bucket of mechanical follow-ups.
Label `todo` deleted in Gitea (Tea removed it from the 16
issues automatically). Remaining labels: `milestone`, `feature`,
`idea`, `in-progress`.
In-tree changes:
- CLAUDE.md: Gitea-issues bullet describes the new shape —
three semantic labels + unlabelled-default-bucket.
- skills/boss/SKILL.md: Step 1 filter-snippet and direction-
freedom commentary updated.
- skills/brainstorm/SKILL.md: Step 7.5 tea-create template
drops `todo` from the choice set and notes that omitting
`--labels` is the default-bucket path.
Verification: cargo test --workspace 647/0/2, architect_sweeps
exit 0, zero residual `todo`-as-label refs in live docs.
Labels renamed in Gitea (Tea propagated the rename to all 24
issues automatically):
- kind:milestone → milestone
- kind:feature → feature
- kind:todo → todo
- kind:idea → idea
- state:in-progress → in-progress
Five live labels total; no semantic ambiguity since milestone,
feature, todo, idea are all "class" and in-progress is the only
"state" — the prefixes were carrying zero distinguishing weight.
In-tree changes:
- CLAUDE.md: Gitea-issues bullet uses the bare label names.
- skills/boss/SKILL.md: Step 1 filter snippets + direction-
freedom new-milestone trigger drop the prefixes.
- skills/brainstorm/SKILL.md: Step 7.5 tea-issues-create
template drops the prefix on the --labels argument.
Verification: cargo test --workspace 647/0/2, architect_sweeps
exit 0, zero residual `kind:*` / `state:*` refs outside
docs/specs/ and docs/plans/.
Empirical observation after one day of running with the Gitea
backlog: P1 was permanently empty (same pattern as the old
docs/roadmap.md — anything that becomes "next-up" instantly
moves to in-progress, never sits in P1), and P3 was 6-of-8
identical to `kind:idea`. Three prio-stages were theatre; the
real distinction is "ja, irgendwann" vs "may be cut", and
`kind:idea` already carries the latter.
`prio:p1` / `prio:p2` / `prio:p3` deleted from Gitea (Tea
auto-removed them from all 24 issues). Remaining labels:
`kind:{milestone,feature,todo,idea}` + `state:in-progress`.
Issue distribution: 3 feature + 16 todo + 5 idea = 24.
In-tree changes:
- CLAUDE.md (project): Gitea-issues bullet rewritten — no
formal priority axis, "what's next" is orchestrator
judgement per session, `kind:idea` flagged as the
may-be-cut marker.
- skills/boss/SKILL.md: Step 1 rewritten — `tea issues ls
--state open` walks every open issue; selection is by
orchestrator judgement, not by reading prio:p1 first.
Cross-references "Queue:" updated to match.
- skills/brainstorm/SKILL.md: Step 7.5 no-override BLOCK
template drops `prio:p2` from the `tea issues create`
--labels argument.
Why not keep one stage (e.g. `prio:next`): no in-flight need;
a `pinned` boolean label can be added later if "next-up" ever
becomes a real distinct state. The cost of adding a label
later is one `tea labels create`; the cost of carrying dead
labels is constant cognitive load on every new issue.
Verification: cargo test --workspace 647/0/2, architect_sweeps
exit 0, zero residual prio:p* refs outside docs/specs/ and
docs/plans/ (historical, unchanged per the JOURNAL-cut
precedent).
The forward queue moves out of the in-tree markdown file and into
Gitea issues at http://192.168.178.103:3000/Brummel/AILang/issues.
Labels: kind:{milestone,feature,todo,idea} + prio:{p1,p2,p3}
+ state:in-progress. Big chunks live as Gitea milestones
(containers) with full prose in the description; smaller items are
standalone issues. Browse-and-filter scales constant against
growing item count; the previous markdown file was 1059 lines, of
which ~850 were already-closed-entry verlauf (the same failure
class the JOURNAL cut removed).
Sync-drift Code<>Tracker mitigation: Soft-convention `closes #N`
/ `refs #N` in commit bodies — Gitea auto-closes the issue on
push. Captured in user-level CLAUDE.md (~/.claude/CLAUDE.md, not
in this commit) as the durable rule; no hook enforcement.
In-repo changes:
- docs/roadmap.md deleted.
- CLAUDE.md (project): Code-layout drops roadmap; /boss gating
retargeted; Roles section rewritten with a new "Gitea issues"
bullet (URL + tea-CLI snippet) and the closes-#N trailer note.
- skills/boss/SKILL.md: 10 sites retargeted, plus Step 1 now
prescribes `tea issues ls --labels prio:p1` as the queue read.
- skills/brainstorm/SKILL.md: Step 7.5 no-override BLOCK now
files a Gitea issue via `tea issues create` instead of
appending a roadmap entry; spec deletion stays.
- skills/audit/SKILL.md + ailang-architect.md: deferral
requirement and debt-heuristic retargeted; forward-intent
belongs in the Gitea backlog.
- skills/fieldtest/SKILL.md, skills/docwriter/SKILL.md +
ailang-docwriter.md: roadmap → backlog.
- design/contracts/honesty-rule.md: forward intent lives in
the Gitea backlog (pinned phrases unchanged).
- design/INDEX.md: Docs bullet drops roadmap, adds the backlog
URL.
- crates/ailang-core/tests/docs_honesty_pin.rs: two assert
messages retargeted (assertion bodies unchanged).
- bench/architect_sweeps.sh: Sweep-4 TABU extended with
`docs/roadmap\.md` so the deleted path cannot quietly regrow
as a cross-reference in design/contracts/.
Verification:
- cargo build --workspace clean.
- cargo test --workspace: 647 passed, 0 failed, 2 ignored.
- bench/architect_sweeps.sh exit 0 (all five sweeps clean, incl.
new TABU).
- grep over the live tree (excluding docs/specs/, docs/plans/)
shows zero residual docs/roadmap.md refs.
Not touched: ~55 historical files under docs/specs/ and
docs/plans/ that mention docs/roadmap.md. Snapshot-character,
analogous to the JOURNAL-cut precedent — historical specs are
not mass-edited just because a live file was retired; their
mentions were correct at write time.
Strict application of the "Future-Use, not Verlauf" criterion to the
two remaining journal artefacts:
- `docs/journals/` (110 files): the per-iter and audit journals from
2026-05-11 onward. Pure history; no live reader after the previous
sweep. Entire directory removed.
- `docs/journals/2026-05-19-design-decision-records.md`: the one file
that had live readers (`docs_honesty_pin.rs:108`, `parse.rs:80`,
`duplicate_ctor_pin.rs:8`, three roadmap.md mentions) and was framed
as a "relitigation guard". On re-examination its three asserted
pinned phrases ("Regions were considered and rejected", the
"demands annotations *because*" rationale, the prose-render
placeholder statement) are rationale-prose, not load-bearing
invariants — the test pinned itself, not a system property. Any
Decision that still holds lives in the code, `design/contracts/`,
or `design/models/`. Removed with the rest.
- `docs/journal-archive.md` (pre-2026-05-11 history): content-frozen
long-tail history with no live reader. Removed; if anyone ever
needs the pre-cutoff rationale they can `git log --before=2026-05-11
--grep=<keyword>`.
Live-file consequences:
- `docs_honesty_pin.rs` `design_md_present_tense_anchors_present`:
the three `records.*` assertions and the `read("docs/journals/…")`
are dropped; the contract/model anchor pins remain.
- `duplicate_ctor_pin.rs`: the "why-two-overlays rationale lives in
docs/journals/…" comment is replaced with the rationale inline.
- `parse.rs`: the "form-refinement rationale lives in docs/journals/…"
comment is dropped (the rule body already states the refinement).
- `roadmap.md`: the decision-records mention in the DESIGN.md →
design/ entry's body is dropped; the journal-archive.md `context:`
pointers across ~12 closed entries are either rephrased to point
at the relevant iter/audit (no path), or simplified to a one-line
comment when the iter name alone carries the story.
- `CLAUDE.md` Roles section: the `docs/journal-archive.md` slot is
removed; vocabulary note rephrased.
- `design/INDEX.md`: the Docs bullet drops `journal-archive.md`.
- `skills/README.md` bootstrap-rationale pointer rephrased.
`docs/specs/` and `docs/plans/` (per-milestone specs and per-iteration
plans) are unaffected — they remain the structured-design artefacts
they were before this sweep.
Workspace builds, full test suite green.
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.
WhatsNew.md duplicated the Notify text into a file the only reader
(the user) does not consult. Removed the file and trimmed every
reference in the live control docs (CLAUDE.md, skills/boss,
skills/implement). The editorial rules (no internals,
telegram-pragmatic, factual) are preserved in skills/boss as
notify-text discipline. Historical specs/plans/journals are not
rewritten — they show the contemporaneous state.
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).
CLAUDE.md previously mixed universal facts (agent role boundaries,
commit discipline, design rationale, file roles, TDD-for-bugs) with
mode-specific autonomy rules (direction freedom, notifications,
WhatsNew procedure). Autonomous-by-default conflicted with the user's
intent that a fresh session should be collaborative-interactive unless
explicitly elevated.
Add `skills/boss/` containing only the three genuinely mode-specific
subsections — Direction freedom, Notifications, Done-state notifications:
WhatsNew.md. Trim CLAUDE.md from 343 to 243 lines; extend the skill-
system pointer paragraph with a one-sentence /boss gate. Universal
orchestrator discipline stays in CLAUDE.md because it applies whether
/boss is active or not.
Two cross-references that named the moved subsections by sub-heading
are repointed: skills/implement/SKILL.md and the implement-orchestrator
agent's standing reading list. The other ~11 agent-file references to
"orchestrator framing" still resolve correctly because that framing
stays in CLAUDE.md.
skills/README.md skill table extended with a `boss` row (now eight
skills); pipeline-diagram caption notes /boss wraps the pipeline.
.claude/skills/boss symlink follows the existing relative-path
convention.
The previous one-liner 'notify when done and nothing left to do'
left 'done' under-defined. Concrete failure mode (2026-05-12, this
session): test suite for an open milestone landed, I notified on
the user-specified stop trigger, but the milestone still had two
follow-up iters (DESIGN.md anchor + audit) plainly in scope. The
user's intent behind the trigger was 'wake me when there's
nothing else to do', not 'wake me at this checkpoint'.
The expanded section codes two states (done-state, problem-state),
explicitly names sub-goal completion as NOT a notify event, and
calibrates user-specified stop triggers: hit only if the trigger
leaves the queue truly empty.
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.
Anthropic now reserves /plan as a UI command, so the Skill tool refuses to
dispatch it. Rename the project's plan skill to planner, update the symlink
under .claude/skills/, and adjust references in CLAUDE.md, DESIGN.md,
skills/README.md, and the cross-references between brainstorm / implement /
audit / fieldtest / fieldtester. Plan files themselves (docs/plans/*.md)
keep their name — only the skill ID changes.
Reversal of the language decision from 6d94fa5. Texts that get
committed to the repo permanently should follow the same English-
only rule as everything else; the Notify push stays 1:1 with the
WhatsNew entry, so both are English now.
The "only file intentionally not in English" carve-out in CLAUDE.md
is removed.
Done-state notifications now produce two synchronised outputs sharing
one text: an entry appended to docs/WhatsNew.md and the same string
sent via notify.sh. The text is written in German for the user-as-
reader who did not watch the session — no technical internals, no
iteration codes, lead with the change-in-the-project.
WhatsNew.md is the only file in the repo intentionally not in English;
the exception is documented in CLAUDE.md (Roles of docs/...) so a
future reader does not "correct" it back. Bounce-back notifications
stay Notify-only.
Adds a priority-ordered, checkbox-format roadmap that the
orchestrator maintains. Three states (`[ ]` open / `[~]` in
progress / `[x]` done), four kinds (milestone / feature / todo /
idea), four priorities (P0..P3). Initial population lifts the
queued items from the JOURNAL tail.
JOURNAL's role narrows: chronological decisions log only, no
forward queue. CLAUDE.md "Roles of ..." section updated to
reflect the split.
Replace the original "Invent your own programming language" prompt
(the very first text in the repo) with a focused statement of the
language's design goal: AILang is for LLM authors, contrary to
conventional compiler design. Lead with the four design priorities
(machine readability, local reasoning, provability, hallucination
robustness) and the cut/keep asymmetry from DESIGN.md's
feature-acceptance criterion.
Compress three sections that now duplicate skill content:
- Skill-system bullet list -> 1-line pointer to skills/README.md.
- Bug-fixes TDD headline -> 1-line pointer to skills/debug/, as
required by skills/debug/SKILL.md ("CLAUDE.md keeps a one-line
pointer").
- Milestone-cycle pipeline diagram + tidy mandate -> short pointer
to skills/README.md and skills/audit/SKILL.md, retaining only the
iter/family vocabulary note that lives nowhere else.
Also fix the Code-layout skills row to match the current repo
(fieldtest had been missing).
Discipline sections that govern behaviour *between* skills (orchestrator
role, when-not-to-delegate, design-rationale-vs-effort, direction
freedom, notifications) and substantive always-on rules (LLM-utility
feature gate) stay verbatim — they are not skill-replaceable.
247 -> 229 lines.
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.
agents/ contained only README.md after the 2026-05-09 migration. The
roster information is more naturally located alongside the skills it
points into. skills/README.md is now the single index (skill table,
pipeline diagram, agent roster, discovery, conventions, how-to-add).
CLAUDE.md updated: code-layout entry consolidated, @-reference points
to skills/README.md.
Adds DESIGN.md "Feature-acceptance criterion" as a top-level section:
a feature ships only if (1) an LLM author naturally produces code
that uses it, and (2) it measurably improves correctness or removes
redundancy. Aesthetic appeal and human ergonomics do not count.
Mirrored in CLAUDE.md as "Feature acceptance: LLM utility", paired
with the existing "Design rationale != implementation effort". The
two together narrow valid feature rationales to one thing: what the
LLM author gets out of the feature.
Trigger: the typeclass-design conversation around 22a. Rule was
implicit in many past decisions (Decision 1's JSON-over-text choice,
Decision 10's "what LLMs are good at" reasoning) but never stated
as a feature-gate. Codifying it now means future feature proposals
get evaluated against an articulated criterion instead of being
re-derived each time.
Documentation-only; no Rust, schema, or bench changes. Test state
288/0/3 unchanged.
Closes the question CLAUDE.md has carried since day one ("LLVM-
linkable, performance is extremely important") with data. Hand-C
variants of the four bench fixtures, compiled with clang -O2,
each carefully matching the AILang algorithm and explicitly
documenting representation differences (cell width, leak policy)
that affect the ratio.
Three substantive findings:
1. Pure-compute parity with C: bench_compute_collatz runs at
AILang/C = 0.99x across both allocators. AILang's IR composes
with LLVM's optimizer at the same level a hand-C source does.
This is the LLVM-linkable performance claim, backed by data
for the first time. bench_compute_intsum (1.05-1.18x) confirms.
2. AILang bump beats glibc malloc 2x on linear allocation:
bench_list_sum.bump/c = 0.50x. Bump's two-instruction inline
fastpath outperforms glibc's free-list-managed malloc on
no-free workloads. Quantitatively measured for the first time.
3. RC overhead vs C malloc quantified: bench_list_sum.rc/c =
1.49x, bench_tree_walk.rc/c = 2.61x. The 8-byte refcount
header + zero-init + libc backing add 50-160% over glibc
malloc on these implicit-mode workloads. Explicit-mode + a
free()-adding C variant (21'f, queued) will close the
apples-to-apples gap on dec-cost.
CLAUDE.md updated to list bench/cross_lang.py as the third
tidy-iter gate alongside bench/check.py and bench/compile_check.py.
20 new metrics in bench/baseline_cross_lang.json with 12-15%
tolerances (cross-language ratios are inherently noisier than
within-AILang ratios — two compiler stacks contribute variance).
Closes the second axis the user named: every typechecker / codegen
perf change was previously invisible to the tidy-iter gate. With
Family 21 typeclasses (queued) and 21'b's poly-ADT additions both
pushing on the typechecker, naive substitution loops would have
landed silently and decayed the compile path.
bench/compile_check.py is a separate script from bench/check.py
because the methodology differs: sub-process spawn timing on small
workloads (1ms scale for `ail check`, 65ms for `ail build`) vs.
allocator-stress on large ones (multi-second). Tolerances differ
by an order of magnitude (25% / 20% here vs. 5-15% there).
Empirically: ail check is sub-ms across the corpus, dominated by
subprocess spawn (~5-10ms on Linux); ail build is 63-69ms,
dominated by clang's link step. The bench is a catastrophe
detector (10x slowdowns visible) — finer regressions need a
profiler. CLAUDE.md updated to list both scripts as co-equal
tidy-iter gates alongside the architect drift report; exit 0/1/2
semantics are uniform across both.
JOURNAL queue: 21'd (pure-compute fixtures) and 21'e (cross-
language reference / hand-C ratio) remain to land the LLVM-
linkable performance claim.
Adds a "Performance regressions" subsection to the iter-cycle
discipline. bench/check.py runs at every family close alongside
the architect drift report; its exit code is the gate. Skipping
it requires the same explicit JOURNAL entry as skipping the
drift review.
Codifies the discipline that 21'a's JOURNAL entry recommended
and explicitly punted to the orchestrator. The tooling shipped
yesterday; the rule that makes it load-bearing ships now.
Also clarifies two non-goals: per-metric tolerances are not the
language correctness bar (Decision-10 thresholds remain in
DESIGN.md, evaluated against absolute numbers); and improvements
do not auto-update the baseline — they surface for ratification.
The Telegram-via-PushNotification-tool path is replaced with a
direct ~/.claude/notify.sh "Text" invocation. Same payload
discipline (actionable one-liner, skip 'hi, I' framing); the
delivery channel is now under the user's control. Tested in the
previous session.
Bug fixes are red-then-green: write a failing test that pins the
symptom, make the smallest change that turns it green, keep the
test as a permanent regression. No fix without a test.
Bug fixes do not need orchestrator permission — when a bug is
unambiguous (build broken, fixture crashes, refcount underflow,
observable wrong output), the fix is autonomous orchestrator work.
The user directs features and priorities; bug fixes are mechanical
work that ships when the bug is found.
User wired up Telegram push notifications. New subsection under
"Direction freedom" pins down the discipline: only notify when
something is genuinely wanted from the user — exactly the
existing bounce-back triggers (real design judgement, genuinely
unexpected event, explicit checkpoint). Never for routine
progress or FYI updates.
The notification is the exception, not the rule. Default mode
stays autonomous. The notification body is the actionable
summary, one short line, phone-screen friendly.
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.
User correction during the post-RC-overnight check-in: the 18a
"Type::Fn metadata vs. new Type variant" call was justified
across DESIGN.md, JOURNAL, and the commit message primarily by
"avoids ~250 match-arm sites". That is an observation about the
current state of the code, not a design rationale.
CLAUDE.md gains two binding rules:
- Design rationale ≠ implementation effort. Effort is at most a
tiebreaker; a choice whose only stated reason is effort is
suspect. The rule names the 18a misstep as the canonical
anti-example so future sessions catch it earlier.
- Direction freedom + bounce-back conditions inlined (was
previously a cross-reference to a private auto-memory file
outside the repo, which the user couldn't see).
DESIGN.md Decision 10's Schema-additions block now leads with
the substantive reasons for per-position metadata: semantic
locality (modes belong to fn-parameter positions, not to types
in general — Decision 1 line); compositional clarity (type
identity vs. calling convention factor apart); future-proofing
(per-position metadata generalises; Type-variant approach
combinatoric blows up). The match-arm count remains parenthetical,
explicitly named a tiebreaker.
JOURNAL records the correction itself — the mistake stays as a
data point because how design discipline corrupts is informative.
Adds an explicit "My role: orchestrator" section so the discipline
doesn't drift across sessions. Three concrete contracts:
- What I do myself (planning, design, JOURNAL/DESIGN) vs. what gets
delegated (implementation, testing, debugging, architectural
drift review). Trivial mechanical edits stay inline.
- Authority over /agents/: I may add, edit, retire, or replace agent
definitions when orchestration needs change, with the change going
through git like any other code.
- When NOT to delegate: direct user questions, single judgement
calls, and cases where context is already loaded.
Triggered by a session where I quietly took over implementer work
on Iter 13a instead of routing it through ailang-implementer.
Finishes the project-wide English convention:
- CLAUDE.md (the user opted in to translate it too).
- examples/hello.ail.json: "Hallo, AILang." -> "Hello, AILang.".
- E2E test assertion and IR snapshot for hello regenerated to match.
- DESIGN.md "Project language: English" section: the previous
CLAUDE.md exception is dropped.
After this commit, no German remains in any committed file
(grep -P '[äöüÄÖÜß]' is empty across .rs / .md / .json / .ll).
Verified: cargo test --workspace passes (44/44).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Erste lauffähige Iteration. examples/sum.ail.json wird zu nativem Binary
kompiliert und druckt 55 (Summe 1..10) als End-to-End-Test.
Architektur:
- ailang-core: hashbares JSON-AST + canonical-form + pretty-printer
- ailang-check: monomorpher HM-Subset + Effekt-Set-Tracking
- ailang-codegen: LLVM-IR-Text-Emitter (kein libllvm-link)
- ail: CLI mit check/manifest/render/describe/emit-ir/build/builtins
Designentscheidungen sind in docs/DESIGN.md dokumentiert; der Verlauf
in docs/JOURNAL.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Brummel