PD-295 — Spécification v3¶

1. Objectif¶

La User Story PD-295 DOIT transformer la bibliothèque documentaire existante en mémoire vivante injectée automatiquement au step 0, en ajoutant cinq briques contractuelles :

• B1 : index sémantique des fiches de veille.
• B2 : persistance et index des clarifications PO step 0.
• B3 : scoring de réutilisation des learnings.
• B4 : promotion de portée et éviction stale des learnings.
• B5 : injection unifiée learnings + veille + clarifications.

La story DOIT préserver les mécanismes existants sans régression.

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

Inclus¶

• Ajout des artefacts B1..B5 (JSONL, FAISS, NPY, scripts, commandes).
• Injection step 0 des trois sources avec traces systématiques.
• Ventilation compounding par source.
• Migration fonctionnelle learnings.jsonl avec scope.
• Promotion/éviction selon règles explicites.
• Réindexation globale avec phases veille + clarifications.
• Signature/horodatage des événements via clé HMAC Vault versionnée.
• Script contractuel scripts/rotate-audit-hmac.sh (rotation manuelle clé audit).
• Baseline CS-1 via scripts/measure-cs1-baseline.py.
• KPI CS-2/CS-3/CS-4 via scripts/measure-cs2.sh, scripts/measure-cs3.sh, scripts/measure-cs4.sh.
• /morning obligatoire avec top 3 réutilisés.
• Rétention clarifications 18 mois avec purge déclenchée par step 10, hook on_story_close, et cron quotidien.

Exclu¶

• Migration de stack hors FAISS + Ollama + Markdown/YAML/JSONL.
• Remplacement des skills existants.
• Nouveau moteur de stockage (Elasticsearch, pgvector, SQLite, graph DB).
• Reranker neural, BM25 hybride, classifier d’intention, skill router auto, boucle adaptative.
• Refonte specs-index/**/*.yaml.
• Architecture L1/L2/L3/L4.
• Attribution causale mono-facteur “injection => GO Gate 8” sans protocole statistique dédié.

3. Définitions¶

4. Invariants (non négociables)¶

5. Flux nominaux¶

5.1 Modèle de données canonique (source unique)¶

5.1.1 Champs partagés¶

5.1.2 data/veille.jsonl¶

5.1.3 PD-XX-clarifications.md¶

5.1.4 data/learnings-scores.jsonl¶

Jointure officielle avec learnings.jsonl : {story, gate, tag_hash}.
Score absent : reuse_score=0.0, reuse_score_brut=0.0.

5.1.5 data/learnings.jsonl (étendu)¶

Règle d’intégrité : les tags d’un learning historique sont immuables.
Si dérive détectée (learning_id recalculé différent), ligne exclue du scoring et log learning_id_drift.

5.1.6 data/learnings-injections.jsonl (trace unifiée signée)¶

Format événement obligatoire :

{
  "event": "learning_injected",
  "timestamp_iso8601": "2026-04-11T09:42:17Z",
  "story_id": "PD-295",
  "step": 0,
  "source": "learning",
  "domain": "auth-identity",
  "project": "backend",
  "operation": "step0_injection",
  "timestamp_bucket": "2026-04-11T09:40:00Z",
  "query": "mfa b2b priorites",
  "query_hash": "sha256:...",
  "count": 5,
  "result_ids": ["PD-19-3-a1b2c3d4e5f6"],
  "key_version": 12,
  "signature_hmac_sha256": "hex...",
  "schema_version": 3
}

Règles contractuelles :

• Clé idempotence : {story_id, step, operation, timestamp_bucket}.
• timestamp_bucket : arrondi 5 minutes UTC.
• query.length <= 500 caractères, sinon ERR-295-17 QUERY_TOO_LONG.
• count == len(result_ids), sinon événement ignoré + log audit_inconsistent_trace.
• Signature : hmac_sha256(payload_canonique, secret_key).
• Clé HMAC :
• secret_key = vault_read("kv/pd-295/memory-audit-hmac").data.key
• clé binaire 32 octets (générée au déploiement via openssl rand -hex 32)
• key_version de Vault est sérialisée dans chaque événement
• Rotation manuelle :
• opérateur exécute scripts/rotate-audit-hmac.sh
• nouvelle clé écrite dans kv/pd-295/memory-audit-hmac
• ancienne clé archivée dans kv/pd-295/memory-audit-hmac/archive/{date}
• événement audit_key_rotated signé émis avec nouvelle key_version
• Vérification a posteriori :
• vérificateur lit key_version
• version active : lecture chemin principal
• version historique : lecture archive correspondante
• Vault indisponible au démarrage :
• fail-closed
• aucun événement audit émis
• ERR-295-16 AUDIT_KEY_UNAVAILABLE
• skill /gov interrompu
• Bootstrap initial clé : opération humaine documentée, pas d’auto-bootstrap.

5.2 Bornes numériques obligatoires¶

5.3 Clarifications JSONL + SLA¶

5.3.1 Schéma data/clarifications.jsonl¶

{
  "story": "PD-42",
  "domain": "auth-identity",
  "project": "backend",
  "date": "2026-03-15",
  "path": "docs/epics/auth-identity/PD-42-mfa/PD-42-clarifications.md",
  "questions": [
    {"id": "Q1", "theme": "probleme", "answer": "..."},
    {"id": "Q2", "theme": "criteres", "answer": "..."},
    {"id": "Q3", "theme": "contraintes", "answer": "..."},
    {"id": "Q4", "theme": "priorites", "answer": "..."}
  ],
  "retention_until": "2027-09-15"
}

Fichier invalide : ligne exclue + log.

5.3.2 SLA temporels¶

5.4 Machine à états des learnings (transitions + retours)¶

États : STORY_ACTIVE, DOMAIN_ACTIVE, GLOBAL_ACTIVE, ARCHIVED.

STORY_ACTIVE : - STORY_ACTIVE -> DOMAIN_ACTIVE : AUTORISÉE (reuse_score>=0.30 && nb_domains>=1). - STORY_ACTIVE -> GLOBAL_ACTIVE : INTERDITE. - STORY_ACTIVE -> ARCHIVED : AUTORISÉE (nb_injections==0 && age>56 jours).

DOMAIN_ACTIVE : - DOMAIN_ACTIVE -> GLOBAL_ACTIVE : AUTORISÉE (reuse_score>=0.60 && nb_domains>=2). - DOMAIN_ACTIVE -> STORY_ACTIVE : INTERDITE (downgrade auto). - DOMAIN_ACTIVE -> ARCHIVED : INTERDITE dans PD-295 (choix de périmètre explicite).

GLOBAL_ACTIVE : - GLOBAL_ACTIVE -> DOMAIN_ACTIVE : INTERDITE. - GLOBAL_ACTIVE -> STORY_ACTIVE : INTERDITE. - GLOBAL_ACTIVE -> ARCHIVED : INTERDITE dans PD-295 (choix de périmètre explicite).

ARCHIVED : - ARCHIVED -> STORY_ACTIVE : AUTORISÉE uniquement manuellement via scripts/restore-learning.py --id <learning_id>. - ARCHIVED -> DOMAIN_ACTIVE : INTERDITE. - ARCHIVED -> GLOBAL_ACTIVE : INTERDITE.

Règles :

• Aucun downgrade automatique.
• restore-learning.py émet un événement signé avec la même politique Vault (INV-295-20), incluant key_version.

5.5 Flux nominal N1 — B1 Index veille¶

1. Collecter les fiches veille et produire data/veille.jsonl.
2. Indexer embeddings 768 + FAISS.
3. Exposer recherche avec --impact, --verdict.
4. Tracer les injections veille (source=veille) avec signature Vault.
5. Intégrer la phase veille dans reindex-all.

5.6 Flux nominal N2 — B2 Clarifications step 0¶

1. Poser les 4 questions PO step 0 (tous modes).
2. Persister PD-XX-clarifications.md verbatim avant rédaction besoin.
3. Collecter en data/clarifications.jsonl conforme §5.3.1.
4. Indexer corpus clarifications.
5. Rechercher avec --domain et --project obligatoires.
6. Tracer source=clarification signé.
7. Purger >18 mois via :
8. step 10 gov-compounder,
9. hook on_story_close (REJECTED, DONE_WITH_ANOMALY),
10. cron quotidien de sécurité.

5.7 Flux nominal N3 — B3 Scoring de réutilisation¶

1. Acquérir locks (ordre fixe) : SH learnings.jsonl.lock, puis EX learnings-scores.jsonl.lock.
2. Lire learnings.jsonl, learnings-injections.jsonl, metrics.jsonl.
3. Calculer reuse_score_brut, puis reuse_score=tanh(reuse_score_brut/10).
4. Écrire data/learnings-scores.jsonl (parallèle).
5. Trier search-learnings par distance FAISS puis reuse_score secondaire.
6. --min-score optionnel (<=0.99).
7. /morning publie 3 top scores ; succès observable code retour 0, sinon ERR-295-19.
8. Geler baseline CS-1 via scripts/measure-cs1-baseline.py à la date merge B5.
9. Libérer les deux locks.

5.8 Flux nominal N4 — B4 Promotion + éviction¶

1. Détecter si migration scope est nécessaire (au moins une ligne sans scope).
2. Si migration nécessaire, vérifier précondition commit git (INV-295-16), sinon passer.
3. Acquérir EX lock sur learnings.jsonl.lock puis learnings-scores.jsonl.lock.
4. Migrer scope: story uniquement pour lignes sans scope.
5. Promouvoir selon seuils.
6. Archiver stale (scope=story, 0 injection, >56 jours).
7. Exclure archivés de l’index actif à la réindexation suivante.
8. Libérer locks ; journaliser événement signé avec key_version.

5.9 Flux nominal N5 — B5 Injection unifiée step 0¶

1. Construire requêtes depuis {story_id,title,domain,project}.
2. Acquérir SH lock sur learnings.jsonl.lock puis learnings-scores.jsonl.lock.
3. Évaluer d’abord le rate-limit (fenêtre glissante) ; dépassement => ERR-295-11.
4. Évaluer ensuite idempotence bucket 5 min.
5. Lancer en parallèle :
6. search-learnings ... --top-k 5 --trace
7. search-veille ... --top-k 3 --trace
8. search-clarifications.py --domain {story.domain} --project {story.project} --top-k 3 --trace
9. Assembler bloc Markdown à 3 sections distinctes.
10. Appliquer cardinalités fixes 5/3/3 ; si count=0 section présente avec “aucun résultat”.
11. Tracer chaque source (événements signés, key_version).
12. 1 ou 2 sources indisponibles : injection partielle + état dégradé.
13. 3 sources indisponibles : blocage step 0 (ERR-295-06).
14. Libérer les deux locks.

5.10 Stratégie de migration DDL¶

Aucune migration DDL SQL applicable.

5.11 Atomicité multi-composant¶

Aucun flux DB+queue introduit ; non applicable.

5.12 Mécanismes de protection distribuée¶

5.13 Contraintes inter-modules¶

5bis. Diagrammes¶

Diagramme d’état¶

stateDiagram-v2
    [*] --> STORY_ACTIVE

    note right of STORY_ACTIVE
      Garde B4: migration scope autorisée
      seulement si commit git préalable
      quand au moins une ligne sans scope
    end note

    STORY_ACTIVE --> DOMAIN_ACTIVE : score>=0.30 && nb_domains>=1
    STORY_ACTIVE --> ARCHIVED : nb_injections=0 && age>56j
    DOMAIN_ACTIVE --> GLOBAL_ACTIVE : score>=0.60 && nb_domains>=2
    ARCHIVED --> STORY_ACTIVE : restore-learning.py (manuel, event signé Vault)

    note left of STORY_ACTIVE
      Transitions interdites explicitement rejetées:
      STORY->GLOBAL, DOMAIN->STORY, DOMAIN->ARCHIVED,
      GLOBAL->DOMAIN, GLOBAL->STORY, GLOBAL->ARCHIVED
    end note

Diagramme de séquence¶

sequenceDiagram
    participant S0 as gov-step-0
    participant INJ as gov-learnings-inject
    participant L1 as learnings.jsonl.lock
    participant L2 as learnings-scores.jsonl.lock
    participant SRCH as search-*
    participant TRACE as learnings-injections.jsonl
    participant VLT as Vault

    S0->>INJ: {story_id,domain,project,title}
    INJ->>VLT: read kv/pd-295/memory-audit-hmac
    alt vault indisponible
      INJ-->>S0: ERR-295-16 (fail-closed)
    else vault disponible
      INJ->>L1: LOCK_SH (timeout 30s, fail-closed ERR-295-09)
      INJ->>L2: LOCK_SH (timeout 30s, fail-closed ERR-295-09)
      INJ->>INJ: rate-limit glissant puis idempotence bucket
      par learning
        INJ->>SRCH: search-learnings --top-k 5 --trace
      and veille
        INJ->>SRCH: search-veille --top-k 3 --trace
      and clarification
        INJ->>SRCH: search-clarifications --domain --project --top-k 3 --trace
      end
      SRCH->>TRACE: append events signés + key_version
      INJ-->>S0: bloc mémoire 3 sections (ou "aucun résultat")
      INJ->>L2: unlock
      INJ->>L1: unlock
    end

6. Cas d’erreur¶

7. Critères d’acceptation — sortie Gate 8¶

7 bis. Formules des KPI de mesure continue post-merge¶

CS-1 (itérations Gate 8)¶

• Baseline gelée : 10 stories pré-B5.
• Fenêtre post : 10 stories post-B5.
• Formule : CS-1 = taux_GO_v1_10_post_B5 - taux_GO_v1_10_pre_B5.
• Script : scripts/measure-cs1-baseline.py + calcul post.

CS-2 (réutilisation des learnings)¶

• Fenêtre : T+90j après merge B5.
• Formule :
  (nb_learnings_injectés_au_moins_1_fois_dans_la_fenêtre / total_learnings_créés_avant_B5) * 100
• Cible : >= 30%.
• Source : data/learnings-injections.jsonl + data/learnings.jsonl.
• Script : scripts/measure-cs2.sh --window 90d.
• Alerte : <20% à T+60j => signal /morning.

CS-3 (capitalisation clarifications)¶

• Fenêtre : 30 jours glissants.
• Formule :
  nb_occurrences où search-clarifications.py --domain D remonte >=1 résultat pour une nouvelle story du même domaine
• Cible : >= 1 occurrence/mois.
• Source : événements de session source=clarification.
• Script : scripts/measure-cs3.sh.

CS-4 (activation veille)¶

• Fenêtre : 5 premières stories post-merge B5.
• Formule :
  nb_stories où une fiche veille impact_pv in ('fort','modere') est injectée au step 0
• Cible : >= 5 sur 5.
• Source : événements de session source=veille.
• Script : scripts/measure-cs4.sh.

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

1. ST-295-01 Veille nominale.
2. ST-295-02 Veille invalide.
3. ST-295-03 Clarifications tous modes.
4. ST-295-04 Clarifications sans filtres.
5. ST-295-05 Scoring tanh.
6. ST-295-06 Jointure score manquant.
7. ST-295-07 Migration scope.
8. ST-295-08 Promotion seuils + nb_domains.
9. ST-295-09 Éviction stale.
10. ST-295-10 Injection unifiée 3 sections + cardinalités.
11. ST-295-11 RWLock double fichier.
12. ST-295-12 Rate-limit prioritaire.
13. ST-295-13 Idempotence/rejeu.
14. ST-295-14 Dégradation partielle source.
15. ST-295-15 Indisponibilité totale.
16. ST-295-16 Signature + key_version.
17. ST-295-17 /morning obligatoire et observable.
18. ST-295-18 Baseline CS-1 gelée.
19. ST-295-19 Purge 18 mois.
20. ST-295-20 Restore archive signé.
21. ST-295-21 Vérification signature sur clé archivée.
22. ST-295-22 Purge via hook on_story_close.
23. ST-295-23 Purge via cron quotidien.
24. ST-295-24 Rejet query > 500.

9. Hypothèses explicites¶

10. Points à clarifier¶

10.1 Contraintes techniques (stack obligatoire)¶

• Projet : ProbatioVault-ia-governance.
• Langages : Python 3 + Shell Bash/Zsh.
• Recherche sémantique : FAISS CPU 1.x + NumPy.
• Embeddings : Ollama nomic-embed-text (768).
• Formats : Markdown, YAML, JSONL, FAISS, NPY.
• Orchestration : .claude/commands/*.
• Épic : tooling.

10.2 Questions ouvertes¶

Références :

• Epic : tooling
• JIRA : PD-295
• Repos : ProbatioVault-ia-governance, ProbatioVault-doc, ProbatioVault-*
• Scripts contractuels : measure-cs1-baseline.py, measure-cs2.sh, measure-cs3.sh, measure-cs4.sh, purge-clarifications.py, restore-learning.py, rotate-audit-hmac.sh

Changelog v2→v3¶

• G3v2-B1 : remplacement HMAC file_mtime_ns par clé statique Vault (kv/pd-295/memory-audit-hmac), ajout key_version, rotation manuelle rotate-audit-hmac.sh, vérification archive, fail-closed ERR-295-16.
• G3v2-M1 : nb_domains redéfini sans max(1, ...) ; promotion story->domain réellement bloquée si nb_domains==0.
• G3v2-M2 : cardinalité clarifications fixée (top_k_clarifications_step0=3) et contractuelle dans INV/CA/B5.
• G3v2-M3 : formules CS-2/CS-3/CS-4 ajoutées avec fenêtres, sources, scripts et seuils.
• G3v2-M4 : politique lock étendue à B3/B4/B5 sur deux lockfiles avec ordre d’acquisition fixe.
• G3v2-M5 : propagation explicite de --domain --project --top-k 3 de B5 vers search-clarifications.py (CA-295-25).
• G3v2-M6 : purge clarifications découplée du seul step 10 (step10 + hook on_story_close + cron), CA-295-26.
• G3v2-M7 : arbitrage rate-limit/idempotence explicite : rate-limit glissant évalué en premier (ERR-295-11), puis idempotence bucket.
• G3v2-M8 : schéma canonique data/clarifications.jsonl ajouté en §5.3 avec contraintes types/champs.
• G3v2-M9 : restore-learning.py aligné sur la même politique clé Vault et key_version que B1..B5.
• G3v2-M10 : limite query <= 500 contractualisée (ERR-295-17).
• G3v2-M11 : règle count == len(result_ids) contractualisée (INV-295-23, log audit_inconsistent_trace).
• Corrections mineures intégrées : migration scope one-shot clarifiée, observabilité /morning explicitée, diagrammes alignés sur gardes contractuelles, hypothèse consommateurs externes rendue contrôlée, borne max min_score_default fixée à 0.99, garde de cohérence horloge ajoutée, stabilité learning_id durcie.