OrenSegal/audit

Exécutez un audit contradictoire de ce codebase et terminez-le. Signalez et livrez d'abord ; ne modifiez le code source qu'avec --fix ou une fois que l'utilisateur a choisi les correctifs.

Vous êtes l'adversaire. Chaque lentille pose une question sous un angle différent : quelle entrée, quel timing, quel utilisateur ou attaquant fait que ce code donne une mauvaise réponse, perd des données, fuit des données ou bloque l'utilisateur ?

Ce dossier contient tout ce dont l'audit a besoin. Résolvez ces chemins à partir du répertoire de ce fichier :

• lenses/<lens>.md : une par lentille. Sa ligne Fires: indique quand la lentille s'exécute (always, ou when <condition>). Chaque sonde est soit inconditionnelle (toujours répondue), soit marquée (when <condition>) (répondue lorsque la condition est vraie, sinon fermée comme non applicable). Puis l'artefact que produit la lentille, et sa ligne done.
• scripts/scan.py : prend les empreintes du dépôt, achemine les lentilles et liste les propres analyseurs du projet à exécuter. scripts/signals.tsv : chaque motif de détection et d'amorce ; scripts/tools.tsv : chaque analyseur connu. Un projet ajoute ses propres lignes dans docs/agents/audit-signals.tsv.
• scripts/verify.py : vérifie les fichiers de constatations par rapport aux fichiers de lentilles. scripts/cochange.sh : les fichiers qui changent ensemble.
• DELIVER.md : notes de transfert, la carte d'audit et ses tickets.
• UNTANGLE.md : le refactoring structurel, pour --untangle et pour les tickets structurels.

1. Périmètre

• Arguments : un chemin (par défaut : racine du dépôt) ; --lens a,b pour exécuter seulement celles-ci ; --since REF pour auditer ce qui a changé depuis une référence (une base de PR, ou le commit du dernier audit) ; --fix ; --untangle [area|ticket] pour passer directement à UNTANGLE.md ; --out DIR (par défaut .audit/).
• Lorsqu'aucune réponse ne peut arriver (CI, claude -p), les questions sans réponse restent sur HANDOFF.md comme questions ouvertes, la livraison va uniquement au tracker local, et la source reste intacte sauf si un ticket est sur la ligne approved:.
• Créez le répertoire de sortie avec un .gitignore contenant *, afin que l'audit ne touche aucun fichier suivi. Lors du démarrage d'une nouvelle exécution (jamais lors d'une reprise), déplacez d'abord les RUN.md, REPORT.md et findings/ d'une exécution précédente vers <out>/history/<sa date>/, afin que la nouvelle exécution puisse les comparer.
• Reprendre : si <out>/HANDOFF.md existe, continuez à partir de sa phase next, en laissant les fichiers de l'exécution là où ils sont. Les tickets sur sa ligne approved: sont autorisés pour les modifications de code sans redemander ; travaillez le premier sur la frontière, un ticket par session, comme le dit DELIVER.md. Tout autre ticket est d'abord renvoyé à l'utilisateur. S'il existe une exécution antérieure dans history/, proposez --since <son commit> et reportez refuted.md.

Chaque phase ci-dessous se termine par la réécriture de <out>/HANDOFF.md comme décrit dans DELIVER.md.

2. Scan et reconnaissance

Exécutez python3 scripts/scan.py <path> [--since REF] [--lens a,b] > <out>/SCAN.md, de sorte que SCAN.md soit la sortie brute du script : piles, paquets, quelles lentilles se déclenchent et pourquoi, points chauds, le plan d'exécution, les analyseurs à exécuter, les sites candidats par sonde (fichiers les plus chauds en premier), et les décomptes de cas particuliers.

Exécutez chaque analyseur listé sous Outils dont la commande est disponible, en enregistrant sa sortie dans <out>/tools/<tool>.txt. Leurs avertissements sont des pistes pour la lentille nommée par chaque ligne, au même titre que les sites de scan ; un outil manquant ou défaillant est noté dans RECON.md, jamais installé.

Écrivez ensuite <out>/RECON.md, en complétant ce qu'un script ne peut pas voir. Terminez seulement lorsque chaque titre a une réponse ou none :

• Limites : chaque endroit par lequel des données externes entrent (HTTP, webhooks, lectures DB, fichiers, env, liens profonds, charges utiles push, sortie du modèle, entrée utilisateur).
• Persistance : magasins locaux, serveur DB, caches, files d'attente, et lequel possède chaque fait.
• Chemins critiques : argent, authentification, suppression de données, migrations, tout ce qui touche à la sécurité, la boucle utilisateur principale.
• Commandes : build, test, lint, run ; si les tests passent maintenant.
• Règles de la maison : CLAUDE.md/AGENTS.md ; le langage du domaine dans GLOSSARY.md (ou GLOSSARY-MAP.md), utilisé pour chaque nom dans les constatations et correctifs ; les ADR, dont les risques acceptés restent réglés sauf si le risque a changé ; le tracker de tickets dans docs/agents/.
• Conditions : pour chaque lentille qui se déclenche, quelles sondes conditionnelles s'appliquent ici, avec preuve.
• Remplacements de lentilles : une lentille que le scan a ignorée mais que la reconnaissance montre nécessaire, ou une lentille déclenchée par un faux signal, avec la raison.

Écrivez <out>/RUN.md : commit, date, arguments, liste finale des lentilles.

3. Chasse

Suivez le plan du scan : séquentiel exécute chaque lentille ici, l'une après l'autre ; parallèle donne à chaque lentille un sous-agent, et une lentille fragmentée un sous-agent par paquet listé. Un hôte qui limite la concurrence exécute des vagues, en associant les lentilles au plus petit nombre de sites ; un hôte sans sous-agents exécute tout en séquence.

Les sous-agents démarrent sans compétences et sans cette conversation, donc chaque briefing est autonome. Il nomme : le fichier de lentille, ce fichier (pour Méthodes et Format de constatation), RECON.md, la section de la lentille dans SCAN.md, le périmètre et le chemin de sortie <out>/findings/<lens>[-<package>].md. Les chasseurs sont des feuilles en lecture seule : ils lisent le code, exécutent les tests, les scripts et l'application, n'écrivent que leur fichier de constatations et leurs reproducteurs, et retournent au contexte principal, qui seul dispatch.

Méthodes

• Pré-mortem : trois mois après le lancement, la critique 1 étoile la plus élevée concerne ce domaine. Écrivez-la, puis trouvez le code qui l'a provoquée.
• Inversion : comment feriez-vous pour que cette fonctionnalité échoue aussi mal que possible ? Vérifiez les blocs de code dans chaque direction.
• Registre des hypothèses : pour chaque fonction sur un chemin critique, listez ce qu'elle suppose. Lesquelles sont imposées par un type ou une contrainte, et lesquelles reposent sur l'espoir ?
• Clôture de Chesterton : avant de qualifier une garde, un cas particulier ou une ligne étrange de bogue, trouvez pourquoi elle existe (git log -L, blame, la PR). Une clôture avec une raison valide n'est pas une constatation.
• Les candidats sont des pistes : un site de scan est un point de départ pour la lecture. Une sonde avec zéro site est quand même répondue, et un site ne devient une constatation qu'avec un scénario concret.

Format de constatation

### <LENS>-<n> <l'affirmation en moins de 60 caractères>
- where: path:line
- probe: <id de la sonde depuis le fichier de lentille>
- scenario: <entrée, état ou timing concret> → <résultat erroné qu'un utilisateur ou le système observe>
- severity: critical | high | medium | low
- detectability: loud (crash, alerte, échec du test) | quiet (mauvaise réponse que quelqu'un peut remarquer) | silent (personne ne remarquera)
- verdict: CONFIRMED (<le test, script, requête ou capture d'écran qui l'a reproduit>) | PLAUSIBLE (raisonné, non exécuté)
- fix family: <le type de changement, pas le patch>

Sévérité : critical perd ou corrompt des données, viole la sécurité ou la vie privée, traite mal l'argent ou présente un risque de sécurité ; high montre une mauvaise réponse ou bloque l'utilisateur sur un chemin courant ; medium fait de même sur un chemin rare ou dégrade la qualité ; low est de l'hygiène. La sévérité est fixée par qui peut la déclencher aujourd'hui dans la configuration livrée : un scénario critical ou high nomme cette personne (tout visiteur, tout utilisateur connecté, un attaquant possédant X) ; un chemin accessible uniquement à un opérateur ou une configuration morte descend d'un niveau.

Rédaction : les constatations, reproducteurs, rapports et tickets seront partagés. Écrivez <REDACTED> à la place de tout secret, jeton ou donnée personnelle, et indiquez où cela se trouve au lieu de le citer.

Un fichier de constatations commence par l'artefact de la lentille. Chaque sonde se termine par au moins une constatation ou une ligne clean: : clean: <probe> — <preuve>, ou pour une sonde conditionnelle dont la condition ne tient pas, clean: <probe> — n/a: <pourquoi>. Un chasseur a terminé lorsque sa ligne done est atteinte et que python3 scripts/verify.py <out> --root <path> --lens <lens> réussit.

4. Vérifier

1. Fusionner les doublons entre les lentilles : lorsque deux constatations partagent un emplacement et un mécanisme, gardez le bloc le plus sévère, ajoutez - also: <les autres ids> et supprimez l'autre bloc, de sorte que chaque problème apparaisse une fois.
2. Réfuter : chaque constatation critical ou high reçoit un réfutateur frais ; les autres sont regroupées par lentille. Un réfutateur reçoit uniquement le bloc de constatation, jamais le raisonnement du chasseur. Pour une constatation PLAUSIBLE, il tente de tuer l'affirmation : une garde en amont, une contrainte dans la DB, un chemin inaccessible, une clôture avec une raison. Pour une constatation CONFIRMED, il vérifie le reproducteur : devient-il rouge pour la raison énoncée, via du code qu'un véritable utilisateur ou attaquant atteint ? Lorsque l'hôte propose un modèle différent, les réfutateurs l'utilisent, car des biais partagés rendent un accord sur le même modèle peu probant.
3. Promouvoir par preuve : survécu et reproduit → CONFIRMED ; survécu par raisonnement → PLAUSIBLE ; tué → <out>/refuted.md avec la raison.
4. Critique de couverture : un sous-agent frais reçoit les chemins critiques de RECON.md et toutes les lignes clean: de chaque lentille, et nomme chaque chemin critique dont la preuve est mince (une phrase là où une trace ou un test était nécessaire) ou qu'aucune lentille n'a atteint. Chacun est renvoyé à la lentille correspondante pour un second regard avant le rapport.

Un reproducteur est une boucle de rétroaction serrée qui devient rouge sur cette constatation et aucune autre : un test échouant au joint le plus proche, un script, une requête. Construisez-en un chaque fois que cela coûte moins de dix minutes, dans <out>/repro/, uniquement sur les systèmes locaux, de branche, de sandbox ou en mode test. Une constatation tuée par une raison qui tiendra le prochain trimestre (un risque accepté, un compromis délibéré) appartient à un ADR, proposé à la livraison, afin que les audits ultérieurs le lisent en reconnaissance.

5. Rapport

Écrivez <out>/REPORT.md :

1. Résumé : décomptes par sévérité et lentille, et les trois correctifs à appliquer en premier, avec pourquoi.
2. Correctifs : regroupez les constatations par cause racine, chaque correctif écrit au-dessus des constatations qu'il résout ; cherchez le correctif unique derrière plusieurs constatations, qui souvent ne leur ressemble pas. Étiquetez chaque correctif structural (couplage, duplication, type manquant, module peu profond, joint mal placé) ou local (un endroit, un changement), et décrivez les correctifs structurels dans le vocabulaire du module profond : module, interface, profondeur, joint, adaptateur, effet de levier, localité, le test de suppression.
3. Constatations non regroupées, classées par sévérité, puis détectabilité (silencieuse en premier), puis portée.
4. Couverture : toutes les lignes clean: de chaque lentille, les lentilles ignorées avec leurs raisons, les analyseurs exécutés ou manquants, et ce que le critique de couverture a renvoyé.
5. Depuis le dernier audit, lorsque history/ contient une exécution antérieure : corrigé, toujours ouvert, nouveau, et régressé (corrigé avant, revenu maintenant).

- Faire du serveur le seul rédacteur de `scan_count`, décrémenté atomiquement avec `where scan_count > 0`, afin que le client ne puisse pas dériver, dépenser deux fois ou réinitialiser. [structural, critical]
  - MONEY-2 `ScanQuota.swift:40` décrémente localement avant le téléchargement, et de nouveau lors d'une nouvelle tentative.
  - MONEY-3 la réinstallation de l'application remet `scansUsed` à 0 dans le stockage local.
  - STATE-5 le quota hebdomadaire se réinitialise le lundi local de l'appareil, donc voler vers l'ouest offre une deuxième semaine.

Exécutez python3 scripts/verify.py <out> --root <path> ; le rapport est final lorsqu'il réussit. Lorsque l'hôte rend les constatations structurées (un outil ReportFindings), signalez également chaque constatation survivante, de la plus sévère à la moins sévère.

Ajustez l'entonnoir pour ce projet : une ligne d'amorce dont tous les sites se sont avérés réfutés ou propres, ou une constatation qu'aucune amorce n'a signalée, est une ligne proposée pour le docs/agents/audit-signals.tsv du projet. Listez les propositions dans le rapport ; elles ne sont écrites que lorsque l'utilisateur les accepte.

6. Livrer et transférer

Lisez DELIVER.md. Cartographiez le rapport en une carte d'audit avec un ticket par correctif, typé, avec des arêtes bloquantes, sur le tracker de tickets du dépôt (.scratch/ local quand aucun n'est configuré ; confirmez avant de poster sur un tracker distant). Demandez ensuite quels correctifs commencer en un tour de grillage : numérotez chaque correctif avec votre réponse recommandée, formulée de sorte que « oui » l'accepte. Avec --fix, suivez chaque recommandation. Enregistrez les numéros de ticket approuvés sur la ligne approved: de HANDOFF.md.

Acheminez chaque ticket selon sa forme. Les compétences nommées sont mattpocock-skills ; appelez-en une avec l'outil Skill quand disponible, et sinon effectuez son étape en ligne :

Forme du ticket	Acheminement
Nécessite d'abord une décision : où va un joint, un ADR qu'il contredit, un terme de domaine flou, un risque à accepter	grill-with-docs, qui enregistre la réponse comme ADR et termes de glossaire
Structurel, un module, qui vaut la peine d'être exploré avec l'utilisateur avant de s'engager	improve-codebase-architecture sur ce domaine
Structurel, conceptions d'interface concurrentes	codebase-design, son motif design-it-twice
Structurel, la voie est claire et tient en une session	UNTANGLE.md, avec le ticket et REPORT.md comme liste de départ
Structurel, plus grand qu'une session	wayfinder, traçant les tickets de décision vers la destination
De nombreux correctifs à découper pour des agents travaillant sans surveillance	to-tickets (tranches balises-traceuses, arêtes bloquantes, refactorings larges en expand–contract), puis implement
Correctif local	tdd : le reproducteur est le premier test rouge, à un joint convenu avec l'utilisateur ; la suite complète reste verte
PLAUSIBLE et critical, pas encore de reproducteur	diagnosing-bugs phase 1 : construire d'abord la boucle serrée

Lorsque la frontière est vide, ré-auditez avec --since <le commit d'audit>. La destination de l'audit est un ré-audit qui vérifie sans constatation critical ou high survivante.

Terminé quand

• Chaque lentille qui se déclenche a un fichier de constatations qui satisfait sa ligne done, et verify.py réussit sur l'ensemble de la sortie.
• Chaque constatation survivante a un emplacement, une sonde, un scénario, une sévérité, une détectabilité et un verdict ; chaque constatation tuée est dans refuted.md.
• REPORT.md place chaque constatation sous un correctif ou dans la liste non regroupée, la carte contient un ticket par correctif, et HANDOFF.md nomme le prochain ticket.