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.
This commit is contained in:
2026-05-10 11:49:44 +02:00
parent 18fc014377
commit ecc00fed8a
2 changed files with 124 additions and 8 deletions
+16 -8
View File
@@ -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/<milestone>.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).