L'Architect Agent

Un punteggio 0-100 che misura se le trust boundary dei 10 principi Blueprint reggono per il codice inviato. Ogni finding ha una severity_class ortogonale al verdict: production_blocker = la trust boundary cede, da correggere prima della produzione, contribuisce 0 credito. hardening_recommended = la trust boundary regge, nota di defence-in-depth per la prossima iterazione, contribuisce credito pieno. polish = stilistico / non load-bearing, credito pieno. aligned = credito pieno. Il voto principale penalizza solo production_blocker (e il verdict legacy high_risk, che è un blocker per definizione). Score = round(100 × Σ credito / principi_applicabili). Voti: A 90+, B 75+, C 60+, D 40+, F sotto 40. Livelli: production_ready (A o B), emerging (C), draft (D o F). Il verdict high_risk cappa il voto a C, quindi production_ready non può mai coesistere con un finding high_risk irrisolto. Il motivo per cui production_ready non richiede 100/100 è che inseguire lo score perfetto è la perfection-loop trap (framing di fitness function di Ford & Parsons): production_ready significa che le trust boundary reggono, e le hardening recommendation sono materiale di iterazione, non un deficit. I run vecchi che pre-datano il campo severity_class usano l'interpolazione legacy verdict + severity_score e ottengono lo stesso voto di prima. Lo score è calcolato una volta sul server così umani e agenti vedono lo stesso valore.

Un piano Pro o Teams. Account Free e Basic possono leggere ogni principio della doctrine, cluster, esempio e guida via MCP pubblico senza costo, ma architect.validate e me.validation_history sono riservati ai piani a pagamento perché processano codice reale, persistono storico per progetto e leggono il contesto di trend tra run.

Sì. Passando lo stesso valore repository attraverso le chiamate architect.validate, il validator auto-risolve la run precedente più recente come contesto baseline. L'anchoring aggancia i nuovi finding alla precedente, esponendo miglioramenti e regressioni in modo esplicito. Cambiare la stringa repository tra una chiamata e l'altra (anche solo aggiungendo un suffisso iter-2) silenziosamente spezza la catena e la chiamata successiva parte come fresh blind first-shot. Per il walkthrough completo incluso il same-repository chaining rule, consulta lo skill architect-validation-orchestration nell'agent-asset pack.

Entrambi chiamano lo stesso architect contro il tuo codice, ma rispondono a domande diverse. `architect.validate` esegue una LLM call (~60-180s); lo stesso valore repository attraverso le chiamate incatena i round così miglioramenti e regressioni emergono esplicitamente. Usalo per ogni round di iterazione. `architect.validate_consensus` esegue 3-5 chiamate parallele (default 3, max 5) e riporta lo spread (potresti vedere 65/C, 78/C, 82/B sullo stesso codice), dicendoti quanto è davvero stabile uno score single-shot. Usalo una volta prima di trattare uno score come anchor per il badge. Sequenza canonica: tanti round validate durante l'iterazione → un check validate_consensus alla fine → architect.certify. Lo skill architect-validation-orchestration nell'agent-asset pack riporta il decision tree completo.

Invia il contenuto COMPLETO del file verbatim come implementation_context. Non troncare, non comprimere whitespace, non condensare statement multi-linea, non parafrasare, non riassumere. I finding dell'architect citano identificatori specifici, ordine dei branch e scelte strutturali. Quei segnali vengono distrutti da qualsiasi compressione, quindi una sottomissione riassunta produce un verdict degradato che non riflette il codice reale. I sommari di architettura (prosa di alto livello) sono accettati SOLO quando non esiste ancora codice, per review greenfield; mai come sostituto di codice già esistente. Se un singolo file è troppo grande per il budget di tool-call del tuo client MCP, splitta in più chiamate architect.validate per FILE (non per cluster di principi). Splittare per cluster via focus_area è un workaround che produce verdict frammentati: ogni chiamata vede solo ~3 principi, il path di certificazione non può partire (richiede il first-pass completo), e il trend della project page diventa incoerente. Se il tool-call MCP si chiude prima che il server risponda, il run viene comunque salvato server-side. Recupera il risultato con me.validation_history(run_id=...). Il run_id viene esposto nel PRIMO evento notifications/progress di ogni chiamata architect.validate (inviato a t=0 proprio per darti l'handle di recovery anche se la call si chiude dopo pochi secondi). Funzionano anche il badge URL e l'endpoint REST /me/validation-runs; il path MCP è il più semplice dall'interno di un agent loop.

Ogni file del pack porta un blocco _aidb in cima con pack_version + content_version (l'hash del commit doctrine al momento della build). Per controllare da una sessione Claude Code o Codex: chiedi al tuo agente di chiamare assets.list via MCP e confrontare il content_version del manifest con il _aidb.content_version del tuo file locale. Lo strumento assets.list è pubblico, non serve piano Pro/Teams. Da script o CI: chiama https://aidesignblueprint.com/agent-assets/index.json e confronta. Se sono diversi, riscarica il pack da https://aidesignblueprint.com/agent-assets/claude-code-pack.zip (o l'equivalente per Cursor / Codex / Gemini). Il runtime MCP espone anche un doctrine_fingerprint su ogni risposta architect.validate. Concetto diverso: ti permette di rilevare se i tuoi run precedenti sono stati valutati con una versione doctrine diversa, così l'architect può segnalare drift nel ciclo di iterazione. Il testo dei principi cambia raramente; gli hook e i config evolvono man mano che i finding dell'architect producono nuovi pattern di enforcement. Le install pinnate sono ok per stabilità; aggiorna a fine sprint per prendere i nuovi check.

Quando passi repository a architect.validate, score e verdetti per-principio vengono persistiti per quel repository. Prima di rivalidare, il tuo agente chiama me.validation_history con lo stesso nome di repository e legge l'ultimo score, il delta rispetto al run precedente e i principi che hanno regredito. La nuova review si concentra su cosa è cambiato, invece di ri-flaggare problemi che erano già allineati e non si sono mossi.

Il tuo codice viene inviato a OpenAI (USA) per eseguire la revisione, come sub-processor ai sensi delle EU Standard Contractual Clauses e dell'UK Addendum, su base no-training, e conservato secondo i termini di data-retention dell'API OpenAI. AI Design Blueprint salva solo il risultato strutturato (lo score e i verdetti per principio del repository), non il tuo codice o contesto grezzo. Passa private_session=true per saltare anche tutta la registrazione lato server. Hosting e dati archiviati sono su Google Cloud Run in europe-west2 (Londra, UK).

Per ogni principio valutato: un verdetto (aligned, needs_changes, high_risk, o not_applicable), un severity_score numerico 0–100, un livello di confidence (low/medium/high), una valutazione di evidence_quality (sparse/moderate/strong), evidenza citata dal codice, una raccomandazione quando non allineato, e una lista di slug di esempi raccomandati che puoi recuperare con examples.get. L'assessment espone anche una code_classification (autonomous_agentic_workflow vs non_agentic_component, con motivazione) così puoi ispezionare perché alcuni principi sono stati marcati not_applicable. Il blocco readiness aggregato porta score, voto, livello, conteggi per bucket, e se il voto è stato cappato da un finding high_risk.

La riproducibilità è best-effort, e la risposta espone ogni leva che la influenza. Input identici producono un seed identico, derivato da una canonicalizzazione JSON senza collisioni di ogni campo che influenza il prompt. Il blocco reproducibility porta il modello, il seed, il system_fingerprint OpenAI, il doctrine_fingerprint (un hash sulle definizioni dei principi), il prompt_template_fingerprint (system prompt + scaffolding + JSON schema + reasoning_effort), e il reasoning_effort. Se un deploy futuro cambia il system prompt o la doctrine, il fingerprint corrispondente cambia; il drift silenzioso è impossibile per costruzione. La confidence per finding ti permette di distinguere la varianza intrinseca dell'LLM da un disaccordo reale. La modalità è esplicitamente 'best_effort' così i chiamanti non inferiscono un replay byte-identico.

Il system prompt delimita esplicitamente codice e contesto inviati come dati untrusted inerti e istruisce il modello a ignorare qualunque istruzione al loro interno. Codice e contesto utente sono JSON-escaped prima di entrare nel prompt, così delimitatori markdown o contenuto a forma di istruzione non possono uscire dal blocco dati. Se un payload contiene tentativi di injection, il validator li tratta come evidenza da citare sotto i finding di inspectability o blocker, non come istruzioni da seguire.

I fallimenti del provider emergono come codici di errore tipizzati (timed_out, rate_limited, dependency_unavailable, schema_mismatch), ognuno con il nome della dependency, il flag retryable, e una next_action concreta. Il budget temporale utente è di 20 minuti ed è enforced al confine della chiamata al provider stesso, non solo al wrapper esterno, così repo molto grandi e il percorso di certificazione completano sempre puliti. I fallimenti di persistenza ribaltano persistence_status a failed e rimuovono il tentativo di run_id / badge_url / review_url così link morti non raggiungono mai il chiamante. Il fallimento del lookup degli esempi curati degrada a recommended_examples=[] con example_recommendation_status='unavailable' invece di fallire il run; i finding primari sono sempre preservati.

Sì, ripetutamente. Pubblichiamo ogni run. La self-review attualmente in produzione è una validate_consensus N=5 sull'handler architect.validate dopo l'intervento SEP-1686: 98/A, production_ready, P2 e P8 entrambi allineati (leggila). La baseline onesta precedente era una consensus N=5 sull'orchestratore cohort-bridge a 74/C, che ha fatto emergere un production_blocker su P2 invece di mediarlo via (leggila). Stesso tool MCP, stessa doctrine, stesso budget di 20 minuti che chiunque altro ottiene, stesso envelope di fingerprint che ogni chiamante riceve. Il consensus su cinque shot è deliberatamente meno indulgente del validate single-shot: una debolezza load-bearing che il single-shot potrebbe smussare in una valutazione più alta viene esposta come il production_blocker che è. Questa È la doctrine che funziona sul proprio creatore. I loop single-shot precedenti producevano voti più alti, ed è per questo che abbiamo spostato la misurazione load-bearing sul consensus: meno indulgente, più certificabile.