workflow: replace docs/roadmap.md with Gitea issue backlog

The forward queue moves out of the in-tree markdown file and into
Gitea issues at http://192.168.178.103:3000/Brummel/AILang/issues.
Labels: kind:{milestone,feature,todo,idea} + prio:{p1,p2,p3}
+ state:in-progress. Big chunks live as Gitea milestones
(containers) with full prose in the description; smaller items are
standalone issues. Browse-and-filter scales constant against
growing item count; the previous markdown file was 1059 lines, of
which ~850 were already-closed-entry verlauf (the same failure
class the JOURNAL cut removed).

Sync-drift Code<>Tracker mitigation: Soft-convention `closes #N`
/ `refs #N` in commit bodies — Gitea auto-closes the issue on
push. Captured in user-level CLAUDE.md (~/.claude/CLAUDE.md, not
in this commit) as the durable rule; no hook enforcement.

In-repo changes:

- docs/roadmap.md deleted.
- CLAUDE.md (project): Code-layout drops roadmap; /boss gating
  retargeted; Roles section rewritten with a new "Gitea issues"
  bullet (URL + tea-CLI snippet) and the closes-#N trailer note.
- skills/boss/SKILL.md: 10 sites retargeted, plus Step 1 now
  prescribes `tea issues ls --labels prio:p1` as the queue read.
- skills/brainstorm/SKILL.md: Step 7.5 no-override BLOCK now
  files a Gitea issue via `tea issues create` instead of
  appending a roadmap entry; spec deletion stays.
- skills/audit/SKILL.md + ailang-architect.md: deferral
  requirement and debt-heuristic retargeted; forward-intent
  belongs in the Gitea backlog.
- skills/fieldtest/SKILL.md, skills/docwriter/SKILL.md +
  ailang-docwriter.md: roadmap → backlog.
- design/contracts/honesty-rule.md: forward intent lives in
  the Gitea backlog (pinned phrases unchanged).
- design/INDEX.md: Docs bullet drops roadmap, adds the backlog
  URL.
- crates/ailang-core/tests/docs_honesty_pin.rs: two assert
  messages retargeted (assertion bodies unchanged).
- bench/architect_sweeps.sh: Sweep-4 TABU extended with
  `docs/roadmap\.md` so the deleted path cannot quietly regrow
  as a cross-reference in design/contracts/.

Verification:

- cargo build --workspace clean.
- cargo test --workspace: 647 passed, 0 failed, 2 ignored.
- bench/architect_sweeps.sh exit 0 (all five sweeps clean, incl.
  new TABU).
- grep over the live tree (excluding docs/specs/, docs/plans/)
  shows zero residual docs/roadmap.md refs.

Not touched: ~55 historical files under docs/specs/ and
docs/plans/ that mention docs/roadmap.md. Snapshot-character,
analogous to the JOURNAL-cut precedent — historical specs are
not mass-edited just because a live file was retired; their
mentions were correct at write time.
This commit is contained in:
2026-05-20 14:48:27 +02:00
parent 99df14c792
commit 93887aa03b
13 changed files with 82 additions and 1122 deletions
+20 -14
View File
@@ -43,7 +43,7 @@ it measurably improves correctness or removes redundancy.
| `bench/` | Regression harnesses (`check.py`, `compile_check.py`, `cross_lang.py`) and the throughput-and-latency runner (`run.sh`); `bench/reference/` holds the hand-C corpus for cross-language ratios | | `bench/` | Regression harnesses (`check.py`, `compile_check.py`, `cross_lang.py`) and the throughput-and-latency runner (`run.sh`); `bench/reference/` holds the hand-C corpus for cross-language ratios |
| `examples/` | AILang fixtures used by tests and benches | | `examples/` | AILang fixtures used by tests and benches |
| `design/` | The canonical contract ledger — `design/INDEX.md` (sole addressable spine: a typed Contracts + Models table), `design/contracts/` (prose-authoritative test-linked invariants), `design/models/` (onboarding whitepapers) | | `design/` | The canonical contract ledger — `design/INDEX.md` (sole addressable spine: a typed Contracts + Models table), `design/contracts/` (prose-authoritative test-linked invariants), `design/models/` (onboarding whitepapers) |
| `docs/` | Specs and roadmap`docs/specs/` (per-milestone design specs), `docs/plans/` (per-iteration plans), `docs/roadmap.md` (forward queue), `PROSE_ROUNDTRIP.md`. Project history lives in `git log`. | | `docs/` | Specs and plans`docs/specs/` (per-milestone design specs), `docs/plans/` (per-iteration plans), `PROSE_ROUNDTRIP.md`. Project history lives in `git log`; the forward queue lives in Gitea issues (see "Roles" section below). |
| `skills/` | Project-local skill definitions and their agents. See `skills/README.md` for the skill table, agent roster, and discovery layout. | | `skills/` | Project-local skill definitions and their agents. See `skills/README.md` for the skill table, agent roster, and discovery layout. |
## Skill system ## Skill system
@@ -54,8 +54,8 @@ are sharper tools, not a replacement for orchestrator judgement.
Specs go to `docs/specs/<milestone>.md`, plans to Specs go to `docs/specs/<milestone>.md`, plans to
`docs/plans/<iteration>.md`. `docs/plans/<iteration>.md`.
Autonomous orchestrator mode — picking the next iter from Autonomous orchestrator mode — picking the next iter from the
`docs/roadmap.md` and looping until done-state — is gated to the Gitea issue backlog and looping until done-state — is gated to the
user-invoked `/boss` skill (`skills/boss/SKILL.md`). Outside user-invoked `/boss` skill (`skills/boss/SKILL.md`). Outside
`/boss`, the default is interactive collaboration: the user asks, `/boss`, the default is interactive collaboration: the user asks,
Claude responds, Claude stops. Claude responds, Claude stops.
@@ -197,7 +197,7 @@ Vocabulary note: pre-2026-05-09 git history uses "iter" / "family";
current vocabulary is "iteration" / "milestone". Old commits are current vocabulary is "iteration" / "milestone". Old commits are
not retroactively renamed. not retroactively renamed.
## Roles of the `design/` ledger, `git log`, `docs/roadmap.md`, `docs/specs/`, `docs/plans/` ## Roles of the `design/` ledger, `git log`, Gitea issues, `docs/specs/`, `docs/plans/`
- **The `design/` ledger** is the canonical specification. It - **The `design/` ledger** is the canonical specification. It
describes what AILang *is*: schema, semantics, invariants, runtime describes what AILang *is*: schema, semantics, invariants, runtime
@@ -210,7 +210,7 @@ not retroactively renamed.
the same iteration. The `design/` ledger is also the artefact the same iteration. The `design/` ledger is also the artefact
`ailang-architect` checks the code against during drift review. `ailang-architect` checks the code against during drift review.
A contract describes only the actual present state; forward intent A contract describes only the actual present state; forward intent
goes to `docs/roadmap.md`, history and rationale to `git log` goes to the Gitea backlog, history and rationale to `git log`
(see `design/contracts/honesty-rule.md`). (see `design/contracts/honesty-rule.md`).
- **`git log`** is the project history. Iter and audit commit - **`git log`** is the project history. Iter and audit commit
@@ -219,15 +219,21 @@ not retroactively renamed.
these bodies at commit time; they are the durable record. Read these bodies at commit time; they are the durable record. Read
recent state with `git log -5 --format=full`; chronological scan recent state with `git log -5 --format=full`; chronological scan
with `git log --oneline -30`; per-milestone scope with with `git log --oneline -30`; per-milestone scope with
`git log <prev-milestone-close>..HEAD --format=full`. `git log <prev-milestone-close>..HEAD --format=full`. Commits
that close a backlog issue reference it via `closes #N` in the
body; Gitea auto-closes the issue on push.
- **`docs/roadmap.md`** (since 2026-05-10): the priority-ordered - **Gitea issues** (since 2026-05-20) are the priority-ordered
forward queue — milestones, features, todos, and ideas. The forward queue — milestones, features, todos, and ideas. Browse:
orchestrator owns this file and is responsible for keeping it http://192.168.178.103:3000/Brummel/AILang/issues. CLI: `tea
current: adding new entries, reprioritising, removing items issues ls --labels prio:p1` etc. Labels: `kind:{milestone,
that are done or dropped. Entries are checkbox lines; finished feature,todo,idea}` and `prio:{p1,p2,p3}`. Big chunks that get
items get checked off, then removed once they stop being their own `docs/specs/` entry live as Gitea **milestones**
interesting context. (containers) plus a `kind:milestone` issue; smaller items are
standalone issues. The orchestrator owns the backlog and is
responsible for keeping it current: opening new issues,
re-labelling for priority, closing on completion (typically via
the `closes #N` commit-body trailer).
- **`docs/specs/<milestone>.md`** (since 2026-05-09): per-milestone - **`docs/specs/<milestone>.md`** (since 2026-05-09): per-milestone
design spec produced by `skills/brainstorm`. Hard-gate before any design spec produced by `skills/brainstorm`. Hard-gate before any
@@ -239,4 +245,4 @@ not retroactively renamed.
Together these answer three questions: "what is the language right Together these answer three questions: "what is the language right
now?" (the `design/` ledger), "how did we get here?" (`git log`), now?" (the `design/` ledger), "how did we get here?" (`git log`),
and "what's next?" (roadmap). and "what's next?" (Gitea backlog).
+1 -1
View File
@@ -52,7 +52,7 @@ run_sweep "3 (schema SoT)" \
'^\s*(struct |enum |pub (struct|enum|fn))|whenever the two disagree|ast\.rs is the source of truth' '^\s*(struct |enum |pub (struct|enum|fn))|whenever the two disagree|ast\.rs is the source of truth'
run_sweep "4 (workflow + stale cross-references)" \ run_sweep "4 (workflow + stale cross-references)" \
'agents/README\.md|ailang-docwriter|Recently lifted|see the JOURNAL queue|later the same day|Sharpened later|closure conversion in JOURNAL|see the per-iter journal|in a per-iter journal' 'agents/README\.md|ailang-docwriter|Recently lifted|see the JOURNAL queue|later the same day|Sharpened later|closure conversion in JOURNAL|see the per-iter journal|in a per-iter journal|docs/roadmap\.md'
run_sweep "5 (honesty: wunschdenken + non-citation post-mortem)" \ run_sweep "5 (honesty: wunschdenken + non-citation post-mortem)" \
'on the path to|may land in a future|ships in a future iter|[Ww]ill back `Show|[Ww]ill eventually (be|support|back)|[Ii]f/?when [a-z]+ (arrives|lands)|[Aa]n earlier draft of this|previously all diagnostics were|[Ww]hat did change in 20|were retired 20[0-9]{2}-|retired in iter [a-z]|originally listed|\bwas deferred\b|foundation for [a-z]' 'on the path to|may land in a future|ships in a future iter|[Ww]ill back `Show|[Ww]ill eventually (be|support|back)|[Ii]f/?when [a-z]+ (arrives|lands)|[Aa]n earlier draft of this|previously all diagnostics were|[Ww]hat did change in 20|were retired 20[0-9]{2}-|retired in iter [a-z]|originally listed|\bwas deferred\b|foundation for [a-z]'
+2 -2
View File
@@ -55,7 +55,7 @@ fn design_corpus() -> String {
fn design_md_has_no_wunschdenken() { fn design_md_has_no_wunschdenken() {
let d = norm(&design_corpus()); let d = norm(&design_corpus());
assert!(!d.contains("is on the path to retirement"), assert!(!d.contains("is on the path to retirement"),
"design/: Boehm retirement is forward intent — it lives in docs/roadmap.md, not the ledger"); "design/: Boehm retirement is forward intent — it lives in the Gitea backlog, not the ledger");
assert!(!d.contains("Will back `Show Float`"), assert!(!d.contains("Will back `Show Float`"),
"design/: 'Will back Show Float' asserts a future capability as fact"); "design/: 'Will back Show Float' asserts a future capability as fact");
assert!(!d.contains("codegen ships in a future iter"), assert!(!d.contains("codegen ships in a future iter"),
@@ -125,7 +125,7 @@ fn design_md_present_tense_anchors_present() {
fn prose_roundtrip_md_has_no_wunschdenken() { fn prose_roundtrip_md_has_no_wunschdenken() {
let p = norm(&read("docs/PROSE_ROUNDTRIP.md")); let p = norm(&read("docs/PROSE_ROUNDTRIP.md"));
assert!(!p.contains("A future iter may layer a tool-use schema"), assert!(!p.contains("A future iter may layer a tool-use schema"),
"PROSE_ROUNDTRIP.md: tool-use/MCP forward intent lives in docs/roadmap.md"); "PROSE_ROUNDTRIP.md: tool-use/MCP forward intent lives in the Gitea backlog");
assert!(p.contains("the lowest-common-denominator cycle and always works with any client"), assert!(p.contains("the lowest-common-denominator cycle and always works with any client"),
"PROSE_ROUNDTRIP.md must close present-tense on the static-prompt path"); "PROSE_ROUNDTRIP.md must close present-tense on the static-prompt path");
} }
+4 -3
View File
@@ -56,9 +56,10 @@ evolving in lockstep with the language:
sole addressable spine for canonical state), `design/contracts/` sole addressable spine for canonical state), `design/contracts/`
(test-linked invariants), `design/models/` (onboarding (test-linked invariants), `design/models/` (onboarding
whitepapers). whitepapers).
- **Docs** (`docs/`): `roadmap.md` (forward queue), `specs/` - **Docs** (`docs/`): `specs/` (per-milestone design specs),
(per-milestone design specs), `plans/` (per-iteration `plans/` (per-iteration implementation plans). Project history
implementation plans). Project history lives in `git log`. lives in `git log`; the forward queue lives in the Gitea issue
backlog (http://192.168.178.103:3000/Brummel/AILang/issues).
- **Tests**: unit tests per crate plus E2E in `crates/ail/tests/e2e.rs`. Every - **Tests**: unit tests per crate plus E2E in `crates/ail/tests/e2e.rs`. Every
new compiler path needs a test, otherwise the feature does not count as done. new compiler path needs a test, otherwise the feature does not count as done.
+1 -1
View File
@@ -6,7 +6,7 @@ Two things never belong in a contract or model file:
- **Forward intent** (anything stated as planned, intended, or - **Forward intent** (anything stated as planned, intended, or
expected of a future iteration rather than true today) — that expected of a future iteration rather than true today) — that
lives in `docs/roadmap.md`. lives in the Gitea issue backlog.
- **History and rationale** (how a prior draft read, what changed - **History and rationale** (how a prior draft read, what changed
since, why one option was chosen, why another was rejected, what since, why one option was chosen, why another was rejected, what
was dropped in some iteration) — that lives in `git log` (iter was dropped in some iteration) — that lives in `git log` (iter
-1058
View File
File diff suppressed because it is too large Load Diff
+3 -3
View File
@@ -1,6 +1,6 @@
--- ---
name: audit name: audit
description: Use at milestone close OR when baseline drift is suspected. Runs architect drift review against the design/ ledger (spine design/INDEX.md) plus the three regression scripts (bench/check.py, bench/compile_check.py, bench/cross_lang.py). Mandatory at every milestone close; deferral requires an explicit roadmap entry naming the reason and the re-run date. description: Use at milestone close OR when baseline drift is suspected. Runs architect drift review against the design/ ledger (spine design/INDEX.md) plus the three regression scripts (bench/check.py, bench/compile_check.py, bench/cross_lang.py). Mandatory at every milestone close; deferral requires an explicit Gitea backlog issue naming the reason and the re-run date.
--- ---
# audit — milestone-tidy # audit — milestone-tidy
@@ -17,7 +17,7 @@ iteration of a milestone closes and before the next milestone starts.
## When to Use / Skipping ## When to Use / Skipping
**Mandatory** at every milestone close. Skipping requires an explicit **Mandatory** at every milestone close. Skipping requires an explicit
roadmap entry naming: Gitea backlog issue naming:
- the blocking sibling milestone (if any), - the blocking sibling milestone (if any),
- the reason for deferral, - the reason for deferral,
- the date the audit will be re-run. - the date the audit will be re-run.
@@ -129,7 +129,7 @@ self-resolve.
- Bumping baseline without a paired ratify statement in the audit commit body - Bumping baseline without a paired ratify statement in the audit commit body
- Treating exit code 2 as a regression to fix - Treating exit code 2 as a regression to fix
- Closing a milestone with drift items in `pending` state - Closing a milestone with drift items in `pending` state
- "We'll re-run after the holidays" without a dated roadmap entry - "We'll re-run after the holidays" without a dated backlog issue
## Cross-references ## Cross-references
+4 -3
View File
@@ -62,7 +62,7 @@ If `milestone_scope` is empty, return a structural error and stop.
- **Drift against the milestone spec** (if one exists). Does the code match - **Drift against the milestone spec** (if one exists). Does the code match
the spec's *Components* and *Data flow* sections? the spec's *Components* and *Data flow* sections?
- **Growing debt.** Heuristics where the schema is authoritative, - **Growing debt.** Heuristics where the schema is authoritative,
TODO/FIXME without a roadmap entry or named owner, `#[allow(dead_code)]` TODO/FIXME without a backlog issue or named owner, `#[allow(dead_code)]`
spots that will tip over long-term, magic numbers without named spots that will tip over long-term, magic numbers without named
constants in hot paths. constants in hot paths.
- **Consistency across crates.** AST changes that landed in one crate but - **Consistency across crates.** AST changes that landed in one crate but
@@ -93,8 +93,9 @@ If `milestone_scope` is empty, return a structural error and stop.
`design/contracts/honesty-rule.md`: a hit is `design/contracts/honesty-rule.md`: a hit is
drift unless it is a present-tense correctly-labelled drift unless it is a present-tense correctly-labelled
reserved/excluded claim, present-tense design rationale, or a reserved/excluded claim, present-tense design rationale, or a
block-quote commit-body citation. Forward intent is roadmap drift; block-quote commit-body citation. Forward intent belongs in the
document/project history belongs in `git log`, not in `design/`. Gitea backlog; document/project history belongs in `git log`, not
in `design/`.
- **Lockstep invariants across files.** Two known cross-file pairings - **Lockstep invariants across files.** Two known cross-file pairings
must move together; a new arm in one without the matching update in must move together; a new arm in one without the matching update in
the other ships silently broken (B1 in the Floats fieldtest is the the other ships silently broken (B1 in the Floats fieldtest is the
+29 -22
View File
@@ -1,6 +1,6 @@
--- ---
name: boss name: boss
description: User-invoked only (typed as `/boss`). Activates autonomous orchestrator mode — Claude picks the next iteration from `docs/roadmap.md`, dispatches the appropriate skill, and continues until done-state or genuine bounce-back. Outside `/boss`, the default is interactive collaboration with the user, not autonomous queue execution. description: User-invoked only (typed as `/boss`). Activates autonomous orchestrator mode — Claude picks the next iteration from the Gitea issue backlog, dispatches the appropriate skill, and continues until done-state or genuine bounce-back. Outside `/boss`, the default is interactive collaboration with the user, not autonomous queue execution.
--- ---
# boss — autonomous orchestrator mode # boss — autonomous orchestrator mode
@@ -11,14 +11,14 @@ description: User-invoked only (typed as `/boss`). Activates autonomous orchestr
Autonomous orchestrator mode is the way Brummel-as-LLM moves the Autonomous orchestrator mode is the way Brummel-as-LLM moves the
AILang project forward when the user is away. Inside this mode, AILang project forward when the user is away. Inside this mode,
Claude reads `docs/roadmap.md`, picks the top item, dispatches the Claude reads the Gitea issue backlog, picks the top item, dispatches
right skill, integrates the result, and continues to the next item the right skill, integrates the result, and continues to the next
— until the queue is empty (done-state) or a real design fork item — until the queue is empty (done-state) or a real design fork
forces a bounce-back to the user. forces a bounce-back to the user.
Outside this mode, the default is interactive collaboration: the Outside this mode, the default is interactive collaboration: the
user asks; Claude answers or executes the specific request; Claude user asks; Claude answers or executes the specific request; Claude
stops. There is no autonomous picking from the roadmap, no stops. There is no autonomous picking from the backlog, no
multi-iter sequence chained off a single user message. multi-iter sequence chained off a single user message.
This skill exists to make the mode-switch explicit. Without it, This skill exists to make the mode-switch explicit. Without it,
@@ -67,12 +67,16 @@ mode. This skill does not restate them.
### Step 1 — Read the queue ### Step 1 — Read the queue
`docs/roadmap.md` is the priority-ordered forward queue. Read it The Gitea issue backlog is the priority-ordered forward queue.
first. The top item is the candidate for the next dispatch. Browse: http://192.168.178.103:3000/Brummel/AILang/issues. CLI:
`tea issues ls --repo Brummel/AILang --labels prio:p1` walks the
highest-priority bucket first; drop to `prio:p2` / `prio:p3` when
P1 is empty. Read the candidate issue body with `tea issues <N>`.
The top P1 item is the candidate for the next dispatch.
If the queue is empty: skip to Step 5 (done-state). Do not invent If the entire open backlog is empty: skip to Step 5 (done-state).
work; an empty queue is a real signal that the milestone closed Do not invent work; an empty queue is a real signal that the
and there is nothing left. milestone closed and there is nothing left.
### Step 2 — Pick the top item per direction-freedom rules ### Step 2 — Pick the top item per direction-freedom rules
@@ -147,10 +151,11 @@ Bounce back to the user only when:
dependency failure, a discovered invariant violation). dependency failure, a discovered invariant violation).
- The user has explicitly asked for a checkpoint. - The user has explicitly asked for a checkpoint.
- **The next item on the queue is a new milestone** — i.e. a - **The next item on the queue is a new milestone** — i.e. a
roadmap entry that has no `docs/specs/` file yet and would backlog issue (typically `kind:milestone`) that has no
require dispatching `brainstorm` to even begin. Continuing `docs/specs/` file yet and would require dispatching `brainstorm`
an open milestone (next iter, audit, fieldtest, post-audit to even begin. Continuing an open milestone (next iter, audit,
tidy) is autonomous; *starting* a new one is a bounce-back. fieldtest, post-audit tidy) is autonomous; *starting* a new one
is a bounce-back.
**Why this is different from the other three triggers.** Cross- **Why this is different from the other three triggers.** Cross-
milestone work is high-context work. A fresh brainstorm alone milestone work is high-context work. A fresh brainstorm alone
@@ -162,7 +167,7 @@ Bounce back to the user only when:
continuation. A new milestone is therefore the natural continuation. A new milestone is therefore the natural
checkpoint: stop, surface the candidate, let the user pick the checkpoint: stop, surface the candidate, let the user pick the
session shape (continue here / spawn fresh / defer / pick a session shape (continue here / spawn fresh / defer / pick a
different roadmap item). different backlog item).
A summary of what shipped is fine and welcome — but in A summary of what shipped is fine and welcome — but in
autonomous mode, follow it with the next dispatch, not a autonomous mode, follow it with the next dispatch, not a
@@ -174,7 +179,7 @@ Two states call for a notify; nothing else does:
1. **Done-state.** The autonomous queue is empty — the milestone 1. **Done-state.** The autonomous queue is empty — the milestone
closed, the audit ratified, and no further iteration is obvious closed, the audit ratified, and no further iteration is obvious
from the spec or the roadmap (or, in a user-scoped session, from the spec or the backlog (or, in a user-scoped session,
every objective the user named has been completed and there is every objective the user named has been completed and there is
nothing else queued). A finished sub-goal inside a still-open nothing else queued). A finished sub-goal inside a still-open
milestone is *not* done-state. If the next iteration is obvious milestone is *not* done-state. If the next iteration is obvious
@@ -186,7 +191,7 @@ Two states call for a notify; nothing else does:
freedom" — design fork I cannot resolve, an unexpected freedom" — design fork I cannot resolve, an unexpected
invariant violation, an external dependency failure, the invariant violation, an external dependency failure, the
user has explicitly asked for a checkpoint, or the next user has explicitly asked for a checkpoint, or the next
roadmap item is a new milestone (no spec yet) and starting backlog item is a new milestone (no spec yet) and starting
it would force a fresh `brainstorm`. it would force a fresh `brainstorm`.
A user-specified stop trigger ("until X is done, then notify") A user-specified stop trigger ("until X is done, then notify")
@@ -244,10 +249,10 @@ actionable ask, not a wrap-up summary.
|--------|---------| |--------|---------|
| "Iter just landed cleanly, let me notify so user can see" | Mid-flow notifications burn user attention without giving them a decision to make. Iter-clean is internal progress, not a notify event. | | "Iter just landed cleanly, let me notify so user can see" | Mid-flow notifications burn user attention without giving them a decision to make. Iter-clean is internal progress, not a notify event. |
| "Sub-goal of the milestone is done, that counts as done-state" | Done-state is queue-empty, not sub-goal-complete. If the next iter is obvious and substantive, keep dispatching. | | "Sub-goal of the milestone is done, that counts as done-state" | Done-state is queue-empty, not sub-goal-complete. If the next iter is obvious and substantive, keep dispatching. |
| "Top of roadmap has two equally good options, I'll just pick one" | If both are substantive and the choice is non-obvious, that's a real fork — bounce back. The cost of a wrong pick (working-tree discard) is higher than the cost of one short ping to the user. | | "Top of the backlog has two equally good options, I'll just pick one" | If both are substantive and the choice is non-obvious, that's a real fork — bounce back. The cost of a wrong pick (working-tree discard) is higher than the cost of one short ping to the user. |
| "User said 'until X then notify', X just completed, notify now" | Check whether X was actually the last actionable thing. If hitting X leaves an open milestone with obvious follow-up, the user's intent was "wake me when there's nothing else to do" — continue. | | "User said 'until X then notify', X just completed, notify now" | Check whether X was actually the last actionable thing. If hitting X leaves an open milestone with obvious follow-up, the user's intent was "wake me when there's nothing else to do" — continue. |
| "Notify can name the iter code — user will figure out what it means" | No. The notify text is for the user-as-reader who did not watch me work. Iter codes, crate names, function identifiers, type names — all internal, all banned. | | "Notify can name the iter code — user will figure out what it means" | No. The notify text is for the user-as-reader who did not watch me work. Iter codes, crate names, function identifiers, type names — all internal, all banned. |
| "The previous milestone closed cleanly and the next roadmap item is obvious — just dispatch `brainstorm` and keep going" | No. Starting a new milestone is itself a bounce-back. A fresh `brainstorm` is high-context work, and I cannot compact my own context — only the user can decide whether the next milestone wants a fresh session or a continuation of this one. The "obviousness" of the candidate is irrelevant; the *cross-milestone hop* is the checkpoint, not the topic choice. | | "The previous milestone closed cleanly and the next backlog item is obvious — just dispatch `brainstorm` and keep going" | No. Starting a new milestone is itself a bounce-back. A fresh `brainstorm` is high-context work, and I cannot compact my own context — only the user can decide whether the next milestone wants a fresh session or a continuation of this one. The "obviousness" of the candidate is irrelevant; the *cross-milestone hop* is the checkpoint, not the topic choice. |
| "It's the same broad area as the milestone I just closed, that's not really a new milestone" | If there is no `docs/specs/<...>.md` file for it yet and it would route through `brainstorm` to get one, it IS a new milestone for this rule's purposes. The rule keys on "needs a fresh spec", not on subjective continuity. | | "It's the same broad area as the milestone I just closed, that's not really a new milestone" | If there is no `docs/specs/<...>.md` file for it yet and it would route through `brainstorm` to get one, it IS a new milestone for this rule's purposes. The rule keys on "needs a fresh spec", not on subjective continuity. |
## Red Flags — STOP ## Red Flags — STOP
@@ -257,7 +262,7 @@ actionable ask, not a wrap-up summary.
- About to autonomously dispatch in a session where the user did NOT type `/boss`. - About to autonomously dispatch in a session where the user did NOT type `/boss`.
- About to send a notify that names a crate, an iter code, or an agent. - About to send a notify that names a crate, an iter code, or an agent.
- About to bounce back at every iter boundary "just to be safe" — that's reactive deference, not direction freedom. - About to bounce back at every iter boundary "just to be safe" — that's reactive deference, not direction freedom.
- About to dispatch `brainstorm` on a roadmap item that does not yet have a spec file, without first bouncing back to the user. New milestones never start autonomously. - About to dispatch `brainstorm` on a backlog issue that does not yet have a spec file, without first bouncing back to the user. New milestones never start autonomously.
## Cross-references ## Cross-references
@@ -266,8 +271,10 @@ actionable ask, not a wrap-up summary.
- **Universal rules:** `CLAUDE.md` — agent role boundaries, commit - **Universal rules:** `CLAUDE.md` — agent role boundaries, commit
discipline, design rationale, authority over skills, feature discipline, design rationale, authority over skills, feature
acceptance, TDD-for-bugs, file-role roster. acceptance, TDD-for-bugs, file-role roster.
- **Queue:** `docs/roadmap.md` — priority-ordered forward queue - **Queue:** Gitea issues — priority-ordered forward queue
consumed by Step 1. consumed by Step 1. Browse:
http://192.168.178.103:3000/Brummel/AILang/issues; CLI: `tea
issues ls --repo Brummel/AILang --labels prio:p1`.
- **Canonical feature-acceptance criterion:** - **Canonical feature-acceptance criterion:**
`design/contracts/feature-acceptance.md` — the criterion that gates `design/contracts/feature-acceptance.md` — the criterion that gates
new features; applied at spec time by `skills/brainstorm`. new features; applied at spec time by `skills/brainstorm`.
+14 -11
View File
@@ -242,19 +242,22 @@ interpretation:
1. Delete the just-written spec file from the working tree 1. Delete the just-written spec file from the working tree
(`rm docs/specs/<spec_filename>.md` — a Bash-level delete on the (`rm docs/specs/<spec_filename>.md` — a Bash-level delete on the
working tree, NOT `git rm`; the file was never committed). working tree, NOT `git rm`; the file was never committed).
2. Append a roadmap entry to `docs/roadmap.md` pointing forward to a 2. Open a Gitea backlog issue pointing forward to a future
future re-brainstorm, under the appropriate priority bucket: re-brainstorm, under the appropriate priority bucket:
```markdown ```bash
- [ ] **[<kind>]** <idea title> — <one-line description> tea issues create --repo Brummel/AILang \
- context: <why this is deferred> --title "<idea title>" \
- depends on: <name of the unratified mechanism> --labels "kind:<milestone|feature|todo|idea>,prio:p2" \
--description "<one-line description>
**context:** <why this is deferred>
**depends on:** <name of the unratified mechanism>"
``` ```
3. Tell the user the spec was retired and which roadmap entry was 3. Tell the user the spec was retired and which Gitea issue was
added. The user / Boss commits the roadmap edit (suggested filed (include the issue number). No commit is needed for the
commit subject: `spec: retire <spec topic> — depends on backlog entry — Gitea is the live store.
<unratified mechanism>`).
After the failure-mode procedure runs, the brainstorm session ENDS. After the failure-mode procedure runs, the brainstorm session ENDS.
There is no Step 8, no Step 9. The idea is parked until the There is no Step 8, no Step 9. The idea is parked until the
@@ -305,7 +308,7 @@ Hand off carries:
| user → `brainstorm` | new milestone request | | user → `brainstorm` | new milestone request |
| `brainstorm` → `ailang-grounding-check` (Step 7.5) | `spec_path` + `iteration_scope` | | `brainstorm` → `ailang-grounding-check` (Step 7.5) | `spec_path` + `iteration_scope` |
| `brainstorm` → `planner` (Step 9, on PASS or overridden BLOCK) | path to spec + iteration scope | | `brainstorm` → `planner` (Step 9, on PASS or overridden BLOCK) | path to spec + iteration scope |
| `brainstorm` → roadmap (Step 7.5, on no-override BLOCK) | `depends on:` entry added to `docs/roadmap.md` in the working tree, spec file deleted from the working tree; Boss commits the roadmap edit | | `brainstorm` → Gitea backlog (Step 7.5, on no-override BLOCK) | new issue opened via `tea issues create` naming the unratified dependency; spec file deleted from the working tree (no commit needed) |
## Common Rationalisations ## Common Rationalisations
+2 -2
View File
@@ -26,7 +26,7 @@ Trigger conditions are any of:
- `cargo doc --no-deps 2>&1` shows accumulated warnings across - `cargo doc --no-deps 2>&1` shows accumulated warnings across
multiple crates after a stability window of several milestones. multiple crates after a stability window of several milestones.
- A roadmap entry like "Rustdoc warning sweep" has matured — the - A backlog issue like "Rustdoc warning sweep" has matured — the
surface it targets has not moved for a while. surface it targets has not moved for a while.
- Onboarding-readability check: navigating `cargo doc --open` for a - Onboarding-readability check: navigating `cargo doc --open` for a
crate is not self-supporting without the design/ ledger. crate is not self-supporting without the design/ ledger.
@@ -86,4 +86,4 @@ iteration; `docwriter` does not self-resolve.
Fieldtest can surface bugs or architecture problems that would Fieldtest can surface bugs or architecture problems that would
invalidate the doc work. invalidate the doc work.
- **Hand-off target:** orchestrator (me). Findings flow into the - **Hand-off target:** orchestrator (me). Findings flow into the
roadmap as candidates for a follow-up tidy iteration. Gitea backlog as candidates for a follow-up tidy iteration.
+1 -1
View File
@@ -89,7 +89,7 @@ YOU NEVER COMMIT. RUSTDOC EDITS LIVE IN THE WORKING TREE; THE BOSS COMMITS.
confusing it needs renaming, raise it in your report instead of changing confusing it needs renaming, raise it in your report instead of changing
it. it.
- No new `pub` exports. Visibility stays as-is. - No new `pub` exports. Visibility stays as-is.
- No edits in `docs/` or `design/`. The orchestrator owns the design/ ledger and the roadmap. - No edits in `docs/` or `design/`. The orchestrator owns the design/ ledger and the Gitea backlog.
- Don't paper over broken behaviour with prose — if doc-writing surfaces - Don't paper over broken behaviour with prose — if doc-writing surfaces
a real bug (a function whose doc you cannot honestly write because it a real bug (a function whose doc you cannot honestly write because it
doesn't actually do what it claims), stop and report it. doesn't actually do what it claims), stop and report it.
+1 -1
View File
@@ -58,7 +58,7 @@ routing table below applies in all cases.
**Skipping is not permitted** for: **Skipping is not permitted** for:
- A milestone that introduced or changed surface syntax, schema, - A milestone that introduced or changed surface syntax, schema,
effects, types, modes, or any user-visible diagnostic. effects, types, modes, or any user-visible diagnostic.
- A milestone whose commit body or roadmap entry claims "LLM author - A milestone whose commit body or backlog issue claims "LLM author
can now write X". `fieldtest` is the gate that empirically can now write X". `fieldtest` is the gate that empirically
substantiates such claims; an unverified claim is drift. substantiates such claims; an unverified claim is drift.