iter cadence.5: per-iter journal + INDEX

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

@@ -0,0 +1,104 @@
+# 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. Two 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).

docs/journals/INDEX.md

@@ -9,3 +9,4 @@
 - 2026-05-11 — fieldtest canonical-type-names → 2026-05-11-fieldtest-canonical-type-names.md
 - 2026-05-11 — iter pr.1: plan-recon subagent → 2026-05-11-iter-pr.1.md
 - 2026-05-11 — iter or.2: orchestrator-agent design correction (no nested subagent dispatch) → 2026-05-11-iter-or.2.md
+- 2026-05-11 — iter cadence: audit/fieldtest/docwriter cadence restructure → 2026-05-11-iter-cadence.md