Rétrospective — PD-63¶

Résumé story¶

Story : PD-63 — Créer endpoint GET /documents/:id/download
Domaine : docs-api
Date : 2026-02-21
Durée totale : 20h (+43% vs estimation)
Gates : G3 GO (v2, 8.38/10) | G5 GO (v2, 8.50/10) | G8 GO (v1, 8.25/10)

Learnings de cette story¶

Depuis les gates¶

Gate	Verdict	Score	Iter	Tags	Note
G3	GO	8.38	v2	#fail-closed, #audit, #zero-knowledge	Clarifier fail-closed vs fail-open dès v1
G5	GO	8.50	v2	#plan, #go-no-go, #intercepteur	Phase 0 go/no-go pour hypothèses critiques
G8	GO	8.25	v1	#download, #audit, #hsm, #sonar	Stubs acceptés si tracés, pv-test-* naming

Depuis le REX (section 11)¶

Fail-closed dès la spec — Contractualiser le comportement en cas d'échec audit dès Gate 3 évite 2+ itérations
Phase 0 go/no-go systématique — Valider les hypothèses critiques (tables existantes, services disponibles) avant implémentation
Labels HSM stricts — Utiliser pv-test-* pour toute clé éphémère, PD-7 vérifie INV-04 globalement
crypto.randomUUID() toujours — Sonar flagge Math.random() même pour logging, utiliser randomUUID par défaut
Pipeline monitoring actif — Surveiller avec barre de progression, annuler pipelines bloqués manuellement

Patterns récurrents (domaine docs-api)¶

Pattern	Stories	Fréquence	Impact
Fail-closed audit	PD-60, PD-63, PD-31	3 stories	GO systématique quand contractualisé
Zero-knowledge architecture	PD-46, PD-63, PD-97	3 stories	GO — pattern mature
Pre-signed URL avec TTL	PD-46, PD-63	2 stories	GO — pattern stable
Exception filter pour rejets guards	PD-60, PD-63, PD-241	3 stories	Évite trous dans audit trail

Patterns récurrents (cross-domaines)¶

Alertes fortes (≥ 5 stories)¶

Tag	Occurrences	Pattern	Recommandation
`#testing`	19 stories	Tests unitaires insuffisants, regex fragiles	Checklist regex génériques dans prompts tests
`#security`	13 stories	Hotspots Sonar récurrents	Linter pré-commit pour Math.random(), btoa, etc.
`#audit`	11 stories	Audit manquant ou incomplet	Template INV-XX-audit obligatoire dans specs
`#zero-knowledge`	11 stories	Architecture bien comprise	Pattern validé — documenter dans CLAUDE.md

Patterns bloquants (NON_CONFORME récurrent)¶

Axe	Stories NON_CONFORME	Pattern
`completeness` (Gate 3)	PD-32, PD-238, PD-239, PD-240, PD-106	Specs v1 incomplètes sur rate limiting, fail-closed
`testability` (Gate 3)	PD-19, PD-32	Critères d'acceptation non mesurables

Axes fragiles (score moyen < 7.5)¶

Axe	Moyenne domaine	Stories concernées
`risk_mitigation` (Gate 5)	~7.2	PD-248, PD-44 — mitigation OCR, Lambda

Recommandations¶

Priorité haute (≥ 5 stories ou NON_CONFORME récurrent)¶

Ajouter checklist fail-closed dans templates/prompts/1 Spécification.md pour endpoints sensibles
Section obligatoire : "Comportement en cas d'échec" avec valeurs explicites
Issu de : PD-63 (2 iter G3), PD-60, PD-31
Exiger Phase 0 go/no-go dans templates/prompts/4 Plan.md pour hypothèses critiques
Vérifier tables/services existants avant de commencer l'implémentation
Issu de : PD-63 G5 v1 (tables document_shares/co_holders inexistantes)
Ajouter règle crypto.randomUUID() dans config/agents/agent-developer.md
Sonar flagge Math.random() même pour IDs non-sécuritaires
Issu de : PD-63 post-merge fix, security hotspot

Priorité normale¶

Cleanup HSM post-test automatique — job GitLab pour supprimer clés pv-test-* orphelines
Issu de : PD-63, PD-7 (clés orphelines après tests)
Section post-merge fixes dans REX — ajouter à templates/outputs/PD-XX-rex.md
Issu de : PD-63 (6 commits post-merge)
Regex tests génériques — vérifier UUID/timestamps dans config/agents/agent-qa-unit-integration.md
Issu de : PD-63 (test regex cassé par changement format correlation_id)

Signal CLAUDE.md¶

Sections suggérées pour révision :

1. Section "Étape 4 — Checklist pré-soumission Gate 5"¶

Ajouter :

### Phase 0 — Go/No-Go (OBLIGATOIRE)

Avant de rédiger le plan, vérifier :

| Hypothèse | Vérification | Résultat |
|-----------|-------------|----------|
| Tables requises existent | `grep -r "table_name" src/database/migrations/` | ✅ / ❌ |
| Services dépendants disponibles | Lister les imports prévus | ✅ / ❌ |
| Permissions HSM/AWS/Vault | Vérifier dans la story PD-7/PD-8 | ✅ / ❌ |

Si ❌ sur une hypothèse critique → **STOP** — créer la story de dépendance d'abord.

2. Section "Règles apprises"¶

Ajouter :

### Labels HSM stricts (2026-02-21)

**IMPORTANT** : Utiliser le préfixe `pv-test-*` pour TOUTES les clés HSM éphémères.

- Les tests contractuels PD-7 (INV-04) vérifient les labels de TOUTES les clés HSM
- Clés sans préfixe `pv-` ou `pv-test-` → échec pipeline
- Clés `pv-test-*` exclues de la vérification de rotation (TC-KL-02)

Exemple de labels valides :
- `pv-master-signing-2026` (production)
- `pv-test-benchmark-1234567890` (test)

Exemple de labels INVALIDES :
- `benchmark-key-1234` ❌ (manque préfixe pv-)
- `test-key-abc` ❌ (manque préfixe pv-test-)

3. Section "Règles apprises"¶

Ajouter :

### crypto.randomUUID() obligatoire (2026-02-21)

**IMPORTANT** : Utiliser `crypto.randomUUID()` pour TOUT identifiant aléatoire, même non-sécuritaire.

```typescript
// ❌ INTERDIT (flaggé par Sonar comme security hotspot)
const correlationId = `dl-${Date.now()}-${Math.random().toString(36).slice(2)}`;

// ✅ CORRECT
import { randomUUID } from 'node:crypto';
const correlationId = `dl-${randomUUID()}`;

Sonar flagge Math.random() même pour des IDs de logging ou de corrélation. ```

Rétrospective générée le 2026-02-21 par Claude (Orchestrateur)