diff --git a/docs/JOURNAL.md b/docs/JOURNAL.md index 8e6c11b..4a97674 100644 --- a/docs/JOURNAL.md +++ b/docs/JOURNAL.md @@ -12759,3 +12759,211 @@ Process notes: the ClassDef/class class of bug structurally rather than through grep-presence + spot inspection. Out of scope for iter 3; queued. + +## 2026-05-10 — Iteration design-md-consolidation 4: workflow / cross-reference cleanup + +Fourth and final iteration of the milestone defined in +`docs/specs/2026-05-10-design-md-consolidation.md`. Sweep 4 +closes the "workflow / cross-reference cleanup" item: the stale +`agents/` ecosystem entry is replaced with a `Skills` entry +pointing to `skills//agents/`; the workflow-detail +attribution to `ailang-docwriter` in §"Verification and +correctness" is dropped (the rule survives, the agent assignment +lives in skills SoT); the "Recently lifted gates" history +paragraph is removed from §"What is not (yet) supported"; the +stale `see the JOURNAL queue` Pipeline pointer is updated to +`docs/roadmap.md` (per the user's 2026-05-10 split that moved the +forward queue out of JOURNAL); two additional residues caught by +the cross-reference audit are closed in a fixup ("Sharpened later +the same day" temporal anchor in Decision 10's opener — a +Sweep-2 missed pattern; supplementary "see closure conversion in +JOURNAL" pointer in the Term::Lam description — not load-bearing). + +Edits: + +- §"Project ecosystem" `Agents` bullet → `Skills` bullet: names + the six skills (`brainstorm`, `plan`, `implement`, `audit`, + `debug`, `fieldtest`) and points to `skills//agents/` as + the agent location; references `skills/README.md` instead of + the (now non-existent) `agents/README.md`. +- §"Project ecosystem" `Docs` bullet expanded: adds `roadmap.md` + (forward queue), `specs/` (per-milestone design specs), + `plans/` (per-iteration implementation plans), and tags + DESIGN.md as "canonical state" + JOURNAL.md as "chronological + decisions log". +- §"Verification and correctness" item 6: `ailang-docwriter` + agent attribution stripped; the "rustdoc warnings are fixed in + the iteration that introduced them, not as follow-up" rule + survives. +- §"What is not (yet) supported" opener: the "Recently lifted + gates that used to live here: cross-module ADTs … `==` + polymorphism" enumeration removed. The first sentence + ("Snapshot of the current boundary. Items move out of this list + as iterations land; the JOURNAL records when.") survives as a + state-only lead-in. +- Pipeline section: `retirement; see the JOURNAL queue.` → + `retirement; see \`docs/roadmap.md\` for the active queue.` +- Decision 10 opener (fixup): `Sharpened later the same day:` → + removed; "was extended" → "is extended" (present-tense state). +- Term::Lam description (fixup): `(see closure conversion in + JOURNAL)` parenthetical removed — the binding claim ("free + variables of its body are captured from the enclosing scope") + is self-sufficient. + +Cross-reference audit final inventory (post-fixup): + +- 3 JOURNAL bench-notes pointers retained as binding-evidence + anchors: + - line ~786 (Decision 10 opener: "bench notes in JOURNAL") + - line ~817 (closure-chain ratio: "current ratio recorded in + JOURNAL bench entries") + - line ~848 (tracing-GC argument: "JOURNAL bench notes") + - line ~1511 (mono-vs-vdisp ratio: "JOURNAL bench-notes entry + record the measured ratios") +- 1 JOURNAL rationale pointer retained (line ~1611, + higher-rank-polymorphism prohibition: "rationale recorded in + JOURNAL"). +- 1 `docs/roadmap.md` pointer added (Pipeline section). +- 1 `skills/README.md` pointer added (Project-ecosystem Skills + bullet). +- 1 `skills//agents/` pointer added (Project-ecosystem + Skills bullet). +- §"Project ecosystem" Docs bullet names DESIGN.md / JOURNAL.md / + roadmap.md / specs/ / plans/ as the doc family. +- §"What is not (yet) supported" lead-in retains + "the JOURNAL records when" as a binding pointer to where each + feature's ship-date lives. + +Acceptance: + +- composite Sweep-4 grep + `grep -nE '\(\`agents/\`\)|agents/README\.md|ailang-docwriter|Recently lifted|see the JOURNAL queue|later the same day|Sharpened later|closure conversion in JOURNAL' docs/DESIGN.md` + empty. +- Sweep-1 + Sweep-2 + Sweep-3 invariants stay empty (no + regression). +- `cargo test -p ailang-core --test design_schema_drift` 7 tests + pass. +- `cargo test --workspace` 0 FAILED. +- `bench/check.py` 0 regressed (63 metrics; 4 improved beyond + tolerance, 59 stable). `bench/compile_check.py` 0 regressed (24 + metrics, 24 stable). +- DESIGN.md size: 2139 → 2132 lines (−7 this sweep, −130 + cumulatively from 2262 at milestone start). + +Tasks (commit subjects): + +- design-md-consolidation 4.1: fix Project-ecosystem stale agents/ path; expand Docs bullet to name roadmap.md + specs/ + plans/ +- design-md-consolidation 4.2: strip ailang-docwriter agent workflow detail from Verification section; rule survives +- design-md-consolidation 4.3: drop 'Recently lifted gates' history paragraph from §What-is-not-yet-supported +- design-md-consolidation 4.4: cross-ref audit — JOURNAL queue → roadmap.md; bench pointers retained as binding-evidence anchors +- design-md-consolidation 4.4 fixup: drop 'Sharpened later the same day' temporal anchor + supplementary 'see closure conversion in JOURNAL' pointer + +Process note: the cross-reference audit (Task 4) surfaced two +additional residues — one Sweep-2 missed pattern ("Sharpened +later the same day") and one not-load-bearing supplementary +pointer ("see closure conversion in JOURNAL"). Both closed inside +Sweep 4 via fixup. Audit-as-discovery worked as intended for +Sweep 4 in the same way it worked for Sweep 3 (the schema-tag +drift caught by `design_schema_drift.rs`): the closing iter of a +milestone surfaces residues the earlier iters missed because +their grep coverage was scoped to specific patterns. + +## 2026-05-10 — Milestone close: design-md-consolidation + +Four sweeps shipped over a single working day. DESIGN.md +transitioned from a mixed state/history/workflow document +(2262 lines) to a state-only specification (2132 lines, −5.7%) +with three orthogonal SoTs cleanly separated: + +- `docs/DESIGN.md` — canonical state + timeless rationale. +- `docs/JOURNAL.md` — chronological decisions log. +- `docs/roadmap.md` — forward queue (introduced by user during + iter 1; integrated into the role table in iter 4). +- `skills//SKILL.md` + `skills//agents/` — workflow + disciplines and agent rosters. +- `crates/ailang-core/src/ast.rs` — Rust-side projection of + DESIGN.md §"Data model" (drift-tested). + +What changed across sweeps: + +- **Sweep 1 (history anchors):** 11 commits. Removed 93 iter + tags + ~16 bare iter-id residues + 4 family tags + 13 date + anchors + 4 status markers; condensed 7 of 12 historical bench + data-points (5 KEEPs grounded the 1.3× retirement target / + ±15% closure-band tolerance policy contracts). +- **Sweep 2 (REVERTED + migration):** 7 commits. Deleted + Decision 7 (Term::If REVERTED block, 32 lines), Decision 10 + Migration plan (32 lines), Decision 9 narrative-of-changes + opener + pre-Decision-9 history paragraphs, Decision 11 + mono-vs-vdisp correction history; condensed 5 future-iter + speculations (1 KEPT as a binding prohibition restructured to + assertive form; 4 REMOVED as non-binding aspirations). +- **Sweep 3 (schema SoT inversion):** 6 commits. Removed 2 Rust + code blocks from Decision 10; inverted §"Data model" SoT + relationship (DESIGN.md canonical, ast.rs projection, drift + test enforces); updated `ast.rs` module doc-comment to + bold-emphasise the inversion; created + `crates/ailang-core/tests/design_schema_drift.rs` (7 tests, + exhaustive match per enum); fixed real schema-vs-doc drift in + Decision 11 §"Form-A schema" (`"kind": "ClassDef"` / + `"InstanceDef"` → `"kind": "class"` / `"instance"` to match + the actual `rename_all = "lowercase"` serde output). +- **Sweep 4 (workflow / cross-reference cleanup):** 5 commits + + 1 close. Project-ecosystem Skills/Docs bullets modernised; + Verification workflow detail stripped; "Recently lifted gates" + history paragraph removed; stale JOURNAL queue pointer + updated to `docs/roadmap.md`; two cross-reference-audit + residues closed inside the iter via fixup. + +Cumulative commit count: 29 commits (4 spec/plan + 25 task / +fixup / nit / close). + +Open questions queued for follow-up: + +- **Drift test fidelity widening.** The current + `design_schema_drift.rs` guards DESIGN.md text presence, not + serde-roundtrip fidelity. A future hardening would round-trip + a constructed `Def` value through `serde_json::to_value` and + assert the emitted JSON matches one of DESIGN.md's anchors + literally — that catches the ClassDef/class class of bug + structurally rather than through grep-presence + spot + inspection. Out of scope for this milestone; queued. +- **Architect agent iron-law extension.** The architect agent's + drift-review iron law could be extended with the standing + greps from Sweeps 1, 2, and 4 so that future commits to + DESIGN.md cannot reintroduce history anchors / REVERTED + narratives / workflow detail without the architect flagging + it. Out of scope for this milestone; queued. + +Process retrospective: + +- The Sweep-1 lesson ("plan-time grep must match spec intent") + held across Sweeps 2-4. No fixup commits were required for + *missed* anchor variants in Sweeps 2, 3, or 4 — the variants + the spec named were all caught by their respective composite + greps on the first attempt. +- Three real bugs / residues were surfaced and closed inside the + milestone, each by a different mechanism: + - Sweep 1 closing: bare iter-id forms ("pre-19b", "14d", "22a" + etc.) — caught by the implementer's "known debt" note + + orchestrator's widened grep. + - Sweep 3 closing: schema-tag drift `ClassDef`/`InstanceDef` + vs serde-emitted `class`/`instance` — caught by the new + drift test created in the same iter. + - Sweep 4 closing: "Sharpened later the same day" + + "(see closure conversion in JOURNAL)" — caught by the + cross-reference audit walk-through in Task 4. + Each closure was an in-scope expansion of the discovering + iter, not deferred debt. +- Quality reviewer's nit-level findings (trailing whitespace, + dangling cross-references, doc-comment task-tag prefixes) + were closed inline as orchestrator edits where mechanical, or + dispatched as fixup commits where judgment was needed. The + two-stage review pattern (spec compliance → code quality) + caught residues that a single-stage review would have missed. +- DESIGN.md size reduction (130 lines, 5.7%) is observation, not + target. The substantive change is the *structure* — three + axes cleanly separated, no mixed framing, drift-test enforcing + the schema axis. A reader can now trust DESIGN.md as + state-only without filtering history-vs-state-vs-workflow on + every paragraph. diff --git a/docs/roadmap.md b/docs/roadmap.md index c371b73..74a9b8e 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -33,16 +33,13 @@ work progresses. ## P0 — In flight -- [~] **\[milestone\]** design-md-consolidation — `docs/DESIGN.md` - becomes a state-only specification across four thematic sweeps - (history anchors out, migration plans out, schema-SoT inversion + - data-model hardening, workflow / cross-reference cleanup). - - context: `docs/specs/2026-05-10-design-md-consolidation.md` - - sub-entries: - - [x] Sweep 1 — remove history anchors - - [x] Sweep 2 — REVERTED + migration plans out - - [x] Sweep 3 — schema SoT inversion + data-model hardening - - [ ] Sweep 4 — workflow / cross-reference cleanup +- [x] **\[milestone\]** design-md-consolidation — `docs/DESIGN.md` + is now a state-only specification across four thematic sweeps + (history anchors out, REVERTED + migration plans out, + schema-SoT inversion + data-model hardening, workflow / + cross-reference cleanup). Closed 2026-05-10. + - context: `docs/specs/2026-05-10-design-md-consolidation.md`, + JOURNAL milestone-close entry of same date. ## P1 — Next