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.
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.
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).
The effect-op-arg-modes brainstorm spec bundled a real, self-contained
DESIGN.md honesty fix with speculative build-ahead infra (an EffectOpSig
arg-mode field whose only consumer was a synthetic test op). Recon had
already destroyed the "effect-handler infrastructure" premise: the effect
raise/declare/subset/propagation machinery is fully generic over any
effect string; the only real prerequisite was one struct field, not a
milestone. The user rejected the bundle as incoherent and the
build-ahead half as the iteration-discipline trap repeated.
- Retire the uncommitted effect-op-arg-modes spec (deleted from the
working tree; never committed).
- roadmap: drop the false "sub-ms-2 = effect-handler infrastructure"
framing; mark Stateful-islands sub-milestone sequencing as UNDER
RE-THINK with the user (no !Mut planning until that conversation);
add the split-out effect-doc-honesty as an in-flight P2 [~] todo.
- plan docs/plans/2026-05-16-effect-doc-honesty.md: placeholder-free
tidy plan (the three DESIGN.md fictions + form_a.md + main.rs +
a new doc-presence pin) over recon-mapped exact byte sites.
- brainstorm SKILL: specs and design talk LEAD with the AILang (.ail)
program that should work (= the feature-acceptance clause-1
evidence); the Rust implementation shape is secondary, never a
substitute; a no-surface infra milestone still shows concrete .ail
(often a must-fail fixture). Codifies user feedback from this session.
One forward iteration; main never rewound. 1ff7e81 (the pre-9973546
commit) is the per-region byte oracle — every reverted source/test
file is byte-identical to it; crates/ailang-check/src/lib.rs fully so.
Root cause being corrected: the Iteration-discipline milestone was an
over-escalation of fieldtest finding F1 (a [friction] item whose own
minimal recommendation was a DESIGN.md note). Its totality dichotomy
made the maximally-LLM-natural build(d:Int)=Node(1,build(d-1),
build(d-1)) inexpressible (it.3 BLOCKED); the only in-thesis escape
(A1/it.2b) conceded the language's first documented-unenforced
totality precondition — a purity-pillar dilution the user rejected in
favour of a full revert + rebuild.
Removed: Term::Loop/Term::Recur/LoopBinder; the verify_structural_
recursion guardedness pass + term_contains_loop + Diverge-injection +
the transitively-it.2 module_fns plumbing; the five Recur*/
NonStructuralRecursion CheckError variants (+ code() + the 3 dedicated
ctx() arms); the it.1 codegen loop-header/phi/back-edge + parallel
block_terminated setter; all Loop/Recur walker arms; 16 it.1/it.2
fixtures; 2 pin files; bench/it3-oracle/. Restored: 2 RC fixtures to
1ff7e81 content.
Surgically kept (not in 1ff7e81, landed with the milestone but
independently sound): feature-acceptance clause 3 in DESIGN.md and
skills/brainstorm/SKILL.md, with its worked example de-claimed from
"shipped" to hypothetical-illustration form; the F3 P2 todo.
bench/orchestrator-stats/2026-05-15-iter-it.{1,2,3}.json kept as
historical record (like journals/plans).
Sole net addition: an honest F1/F4 documented-idiom note in DESIGN.md
(the tail-recursive accumulator fallback; examples/mut_counter.ail),
guarded by a doc-presence test — "a documentation note is not a
reshape", asserts nothing at the typecheck level.
Roadmap: the Iteration-discipline block + blocking-fork section
removed; the genuine total-Int-recursion ambition preserved as a
deferred P2 milestone sequenced behind a future Nat/refinement-types
milestone (not abandoned — correctly sequenced after the type
machinery it needs). 2026-05-15-iteration-discipline.md carries a
superseded header; it.1/it.2/it.3 journals + plans stay as history.
Correctness gate PRISTINE: 164 surviving 1ff7e81-era fixtures
ail check/ail run byte-identical to pre-milestone behaviour (verified
against a 1ff7e81 worktree reference compiler, zero drift);
cargo test --workspace 600/0; zero residual it.1/it.2 production
surface.
Spec docs/specs/2026-05-16-iteration-discipline-revert.md (b3853bf),
plan docs/plans/2026-05-16-iter-revert.md (abf0013).
Sharpen the feature-acceptance criterion (DESIGN.md, mirrored in the
brainstorm gate) with a third conjunctive-necessary clause: a feature
reintroduces no bug class the core constraint exists to eliminate.
Criterion 1 ("an LLM reaches for it") does not discriminate — an LLM
reaches for every construct native to its imperative training
distribution, so utility alone would launder the imperative paradigm
back in one construct at a time. Clause 3 is the discriminator; a
documentation note is not a reshape (the gate is whether the wrong
code fails to typecheck).
Record the decided iteration story as a P1 milestone: structural
recursion permitted (total-by-construction under Decision 10's
acyclic-ADT invariant) + named loop/recur as the only other
repetition + tail-app retired. Discharges fieldtest finding F1 without
introducing an imperative construct; closes the residual "forgot to
mark tail" trap completely; unifies with Decision 10 (acyclic values
AND acyclic implicit call graph). Supersedes the "while-loops legal"
scope bullet of the Stateful-islands milestone, which is amended for
internal consistency. The escaping-state path (ref/MutArray/Stateful)
is unaffected and stays in Stateful-islands.
Closes the P1 todo from earlier today: Step 7.5 PASS report is
bound to the exact bytes of the spec at dispatch time. Any
subsequent edit — wording polish, user-requested change, anything
— invalidates the report and forces a fresh dispatch before the
Step 8 commit.
Three edits:
- Step 7.5 gets a 'Re-dispatch on any post-PASS edit' subsection
stating the rule and explaining why (PASS attests to bytes).
- Step 8 wording: '... edit in place, re-run Step 7 AND re-dispatch
Step 7.5, then return here. Only proceed after approval AND a
fresh Step 7.5 PASS.'
- Common Rationalisations + Red Flags gain matching entries
('just polishing wording, no need to re-dispatch' / 'Editing the
spec after PASS without re-dispatching').
Roadmap P1 todo retired with this commit.
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.
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.
Brummel