Repository navigation
Add a "Loop states" section showing the label state machine on the landing page #84
Description
Context
The landing page explains boucle in prose (why-boucle, how-it-works, the 7 steps) but never shows the thing that makes it deterministic: the label state machine. A visitor reading "deterministic, therefore reliable" has to take it on faith. The states are the product's most concrete differentiator and they are currently invisible.
What to add
A new section between how-it-works and quick-start rendering the loop's states as a progression, driven by a new src/content/loop-states/ collection (one file per state) so the copy stays editable from public/admin like every other section.
Each state needs a label chip, a one-line description of what boucle is doing in it, and a marker for whether it is an autonomous state or one where a human decides.
The states to cover, in order:
| Label | Autonomous? |
|---|---|
boucle:triage |
autonomous |
boucle:spec-review |
human decides |
boucle:todo |
autonomous |
boucle:working |
autonomous |
boucle:review |
autonomous |
boucle:approval |
human decides |
boucle:merging |
autonomous |
boucle:done |
terminal |
boucle:human |
escalation (terminal) |
The two terminal states should read as terminal — they are exits from the loop, not steps in it.
Layout
This is the part that needs design judgement, and the reason a mockup matters:
- Desktop (≥1024px): a horizontal progression. Nine states will not fit on one row legibly, so it needs to wrap or scroll in a way that keeps the reading order obvious. The two "human decides" states must be visually distinct from the autonomous ones — that contrast is the section's whole point.
- Mobile (<768px): the horizontal progression cannot survive at 390px. It should become a vertical list with the connector running down the left edge.
- The escalation state (
boucle:human) branches off the main path rather than sitting in sequence; that branching needs to survive the collapse to vertical.
Use the existing tokens from DESIGN.md — --accent gold for the human-decision states, --accent-cyan for autonomous, --surface-raised for the chips. No new colours.
Non-goals
- No animation or scroll-triggered reveal.
- Not adding these states to the README or docs — landing page only.
- Not making the chips link anywhere.
Acceptance criteria
- New
loop-statescontent collection with a schema, one entry per state, registered insrc/content.config.ts. - The section renders all nine states in order, with the autonomous/human/terminal distinction visible without reading the text.
- At 390px wide the section is legible with no horizontal page scroll.
- At 1440px the progression reads left-to-right without crowding.
- Editable from
public/admin/config.ymllike the other collections. npm run buildpasses.
Activity
baderdean commentedon Aug 26, 2026
TL;DR
Add a new "loop states" section to the landing page that visualizes boucle's nine label states as a progression. Autonomous states use cyan, human-decision states use gold, terminal states read as exits. Content is driven by a new
loop-statescollection so it stays editable from the CMS. Desktop shows a horizontal progression; mobile collapses to a vertical list with the escalation state branching off.Preview
📱 Mobile (390x844)
🖥️ Desktop (1440x900)
Analysis
The landing page explains boucle in prose and a 7-step slideshow but never shows the label state machine — the product's most concrete differentiator. A visitor reading "deterministic, therefore reliable" has to take it on faith. This issue asks to make the states visible as a rendered progression between
how-it-worksandquick-start.User segment — Product Builders evaluating boucle.dev who want to understand how the loop is deterministic, not just be told it is.
Pain points — The states are the product's most concrete differentiator and they are currently invisible. Visitors cannot see where humans intervene vs where boucle acts alone. The 7-step slideshow is narrative; the state machine is structural.
Business context — "Deterministic and reliable" is key message #2. Showing the state machine converts the claim from marketing copy into something verifiable at a glance. The autonomous/human contrast is the section's whole point.
Success metrics — A visitor can identify the two human-decision points and the two terminal exits without reading the descriptions, by colour alone.
Docs impact:
DESIGN.md(new component spec for the loop-states section),src/content.config.ts(new collection schema),public/admin/config.yml(new CMS collection).Draft acceptance criteria
how-it-worksandquick-start, Then all nine states render in order with a label chip, a one-line description, and a type marker (autonomous / human / terminal / escalation)boucle:humanstate, When rendered in either layout, Then it branches off the main path (not in sequence with the other eight) and the branching is visually clearloop-statescollection, When the Astro build runs, Then one entry per state is loaded fromsrc/content/loop-states/with a schema (order, label, description, type) registered insrc/content.config.tspublic/admin/config.yml, When an editor opens the CMS, Then theloop-statescollection appears with fields matching the schema, editable like the other collectionsnpm run buildruns, Then the build succeeds with no errors--accentgold for human,--accent-cyanfor autonomous,--surface-raisedfor chips,--text-secondaryfor terminal)Must-haves
src/content/loop-states/*.md(9 files, one per state),src/content.config.ts(newloopStatescollection in the schema and exports),public/admin/config.yml(new collection entry),src/pages/index.astro(new section HTML + CSS between how-it-works and quick-start)how-it-workssection and thewhy-bouclesection (which precedesquick-start); theloopStatescollection is registered insrc/content.config.tsand exported incollections; the CMS collection inpublic/admin/config.ymlmirrors the schema fieldsNon-goals
how-it-worksslideshow orwhy-bouclecardsImpacts
🏗️ ui, data-model
Diagram
The state machine the section visualizes — autonomous states (cyan), human-decision states (gold), and the escalation branch:
%%{init: {"theme":"base","themeVariables":{"background":"transparent","primaryColor":"#f5c842","primaryTextColor":"#0d1117","primaryBorderColor":"#c9a233","lineColor":"#a0a0b8","secondaryColor":"#fdf3d7","tertiaryColor":"#e8e6f5","clusterBkg":"#faf7f2","clusterBorder":"#c9a233","edgeLabelBackground":"#ffffff","fontFamily":"Sora, system-ui, sans-serif","fontSize":"14px"}}}%% stateDiagram-v2 [*] --> triage triage --> spec_review spec_review --> todo todo --> working working --> review review --> approval approval --> merging merging --> done done --> [*] working --> human : escalates review --> human : escalates human --> [*]Impacted files
📁
src/content.config.ts,src/content/loop-states/,src/pages/index.astro,public/admin/config.yml,DESIGN.mdClassification
Size: M
Validation: author-required
Questions
none
Disposition
READY
Validation
Review the TL;DR above.
approved(just that word, on its own line) to approve the spec — nothing else approves it.boucle:approvedlabel to this issue to approve the spec.baderdean commentedon Aug 26, 2026
approved
baderdean commentedon Aug 26, 2026
📦 File-impact claim:
DESIGN.md,public/admin/config.yml,src/content.config.ts,src/content/loop-states-header/loop-states-header.md,src/content/loop-states/state-1-triage.md,src/content/loop-states/state-2-spec-review.md,src/content/loop-states/state-3-todo.md,src/content/loop-states/state-4-working.md,src/content/loop-states/state-5-review.md,src/content/loop-states/state-6-approval.md,src/content/loop-states/state-7-merging.md,src/content/loop-states/state-8-done.md,src/content/loop-states/state-9-human.md,src/pages/index.astrobaderdean commentedon Aug 26, 2026
➰ boucle — loop state (machine-written, safe to ignore)
Approach
loopStatesfolder collection (one.mdper state) and aloopStatesHeadersingle-file collection, registered insrc/content.config.ts. Schema{ order, label, description, type, typeLabel }withtype ∈ autonomous|human|terminal. All copy is CMS-editable (acceptance criterion 5), mirroring the existing why/cards split.<section class="loop">between how-it-works and why-boucle inindex.astro. Desktop ≥1024px: 4-column grid, left-to-right reading order; 768–1024px: 2 columns; <768px: single column with a connector rail down the left edge (no horizontal scroll at 390px). Conforms to DESIGN §2 (tokens), §3 (no motion), §4 (components).boucle:humanis pulled out of the numbered<ol>into its own branch block beneath the sequence, with a visible join notch + "Escalation branch" tag, keeping the terminal (struck-through) treatment so it reads as an exit. Branch conveyed purely by layout, not a new colour.--accent-cyanchip, human =--accentgold chip, terminal =--text-secondarychip, nodes on--surface-raised. No new colours, no hardcoded hex/rgba in the section CSS. No animation (non-goal).aria-labelsection + ordered list, each chip carries a visibletypeLabel(colour is never the only signal), legendaria-hidden.loopStates+loopStatesHeadercollections topublic/admin/config.yml; added a Loop states component spec toDESIGN.md(Docs impact per triage).Scope Self-Check
Task as stated: add a loop-states section (collection, schema, render, CMS, responsive, no animation, no new colour) between how-it-works and why-boucle.
Files I touched: 9
src/content/loop-states/*.md,loop-states-header.md,src/content.config.ts,src/pages/index.astro,public/admin/config.yml,DESIGN.md.Lines I'm tempted to add but won't: none — no animation JS, no chip links, no README/docs additions.
Abstractions considered and rejected: a single header+state union collection (over-engineered vs the existing split); a per-node arrow/grid connector (fragile).
Diff size: ~440 insertions.
Could it be smaller? No — nine states, responsive layout, and CMS wiring are all required by the spec.
Tried and rejected
(none yet)
Awaiting human
nothing
Merge pull request #85 from ankaboot-source/boucle/84-add-a-loop-stat…
baderdean commentedon Oct 17, 2026
VERDICT: FAIL
loop-statescontent collection with a schema, one entry per state, registered insrc/content.config.ts— verified in source:loopStatesfolder collection (9 entries, schema: order/label/description/type/typeLabel, type enum autonomous|human|terminal) +loopStatesHeader; schema validated by a freshnpm run build.public/admin/config.ymllike the other collections —loopStatesHeader(file collection) andloopStates(folder collection, create: true) both registered.npm run buildpasses — fresh run after cleannpm install: build complete, exit 0, 1 page built./* ============ LOOP STATES ============ */(src/pages/index.astro ~line 1828 — AFTER the closing</style>at line 1589, outside any tag), ships to production as visible text betweenhow-it-worksand the loop section. curl shows</section>/* ============ LOOP STATES ============ */<section class="loop"and screenshots at 390px and 1440px showTES ============== */rendered as page text at the top of the section. Fix: delete the stray comment line in the markup (the one at ~line 1041 inside the style block is fine and can stay)..loop*block; nothing animated to verify on the live page.metrics: raw health for issue #84
metrics: raw health for issue #84
baderdean commentedon Oct 17, 2026
E2E verification FAILED. A follow-up issue #112 has been opened in triage to fix the defect.
Live URL
https://ankaboot-source.github.io/boucle.dev/
E2E trace
Closing this issue — work continues in #112.
metrics: issue #84 (done)