Aller au contenu

Les artefacts sont indexés. Le template de review est intégré dans le prompt. Je procède à l'audit complet.

PD-103 — Plan d'implémentation : Revue

1. Références

  • Spécification : PD-103-specification.md (v3)
  • Tests contractuels : PD-103-tests.md (v3)
  • Plan d'implémentation : PD-103-plan.md (v2, inclut §11bis/11ter)
  • Code Contracts : PD-103-code-contracts.yaml
  • Date de revue : 2026-04-03
  • Reviewer : Claude (auditeur PMO indépendant)

2. Constatations (écarts)

# Type Référence (Spec/Test/Plan) Description Impact Gravité
1 Code Contract — Complétude CC-13 / Plan §1.2 M13 / §11bis CC-13 ne liste qu'un fichier migration (*-PD103-CreateCaptureEvents.ts) alors que le plan §1.2 M13 et §11bis décrivent explicitement deux tables : capture_events ET capture_audit_log (journal probatoire append-only avec trigger INSERT-ONLY). Le fichier *-PD103-CreateCaptureAuditLog.ts est absent de la liste files du CC-13. L'agent step 6b risque de ne pas créer la migration du journal probatoire. Journal probatoire potentiellement absent → violation INV-103-25 et INV-103-10. MAJEUR
2 Code Contract — Complétude CC-9 / Spec §5.6 / INV-103-25 CC-9 ne mentionne ni l'entité audit log ni l'insert dans capture_audit_log dans son scope, fichiers ou invariants. La spec §5.6 step 1 exige que l'événement probatoire soit persisté dans capture_events ET dans le journal probatoire append-only. CC-9 ne couvre que capture-event.entity.ts. Il manque une entité (ou référence) pour capture_audit_log et le mécanisme d'insertion dans le même périmètre. L'agent M9 pourrait persister capture_events sans écrire dans le journal append-only → rupture d'auditabilité. MAJEUR
3 Couverture manquante (mapping tests) Plan §5 / TC-ERR-03, TC-ERR-04, TC-ERR-14, TC-ERR-15 4 test cases absents de la table de mapping §5 du plan : TC-ERR-03 (OCR échec), TC-ERR-04 (réseau indisponible dès UPLOADING), TC-ERR-14 (checksum S3 mismatch), TC-ERR-15 (JWT expiré en reprise). Les mécanismes existent (M3, M4, M6) mais aucun point d'observation n'est formellement mappé pour ces TCs dans le plan. Risque d'oubli de couverture en phase 6b/7 pour ces cas d'erreur. MINEUR
4 Hypothèse implicite Plan §2.3 step 1 / INV-103-10 BullMQ utilisé comme queue async post-commit sans figurer dans les hypothèses techniques (§8) ni dans les contraintes (§10.1 de la spec). Le plan suppose que BullMQ est déjà déployé et configuré dans le backend. Si BullMQ n'est pas présent ou si un autre mécanisme de queue est utilisé, le plan est inapplicable pour le scellement async. MINEUR
5 Hypothèse implicite Plan §8 HT-103-04 vs §11 Incohérence d'estimation d'effort pour le service S3PresignedUrl : HT-103-04 estime ~2j, §11 estime ~0.5j. Ambiguïté sur l'effort réel si le service n'existe pas. Risque de sous-estimation planning si le service doit être créé. MINEUR
6 Non-conformité Spec Spec §10.1 "obligatoire" / Plan §8 HT-103-01 Le plan introduit un fallback @noble/hashes/sha3 pour SHA3-256 alors que la spec v3 §10.1 qualifie react-native-quick-crypto d'obligatoire. Le plan contredit le caractère obligatoire en ajoutant une stratégie de dérogation non contractualisée dans la spec. Le lien avec H-103-11 (hypothèse spec) est implicite mais non tracé. Si le fallback est utilisé sans dérogation formelle, le livrable est techniquement non conforme à la spec. MAJEUR
7 Hypothèse implicite Plan §3 mapping INV-103-12 / Spec §5.6 step 6 Mécanisme de notification push ambigu : le plan mentionne "SSE/polling backend" pour déclencher la notification push. La spec exige un "push iOS obligatoire" initié côté backend (APNs). Le plan confond potentiellement la mise à jour d'état côté mobile (polling/SSE) avec la notification push serveur-initiée. Le composant responsable côté backend n'est pas identifié (pipeline existant supposé). Confusion architecturale entre state sync et push notification, risque d'absence de push réel. MINEUR
8 Code Contract — Complétude CC-10 / Spec §5.12 payload canonique upload_object_key absent du contrat CC-10. La spec §5.12 inclut upload_object_key dans l'objet canonique d'idempotence (9 champs). CC-10 (idempotence service) ne mentionne pas explicitement ce champ ni dans ses inputs, ni dans ses invariants, ni dans sa liste forbidden. Le flux presign → object_key → POST → canonical hash n'est pas tracé dans les flux techniques §2.2. Si upload_object_key est omis du fingerprint, deux uploads vers des objets S3 différents avec le même capture_id pourraient être considérés idempotents à tort. MAJEUR
9 Couverture manquante Spec §5.1 ocr_text / Plan M9 Sanitisation NFC + control chars non explicite dans le plan. La spec v3 §5.1 exige pour ocr_text : "normalisation NFC + suppression des control chars C0/C1 (hors tab, newline, CR) + longueur max". Le plan mentionne la validation DTO (class-validator) dans M9 mais ne documente pas ce mécanisme de sanitisation spécifique. L'agent M9 pourrait implémenter uniquement une validation de longueur sans la normalisation NFC ni le filtrage des control chars. MINEUR
10 Contrainte technique non documentée Plan §12 / CLAUDE.md conventions Variables CI pour tests d'intégration backend non listées. Le plan §12 prévoit des tests d'intégration M9+M10+M11 et M12+DB mais ne documente pas les variables d'environnement requises (DATABASE_URL, REDIS_URL pour rate-limit, S3_BUCKET pour GC tests, etc.). Tests d'intégration non reproductibles en CI sans documentation des prérequis. MINEUR
11 Hypothèse implicite Plan §11 / Spec §5.12 Endpoint POST /documents/capture/presign non contractualisé dans la spec. Le plan §11 ajoute un endpoint de pré-signature qui n'apparaît ni dans la spec §5.12 ni dans les invariants. C'est un ajout d'interface non spécifié. Le plan ne précise pas non plus les gardes d'authentification de cet endpoint (JWT requis ?). Endpoint potentiellement non sécurisé ou non couvert par les tests contractuels. MINEUR
12 Code Contract — Frontière CC-14 forbidden "Mock du state machine pour tests de transition" est trop restrictif. CC-14 interdit de mocker le state machine pour les tests. Or, les tests unitaires des composants M4, M6, M9 qui utilisent le state machine comme dépendance ont légitimement besoin de le mocker. L'interdiction devrait se limiter aux tests de la state machine elle-même (CC-1). L'agent tests risque soit de violer le forbidden, soit de ne pas écrire de tests unitaires isolés pour les composants dépendants. MINEUR

3. Synthèse

Écarts par gravité :

Gravité Nombre
BLOQUANT 0
MAJEUR 4
MINEUR 8

Points critiques :

  1. Journal probatoire incomplet dans les code contracts (écarts #1 et #2) — Le journal append-only (capture_audit_log) est décrit dans le plan §11bis mais insuffisamment contractualisé : migration absente de CC-13, entité absente de CC-9. Deux code contracts à corriger pour garantir que les agents step 6b implémentent le journal probatoire.

  2. upload_object_key manquant dans CC-10 (écart #8) — Champ présent dans la définition normative du payload canonique (spec §5.12) mais absent du contrat d'idempotence. Risque d'un fingerprint incomplet compromettant la sémantique 200/409.

  3. Fallback crypto non autorisé par la spec (écart #6) — La stratégie de dérogation @noble/hashes/sha3 doit être soit supprimée du plan, soit formalisée comme dérogation tracée vers H-103-11 avec validation PO.

  4. Couverture formelle complète — Hors les 4 écarts MAJEURS ci-dessus, le plan couvre l'intégralité des 39 invariants, 28 critères d'acceptation, et la quasi-totalité des 60+ test cases. Le découpage en 15 composants et 4 waves est cohérent avec les dépendances et les code contracts. La machine à états, le pipeline crypto, l'idempotence et la réconciliation sont correctement mappés.

4. Verdict de la revue

  • Statut : ⚠️ Accepté avec réserves
  • Motif synthétique : Le plan est structurellement solide et couvre l'ensemble des exigences de la spec v3. Les 4 écarts MAJEURS identifiés sont tous corrigeables sans refonte architecturale : compléter les code contracts CC-9/CC-13 pour le journal probatoire, ajouter upload_object_key au contrat CC-10, et résoudre le statut du fallback crypto. Aucun écart BLOQUANT. Le plan peut passer en Gate 5 après correction des 4 MAJEURS.