PD-295 — Spécification (cycle 2 v3)¶

1. Objectif¶

La User Story PD-295 DOIT transformer la bibliothèque documentaire en mémoire vivante injectée automatiquement au step 0, via 5 briques contractuelles (B1..B5), avec sécurité fail-closed, audit HMAC canonique JCS (RFC 8785), conformité RGPD, isolation runtime des subprocess manipulant du verbatim PO, et signature des fichiers d’état.

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

Inclus¶

• B1 : indexation sémantique des fiches de veille.
• B2 : capture clarifications PO en résumé structuré non-PII, validation binaire PO.
• B3 : scoring reuse_score et tri secondaire.
• B4 : promotion scope + archivage stale.
• B5 : injection unifiée learnings + veille + clarifications.
• Isolation runtime subprocess verbatim.
• Signature HMAC des fichiers d’état + filtrage lecture fail-closed.
• Purge RGPD multi-artefacts + purge backups ciblés.
• Gate 8 méta : existence/exécutabilité scripts CS-1..CS-4.
• Mesures CS-1..CS-4 post-merge (T+30/T+60/T+90).

Exclu¶

• Changement de stack (FAISS/Ollama/Markdown/YAML/JSONL imposés).
• Reranker neural, BM25 hybride, knowledge graph, classifier d’intention, router automatique.
• Refonte specs-index/**/*.yaml.
• Migration DB/vector engine.
• Persistance verbatim PO.
• Mode dégradé autorisant injection non tracée.
• Non-répudiation forte (EdDSA/HSM), report candidat G33.
• Exécution multi-hôte active/active, report candidat G34.

3. Définitions¶

4. Invariants¶

4.1 Invariants non négociables (runtime/produit)¶

4.2 Invariant de code (non-runnable en boîte noire)¶

5. Flux nominaux¶

5.1 Modèle de données canonique¶

5.2 Flux nominal B1 — Index veille¶

1. Collecte ProbatioVault-doc/docs/veille/**/*.md.
2. Production data/veille.jsonl conforme D-295-15/16.
3. Index FAISS dimension 768.
4. Recherche avec filtres --impact et --verdict.
5. Erreurs de format journalisées sans bloquer les lignes valides.
6. Toute ligne d’état écrite (sessions) est signée sig_hmac_sha256.

5.2.4 Chargement de la clé Vault (session)¶

• La clé HMAC est chargée une seule fois au démarrage de la session /gov.
• Si Vault est indisponible au chargement ou renvoie un format invalide, /gov s’arrête immédiatement (SystemExit(1)), avec code opérateur ERR-295-AUDIT_KEY_UNAVAILABLE ou ERR-295-AUDIT_KEY_FORMAT_INVALID.
• Si Vault redevient disponible pendant la session, aucune relecture n’est faite; la clé de session reste immuable jusqu’au prochain démarrage.
• Cette règle garantit qu’une session donnée n’utilise qu’un seul contexte clé/version.

5.3 Flux nominal B2 — Clarifications structurées non-PII + isolation runtime¶

1. Step 0 collecte 4 réponses PO en mémoire volatile.
2. Appel scripts/b2-sanitizer.py avec verbatim sur stdin uniquement.
3. stdout/stderr subprocess redirigés vers buffer mémoire (pipe + buffer Python), jamais fichier.
4. Environnement subprocess impose CLAUDE_DISABLE_SESSION_LOG=1 et TERM=dumb.
5. Aucun fichier temporaire disque.
6. Résumé structuré non-PII produit et validé PO (binaire).
7. Si validé: écriture PD-XX-clarifications.md + indexation; sinon REJECTED sans persistance.
8. Événement signé verbatim_subprocess_invoked émis sans verbatim.
9. Effacement des buffers verbatim en sortie.

5.3.3 Architecture subprocess B2 sanitizer¶

gov-step-0 (process parent)
  1) Collecte verbatim en mémoire (io.StringIO)
  2) Prépare pipe stdin avec verbatim
  3) Lance subprocess "b2-sanitizer.py"

b2-sanitizer.py (process enfant)
  1) Lit verbatim depuis stdin
  2) Lance sous-subprocess "claude -p" avec:
     - stdin = verbatim
     - stdout = pipe vers b2-sanitizer
     - env = CLAUDE_DISABLE_SESSION_LOG=1, TERM=dumb
     - argv = ["-p","--append-system-prompt","SANITIZE: extraire intention, supprimer PII"]
  3) Lit le résumé via pipe
  4) Écrit le résumé sur stdout (pipe retour)

gov-step-0 (retour)
  1) Lit le résumé via pipe
  2) Écrase le buffer verbatim en mémoire
  3) Écrit uniquement le résumé structuré sur disque

5.4 Flux nominal B3 — Scoring de réutilisation + état signé¶

1. Lecture learnings.jsonl, learnings-injections.jsonl, metrics.jsonl.
2. Vérification signatures sur lignes learnings-injections; lignes non signées/invalides ignorées.
3. Compteur ERR-295-UNSIGNED_ENTRY incrémenté pour chaque ligne ignorée.
4. Calcul reuse_score_brut, puis reuse_score.
5. Écriture data/learnings-scores.jsonl via scripts/lib/write-signed-state.py.
6. Tri secondaire search-learnings sur reuse_score.
7. /morning affiche 3 entrées top score format score=X.XXXX.
8. Migration initiale: scripts/sign-existing-state.py re-signe les entrées pré-B3.

5.5 Flux nominal B4 — Promotion et éviction¶

1. Migration initiale scope:story si absent.
2. Promotion story->domain et domain->global selon seuils.
3. Éviction stale (nb_injections==0, âge >56j) vers archive.
4. Lecture des fichiers d’état signés; lignes non signées filtrées.
5. Restauration uniquement via scripts/restore-learning.py (audit signé).
6. Exclusion des archived de l’index actif.

5.6 Flux nominal B5 — Injection unifiée + fail-closed borné¶

1. Acquisition locks lecture (INV-295-14).
2. Recherches:
3. learnings (top_k=5)
4. veille (top_k=3)
5. clarifications (top_k=3, --domain et --project obligatoires)
6. Pour chaque source:
7. count_configured fixé (5/3/3),
8. count_effective=min(configured, available_after_filter),
9. under_corpus=true si insuffisant.
10. Construction bloc injection 3 sections.
11. Construction événement audit conforme schéma générique §5.14.
12. Signature HMAC JCS et écriture trace signée en session via helper signé.
13. Si écriture réussie: retour bloc injection.
14. Si échec écriture trace: ERR-295-TRACE_WRITE_FAILED, fail_closed_depth +=1, retour EMPTY_BLOCK tant que fail_closed_depth <=3.
15. Si tentative de 4e fail-closed (fail_closed_depth==4): événement fail_closed_recursion signé (ou UNSIGNED_DEGRADED si clé absente), puis arrêt process SystemExit(1) avec ERR-295-FAIL_CLOSED_RECURSION.
16. Si clé audit indisponible/invalide au moment critique: tentative d’événement audit_key_unavailable_fatal signé avec dernière clé valide en mémoire; sinon log local UNSIGNED_DEGRADED; arrêt process immédiat.

5.6.10 Scope du compteur fail_closed_depth¶

• Scope: par invocation de step 0, thread-local.
• Initialisation: 0 au début de l’invocation.
• Incrément: à chaque fail-closed imbriqué dans le thread courant.
• Réinitialisation: 0 en fin d’invocation (succès ou échec).
• Pas de persistance disque, pas de partage inter-invocations.
• Implémentation de référence: threading.local().

5.7 Bornes numériques¶

Règle stricte reuse_score: - Calcul pré-arrondi: raw=tanh(reuse_score_brut/10). - Si raw >= 0.99995, valeur sérialisée forcée à 0.9999. - Sinon arrondi décimal 4 chiffres. - 1.0000 est interdit.

5.8 Hooks de cycle de vie des stories¶

• Hook: on_story_close(story_id, final_state).
• Déclenchement: transitions vers REJECTED, DONE_WITH_ANOMALY, DONE.
• Implémentation de référence: scripts/lib/story-hooks.sh, appelé depuis .claude/commands/gov.md lors de la transition Jira finale.
• Action contractuelle: appel scripts/purge-clarifications.py --story {story_id}.
• Idempotence: plusieurs appels successifs doivent produire le même état final (sans double-effet indésirable).

5.9 Format canonique du bloc d’injection ({{LEARNINGS}})¶

Le bloc injecté DOIT respecter la forme suivante (lignes et sections obligatoires):

## Mémoire pertinente pour cette story

### Learnings (count_configured=5, count_effective={N}, under_corpus={bool})
- [{story}] [{tags}] {learning_text} (scope: {scope}, score: {reuse_score:.4f})

### Veille (count_configured=3, count_effective={N}, under_corpus={bool})
- [{date}] [{impact_pv}] {title}

### Clarifications passées (count_configured=3, count_effective={N}, under_corpus={bool}, même domaine)
- [{story}, {date}] Priorités : {summary_priorities_one_line}

5.10 SLA temporels¶

5.11 Machines à états¶

5.11.1 learning.scope¶

5.11.2 clarification.lifecycle_state¶

5.12 Migration DDL¶

Aucune migration DDL SQL.

5.13 Atomicité DB/queue¶

Non applicable (pas de flux transaction DB + queue dans PD-295).

5.14 Schéma générique d’événement audit + vecteurs HMAC¶

Schéma contractuel signé (JCS strict, champ signature exclu avant HMAC):

{
  "schema_version": 3,
  "timestamp_iso8601": "2026-04-11T15:42:33.123Z",
  "story_id": "PD-295",
  "event_type": "learning_injected|veille_injected|clarification_injected|verbatim_subprocess_invoked|audit_key_rotated|clarification_purged|unsigned_entry_detected|injection_failed_fail_closed|audit_key_unavailable_fatal|fail_closed_recursion",
  "brick": "B1|B2|B3|B4|B5",
  "key_version": 1,
  "payload_canonique": {},
  "sig_hmac_sha256": "..."
}

Vecteurs contractuels pré-calculés (utilisés par TC-NOM-06):

V1 (nominal B5 5/3/3 plein)
key_hex=000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
payload_canonique_jcs={"brick":"B5","event_type":"learning_injected","key_version":1,"payload_canonique":{"sections":{"clarification":{"count_configured":3,"count_effective":3,"result_ids":["PD-090","PD-091","PD-092"],"under_corpus":false},"learning":{"count_configured":5,"count_effective":5,"result_ids":["PD-101","PD-102","PD-103","PD-104","PD-105"],"under_corpus":false},"veille":{"count_configured":3,"count_effective":3,"result_ids":["VE-201","VE-202","VE-203"],"under_corpus":false}}},"schema_version":3,"story_id":"PD-295","timestamp_iso8601":"2026-04-11T15:42:33.123Z"}
expected_sig=f92f494419827c18d40d69ca1d606e015ba72618056a9c8863b96f60e1a5240b

V4 (sous-corpus learnings 1/5)
key_hex=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
payload_canonique_jcs={"brick":"B5","event_type":"learning_injected","key_version":1,"payload_canonique":{"count_configured":5,"count_effective":1,"result_ids":["PD-042"],"under_corpus":true},"schema_version":3,"story_id":"PD-295","timestamp_iso8601":"2026-04-11T15:42:34.123Z"}
expected_sig=84aa1fc05652688b4b426cb7b34f3563372d7225a002ba0ab673b4ed609e3a5a

V6 (rotation de clé 1 -> 2)
key_hex=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
payload_canonique_jcs={"brick":"B3","event_type":"audit_key_rotated","key_version":2,"payload_canonique":{"archive_path":"kv/pd-295/memory-audit-hmac/archive/1","new_key_version":2,"previous_key_version":1},"schema_version":3,"story_id":"PD-295","timestamp_iso8601":"2026-04-11T15:42:35.123Z"}
expected_sig=377b66b089c4e337405c2d48ab93b0950eded52e758ee7a2b5acf25c6d2f60b8

V8 (purge clarification --force, droit à l’oubli)
key_hex=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
payload_canonique_jcs={"brick":"B2","event_type":"clarification_purged","key_version":1,"payload_canonique":{"count_configured":3,"count_effective":0,"force":true,"result_ids":[],"story_id":"PD-295","under_corpus":true},"schema_version":3,"story_id":"PD-295","timestamp_iso8601":"2026-04-11T15:42:36.123Z"}
expected_sig=29262974fd91d2e0812bc52b0f83012ace1a19ca53b7bd69620a3a05699de17a

5.15 Signature des fichiers d’état¶

• Writer unique: scripts/lib/write-signed-state.py.
• Reader filtering: compute-learning-scores.py, promote-learnings.py, gov-learnings-inject.
• Migration one-shot: scripts/sign-existing-state.py.
• Rotation clé: scripts/rotate-audit-hmac.sh + re-signature existant + archive clé précédente.
• Écriture manuelle autorisée via scripts/write-signed-state.py <file> <payload_json> uniquement.

5.16 Protection distribuée et déploiement¶

5.17 Guards obligatoires (préconditions fail-closed)¶

5bis. Diagrammes¶

Diagramme d’état learning.scope¶

stateDiagram-v2
    [*] --> STORY_ACTIVE
    STORY_ACTIVE --> DOMAIN_ACTIVE: seuil domain
    STORY_ACTIVE --> ARCHIVED: stale
    DOMAIN_ACTIVE --> GLOBAL_ACTIVE: seuil global
    DOMAIN_ACTIVE --> ARCHIVED: stale
    GLOBAL_ACTIVE --> ARCHIVED: stale
    ARCHIVED --> STORY_ACTIVE: restore manuel audité

Diagramme d’état clarification.lifecycle_state¶

stateDiagram-v2
    [*] --> VERBATIM_IN_MEMORY
    VERBATIM_IN_MEMORY --> SUMMARY_PENDING_VALIDATION
    SUMMARY_PENDING_VALIDATION --> SUMMARY_VALIDATED: PO=oui
    SUMMARY_PENDING_VALIDATION --> REJECTED: PO=non
    SUMMARY_VALIDATED --> SUMMARY_INDEXED
    SUMMARY_INDEXED --> EXPIRED: date > retention_until
    EXPIRED --> PURGED

Diagramme de séquence B5 (arrêt /gov si clé indisponible)¶

sequenceDiagram
    participant S0 as /gov-step-0
    participant B5 as gov-learnings-inject
    participant V as Vault
    participant L as data/sessions/*.jsonl
    participant O as local ops log

    S0->>B5: inject(story_id,domain,project,query)
    B5->>B5: guard checks + locks + build sections
    B5->>V: read session key
    alt Vault/clé indisponible ou corrompue
        alt last_valid_key disponible en mémoire
            B5->>L: append signed audit_key_unavailable_fatal
        else aucune clé valide
            B5->>O: append marker UNSIGNED_DEGRADED
        end
        B5->>B5: SystemExit(1)
        Note over S0: aucun retour; processus /gov arrêté
    else clé disponible
        B5->>L: append signed event
        alt append OK
            B5-->>S0: injection block
        else append FAIL
            B5->>B5: fail_closed_depth++
            alt fail_closed_depth <= 3
                B5-->>S0: EMPTY_BLOCK + ERR-295-TRACE_WRITE_FAILED
            else fail_closed_depth == 4
                B5->>L: append signed fail_closed_recursion (ou UNSIGNED_DEGRADED)
                B5->>B5: SystemExit(1)
                Note over S0: aucun retour; processus /gov arrêté
            end
        end
    end

6. Cas d’erreur¶

7. Critères d’acceptation¶

8. Scénarios de test contractuels (résumé)¶

• ST-295-01..26 conservés.
• ST-295-27: arrêt process sur clé Vault invalide avec absence de retour au caller.
• ST-295-28: hook on_story_close 3 états + idempotence.
• ST-295-29: stabilité clé Vault sur session complète.
• ST-295-30: attestation DPO pii_ruleset_v1.
• ST-295-31: validation regex template {{LEARNINGS}}.
• ST-295-32: transition E2E MEMORY_DEGRADED -> MEMORY_HEALTHY.

9. Hypothèses¶

10. Points clarifiés (clos)¶

Références¶

• Epic : tooling
• JIRA : PD-295
• Repos : ProbatioVault-ia-governance, ProbatioVault-doc, ProbatioVault-app, ProbatioVault-backend, ProbatioVault-infra, ProbatioVault-site
• Besoin : docs/epics/tooling/PD-295-memoire-vivante-5-briques/PD-295-besoin.md
• Archive cycle 1 : docs/epics/tooling/PD-295-memoire-vivante-5-briques/cycle-1/

Changelog cycle2-v2 → cycle2-v3¶

• B-01 : borne fail_closed_depth alignée (0..4 ouvert à 4 pour abort)
• B-02 : vecteurs HMAC V1/V4/V6/V8 recalculés avec schéma v3 {count_configured/effective/under_corpus}
• B-03 : diagramme B5 aligné sur arrêt /gov (sys.exit)
• M-01 : tmpfs interdit macOS, buffer mémoire Python exclusif
• M-02 : architecture subprocess b2-sanitizer contractualisée §5.3.3
• M-03 : hook on_story_close ancré §5.8
• M-04 : scope fail_closed_depth thread-local par invocation §5.6.10
• M-05 : clé Vault chargée une fois par session §5.2.4
• M-06 : locks fcntl.flock étendus aux fichiers d'état signés
• Q-295-05 : pii_ruleset_v1 attestation DPO via commit signé
• Q-295-06 : template YAML bloc d'injection §5.9