maxgfr/construct

construct — une idée de produit, ancrée dans un SRD constructible

construct transforme une idée de produit en une suite de documents d'exigences logiciel (SRD) dont les exigences et les décisions sont ancrées dans des recherches réelles, et non dans la mémoire du modèle. Le moteur déterministe (scripts/construct.mjs, zéro dépendance Node) effectue les recherches, l'assemblage des dossiers, le rendu et la validation du SRD avec du code ; votre travail consiste à mener l'entretien, à piloter les recherches et à enrichir l'échafaudage rendu pour obtenir un SRD précis et bien fondé.

La règle fondamentale : préférez une exigence ancrée à une exigence devinée. Utilisez les recherches récupérées par le moteur (concurrents, travaux antérieurs en OSS, documentation technique, StackOverflow) pour justifier le périmètre, les exigences non fonctionnelles (NFR) et les décisions architecturales, et citez les preuves avec [E#]. L'ancrage est indicatif ici — construct check rapporte la couverture mais n'échoue jamais à cause de celle-ci — c'est donc à vous d'appliquer la rigueur.

Le script

Un seul bundle, sans dépendances, validé : node scripts/construct.mjs <commande>. Pas de npm install, pas de clés API. Exécutez --help pour la liste complète. Commandes clés :

• init --idea "<une phrase>" --out <run> — crée un dossier d'exécution + brief.json.
• research --out <run> [--angles market,oss,tech,semantic] [--q "<focus>"] [--semantic] — rassemble des preuves selon différents angles dans <run>/evidence/ (un dossier EVIDENCE.md + evidence.json avec des identifiants [E#]). Angles par défaut : market,oss,tech.
• analyze --out <run> [--json] — le rapport « qu'est-ce qui est faible ? » : nomme chaque fonctionnalité/concurrent/technologie/graine qui sera rendue NON ANCRÉE telle quelle, et affiche la commande de forage qui corrige chaque lacune. Informatif, ne bloque jamais.
• web|oss|tech|so --out <run> [--q "<focus>"] [--url ...] [--seeds ...] [--docs-url <u,...>] — fore UN angle vers la sortie standard (pas de dossier). Utilisez ces commandes pour approfondir un fil ténu ; --docs-url ancre directement les pages de documentation connues.
• render --out <run> [--level light|complex] [--merge] — génère l'arborescence SRD + SRD.json à partir de brief.json + le dossier.
• check --out <run> [--min-grounding <0-100>] [--semantic] [--json] — la porte structurelle stricte (code de sortie ≠ 0 en cas de SRD incomplet) plus le rapport de couverture d'ancrage indicatif. --min-grounding N active une seconde porte qui échoue si le pourcentage de revendications ancrées est inférieur à N % ; --semantic intègre VERIFY.json (voir review) et échoue en cas de revendication réfutée ou non étayée. (Distinct de research --semantic, qui réordonne seulement les preuves par pertinence d'intégration.)
• review --out <run> [--apply <verdicts.json>] [--max-review N] [--json] — le harnais de vérification des revendications. Sans --apply, écrit une liste de travail revendication↔preuve (VERIFY.todo.json + VERIFY.md) : chaque revendication ancrée est associée à chaque extrait [E#] cité pour être jugée. --apply <verdicts.json> réduit vos verdicts (supported|partial|refuted|unsupported) en VERIFY.json, sur lequel check --semantic se base. Distribuez-le selon references/orchestration.md.
• verify --out <run> [--app <dir>] [--run-tests] [--strict] [--json] — l'arbitre de construction : BUILD-PLAN.json bien formé et acyclique, chaque référence de tâche se résout dans SRD.json, les fichiers des tâches terminées existent, chaque exigence est référencée par un test. --run-tests exécute également les commandes de test déclarées ; --strict échoue pour une exigence obligatoire construite sans test de référence.
• status --out <run> [--json] — ce qui existe dans l'exécution jusqu'à présent ; --json ajoute la frontière de construction (quelles tâches BUILD-PLAN sont constructibles maintenant vs. bloquées).
• semantic up|down|status — pile Docker locale optionnelle (Qdrant + Ollama + SearXNG).

Flux de travail

Vous êtes invoqué une fois et devez retourner un SRD complet et ancré. Pilotez la boucle jusqu'à son terme ; ne vous interrompez que pour demander à l'utilisateur une vraie décision.

1. Interviewez l'utilisateur — une question à la fois. Établissez le produit avant de faire des recherches. Suivez references/interview-playbook.md : problème, utilisateurs cibles, valeur fondamentale, fonctionnalités impératives/souhaitables/optionnelles, contraintes (budget, calendrier, équipe, conformité), technologies candidates, et toute graine de concurrent/OSS. Recommandez une réponse à chaque question ; ne déversez pas un questionnaire. Écrivez les réponses dans brief.json (commencez-le avec construct init).

2. Recherchez — ancrez l'idée. Exécutez :

   node scripts/construct.mjs research --out <run> --angles market,oss,tech
   

   Cela découvre les concurrents sur le web, explore les projets OSS comparables (et leurs issues/PR pour les pièges réels), et récupère la documentation des technologies candidates + StackOverflow. Lisez <run>/evidence/EVIDENCE.md.

3. Creusez plus profond — jusqu'à ce que analyze soit propre ou que l'utilisateur vous arrête. Exécutez :

   node scripts/construct.mjs analyze --out <run>
   

   Cela nomme exactement ce qui est faible — fonctionnalités, concurrents, technologies candidates et graines OSS sans preuve correspondante — et affiche la commande de forage qui corrige chaque lacune. Distribuez : si vous pouvez lancer des sous-agents parallèles, dépêchez-en un par lacune ; chacun reçoit la phrase décrivant l'idée, la lacune, sa commande de forage et sa propre recherche web, et retourne un résumé de ≤5 lignes avec les URL à ancrer. Les sous-agents NE DOIVENT PAS écrire dans le dossier d'exécution — les forages affichent sur la sortie standard ; seul construct research écrit le dossier, et seulement VOUS l'exécutez. Intégrez les résultats en série : construct web --url <u,...> --out <run> → ré-exécutez research → ré-exécutez analyze. (Pas de sous-agents ? Travaillez les lacunes vous-même, un forage à la fois.) Dites à l'utilisateur ce que vous avez trouvé et laissez-le diriger — priorisez les fonctionnalités impératives et les décisions cruciales, arrêtez-vous quand il dit que ça suffit. Voir references/orchestration.md et references/research-playbook.md.

4. Générez le SRD. Lorsque le brief est solide et le dossier riche :

   node scripts/construct.mjs render --out <run> --level complex
   

   Choisissez complex chaque fois qu'une construction est même possible ; changer de niveau plus tard renumérote les identifiants FR (voir references/srd-authoring.md). Cela écrit l'arborescence SRD (voir ci-dessous). Le modèle de données et les interfaces sont pré-initialisés par inférence à partir du brief — vérifiez-les, ne leur faites pas confiance. Ensuite, enrichissez-le : résolvez chaque appel 🧠 Décidez :, affinez les critères d'acceptation modélisés et les métriques NFR en déclarations testables et bornées (suivez references/acceptance-criteria.md — check émet un avertissement tant qu'ils restent modélisés), corrigez/étendez le modèle de données et les interfaces, et ajoutez des citations [E##] du dossier aux exigences et décisions qu'ils étayent. Voir references/srd-authoring.md et references/citation-format.md. Au niveau complex, enrichissez également le système de conception (design/) : remplacez les jetons de conception initialisés par les vraies valeurs de la marque du produit, vérifiez l'inventaire des composants et des écrans/flux, et affinez les critères d'accessibilité selon la norme cible (dérivée du brief, par défaut WCAG 2.2 AA). Voir references/design-system-authoring.md.

5. Révision contradictoire — laissez un regard neuf le casser. Lancez un sous-agent réviseur SANS aucun contexte autre que le chemin du dossier d'exécution et references/adversarial-review.md (pas de sous-agents ? faites le passage vous-même, en suivant strictement cette liste de contrôle en tant que lecteur hostile). Il doit essayer de casser le SRD — ambiguïté, critères non testables, chemins d'échec manquants, blanchiment de citations, contradictions — et retourner des constatations étiquetées. Corrigez chaque [bloquant], utilisez votre jugement pour [indicatif], puis ré-exécutez check. Bouclez tant que de nouveaux bloqueurs apparaissent (limite : 3 tours, puis remontez ce qui reste à l'utilisateur). Pour une ADR véritablement contestée et difficile à inverser au niveau complex, exécutez également le panel de 3 juges de references/orchestration.md.

6. Validez (trois couches).

   • Structurelle (stricte) : node scripts/construct.mjs check --out <run>. Échoue en cas de 🧠 non résolu, d'absence totale d'exigences fonctionnelles, d'une FR sans critère d'acceptation, de référence à une entité/interface/NFR pendante, de catégorie NFR obligatoire manquante, ou d'ADR mal formée. Corrigez jusqu'à ce qu'il passe.
   • Ancrage (indicatif) : la même commande affiche la couverture — quelle fraction des exigences/décisions citent des preuves. Augmentez-la là où c'est important (les décisions cruciales) ; voir references/grounding-coverage.md. Par défaut, il ne fait jamais échouer la construction, donc utilisez votre jugement. Lorsque l'utilisateur souhaite un ancrage obligatoire, ajoutez la porte optionnelle : check --out <run> --min-grounding 70.
   • Soutien des revendications (indicatif → porte optionnelle) : la couverture compte les citations ; elle ne vérifie pas qu'elles tiennent. construct review --out <run> construit une liste de travail revendication↔preuve ; jugez chaque paire (distribuez selon references/orchestration.md Pattern 4), assemblez verdicts.json, review --apply verdicts.json, puis check --out <run> --semantic pour bloquer les revendications réfutées ou non étayées. Cela vaut un passage sur les FR/ADR cruciales avant la présentation. Bouclez les étapes 3 à 6 jusqu'à ce que check passe structurellement, que le réviseur ne trouve plus de nouveaux bloqueurs et que l'ancrage soit honnête.

7. Présentez. Donnez à l'utilisateur la suite SRD : la vision, le paysage concurrentiel, les exigences ancrées et les décisions clés (avec leurs preuves [E#] et liens). Signalez explicitement les inconnues plutôt que de deviner.

8. Construisez (quand l'utilisateur veut l'application, pas seulement le SRD). Le rendu a également émis BUILD-PLAN.json — un DAG de tâches lisible par machine (T-000 squelette + une tâche par FR, impératif → souhaitable → optionnel, dépendances tenant compte des entités) dont les entrées acceptance POINTENT vers SRD.json. Vous écrivez tout le code de l'application ; le moteur arbitre. Suivez references/build-playbook.md :

   • Faites T-000 (scaffold, harnais de test, CI) ; définissez conventions.appDir et conventions.testCommand dans BUILD-PLAN.json.
   • Par tâche, dans l'ordre topologique : lisez les critères d'acceptation depuis SRD.json ; appliquez le TDD — chaque test nomme son identifiant FR (ex. describe("FR-001 …") ; c'est ce que verify recherche) ; enregistrez artifacts + tests ; mettez status: "done" ; exécutez node scripts/construct.mjs verify --out <run> et corrigez toute erreur avant la tâche suivante.
   • Les tâches d'une même étape n'ont pas d'arêtes entre elles, donc leur frontière prête (status --out <run> --json) peut être construite en parallèle — un répertoire de travail git isolé par tâche ; vous seul intégrez les résultats dans BUILD-PLAN.json (Pattern 5 dans references/orchestration.md).
   • Par étape : verify --out <run> --run-tests --strict, puis une révision contradictoire d'étape — un regard neuf cherchant un critère d'acceptation qu'aucun test n'exerce réellement (voir le playbook ; references/verify.md explique ce que verify peut et ne peut pas prouver).
   • Si une FR se révèle erronée pendant la construction, modifiez le brief, régénérez (la progression fusionne par titre de fonctionnalité), re-étiquetez les identifiants FR décalés, re-exécutez check.

Ce qu'il produit (l'arborescence SRD, sous --out)

00-overview/   VISION.md · SCOPE.md (+ 🧠 décisions ouvertes)
requirements/  FUNCTIONAL.md (FR-NNN · priorité · Given/When/Then · [E#])
               NON-FUNCTIONAL.md (NFR-NNN par catégorie · métrique · [E#])
architecture/  SYSTEM-CONTEXT.md · DATA-MODEL.md · INTERFACES.md
               decisions/NNNN-*.md  (ADR)
design/        PRINCIPLES.md · DESIGN-TOKENS.md (+ design-tokens.json) · COMPONENTS.md
               SCREENS.md · ACCESSIBILITY.md      (complex uniquement ; --no-design pour ignorer)
competitive/   LANDSCAPE.md (concurrents + travaux antérieurs en OSS)
BUILD-PLAN.md · BUILD-PLAN.json (DAG de tâches pour la phase de construction)
TRACEABILITY.md (FR ↔ NFR ↔ ADR ↔ entité ↔ interface ↔ composant ↔ écran)
evidence/      EVIDENCE.md · evidence.json · meta.json   ·   brief.json · SRD.json

light le maintient léger ; complex ajoute l'ensemble complet des NFR, une deuxième ADR, des critères d'acceptation des chemins d'échec, la matrice de traçabilité complète et une sous-arborescence du système de conception (design/ : principes, jetons, composants, écrans/flux, un contrat d'accessibilité — --no-design l'exclut). Ajoutez --merge pour un seul fichier SRD.md.

Mode sémantique optionnel (totalement local, sans clé API)

Les angles market/OSS/tech ne nécessitent qu'un accès réseau. Pour un passage de pertinence sur les preuves rassemblées, vous pouvez activer un modèle d'intégration local :

node scripts/construct.mjs semantic up        # docker : Qdrant + Ollama + SearXNG
node scripts/construct.mjs research --out <run> --angles market,oss,tech,semantic --semantic

Tout s'exécute dans des conteneurs Docker locaux — pas de clé, aucune donnée ne quitte la machine. Si la pile n'est pas opérationnelle, --semantic enregistre un avis et conserve le classement lexical. Voir references/semantic-setup.md.

Références

• references/interview-playbook.md — comment obtenir le brief, une question à la fois.
• references/research-playbook.md — choisir les angles et creuser jusqu'à « assez bien ».
• references/orchestration.md — le modèle de flux de travail dynamique à trois niveaux et les modèles de sous-agents : distribution des recherches, équipe rouge, panel de juges, distribution de la révision des revendications, distribution de la construction (et la règle du rédacteur unique).
• references/adversarial-review.md — la liste de contrôle de l'équipe rouge et son contrat de constatations.
• references/srd-authoring.md — résoudre les appels 🧠, rédiger des exigences et des ADR testables.
• references/design-system-authoring.md — enrichir le système de conception complex : jetons, composants, écrans/flux et le contrat d'accessibilité.
• references/acceptance-criteria.md — réécritures Given/When/Then mauvais→bon et modèles de métriques NFR mesurables.
• references/citation-format.md — la convention d'ancrage [E#].
• references/grounding-coverage.md — ce que signifie le rapport de couverture indicatif et comment l'augmenter.
• references/build-playbook.md — la boucle de construction : TDD des tâches, convention d'étiquetage FR, portes d'étape, la révision d'étape.
• references/verify.md — ce que chaque vérification verify prouve et ce qui nécessite encore des yeux.
• references/provider-apis.md — comment les issues/PR OSS sont récupérées par hôte, sans clé.
• references/web-discovery.md — la recherche web superposée sans clé.
• references/semantic-setup.md — la pile Docker locale optionnelle.