robcsaszar/crucible

Que fait crucible ?

Reconnaissance de domaine parallèle → validation adversarial → planification → vérification → SPEC → implémentation → PR.

Règle de Propriété des Fichiers

Les sous-agents N'écrivent JAMAIS de fichiers. Ils retournent les résultats sous forme de texte. Vous (l'orchestrateur) écrivez chaque artefact. Les fichiers sont le point de transfert entre phases — la mémoire des sous-agents ne l'est pas.

Configuration

Analysez l'invocation pour :

• Domaines (obligatoire) — zones orientées utilisateur à auditer, par ex. player, curator
• Indice de portée (facultatif) — focus étroit dans un domaine, par ex. lobby SSE, role selection

Déterminez le répertoire de sortie : .crucible/run-<N>/ où N est le prochain entier non utilisé.

Vérification des exécutions précédentes : analysez .crucible/ pour les répertoires d'exécution existants. Lisez chaque findings.json. Alimentez leurs ID confirmés comme liste d'exclusion dans les agents de Phase 1 — ne redécouvrez pas les problèmes connus corrigés ; concentrez l'effort sur les lacunes.

Fichiers écrits lors de cette exécution (tous par l'orchestrateur) :

Fichier	Phase	Rôle
codebase-map.md	1	Contexte injecté textuellement dans tous les agents en aval
recon-<domaine>.json	1	Conclusions brutes par domaine
findings.json	1→2→4	Conclusions fusionnées ; verdicts ajoutés à chaque phase
PLAN.md	3	Plan de correction priorisé
SPEC.md	5	Code avant/après + cas de test par conclusion

Phase 1 — Reconnaissance

LECTURE OBLIGATOIRE de references/recon-phase.md avant de lancer les agents.

Lancez un agent de recherche par domaine déclaré, tous en parallèle. Fournissez à chacun : le chemin de la codebase, le nom du domaine, l'indice de portée (le cas échéant), les ID connus antérieurs à ignorer.

Les agents renvoient du texte JSON. Si un agent renvoie de la prose au lieu d'un tableau JSON, re-invitez une fois avec la forme exacte du schéma de assets/findings-schema.json. S'il échoue à nouveau, écrivez un recon-<domaine>.json vide ([]) et notez l'échec dans codebase-map.md. Continuez — un domaine en échec est récupérable ; n'abandonnez pas l'exécution.

Collectez les réponses valides, puis :

1. Écrivez recon-<domaine>.json par réponse d'agent
2. Synthétisez codebase-map.md — chemins de fichiers clés, limites de domaine, modules partagés, conventions
3. Fusionnez toutes les conclusions de domaine dans findings.json

Critère d'achèvement : chaque domaine a un recon-<domaine>.json, codebase-map.md écrit, findings.json écrit. Ne CHARGEZ PAS references/adversarial-phase.md avant la Phase 2.

Phase 2 — Révision Adversariale

LECTURE OBLIGATOIRE de references/adversarial-phase.md avant de lancer les agents.

Lancez un agent général par conclusion (regroupez les conclusions du même domaine). Chaque agent reçoit le JSON de la conclusion et codebase-map.md — PAS le raisonnement de l'agent de reconnaissance. La frontière d'indépendance est la porte de qualité.

Les agents retournent CONFIRMÉ / REJETÉ / RÉDUIT avec des preuves de code. Ajoutez chaque verdict à l'entrée correspondante dans findings.json. Exécutez node scripts/validate-findings.cjs findings.json — corrigez toute erreur de schéma avant la Phase 3.

Lorsque le validateur lui-même ne peut pas s'exécuter — node pas dans le PATH, le script ou son schéma manquant, une erreur d'utilisation, ou tout échec avant le début de la validation (Échec de chargement du schéma, Échec d'analyse du JSON) — ce n'est pas un succès. Notez ⚠ conclusions non validées — validateur indisponible : <raison> dans la sortie des conclusions et en haut du transfert SPEC, puis continuez. Un rejet du schéma est le cas opposé et bloque toujours : corrigez les conclusions, ré-exécutez, ne procédez pas en cas de rejet. Les deux cas renvoient actuellement 1, alors lisez le texte de l'erreur, pas le code de sortie.

Critère d'achèvement : chaque conclusion a un champ adversarial_verdict. La validation du schéma réussit. Ne RECHARGEZ PAS references/recon-phase.md à partir de ce point.

Phase 3 — Synthèse du Plan

Vérification zéro conclusion : avant de synthétiser, comptez les entrées confirmées + réduites dans findings.json. Si zéro, écrivez .crucible/run-<N>/REPORT.md avec la ligne unique "Aucune conclusion exploitable après révision adversariale." Arrêtez — n'ouvrez pas de PR.

Synthétisez les conclusions confirmées + réduites de findings.json dans PLAN.md :

• P1 (critique/élevé) : flux principaux cassés, perte de données, déconnexion permanente
• P2 (moyen) : erreurs visibles par l'utilisateur, chemins de récupération manquants
• P3 (faible) : polissage, dérive de documentation, problèmes de copie

Regroupez les conclusions qui partagent une cause racine — une correction peut en éliminer plusieurs. Lors du regroupement : la sévérité la plus élevée parmi les conclusions regroupées définit la priorité du groupe. Si les conclusions regroupées ont des approches de correction conflictuelles, divisez-les — une cause racine partagée n'exige pas une correction partagée. Déclarez l'ordre des corrections lorsqu'il existe des dépendances. Les conclusions rejetées sont exclues entièrement.

Critère d'achèvement : PLAN.md écrit ; chaque conclusion confirmée apparaît exactement une fois.

Phase 4 — Vérification Indépendante

Lancez un agent de recherche par conclusion P1 + P2, tous en parallèle. Chaque agent se voit dire : "Vous N'avez PAS écrit cette conclusion. Vérifiez chaque affirmation factuelle par rapport au code source actuel."

Chaque agent vérifie : le fichier existe au chemin, le numéro de ligne correspond au code décrit, le nom de portée est correct, le modèle décrit apparaît effectivement. Retourne VÉRIFIÉ / CORRIGÉ [champ: faux → vrai] / REJETÉ [raison].

Appliquez toutes les corrections à PLAN.md et findings.json. Exécutez à nouveau la validation du schéma. PLAN.md et findings.json doivent concorder — pas de désaccord entre les livrables.

Critère d'achèvement : toutes les conclusions P1+P2 vérifiées. Toutes les corrections appliquées. Le schéma réussit.

Phase 5 — SPEC

Écrivez SPEC.md avec une section par conclusion confirmée (ordre P1 → P2 → P3) :

• Chemin de fichier exact + plage de lignes (vérifié)
• Code avant (source réelle, pas de pseudo-code)
• Code après (correction concrète)
• Cas de test : une phrase par comportement que le test doit vérifier

Exécutez node scripts/validate-findings.cjs findings.json vérification finale.

Critère d'achèvement : chaque entrée de PLAN.md a une section SPEC. La validation réussit.

Phase 6 — Transfert

1. Mettez à jour les docs de flux (docs/flows/) pour toute conclusion qui modifie un comportement orienté utilisateur
2. Invoquez la compétence implement avec SPEC.md
3. Ouvrez un PR — c'est la porte de validation humaine ; aucune approbation intermédiaire n'est demandée

Corps du PR : lien vers PLAN.md, nombre de conclusions par sévérité, lien vers SPEC.md, liste des docs de flux mis à jour.

JAMAIS

• NE JAMAIS demander à un sous-agent d'écrire un fichier À la place : Faites en sorte que l'agent renvoie le contenu sous forme de texte ; écrivez le fichier vous-même. Pourquoi : L'état entre les phases réside dans les fichiers. Si un agent écrit directement, l'orchestrateur perd la copie canonique et ne peut pas réconcilier les livrables après les corrections de Phase 4.

• NE JAMAIS donner à un agent adversarial la chaîne de raisonnement de l'agent de reconnaissance À la place : Passez uniquement la conclusion structurée (JSON) et codebase-map.md. Pourquoi : Voir la logique de l'agent de reconnaissance ancre l'agent adversarial aux mêmes hypothèses — la frontière d'indépendance est ce qui élimine les faux positifs.

• NE JAMAIS continuer au-delà de la Phase 2 avec des échecs de validation de schéma À la place : Corrigez les champs défaillants dans findings.json avant de synthétiser le plan. Pourquoi : Un PLAN construit sur des conclusions mal formées produit une SPEC avec des chemins de fichier et numéros de ligne incorrects que la compétence d'implémentation ne peut pas utiliser.

• NE JAMAIS écrire SPEC.md alors qu'une conclusion P1/P2 a verification: "en attente" À la place : Exécutez node scripts/validate-findings.cjs findings.json --pre-spec et résolvez tous les échecs avant la Phase 5. Pourquoi : La protection --pre-spec existe dans le script du validateur mais est invisible sauf si invoquée — un agent qui saute cet appel générera SPEC avec des chemins de fichier non vérifiés et transmettra silencieusement des numéros de ligne incorrects à l'implémentation.