PD-295 — Plan d'implémentation¶

Mode : équilibré — outil interne mono-utilisateur, stack Python/FAISS/Ollama/Markdown/YAML déjà en place, aucune refonte. Priorité à la simplicité et au zéro-SPOF non bloquant.

Résolution des réserves Gate 3 (RESERVE) : le plan tranche techniquement 4 écarts majeurs sans modifier spec ni tests (Art. I §Immuabilité).

Réserve	Écart spec	Décision plan	Référence
M-01	Écart 1 — reuse_score non normalisé	Score = somme pondérée brute (pas un ratio). Seuils 0.3/0.6 appliqués à la somme brute. Cohérent avec TC-NOM-05 (1.0 / 1.8). Documenté en §2.3 + H-01.	§2.3, H-01
M-02	Écart 2 — filtres exacts vs KNN clarifications	Récupération clarifications = filtre exact {domain, project} + tri récence desc, top_k=3. Le diagramme §5bis est stylisé. Documenté en §2.5 + H-02.	§2.5, H-02
M-03	Écart 3 — tags_hash non canonique	Canonicalisation stricte : lowercase NFC → dédup → tri ASC → join \n → SHA-256 hex lowercase. Fonction unique compute_tags_hash() partagée entre producteurs learnings et scoring.	§2.6, INV-plan-03
M-06	Écart 6 — atomicité JSONL	Pattern tempfile + fsync + rename atomique (POSIX) pour toute réécriture. Appends gardés par flock advisory (LOCK_EX) sur sentinelle .lock par fichier. Reader utilise snapshot (open fd à l'entrée).	§2.7, INV-plan-06

1. Découpage en composants¶

Aucune modification d'autres modules (cross-module guards) : PD-295 est 100% confiné à ProbatioVault-ia-governance/scripts/ et ProbatioVault-ia-governance/data/. Aucune route HTTP, aucun guard NestJS, aucun schéma SQL.

2. Flux techniques¶

2.1 Flux B1 — Indexation veille¶

1. veille-index.py parcourt ProbatioVault-doc/docs/veille/**/*.md avec glob.glob(recursive=True).
2. Pour chaque fichier : parse frontmatter YAML via python-frontmatter. Si frontmatter manquant ou invalide, fiche ignorée, print(f"[WARN] veille: {path} skipped: {err}", file=sys.stderr).
3. Validation schéma : champs requis title, date, verdict_veille ∈ {signal,bruit,veille}, impact_pv ∈ {fort,modere,faible,aucun}. Validation via data_format.validate_veille_record().
4. Extraction : H1 comme fallback title, résumé = premier paragraphe sous ## Résumé ou les 400 premiers chars.
5. Construction ligne JSONL : {path, title, date, verdict_veille, impact_pv, summary, tags[]}. Écriture via jsonl_atomic.write_all() (tempfile + fsync + rename).
6. Embeddings : pour chaque résumé, appel Ollama POST /api/embeddings modèle nomic-embed-text, timeout 30000 ms. Dimension attendue 768, sinon raise ValueError.
7. FAISS : IndexFlatIP 768 dim, mapping index position → ligne veille.jsonl. Persistance data/veille-index.faiss et data/veille-embeddings.npy via rename atomique.

2.2 Flux B2 — Clarifications persistées¶

1. gov-step-0-glue collecte les 4 réponses PO via gov_ask_po text (helper existant scripts/lib/gov-interact.sh, conforme mode Ringbearer).
2. clarifications-persist.py --story PD-XXX --project backend écrit le fichier Markdown :

   # PD-XXX — Clarifications PO
   Date : 2026-04-12
   Domain : tooling
   Project : ia-governance
   
   ## Q1. {question 1}
   {verbatim R1}
   
   ## Q2. {question 2}
   ...
   

3. Règle de ré-entrée : si PD-XXX-clarifications.md existe déjà, créer PD-XXX-clarifications-{YYYY-MM-DD-HHMMSS}.md à côté (append historique). Cf. §9 Écart 12 — les versions successives sont toutes indexées, la plus récente est retournée par défaut.
4. clarifications-index.py lit tous les PD-*-clarifications*.md du workspace, produit data/clarifications.jsonl (un enregistrement par question, soit 4 lignes par fichier) avec {story_id, domain, project, question_idx, verbatim, date}, puis index FAISS data/clarifications-index.faiss. Embeddings Ollama sur le verbatim concaténé.

2.3 Flux B3 — Scoring de réutilisation (résolution M-01)¶

1. compute-reuse-scores.py lit data/learnings-injections.jsonl (si absent : traité comme corpus vide + print(..., file=sys.stderr), voir ERR-295-03).
2. Aggrégation par (story, gate, tags_hash) → {nb_injections, set(stories_gate8_go), set(domains)}.
3. Application formule brute INV-295-05 :

   reuse_score = (
       0.4 * nb_injections
       + 0.4 * nb_stories_gate8_go_apres_injection
       + 0.2 * nb_domains_distincts
   )
   

   Pas de normalisation : le score est une somme pondérée à valeurs dans [0, 999999.9999] (D-295-08). TC-NOM-05 valide score(L1)=1.8 et score(L2)=1.0, ce qui confirme l'intention.
4. Interprétation des seuils promotion (INV-295-09/10) :
5. reuse_score >= 0.3 (soit nb_injections>=1 OU gate8_go>=1 OU domains>=2) → éligible domain
6. reuse_score >= 0.6 (par exemple nb_injections>=2, ou nb_inj=1 + gate8_go=1) → éligible global
7. Écriture data/learnings-scores.jsonl atomique, une ligne par clé {story, gate, tags_hash, reuse_score, nb_injections, nb_stories_gate8_go_apres_injection, nb_domains_distincts, computed_at}.
8. Learnings non jointables (aucune ligne learnings-injections.jsonl) → pas de ligne learnings-scores.jsonl produite. Semantique aval (résolution Écart 9) : tout lookup scope_fsm.get_score() sur un learning non scoré retourne 0.0 via dict.get(key, 0.0). Tri secondaire INV-295-07 : score manquant traité comme 0.0, stable tri (sorted(..., key=..., stable=True)).

2.4 Flux B4 — Promotion et éviction¶

1. learnings-lifecycle.py --migrate : lit learnings.jsonl, pour chaque entrée sans champ scope → ajoute "scope": "story". Idempotent : si scope déjà présent, no-op. Un champ scope_migrated_at est persisté comme sentinelle d'achèvement (résolution Écart 7).
2. learnings-lifecycle.py --promote : FSM de scope_fsm.py. Pour chaque learning, lookup reuse_score via jointure {story, gate, tags_hash}. Applique strictement :
3. story → domain si reuse_score >= 0.3
4. domain → global si reuse_score >= 0.6
5. Jamais de downgrade : toute transition retour lève TransitionRefused et retourne le learning inchangé, stderr.
6. learnings-lifecycle.py --evict : pour chaque learning, calcule age_days = (today - date_created).days. Champ de référence = date_created persisté en entête du learning (créé par gov-compounder). Si absent, fallback sur date D-295-12 interprété comme date de création (résolution Écart 14, H-03). Éviction ssi age_days > 56 AND nb_injections == 0. Déplacement vers learnings-archive.jsonl : append dans archive (flock), puis réécriture atomique de learnings.jsonl sans le learning évincé.
7. ARCHIVED est terminal : scope_fsm.transition(archived, *) retourne toujours TransitionRefused("ARCHIVED terminal, résolution manuelle uniquement").
8. Les index actifs (learnings-index.faiss, learnings-cache.json) sont reconstruits à la fin d'un run lifecycle par appel à l'existant learnings-index-rebuild.py, en excluant learnings-archive.jsonl du corpus source.

2.5 Flux B5 — Injection unifiée step 0 (résolution M-02)¶

1. gov-learnings-inject.py reçoit --story PD-XXX --domain tooling --project ia-governance --query-text "...".
2. Section 1 — learnings (top 5) : embed(query_text) via Ollama, KNN sur learnings-index.faiss (hors archive), tri primaire = score cosine, tri secondaire = reuse_score desc (fallback 0.0), tri tertiaire = date_created desc (tie-break déterministe, résolution Écart 13).
3. Section 2 — veille (top 3) : embed(query_text), KNN sur veille-index.faiss, filtre post-KNN impact_pv ∈ {fort, modere}, puis limitation à 3. Scénario test recommandé ajouté en §4 pour couvrir INV-295-15/16 (Écart 11).
4. Section 3 — clarifications (top 3) : filtre exact sur clarifications.jsonl par {domain, project} (pas de KNN, résolution M-02), tri par date desc, limitation à 3. Pas d'embed, pas d'appel Ollama pour cette section → plus robuste (pas d'échec Ollama possible).
5. Assemblage Markdown strict :

   ## Learnings injectés (reuse_score)
   - [PD-XXX gate 5] {extrait} (score=1.8)
   - ...
   
   ## Fiches veille pertinentes
   - [2026-04-10] {title} (impact={impact_pv})
   - ...
   
   ## Clarifications PO passées (domain/project)
   - [PD-YYY] Q1: {verbatim 200 chars}
   - ...
   

6. Mode dégradé non bloquant par section : | Cas | Comportement | | --- | --- | | 0 résultat | Section contient _aucun résultat_ | | Exception (IO/FAISS/Ollama) | try/except Exception as e: print(f"[inject] section {name} failed: {e}", file=sys.stderr); section="_source indisponible_" |
7. Sortie sur stdout → capturée par gov-step-0.md et concaténée au prompt step 0.

2.6 Canonicalisation tags_hash (résolution M-03)¶

Fonction unique data_format.compute_tags_hash(tags: list[str]) -> str :

import hashlib, unicodedata

def compute_tags_hash(tags: list[str]) -> str:
    if tags is None:
        tags = []
    normalized = []
    for t in tags:
        t = unicodedata.normalize("NFC", t).strip().lower()
        if not t.startswith("#"):
            t = f"#{t}"
        normalized.append(t)
    canonical = "\n".join(sorted(set(normalized)))
    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()

Règles contractuelles (INV-plan-03) : - Tout producteur de ligne learnings.jsonl OU learnings-scores.jsonl DOIT appeler compute_tags_hash() — aucune autre implémentation. - Test unitaire obligatoire test_tags_hash_canonical_idempotent : permutations, casse, dédup, espaces, NFD/NFC → même hash. - Invariant cross-module dans code-contracts.yaml : forbidden: "Implémenter sa propre canonicalisation tags_hash".

2.7 Atomicité JSONL (résolution M-06)¶

Module scripts/lib/jsonl_atomic.py — 3 primitives :

def write_all(path: Path, lines: Iterable[dict]) -> None:
    """Réécriture totale : tempfile + fsync + rename atomique POSIX."""
    tmp = path.with_suffix(path.suffix + ".tmp")
    with open(tmp, "w", encoding="utf-8") as f:
        for line in lines:
            f.write(json.dumps(line, ensure_ascii=False) + "\n")
        f.flush()
        os.fsync(f.fileno())
    os.replace(tmp, path)  # atomique POSIX

def append_locked(path: Path, line: dict, timeout: float = 5.0) -> None:
    """Append guardé par flock advisory LOCK_EX sur sentinelle .lock."""
    lock_path = path.with_suffix(path.suffix + ".lock")
    with open(lock_path, "a+") as lock_fd:
        _acquire_flock(lock_fd, fcntl.LOCK_EX, timeout)
        with open(path, "a", encoding="utf-8") as f:
            f.write(json.dumps(line, ensure_ascii=False) + "\n")
            f.flush()
            os.fsync(f.fileno())
        fcntl.flock(lock_fd, fcntl.LOCK_UN)

def read_snapshot(path: Path) -> list[dict]:
    """Lecture snapshot : open fd puis read all. Un rename concurrent ne corrompt pas."""
    with open(path, "r", encoding="utf-8") as f:
        return [json.loads(l) for l in f if l.strip()]

Règles contractuelles (INV-plan-06) : - Toute écriture sur veille.jsonl, clarifications.jsonl, learnings-scores.jsonl, learnings.jsonl, learnings-archive.jsonl DOIT passer par jsonl_atomic.*. - Interdit : open(path, "w") direct, > shell redirect, pandas.to_json(path). - Le reader (injection) utilise read_snapshot() → un rename concurrent du writer ne corrompt jamais la lecture (Linux/macOS : rename(2) atomique et le fd pointe sur l'inode d'origine). - H-01 (spec §9) est maintenue côté fonctionnel mais techniquement renforcée par ces primitives : même en cas de violation accidentelle du mono-instance, pas de corruption.

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

graph LR
    subgraph Wave1["Wave 1 — Fondations (parallèle)"]
        CORE[agent-tooling-core<br/>data-format + jsonl_atomic]
    end
    subgraph Wave2["Wave 2 — Indexers (parallèle, dépend de CORE)"]
        VEI[agent-tooling-indexer<br/>veille-indexer + search]
        CLR[agent-tooling-clarifications<br/>clarifications-store + search]
        SCO[agent-tooling-scoring<br/>reuse_score]
    end
    subgraph Wave3["Wave 3 — Lifecycle + Injection"]
        LIF[agent-tooling-lifecycle<br/>FSM scope + évicition]
        INJ[agent-tooling-injection<br/>bloc unifié 5/3/3]
    end
    subgraph Wave4["Wave 4 — Glue + Metrics"]
        GLU[agent-tooling-glue<br/>gov-step-0 hook]
        MET[agent-tooling-metrics<br/>analyze-compounding]
    end
    subgraph Wave5["Wave 5 — Tests"]
        TST[agent-tooling-tests<br/>pytest + fixtures]
    end

    CORE --> VEI
    CORE --> CLR
    CORE --> SCO
    SCO --> LIF
    VEI --> INJ
    CLR --> INJ
    LIF --> INJ
    INJ --> GLU
    LIF --> MET
    GLU --> TST
    MET --> TST

5 waves. La wave 1 (CORE) doit être mergée avant que les autres démarrent, car elle fournit les primitives partagées (tags_hash, jsonl_atomic). La wave 5 consomme l'ensemble pour tests intégrés.

3. Mapping invariants → mécanismes¶

Invariants ajoutés par le plan (non spec)¶

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

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

Tests de plan (nouveaux, couvrent résolutions)¶

Périmètre de test¶

Tous les niveaux fonctionnels sont in scope. Les niveaux performance/sécurité avancée sont hors scope par décision contractuelle de la spec (§2 exclusions).

6. Gestion des erreurs¶

Politique globale : tout stderr suit le format [{module}] {short_msg}: {details} pour parsing aval par /gov-retrospective (terminal.log injection, cf. mémoire projet). Aucun sys.exit(1) dans B1/B2/B5 — le step 0 est non bloquant par contrat.

7. Impacts sécurité¶

Conformité Art. VI (responsabilité) : tous les try/except Exception sont étroits et journalisent. Aucun pass silencieux. Aucun .catch(() => log) pattern (anti-catch-absorb, cf. learnings universels).

8. Hypothèses techniques¶

9. Points de vigilance¶

• Écart 5 (spec) : la spec §5.1 n'attribue pas explicitement les champs D-295 à chaque artefact. Le plan interprète — à valider en Gate 5 que l'interprétation des regex applicables par artefact est acceptée.
• Écart 8 (cardinalités cibles vs max) : le plan choisit max (moins = acceptable). Si 0 hit → _aucun résultat_, si 1-4 hits → section avec N éléments. Pas d'erreur pour 1 ≤ N < top_k.
• Écart 10 (RGPD) : fonctionnalité de suppression ciblée absente. Dette documentée comme H-05.
• Écart 11 (filtre impact_pv) : TC-PLAN-04 ajouté pour couvrir la régression silencieuse possible.
• Écart 14 (date base) : le champ date_created doit être introduit en même temps que la migration B4, sinon le fallback risque d'être systématique.
• Ré-entrée clarifications : accumulation de fichiers PD-XXX-clarifications-{ts}.md peut être bruyante sur les stories relancées souvent. À réévaluer si >5 versions pour une même story.
• Dette FAISS index clarifications : construit mais non utilisé par step 0 (H-02). À supprimer si la décision M-02 est confirmée en long terme, ou à brancher sur /clarifications CLI.
• Tri cosine FAISS IndexFlatIP : nécessite normalisation L2 des embeddings avant insertion (faiss.normalize_L2). À ne pas oublier dans veille-indexer et learnings-indexer.
• Parallélisation agents step 6b : les waves 2 (indexers) sont indépendantes mais toutes consomment data-format. Wave 1 doit finir 100% avant d'ordonnancer wave 2. Surveiller conflits de merge sur scripts/lib/data_format.py.

10. Hors périmètre¶

• Signature HMAC, canonicalisation JCS, clé Vault, 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 (spec §2).
• Migration moteur de stockage, refonte pipeline existant hors B1..B5.
• Toute exigence SaaS multi-tenant ou conformité externe.
• Performances percentiles P95/P99 (aucune dans spec §5.2).
• Restauration depuis ARCHIVED (état terminal, résolution manuelle hors automation).
• Validation Enum exacte du champ project D-295-04 (non énumérée en spec — traité comme string en best-effort, flaggé dette).
• Tie-break parfait lorsque similarité ET reuse_score ET date_created sont égaux (ultra-rare, accepté comme non déterministe au-delà de l'ordre stable Python).