Case study · Integrità ricorsiva · Reference honesty
Reference agent A2A: cosa trova il validator nel nostro esempio
Il validator che valuta gli applicanti della cohort è stato puntato sul Blueprint Governed Agent, il nostro esempio reference A2A pubblicato su a2aproject/a2a-samples. Il verdetto è 58/D, draft, con quattro blocker production. Il case study nomina esattamente quali blocker sono scope deliberato (l'esempio è una dimostrazione di protocollo, non infrastruttura production) e quali erano abbastanza piccoli da chiudere in una PR companion.
Fatti chiave
Verdetto
58/D · draft
Blocker production
4 dei 10 principi
Allineati
5 dei 10 principi
Metodologia
Scan single-pass · run-id pinned
Cosa è stato scansionato
Submission: `a2a/agent_executor.py` (l'executor A2A `GovernedFileAgent`) più `server.py` (il proxy stdio verso il Blueprint MCP remoto). Entrambi sono file pubblici in `aidesignblueprint/integrations`, il repo canonico di integrazioni della doctrine. La submission ha incluso gli stessi file nella stessa forma che qualsiasi lettore clonerebbe dal repo pubblico.
L'esempio è pubblicato come reference di protocollo. Il suo README, il README della PR #536 di `a2aproject/a2a-samples`, e il framing del case study qui dicono tutti la stessa cosa: questo codice dimostra come mappare i principi Blueprint sulle primitive del protocollo A2A, non come spedire un agente production di file-deletion. Lo scan applica la doctrine dei 10 principi al codice al valore facciale, e il case study nomina quali finding riflettono quello scope intenzionale.
La decisione, detta chiaramente
Quattro dei cinque finding non allineati sono architetturali (P1 envelope di delega, P5 magia implicita, P7 catena di audit, P8 approvazione tipizzata). Uno era abbastanza piccolo da chiudere in una PR companion (P4 progressive disclosure, limitato al proxy stdio). Il rapporto architetturale-vs-triviale è 4:1, decisamente sopra la soglia del 60% dove la mossa giusta è FRAME, non FIX.
Ricostruire l'esempio per fargli prendere 100/A richiederebbe aggiungere una chiamata reale al filesystem, una primitiva di approvazione strutturata, un ledger di audit durevole, e un envelope di azione tipizzato, tutti elementi che trasformerebbero una reference di protocollo in infrastruttura production e cancellerebbero la cosa che l'esempio effettivamente dimostra. I quattro blocker architetturali restano nel codice come scope deliberato. Il fix triviale P4 viaggia in una piccola PR companion sul repo integrations.
Tre case study, tre faccette
Ognuno dei tre case study di integrità ricorsiva su questo sito esercita la doctrine contro una superficie di codice diversa, così il lettore può triangolare cosa fa bene il validator e dove finisce il suo scope.
Come leggere ogni finding
Ogni blocker qui sotto è annotato col pattern AUX, una forma a tre righe che usiamo per rendere i finding della doctrine azionabili: cosa richiede il principio, dove questo codice è insufficiente e perché, e come apparirebbe la versione doctrine-compliant. Questo è il primo case study a pubblicare quelle annotazioni esplicitamente, quindi il vocabolario atterra qui.
Verdetto
58/D, draft. Quattro blocker production su P1, P5, P7, P8. Una raccomandazione di hardening su P4. Cinque principi allineati (P2, P3, P6, P9, P10). La code-classification del validator etichetta la submission come `autonomous_agentic_workflow` perché l'executor A2A implementa lifecycle di task delegato, pause/resume via `TASK_STATE_INPUT_REQUIRED`, eventi di progresso, cancellation e completion terminale, anche se `server.py` stesso è solo un bridge stdio sincrono.
Il set di principi allineati è significativo. Il validator riconosce all'executor di emettere stato di task genuinamente percepibile (P2), calibrare il feedback all'attenzione (P3), esporre stato operativo significativo invece di complessità interna (P6), rappresentare il lavoro come sistema di task piuttosto che come trascritto di chat (P9), e supportare lo steering tramite cancel e abort (P10). Il set non allineato nomina i gap che dovrebbero chiudersi perché il codice possa leggersi come production-governed, e quei gap sono esattamente dove l'esempio smette di essere una dimostrazione di protocollo.
P5, il finding load-bearing
La prosa del validator su P5 è la causa radice architetturale. L'executor riporta successo di validazione e deletion senza fare nessuna delle due, che significa che tre degli altri finding (P1 envelope, P7 catena di audit, P8 approvazione tipizzata) non possono atterrare puliti finché l'esempio non diventa reale o si etichetta come simulazione. Il testo è del validator, non dell'autore del case study.
NEEDS_CHANGES70/100
Il modello mentale è materialmente fuorviante. Il testo di approvazione dice `This will permanently delete the requested file`, il messaggio di progresso dice `Validating target path...`, e il risultato dice `File deleted successfully.`, ma il codice non contiene un path di destinazione parsato, nessuna primitiva di validazione, e nessuna chiamata di eliminazione. Utenti o implementatori potrebbero credere che l'esempio dimostri una deletion governata completa quando in realtà sta solo emettendo testo di stato.
Blocker production, con annotazioni AUX
I quattro blocker architetturali. Ognuno è annotato con la prosa di evidence verbatim del validator più un pattern AUX a tre righe: cosa richiede il principio, dove questo codice è insufficiente e perché, e come apparirebbe la forma doctrine-compliant. Ordinati per severità.
P8 · Hand-offs, approvals, and blockersmake-hand-offs-approvals-and-blockers-explicit
NEEDS_CHANGESPRODUCTION_BLOCKER80/100
L'handoff è esplicito a livello di protocollo perché la prima chiamata emette `TASK_STATE_INPUT_REQUIRED` con un'istruzione concreta di rispondere `confirm`, e il path di abort emette `TASK_STATE_CANCELED`. Tuttavia, il gate di approvazione non è sicuro: `if "confirm" not in user_input.lower()` significa che frasi come `do not confirm` o `confirm nothing` proseguono, e il messaggio di approvazione non è legato a uno specifico file o istanza di operazione.
Richiede
Un'approvazione deve essere esatta, tipizzata e legata all'operazione che autorizza.
Insufficiente
Il controllo per sottostringa `"confirm" in user_input.lower()` accetta frasi ambigue, e il prompt non nomina il path di destinazione, quindi il task ripreso può eseguire un'operazione diversa da quella che l'utente pensava di aver approvato.
Pattern AUX
Sostituire il match per sottostringa con una primitiva di approvazione esatta e tipizzata come `DELETE <target_path> <approval_nonce>`, rifiutare il resto, e mostrare lo stesso envelope verbatim nel prompt del blocker che l'utente vede.
P5 · Replace implied magic with clear mental modelsreplace-implied-magic-with-clear-mental-models
NEEDS_CHANGESPRODUCTION_BLOCKER70/100
Il modello mentale è materialmente fuorviante. Il testo di approvazione dice `This will permanently delete the requested file`, il messaggio di progresso dice `Validating target path...`, e il risultato dice `File deleted successfully.`, ma il codice non contiene un path di destinazione parsato, nessuna primitiva di validazione, e nessuna chiamata di eliminazione. Utenti o implementatori potrebbero credere che l'esempio dimostri una deletion governata completa quando in realtà sta solo emettendo testo di stato.
Richiede
Se il codice dice di aver fatto qualcosa, deve aver fatto quella cosa.
Insufficiente
Non c'è una variabile di path, nessuna chiamata al filesystem, nessuna invocazione di tool remoto, nessuna funzione di validazione, e nessun error handling, eppure l'evento di risultato riporta `File deleted successfully.` indipendentemente da qualsiasi operazione reale.
Pattern AUX
O etichettare il sample come simulazione non distruttiva nel testo stesso del risultato, o collegare la deletion a una primitiva reale il cui successo o fallimento guida l'evento di completion così l'artefatto riporta cosa è effettivamente accaduto.
P7 · Trust through inspectabilityestablish-trust-through-inspectability
NEEDS_CHANGESPRODUCTION_BLOCKER65/100
Il workflow non fornisce una traccia di produzione ispezionabile per un'azione sensibile all'accountability. `TaskArtifactUpdateEvent` contiene solo `new_text_artifact(name="result", text="File deleted successfully.")`; non c'è alcun record di audit su quale file è stato richiesto, quale validazione è avvenuta, chi ha confermato, quale conferma esatta è stata accettata, o se l'operazione finale ha effettivamente cambiato qualcosa. Il proxy MCP allo stesso modo inoltra `_call_tool()` a `client.call_tool(name, arguments or {})` e ritorna solo `result.content`, senza correlazione di chiamata o envelope di audit in questo codice.
Richiede
Ogni azione sensibile all'accountability deve lasciare un record durevole e ispezionabile fuori dal loop di esecuzione.
Insufficiente
L'unico artefatto testuale `result` non porta correlazione `task_id`, nessun testo di approvazione, nessuna evidence di validazione, nessuna identità dell'executor, e nessun esito dell'operazione, quindi non c'è modo di ricostruire cosa è successo dopo la chiusura del task.
Pattern AUX
Spostare l'auditabilità in un ledger di task durevole o artefatto strutturato che registri task_id, envelope d'azione immutabile, decisione di approvazione, evidence di validazione, risultato di esecuzione, timestamp e identità dell'attore, separatamente dal testo di stato user-facing.
P1 · Design for delegationdesign-for-delegation-rather-than-direct-manipulation
NEEDS_CHANGESPRODUCTION_BLOCKER50/100
L'executor è strutturato intorno al lavoro delegato piuttosto che a passi manuali: `GovernedFileAgent.execute()` crea o riprende un task A2A, emette `TASK_STATE_WORKING`, si ferma per l'approvazione, riprende, e completa con un artefatto. Tuttavia, l'autorità delegata è ancora rappresentata solo come testo libero da `context.get_user_input()` / `context.message`; non c'è un file di destinazione strutturato, envelope di vincoli, o scope di autorità esplicito collegato al task prima di chiedere all'utente di confermare la deletion.
Richiede
L'autorità delegata deve essere un envelope tipizzato e immutabile, non testo libero.
Insufficiente
L'executor estrae solo `user_input = context.get_user_input().strip()` e non lega mai la richiesta a un target_path concreto, action_kind, o set di vincoli, quindi il prompt di approvazione sta parlando di un file che il task non porta effettivamente.
Pattern AUX
Legare il lavoro delegato a un envelope tipizzato (`{action, target_path, constraints, requested_by, task_id}`) prima di richiedere l'approvazione, e mostrare lo stesso envelope verbatim nel blocker così l'utente autorizza esattamente ciò che il task eseguirà.
Una raccomandazione di hardening viaggia con un fix companion
P4 (progressive disclosure) era l'unico finding abbastanza piccolo da indirizzare senza cambiare lo scope del demo, quindi è mostrato qui come raccomandazione di hardening invece che come blocker architetturale che richieda un'annotazione AUX. La PR companion su aidesignblueprint/integrations ripristina `outputSchema` e `structuredContent` end-to-end sul proxy stdio `server.py`, così la validazione di MCP Inspector e gli agent downstream possono affidarsi alla superficie tipizzata che il Blueprint MCP upstream già pubblicizza su tutti i 24 tool.
P4 · Progressive disclosure of system agencyapply-progressive-disclosure-to-system-agency
NEEDS_CHANGESHARDENING_RECOMMENDED35/100
I messaggi di stato di default sono concisi, ma non c'è un layer di ispezione più profondo quando confidenza o intervento contano. Il workflow emette solo messaggi generici come `Validating target path...`, `Executing file deletion...`, e un artefatto con `File deleted successfully.`; non espone il path di destinazione, risultato di validazione, record di approvazione, o dettagli dell'azione come dettaglio ispezionabile del task.
Perché questo conta operativamente
Gli applicanti della cohort vedranno questo esempio prima di quasi qualsiasi altra cosa sul sito. Se il validator è onesto sul suo stesso codice reference, allora il validator può essere onesto sul codice degli applicanti. Se il validator nasconde i gap nella sua stessa reference, allora i verdetti del validator altrove si leggono come marketing piuttosto che diagnostica. Pubblicare il verdetto 58/D contro il nostro esempio è il modo più economico per dimostrare in quale modalità è il validator.
I quattro blocker architetturali nominano ciascuno un principio Blueprint specifico che il codice reference può dimostrare nel mapping del protocollo, ma non può soddisfare a livello production senza smettere di essere codice reference. P1 vuole un envelope tipizzato, P5 vuole esecuzione reale, P7 vuole un ledger di audit durevole, P8 vuole una primitiva di approvazione esatta. Una dimostrazione di protocollo non può portarsi tutti e quattro senza diventare un agente completo di file-management, che non è ciò per cui esiste l'esempio.
Nominare i gap esplicitamente trasforma l'esempio da silenziosa over-claim a artefatto didattico. Un practitioner che legge il codice A2A ora lo legge accanto a un verdetto pubblico che nomina i meccanismi esatti che dovrebbero atterrare prima che il pattern raggiunga production. L'esempio dimostra un protocollo. Il case study dimostra la doctrine. Entrambi sono utili, e il validator fa il lavoro di distinguerli.
Cosa stabilisce questo case study
Tre layer di integrità ricorsiva hanno ora ricevute pubbliche: validator sul suo stesso bridge, validator sul substrato sopra cui la doctrine gira, e validator su una reference di protocollo pubblicata. Stesso rubric dei 10 principi, stesso engagement mechanism-specific, tre superfici di codice diverse, tre verdetti diversi, tre framing diversi. Le ricevute sono l'artefatto.
Ricevute
Rigiocabile dal run_id: /readiness-review/ca187db7…. Il ragionamento completo per principio, le severità, le raccomandazioni e il razionale di code-classification sono persistiti server-side. Il fingerprint della doctrine dei 10 principi è lo stesso fingerprint che ha valutato ogni precedente run layer-1 e layer-2 su questo sito.
Questo scan riflette il repo integrations al run-time del 2026-05-14. Il fix companion P4 nella PR aidesignblueprint/integrations#1 era aperta al momento dello scan e atterra separatamente; i blocker architetturali (P1, P5, P7, P8) sono scope deliberato della reference di protocollo e non ci si aspetta che chiudano in questa superficie. Eventuali rescan futuri, se condotti, verrebbero pubblicati come case study separati con run_id propri.
