PD-295 — Spécification (cycle 3 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, conformité RGPD, et isolation runtime des subprocess manipulant du verbatim PO.

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 (§3.10.1 besoin v2.2).
• Signature HMAC des fichiers d’état + filtrage lecture fail-closed (§3.10.2 besoin v2.2).
• 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 valides.
6. Toute ligne d’état écrite (sessions) est signée sig_hmac_sha256.

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

1. Step 0 collecte 4 réponses PO en mémoire volatile (io.StringIO).
2. Appel subprocess wrapper scripts/b2-sanitizer.py avec verbatim sur stdin (pipe OS).
3. Le wrapper appelle claude -p en sous-subprocess (stdin=verbatim, stdout=pipe, env=CLAUDE_DISABLE_SESSION_LOG=1,TERM=dumb, sans CLAUDECODE via unset/filtrage env).
4. stdout/stderr de la chaîne subprocess restent en mémoire (pipes), jamais fichier.
5. Aucun fichier disque pour verbatim.
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.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 nb_domains = len(set(injection.domain for injection in learnings-injections.jsonl if injection.learning_id == L.id)), puis reuse_score_brut et 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 (INV-295-STATE-02).
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 rwlock (INV-295-14).
2. Recherches exécutées: learnings (top_k=5), veille (top_k=3), clarifications (top_k=3, --domain et --project obligatoires).
3. Pour chaque source: count_configured fixé, count_effective=min(configured, available_after_filter), under_corpus=true si insuffisant.
4. Construction bloc injection 3 sections avec count_configured, count_effective, under_corpus.
5. Construction événement audit conforme schéma générique §5.14.
6. Signature HMAC JCS et écriture trace signée en session via helper signé.
7. Si écriture réussie: retour bloc injection.
8. Si écriture trace échoue et fail_closed_depth < 3: ERR-295-TRACE_WRITE_FAILED, fail_closed_depth += 1, retour EMPTY_BLOCK.
9. Si nouvelle erreur impose une tentative d’incrément de fail_closed_depth de 3 vers 4: arrêt process + alerte (ERR-295-FAIL_CLOSED_RECURSION).

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 SLA temporels¶

5.9 Machine à états¶

5.9.1 learning.scope¶

5.9.2 clarification.lifecycle_state¶

5.10 Migration DDL¶

Aucune migration DDL SQL.

5.11 Atomicité DB/queue¶

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

5.12 Protection distribuée et déploiement¶

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

Chaque guard est évalué avant toute opération; échec => arrêt du flux concerné, jamais warn+continue.

La dérive d’horloge est revalidée en précondition de chaque événement signé; dépassement >500ms => fail-closed strict, abort /gov + alerte opérateur. Indisponibilité simultanée sntp + cache timed => ERR-295-NTP_UNREACHABLE et abort /gov.

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

Schéma contractuel (JCS signé) :

{
  "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|purge_clarifications_failed|unsigned_entry_detected|injection_failed_fail_closed",
  "brick": "B1|B2|B3|B4|B5",
  "key_version": 1,
  "payload_canonique": {},
  "sig_hmac_sha256": "..."
}

Vecteurs contractuels pré-calculés (JCS strict, champ signature exclu avant HMAC) :

V1 (nominal 5/5)
key_hex=000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
payload_canonique_jcs={"brick":"B5","event_type":"learning_injected","key_version":1,"payload_canonique":{"count_configured":5,"count_effective":5,"result_ids":["PD-19-3-a1b2c3d4e5f6","PD-42-8-abcdef123456","PD-77-1-111111111111","PD-88-2-222222222222","PD-99-4-333333333333"],"source":"learning","under_corpus":false},"schema_version":3,"story_id":"PD-295","timestamp_iso8601":"2026-04-11T15:42:33.123Z"}
expected_sig=1e2893b482800032ac24a72966a09957e5baba795aa8908c908ddf7de8080f48

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-10-1-aaaaaaaaaaaa"],"source":"learning","under_corpus":true},"schema_version":3,"story_id":"PD-295","timestamp_iso8601":"2026-04-11T15:42:34.123Z"}
expected_sig=737a7cb44264ba6d7dd513a7e12e0466977c0694d1e4ac5dfe34854a605c53ba

V6 (rotation clé 1->2, émis par `scripts/rotate-audit-hmac.sh` hors session `/gov`, signé avec la nouvelle clé v2)
key_hex_v1=1111111111111111111111111111111111111111111111111111111111111111
key_hex_v2=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
hmac_key_used=key_hex_v2
payload_canonique_jcs={"brick":"B3","event_type":"audit_key_rotated","key_version":2,"payload_canonique":{"archive_path":"kv/pd-295/memory-audit-hmac/archive/v1","count_configured":1,"count_effective":1,"key_version_new":2,"key_version_old":1,"under_corpus":false},"schema_version":3,"story_id":"PD-295","timestamp_iso8601":"2026-04-11T15:42:36.123Z"}
expected_sig=a0d289da4aa24d6a803ca98c812ce8df177915c8c77e28407539bb908e9269c2
verify_note=V6 se vérifie avec v2; v1 archivée pour vérifier les événements historiques signés avant rotation.

V8 (droit à l’oubli `clarification_purged --force`)
key_hex=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
payload_canonique_jcs={"brick":"B2","event_type":"clarification_purged","key_version":2,"payload_canonique":{"count_configured":6,"count_effective":6,"force":true,"scope":"story","under_corpus":false},"schema_version":3,"story_id":"PD-295","timestamp_iso8601":"2026-04-11T15:42:37.123Z"}
expected_sig=a2519bc7eca3e3b187671fda529d99858e084c15dc69bdfaf1755ca5fa286314

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 + contrôle anti-session active + re-signature existant + archive clé précédente.
• Écriture manuelle autorisée via scripts/write-signed-state.py <file> <payload_json> uniquement.

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 (EMPTY_BLOCK en fail-closed)¶

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

    S0->>B5: inject(story_id,domain,project,query)
    B5->>B5: guard checks + rwlock + check key session
    alt key absente en mémoire (démarrage session)
        B5->>V: read key (once at startup)
        alt Vault KO
            B5->>B5: sys.exit(1) ERR-295-AUDIT_KEY_UNAVAILABLE
            Note over S0,B5: /gov terminé, aucun retour au caller
        else Vault OK
            B5->>B5: cache key immuable en session
        end
    end
    B5->>B5: build 3 sections with count_configured/count_effective/under_corpus
    B5->>L: append signed event
    alt append OK
        B5-->>S0: injection block
    else append FAIL
        B5->>B5: fail_closed_depth++
        B5-->>S0: EMPTY_BLOCK + ERR-295-TRACE_WRITE_FAILED
    end

6. Cas d’erreur¶

7. Critères d’acceptation¶

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

• ST-295-01..20 conservés (nominal, erreurs, transitions, purge, lock, métriques, non-DDL).
• ST-295-21 : isolation subprocess verbatim.
• ST-295-22 : filtrage lignes non signées.
• ST-295-23 : re-signature après rotation clé.
• ST-295-24 : guards préconditions (10/10).
• ST-295-25 : fail-closed depth borné.
• ST-295-26 : exclusion backups PD-295.
• ST-295-27 : frontière rétention 540/541 jours.
• ST-295-28 : on_story_close succès + échec purge avec retry/fail-safe.

9. Hypothèses¶

10. Points à clarifier¶

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 cycle3-v2 → cycle3-v3¶

• F-01 : INV-295-RUNTIME-01 explicite unset CLAUDECODE (learning universel 2026-02-20)
• F-02 : INV-295-STATE-04 hook on_story_close → purge-clarifications --mode eligible-only (pas de purge immédiate non expirée)
• F-03 : §5.12 source NTP sntp/timed + ERR-295-NTP_UNREACHABLE
• F-04 : rotate-audit-hmac lock anti-session + ERR-295-ROTATION_BLOCKED
• F-05 : §5.12 rwlock portée (4 fichiers + granularité + timeout + stale)
• F-06 : V6 signé avec la nouvelle clé, archive v1 pour vérification historique
• F-07 : matrice ST↔TC complétée (INV-295-STATE-01..04, RUNTIME-04)