Cette page est traduite de la documentation anglaise. Les commandes, identifiants et exemples sont inchangés. Runtime 7.24.4 · SDK 2.6.7. Source anglaise

Assurance des objectifs

Statut : actuel Portée : contrôles d’acceptation des objectifs et fraîcheur des sources Dernière revue : 2026-09-14 Responsable : mainteneurs du runtime AX Code

Les plans de changement de code produits par le planificateur d’objectifs déclarent des contrôles d’acceptation exécutables. Chaque contrôle nomme le résultat qu’il couvre, sa commande exacte, son rôle et l’environnement visé. AX Code enregistre une preuve d’exécution lorsque l’agent lance verify_project avec l’identifiant goalCheck du contrôle.

{ "goalCheck": "invoice-parity" }

La commande vient du plan d’objectif figé. L’agent ne peut pas la remplacer par une autre commande par cet appel. Les permissions bash existantes s’appliquent toujours. Achever l’objectif exige que la dernière tentative de chaque contrôle déclaré réussisse, avec un objectif, une session, un espace de travail, un contrat et un contenu de source correspondants. La prose d’acceptation explique le résultat ; elle ne remplace pas les contrôles exécutés. Les exécutions shell ordinaires et les contrôles entièrement sautés ne peuvent pas fournir cette preuve.

Les anciens plans d’objectif sans assurance conservent leurs règles d’achèvement antérieures. Effacez et recréez un ancien objectif lorsque vous avez besoin du nouveau contrat ; modifier sur place ses exigences figées provoque un écart de contrat. Un fork conserve le contrat, mais exige de nouvelles exécutions de contrôles dans la nouvelle session.

Préparer un projet de migration

Fournissez une source ou des exports hérités faisant autorité, avec des identifiants de révision, un inventaire de couverture borné, et des scripts de contrôle qui échouent lorsque les assertions ne peuvent pas être vérifiées. Traitez les commentaires et les implémentations de migration antérieures comme des pistes à examiner. Enregistrez les changements de comportement approuvés à part des exigences de parité avec l’existant.

Choisissez des contrôles pour les couches que le changement demandé affecte réellement :

Les scripts doivent affirmer l’identité de la cible avant d’effectuer leurs contrôles. Conservez les authentifiants dans le mécanisme d’authentifiants déjà présent du projet, jamais dans le texte du plan, les commandes ou les descriptions de cible. Un contrôle doit renvoyer un code de sortie non nul pour une assertion en échec, un environnement manquant ou une assertion exigée qui a été sautée. Évitez les enveloppes qui masquent les échecs. AX Code ne peut pas inférer des assertions à partir d’une sortie de processus réussie.

Pour les grandes migrations, organisez le travail en lots bornés de flux métier et tenez un inventaire qui relie formulaires, dépendances, références héritées et contrôles d’acceptation. Rapportez à la fois le lot accepté et la couverture restante. La réussite d’un lot n’achève pas toute la migration.

Ce qu'un plan enregistre

Le planificateur fournit un objet assurance. Ce fragment illustratif suppose que le projet possède l’export de source et le script de contrôle cités :

{
  "version": 1,
  "sourcePaths": ["src", "checks", "package.json"],
  "sources": [
    { "role": "legacy", "reference": "legacy/invoice-schema.sql at export-v1" },
    { "role": "requirement", "reference": "Invoice acceptance criteria supplied by the user" }
  ],
  "checks": [
    {
      "id": "invoice-parity",
      "acceptanceIds": ["AC1"],
      "command": "node checks/invoice-parity.cjs",
      "purpose": "Assert invoice behavior, database mappings and target identity",
      "environment": "Staging migration target, schema ERP"
    }
  ]
}

Tous les identifiants d’acceptation doivent être couverts. Les commandes s’exécutent depuis la racine de l’espace de travail. L’objet d’assurance est figé avec le contrat d’acceptation. L’agent reçoit, dans le contexte d’objectif qui continue, le périmètre validé, les références de source, les identifiants de contrôle et les cibles déclarées. Des contrats manquants ou altérés produisent un avis de restauration. Les résumés de conversation générés restent faillibles ; les références déclarées et les libellés de cible sont des exigences, pas des faits observés indépendamment.

Les plages Git qui mesurent ce que cet objectif a changé doivent utiliser {BASELINE} comme état antérieur. Le planificateur réécrit cette marque de substitution vers le SHA de HEAD capturé à la soumission du plan, afin que des commits déjà présents en avant de origin/main ou un arbre de travail sale ne rendent pas l’objectif inachevable. Les références de suivi distant (origin/main, @{u}, refs/remotes/…) sont rejetées comme cet état antérieur, sauf si l’objectif nomme le distant. Enregistrez les chemins déjà divergents ou sales sous Risques ; ne figez pas un contrôle bloquant qui échoue déjà, sauf si l’objectif est de corriger cet échec.

Fraîcheur et limites

Les empreintes de source Git incluent les octets réels des fichiers suivis et des fichiers non suivis non ignorés dans le sourcePaths déclaré. Les chemins de fichiers explicites incluent aussi les fichiers de configuration ignorés ; les chemins de répertoires conservent les règles d’ignorance Git. Les listes de contrôle mutables du plan d’objectif sont exclues ; leurs exigences figées sont contrôlées par le condensé du contrat. Les projets hors Git empreintent récursivement les sourcePaths déclarés, y compris les chemins manquants. Incluez dans ce périmètre chaque source pertinente, chaque fichier de configuration et chaque script de contrôle.

L’empreinte est limitée à 20,000 entrées et 128 MiB de contenu de fichiers. Une source liée, des dépôts Git imbriqués, des fichiers spéciaux, des chemins qui s’échappent, des fichiers qui changent et des lectures indisponibles ne peuvent pas produire une preuve fraîche. De tels échecs bloquent l’achèvement assuré. Les artefacts de sortie des contrôles doivent aller dans un emplacement ignoré, afin que produire un rapport ne change pas la source en cours de vérification.

Les fichiers ignorés non nommés explicitement, les dépendances hors du périmètre des sources, les bases et les déploiements ont besoin d’assertions dans la commande du projet. Un reçu enregistre une observation au moment de son exécution ; il ne prouve pas que l’état externe est resté inchangé. Relancez les contrôles affectés après un changement de configuration, de base ou de déploiement. AX Code ne découvre pas automatiquement tout le comportement hérité et ne certifie pas la parité de migration.

Quand la planification s'exécute

La planification est sur activation, sur les deux surfaces. /goal <objective> et create_goal sans assure démarrent l’objectif immédiatement : il ne porte pas de critères d’acceptation figés, et l’achèvement est jugé par le plan de travail (tâches en attente) plus une vérification réussie après le dernier changement. /goal --assure <objective> et create_goal avec assure: true exécutent d’abord le rédacteur de plan, ce qui fait des reçus de contrôles exécutés ci-dessous une exigence d’achèvement.

Un objectif sans contrat le dit partout où il est montré (/goal view, la boîte de l’objectif, les messages de contrôle), afin que sa barrière d’achèvement ne soit jamais quelque chose à deviner. /goal replace conserve l’assurance lorsque l’objectif remplacé a un contrat valide.

Contexte de planification et choix du modèle

La planification d’objectif hérite du modèle de session choisi, à la fois par /goal et par l’outil create_goal. Les variantes compatibles de l’appelant sont conservées. Le rédacteur en lecture seule reçoit les exigences utilisateur originales récentes et les références de pièces jointes, avec un budget d’enregistrement de 16 KiB. Un enregistrement trop grand arrête l’inclusion des enregistrements plus anciens, avec un avis, afin qu’une exigence plus ancienne ne remplace pas en silence une correction omise ; le contenu média en ligne n’est pas traité comme une preuve inspectée. Fournissez des fichiers sources inspectables pour les exigences qui ne sont présentes que dans un média.

Progrès et blocages

get_goal inclut le statut courant des contrôles (réussi, échoué, périmé, en cours ou manquant) et les identifiants de preuves d’outils récents. La barrière d’achèvement exige encore des reçus réussis et courants. Une mise à jour bloquée exige un type de blocage, une raison, le changement externe requis, les identifiants de preuves originales, et la confirmation qu’il ne reste aucun travail indépendant. Les raisons de blocage sont des déclarations du modèle, appuyées sur des enregistrements inspectables, pas une certification qu’un service externe reste indisponible.

Les tours terminés qui ne produisent à plusieurs reprises aucune nouvelle preuve d’outil réussie reçoivent une consigne de reprise, puis mettent l’objectif en pause avec le travail inachevé signalé. De nouveaux résultats de recherche peuvent compter sans modification de source ; les réécritures de tâches et les résultats identiques répétés ne comptent pas. C’est une heuristique bornée, pas une preuve de progrès sémantique. /goal resume démarre une autre tentative. Les appels d’outils générés pour un objectif antérieur ne peuvent pas terminer son remplaçant. Un objectif créé par un outil est disponible pour les mises à jour de statut une fois que le modèle a reçu le résultat de création à son étape suivante.

Réviser un plan existant

Utilisez /goal revise <correction> pour réviser explicitement un objectif figé actif, en pause ou bloqué. Un travail achevé et des budgets épuisés exigent un nouvel objectif. Le plan et le condensé précédents restent intacts. Le plan révisé reçoit une identité neuve et un enregistrement local de révision préparée, qui relie les deux condensés et la correction. L’identité courante de l’objectif détermine quel candidat a réellement été installé ; les candidats concurrents en échec peuvent rester sur disque pour inspection. Les anciens reçus restent dans l’historique et ne peuvent pas satisfaire la nouvelle révision. Le budget de jetons et l’usage accumulé sont reportés ; la révision n’accorde pas un nouveau budget de dépense.

La révision annule l’exécution en cours et met l’objectif en pause pendant la préparation du nouveau plan. Si la planification échoue, le contrat précédent reste reprenable ; un objectif déjà bloqué conserve ce statut. Une pause ou une annulation par l’utilisateur pendant la planification empêche l’activation. Un remplacement concurrent empêche le candidat de prendre la main. Les outils du modèle ne peuvent pas réviser en silence les exigences figées. Revoyez le plan résultant et ses critères d’acceptation ; une commande exécutable seule n’établit pas que ses assertions couvrent la demande corrigée.

Résultats de revue et changements de source ultérieurs

Un journal de revue non vide n’établit pas une revue réussie. Pour les relecteurs externes exigés, utilisez un contrôle appartenant au projet qui valide le code de sortie réel, l’achèvement terminal, l’identité de la source ou du diff, et les constats finaux ou un verdict explicite d’absence de constat. Les journaux seulement d’avertissement, le raisonnement partiel et les expirations doivent échouer. Conservez les tentatives en échec à part, pour le diagnostic.

Les nouvelles soumissions de changement de code rejettent les contrôles simples reconnus de présence de fichier et d’inspection. C’est une garde d’admission étroite, pas une preuve sémantique de commandes shell arbitraires. Les contrats figés existants conservent leur schéma et leur condensé ; les points de contrôle avertissent lorsqu’un contrôle plus ancien a cette faiblesse.

La fraîcheur des contrôles d’objectif empreinte aussi les chemins de fichiers résolus, signalés par les outils d’édition de fichiers réussis pendant l’objectif courant, y compris chaque résultat multiedit et les chemins omis de la liste de sources originale. Des modifications ultérieures de ces fichiers invalident les reçus antérieurs. Le contrat figé et le condensé sont inchangés. Ce suivi utilise les métadonnées de résultat des outils de fichiers ; il n’infère pas les effets de bord shell arbitraires ni la couverture de tests. Les limites existantes de confinement du système de fichiers, de liens, de taille et de nombre de fichiers s’appliquent toujours.

La sortie des contrôles et les points de contrôle d’objectif signalent les chemins supplémentaires. Si une commande de test figée omet des régressions nécessaires, demandez /goal revise <correction> et exécutez les contrôles révisés. Inclure un fichier dans une empreinte prouve la fraîcheur, pas qu’un test a exercé ce fichier. Préférez des répertoires de sources bornés et des commandes de test qui incluent les nouvelles régressions lorsque vous planifiez un balayage de bogues ouvert.

Les alias d’espace de travail sont normalisés pour les chemins de fichiers observés. Les fichiers de brouillon externes ne deviennent pas des entrées de source de l’espace de travail ; les points de contrôle signalent que le contenu externe n’est pas empreint. L’état externe exigé a encore besoin d’une vérification appartenant au projet.

Preuve du périmètre de commit

Un git log <baseline>..HEAD -- <paths> non vide prouve seulement qu’un commit correspond au filtre. Il n’exclut ni les fichiers sans lien dans ce commit, ni d’autres commits. Les nouveaux plans de changement de code rejettent les assertions Git-log autonomes reconnues, non vides et filtrées par chemin ; les contrôles figés plus anciens reçoivent une consigne de révision sans changement de leur condensé ni de la validation au moment de la lecture.

Utilisez un vérificateur appartenant au projet qui contrôle l’ascendance de la base, exige une plage non vide et inspecte chaque chemin changé de chaque commit, sans filtre de chemin. Incluez les fichiers supprimés et les deux côtés des renommages, traitez explicitement les commits de fusion, et validez à part toute propriété exigée de branche ou de message. Utilisez /goal revise pour renforcer un contrat existant ; ne modifiez pas les exigences figées.

Taille du plan et nouvelle soumission complète

Le plan rendu, y compris le Markdown et le JSON d’assurance, doit tenir dans 8,192 octets UTF-8. Visez moins de 7,168 octets. Si la soumission dépasse le plafond, raccourcissez la prose répétée et resoumettez l’objet complet, y compris kind et tous les champs exigés. Conservez les identifiants et les contrôles d’acceptation ; le runtime ne tronque pas les exigences et n’élève pas la limite de lecture pour accepter un plan trop grand.

Reçus de revue d'animation de la CLI locale

Le packages/ax-code/script/verify-cli-review-receipts.ts appartenant au dépôt contrôle les artefacts round-* sous la racine de reçus choisie avec --root. Chaque tour exige revision.txt, et chacun de grok, claude et codex exige exit.txt avec 0 et un verdict final dans stdout.jsonl (événements texte Grok) ou stdout.txt (Claude/Codex). Conservez les tentatives en échec hors des répertoires de tours achevés ; ne transformez pas les échecs en reçus de code de sortie zéro.

dispositions.json contient un tableau findings. Chaque entrée nomme round, cli, id, status (fixed ou rejected) et un evidence non vide. Les entrées fixes exigent en plus un objet regression avec un chemin de dépôt littéral file sous packages/ax-code/test/cli/tui/ et le fullName Vitest exact. Des dispositions en double ou plusieurs verdicts ambigus échouent.

Le vérificateur exécute ces fichiers avec le Vitest installé, le défaut de nouvel essai global réglé à zéro (les options de test individuelles peuvent remplacer ce défaut), puis contrôle que chaque assertion citée a réussi exactement une fois. Les assertions manquantes, sautées, en échec ou ambiguës font échouer la vérification. Cela prouve que ces tests cités ont réussi, pas que leurs assertions couvrent sémantiquement le constat. Les dispositions rejetées restent des jugements enregistrés. Un tour final doit correspondre au HEAD courant ; les constats marqués corrigés exigent une révision plus récente et un tour de revue. Des changements non validés de source, de test ou de configuration du paquet central empêchent la vérification. Gardez la configuration locale sans lien ax-code.json hors des commits.

Pour ce dépôt, vitest run --dir test/cli/tui conserve les exclusions de la voie normale tout en parcourant le répertoire du TUI. Les lanceurs de groupe peuvent encore choisir des fichiers exacts avec AX_TEST_FILES ; choisir un répertoire ne désactive pas les exclusions.