feat: Add a "Loop states" section showing the label state machine on the (#84)

[baderdean]

Issue #84 — iteration 1/5

Screenshots (screenshot review mode)

📱 Mobile (390x844)

🖥️ Desktop (1440x900)

What changed

• feat: add loop-states section showing the label state machine (Add a "Loop states" section showing the label state machine on the landing page #84) [skip ci]

Approach

• Content model — added a loopStates folder collection (one .md per state) and a loopStatesHeader single-file collection, registered in src/content.config.ts. Schema { order, label, description, type, typeLabel } with type ∈ autonomous|human|terminal. All copy is CMS-editable (acceptance criterion 5), mirroring the existing why/cards split.
• Nine states in order — triage, spec-review, todo, working, review, approval, merging, done, human (state-1..state-9 files). spec-review + approval are human (gold), the rest autonomous (cyan), done + human terminal (muted/strikethrough).
• Section & layout — new <section class="loop"> between how-it-works and why-boucle in index.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).
• Escalation branch — boucle:human is 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.
• Colour discipline — autonomous = --accent-cyan chip, human = --accent gold chip, terminal = --text-secondary chip, nodes on --surface-raised. No new colours, no hardcoded hex/rgba in the section CSS. No animation (non-goal).
• Accessibility — semantic aria-label section + ordered list, each chip carries a visible typeLabel (colour is never the only signal), legend aria-hidden.
• CMS + docs — added loopStates + loopStatesHeader collections to public/admin/config.yml; added a Loop states component spec to DESIGN.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.

---

Closes #84 | 1 commit(s) | boucle worker run 1/5 | mode: deploy=self review=preview

[baderdean]

VERDICT: PASS

• 🔴 loop-states content collection with schema, one entry per state, registered in content.config.ts — verified: loopStates collection (order/label/description/type/typeLabel) + loopStatesHeader single-file collection, both registered in collections; 9 state files + header present in diff.
• 🔴 Section renders all nine states in order, autonomous/human/terminal distinction visible without reading text — verified in built HTML: all 9 labels present; 5 loop-node--autonomous (cyan), 2 loop-node--human (gold), 2 loop-node--terminal (muted, incl. escalation). Colour + visible typeLabel text both signal the distinction.
• 🔴 At 390px legible with no horizontal page scroll — verified: mobile-first single column (grid-template-columns: 1fr, max-width 720px), connector rail down left edge; no overflow at 390px.
• 🔴 At 1440px progression reads left-to-right without crowding — verified: ≥1024px 4-column grid (max-width 1040px), reading left-to-right top-to-bottom; escalation branch centred beneath.
• 🔴 Editable from public/admin/config.yml — verified: loopStates (folder collection, create:true) + loopStatesHeader (file collection) added to config.yml.
• 🔴 npm run build passes — verified: npm run build on PR branch (9ae2cda) exits 0, 1 page built.
• 🔴 Content fidelity — verified: all 9 labels (boucle:triage…boucle:human) preserved verbatim; autonomous/human/terminal types match the spec table exactly; one-line descriptions present; no placeholders/rewrites.
• 🔴 Non-goals respected — verified: no <a> links in loop section (chips not linked); no animation/transition/@Keyframes in loop CSS (only a comment noting the non-goal); no README/docs product documentation of the states (DESIGN.md update is the design-system doc, required by doc self-maintenance).
• 🔴 Section placement — verified: loop-states sits between how-it-works and why-boucle (i.e. between how-it-works and quick-start) in index.astro.
• 🔴 Escalation branch — verified: boucle:human pulled out of the numbered sequence into a .loop-branch block with join notch + "Escalation branch" tag, terminal treatment preserved; survives collapse to vertical.
• 🟡 DESIGN.md updated with a "Loop states" design-system section (tokens, layout, motion=none, accessibility) — consistent with the code and the doc self-maintenance mandate.

Diff review mode: no preview URL was available, so criteria were graded against the PR diff and a fresh build of the PR branch (head 9ae2cda). All acceptance criteria pass.

---

✅ Ready to merge. The PR has been assigned to you for approval. To approve and merge, reply approved on PR #85. The merger will then rebase the PR onto main and merge it serially (avoiding conflicts with other approved PRs).

Reply approved on this PR to approve and merge.