# Story: Architectural Rule Amendment — Dynamic Blocks Exception for Actualité

## 1. Contexte (Context)

This is a **documentation-only story** — no application code changes, low risk, fast to review — and should be prioritized **first** among all seven Actualité stories because it unblocks two others.

This project's architecture rule, `spec-driven-development/rules/section-component-architecture.md`, currently mandates (line 34) **"Admin cannot add/remove/reorder sections (template-defined)"** and lists as an anti-pattern (line 1559) **"Don't allow dynamic sections - Template defines fixed section structure."** The new Actualité (news article) template breaks this assumption by design: per the finalized spec's Decision #4 (`spec-driven-development/2026-07-07-actualite-news-page-template.md`), admin-driven add/remove/reorder of text/text-image content blocks is a **core requirement** for a news/blog-style template — unlike the fixed-slot templates (Home, About, Contact) the rule was originally written for, where sections are fixed at template-definition time.

Rather than silently violating this documented rule or bypassing it ad hoc in code, this story formally amends the rule document to carve out a **named, documented exception** with clear rationale, before any dynamic-block code is written. This is a deliberate sequencing decision: **Story "Actualité DTO/Model + CreationService + TemplateMatcher registration"** (whose `ActualitePageContentDto.blocks` is exactly this kind of repeatable, admin-mutable content) and **Story "Inline editor: dynamic block add/remove/reorder UI"** (the concrete implementation of the exception) should **not begin until this rule amendment is reviewed and merged** — both stories build on an architectural decision that must be documented first, not retrofitted afterward. Landing this story does not itself implement anything functional; it exists purely to make the exception explicit, reviewable, and citable so downstream implementation work has a documented basis.

## 2. Le besoin (User Story)

```
En tant que développeur travaillant sur ce projet (présent ou futur)
Je souhaite que l'exception aux sections dynamiques pour le template Actualité soit documentée explicitement dans la règle d'architecture existante
Afin de comprendre pourquoi ce template déroge à la règle générale, et de disposer d'un pattern réutilisable si un futur template a le même besoin (blocs répétables gérés par l'admin)
```

## 3. Liens utiles (Useful Links)

- **Fichier à amender**: `spec-driven-development/rules/section-component-architecture.md` (règle actuelle aux lignes 34 et 1559)
- **Spec source**: `spec-driven-development/2026-07-07-actualite-news-page-template.md`, section "Architectural Rule Amendment — Dynamic Blocks Exception (Decision #4)" (contient déjà la rédaction de référence pour cette story)
- **Code existant illustrant le pattern "repeatable, type-discriminated block"** (structure similaire déjà présente, mais sans UI d'ajout/suppression/réordonnancement admin) :
  - `src/Page/List/Dto/ListPageSectionDto.php`
  - `src/Page/About/Dto/AboutPageSectionDto.php`
  - Templates associés (`list.html.twig`, `contact.html.twig`) qui rendent les sections de façon uniforme, sans brancher sur `section.type`
- **Stories bloquées par celle-ci** (à ne démarrer qu'après merge) :
  - Story "Actualité DTO/Model + CreationService + TemplateMatcher registration" (fichier `stories/actualite-dto-model-creation-service.md`)
  - Story "Inline editor: dynamic block add/remove/reorder UI" (fichier `stories/actualite-inline-editor-dynamic-blocks.md`)

## 4. Critères d'acceptation (Acceptance Criteria)

### Scénario 1: Ajout d'une exception documentée près de la règle "Admin cannot add/remove/reorder sections"
```gherkin
Scénario: La règle ligne 34 est accompagnée d'une exception nommée
  Étant donné que `section-component-architecture.md` contient la règle "❌ Admin cannot add/remove/reorder sections (template-defined)"
  Quand j'amende le document
  Alors une sous-section "Repeatable Block Templates" (ou équivalent) est ajoutée à proximité immédiate de cette règle
  Et cette sous-section nomme explicitement "Actualité" comme premier template bénéficiant de cette exception
  Et elle explique le "pourquoi" : les templates de type actualité/blog nécessitent un ajout/suppression/réordonnancement de blocs piloté par l'admin, contrairement aux templates à emplacements fixes (Home, About, Contact) pour lesquels la règle initiale a été écrite
```

### Scénario 2: Amendement de l'anti-pattern "Don't allow dynamic sections"
```gherkin
Scénario: L'anti-pattern ligne 1559 référence l'exception
  Étant donné que la section "DON'T ❌" liste "Don't allow dynamic sections - Template defines fixed section structure"
  Quand j'amende le document
  Alors cette entrée est mise à jour pour renvoyer vers la nouvelle sous-section d'exception ("sauf pour les templates listés dans Repeatable Block Templates, voir section X")
  Et aucune autre règle du document n'est modifiée sans rapport avec cette exception
```

### Scénario 3: Documentation des conventions d'attributs pour les blocs dynamiques
```gherkin
Scénario: Les conventions data-section/data-field pour blocs dynamiques sont documentées
  Étant donné qu'Actualité est le premier template à nécessiter des blocs éditables ajoutés/retirés côté client
  Quand j'amende le document
  Alors la nouvelle sous-section documente la convention d'identifiant stable (UUID généré côté client, ex. `crypto.randomUUID()`, plutôt qu'un index positionnel) pour l'attribut `data-section`/`id` de chaque bloc
  Et elle documente le discriminateur de type (`data-section-type` ou équivalent) utilisé pour distinguer les types de blocs (texte, texte+image gauche, texte+image droite)
  Et elle précise que les futurs templates ayant un besoin similaire de contenu répétable éditable par l'admin doivent réutiliser ce pattern plutôt que d'en inventer un nouveau
```

### Scénario 4: Traçabilité vers la spec Actualité
```gherkin
Scénario: L'amendement référence la spec source
  Étant donné que cette exception découle d'une décision prise dans la spec Actualité
  Quand j'amende le document
  Alors la nouvelle sous-section contient un renvoi explicite (chemin de fichier) vers `spec-driven-development/2026-07-07-actualite-news-page-template.md`
  Et la date de dernière mise à jour du document ("Last Updated" en en-tête) est actualisée
```

### Scénario 5: Aucune régression sur le reste du document
```gherkin
Scénario: Le reste de la règle d'architecture reste inchangé
  Étant donné que ce document régit également Home, About, List, Contact, ProjectDetail, ComingSoon
  Quand la revue de la pull request est effectuée
  Alors aucune règle applicable aux templates à emplacements fixes n'est modifiée ou affaiblie par cette exception
  Et le diff de la pull request ne contient que des ajouts/clarifications localisés (pas de réécriture globale du fichier)
```