Convention du `CHANGELOG.md`¶

Cette page documente les règles d'écriture du fichier CHANGELOG.md à la racine du dépôt. Pour la consultation du changelog lui-même, voir la page Changelog.

Versionnement : par tag de release¶

Tant qu'aucune version 1.0.0 n'a été publiée, les évolutions sont versionnées par tag de release. Chaque tag Git YYYYMMDDHHMM (cf. Créer un tag de release) donne une section dans le CHANGELOG.md, dont le titre reprend le nom du tag et sa date :

## [202606220820] — 2026-06-22

Cette section est alimentée automatiquement par le skill /creer-tag, à partir des commits accumulés depuis le tag précédent. La génération est déterministe (aucune rédaction par un LLM) : elle s'appuie sur la cible castor changelog:prepare, qui classe les sujets de commits par rubrique selon leur préfixe Conventional Commits. Voir Créer un tag de release.

Anciennes sections 0.X.0 figées

Les sections au format 0.X.0 correspondent à l'ancien découpage par étape de cadrage (0.X.0 = clôture de l'étape X). Elles restent figées telles quelles : on ne réécrit pas l'historique, seules les nouvelles sections suivent le format YYYYMMDDHHMM.

Correspondance préfixe → rubrique¶

changelog:prepare (via la classe App\Castor\Changelog\ChangelogGenerator dans castor/src/Changelog/ChangelogGenerator.php) classe chaque commit dans une rubrique d'après son préfixe conventionnel :

Préfixe(s) Conventional Commits	Rubrique
`feat`	Ajouté
`fix`	Corrigé
`perf`, `refactor`	Modifié
`docs`	Documentation
`ci`, `build`, `chore`, `test`, `style`	Outillage & CI
(préfixe absent ou non reconnu)	Divers

Les rubriques sont rendues dans cet ordre fixe, la rubrique de repli Divers en dernier ; seules les rubriques non vides apparaissent. Chaque puce reprend le sujet du commit débarrassé de son préfixe type(scope):, première lettre capitalisée.

Source de vérité et pipeline d'inclusion¶

Le changelog vit dans CHANGELOG.md à la racine du dépôt — c'est la seule version maintenue. La page docs/changelog.md se contente de l'inclure via la directive pymdownx.snippets :

<!--
  Convention d'écriture de ce fichier : docs/reference/changelog.md
  (page publiée : https://docs.kirexo.fr/reference/changelog/).

  Règle critique : PAS DE LIENS MARKDOWN RELATIFS. Ce fichier est inclus
  dans docs/changelog.md via `--8<-- "CHANGELOG.md"` (pymdownx.snippets) ;
  mkdocs résout alors les liens relatifs depuis docs/changelog.md, donc
  un lien `docs/reference/foo.md` devient `docs/docs/reference/foo.md`
  → warning → strict mode → build cassé → conteneur docs en exit 1.

  À la place, utiliser une URL absolue :
    - GitLab (préféré, fonctionne aussi en lecture brute sur GitLab) :
      https://gitlab.com/shaurifr/kirexo/-/blob/main/docs/reference/foo.md
    - Doc publiée :
      https://docs.kirexo.fr/reference/foo/
-->

# Changelog

Toutes les évolutions notables du projet Kirexo sont consignées ici.

Le format suit [Keep a Changelog](https://keepachangelog.com/fr/1.1.0/) et le projet adhère, autant que possible, au [Versionnement Sémantique](https://semver.org/lang/fr/).

Tant qu'aucune version `1.0.0` n'a été publiée, les évolutions sont **versionnées par tag de release** : chaque tag Git `YYYYMMDDHHMM` (cf. [Créer un tag de release](https://gitlab.com/shaurifr/kirexo/-/blob/main/docs/how-to/creer-un-tag-de-release.md)) donne une section, alimentée automatiquement par le skill `/creer-tag` à partir des commits depuis le tag précédent. Les sections antérieures au format `0.X.0` correspondent à l'ancien découpage par étape de cadrage (`0.X.0` = clôture de l'étape *X*) et restent figées telles quelles.

## [202607210830] — 2026-07-21

### Ajouté

- Étape 8 - lot 8 — header, retour Réglages, KPI filtrants
- Étape 8 - lot 7 — refond le dashboard en cockpit de conformité
- Étape 8 - lot 5 — aligne les écrans admin sur le DS et clarifie la conformité
- Étape 8 - lot 3 — fluidifie la navigation home app, /u et éditeur
- Étape 8 - lot 2 — unifie le menu utilisateur en disclosure sur les 3 espaces

### Corrigé

- Migre les règles de permission Write() vers Edit()
- Étape 8 - lot 6 — rend la déconnexion globale aux deux firewalls
- Étape 8 - lot 4 — rattache le nouvel article au carnet source
- Retire le plugin PHP bundlé de la liste JetBrains

### Documentation

- Journalise la clôture et versionne le cadrage
- Étape 8 - lot 1 — pose les patterns UI industrie et leur chargement

### Divers

- Ticket #5 — Monte Claude Code 2.1.211 → 2.1.216 (devcontainer)
- Ticket #5 — Consigne le bilan de clôture (apprentissage.md)
- Ticket #5 - lot 5 — Documente la migration Alpine (Diátaxis)
- Ticket #5 - lot 4 — Constate le gain CVE Alpine et allowliste le résiduel
- Ticket #5 - lot 3 — Migre le stage prod sur Alpine et durcit les CVE
- Ticket #5 - lot 2 — Migre le stage dev du devcontainer sur Alpine
- Ticket #5 - lot 1 — Migre l'image base FrankenPHP sur Alpine
- Ticket #100 — Journalise le bilan de clôture (apprentissage.md)
- Ticket #100 - lot 4 — Documente comment garder son devcontainer à jour
- Ticket #100 - lot 3 — Ajoute la cible castor devcontainer:refresh (host-only)
- Ticket #100 - lot 2 — Détecte une image dev périmée et alerte le dashboard
- Ticket #100 - lot 1 — Estampille l'image dev avec le SHA de build
- Ticket #99 — Outille la clôture et journalise l'apprentissage
- Ticket #99 - lot 5 — Corrige la capture et l'upload de /demo-video
- Ticket #99 - lot 4 — Documente la vidéo de démo et la config MCP Playwright
- Ticket #99 - lot 3 — Impose une vidéo de démo quand un .twig est touché
- Ticket #99 - lot 2 — Ajoute le skill /demo-video de capture reproductible
- Ticket #99 - lot 1 — Versionne le MCP Playwright dans .mcp.json
- Lock file maintenance
- Update dependency php to >=8.5.8

## [202607181752] — 2026-07-18

### Ajouté

- Affiche vitesse et accélération de conso quota

### Corrigé

- Assouplit la contrainte php à >=8.5
- Adapte les stubs mock à PHPUnit 13

### Outillage & CI

- Met à jour castor, glab, node et claude-code

### Divers

- Update dépendances non majeures
- Ticket #86 - clôture — bilan interactions (apprentissage.md)
- Update dependency phpunit/phpunit to v13
- Ticket #86 - lot 2 — Épingle Chromium 149 via snapshot pour fiabiliser les E2E
- Ticket #86 - lot 1 — Capture le log verbeux Chromium et durcit les flags E2E
- Update dependency typescript to v7

## [202607060654] — 2026-07-06

### Ajouté

- Ticket #45 - lot 7 — polish éditeur — drag Crepe, typo Bringhurst, mode focus, aperçu serveur
- Ticket #45 - lot 1 — thème de formulaire mappé sur le design-system
- Famille de skills « ticket » GitLab + raffinements outillage
- Étape 7 - lot 6 — cible castor monitor (métriques live via Ember)
- Étape 7 - lot 5 — analyse IA Claude asynchrone des articles publiés
- Étape 7 - lot 4 — vue contenu public et clé API Claude chiffrée
- Étape 7 - lot 3 — parcours d'écriture, autosave et corbeille
- Étape 7 - lot 2 — domaine, cycle de vie et révisions
- Étape 7 - lot 1 — fondations workflow/Mercure/scheduler
- Ajoute le skill /creer-tag (release + maj CHANGELOG)
- Versionne le CHANGELOG par tag de release
- Ajoute la cible tag:create pour déclencher une release

### Corrigé

- Ticket #45 - lot 2 — habillage DS + débloque CSRF périmé et double-bouton
- Update dépendances non majeures
- Update dépendances non majeures
- Update dépendances non majeures
- Problème récupération variable env ci gitlab

### Documentation

- Ticket #55 — clôture — bilan interactions
- Ticket #54 — clôture — bilan interactions
- Ticket #57 — clôture — bilan interactions
- Ticket #45 — clôture — bilan interactions étape 7
- Consigne l'évaluation de clôture dans apprentissage.md
- Cadre l'écriture d'article en 6 lots
- Documente le versionnement par tag et /creer-tag

### Outillage & CI

- Ticket #57 - lot 4 — allège la garde de lot et silence le ship
- Ticket #57 - lot 3 — gen-tasks.sh — garde-fou anti-clobber + mermaid réel
- Ticket #57 - lot 2 — fiabilise ticket-context.sh sur 0 fichier cité
- Ticket #57 - lot 1 — attente discriminante sur le h1 après navigation
- Ticket #45 - lot 6 — durcit l'outillage implementer-lot-ticket + analyser-ticket
- Ticket #45 - lot 5 — réconcilie design-system/screens.css avec la copie servie
- Ticket #45 - lot 4 — backfill CSS des écrans réglages, articles et analyse IA
- Ticket #45 - lot 3 — habille l'éditeur d'article et l'e-mail de réinitialisation
- Update dépendances non majeures
- Installe unzip pour des installs Composer fiables
- Update anchore/syft docker tag to v1.46.0
- Update dependency friendsofphp/php-cs-fixer to ^3.95.11
- Exception multi-lots, gate 80 %, testabilité, couverture
- Allège le contexte CLAUDE.md et fixe le quota du skill

### Divers

- Ticket #62 - clôture — bilan interactions (apprentissage.md)
- Câble la bascule d'onglets Actifs/Archivés et les états vides des carnets
- Ticket #62 - lot 10 — Rend l'isolation E2E structurelle et fiabilise l'auto-merge
- Ticket #62 - lot 9 — Ajoute la recherche globale d'articles par titre
- Ticket #62 - lot 8 — Ajoute l'archivage, la restauration et la suppression d'un carnet
- Ticket #62 - lot 7 — Ajoute la création et les réglages d'un carnet
- Ticket #62 - lot 6 — Ajoute la modale d'aperçu d'article
- Ticket #62 - lot 5 — Ajoute le fenêtrage paginé de la frise chronologique
- Ticket #62 - lot 4 — Rend la frise chronologique statique d'un carnet
- Ticket #62 - lot 3 — Rend la section carnet, son tri et son pliage
- Ticket #62 - lot 2 — Refond la page d'accueil de l'espace autour des carnets
- Ticket #62 - lot 1 — Introduit le modèle multi-carnets et migre les données
- Update dependency phpstan/phpstan-phpunit to ^2.0.18
- Ajoute le hook guard-rm et libère rm sous var/claude/
- Ticket #55 - lot 6 — Fiabilise ticket-context.sh et gen-tasks.sh
- Ticket #55 - lot 5 — Dé-duplique les SKILL.md et branche le chargement des règles
- Ticket #55 - lot 4 — Étend suggest-docs.sh (--docs/--rules) et allège CLAUDE.md
- Ticket #55 - lot 3 — Déporte tests, délégation, secrets et actions remote en fiches _shared
- Ticket #55 - lot 2 — Déporte patterns, design system et conventions en fiches _shared
- Ticket #55 - lot 1 — Cartographie les sujets de règles dans un index _shared
- Ticket #54 - lot 5 — Outille la préparation mécanique des tests (mass-sed) pour le test-writer
- Ticket #54 - lot 4 — Bascule ArticleAnalysis et Setting en PK UUIDv7, requirements v7 partout
- Ticket #54 - lot 3 — Bascule Article et ArticleRevision en PK UUIDv7 applicative
- Ticket #54 - lot 2 — Bascule User et ResetPasswordRequest en PK UUIDv7 applicative
- Ticket #54 - lot 1 — Ajoute symfony/uid et consolide les règles Doctrine en source unique

## [202606220820] — 2026-06-22

### Ajouté

- E-mails au design system (user/admin) + transport failed
- Connexion et réinitialisation au design system
- Header partagé et sélecteur de thème clair/sombre/système
- Étape 6 - lot 4 — dashboards et réglages d'accent au design system
- Étape 6 - lot 3 — connexion et accueil plateforme au design system
- Étape 6 - lot 2 — socle design system + accent d'instance (Setting)
- Étape 6 - lot 1 — fondations Article et prénom

### Corrigé

- Corrige le nom d'env du token github pour Renovate
- Régénère composer.lock + recrée la MR Renovate sur main

### Documentation

- Cadrage GitLab (design system, connexion, accueil)

### Outillage & CI

- Bump glab 1.103.0, Node 24.17.0, Claude Code 2.1.185
- Préflight de diagnostic du token github.com
- Clôture — apprentissage + outillage skills

## [202606150332] — 2026-06-15

### Ajouté

- Lot 10 — remember-me + rate limiter sur les logins
- Lot 9 — saisie du nouveau mot de passe (reset password)
- Lot 8 — demande de réinitialisation de mot de passe
- Lot 7 — composant Twig Header partagé
- Lot 6 — bascule admin↔user par jeton signé à usage unique
- Lot 5 — Voter UserDataVoter + dashboards user/admin
- Ajoute le Live Component de connexion email-first
- Configure les firewalls user/admin et les pages de login
- Ajoute la commande console app:user:create
- Pose la fondation utilisateur (User + repository)

### Corrigé

- Neutralise le mailer en env test (MAILER_DSN=null)

### Documentation

- Cadrer la sécurité Symfony et lier le ticket GitLab #14
- Aligne les commandes glab sur `glab ci run`

### Outillage & CI

- Conventions GitLab d'assignation/traçabilité + optims
- Trait réutilisable de login email-first en WebTestCase
- Patches friction implementer-lot (pré-vol, anti-parasites, rearm, rebase)
- Quota PHP 10, gotchas + checkpoints agents, rm tests/
- Update redis docker tag to v8
- Update rabbitmq docker tag to v4
- Update postgres docker tag to v18
- Update node.js to v24
- Déplace le gate branches du CI vers une vérif locale
- Ts:check lit la version TypeScript du package.json
- Ajoute GITHUB_COM_TOKEN pour régénérer composer.lock
- Restreint le scope des règles changes des jobs de test
- Update gcr.io/projectsigstore/cosign docker tag to v3

## [202606071913] — 2026-06-07

### Corrigé

- Échappe !<iid> qui cassait le chargement des skills
- Refresh OAuth, fuseau Paris et plugin Mermaid

### Outillage & CI

- Active l'auto-merge et l'auto-rebase des MR
- Update dependency typescript to v6
- Update docker docker tag to v29

### Divers

- Corrige le flag glab mr create (-F inexistant → -d)
- Ajoute les skills de cadrage d'étape, agents et doc associée

## [202606061525] — 2026-06-06

### Corrigé

- Pré-charge Composer via COPY --from au lieu de install-php-extensions @composer

## [202606061413] — 2026-06-06

### Corrigé

- Curl avec retries pour résister aux hoquets réseau CI

## [202606061256] — 2026-06-06

### Corrigé

- Renovate utilise binarySource: install pour régénérer composer.lock

## [202606060754] — 2026-06-06

### Corrigé

- Security:container-issue — revert GITLAB_TOKEN + format CVE

### Outillage & CI

- Purge linux-libc-dev de l'image (-22 CVE faux positifs)

## [202606052107] — 2026-06-05

### Corrigé

- Security:container-issue passe à CI_JOB_TOKEN + filtre Critical/High

### Modifié

- Skippe les jobs redondants sur la pipeline tag

### Outillage & CI

- Bump cosign v2.6.3 + syft v1.45.1 + alpine 3.22

## [202606051643] — 2026-06-05

### Corrigé

- Supply-chain en multi-stage COPY --from= (CDN GitHub KO)
- Image kirexo-supply-chain pour cosign + syft

### Documentation

- Ajoute la règle « actions remote = script obligatoire »
- Corrige la syntaxe glab ci run dans tag.yml

## [202606051059] — 2026-06-05

### Ajouté

- Pipeline GitLab CI complète — qualité, builds, security, releases, supply chain
- Task runner Castor, hooks Claude, harnais de tests, dépendances
- Push HTTPS via glab credential helper

### Corrigé

- Cache vendor/ corrompu (bump prefix v2 + chown dans build:vendor)
- Pré-chauffage ipset api.anthropic.com pour Claude Code
- Security:secret-gate filtre les placeholders publics de dev
- Chdir vers la racine pour résoudre les chemins relatifs

### Documentation

- Pipeline CI, déploiement, signature cosign, SBOM, audit, cleanup registry

### Outillage & CI

- Couvre ToolsUpgrader::isDocumentedArg() (pipeline 99.56% → 100%)
- Bump glab 1.101.0 + Claude Code 2.1.163, skip SHA256 dans la doc
- Ci:local exécute les jobs Docker en local
- Valider l'étape 4 et journaliser l'apprentissage
- Cadrage de l'étape 4 — pipeline GitLab CI complète
- Whitelister github.com et raw.githubusercontent.com
- Autoriser glab issue create/close/note
- Ajouter laravel/pao pour des sorties dev plus compactes
- Bump glab 1.99, node 24.16, claude-code 2.1.150

## [0.3.0] — 2026-05-19

### Correctifs rétrospective étape 3 — 2026-05-18

- **Fusion `FirewallWhitelistStore` → `FirewallWhitelist`** : une seule classe `src/DevContainer/FirewallWhitelist.php` combine désormais la logique pure statique (`isValidDomain`, `parseDomainLines`, `isAlreadyCovered` + constantes `DOMAIN_REGEX`, `DEFAULT_BASELINE_PATH`, `DEFAULT_LOCAL_PATH`) et les méthodes d'instance d'I/O fichier (`readBaseline`, `readLocal`, `readLocalRejected`, `isInBaseline`, `isInLocal`, `appendLocal`, `removeFromLocal`). La méthode `parseLocal` est **renommée `parseDomainLines`** pour aligner la sémantique avec le helper bash `firewall_parse_domain_lines` (`.devcontainer/init-firewall.lib.sh`).
- **Extraction de logique pure dans `ToolsUpgrader`** : `selectFrankenphpCandidate()` (sélection de tag candidat pour l'image base FrankenPHP, comparaison de tuples `(franken-major, php-major, php-minor)` + exclusion régression PHP) et `buildDockerfileUrls()` (reconstruction des URLs des `RUN curl …` à partir des `ARG *_VERSION`). Permet la couverture unitaire de `fetch_frankenphp_drift()` et de la sous-étape `host:check` HEAD HTTP sans réseau.
- **Section « Ce que l'isolation ne protège pas »** ajoutée dans [`docs/explanation/devcontainer.md`](https://gitlab.com/shaurifr/kirexo/-/blob/main/docs/explanation/devcontainer.md) entre « Comment ça marche — flow réseau » et « Pourquoi NE PAS monter `/var/run/docker.sock` ». Deux limites assumées documentées : exfiltration via l'API Anthropic (les credentials lus dans `${HOME}/.claude/.credentials.json` peuvent partir dans le contenu d'une requête vers `api.anthropic.com` légitimement whitelisté — le RO empêche la persistance entre sessions, pas l'exfiltration en session) et contournement potentiel via DNS-over-HTTPS (préférer des FQDNs précis, pas des suffixes génériques de CDN).
- **Contrôle négatif documentaire** : `203.0.113.1` (IP RFC 5737 TEST-NET-3, garantie non routable) remplace `example.com` dans le tutoriel [Ouvrir Kirexo dans un Dev Container PHPStorm](https://gitlab.com/shaurifr/kirexo/-/blob/main/docs/tutorials/devcontainer-phpstorm.md). Reste proche du modèle de menace (filtrage par socket, pas seulement par résolution DNS) et évite qu'un domaine de test finisse par accident dans la whitelist.
- **Références obsolètes à `init-firewall.sh` pour l'ajout de domaine** corrigées : `.devcontainer/AGENTS.md` et `.devcontainer/whitelist.local.txt.dist` pointent désormais vers `baseline-domains.txt` (source de vérité versionnée de la baseline) et `castor devcontainer:whitelist-add`. La whitelist n'est plus inlinée dans `init-firewall.sh`.
- **`castor devcontainer:check-tools` / `upgrade-tools` étendus au drift de l'image base FrankenPHP** : interrogation de Docker Hub (`hub.docker.com/v2/repositories/dunglas/frankenphp/tags/`), warning non bloquant dans `upgrade-tools` (le bump cible une instruction `FROM`, pas un `ARG` — donc manuel), compté dans le `exit 2` de `--check`. Couvre indirectement les paquets apt et `install-php-extensions` livrés via la base.
- **`castor host:check` étendu de 3 à 5 sous-étapes** : ajout de **hadolint** sur le `Dockerfile` (`docker run --rm -i hadolint/hadolint:latest hadolint --failure-threshold error - < Dockerfile`, seules les erreurs sont bloquantes ; warnings et info remontés mais tolérés) et de **HEAD HTTP en parallèle** sur les URLs construites par `ToolsUpgrader::buildDockerfileUrls()` à partir des `ARG *_VERSION` (Castor, glab, tarball Node, `SHASUMS256.txt`). Détecte une release upstream supprimée/renommée avant un rebuild qui rejetterait silencieusement un fichier corrompu via `sha256sum -c`. Coût observé : ~0.8 s en cache, ~3.5 s au premier appel (pull de l'image hadolint).
- **Documentation Diátaxis mise à jour** :
    - [`docs/reference/devcontainer.md`](https://gitlab.com/shaurifr/kirexo/-/blob/main/docs/reference/devcontainer.md) : `parseLocal()` → `parseDomainLines()` dans la ligne `baseline-domains.txt`, nouvelle section « Surveillance de l'image base FrankenPHP » sous l'outillage.
    - [`docs/reference/commandes-castor.md`](https://gitlab.com/shaurifr/kirexo/-/blob/main/docs/reference/commandes-castor.md) : descriptions de `host:check` (5 sous-étapes), `check-tools` et `upgrade-tools` enrichies du volet image base FrankenPHP.
    - [`docs/explanation/devcontainer.md`](https://gitlab.com/shaurifr/kirexo/-/blob/main/docs/explanation/devcontainer.md) : section « Ce que l'isolation ne protège pas ».

### Ajouté

- `CHANGELOG.md` racine au format Keep a Changelog, exposé dans la doc Diátaxis en complément de la nav existante.
- **Dev Container** dérivé de [`dunglas/symfony-docker`](https://github.com/dunglas/symfony-docker) :
    - `.devcontainer/devcontainer.json`, `compose.devcontainer.yaml`, `post-create.sh`, `post-start.sh`.
    - Stack complète accessible depuis l'IDE (PHPStorm 2024.1+ ou VS Code) sans installer PHP/Node/Composer côté hôte.
    - Stratégie d'isolation **sans socket Docker monté** — `castor docker:*`, `cert:trust`, `doctor`, `docs:build` refusent de tourner depuis l'intérieur (cf. `assert_outside_container()` dans `castor.php`).
- **Pare-feu interne** (`init-firewall.sh`) restreignant le trafic sortant à une whitelist de domaines :
    - Policies `OUTPUT/INPUT/FORWARD DROP` posées immédiatement après le flush.
    - `dnsmasq` + `ipset allowed-domains` alimentés à la volée à chaque résolution DNS.
    - Plage CIDR intra-stack unique `172.30.0.0/24` (réseau Docker custom `kirexo`) au lieu des trois RFC1918.
    - Override local `whitelist.local.txt` (gitignored) concaténé à la baseline si présent.
    - Smoke-tests post-reload : contrôle négatif **bloquant** sur `203.0.113.1` (RFC 5737), contrôles positifs **non bloquants** sur `gitlab.com` / `symfony.com` / `packagist.org` / `registry.npmjs.org`, résolution intra-stack **bloquante**.
- **Mode `bypassPermissions` Claude Code** activé par `post-create.sh` via création de `.claude/settings.local.json`, avec opt-out :
    - One-shot par variable d'environnement `KIREXO_CLAUDE_BYPASS=0`.
    - Persistant par marqueur fichier `.devcontainer/no-claude-bypass` (gitignored).
- **Embarquement direct de Node + Claude Code** dans le stage `frankenphp_dev` du `Dockerfile` (et non via les `features` du devcontainer) pour contourner un bug du pipeline JetBrains qui re-cible le stage `frankenphp_dev` sur un Dockerfile temporaire.
- **Vérification d'intégrité par SHA-256** sur les binaires Castor, glab et Node (ARG `*_VERSION` + `*_SHA256`). Claude Code repose sur le `dist.integrity` SRI sha512 du registre npm.
- **`autocomplete Castor` system-wide** dans le devcontainer via `/etc/bash.bashrc` (sourcing de `bash-completion` + `eval "$(castor completion bash)"`).
- **Logique pure testable** extraite dans `src/DevContainer/` :
    - `FirewallWhitelist` — validation FQDN, parsing baseline, dédoublonnage.
    - `ToolsUpgrader` — extraction et substitution d'`ARG` dans le `Dockerfile` et la doc.
- **Nouvelles cibles Castor** (cf. `docs/reference/commandes-castor.md`) :
    - `castor devcontainer:upgrade-tools [--check|--apply]` — résout les `latest` (Castor via GitHub API, glab via GitLab API, Node majeure LTS via `nodejs/Release/schedule.json`, Node patch via `nodejs.org/dist/index.json`, Claude Code via npm registry), recalcule les SHA-256, met à jour le `Dockerfile` et la doc.
    - `castor devcontainer:firewall-reload` — wrapper sur `sudo init-firewall.sh`, refuse l'hôte.
    - `castor devcontainer:whitelist-add <domain>` / `whitelist-remove <domain>` — édite `whitelist.local.txt` puis recharge le pare-feu, avec validation FQDN et dédoublonnage.
    - `castor devcontainer:doctor` — pendant interne de `castor doctor` (vérifie l'amorçage, dnsmasq, l'ipset, FrankenPHP sur `127.0.0.1`, la résolution intra-stack, les migrations à jour).
    - `castor devcontainer:frankenphp-restart` — relance le supervisor FrankenPHP après bail-out ou kill manuel.
    - `castor lint:shell` — `shellcheck` sur les scripts `.devcontainer/*.sh` et `.claude/hooks/*.sh`, intégrée à `castor lint`.
- **Supervisor FrankenPHP** (`frankenphp-supervisor.sh`) avec backoff exponentiel borné (`INITIAL_DELAY=2`, `MAX_DELAY=30`) et bail-out après 5 crashs consécutifs sans stabilisation (>60s).
- **Marqueurs d'amorçage** `.devcontainer/.bootstrap.{ok,failed}` écrits par `post-create.sh` et consultés en première ligne par `castor devcontainer:doctor`.
- **Tests unitaires** :
    - `FirewallWhitelistTest` — validation FQDN, parsing baseline et locale, dédoublonnage.
    - `ToolsUpgraderTest` — extraction et substitution d'ARG, calcul du diff de versions.
    - `FirewallRegexConsistencyTest` — garde-fou contre le drift entre la regex bash (`DOMAIN_VALIDATION_REGEX`) et la regex PHP (`FirewallWhitelist::DOMAIN_REGEX`) : égalité textuelle + dataset croisé `preg_match` ↔ `[[ =~ ]]`.
- **Documentation Diátaxis** :
    - Tutoriel : [Ouvrir Kirexo dans un Dev Container PHPStorm](https://gitlab.com/shaurifr/kirexo/-/blob/main/docs/tutorials/devcontainer-phpstorm.md).
    - Guides : [Whitelister un domaine](https://gitlab.com/shaurifr/kirexo/-/blob/main/docs/how-to/whitelister-un-domaine.md), [Debugger le pare-feu](https://gitlab.com/shaurifr/kirexo/-/blob/main/docs/how-to/debugger-le-pare-feu-devcontainer.md), [Activer l'autocomplétion Castor sur l'hôte](https://gitlab.com/shaurifr/kirexo/-/blob/main/docs/how-to/activer-lautocompletion-castor.md).
    - Référence : [Dev Container](https://gitlab.com/shaurifr/kirexo/-/blob/main/docs/reference/devcontainer.md).
    - Explication : [Choix d'isolation du Dev Container](https://gitlab.com/shaurifr/kirexo/-/blob/main/docs/explanation/devcontainer.md).
- `.devcontainer/whitelist.local.txt.dist` versionné comme modèle pour le fichier d'override local.

### Modifié

- `assert_outside_container()` (`castor.php`) accepte désormais une suggestion contextuelle d'alternative ; `castor doctor` et `castor docs:build` lancés depuis l'intérieur du devcontainer affichent une commande utilisable directement (`castor devcontainer:doctor` et `curl -sIf http://localhost:8000/` respectivement) en plus du refus.
- `Dockerfile` (stage `frankenphp_dev`) : ajout de `sudo`, `iptables`, `ipset`, `dnsmasq`, `jq`, `iproute2`, `ca-certificates`, `shellcheck`, `bash-completion`. Création d'un user `app` aligné sur l'UID/GID hôte.
- `frankenphp/Caddyfile` : ajout de `skip_install_trust` au bloc global pour empêcher Caddy de tenter d'installer sa CA racine dans le trust store du conteneur (qui exigerait `sudo`).
- `compose.override.yaml` : définition d'un réseau Docker custom `kirexo` (`172.30.0.0/24`) + build args `USER_ID`/`GROUP_ID`.

### Sécurité

- `bypassPermissions` Claude Code rendu acceptable par l'addition de deux barrières structurelles : isolation filesystem (le conteneur ne voit que `/app`) + isolation réseau (pare-feu iptables sur whitelist). Sans ces deux barrières, ne pas reproduire ce paramétrage.
- GitHub volontairement **exclu** de la whitelist : le projet est hébergé sur GitLab, et les binaires GitHub indispensables (Castor, glab) sont récupérés au **build de l'image** via le réseau hôte, pas au runtime depuis le conteneur.
- **Durcissements post-audit** (4 mécanismes ajoutés en seconde passe, cf. [Référence](https://gitlab.com/shaurifr/kirexo/-/blob/main/docs/reference/devcontainer.md)) :
    - **Surcharge RO ciblée** sur `${HOME}/.claude/.credentials.json`, `${HOME}/.claude/settings.json` et `${HOME}/.claude/CLAUDE.md` — un Claude éventuellement compromis dans le conteneur ne peut plus *réécrire* ces fichiers (exfiltration via la prochaine session côté hôte impossible). L'historique de conversations (`projects/`, `sessions/`, `history.jsonl`) reste en RW pour rester persisté côté hôte.
    - **Bind-mount RO** sur `init-firewall.sh`, `init-firewall.lib.sh`, `baseline-domains.txt` et `firewall-healthcheck.sh` — un sous-processus malveillant ne peut plus réécrire les scripts puis attendre le prochain reload pour s'exécuter en root via le sudoers NOPASSWD. Pour modifier ces fichiers, redémarrer le devcontainer.
    - `security_opt: ["no-new-privileges:true"]` — empêche un binaire setuid/setgid d'élever ses droits dans le conteneur.
    - **Healthcheck enrichi** d'une 4e condition `sudo -n /app/.devcontainer/firewall-healthcheck.sh` (wrapper read-only qui vérifie `iptables -S OUTPUT | grep -q '^-P OUTPUT DROP'`). Détecte un `iptables -F` manuel oublié qui laissait jusqu'ici le pare-feu silencieusement ouvert avec dnsmasq encore vert.

### Ajouté (post-audit)

- **Tests bats** dans `tests/Bash/firewall/` (43 tests, 3 fichiers) — couvrent les fonctions pures `firewall_is_valid_domain`, `firewall_parse_domain_lines`, `firewall_is_already_covered`. Premier lot de tests shell du projet ; convention bats documentée dans `tests/Bash/firewall/README.md`.
- `.devcontainer/init-firewall.lib.sh` — fonctions pures extraites de `init-firewall.sh` pour permettre les tests bats sans NET_ADMIN. La regex `FIREWALL_DOMAIN_REGEX` y est définie en `readonly`, partagée avec `App\DevContainer\FirewallWhitelist::DOMAIN_REGEX` côté PHP.
- `.devcontainer/firewall-healthcheck.sh` — wrapper sudo read-only utilisé par le healthcheck Docker pour valider que la policy `OUTPUT DROP` est toujours posée.
- **Cible Castor `test:bash`** + intégration dans `castor test` et `castor all` (entre `test:unit` et `test:e2e`). Lance `bats --recursive tests/Bash/` dans le conteneur.
- **Pare-feu activé dans `post-create.sh`** (avant `castor install`) — la phase d'amorçage Composer/importmap/Tailwind est maintenant filtrée par la whitelist au lieu de tourner avec un réseau ouvert.
- **Mermaid** activé dans mkdocs (`pymdownx.superfences` + `custom_fences`) — diagrammes du flow réseau (DNS → dnsmasq → ipset → iptables, cas rejet, ordre d'exécution) ajoutés dans `docs/explanation/devcontainer.md`.
- **`bats`** ajouté au stage `frankenphp_dev` du Dockerfile (paquet Debian, v1.x).
- **Auto-relance de FrankenPHP** via le healthcheck Docker du service `php` (devcontainer) — rattrape le cas où PhpStorm zappe le `postStartCommand` en s'attachant à un conteneur déjà démarré. Logique déportée dans `.devcontainer/php-healthcheck.sh` (bind-mount RO, deny-list Claude), avec deux garde-fous (`pgrep frankenphp-supervisor.sh` + lockfile mtime `RELAUNCH_MIN_INTERVAL=30s`), détachement via `setsid -f` et audit dans `var/log/devcontainer/frankenphp.log`. Cf. [Référence — Auto-relance de FrankenPHP](https://gitlab.com/shaurifr/kirexo/-/blob/main/docs/reference/devcontainer.md#auto-relance-de-frankenphp).

### Modifié (post-audit)

- `castor.php` allégé (1602 → 868 lignes) : extraction des cibles `devcontainer:*` + helpers associés dans `castor/devcontainer.php`, importé via `Castor\import()`. Inventaire des cibles identique (46), comportement inchangé.
- `init-firewall.sh` refactoré pour sourcer `init-firewall.lib.sh` — suppression des deux boucles inlinées de parsing baseline/locale, validation FQDN déléguée à `firewall_is_valid_domain`. Sémantique inchangée.
- `Dockerfile` (stage `frankenphp_dev`) : sudoers étendu à un **second** script (`firewall-healthcheck.sh`) en NOPASSWD — auparavant seul `init-firewall.sh` était autorisé.
- `compose.devcontainer.yaml` : ajout `security_opt`, 3 bind-mounts RO `${HOME}/.claude/*`, 5 bind-mounts RO `.devcontainer/*` (dont `php-healthcheck.sh`), healthcheck déporté dans `php-healthcheck.sh` (4 conditions enchaînées + auto-relance FrankenPHP).
- `.devcontainer/AGENTS.md` : pointer explicite vers `/CLAUDE.md` comme source de vérité primaire, rappel du quota 5 fichiers PHP et de la délégation obligatoire aux sous-agents.

### Défaut connu (à corriger en suivi)

- **`FIREWALL_DOMAIN_REGEX` accepte les IPs littérales** : la regex actuelle laisse passer `1.2.3.4` comme FQDN valide (labels purement numériques autorisés). La doc dit le contraire. Découvert pendant l'écriture des tests bats — le test verrouille le comportement actuel avec un commentaire pointant l'inversion à faire le jour où on durcit la regex (côté lib **et** côté `FirewallWhitelist::DOMAIN_REGEX` PHP, sinon `FirewallRegexConsistencyTest` cassera).

## [0.2.0] — Étape 2 — Cadrage, outillage et documentation

### Ajouté

- `castor.php` à la racine — task runner Castor, source unique des cibles de qualité et de développement (`cs:fix`, `phpstan`, `lint`, `test:unit`, `test:e2e`, `qa`, `all`, …).
- Documentation [Diátaxis](https://diataxis.fr/) initiale publiée via `mkdocs-material` (service `docs` du compose).
- `mkdocs.yml` à la racine + image custom `mkdocs/Dockerfile` (plugins `git-revision-date-localized` et `social`).
- Sous-agents Claude Code dans `.claude/agents/` (`reviewer`, `test-writer`, `doc-writer`) avec hooks de délégation et de comptage de fichiers PHP de production.

## [0.1.0] — Étape 1 — Bootstrap

### Ajouté

- Bootstrap du projet à partir de [`dunglas/symfony-docker`](https://github.com/dunglas/symfony-docker) (FrankenPHP + Symfony + Docker Compose).
- Services Postgres, Redis, RabbitMQ, Typesense, Gotenberg, Mailpit ajoutés au compose.
- `CLAUDE.md` initial — cadrage technique, patterns d'architecture (CQRS, plugins isolés, Voters, Live Components, DTOs immuables, Repository pattern), règles de développement.

[0.3.0]: https://gitlab.com/shaurifr/kirexo/-/compare/v0.2.0...v0.3.0
[0.2.0]: https://gitlab.com/shaurifr/kirexo/-/compare/v0.1.0...v0.2.0
[0.1.0]: https://gitlab.com/shaurifr/kirexo/-/tags/v0.1.0

La configuration mkdocs (cf. mkdocs.yml) étend base_path à la racine du projet pour permettre cette inclusion, et check_paths: true fait échouer le build si le snippet est introuvable.

Règle : pas de liens Markdown relatifs¶

Interdit dans CHANGELOG.md : tout lien Markdown relatif vers une page de la doc, par exemple [Référence](docs/reference/devcontainer.md).

Pourquoi : après inclusion via --8<--, le rendu du lien est résolu par mkdocs relativement à la page hôte (docs/changelog.md), pas relativement à la racine du dépôt. Un lien docs/reference/devcontainer.md pointe alors vers docs/docs/reference/devcontainer.md qui n'existe pas. mkdocs émet un warning, et comme mkdocs.yml est en strict: true, le build échoue avec un exit code 1 — le conteneur kirexo-docs-1 ne démarre plus.

Alternatives valides¶

Par ordre de préférence dans le contexte du CHANGELOG.md :

URL GitLab absolue vers le fichier sur la branche main — style en place dans le CHANGELOG.md (cf. liens vers les pages de doc dans la section Documentation Diátaxis de la version [0.3.0]) :
```
[Référence](https://gitlab.com/shaurifr/kirexo/-/blob/main/docs/reference/devcontainer.md)
```
Avantage : le lien fonctionne aussi bien depuis la page mkdocs que depuis la vue GitLab du CHANGELOG.md (où la doc n'est de toute façon pas rendue). C'est le style à adopter par défaut.
URL absolue vers la doc publiée (https://docs.kirexo.fr/...) — utilisable une fois la doc déployée publiquement. Même propriété : fonctionne dans les deux contextes de lecture (GitLab et mkdocs).
Lien externe absolu (RFC, doc d'un projet tiers, etc.) — sans contrainte particulière, c'est le seul cas où on peut écrire un lien de manière naturelle.

Rappel in situ¶

Un commentaire HTML en tête du CHANGELOG.md racine renvoie vers cette page. Il est invisible dans le rendu mkdocs comme dans le rendu GitLab, mais visible pour tout contributeur (humain ou agent) qui ouvre le fichier pour l'éditer. Ne pas le supprimer.

Convention du CHANGELOG.md¶