AILang/docs/journals/2026-05-11-iter-cadence.md

iter cadence — audit/fieldtest/docwriter cadence restructure

Date: 2026-05-11 Branch: main Status: DONE Tasks completed: 5 of 5

Summary

This iter sorts the milestone-close stretch of the pipeline into three cadence buckets, packaged by stability-window rather than by milestone-grain:

1. Per-milestone-mandatory — audit. Runs every milestone close. Architect drift review against DESIGN.md plus the three regression scripts (bench/check.py, bench/compile_check.py, bench/cross_lang.py). Step 3 ("Optional rustdoc audit") and the ailang-docwriter cross-reference are removed; the rustdoc warning line is gone from the Handoff Contract and the Common Rationalisations table. Audit is now purely drift + bench.
2. Boss-judgment post-audit — fieldtest. Fires only when the orchestrator decides the iteration is correct and wants a field test, after audit closes clean (or with ratify-d drift only). Trigger is reframed from "audit closes" to "Boss judgment call"; the expected finding shape (simple bugs route via debug, catastrophic architecture problems route via next brainstorm) is named explicitly. Cross-references add the ordering rule: fieldtest runs before docwriter.
3. Boss-judgment post-fieldtest — docwriter. New skill at skills/docwriter/SKILL.md. Boss-dispatched only, never triggered by audit closing. Pre-condition is clean audit plus any pending fieldtest. The agent (ailang-docwriter) carries the substantive rustdoc rules; the SKILL.md only governs trigger and dispatch. Symlinks added at .claude/skills/docwriter and .claude/agents/docwriter.

skills/README.md is the one place that visibly mirrors the new three-bucket taxonomy: the skill table grew from six rows to seven, the pipeline diagram extends past audit --(clean)--> into fieldtest and docwriter as two distinct Boss-decision points, and the agent roster moves ailang-docwriter into its own dispatch group.

Per-task subjects

• iter cadence.1: skills/docwriter — new Boss-dispatched skill (split from audit)
• iter cadence.2: skills/audit — drop docwriter step (now own skill)
• iter cadence.3: skills/fieldtest — Boss-dispatched framing + ordering note
• iter cadence.3-fix: address quality-review minors (frontmatter desc + cross-ref path)
• iter cadence.4: skills/README — three-bucket cadence taxonomy
• iter cadence.4-fix: drop stale audit-dispatches-docwriter parenthetical (README Conventions)
• iter cadence.4-fix: address quality-review importants + German-loanword sweep (English-only in-tree)
• iter cadence.5: per-iter journal + INDEX

Lesson

Packaging cadence by stability-window outperforms packaging by milestone-grain. The previous arrangement bundled rustdoc cleanup into audit as an "optional Step 3", which papered over the real mismatch: rustdoc rot is a post-stability concern (documenting something that gets rewritten three iterations later is waste), while drift review and bench regression are per-iteration concerns (letting them slip even one milestone compounds). Bundling those two cadences inside one skill made the optional step easy to skip on every milestone, which is exactly the failure mode the skill discipline exists to prevent. Splitting docwriter out into its own Boss-dispatched skill makes the cadence honest: audit is non-negotiable per milestone, docwriter is non-negotiable per stability window. The fieldtest framing flip — from "fires when audit closes" to "Boss judgment after audit closes" — is the same refactor at a smaller scale: the milestone clock was not the right trigger; the orchestrator's judgement that the iteration is complete is.

Concerns

None worth carrying forward. Three quality-review-fix follow-ups on cadence.3 and cadence.4 (frontmatter description drift, stale audit-dispatches-docwriter parenthetical, one German-loanword in in-tree text) — all caught by the standard implement-skill two-stage review and resolved inline.

Known debt

• The agent file skills/docwriter/agents/ailang-docwriter.md was moved from skills/audit/agents/ by the user before this iter began. Its standing reading list still names skills/audit as its home in one or two phrasings; a sweep of the agent's cross-references is a candidate tidy iteration but did not block this iter's narrower SKILL.md reshuffle.
• docs/specs/2026-05-11-audit-fieldtest-docwriter-cadence.md is a dated artefact — the spec describes the design at time of writing and is not retroactively updated as the implementation shipped. Per the or.1 convention, the per-iter journal is the running annotation.

Blocked detail

N/A — DONE.

Commits

e351969^..HEAD (8 commits including 3 quality-review-fix follow-ups across cadence.3 and cadence.4).