Spec — Workflow Codex de correction App KG

Objectif

Définir comment Codex doit exploiter les audits App KG, findings Nexus/Ruff/Bandit/OSV et futurs tools MCP nexus-kg pour corriger prudemment le code réel, sans correction de masse aveugle.

Ce document ne déclenche aucune correction automatique. Il cadre le workflow qui sera utilisé par Codex et les agents IA quand le MCP runtime sera disponible.

Principes

1. Prioriser avant de corriger.
2. Résoudre les findings par preuve structurée.
3. Lire le code réel avant patch.
4. Corriger un finding ou un cluster homogène à la fois.
5. Vérifier par tests ciblés.
6. Régénérer le KG seulement avec validation/scope explicite.
7. Comparer le score et les deltas de findings après correction.
8. Documenter les faux positifs au lieu de les supprimer silencieusement.

Entrées attendues

• Audit App KG courant.
• Export docs/codex/repo-audits/**/findings.json.
• Risques IA persistés si disponibles.
• Tools MCP nexus-kg définis dans 19-Nexus-KG-MCP-Spec.md.
• Code réel du repository cible.
• Tests disponibles dans le repository cible.

Priorisation

Ordre recommandé :

1. high actionnable avec fichier et ligne.
2. Findings bloquants de parsing, imports internes non résolus ou runtime probable.
3. medium sécurité, runtime ou architecture.
4. Clusters homogènes Ruff/Bandit répétitifs, après validation que la correction est mécanique et testable.
5. Findings de tests seulement si le projet les traite comme dette active.
6. low et info uniquement sur demande explicite ou lot dédié.

Classification avant correction

Paquet MCP attendu

Un paquet de correction doit inclure :

{
  "risk": {},
  "findings": [
    {
      "graph_id": "uuid",
      "source_tool": "bandit",
      "finding_type": "bandit_b324_hashlib",
      "path": "services/echo/app/services/meeting_service.py",
      "line": 1094,
      "severity": "high",
      "message": "Use of weak SHA1 hash for security."
    }
  ],
  "file_context": {},
  "nearby_relations": [],
  "impact": {},
  "recommended_reads": [],
  "recommended_commands": [],
  "safety_notes": []
}

Les findings doivent être résolus par tuple :

(graph_id, source_tool, finding_type, path, line)

Fallback sans ligne seulement si la ligne est absente :

(graph_id, source_tool, finding_type, path)

Workflow — finding unique

1. Appeler kg_get_anomaly ou kg_get_audit_risk.
2. Vérifier que le finding est résolu sans ambiguïté.
3. Appeler kg_file_context.
4. Relire le fichier réel et les tests proches.
5. Formuler la correction minimale.
6. Appliquer le patch.
7. Lancer les tests ciblés.
8. Si validé, demander ou préparer kg_regenerate.
9. Comparer via kg_compare_runs.

Prompt Codex :

Corrige un finding App KG unique.

Contraintes :
- Résous le finding par tuple (graph_id, source_tool, finding_type, path, line).
- Appelle kg_get_anomaly puis kg_file_context si MCP est disponible.
- Relis le fichier réel avant patch.
- Garde la correction minimale.
- Lance le test ciblé le plus proche.
- Ne régénère le KG que si la validation humaine ou le scope l'autorise.
- Résume le delta attendu.

Workflow — cluster homogène

Un cluster est homogène si tous les findings partagent :

• même source_tool ;
• même finding_type ;
• même pattern de correction ;
• même niveau de risque ;
• tests ou vérification commune raisonnable.

Exemples acceptables :

• série Ruff d'import inutilisé sur un même package ;
• série Bandit identique sur du code de test, après décision explicite ;
• imports internes ambigus causés par une racine package unique.

Prompt Codex :

Prépare une correction de cluster homogène App KG.

Avant patch :
- Liste le critère d'homogénéité.
- Échantillonne 3 findings représentatifs.
- Vérifie qu'aucun fichier archive/backup/generated n'est inclus.
- Propose une correction mécanique unique.
- Indique les tests communs.

Stoppe si le cluster mélange source_tool, finding_type, risque ou contexte produit.

Workflow — faux positif

Un faux positif doit être prouvé, pas supposé.

Critères possibles :

• code de test volontaire ;
• exemple/documentation non exécuté ;
• chemin generated/backup/fixture validé ;
• mitigation déjà présente dans le code ;
• alerte scanner non applicable au contexte.

Prompt Codex :

Analyse un possible faux positif App KG.

Tu dois :
- relire le fichier réel ;
- citer la preuve locale ;
- expliquer pourquoi le risque ne s'applique pas ;
- proposer soit une documentation du faux positif, soit une vraie correction ;
- ne jamais supprimer ou masquer le finding sans règle validée.

Workflow — archives, backups, generated

Par défaut, Codex ne corrige pas automatiquement :

• archives ;
• backups ;
• dossiers generated ;
• dumps ;
• fixtures volumineuses ;
• code vendor ;
• snapshots de tests.

Action attendue :

1. Marquer la classe comme non actionnable automatiquement.
2. Proposer exclusion scanner ou décision humaine si récurrent.
3. Ne pas modifier le fichier sans validation explicite.

Workflow — vérification post-correction

Commandes attendues selon le type :

Prompt Codex :

Vérifie une correction App KG.

Tu dois :
- lancer les tests ciblés ;
- relancer les contrôles utiles ;
- régénérer le graphe seulement si autorisé ;
- comparer score, high/medium, source_tool et finding_type ;
- signaler tout nouveau finding ou régression.

Critères de clôture

Un lot de correction est clos seulement si :

• le patch est minimal ;
• les tests ciblés passent ;
• les findings traités sont vérifiés par tuple ;
• les faux positifs sont documentés ;
• les nouveaux findings sont signalés ;
• le delta KG est comparé quand régénération possible.

Interdits

• Corriger tous les findings en masse.
• Modifier archives/backups/generated sans validation.
• Se fier au résumé IA sans lire le code.
• Utiliser un mot de passe Nexus dans un agent IA.
• Accéder directement à la DB Nexus.
• Masquer un finding au lieu de corriger ou documenter.