Questa pagina è tradotta dalla documentazione inglese. Comandi, identificatori ed esempi restano invariati. Runtime 7.24.4 · SDK 2.6.7. Testo inglese

Assicurazione degli obiettivi

Stato: Attuale Ambito: controlli di accettazione degli obiettivi e freschezza delle fonti Ultima revisione: 2026-09-14 Responsabile: responsabili del runtime di AX Code

I piani di modifica del codice prodotti dal pianificatore degli obiettivi dichiarano controlli di accettazione eseguibili. Ogni controllo nomina l’esito che copre, il comando esatto, lo scopo e l’ambiente previsto. AX Code registra l’evidenza di esecuzione quando l’agente esegue verify_project con l’id goalCheck del controllo.

{ "goalCheck": "invoice-parity" }

Il comando arriva dal piano dell’obiettivo congelato. L’agente non può sostituirlo con un comando diverso tramite questa chiamata. Le autorizzazioni bash esistenti si applicano comunque. Completare l’obiettivo richiede che l’ultimo tentativo di ogni controllo dichiarato passi con obiettivo, sessione, workspace, contratto e contenuto delle fonti corrispondenti. La prosa di accettazione spiega il risultato; non sostituisce i controlli eseguiti. Le esecuzioni di shell ordinarie e i controlli saltati per intero non possono fornire questa evidenza.

I piani di obiettivo vecchi, senza assicurazione, conservano le regole di completamento precedenti. Cancella e ricrea un obiettivo vecchio quando ti serve il nuovo contratto; modificare sul posto i requisiti congelati provoca una discordanza di contratto. Una biforcazione conserva il contratto ma richiede esecuzioni di controllo nuove nella nuova sessione.

Preparare un progetto di migrazione

Fornisci sorgente o esportazioni legacy autorevoli, con identificatori di revisione, un inventario di copertura limitato e script di controllo che falliscono quando le asserzioni non si possono verificare. Tratta i commenti e le implementazioni di migrazione precedenti come piste da indagare. Registra le modifiche di comportamento approvate separatamente dai requisiti di parità con il legacy.

Seleziona i controlli per i livelli che la modifica richiesta tocca davvero:

Gli script devono asserire l’identità del bersaglio prima di eseguire i propri controlli. Tieni le credenziali nel meccanismo di credenziali già usato dal progetto, mai nel testo del piano, nei comandi o nelle descrizioni del bersaglio. Un controllo dovrebbe restituire un codice di uscita diverso da zero per un’ asserzione fallita, un ambiente mancante o un’asserzione obbligatoria saltata. Evita involucri che mascherano i fallimenti. AX Code non può dedurre asserzioni da un’uscita di processo riuscita.

Per le migrazioni grandi, organizza il lavoro in lotti limitati di flusso di business e mantieni un inventario che collega moduli, dipendenze, riferimenti legacy e controlli di accettazione. Riporta sia il lotto accettato sia la copertura restante. Superare un lotto non completa l’intera migrazione.

Che cosa registra un piano

Il pianificatore fornisce un oggetto assurance. Questo frammento illustrativo assume che il progetto abbia l’esportazione di sorgente e lo script di controllo citati:

{
  "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"
    }
  ]
}

Tutti gli id di accettazione devono essere coperti. I comandi si eseguono dalla radice del workspace. L’oggetto di assicurazione è congelato insieme al contratto di accettazione. L’agente riceve ambito validato, riferimenti alle fonti, id dei controlli e bersagli dichiarati nel contesto continuativo dell’obiettivo. Contratti mancanti o alterati producono un avviso di ripristino. I riepiloghi di conversazione generati restano fallibili; i riferimenti dichiarati e le etichette dei bersagli sono requisiti, non fatti osservati in modo indipendente.

Gli intervalli Git che misurano che cosa ha cambiato questo obiettivo devono usare {BASELINE} come stato precedente. Il pianificatore riscrive quel segnaposto nello SHA di HEAD catturato quando il piano viene inviato, così i commit preesistenti davanti a origin/main o un albero di lavoro sporco non possono rendere l’obiettivo incompletabile. I ref di tracciamento remoto (origin/main, @{u}, refs/remotes/…) sono rifiutati come quello stato precedente, salvo che l’obiettivo nomini il remoto. Registra sotto Rischi i percorsi già divergenti o sporchi; non congelare un controllo di soglia che sta già fallendo, salvo che l’obiettivo sia correggere quel fallimento.

Freschezza e limiti

Le impronte delle fonti Git includono i byte reali dei file tracciati e di quelli non tracciati e non ignorati dentro l’ambito dichiarato sourcePaths. I percorsi di file espliciti includono anche i file di configurazione ignorati; i percorsi di directory conservano le regole di ignore di Git. Le checklist mutabili del piano dell’obiettivo sono escluse; i loro requisiti congelati sono controllati tramite il digest del contratto. I progetti non Git improntano in modo ricorsivo gli ambiti dichiarati sourcePaths, inclusi i percorsi mancanti. Includi in quell’ambito ogni sorgente pertinente, ogni file di configurazione e ogni script di controllo.

L’impronta è limitata a 20,000 voci e a 128 MiB di contenuto dei file. Sorgenti collegate, repository Git annidati, file speciali, percorsi che escono, file che cambiano e letture non disponibili non possono produrre evidenza fresca. Tali fallimenti bloccano il completamento assicurato. Gli artefatti di output dei controlli dovrebbero andare in una posizione ignorata, così produrre un report non cambia la sorgente che si sta verificando.

I file ignorati non nominati in modo esplicito, le dipendenze fuori dall’ambito delle fonti, i database e le distribuzioni hanno bisogno di asserzioni nel comando del progetto. Una ricevuta registra un’osservazione al momento dell’esecuzione; non dimostra che lo stato esterno sia rimasto invariato. Riesegui i controlli interessati dopo aver cambiato configurazione, database o distribuzioni. AX Code non scopre in automatico tutto il comportamento legacy e non certifica la parità della migrazione.

Quando gira la pianificazione

La pianificazione è su adesione su entrambe le superfici. /goal <objective> e create_goal senza assure avviano l’obiettivo subito: non porta criteri di accettazione congelati, e il completamento è giudicato dal piano di lavoro (attività in sospeso) più una verifica superata dopo l’ultima modifica. /goal --assure <objective> e create_goal con assure: true eseguono prima il redattore del piano, ed è questo che rende le ricevute dei controlli eseguiti, sotto, un requisito di completamento.

Un obiettivo senza contratto lo dice ovunque venga mostrato (/goal view, la finestra dell’obiettivo, i messaggi di controllo), così la sua soglia di completamento non è mai qualcosa che devi dedurre. /goal replace conserva l’assicurazione quando l’obiettivo sostituito ha un contratto valido.

Contesto di pianificazione e selezione del modello

La pianificazione dell’obiettivo eredita il modello di sessione selezionato sia tramite /goal sia tramite lo strumento create_goal. Le varianti compatibili del chiamante sono conservate. Il redattore in sola lettura riceve i requisiti utente originali recenti e i riferimenti agli allegati, con un budget di registro di 16 KiB. Un registro troppo grande ferma l’inclusione dei registri più vecchi, con un avviso, così i requisiti più vecchi non possono sostituire in silenzio una correzione omessa; il contenuto multimediale in linea non è trattato come evidenza ispezionata. Fornisci file sorgente ispezionabili per i requisiti presenti solo nei media.

Progresso e blocchi

get_goal include lo stato corrente dei controlli (superato, fallito, stantio, in esecuzione o mancante) e gli ID di evidenza degli strumenti recenti. La soglia di completamento richiede comunque ricevute correnti riuscite. Un aggiornamento bloccato richiede un tipo di blocco, una ragione, il cambiamento esterno necessario, gli ID dell’evidenza originale e la conferma che non resta lavoro indipendente. Le ragioni dei blocchi sono dichiarazioni del modello sostenute da registri ispezionabili, non una certificazione che un servizio esterno resti non disponibile.

I turni finiti che producono ripetutamente nessuna nuova evidenza di strumento riuscita ricevono una guida di recupero, poi mettono in pausa l’obiettivo con il lavoro incompiuto dichiarato. Nuovi risultati di ricerca possono contare senza modifiche alle fonti; le riscritture delle attività e i risultati identici ripetuti no. È un’euristica limitata, non una prova di progresso semantico. /goal resume avvia un altro tentativo. Le chiamate di strumenti generate per un obiettivo precedente non possono terminare il suo sostituto. Un obiettivo creato da uno strumento è disponibile per gli aggiornamenti di stato dopo che il modello ha ricevuto il risultato della creazione nel passo successivo.

Rivedere un piano esistente

Usa /goal revise <correction> per rivedere in modo esplicito un obiettivo congelato attivo, in pausa o bloccato. Il lavoro completato e i budget esauriti richiedono un obiettivo nuovo. Il piano precedente e il digest restano intatti. Il piano rivisto ottiene un’identità nuova e un registro locale di revisione preparata che collega entrambi i digest e la correzione. L’identità corrente dell’obiettivo determina quale candidato è stato davvero installato; i candidati concorrenti falliti possono restare su disco per l’ispezione. Le ricevute vecchie restano nella cronologia e non possono soddisfare la revisione nuova. Il budget di token e l’uso accumulato si trasferiscono; la revisione non concede un budget di spesa nuovo.

La revisione annulla l’esecuzione corrente e mette in pausa l’obiettivo mentre prepara il piano nuovo. Se la pianificazione fallisce, il contratto precedente resta riprendibile; un obiettivo già bloccato conserva quello stato. Una pausa o un annullamento dell’utente durante la pianificazione impedisce l’attivazione. Una sostituzione concorrente impedisce al candidato di prendere il controllo. Gli strumenti del modello non possono rivedere in silenzio i requisiti congelati. Revisiona il piano risultante e i suoi criteri di accettazione; un comando eseguibile da solo non stabilisce che le sue asserzioni coprano la richiesta corretta.

Risultati di revisione e modifiche successive delle fonti

Un log di revisione non vuoto non stabilisce una revisione riuscita. Per i revisori esterni obbligatori, usa un controllo di proprietà del progetto che valida il codice di uscita reale, il completamento del terminale, l’identità della sorgente o del diff, e i rilievi finali oppure un verdetto esplicito di assenza di rilievi. I log solo di avviso, il ragionamento parziale e i timeout devono fallire. Conserva separatamente i tentativi falliti per la diagnosi.

I nuovi invii di modifica del codice rifiutano i controlli riconosciuti di semplice presenza e ispezione dei file. È una guardia di ammissione stretta, non una prova semantica di comandi di shell arbitrari. I contratti congelati esistenti conservano schema e digest; i checkpoint avvisano quando un controllo più vecchio ha questa debolezza.

La freschezza dei controlli dell’obiettivo impronta anche i percorsi di file risolti riportati dagli strumenti di modifica dei file riusciti durante l’obiettivo corrente, incluso ogni risultato multiedit e i percorsi omessi dall’ elenco originale delle fonti. Modifiche successive a quei file invalidano le ricevute precedenti. Il contratto congelato e il digest non cambiano. Questo tracciamento usa i metadati del risultato degli strumenti sui file; non deduce effetti collaterali arbitrari della shell né la copertura dei test. I limiti esistenti di contenimento del filesystem, di collegamenti, di dimensione e di conteggio dei file si applicano comunque.

L’output dei controlli e i checkpoint dell’obiettivo dichiarano percorsi aggiuntivi. Se un comando di test congelato omette regressioni necessarie, richiedi /goal revise <correction> ed esegui i controlli rivisti. Includere un file in un’impronta dimostra la freschezza, non che un test abbia esercitato quel file. Preferisci directory di sorgente limitate e comandi di test che includano le nuove regressioni quando pianifichi una ricerca di bug a estremi aperti.

Gli alias del workspace sono normalizzati per i percorsi di file osservati. I file di appoggio esterni non diventano input di sorgente del workspace; i checkpoint dichiarano che il contenuto esterno non è improntato. Lo stato esterno obbligatorio ha comunque bisogno di verifica di proprietà del progetto.

Evidenza dell'ambito dei commit

Un git log <baseline>..HEAD -- <paths> non vuoto dimostra solo che un commit corrisponde al filtro. Non esclude file non correlati in quel commit né altri commit. I nuovi piani di modifica del codice rifiutano le asserzioni riconosciute e autonome di log Git filtrate per percorso e non vuote; i controlli congelati più vecchi ricevono una guida di revisione senza cambiare il loro digest o la validazione in lettura.

Usa un verificatore di proprietà del progetto che controlli l’ascendenza della linea di base, richieda un intervallo non vuoto e ispezioni ogni percorso cambiato in ogni commit, senza filtri di percorso. Includi i file cancellati ed entrambi i lati delle rinomine, gestisci in modo esplicito i commit di merge e valida separatamente eventuali proprietà obbligatorie di ramo o di messaggio. Usa /goal revise per rafforzare un contratto esistente; non modificare i requisiti congelati.

Dimensione del piano e reinvio completo

Il piano reso, inclusi Markdown e JSON di assicurazione, deve stare entro 8,192 byte UTF-8. Punta sotto i 7,168 byte. Se l’invio supera il tetto, accorcia la prosa ripetuta e reinvia l’oggetto completo, inclusi kind e tutti i campi obbligatori. Conserva gli id e i controlli di accettazione; il runtime non tronca i requisiti e non alza il limite di lettura per accettare un piano troppo grande.

Ricevute di revisione delle animazioni della CLI locale

Il packages/ax-code/script/verify-cli-review-receipts.ts di proprietà del repository controlla gli artefatti round-* sotto la radice delle ricevute selezionata con --root. Ogni round ha bisogno di revision.txt, e ciascuno di grok, claude e codex ha bisogno di exit.txt con 0 e un verdetto finale in stdout.jsonl (eventi di testo Grok) oppure stdout.txt (Claude/Codex). Conserva i tentativi falliti fuori dalle directory dei round completati; non trasformare i fallimenti in ricevute con uscita zero.

dispositions.json contiene un array findings. Ogni voce nomina round, cli, id, status (fixed o rejected) e evidence non vuoto. Le voci fisse richiedono inoltre un oggetto regression con un percorso letterale del repository file sotto packages/ax-code/test/cli/tui/ e il Vitest esatto fullName. Disposizioni duplicate o verdetti multipli ambigui falliscono.

Il verificatore esegue quei file usando il Vitest installato, con il predefinito globale di tentativi impostato a zero (le opzioni del singolo test possono scavalcare quel predefinito), poi controlla che ogni asserzione citata sia passata esattamente una volta. Asserzioni mancanti, saltate, fallite o ambigue fanno fallire la verifica. Questo dimostra che quei test citati sono passati, non che le loro asserzioni coprano semanticamente il rilievo. Le disposizioni rifiutate restano giudizi registrati. Un round finale deve corrispondere all’HEAD corrente; i rilievi marcati come corretti richiedono una revisione più nuova e un round di revisione. Modifiche non committate di sorgente, test o configurazione del pacchetto centrale impediscono la verifica. Tieni la configurazione locale non correlata ax-code.json fuori dai commit.

Per questo repository, vitest run --dir test/cli/tui conserva le esclusioni della corsia normale mentre scandisce la directory della TUI. I runner di gruppo possono ancora selezionare file esatti con AX_TEST_FILES; la selezione di directory non disattiva le esclusioni.