PD-299 — Plan d'implémentation¶

• Story : PD-299 — Consolidation PD-298 : robustesse sharing app et durcissement workflow gouvernance
• Domaine : workflow (avec livraisons app et ia-governance, scope partiel backend limité à la règle B2 Gate 8)
• Sources contractuelles : PD-299-specification.md (révision 2026-04-23 21:58), PD-299-tests.md, PD-299-specification-review.md
• Stacks contractuelles :
• ProbatioVault-app : React Native + Expo SDK 54 + TypeScript
• ProbatioVault-ia-governance : Shell (bash/zsh) + Python 3 + Markdown/YAML/JSON
• ProbatioVault-backend (règle B2 seulement) : NestJS + TypeORM + PostgreSQL (pas de livrable de code, cible de contrôle Gate 8)

0. Décisions techniques de résolution des ambiguïtés de la spec¶

Les ambiguïtés et contradictions documentées dans la revue de spécification (§2 à §7) sont tranchées ici par décisions explicites, sans modification de la spec. Chaque décision est référencée dans les hypothèses techniques (§8 H-T-*).

1. Découpage en composants¶

Neuf modules cibles, répartis en deux projets. Aucun chevauchement de files (voir PD-299-code-contracts.yaml).

1.1 ProbatioVault-app (4 modules)¶

1.2 ProbatioVault-ia-governance (5 modules)¶

1.3 Module transverse (hors découpage agents)¶

Justification du regroupement : gov-legal est utilisé à la fois par gov-check-extensions (pour ratification_ref) et par la vérification A8 elle-même, mais ne constitue pas un « agent step 6b » autonome au sens decomposition — il est porté conjointement par gov-check-extensions (les deux scripts vivent ensemble).

2. Flux techniques¶

2.1 F-299-01 — Qualification tests sharing (A1, INV-299-01/02)¶

1. Collecte : le corpus PD-298-tests.md est figé par référence versionnée ; on en extrait les 45 scénarios contractuels.
2. Matérialisation : chaque scénario produit un fichier src/sharing/**/__tests__/<domaine>.<scénario>.test.ts (ou .tsx selon le rendu React Native Testing Library).
3. Comptage de contrôle : jest --listTests --testPathPattern='src/sharing/' doit retourner exactement 45 entrées.
4. Couverture : jest --coverage --collectCoverageFrom='src/sharing/**/*.{ts,tsx}' --coverageThreshold='{"global":{"statements":80,"branches":80,"functions":80,"lines":80}}'.
5. Échec → NON_CONFORME remonté par l'exécuteur CI + blocage Gate 8 par gov-gate-zerotest dès que test_file_count=0 (DEC-01) ou couverture <80%.

2.2 F-299-02 — Guard propriétaire CTA Partager (A2, INV-299-03)¶

1. Source de propriété : proof.ownerUserId (D-299-05) chargé par sharing-api via hook existant useProofDetail(proofId).
2. Source de l'utilisateur courant : useAuth() → currentUser.id (même branded type UserId).
3. Comparaison stricte dans sharing-ui/guards/OwnershipGuard.tsx : isOwner = isValidUuid(ownerUserId) && isValidUuid(currentUser?.id) && ownerUserId === currentUser.id.
4. Rendu : le composant ShareCTA est monté uniquement si isOwner === true. Aucun fallback (INV-299-03).
5. Cas invalide : ownerUserId ou currentUser.id non-UUID → CTA caché silencieusement + log technique SHARE_OWNERSHIP_MISMATCH (DEC-05).

2.3 F-299-03 — Auth réelle appels sharing (A3, INV-299-04)¶

1. Acquisition : SharingApiClient.buildAuthHeader() lit auth_access_token (D-299-06) via useAuth().getAccessToken() (API existante ProbatioVault-app/src/auth).
2. Construction : Authorization: \Bearer ${token}`` avec un seul espace ASCII (conformité RFC 6750 interprétée en plus strict que D-299-07, voir DEC-05 / §7).
3. Validation avant émission : regex exécutée sur la chaîne finale ^Bearer [!-~]+$. Rejet = throw new SharingApiError('SHARE_AUTH_INVALID') sans émission réseau.
4. Masquage : tout log/telemetry/crash reporter applique maskToken() qui remplace la portion après Bearer par <REDACTED_TOKEN> (DEC-10).
5. Token manquant / invalide → SharingApiError('SHARE_AUTH_MISSING'), navigation vers écran login si applicable.

2.4 F-299-04 — Telemetry PII-free allowlist Zod (A4, INV-299-05)¶

1. Schéma canonique dans src/sharing/telemetry/schemas/metadata.ts :

   export const shareTelemetryMetadataSchema = z.strictObject({}).passthrough(false);
   

   Allowlist par défaut vide (D-299-09, §5.2 metadata_allowlist_keys_count_default=0). Toute clé additionnelle future passe par une PR explicite qui étend ce schéma.
2. logShareEvent({ action, metadata }) valide action (enum D-299-08) puis metadata via shareTelemetryMetadataSchema.parse(metadata).
3. Erreur Zod → l'événement est rejeté et une trace technique TELEMETRY_SCHEMA_VIOLATION est émise (DEC-05). Rien n'est persisté, rien n'est envoyé.
4. Initialisation : tous les sites d'appel existants qui passaient {recipientEmail, ip, userAgent, ...} doivent être corrigés en parallèle (A4 exige zéro leak).

2.5 F-299-05 — Fallback maskIp fail-closed (A5, INV-299-06)¶

1. Entrée ip_input (D-299-10). Parsing via ipaddr.js (déjà dépendance PD-298).
2. Si parsing échoue (exception ou ipaddr.isValid(input) === false) → retour littéral exact IP masquée indisponible (D-299-11). Comparaison par identité ===.
3. Aucune restitution de l'entrée brute, ni de fragment (pas de substring, pas de hash).
4. Test d'identité stricte dans sharing-tests : expect(maskIp('<script>')).toBe('IP masquée indisponible').

2.6 F-299-06 — Blocage offline (A6, INV-299-07)¶

1. Hook central useNetworkGuard() dans sharing-ui/hooks/useNetworkGuard.ts : s'abonne à @react-native-community/netinfo et expose isConnected: boolean.
2. Tous les handlers sharing (onCreateShare, onRevokeShare, onLoadShares, onLoadEvents) exécutent if (!netInfo.isConnected) throw new SharingError('SHARE_OFFLINE', t('sharing.offline_blocked')).
3. UI : l'erreur remonte au composant qui affiche un ErrorBanner avec le libellé traduit. Aucun appel API n'est émis.
4. netinfo_is_connected === null est traité comme false (fail-closed, conformément à D-299-12).

2.7 F-299-07 — 6c.bis cross-module (B1, INV-299-10/11)¶

1. /gov-impl étape 6c termine → appel scripts/gov-6cbis.sh <story_id> <project>.
2. Extraction : extract-cross-module-points.py lit la section ## Mécanismes cross-module du plan et produit la liste cross_module_point_path (D-299-16, regex ASCII POSIX). Sortie YAML dans /tmp/<story>-cross-module-expected.yaml.
3. Diff effectif : git -C <project_path> diff --name-only origin/main...HEAD → liste git_diff_path (D-299-17).
4. Comparaison ensembliste : missing = expected - diff. Tolérance 0 (§5.2).
5. Journalisation : chaque exécution écrit une entrée 6cbis dans .gov-local.json avec correlation_id (D-299-22) UUID v4 généré via uuidgen, timestamp ISO8601, liste missing.
6. missing non vide → transition step 7 INTERDITE, le script retourne exit code 2 et un motif listant chaque chemin manquant. gov_signal_escalade est appelé en mode Ringbearer.

2.8 F-299-08 — Gate 8 zéro test déterministe (B2, INV-299-12/13)¶

1. À l'entrée de Gate 8 (CHECKING), gov-gate-zerotest s'exécute avant le scoring arithmétique.
2. Résolution du chemin projet : si project_code ∈ {app,backend}, project_root = dossier git correspondant ; sinon l'étape est un no-op (ERR-299-13).
3. Comptage : find "$project_root/src" -type f \( -name '*.test.ts' -o -name '*.test.tsx' -o -name '*.spec.ts' -o -name '*.spec.tsx' \) | wc -l (DEC-01, DEC-02).
4. Si test_file_count == 0 :
5. test_coverage est forcé à exactement 6.0 dans le verdict JSON, indépendamment de la valeur brute (peut remonter, descendre, ou remplacer une valeur non calculée).
6. Transition CHECKING → NON_CONFORME forcée même si la moyenne arithmétique des autres critères est >= 7.0.
7. Motif : forced_by_zero_test_rule consigné dans le verdict avec raw_test_coverage archivé pour auditabilité.
8. Sinon : scoring arithmétique standard inchangé (F-299-08 branche else).

2.9 F-299-09 — Injection source canonique companion (B3, INV-299-14)¶

1. assemble-prompt.sh lit le besoin de la story courante pour extraire source_story_id (DEC-07, front-matter YAML).
2. Si présent :
3. load-companion-source.py <source_story_id> résout le chemin de la spec source (data/specs-index/<project>/epics/<domain>/<source>/index.yaml → specification_path).
4. Extraction des sections ## 4. Invariants et ## Arbitrages — Vérification formelle post-step 1 via regex de section Markdown (header de niveau 2 + contenu jusqu'au prochain header de niveau ≤ 2).
5. Concaténation : <companion_block> = "source_story_id: " + id + "\n\n## Invariants de la source\n" + invariants_block + "\n\n## Arbitrages de la source\n" + arbitrages_block.
6. Contrôle de taille : len(companion_block.encode('utf-8')) doit être dans [1, 2048] (DEC-03). Hors bornes → rejet avec exit 1 (ERR-299-11).
7. Si absent : la story n'est pas companion, aucune injection (no-op, pas d'erreur).
8. Le bloc est inséré en tête du prompt reviewer, après le template stable, avant les documents d'entrée spécifiques — cohérent avec workflow-rules.md (cache-first).

2.10 F-299-10 — detect-plan-extensions (B6, INV-299-17)¶

1. /gov-check-plan atteint la phase 4 → appel scripts/detect-plan-extensions.py <plan_path> <spec_path>.
2. Extraction plan : parse des sections « endpoints », « headers », « timeouts » (conventions de section Markdown documentées dans .claude/rules/workflow-rules.md).
3. Extraction spec : parse des tableaux de contrats §5.1 / sections équivalentes.
4. Diff par clé : pour chaque endpoint/header/timeout du plan, recherche de la même clé dans la spec. Absence → item {kind, key, status, ratification_ref?}.
5. Validation de schéma stricte :
6. kind ∈ {endpoint, header, timeout} — toute autre valeur → exit 2 + message invalid plan_extension_item.kind.
7. status ∈ {RATIFIED, UNRATIFIED}.
8. Si status=RATIFIED et ratification_ref vide → reclassement en UNRATIFIED_MISSING_PROOF (DEC-04).
9. Blocage : tout item UNRATIFIED* ou erreur de schéma → exit 1 avec liste des items + motif. Message explicite : gate5_blocked_by_unratified_extensions.
10. Artefact : rapport JSON sauvegardé dans data/specs-index/<project>/epics/<domain>/<story>/plan-extensions.yaml (même format pour audits futurs).

2.11 F-299-11 — Validation A8 traçable (INV-299-09)¶

1. Préalable : l'auteur humain remplit docs/epics/<domain>/<story>/PD-299-legal-approvals.yaml avec 3 entrées (ARB-7, ARB-8, RGPD-90J).
2. validate-legal-approvals.py <legal_yaml> exécute :
3. Présence des 3 text_id.
4. Pour chaque entrée : approvals.PO et approvals.LEGAL avec {approver_id, approved_at, jira_comment_id}.
5. approver_id discriminé DEC-06 (email via regex RFC 5322 simplifiée ou username Jira regex ^[A-Za-z0-9][A-Za-z0-9._-]{2,63}$).
6. approved_at parsé ISO8601 (dateutil.parser.isoparse).
7. jira_comment_id non vide + existence effective via GET /rest/api/3/issue/<story>/comment/<id> (token Jira CLAUDE.local.md). 404 → rejet.
8. Unicité DEC-08 : approver_id_PO != approver_id_LEGAL et jira_comment_id_PO != jira_comment_id_LEGAL.
9. Sortie JSON : {assurance_level: "traceability_only", verdict: "PASS|FAIL", details: [...]} (DEC-09).
10. A8 est conforme si et seulement si le verdict est PASS pour les 3 entrées.

2bis. Diagramme de dépendances agents (step 6b)¶

graph LR
    subgraph Wave1_App["Wave 1 — ProbatioVault-app (parallélisables)"]
        AT[sharing-types<br/>(existant PD-298)]
        AE[sharing-telemetry<br/>A4 A5]
        AA[sharing-api<br/>A3]
        AU[sharing-ui<br/>A2 A6 A7]
    end

    subgraph Wave2_Tests["Wave 2 — Tests app"]
        STS[sharing-tests<br/>A1]
    end

    subgraph Wave1_Gov["Wave 1 — ProbatioVault-ia-governance (parallélisables)"]
        G6[gov-6cbis<br/>B1]
        G8[gov-gate-zerotest<br/>B2]
        GC[gov-assemble-companion<br/>B3]
        GP[gov-check-extensions<br/>B6]
        GD[gov-docs-guardrails<br/>B4 B5]
    end

    subgraph Wave3_Legal["Wave 3 — A8 Legal"]
        LEG[gov-legal<br/>A8]
    end

    AT --> AE
    AT --> AA
    AE --> AU
    AA --> AU
    AE --> STS
    AA --> STS
    AU --> STS

    GP --> LEG
    G6 -.shared helper.-> GH[gov-interact.sh<br/>existant]
    G8 -.shared helper.-> GH

Waves d'exécution :

• Wave 1 (parallèle) : 4 agents app + 5 agents gov exécutables en parallèle (pas de dépendance cross-agent ni cross-projet). Les modules app s'appuient sur sharing-types déjà livré par PD-298.
• Wave 2 (séquentielle après Wave 1 app) : sharing-tests qui exécute les 4 modules app.
• Wave 3 (séquentielle après Wave 1 gov) : gov-legal qui est consommé par gov-check-extensions pour ratification_ref et utilisé seul pour A8.

2ter. Mécanismes cross-module (OBLIGATOIRE)¶

Le flux sharing interagit avec le module preuves (ProbatioVault-app/src/proofs) dont une route/écran doit être protégée.

cross_module_point_path attendus dans le diff (6c.bis) :

• ProbatioVault-app/src/proofs/screens/ProofDetailScreen.tsx (injection du guard)
• ProbatioVault-app/src/sharing/guards/OwnershipGuard.tsx (nouveau composant)
• ProbatioVault-app/src/sharing/guards/index.ts (export)

3. Mapping invariants → mécanismes¶

4. Mapping critères d'acceptation → mécanismes¶

5. Mapping tests (TC-*) → mécanismes + observables¶

5.1 Tests nominaux¶

5.2 Tests d'erreur¶

5.3 Tests de non-régression¶

5.4 Tests négatifs/adversariaux¶

6. Gestion des erreurs¶

6.1 Table des codes d'erreur (DEC-05)¶

6.2 Propagation et isolement¶

• Côté app : toutes les erreurs typées dérivent de SharingError. Le wrapper React Native ErrorBoundary capture l'erreur dans chaque écran et affiche ErrorBanner sans révéler de détails techniques.
• Côté gov : chaque script shell/Python retourne un exit code ≠ 0 pour tout blocage, avec un message stderr contenant le code DEC-05. L'orchestrateur /gov* capture l'exit code et interrompt la transition concernée.
• Corrélation : chaque événement gouvernance inclut un correlation_id UUID v4 (D-299-22) généré à l'entrée de Gate 8/6c.bis/phase 4 et propagé dans tous les sous-appels.

7. Impacts sécurité¶

7.1 Risques identifiés¶

7.2 Points de conformité¶

• RGPD : la règle telemetry allowlist Zod stricte (INV-299-05) élimine toute PII involontaire ; la rétention 90 jours de la notice RGPD est une donnée textuelle validée humainement (hors périmètre vérification automatique §10.2 spec).
• Art. II CONSTITUTIONAL (séparation des pouvoirs) : la règle d'unicité DEC-08 matérialise l'impossibilité d'auto-approbation PO+LEGAL sur un même texte.
• Art. I CONSTITUTIONAL (quality gates) : la règle B2 zéro test rend la Gate 8 plus conservatrice sans introduire de contournement.

7.3 Journalisation requise¶

• correlation_id (D-299-22) dans chaque entrée d'audit (6c.bis, Gate 8, phase 4, validation A8).
• Bundle probatoire par story : rapport coverage, comptage tests, verdict Gate 8, rapport 6c.bis, rapport plan-extensions.yaml, rapport legal-validation.yaml. Agrégé via scripts/gov-compounder existant.

8. Hypothèses techniques¶

Hypothèses spec reprises (H-299-01 à H-299-05 du §9 spec) intégrées implicitement : H-T-07 couvre H-299-01, H-T-02 couvre H-299-03, H-T-11 couvre H-299-05.

9. Points de vigilance (risques, dette, pièges)¶

9.1 Ambiguïtés spec résolues par décision (à re-confirmer en Gate 5)¶

• DEC-01/DEC-02 glob récursif et échelle projet : la spec laissait les deux dimensions ambigües (E-AMB-03, E-AMB-04). La décision ici est la plus sûre (récursif + projet) mais doit être validée explicitement par le PO en Gate 5 ; sinon risque d'écart interprétatif avec l'équipe d'audit.
• DEC-03 borne min 1 byte : contredit la lecture littérale de §5.2 (min=0 KiB). Alignement avec §5.1 assumé ; à ratifier par Gate 5.
• DEC-04 RATIFIED sans ratification_ref : la spec autorise le champ optionnel mais DEC-04 le rend obligatoire pour RATIFIED. Décision plus stricte = plus sûre, à ratifier.
• DEC-05 codes d'erreur fermés : extension spec non ratifiée (au sens B6 du flux !). Méta-risque : l'introduction de ces codes peut elle-même déclencher detect-plan-extensions phase 4 → les codes DOIVENT être listés comme « headers/timeouts/endpoints » si applicable, sinon classés comme « constantes applicatives hors portée detect-plan-extensions » (documenté dans gov-check-extensions).

9.2 Dettes techniques assumées¶

• Non-répudiation « minimale » ambiguë : la sortie JSON traceability_only documente la limite (DEC-09) mais le vocabulaire spec reste confus. Dette documentaire portée dans le REX → proposer une réécriture de la spec en itération future.
• Homoglyphes Unicode : mitigation basique NFKC seulement ; pas de dictionnaire homoglyphe exhaustif. Risque résiduel accepté.
• Idempotence detect-plan-extensions (E-HD-02) : script déterministe en entrée mais pas d'état persistant ; chaque run recrée le rapport. OK tant que Gate 5 ne conserve pas d'historique entre runs.
• Atomicité non garantie en re-gate concurrentiel (E-HD-05) : l'implémentation suppose un seul processus Gate 8 par story à un instant donné (verrouillage implicite via .gov-local.json).

9.3 Pièges spécifiques à l'intégration¶

• gov-6cbis.sh parsing du plan : la section « Mécanismes cross-module » doit être structurée identiquement à PD-299-plan.md §2ter. Un plan sans cette section produit un no-op silencieux → extract-cross-module-points.py doit rejeter les plans dépourvus de section avec un code d'erreur explicite.
• Ordre d'exécution Gate 8 : gov-gate-zerotest doit s'exécuter avant tout autre check sinon la priorité INV-299-12 peut être contournée. Test TC-NOM-21 vérifie cet ordre.
• assemble-prompt.sh cache-first : l'ajout du bloc companion doit respecter l'ordre contenu statique → dynamique (workflow-rules.md). Le bloc companion, bien que dynamique par source_story_id, reste stable pour une même story — à placer dans la portion cacheable.

9.4 Risques projet¶

• Le scope couvre 2 projets et 1 scope partiel backend : coordination inter-repos nécessaire en step 6b. Les agents gov et app sont indépendants (pas de dépendance cross-projet directe) mais partagent la story Jira.
• 9 modules en step 6b ≈ pression sur le prompt caching : conserver strictement l'ordre d'assemblage.
• Gate 8 sur la story PD-299 elle-même : en mode gouvernance, test_file_count est calculé sur ProbatioVault-ia-governance (= ia-governance → hors scope INV-299-12), donc la règle B2 ne s'applique pas à PD-299 côté gov — à contrôler pour éviter un faux positif récursif.

10. Hors périmètre¶

Alignement avec la spec §2 « Exclu » et §10.2 « Points hors périmètre vérification automatique » :

• Refonte globale du module sharing (hors A1-A8).
• Modification des règles de scoring Gate 3 et Gate 5 (seule Gate 8 est modifiée via B2).
• Automatisation de la décision juridique de fond.
• Vérification automatique de la validité juridique substantielle des textes ARB-7/ARB-8/RGPD-90j.
• Vérification cryptographique de l'intention des approbateurs (au-delà de la trace Atlassian).
• Vérification automatique de la pertinence métier des arbitrages PO.
• Écriture sur des routes du module preuves autres que le point d'intégration ProofDetailScreen (le guard est additif, pas intrusif).
• Implémentation d'un mécanisme d'expiration applicative pour la rétention 90 jours (donnée textuelle §5.3 spec).
• Intégration de nouveaux MCP, de nouveaux modèles LLM ou de nouvelles infrastructures.

11. Périmètre de test (OBLIGATOIRE)¶

Justifications hors scope : aucune exclusion autre que performance (non demandée) et audit sécurité externe (hors CI). Tous les autres niveaux sont couverts.

12. Code contracts similaires (réutilisation décisions)¶

Références principales identifiées a priori :

• PD-298 sharing-masking : patterns de déterminisme maskIp et fallback fermé — réutilisé à l'identique pour INV-299-06.
• PD-298 sharing-validation : branded types + regex stricts — réutilisés pour D-299-05 (UUID v4), D-299-07 (header Bearer).
• PD-297 ontologie-enrichissement : patterns d'extraction de sections Markdown — réutilisés pour load-companion-source.py et extract-cross-module-points.py.
• PD-296 formal-check.sh : convention exit code + verdict JSON + correlation_id — réutilisée pour gov-6cbis.sh, detect-plan-extensions.py, validate-legal-approvals.py.

13. Références¶

• Epic : Référence épique (valeur métier non renseignée, Q-299-01).
• Jira : PD-299.
• Repos concernés : ProbatioVault-app, ProbatioVault-ia-governance (scope B2 supervisant ProbatioVault-backend).
• Documents associés :
• PD-299-besoin.md
• PD-299-specification.md
• PD-299-tests.md
• PD-299-specification-review.md
• PD-298-code-contracts.yaml
• gov-impl.md
• gov-gate.md
• gov-check-plan.md
• assemble-prompt.sh
• workflow-rules.md
• learnings-universal.md