PD-299 — Consolidation PD-298 : robustesse sharing app et durcissement workflow gouvernance¶

1. Objectif¶

La User Story PD-299 DOIT résorber la dette technique identifiée sur PD-298 côté application mobile et DOIT ajouter des garde-fous de gouvernance empêchant la récurrence des mêmes écarts (tests absents, points cross-module oubliés, extensions plan→spec non ratifiées, prompts companion incomplets).

2. Périmètre / Hors périmètre¶

Inclus¶

• A1 à A7 côté ProbatioVault-app (tests sharing, guard owner, auth réelle, telemetry PII-free, fallback maskIp, blocage offline, correction useProofShares).
• A8 avec critère testable de preuve de validation humaine PO/Legal des textes ARB-7, ARB-8 et notice RGPD 90 jours.
• B1 à B6 côté ProbatioVault-ia-governance (check 6c.bis, cap Gate 8 zéro test, injection companion source, règle learnings universelle, traçabilité placeholders 6a, détection plan→spec).
• Blocage explicite des transitions de workflow quand une condition contractuelle échoue.

Exclu¶

• Refonte globale du module sharing.
• Modification des règles de scoring Gate 3 et Gate 5.
• Automatisation de la décision juridique de fond par IA.
• Vérification automatique de la validité juridique substantielle des textes ARB-7/ARB-8/RGPD-90j (hors périmètre vérification automatique).
• Vérification automatique de l’intention réelle d’un approbateur humain au-delà de la trace Atlassian (hors périmètre vérification automatique).
• Vérification automatique de la pertinence métier des arbitrages PO et des décisions de ratification au-delà de leur présence formelle (hors périmètre vérification automatique).

3. Définitions¶

4. Invariants (non négociables)¶

5. Flux nominaux¶

5.1 Modèle de données contractuel (source unique des formats)¶

Référencement unique : les sections §6 à §8 réutilisent ces IDs (D-299-*) sans redéfinition de format.

5.2 Bornes numériques contractuelles¶

5.3 SLA temporels (transitions)¶

Aucune transition temporelle identifiée.

Note contractuelle : la mention “rétention 90 jours” est une donnée textuelle à valider (D-299-21), pas un mécanisme d’expiration d’état applicatif dans PD-299.

5.4 Machine d’états (Gate 8 test-coverage)¶

Portée contractuelle : cette FSM fermée s’applique uniquement à Gate 8. Les enchaînements workflow (6c→6c.bis→7, Gate 5 plan→spec) restent des gardes séquentielles hors FSM.

États : PENDING, CHECKING, NON_CONFORME, GO, RESERVE, ESCALADE.

État PENDING¶

État CHECKING¶

État NON_CONFORME¶

Comportement retour (NON_CONFORME -> PENDING) :

1. La transition réouvre l’évaluation via PENDING -> CHECKING.
2. Les checks sont réappliqués séquentiellement, non atomiquement, dans l’ordre logique de §5.4.
3. Étape 1 : pré-check zéro-test (INV-299-12/13). Si échec, CHECKING -> NON_CONFORME immédiat et arrêt de l’évaluation.
4. Étape 2 : uniquement si étape 1 passe, scoring arithmétique standard et application de la transition correspondante.
5. Le premier check en échec suffit à maintenir NON_CONFORME.
6. Les gardes workflow hors FSM (6c.bis, plan→spec) restent évaluées séparément dans leurs commandes dédiées.

États terminaux¶

Checklist machine à états :

• Chaque état a ses transitions sortantes autorisées/interdites.
• Chaque état terminal mentionne explicitement -> * : INTERDITE (état terminal, résolution manuelle uniquement).
• Le scope de fermeture est explicitement limité à la FSM Gate 8.
• Modèle couvert par invariant dédié (INV-299-18).

5.5 Flux nominaux contractuels¶

1. F-299-01 — Qualification tests sharing
   Précondition : module src/sharing/ ciblé.
   Le corpus PD-298-tests est matérialisé en 45 tests Jest.
   Le run de couverture du module respecte >= 80%.
   Sinon : NON_CONFORME.

2. F-299-02 — Guard propriétaire CTA partage
   Le rendu CTA dépend strictement de D-299-05.
   Si IDs non égaux ou invalides : CTA absent.
   Aucun fallback permissif.

3. F-299-03 — Auth réelle appels sharing
   Tout appel sharing construit D-299-07 à partir de D-299-06.
   Le header DOIT respecter ^Bearer [ ]+[!-~]+$ (pas de CR/LF, pas de caractères de contrôle).
   Si token ou header invalide : appel annulé et erreur explicite.

4. F-299-04 — Telemetry PII-free
   action valide (D-299-08).
   metadata soumise à D-299-09.
   Toute clé hors allowlist : rejet log.

5. F-299-05 — Masquage IP fail-closed
   Entrée IP invalide (D-299-10) => sortie D-299-11.
   La valeur brute initiale n’est jamais restituée.

6. F-299-06 — Blocage offline
   Si D-299-12 ≠ true, création/révocation/chargement sharing bloqués.
   Message utilisateur explicite obligatoire.

7. F-299-07 — Contrôle 6c.bis cross-module
   Après 6c, extraction de D-299-16 depuis le plan.
   Vérification présence dans D-299-17.
   Au moins un manquant => step 7 interdit.

8. F-299-08 — Gate 8 zéro test déterministe
   Gate 8 passe en CHECKING.
   Si project_code ∈ {app,backend} et D-299-14 = 0 (glob *.{test,spec}.{ts,tsx}) : D-299-15 est forcé à exactement 6.0, quelle que soit la valeur brute, puis transition forcée CHECKING -> NON_CONFORME.
   Pour autres projets : scoring arithmétique standard inchangé.

9. F-299-09 — Prompts companion enrichis avec source canonique
   Pour D-299-18, assemble-prompt charge la source canonique companion (<story_source_id>-specification.md, sections ## 4. Invariants et ## Arbitrages — Vérification formelle post-step 1).
   Le bloc stable inclut D-299-19 + source_story_id.
   Bloc absent/incomplet => prompt reviewer non conforme.

10. F-299-10 — Détection plan→spec avec validation de schéma
    /gov-check-plan phase 4 produit la liste D-299-20.
    Si kind hors enum : rejet explicite du check (invalid plan_extension_item.kind) + blocage Gate 5.
    Sinon, si au moins un status=UNRATIFIED : blocage + ratification PO exigée.

11. F-299-11 — Validation légale A8 traçable
    Existence de D-299-21 pour ARB-7, ARB-8, RGPD-90J avec rôles PO+LEGAL.
    Chaque approbation inclut approver_id, approved_at, jira_comment_id (non-répudiation minimale via trace Atlassian).
    Si incomplet : A8 non validé.

5.6 Contraintes inter-modules¶

5.7 Clauses obligatoires non applicables¶

• Stratégie de migration DDL : non applicable (aucune modification de colonne SQL).
• Atomicité multi-composant DB + queue/append-only : non applicable.
• Mécanismes de protection distribuée : Aucun mécanisme de protection distribuée applicable (module synchrone mono-instance).
• Invariant envelope encryption crypto : non applicable (domaine workflow + sharing, pas crypto/crypto-proof).

5bis. Diagrammes (applicable)¶

Diagramme d’état¶

stateDiagram-v2
    [*] --> PENDING

    PENDING --> CHECKING: start Gate 8
    PENDING --> NON_CONFORME: INTERDITE
    PENDING --> GO: INTERDITE
    PENDING --> RESERVE: INTERDITE
    PENDING --> ESCALADE: INTERDITE

    CHECKING --> NON_CONFORME: project in app/backend && test_count==0 => test_coverage:=6.0 (exact, ignore raw) OR arithmetic non-conforme
    CHECKING --> GO: arithmetic GO (if no zero-test trigger)
    CHECKING --> RESERVE: arithmetic RESERVE (if no zero-test trigger)
    CHECKING --> ESCALADE: technical/human block
    CHECKING --> PENDING: INTERDITE

    NON_CONFORME --> PENDING: corrections + re-gate
    NON_CONFORME --> ESCALADE: v3 non-conforme or convergence plateau
    NON_CONFORME --> GO: INTERDITE
    NON_CONFORME --> RESERVE: INTERDITE

    GO --> PENDING: INTERDITE (etat terminal)
    GO --> CHECKING: INTERDITE (etat terminal)
    GO --> NON_CONFORME: INTERDITE (etat terminal)
    GO --> ESCALADE: INTERDITE (etat terminal)

    RESERVE --> PENDING: INTERDITE (etat terminal)
    RESERVE --> CHECKING: INTERDITE (etat terminal)
    RESERVE --> NON_CONFORME: INTERDITE (etat terminal)
    RESERVE --> ESCALADE: INTERDITE (etat terminal)

    ESCALADE --> PENDING: INTERDITE (etat terminal)
    ESCALADE --> CHECKING: INTERDITE (etat terminal)
    ESCALADE --> NON_CONFORME: INTERDITE (etat terminal)
    ESCALADE --> GO: INTERDITE (etat terminal)
    ESCALADE --> RESERVE: INTERDITE (etat terminal)

Diagramme de séquence¶

sequenceDiagram
    participant GI as /gov-impl
    participant Git as Git diff
    participant GG as /gov-gate
    participant VS as verdict-scoring
    participant AP as assemble-prompt.sh
    participant Src as Story source artifacts
    participant GCP as /gov-check-plan
    participant DPE as detect-plan-extensions
    participant FSM as Jira/FSM

    GI->>GI: extract(cross_module_point_path[]) depuis plan
    GI->>Git: diff_paths()
    GI->>GI: missing = cross_module_point_path - diff_paths
    alt missing > 0
        GI->>FSM: block(step7, reason=missing_cross_module_files)
    else missing == 0
        GI->>FSM: allow(step7)
    end

    GG->>GG: test_count = count(find(src/{module}, "*.{test,spec}.{ts,tsx}"))
    alt project in {app,backend} and test_count==0
        GG->>VS: test_coverage = 6.0 (forced exact, independent of raw)
        VS-->>GG: verdict=NON_CONFORME
        GG->>FSM: transition(CHECKING->NON_CONFORME)
    else
        GG->>VS: verdict = arithmetic(scores)
        VS-->>GG: GO/RESERVE/NON_CONFORME/ESCALADE
        GG->>FSM: transition according to verdict
    end

    AP->>Src: load_canonical(source_story_spec, sections=invariants+arbitrages)
    Src-->>AP: source_block + source_story_id
    AP->>AP: stable_prompt = template_stable + source_block
    AP-->>GG: reviewer_prompt(stable_prompt)

    GCP->>DPE: diff(plan.endpoints|headers|timeouts, spec.contracts)
    DPE-->>GCP: extension_items(kind,status,ratification_ref)
    alt exists kind hors enum
        GCP->>FSM: block(Gate5, reason=invalid_extension_kind) + explicit_error
    else exists UNRATIFIED
        GCP->>FSM: block(Gate5) + request_PO_ratification
    else
        GCP->>FSM: allow(Gate5)
    end

6. Cas d’erreur¶

7. Critères d’acceptation (testables)¶

8. Scénarios de test (Given / When / Then)¶

1. Given le module sharing sans tests sur *.{test,spec}.{ts,tsx}, When la campagne A1 est exécutée, Then 45 tests sont présents et la couverture atteint au moins 80%.
2. Given un utilisateur non propriétaire, When l’écran preuve est affiché, Then le CTA “Partager” n’est pas rendu.
3. Given un token valide en stockage sécurisé, When un appel sharesApi.* est déclenché, Then le header Authorization respecte D-299-07 (^Bearer [ ]+[!-~]+$).
4. Given une metadata contenant recipientEmail, When logShareEvent est invoqué, Then une erreur de validation est levée et rien n’est logué.
5. Given une IP invalide, When maskIp est appelé, Then la valeur retournée est IP masquée indisponible.
6. Given NetInfo.isConnected=false, When l’utilisateur tente de créer/révoquer un partage, Then l’action est bloquée avec erreur explicite.
7. Given proofId undefined, When l’écran détail partage se charge, Then aucun appel useProofShares(undefined) n’est autorisé.
8. Given des points cross-module déclarés au plan, When 6c.bis compare avec le diff et qu’un fichier manque, Then step 7 est bloqué.
9. Given Gate 8 sur projet app avec test_file_count=0, When pré-verdict s’exécute, Then test_coverage est forcé à 6.0 exactement et le verdict passe en NON_CONFORME, même si la moyenne arithmétique resterait >= 7.
10. Given une story companion avec source canonique disponible, When assemble-prompt construit le reviewer prompt, Then le bloc stable contient arbitrages PO et invariants source avec source_story_id.
11. Given une extension endpoint/header/timeout non ratifiée ou un kind invalide, When /gov-check-plan phase 4 exécute detect-plan-extensions, Then Gate 5 est bloquée avec erreur explicite.
12. Given A8, When la vérification de clôture est faite, Then la preuve PO+Legal signée et horodatée est requise pour ARB-7, ARB-8 et RGPD-90j via commentaires Jira traçables.

9. Hypothèses explicites¶

10. Points à clarifier¶

10.1 Contraintes techniques (stack projet cible)¶

Contrainte explicite : aucune substitution de stack n’est autorisée (ex. pas de Swift/SwiftUI pour l’app, pas de Spring Boot pour le backend).

10.2 Questions ouvertes¶

Références¶

• Epic : Référence épique (valeur métier non renseignée).
• JIRA : PD-299.
• Repos concernés : ProbatioVault-app, ProbatioVault-ia-governance.
• Documents associés :
• PD-299-besoin.md
• gov-impl.md
• gov-gate.md
• gov-check-plan.md
• assemble-prompt.sh
• 6a Decomposition.md
• learnings-universal.md
• PD-298-specification.md

Arbitrages — Vérification formelle post-step 1¶

Score : 96.5/100 — 6 flow_gaps MEDIUM (faux positifs documentés).

Les 6 issues détectées concernent des états du cycle de vie preuve (PD-279 : restituted, sealed, expired, disposed) absents du FSM §5.4 de PD-299. Ce FSM modélise exclusivement le scoring Gate 8 (états PENDING/CHECKING/NON_CONFORME/GO/RESERVE/ESCALADE), pas le cycle de vie des preuves. Les deux FSM sont orthogonaux.

Décision : faux positifs, workflow non bloqué.