From ecc00fed8ac4c2b382b7d5c6f9a3b7d021d1410d Mon Sep 17 00:00:00 2001 From: Brummel Date: Sun, 10 May 2026 11:49:44 +0200 Subject: [PATCH] roadmap: introduce docs/roadmap.md as forward queue 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. --- CLAUDE.md | 24 +++++++---- docs/roadmap.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 124 insertions(+), 8 deletions(-) create mode 100644 docs/roadmap.md diff --git a/CLAUDE.md b/CLAUDE.md index 4f3f756..7429593 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -199,7 +199,7 @@ Vocabulary note: legacy JOURNAL entries (pre-2026-05-09) use "iter" / "family"; new entries use "iteration" / "milestone". Existing entries are not retroactively renamed. -## Roles of `docs/JOURNAL.md`, `docs/DESIGN.md`, `docs/specs/`, `docs/plans/` +## Roles of `docs/DESIGN.md`, `docs/JOURNAL.md`, `docs/roadmap.md`, `docs/specs/`, `docs/plans/` - **`docs/DESIGN.md`** is the canonical specification. It describes what AILang *is*: schema, semantics, invariants, runtime contracts. @@ -211,10 +211,18 @@ Existing entries are not retroactively renamed. - **`docs/JOURNAL.md`** is the decisions log. It records *why* the project moved the way it did — alternatives considered and - rejected, lessons from past iterations, queued options for future - work, and the rationale behind choices that does not belong in - `docs/DESIGN.md` (rationale is about the choice, not about the - language). + rejected, lessons from past iterations, and the rationale behind + choices that does not belong in `docs/DESIGN.md` (rationale is + about the choice, not about the language). It is chronological + and append-only; it does not carry the forward queue. + +- **`docs/roadmap.md`** (since 2026-05-10): the priority-ordered + forward queue — milestones, features, todos, and ideas. The + orchestrator owns this file and is responsible for keeping it + current: adding new entries, reprioritising, removing items + that are done or dropped. Entries are checkbox lines; finished + items get checked off, then removed (with a one-line mirror in + JOURNAL) once they stop being interesting context. - **`docs/specs/.md`** (since 2026-05-09): per-milestone design spec produced by `skills/brainstorm`. Hard-gate before any @@ -224,6 +232,6 @@ Existing entries are not retroactively renamed. bite-sized executable plan produced by `skills/plan`, consumed by `skills/implement`. -Together these answer two questions: "what is the language right -now?" (DESIGN) and "how did we get here, and what's next?" (JOURNAL, -specs, plans). +Together these answer three questions: "what is the language right +now?" (DESIGN), "how did we get here?" (JOURNAL, specs, plans), +and "what's next?" (roadmap). diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..5dbd241 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,108 @@ +# AILang Roadmap + +Priority-ordered list of upcoming work — milestones, features, todos, +and ideas. The orchestrator maintains this file. The user can request +additions; the orchestrator chooses what to remove or reprioritise as +work progresses. + +## Conventions + +- One checkbox per entry. `- [ ]` is open; `- [~]` is in progress + (work has started — a plan exists, a branch is open, or commits are + landing); `- [x]` is done. A finished entry may stay briefly for + context, then is removed (with a one-line mirror in + `docs/JOURNAL.md`). +- Each entry is tagged by **kind** and lives under a **priority** + bucket: + - **\[milestone\]** — big chunk that will get a `docs/specs/.md`. + - **\[feature\]** — smaller addition inside a milestone, no full + spec. + - **\[todo\]** — concrete task that can run without a brainstorm + (cleanup, doc fix, mechanical refactor, test backfill). + - **\[idea\]** — not yet decision-ready, no commitment. +- Optional `depends on:` line names another entry that has to land + first. +- Optional `context:` line points to the JOURNAL entry where the + rationale lives. The roadmap is intentionally terse; rationale + stays in JOURNAL. +- Priority buckets: + - **P0** — in flight. Spec or plan already exists. + - **P1** — next up. Decision made; not yet started. + - **P2** — medium-term. Decided in principle, scheduled later. + - **P3** — ideas. No commitment; may be cut. + +## 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: + - [~] Sweep 1 — remove history anchors + (`docs/plans/2026-05-10-design-md-consolidation-1-history-anchors.md`; + tasks 1-3 of 6 landed) + - [ ] Sweep 2 — REVERTED + migration plans out + - [ ] Sweep 3 — schema SoT inversion + data-model hardening + - [ ] Sweep 4 — workflow / cross-reference cleanup + +## P1 — Next + +- [ ] **\[milestone\]** Post-22 Prelude — ship `Show` / `Eq` / `Ord` + with the four primitive instances (Int, Bool, Str, Float); rewire + `print` through `Show.show`. Originally queued as 22b.4 in the + typeclass milestone, kept on hold pending demand. + - context: JOURNAL 2026-05-09 ("JOURNAL queue") + - depends on: design-md-consolidation (touches DESIGN.md schema + sections that the consolidation will reshape) + +## P2 — Medium-term + +- [ ] **\[feature\]** Operator routing through `Eq` / `Ord` — `==`, + `<` etc. resolved via the typeclass instead of the built-in + primitive comparators. No commitment; gated on bench re-baselining + to make sure the indirection doesn't tank latency. + - context: JOURNAL 2026-05-09 + - depends on: Post-22 Prelude +- [ ] **\[todo\]** `types` / `ctor_index` overlay shape question — + decide whether the env's two parallel ctor maps should collapse + into one overlay, or stay split. Surfaced during the + env-construction unify audit. + - context: JOURNAL 2026-05-10 ("Audit close: env-construction unify") +- [ ] **\[feature\]** 22c — typeclass corpus expansion. User-defined + classes beyond the prelude four; multi-parameter classes; superclass + chains; richer instance bodies. Deferred from milestone 22. + - context: JOURNAL 2026-05-09 +- [ ] **\[todo\]** Boehm full retirement — remove the transitional + Boehm GC path now that RC + uniqueness is the canonical memory + story. + - context: JOURNAL pre-22, "Boehm transitional" +- [ ] **\[feature\]** Closure-pair slab / pool — codegen tweak to + pool the env+code closure pairs instead of one-shot heap allocs. + Bench-gated. +- [ ] **\[todo\]** `FnDef::synthetic` flag — formalise the + monomorphiser-emitted FnDefs so downstream passes can tell + user-authored from synthesised at a glance. Currently inferred from + symbol naming. +- [ ] **\[todo\]** 21'h iteration — final 21' carry-over (latency + methodology pass). Numbering kept for continuity with the 21' arc. + +## P3 — Ideas + +- [ ] **\[idea\]** Latency methodology rework — switch from per-run + timing to a histogram-based approach so tail-latency regressions + are visible without re-running. Queued from 21'g. +- [ ] **\[idea\]** Parser-test backfill for 22b.4a-era duplicate-clause + sites (class × 3, class method × 2, instance × 3, instance method + × 1). No regression pin today; only worth it if a 22b.4a-era + diagnostic needs to change. + - context: JOURNAL 2026-05-10 ("Iteration 22-tidy.7") +- [ ] **\[idea\]** `write_type` `Type::Forall` arm in + `crates/ailang-prose/src/lib.rs` silently drops constraints in + inline-type rendering. Dormant — surface forms today only carry + forall at fn-signature top level. Fix only if a future feature + carries forall + constraints inline. + - context: JOURNAL 2026-05-10 ("Iteration 22-tidy.6") +- [ ] **\[idea\]** Richer integration paths between RC and + uniqueness — deferred from the 21' arc; revisit once the + uniqueness inference covers more program shapes.