Question 1

Cos'è il Blueprint Readiness Score?

Accepted Answer

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 e' 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 puo' mai coesistere con un finding high_risk irrisolto. Il motivo per cui production_ready non richiede 100/100 e' che inseguire lo score perfetto e' 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 e' calcolato una volta sul server cosi' umani e agenti vedono lo stesso valore.

Question 2

Quale piano serve per chiamare architect.validate?

Accepted Answer

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.

Question 3

Come devo inviare il codice ad architect.validate? Posso riassumere o splittare?

Accepted Answer

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 e' troppo grande per il budget di tool-call del tuo client MCP, splitta in piu' chiamate architect.validate per FILE (non per cluster di principi). Splittare per cluster via focus_area e' un workaround che produce verdict frammentati: ogni chiamata vede solo ~3 principi, il path di certificazione non puo' 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 persistito 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 piu' semplice dall'interno di un agent loop.

Question 4

Come faccio a sapere se gli asset scaricati (CLAUDE.md, pack .claude/, config MCP) sono obsoleti?

Accepted Answer

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` e' 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, cosi' l'architect puo' 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 stabilita'; aggiorna a fine sprint per prendere i nuovi check.

Question 5

Come fa l'Architect Agent a impedire al mio agente di ripetere problemi già risolti?

Accepted Answer

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.

Question 6

Il mio codice viene salvato quando chiamo architect.validate?

Accepted Answer

I payload vengono processati transitoriamente in memoria dal provider LLM sottostante (OpenAI API, sotto policy di no-training-on-API-data) e scartati. Non addestriamo mai modelli su codice utente, payload di validation o diagrammi di architettura. Passa private_session=true sulla chiamata per saltare anche tutta la registrazione server-side dal nostro lato. Residenza dati UK/EU su Google Cloud Run europe-west2.

Question 7

Cosa restituisce l'Architect Agent per principio?

Accepted Answer

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.

Question 8

Il validator è deterministico? Posso riprodurre un run più tardi?

Accepted Answer

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.

Question 9

Come gestisce l'Architect Agent il prompt injection nel codice inviato?

Accepted Answer

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.

Question 10

Cosa succede quando OpenAI è rate-limited, lento, o offline?

Accepted Answer

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 5 minuti (300 secondi) ed è enforced al confine della chiamata al provider stesso, non solo al wrapper esterno. 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.

Question 11

L'Architect Agent è stato revisionato su sé stesso?

Accepted Answer

Sì, ripetutamente. La self-review più recente sul prior-run baseline injection ha totalizzato production_ready (B, 86 / 100, 5 su 6 principi applicabili allineati, nessun finding high_risk, voto non cappato) sull'endpoint prod live. La review pubblica è qui: https://aidesignblueprint.com/en/readiness-review/6d70eb0c-ec05-4ed4-b882-e30d8ca400de. Stesso tool MCP, stessa doctrine, stesso budget di 5 minuti che chiunque altro ottiene, stesso envelope di fingerprint che ogni chiamante riceve. Lo score è onesto, non rubber-stamped: l'agente ha trovato un principio ancora da stringere, ed è proprio cosa significa production_ready sotto la doctrine: le trust boundaries reggono anche se l'iterazione successiva potrebbe affinare la superficie dello stato operativo. Loop di iterazione precedenti sullo stesso codice hanno portato lo score da 89 / B a 100 / A in tre round con contesto del run precedente iniettato, facendo emergere bug reali round dopo round: classificazione strutturata mancante, canonicalizzazione del seed lossy, errori provider LLM non tipizzati, vulnerabilità di prompt injection nel contenuto baseline, AttributeError che scappava su campi nidificati non-dict truthy, e un primitivo di parse-boundary tipizzato che è atterrato nel round finale.

L'Architect Agent

Cosa ricevi indietro

Scoring per severity_class (production_blocker vs hardening_recommended)

Envelope di riproducibilità (best-effort, ma auditabile)

Memoria trend tra run