PD-295 — Bibliothèque documentaire vers mémoire vivante (spécification canonique contractuelle)¶

1. Objectif¶

La User Story PD-295 DOIT permettre, au démarrage du step 0 du workflow /gov, l’injection automatique et non bloquante de connaissances issues de 3 sources: - learnings historiques pondérés par réutilisation, - fiches de veille pertinentes, - clarifications PO passées du même domaine.

La story DOIT également maintenir un cycle de vie explicite des learnings (scope story|domain|global + archivage), sans changer la stack existante du projet.

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

Inclus¶

• B1: indexation FAISS des fiches de veille depuis ProbatioVault-doc/docs/veille/**/*.md.
• B2: persistance du verbatim des 4 réponses PO du step 0 dans PD-XX-clarifications.md + indexation.
• B3: calcul de reuse_score à partir des injections historisées.
• B4: migration scope, promotion (story→domain→global) et éviction vers archive.
• B5: injection unifiée step 0 en 3 sections (learnings, veille, clarifications), non bloquante en cas d’erreur source.
• Mesure post-merge des KPI CS-1..CS-4 via scripts/analyze-compounding.py (hors Gate 8).

Exclu¶

• Toute migration de moteur de stockage.
• Toute refonte de pipeline existant hors périmètre B1..B5.
• Signature HMAC, clé Vault, canonicalisation JCS, fail-closed strict, filtre PII, purge RGPD multi-artefacts, rate-limit lecture, reranker neural, BM25 hybride, knowledge graph, skill router, résumés hiérarchiques.
• Toute exigence SaaS multi-tenant ou conformité externe non applicable au contexte mono-utilisateur interne.

3. Définitions¶

4. Invariants (non négociables)¶

5. Flux nominaux¶

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

5.2 Bornes numériques contractuelles¶

Aucune exigence de performance percentile (P95/P99) n’est contractualisée pour PD-295.

5.3 SLA temporels (transitions d’état)¶

Aucune autre transition temporelle identifiée.

5.4 Flux nominal B1 — Index veille¶

1. Lecture des fiches ProbatioVault-doc/docs/veille/**/*.md.
2. Extraction frontmatter YAML + H1 + résumé.
3. Production data/veille.jsonl conforme §5.1.
4. Génération embeddings via Ollama nomic-embed-text (dimension 768).
5. Construction index FAISS veille.
6. Exposition recherche /veille-search avec filtres --impact et --verdict.

5.5 Flux nominal B2 — Clarifications persistées¶

1. Recueil des 4 réponses PO du step 0.
2. Écriture verbatim brut dans PD-XX-clarifications.md (dossier epic).
3. Indexation dans data/clarifications.jsonl + index FAISS clarifications.
4. Exposition recherche /clarifications avec filtres --domain et --project.
5. Suppression manuelle possible par suppression du fichier clarification puis réindexation globale.

5.6 Flux nominal B3 — Scoring de réutilisation¶

1. Lecture des injections (learnings-injections.jsonl).
2. Calcul reuse_score par learning selon INV-295-05.
3. Écriture dans data/learnings-scores.jsonl avec clé de jointure {story, gate, tags_hash}.
4. Tri secondaire des résultats learnings par reuse_score décroissant.

5.7 Flux nominal B4 — Promotion et éviction¶

1. Migration initiale: scope=story pour les learnings existants sans scope.
2. Promotion vers domain à partir de reuse_score >= 0.3.
3. Promotion vers global à partir de reuse_score >= 0.6.
4. Éviction vers learnings-archive.jsonl si stale.
5. Exclusion des learnings archivés de toute indexation active.

5.8 Flux nominal B5 — Injection unifiée step 0¶

1. Récupération learnings pertinents (max 5), pondérés par reuse_score.
2. Récupération fiches veille (max 3) avec impact_pv ∈ {fort, modere}.
3. Récupération clarifications passées même domaine (max 3).
4. Construction d’un bloc Markdown à 3 sections.
5. Cas 0 résultat source: section affiche aucun résultat.
6. Cas erreur source: section vide + stderr, sans blocage du step 0.

5.9 Machine à états et transitions retour (obligatoire)¶

État STORY_ACTIVE (scope story)¶

État DOMAIN_ACTIVE (scope domain)¶

État GLOBAL_ACTIVE (scope global)¶

État ARCHIVED (scope archived, terminal)¶

Aucune transition retour autorisée. Toutes les transitions retour sont explicitement interdites.

Checklist machine à états: - [x] Chaque état liste ses transitions sortantes autorisées et interdites. - [x] État terminal ARCHIVED documenté avec → * : INTERDITE. - [x] Invariants de transition dédiés en §4 (INV-295-TR-*).

5.10 Clauses obligatoires “non applicables”¶

• Stratégie de migration DDL: non applicable (aucune base relationnelle, 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).
• Contraintes inter-modules (routes cross-module): Aucune contrainte inter-module applicable.
• Invariant envelope encryption crypto: non applicable (domaine tooling, non crypto/crypto-proof).

5bis. Diagrammes (si applicable)¶

Diagramme d’état (>= 3 états)¶

stateDiagram-v2
    [*] --> STORY_ACTIVE

    STORY_ACTIVE --> DOMAIN_ACTIVE : AUTORISEE (reuse_score >= 0.3)
    STORY_ACTIVE --> GLOBAL_ACTIVE : INTERDITE
    STORY_ACTIVE --> ARCHIVED : AUTORISEE (nb_injections==0 && age>56j)

    DOMAIN_ACTIVE --> STORY_ACTIVE : INTERDITE
    DOMAIN_ACTIVE --> GLOBAL_ACTIVE : AUTORISEE (reuse_score >= 0.6)
    DOMAIN_ACTIVE --> ARCHIVED : AUTORISEE (nb_injections==0 && age>56j)

    GLOBAL_ACTIVE --> STORY_ACTIVE : INTERDITE
    GLOBAL_ACTIVE --> DOMAIN_ACTIVE : INTERDITE
    GLOBAL_ACTIVE --> ARCHIVED : AUTORISEE (nb_injections==0 && age>56j)

    ARCHIVED --> STORY_ACTIVE : INTERDITE (etat terminal)
    ARCHIVED --> DOMAIN_ACTIVE : INTERDITE (etat terminal)
    ARCHIVED --> GLOBAL_ACTIVE : INTERDITE (etat terminal)

Diagramme de séquence (flow multi-services)¶

sequenceDiagram
    participant GOV as /gov-step-0
    participant LRN as Learnings Search
    participant VEI as Veille Search
    participant CLR as Clarifications Search
    participant OLL as Ollama embeddings
    participant FAI as FAISS index
    participant FS as JSONL/Markdown storage

    GOV->>LRN: query_text + domain + top_k=5
    LRN->>OLL: embed(query_text) -> float32[768]
    OLL-->>LRN: embedding[768]
    LRN->>FAI: knn_search(embedding, 5)
    FAI-->>LRN: hits[{story_id,gate,tags_hash,reuse_score}]
    LRN-->>GOV: learning_section_md

    GOV->>VEI: query_text + impact={fort,modere} + top_k=3
    VEI->>OLL: embed(query_text) -> float32[768]
    OLL-->>VEI: embedding[768]
    VEI->>FAI: knn_search(embedding, 3)
    FAI-->>VEI: hits[{title,impact_pv,verdict_veille,summary}]
    VEI-->>GOV: veille_section_md

    GOV->>CLR: domain + project + top_k=3
    CLR->>OLL: embed(domain+project) -> float32[768]
    OLL-->>CLR: embedding[768]
    CLR->>FAI: knn_search(embedding, 3)
    FAI-->>CLR: hits[{story_id,clarification_verbatim_excerpt}]
    CLR-->>GOV: clarification_section_md

    alt Source retourne 0 résultat
        LRN-->>GOV: []
        GOV->>GOV: section = "aucun résultat"
    else Source en erreur
        VEI-->>GOV: erreur technique
        GOV->>FS: log stderr(error)
        GOV->>GOV: section = vide
    end

    GOV-->>GOV: assemble bloc markdown 3 sections

6. Cas d’erreur¶

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

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

9. Hypothèses explicites¶

10. Points à clarifier¶

10.1 Contraintes techniques (stack cible contractuelle)¶

10.2 Questions en suspens¶

Références¶

• Epic : Non communiqué (champ “Référence épique” vide au 2026-04-12)
• JIRA : PD-295
• Repos concernés : ProbatioVault-ia-governance, ProbatioVault-doc
• Documents associés : docs/epics/tooling/PD-295-memoire-vivante-5-briques/PD-295-besoin.md, templates/outputs/PD-XX-specification.md