agent-doc-system 1.4.0 → 1.5.1

package/docs/EVALS.md

@@ -387,3 +387,127 @@ Each was fixed in the engine, not by relaxing a threshold.
   weight a long constraint file against a short ref.
 - Scenarios touch one or two files. A change spanning twenty files is not
   measured.
+
+## Executable agent-task campaigns
+
+`node evals/agent/run.mjs --list` lists a bootstrap corpus of 30 pinned fixtures
+(10 coding-task families, three fixture variants per family). This is a synthetic
+pilot corpus, not a benchmark of 30 independent production incidents. Development
+and holdout families are disjoint. Fixture content hashes live in
+`evals/agent/tasks/pins.json`; changes require deliberately updating those pins.
+Each attempt creates and commits a fresh temporary repository. Validation runs
+after the driver exits, outside the task repository, against executable behavior
+and input-preservation requirements. Neither the validator nor its cases are
+included in the model prompt. A driver saying it succeeded does not pass a task.
+
+Campaigns are opt-in. No model request is made by the regular deterministic
+routing evaluation or test suite. Example configuration:
+
+```json
+{
+  "driver": ["node", "/absolute/path/to/evals/agent/codex-driver.mjs"],
+  "model": "your-configured-model",
+  "modelVersion": "record-the-model-version-and-driver-version",
+  "repeats": 3,
+  "split": "development",
+  "tasks": ["money-1"],
+  "budget": {
+    "timeoutMs": 120000,
+    "maxTokens": 16000,
+    "maxToolCalls": 40,
+    "maxCostUsd": null,
+    "maxOutputBytes": 1048576
+  },
+  "conditions": {
+    "baseline": {"contextCommands": []},
+    "reference": {"contextCommands": [
+      ["node", "{agentdoc}", "compile"],
+      ["node", "{agentdoc}", "query", "service/src/logic.mjs"]
+    ]},
+    "candidate": {"contextCommands": [
+      ["node", "{agentdoc}", "prepare", "--request", "request.json"]
+    ]}
+  }
+}
+```
+
+Run `node evals/agent/run.mjs --config campaign.json --out report.json`.
+The runner records the declared model/version, driver file hashes, fixture pins,
+conditions, repeats, validation results, usage, runtime and infrastructure errors.
+It does not resolve a provider's model alias to an immutable model build; the
+chosen driver must pin and report its actual deployment for that guarantee.
+Model prompts, editing tools and execution permissions should otherwise remain
+identical across conditions. Context-command outputs are included in the model
+prompt and must be counted in input usage. The built-in Codex adapter uses the
+user's existing configured provider and model without switching either.
+
+### Driver protocol and limits
+
+The runner starts an argv array without a shell. The driver receives one JSON
+line on stdin with protocol `agentdoc.eval.driver/v1`, the temporary workspace,
+public task, condition, context and budgets. It writes JSON lines on stdout:
+
+```json
+{"type":"usage","usage":{"inputTokens":100,"outputTokens":20,"toolCalls":2,"costUsd":0.01}}
+{"type":"result","completed":true}
+```
+
+Usage events are cumulative and nondecreasing. Optional `trace` events can carry
+diagnostics. Missing usage, malformed events, a failed driver or failed context
+command is an infrastructure error. Wrong behavior is a task failure. Both stay
+in the report and denominator; neither is silently dropped. Reports with unknown
+cost retain `null` cost rather than treating it as zero.
+
+Wall time and output limits terminate the process group on POSIX, including its
+children. Token, tool and dollar limits terminate when usage events report a
+limit exceeded. They cannot prevent an unreported request from being charged:
+a driver must reserve/enforce provider request budgets before making calls for
+a hard spend guarantee. The Codex adapter receives token usage at turn boundaries
+and does not expose dollar cost, so use `maxCostUsd: null` with that adapter.
+For a driver reporting dollars, `maxCampaignCostUsd` additionally reserves each
+attempt's maximum before launch and stops when costs are unmeasured.
+
+Temporary repositories isolate task files and cleanup; they are not an OS
+security sandbox. Driver execution permissions and common tool restrictions
+belong to the driver/runtime. The optional Codex adapter requests workspace-write
+execution. Untrusted third-party task code requires an external container or
+sandbox, including for validation.
+
+### Candidate selection
+
+`selectCandidate(reference, candidate)` requires paired holdout outcomes and
+identical fixture hashes. It rejects infrastructure errors and declared critical
+errors. It groups variants and repetitions by family and uses a conservative
+95% bounded-variable interval on the paired success-rate difference. A tiny pilot
+cannot establish a 2-point noninferiority margin, even with identical outcomes.
+Adoption additionally requires measured cost per success to improve by at least
+20%; unknown cost cannot support adoption. All attempts, including failures,
+contribute to total cost. This selector evaluates supplied candidates; it never
+changes truth, edits thresholds, publishes code or starts a paid campaign itself.
+Use development tasks to propose variants, holdout tasks to select them, and a
+separate final test set before making production performance claims.
+
+`node evals/agent/optimize.mjs optimization.json report.json` runs a bounded offline
+search. Its configuration contains `campaign` (the runner configuration),
+`reference`, named `variants` (context-command settings), `maxCandidates` (1–20),
+and `maxTotalCostUsd`. The nested campaign must have a measured per-attempt dollar
+cap. An optional `proposer` argv receives public development tasks and the allowed
+variant definitions, and returns `{"variants":["variant-name"]}`. Only declared
+variants can be proposed. The optimizer compares them on development tasks, then
+runs the selected candidate and reference on holdout tasks and applies the
+conservative selection gate. Unknown costs stop the search; the total dollar
+limit is shared across the two stages. Proposal-provider costs are outside the
+runner's usage stream and must be budgeted by that provider driver separately.
+The optimizer never edits the implementation, adjusts thresholds or publishes a
+candidate. The bootstrap corpus is too small to establish a 2-point margin;
+normal pilot output is therefore `inconclusive`, not an adoption claim.
+
+A real-model functional smoke is recorded in
+[`evals/agent/results/smoke-gpt-6.1-sol.json`](../evals/agent/results/smoke-gpt-6.1-sol.json).
+On one synthetic development task with one repetition, the independent validator
+accepted the reference and candidate patches and rejected the baseline patch's
+per-unit decimal rounding. This verifies the runner/model/validator integration;
+it establishes neither a general success-rate difference nor a cost improvement.
+The configured model was `gpt-6.1-sol` through local Codex CLI 0.167.2. Dollar cost
+was unavailable, and the run used the development worktree rather than an
+immutable released revision. Larger pinned holdout campaigns remain necessary.

package/docs/IMPLEMENTATION-PLAN.md

@@ -0,0 +1,310 @@
+# AgentDoc — plan d’implémentation pour un outil destiné aux agents IA
+
+## 1. Résultat visé
+
+Transformer AgentDoc en moteur de contexte opérationnel : un agent décrit une tâche, reçoit les connaissances nécessaires pour agir, approfondit les points utiles et actualise son contexte après les modifications.
+
+L’objectif principal est de réduire le **coût total d’une tâche correctement terminée**, sous contrainte de fiabilité. Le coût inclut les appels au modèle, les outils, les vérifications, les reprises et les échecs. La longueur d’une réponse et la vitesse d’une requête sont des mesures intermédiaires.
+
+Public cible : agents de développement et systèmes qui pilotent leurs sessions. Le protocole, les erreurs et les sorties sont conçus pour leur utilisation directe. Les documents humains servent à maintenir le projet ; ils ne constituent pas l’interface de travail obligatoire de l’agent.
+
+Ce document décrit la cible et ses critères. La version 1.5.0 implémente le protocole, le cache conservateur, les API de session, les expériences de symboles et le runner d’évaluation. Le suivi ci-dessous distingue les fonctionnalités disponibles des résultats empiriques restant à établir.
+
+## 2. Point de départ et invariants
+
+État constaté lors de l’audit de la version locale 1.4.0 :
+
+- Les 30 scénarios déterministes retrouvent les 101 faits attendus. Ils n’évaluent pas la résolution d’une tâche par un modèle.
+- Les 422 tests passent avec la signature Git désactivée pour l’exécution. Les dépôts temporaires héritent sinon de la configuration de signature de la machine.
+- Le rendu Markdown par défaut ne transmet pas toutes les garanties de l’objet interne. Reproductions : une vérification affichée sur quatre sans avertissement sur la fixture Rust ; un conflit affiché sur quatre sans avertissement sur Koda, avec des budgets explicites de un.
+- `query` et `impact` recompilent chacun le dépôt. Des lectures, parsings et constructions d’index sont répétés.
+- Les budgets portent sur des nombres d’éléments ; certaines surfaces, dont les engagements de revue globaux, restent non bornées.
+
+Préserver pendant toute la migration :
+
+1. La distinction entre faits déclarés, dérivés et observés, avec leur provenance.
+2. Les conflits et les inconnues explicites. Une absence de résultat n’est pas une preuve d’absence.
+3. La reproductibilité du graphe et la validation stricte des schémas.
+4. La détection des entrées modifiées, ajoutées, supprimées ou nouvellement résolues.
+5. Les règles de secret, de chemin, de propriété et de validité des observations.
+6. La distinction entre une vérification recommandée, exécutée, réussie et encore valide.
+
+La compilation complète reste la référence de correction. Aucun résultat de performance ne justifie une perte silencieuse d’information critique.
+
+## 3. Décisions d’architecture
+
+### Interface principale
+
+Ajouter trois opérations, d’abord exposées en CLI avec JSON sur stdin/stdout et diagnostics sur stderr :
+
+| Opération | Entrée | Résultat |
+|---|---|---|
+| `prepare` | tâche, chemins ou diff, intention, budget | paquet de travail sur un instantané explicite |
+| `expand` | référence de paquet, éléments ou continuation | connaissances supplémentaires du même instantané |
+| `refresh` | paquet précédent et état courant du dépôt | changements de connaissances et obligations invalidées |
+
+Le CLI appelle une interface JavaScript commune. Un transport MCP pourra l’exposer ensuite sans reproduire sa logique. Aucun serveur permanent n’est requis pour la première livraison.
+
+`prepare` rassemble résolution, impact, contraintes, preuves et sélection des vérifications sur un seul instantané. Les intentions initiales sont `implement`, `change-contract`, `debug-runtime` et `review`. Elles modifient les priorités de présentation ; elles ne permettent pas, à elles seules, d’exclure une obligation.
+
+### Paquet de travail
+
+Créer un schéma de paquet indépendant du schéma du graphe, versionné `agentdoc.dev/context/v1` et fermé aux champs inconnus. Il comprend :
+
+- `snapshot` : empreinte des entrées, versions des extracteurs et schémas ; le commit seul ne suffit pas pour un arbre modifié ;
+- `task` et `scope` : demande normalisée, sujets résolus, portée effective ;
+- `coverage` : capacités d’analyse disponibles, chemins non couverts, résultats partiels et ambiguïtés ;
+- `requirements`, `conflicts`, `facts` : connaissances utiles et leur statut d’autorité ;
+- `evidence` : références adressables, empreintes et localisateurs ;
+- `checks` : vérifications sélectionnées, justification, portée et contexte d’exécution ;
+- `budget`, `omitted`, `continuation` : consommation, omissions explicites et moyen de poursuivre.
+
+Séparer l’incomplétude due au budget, une analyse non prise en charge et un conflit non résolu. Un paquet complet signifie complet dans la portée et les capacités annoncées, jamais connaissance exhaustive du dépôt.
+
+### Frontières internes
+
+| Module cible | Responsabilité | Base existante |
+|---|---|---|
+| `core/context/` | préparation, sélection, sérialisation et approfondissement | `query.mjs`, `impact.mjs`, `dependents.mjs` |
+| `core/snapshot.mjs` | accès cohérent aux entrées et identité de l’instantané | `fsx.mjs`, `compile.mjs` |
+| `core/cache/` | résultats intermédiaires et invalidation | suivi des lectures, probes et listings |
+| `core/session/` | références livrées, versions et deltas | nouveau |
+| `evals/agent/` | exécution des tâches et comparaison des variantes | nouveau, distinct du routage déterministe |
+
+Introduire ces modules avec leurs premiers usages. Éviter une extraction massive préalable de fonctions ou une seconde implémentation des règles d’autorité.
+
+## 4. Lots d’implémentation
+
+### Lot 0 — rendre la mesure reproductible
+
+**Dépendance :** aucune.
+
+**Travaux**
+
+- Désactiver la signature des commits dans les dépôts de test et les utilitaires qui les créent, sans changer la configuration Git de l’utilisateur. Conserver des cas explicites pour les règles Git que le produit doit réellement respecter.
+- Recenser les autres créations de dépôts qui contournent `tests/helpers.mjs` et appliquer la même isolation.
+- Ajouter une instrumentation opt-in : durée par étape, octets lus, lectures physiques, parsings, reconstructions d’index, taille sérialisée et mémoire du processus.
+- Émettre cette télémétrie hors du graphe et hors du contexte envoyé au modèle. Les horodatages et mesures de machine ne doivent pas casser le déterminisme.
+- Enregistrer une référence sur les fixtures et les dépôts publics déjà épinglés, avec matériel, versions, nombre de répétitions et état froid/chaud.
+
+**Fichiers :** `tests/helpers.mjs`, créateurs de fixtures, `core/fsx.mjs`, `core/compile.mjs`, `scripts/bench/run.mjs`, `docs/BENCHMARK.md`.
+
+**Acceptation :** suite indépendante de la signature locale ; instrumentation sans effet sur les sorties fonctionnelles ; comparaison répétée de `query`, `impact` et séquences de requêtes. Les temps historiques de la version 1.2.0 restent identifiés comme tels.
+
+### Lot 1 — rendre les sorties fidèles au moteur
+
+**Dépendance :** lot 0.
+
+**Travaux**
+
+- Définir les informations que chaque format doit restituer : contraintes, conflits pertinents, statut d’autorité, obligations de vérification et indications d’incomplétude.
+- Corriger le Markdown : afficher les troncatures de toutes les sections plafonnées, les gates applicables, les faits utiles des observations et les relations nécessaires pour comprendre l’impact.
+- Préserver la distinction entre conflit résolu et non résolu ; ne pas présenter toutes les décisions comme des contradictions encore ouvertes.
+- Tester les sorties réellement sérialisées et les invocations CLI. L’évaluation de l’objet interne reste utile mais ne suffit plus.
+- Ajouter des scénarios où une information critique se situe au-delà des plafonds par défaut.
+
+**Fichiers :** `core/query.mjs`, `core/impact.mjs`, `bin/agentdoc.mjs`, `evals/harness.mjs`, `tests/modes.test.mjs`, `tests/evals.test.mjs`, `docs/QUERY.md`.
+
+**Acceptation :** les reproductions Rust et Koda ne perdent plus silencieusement d’obligations ; les gates ne disparaissent pas au rendu ; toutes les omissions sont détectables par l’agent. La brièveté n’est pas un critère de refus de ce correctif.
+
+**Livraison :** correctif autonome, compatible avec les commandes actuelles.
+
+### Lot 2 — installer l’évaluation avec de vrais agents
+
+**Dépendance :** lot 0 ; mesurer la version avant et après le lot 1.
+
+**Travaux**
+
+- Créer un runner reproductible avec adaptateurs de modèles, limites d’appels, de temps et de coût, environnement isolé et collecte des sorties d’outils.
+- Constituer un premier corpus de 30 tâches exécutables : correctifs, modifications de contrat, migrations, conflits de documentation, diagnostic à partir d’observations enregistrées et changements transverses.
+- Utiliser des commits épinglés, des validateurs indépendants du graphe et des tests non exposés à l’agent. Une tâche doit pouvoir être évaluée sans compter les libellés choisis par AgentDoc.
+- Séparer tâches de développement et tâches réservées à la validation, en séparant aussi les dépôts ou familles de tâches lorsque nécessaire pour limiter les fuites.
+- Comparer recherche/lecture seules, AgentDoc de référence et variante candidate. Garder les mêmes outils de modification et de test, le même modèle et les mêmes budgets ; compter les instructions supplémentaires d’AgentDoc dans le coût.
+- Commencer par un modèle pour stabiliser le runner, puis confirmer les décisions majeures sur au moins deux modèles épinglés. Exécuter au moins trois répétitions par tâche et configuration lors du pilote ; augmenter l’échantillon si la décision reste incertaine.
+- Conserver les 30 scénarios déterministes actuels comme tests de régression séparés, avec leurs seuils inchangés.
+
+**Fichiers :** nouveaux `evals/agent/`, `evals/agent/tasks/`, configuration des campagnes, `docs/EVALS.md`, script npm dédié.
+
+**Acceptation :** les trois variantes peuvent résoudre la même tâche depuis le même état initial ; un patch erroné échoue même si son contexte semble correct ; les erreurs d’infrastructure sont distinguées des échecs de l’agent et restent comptabilisées dans les rapports d’exécution.
+
+**Livraison :** runner et référence figée. Les campagnes payantes sont explicites, avec plafond configuré ; elles ne s’ajoutent pas automatiquement à chaque CI.
+
+### Lot 3 — livrer `prepare` et `expand`
+
+**Dépendance :** lots 1 et 2.
+
+**Travaux**
+
+- Créer le schéma du paquet et le validateur des requêtes, puis brancher les deux commandes dans la table commune des commandes et de l’aide.
+- Réutiliser un même graphe et un même index pour tous les chemins de la requête. Dédupliquer les obligations par identité et version.
+- Calculer un périmètre pertinent pour les engagements de revue ; conserver les engagements globaux explicitement applicables, pas tous ceux des composants sans rapport.
+- Fournir des extraits ciblés de contraintes et contrats, avec chemin, localisateur et empreinte. Une référence vers un document ne remplace pas automatiquement son contenu nécessaire à la décision.
+- Donner aux vérifications un contexte d’exécution explicite. Préserver les commandes shell comme telles ; ne pas convertir naïvement une chaîne shell en liste d’arguments. Marquer une commande non exécutable automatiquement si son contexte ne peut pas être établi.
+- Implémenter un classement déterministe : obligations applicables d’abord, preuves utiles ensuite, détails complémentaires enfin. L’ordre reste stable à entrée identique.
+- Ajouter un adaptateur de comptage de tokens avec tokenizer et version épinglés. Le mode à budget strict refuse un tokenizer indisponible ; une estimation éventuelle est explicitement distincte.
+- Compter le paquet final, y compris les métadonnées, erreurs et continuations. Recompter après sérialisation. Si même l’enveloppe minimale ne tient pas, refuser le budget demandé.
+- Si les obligations dépassent le budget, retourner un état partiel et une continuation. Ne jamais présenter une sélection de checks comme la liste complète.
+- Lier les continuations à l’instantané, à la requête et à la version du protocole. Un instantané disparu ou périmé appelle un nouveau `prepare` ; aucune continuation ne mélange deux versions du dépôt.
+
+**Fichiers :** nouveaux `schemas/context.schema.json`, `core/context/`, modifications de `bin/commands.mjs`, `bin/agentdoc.mjs`, `core/query.mjs`, `core/impact.mjs`, `core/indexes.mjs`.
+
+**Acceptation :** une invocation prépare un paquet multi-chemins ; tous les faits sont justifiables ; budgets stricts respectés sur la sortie réelle ; approfondissements sans perte ni duplication incohérente ; aucun programme du dépôt n’est exécuté par la préparation.
+
+**Livraison :** commandes additives expérimentales ; `query` et `impact` restent utilisables avec leurs contrats existants.
+
+### Lot 4 — accélérer les lectures et partager les index
+
+**Dépendance :** lot 3.
+
+**Travaux**
+
+- Introduire un instantané de lecture par requête avec cache des octets et des parsings. Inclure les options et versions du parseur dans les clés de réutilisation.
+- Réutiliser les index d’entités, chemins, contrats, relations, assertions et dépendants au sein de cet instantané.
+- Détecter une modification concurrente pendant la capture : vérifier la cohérence des entrées et listings, réessayer de façon bornée, puis signaler un dépôt instable. Ne pas publier un graphe composé de versions incompatibles.
+- Éviter de relire un graphe disque si l’opération travaille explicitement sur l’instantané courant. Préserver la politique de fraîcheur existante de `query` pendant la migration.
+- Borner la mémoire ; éviction et cache désactivé restent des modes corrects.
+
+**Fichiers :** `core/snapshot.mjs`, `core/fsx.mjs`, `core/compile.mjs`, `core/context/`, `core/dependents.mjs`.
+
+**Acceptation :** mêmes résultats avec et sans cache ; tests de mutation pendant une capture ; réduction mesurée des lectures physiques et reconstructions d’index ; absence de régression matérielle de mémoire sur les corpus choisis.
+
+### Lot 5 — compilation incrémentale persistante
+
+**Dépendance :** lot 4.
+
+**Travaux**
+
+- Enregistrer les dépendances entre entrées, résultats d’extraction et faits produits. Commencer par les parsings et extracteurs dont les dépendances sont précisément connues ; recalculer les autres intégralement.
+- Identifier les résultats par le contenu des entrées, les options et les versions du compilateur, des schémas et adaptateurs.
+- Conserver les dépendances négatives : existence testée mais absente, listes de répertoires, règles d’exclusion et chemins candidats de résolution.
+- Invalider sur modification, ajout, suppression, renommage, changement de résolution, de configuration, d’exclusion ou d’extracteur. Reprendre les règles existantes pour les chemins et liens symboliques.
+- Garder l’évaluation temporelle des observations hors d’un cache supposé immuable : une observation peut expirer sans changement de fichier.
+- Stocker le cache sous `.agentdoc/`, séparé du graphe publié. Écritures atomiques, concurrence contrôlée et récupération par recalcul après corruption ou interruption.
+- Exécuter un mode comparatif qui calcule aussi la compilation complète. Activer progressivement le chemin incrémental après comparaison des résultats.
+- Garder une compilation complète en CI comme référence indépendante du cache.
+
+**Fichiers :** `core/cache/`, `core/compile.mjs`, `core/fsx.mjs`, adaptateurs progressivement instrumentés, tests de mutations et de déterminisme.
+
+**Acceptation :** identité des graphes, diagnostics et provenances entre les deux chemins sur les mutations du corpus ; cache absent, corrompu ou périmé sans faux résultat frais ; bénéfice mesuré sur les petites modifications et requêtes répétées.
+
+**Livraison :** activation optionnelle, puis par défaut après validation. Revenir au calcul complet ne change pas le protocole.
+
+### Lot 6 — mémoire de session et `refresh`
+
+**Dépendance :** lots 3 et 4 ; le lot 5 accélère ce lot sans être nécessaire à sa correction.
+
+**Travaux**
+
+- Donner aux faits une identité logique stable et une version dépendant de leur contenu et de leurs preuves.
+- Enregistrer ce qui a été livré et explicitement retenu par le système qui pilote l’agent. « Livré » ne signifie pas « compris » ni « encore présent dans le contexte ».
+- Retourner les faits ajoutés, modifiés et rétractés, ainsi que les obligations de vérification invalidées.
+- Répéter les obligations critiques actives dans une enveloppe compacte ; ne pas dépendre d’un souvenir implicite du modèle.
+- Prévoir acquittement, réinitialisation et récupération d’un paquet complet après perte de session, compaction ou changement de modèle.
+- Ajouter un contrat d’import des résultats de vérification : commande, contexte, instantané, statut, preuve de sortie. Un résultat ne reste valide que si les entrées pertinentes et les conditions d’exécution le permettent.
+- Intégrer le runner d’agents pour remplacer le contexte actif et demander les preuves à la demande, au lieu d’empiler indéfiniment les réponses.
+- Isoler les sessions par dépôt, tâche et client ; borner leur stockage et proposer leur suppression.
+
+**Fichiers :** `core/session/`, `core/context/`, schéma de delta, commande `refresh`, intégration `evals/agent/`.
+
+**Acceptation :** appliquer les deltas reconstruit le même état qu’un nouveau paquet complet ; suppressions et rétractions transmises ; aucune vérification périmée réutilisée ; reprise correcte après oubli de contexte. Mesurer les tokens cumulés de session, pas seulement la taille du delta.
+
+### Lot 7 — expérimenter la représentation et l’analyse sémantique
+
+**Dépendance :** lots 2, 3 et 6.
+
+**Travaux**
+
+- Formaliser un vocabulaire de faits et obligations (`requires`, `forbids`, `depends_on`, `affects`, `verified_by`) avec portée, preuve, conditions et statut d’autorité.
+- Réutiliser les assertions et exigences normatives existantes. Une interprétation proposée par l’IA reste une hypothèse tant que les règles d’autorité ne permettent pas sa promotion ; ne pas confondre format structuré et vérité démontrée.
+- Comparer JSON compact, lignes typées et format tabulaire sur le même paquet sémantique. Inclure dans le coût l’apprentissage du format, les descriptions d’outils, les appels supplémentaires et les erreurs.
+- Choisir une première famille de tâches pour les symboles, par exemple les modifications d’API TypeScript. Extraire les symboles et usages nécessaires à la demande, avec une solution de repli au niveau du composant pour les usages dynamiques ou ambigus.
+- Garder les symboles dans un index auxiliaire versionné au début. Les cinq types d’entités normatifs du graphe ne sont pas étendus implicitement.
+- Ne réduire une obligation de vérification que lorsqu’une preuve permet cette exclusion. Une classification d’intention ou un score de pertinence ne suffit pas.
+
+**Acceptation :** le format ou l’analyse supplémentaire améliore le résultat sur les tâches réservées et sur les modèles retenus. Sinon, conserver le protocole précédent et retirer l’expérience du chemin par défaut.
+
+**Livraison :** chaque expérience est indépendante et réversible ; aucun langage propriétaire n’est un prérequis des lots antérieurs.
+
+### Lot 8 — optimisation continue contrôlée
+
+**Dépendance :** lot 2 ; chaque variante ne dépend que des fonctionnalités qu’elle modifie.
+
+**Travaux**
+
+- Autoriser un agent d’optimisation à proposer des changements bornés : classement, format, descriptions d’outils, stratégies d’approfondissement.
+- Limiter chaque campagne en coût, temps et nombre de variantes ; journaliser configuration et version des candidats.
+- Utiliser les tâches de développement pour la recherche et un jeu de validation séparé pour sélectionner les candidats. Réserver un test final aux décisions de livraison ; le renouveler quand des consultations répétées risquent de contaminer l’évaluation.
+- Conserver les variantes qui améliorent le compromis réussite/coût/latence. Ne pas modifier automatiquement les obligations, la vérité attendue ou les seuils pour faire accepter une variante.
+- Livrer les changements retenus par le processus normal du dépôt, avec mécanisme de retour à la version précédente. Ne pas auto-modifier le moteur en cours de session.
+
+**Acceptation :** une variante nuisible à la fiabilité est rejetée malgré sa brièveté ; les décisions sont reproductibles depuis les artefacts de campagne ; aucune dépendance à un service de modèle n’est requise pour le fonctionnement déterministe courant.
+
+## 5. Mesures et critères de décision
+
+| Mesure | Définition et usage |
+|---|---|
+| Réussite vérifiée | tâche terminée selon tests et contraintes indépendants d’AgentDoc |
+| Coût par réussite | coût de tous les essais, échecs inclus, divisé par le nombre de réussites ; indéfini si aucune réussite |
+| Erreurs critiques | obligation manquée, conflit masqué, preuve invalide, mauvais périmètre ou contexte d’exécution |
+| Tokens de session | entrées, sorties et raisonnement facturé si disponible ; tokens mis en cache distingués |
+| Latence | médiane et p95 des opérations et des tâches ; démarrage à froid séparé des appels répétés |
+| Charge locale | lectures, parsings, CPU, mémoire maximale et stockage des caches |
+| Coût des checks | temps réel des vérifications sélectionnées ; leur nombre seul ne mesure pas l’économie |
+
+Avant chaque campagne comparative, figer corpus, versions, paramètres, règles de coût, plafond d’essai et critères statistiques. Utiliser une comparaison appariée par tâche et rendre l’incertitude visible. Le pilote de 30 tâches ne suffit pas automatiquement à conclure sur de faibles écarts.
+
+Objectif initial proposé pour la refonte combinée : **réduire d’au moins 20 % le coût par réussite** sur la validation réservée, sans régression de fiabilité établie. Ce seuil est un objectif d’adoption à figer avant les essais, pas un gain déjà observé.
+
+Pour la non-infériorité du taux de réussite, préenregistrer une marge maximale de 2 points et exiger que la borne inférieure de l’intervalle de confiance à 95 % de l’écart reste au-dessus de −2 points. Une nouvelle erreur critique reproductible bloque l’adoption indépendamment de cette marge. Si l’échantillon ne permet pas de conclure, élargir la campagne ou conserver la version de référence ; ne pas conclure à l’équivalence par défaut.
+
+Les correctifs de fidélité restent livrables même s’ils augmentent les tokens. Les optimisations locales peuvent être intégrées si leur bénéfice est mesuré et leur correction démontrée, sans prétendre qu’elles satisfont seules l’objectif global de 20 %.
+
+## 6. Compatibilité, migration et livraison
+
+- Conserver les commandes historiques pendant l’introduction du protocole. Modifier les instructions du skill seulement après validation de son nouveau parcours.
+- Versionner séparément graphe, protocole et cache. Un format de cache incompatible peut être abandonné et recalculé ; un graphe incompatible doit être détecté et migré explicitement.
+- Toute évolution des champs normatifs du graphe passe par la politique de version de `docs/SPEC.md`. Les schémas fermés existants interdisent les ajouts implicites.
+- Pour `prepare`, annoncer explicitement l’utilisation de l’arbre de travail courant. Ne pas modifier silencieusement le contrat de fraîcheur du `query` historique.
+- Garder le cœur sans dépendance à une API de modèle. Isoler les dépendances de tokenizer et d’évaluation ; documenter leur version et leur disponibilité. Une nouvelle dépendance de production doit apporter un bénéfice vérifié et apparaître dans le test d’installation du paquet.
+- Tester l’installation depuis `npm pack`, la présence des nouveaux schémas et l’absence de dépendances accidentelles aux fichiers du dépôt de développement.
+- Mettre à jour `docs/SPEC.md`, `docs/QUERY.md`, `docs/VERIFICATION.md`, `docs/EVALS.md`, `docs/CI.md`, le skill, l’aide CLI et le changelog avec chaque fonctionnalité livrée. Ne pas annoncer une cible comme une capacité déjà présente.
+- Garder les tests déterministes sur la matrice Node 22/24/26. Les campagnes de modèles et de performance utilisent des environnements dédiés, épinglés, sans bloquer chaque changement documentaire.
+
+## 7. Ordre d’exécution et suivi
+
+| Livraison | Lots | Condition de passage |
+|---|---|---|
+| A — fiabilité et référence | 0, 1, 2 | sorties fidèles, tests isolés, runner et référence disponibles |
+| B — interface de travail | 3, 4 | paquet multi-chemins, budget vérifié, approfondissement et instantané cohérent |
+| C — réutilisation | 5, 6 | équivalence incrémentale et deltas corrects, bénéfices mesurés |
+| D — spécialisation | 7, 8 | amélioration confirmée sur validation réservée, retour arrière disponible |
+
+Les lots 1 et 2 peuvent avancer indépendamment après le lot 0. Les lots 5 et 6 peuvent avancer indépendamment après le lot 4. Cet ordre décrit les dépendances ; il n’impose pas d’exécution multi-agent.
+
+- [ ] Lot 0 — mesure et tests reproductibles.
+- [ ] Lot 1 — fidélité de toutes les sorties.
+- [ ] Lot 2 — évaluation de tâches par agents.
+- [ ] Lot 3 — protocole `prepare` / `expand` et budget réel.
+- [ ] Lot 4 — instantané, lectures et index partagés.
+- [ ] Lot 5 — compilation incrémentale persistante.
+- [ ] Lot 6 — mémoire de session et `refresh`.
+- [ ] Lot 7 — formats et analyse sémantique expérimentaux.
+- [ ] Lot 8 — boucle d’optimisation mesurée.
+
+**Premier changement à implémenter :** isoler la signature Git des fixtures, ajouter les reproductions des omissions Markdown comme tests de régression, puis corriger le rendu. Cette livraison apporte un résultat concret avant d’engager la refonte.
+
+## 8. État de la livraison 1.5.0
+
+| Lot | Résultat livré | Limite empirique ou fonctionnelle explicite |
+|---|---|---|
+| 0 | Fixtures sans signature héritée, télémétrie et benchmark local reproductible | Mesures locales sur six corpus ; pas de nouvelle campagne des dépôts publics |
+| 1 | Sorties Markdown fidèles, omissions et gates visibles, tests CLI | Les budgets historiques restent des plafonds par section |
+| 2 | Runner, 30 tâches synthétiques épinglées, driver Codex et smoke réel comparatif | Une tâche, un modèle, une répétition ne prouvent pas un gain général |
+| 3 | prepare / expand / refresh, schéma fermé, budget exact, preuves et continuations | Le cwd des checks reste explicitement inconnu quand il n’est pas démontré ; mêmes obligations conservatrices pour chaque intention |
+| 4 | Capture cohérente des octets et index partagé dans la préparation | Pas de serveur permanent ni cache des index entre processus |
+| 5 | Cache persistant de compilation complète et parsing JSON par contenu | Pas de reconstruction granulaire de tous les extracteurs ; retour au compilateur complet si nécessaire |
+| 6 | Deltas, rétractions, état logique complet, preuves d’exécution et nettoyage JS | L’intégration au contexte actif d’un harness externe reste à la charge de son appelant |
+| 7 | Faits typés et candidats TypeScript à la demande via API JS | Analyse lexicale partielle ; aucune exclusion de checks ni adoption d’un nouveau format sans mesure |
+| 8 | Optimiseur borné, proposeur de variantes déclarées, campagnes dev/holdout et sélection | Aucun gain de 20 % établi, aucune variante promue par le seul smoke ; validation finale indépendante exigée pour toute revendication |
+
+Les cases de la section 7 représentent les acceptations complètes du plan, y compris les campagnes empiriques étendues. La release fournit les mécanismes permettant ces campagnes sans présenter leurs objectifs comme des résultats déjà obtenus. Les nouveaux protocoles sont additifs ; les expériences non validées ne remplacent pas le chemin historique.

package/docs/QUERY.md

@@ -90,12 +90,16 @@ reading the whole specification.
 **Critical context is separated from the rest.** `authority.conflicts`,
 `authority.observations` and `constraints.constraints` are the things that cause
 the most damage when missed, and the markdown rendering puts them under explicit
-headings: `CONFLICTS (do not assume one is true)`, `RUNTIME OBSERVATIONS`,
-`CONSTRAINTS`.
+headings: `CONFLICTS (do not assume one is true)` for unresolved conflicts,
+`RESOLVED CONFLICTS` for recorded elections, `RUNTIME OBSERVATIONS`, and
+`CONSTRAINTS`. Runtime observations include the actual keys, values and semantics,
+not only their capture metadata.
 
 **Both sides of a conflict are printed.** A conflicted assertion shows its
 evidence class, its confidence and its value. The contradicted value is never
-withheld.
+withheld within a displayed conflict. Resolved conflicts also show their election,
+including the elected assertion and review condition; they are not presented as
+open decisions. A budget that omits entire conflicts is explicitly reported.
 
 **A contract subject carries the provider's and consumers' checks.** Changing an
 endpoint is proved by running their suites, so `verification` for an API subject
@@ -174,6 +178,20 @@ complete arrays under `constraints.docs`, `constraints.constraints` and
 `constraints.runbooks`; these markdown-only caps do not shorten the JSON arrays
 or `entity.spec.context`.
 
+The default Markdown format also displays typed relation directions and evidence
+classes, API providers/consumers and contracts, resource users, journey peers,
+assertions, contract operations and evidence pointers. Scoped checks retain their
+IDs and configuration paths. Repository gates are a separate required list;
+a scoped verification budget never removes them.
+
+Every capped JSON section that was shortened is repeated in an `INCOMPLETE
+CONTEXT` block, including nested authority sections, with its displayed and total
+counts. For example, `verification [truncated: 1 of 4]` means three required
+verification recommendations are still omitted. Request the same query with a
+larger `--budget verification=...` before treating the list as complete. Truncated
+relations and evidence are likewise identified rather than silently disappearing
+from the default response.
+
 `--md` (the default) produces a compact block suitable for a prompt or a human:
 
 ```
@@ -184,7 +202,7 @@ Triggers governed endpoints on a platform schedule and owns no business logic.
 - CONSTRAINTS: workers/koda-cron/CONSTRAINTS.md
 - verify:
   - [unit] vitest run
-- CONFLICTS (do not assume one is true):
+- RESOLVED CONFLICTS (use the recorded election; re-check its review condition):
   - schedule.cron [contradiction/resolved]
     - DERIVED/deterministic: "0 3 * * *"
     - OBSERVED_RUNTIME/direct: "0 * * * *,3 0 * * *"
@@ -267,6 +285,6 @@ Ask for `--md` and give the output to the agent as-is. Two rules keep it
 honest:
 
 1. Do not summarise a conflict away. If the context contains a `CONFLICTS`
-   block, the agent must be told about it.
+   block, the agent must be told about it, including its status and any recorded election.
 2. If the context contains `UNRESOLVED` or a conflict with `basis: none`, the
    correct agent behaviour is to say so and stop, not to choose a side.

package/docs/ci/github-actions.yml

@@ -21,7 +21,7 @@ jobs:
         with: { node-version: '24' }
       - name: Install the agentdoc CLI
         # Unpinned tracks main. For CI reproducibility pin a tag or commit:
-        #   github:lbframe/agent-doc-system#v1.4.0
+        #   github:lbframe/agent-doc-system#v1.5.1
         # A compiler upgrade intentionally invalidates committed graphs.
         run: npm install -g github:lbframe/agent-doc-system
       - name: Validate and compile

package/evals/agent/codex-driver.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// Optional local Codex driver. Uses the user's configured model/provider unchanged.
+import readline from 'node:readline';
+import {spawn} from 'node:child_process';
+const lines=readline.createInterface({input:process.stdin});
+let request;
+for await(const line of lines){request=JSON.parse(line);break;}
+if(!request||request.protocol!=='agentdoc.eval.driver/v1')throw new Error('invalid evaluation request');
+const prompt=[request.instructions,request.task.prompt,'Task paths: '+request.task.paths.join(', '),
+  'Budget: '+JSON.stringify(request.budget),'Context supplied by '+request.condition+':',...request.context,
+  'Work only in this temporary task repository. Finish after implementing and checking the fix.'].join('\n\n');
+const child=spawn('codex',['exec','--json','--ephemeral','--skip-git-repo-check','-s','workspace-write','-C',request.workspace,'-'],{stdio:['pipe','pipe','pipe']});
+const emit=x=>process.stdout.write(JSON.stringify(x)+'\n');
+let inputTokens=0,outputTokens=0,cachedInputTokens=0,toolCalls=0,failed=false;
+const usage=()=>({inputTokens,outputTokens,cachedInputTokens,toolCalls,costUsd:null});
+const stop=()=>{failed=true;child.kill('SIGKILL');};
+child.stdin.end(prompt);
+child.stderr.on('data',chunk=>process.stderr.write(chunk));
+const exited=new Promise(resolve=>{child.on('error',error=>{console.error(error.message);resolve(1);});child.on('close',resolve);});
+const reader=readline.createInterface({input:child.stdout});
+for await(const line of reader){
+  let event;try{event=JSON.parse(line);}catch{continue;}
+  if(event.type==='item.completed'&&['command_execution','mcp_tool_call','web_search'].includes(event.item?.type))toolCalls++;
+  if(event.type==='turn.completed'){
+    inputTokens+=event.usage?.input_tokens||0;outputTokens+=event.usage?.output_tokens||0;cachedInputTokens+=event.usage?.cached_input_tokens||0;
+    emit({type:'usage',usage:usage()});
+  }
+  if(event.type==='turn.failed'||event.type==='error'){failed=true;emit({type:'trace',message:event.error?.message||event.message||event.type});}
+  if(inputTokens+outputTokens>request.budget.maxTokens||toolCalls>request.budget.maxToolCalls)stop();
+}
+const code=await exited;
+emit({type:'usage',usage:usage()});emit({type:'result',completed:code===0&&!failed});process.exitCode=code===0&&!failed?0:1;

package/evals/agent/optimize.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// Bounded offline selection of agent-proposed context variants. Never edits core code.
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {campaign,runProcess,selectCandidate} from './run.mjs';
+import {tasks,publicTask} from './tasks/corpus.mjs';
+
+export async function optimize(config){
+  if(!Number.isInteger(config.maxCandidates)||config.maxCandidates<1||config.maxCandidates>20)throw new Error('maxCandidates must be an integer in [1,20]');
+  const variants=config.variants;
+  if(!variants||!Object.keys(variants).length||Object.keys(variants).length>config.maxCandidates)throw new Error('declare at most maxCandidates context variants');
+  if(Object.keys(variants).some(id=>id==='reference'||!(/^[a-z][a-z0-9-]*$/).test(id)))throw new Error('variant names must be unique non-reference identifiers');
+  if(!config.reference)throw new Error('reference condition required');
+  let ids=Object.keys(variants);
+  if(config.proposer){
+    const r=await runProcess(config.proposer,{cwd:process.cwd(),timeoutMs:config.proposerTimeoutMs||30000,maxOutputBytes:65536,input:JSON.stringify({protocol:'agentdoc.eval.proposal/v1',developmentTasks:tasks.filter(t=>t.split==='development').map(publicTask),allowedVariants:variants,maxCandidates:config.maxCandidates})+'\n'});
+    if(r.code!==0||r.reason||r.error)throw new Error('proposal driver failed');
+    const proposed=JSON.parse(r.stdout);
+    if(!Array.isArray(proposed.variants)||!proposed.variants.length||proposed.variants.length>config.maxCandidates||new Set(proposed.variants).size!==proposed.variants.length||proposed.variants.some(id=>!Object.hasOwn(variants,id)))throw new Error('proposal contains an undeclared variant');
+    ids=proposed.variants;
+  }
+  const base=config.campaign;
+  if(!base||!Number.isFinite(config.maxTotalCostUsd)||config.maxTotalCostUsd<=0||!Number.isFinite(base.budget?.maxCostUsd)||base.budget.maxCostUsd<=0)throw new Error('optimization requires measured per-attempt and total dollar caps');
+  let spent=0;
+  const run=async(split,conditions)=>{
+    const remaining=config.maxTotalCostUsd-spent;
+    if(remaining<base.budget.maxCostUsd)throw new Error('optimization campaign budget exhausted');
+    const report=await campaign({...base,tasks:undefined,split,conditions,maxCampaignCostUsd:remaining});
+    if(report.summary.totalCostUsd===null)throw new Error('optimization stopped: unmeasured cost');
+    spent+=report.summary.totalCostUsd;
+    return report;
+  };
+  const conditions={reference:config.reference,...Object.fromEntries(ids.map(id=>[id,variants[id]]))};
+  const development=await run('development',conditions);
+  if(development.stopped||development.summary.infrastructureErrors)return {status:'inconclusive',reason:development.stopped||'infrastructure-errors',spent,development};
+  const ranked=ids.sort((a,b)=>{
+    const x=development.conditions[a],y=development.conditions[b];
+    return y.successRate-x.successRate||(x.costPerSuccess??Infinity)-(y.costPerSuccess??Infinity)||a.localeCompare(b);
+  });
+  const candidate=ranked[0];
+  const validation=await run('holdout',{reference:config.reference,[candidate]:variants[candidate]});
+  const decision=validation.stopped?{adopt:false,reason:validation.stopped}:selectCandidate(validation.attempts.filter(x=>x.condition==='reference'),validation.attempts.filter(x=>x.condition===candidate),config.criteria);
+  return {schemaVersion:'agentdoc.eval.optimization/v1',status:decision.adopt?'candidate-selected':'inconclusive',candidate,decision,spent,development,validation,publication:'not-performed',finalTest:'required-on-independent-tasks-before-production-performance-claims'};
+}
+if(process.argv[1]&&fs.existsSync(process.argv[1])&&fs.realpathSync(process.argv[1])===fs.realpathSync(fileURLToPath(import.meta.url))){
+  try{const config=JSON.parse(fs.readFileSync(process.argv[2],'utf8'));const report=await optimize(config);const text=JSON.stringify(report,null,2)+'\n';if(process.argv[3])fs.writeFileSync(process.argv[3],text);else process.stdout.write(text);if(report.status!=='candidate-selected')process.exitCode=1;}catch(e){console.error(e.message);process.exitCode=2;}
+}