Vai al contenuto principaleVai al footer
Revisionato

Valutazione completata; in attesa di revisione delle prove.

Agent Architecture Review, Snapshot di validazione

Valutato il 12 maggio 2026 rispetto alla doctrine di AI Design Blueprint

In sviluppo

Stato: Alto rischio

74/100

Voto C

7 allineati2 blocker produzione1 hardening

Blueprint Readiness misura l'allineamento alla doctrine, non la runtime correctness. Un verdetto production-ready significa che l'architettura incarna i 10 principi; non esegue i tuoi test o i tuoi tipi. Affiancala alla tua test suite, non sostituirla.

Verdetti per principio

This is a real delegated validation workflow with durable job state, typed transitions, audit metadata, and improved rollback/failure handling. The remaining production blockers are at the trust-boundary edges: arbitrary repository text is still bundled into an instruction-bearing validation payload with only an in-band warning header, and the approval/email handoff can fail after approval is committed without a durable blocker state.

Storico iterazioni

2 run precedenti su questo artefatto. Ogni run_id apre la sua readiness review.

I punteggi possono salire o scendere tra le iterazioni: il ragionamento del validator non è strettamente deterministico, quindi lo stesso artefatto può ottenere punteggi diversi tra una run e l'altra. I delta per principio più sotto mostrano il cambiamento sostanziale.

QuandoScoreTierRun ID
12 maggio 2026 (questa run)74 / CIn sviluppo659a695a…
12 mag 202667 / CIn sviluppoe476247c…
12 mag 202630 / FBozza86b2c59d…

Findings per principio

10 principi valutati. Verdict, severity, evidenza e raccomandazione per ognuno. Evidenza e raccomandazione sono nella lingua originale della review, l'inglese.

P7

Richiede modificheBlocker di produzione65/100

Stabilire fiducia attraverso l'ispezionabilità

The audit trail is strong in several places (`commit_sha`, per-file `content_sha256`, `bundle_sha256`, selected/skipped files, latency, job transitions), but the key trust boundary for arbitrary public repository content is still in-band. `_build_implementation_context()` concatenates raw file contents into strings like `# === FILE: {path} ===\n{content}`, `wrap_bundle_with_boundary(raw_bundle)` prepends a warning header, and `ValidationRequest(code=bundle, ...)` sends that monolithic text to the validator. A repository can still contain instruction-shaped text inside comments/docstrings/strings; the boundary is a prompt convention rather than a typed artifact boundary enforced by `validatio…

Raccomandazione

Move the inertness boundary into the validation service as a typed file-envelope primitive: pass files as structured data such as `{path, byte_size, sha256, content}` with an envelope version/hash, render source only in a non-instruction-bearing section controlled by the service, and persist that envelope hash alongside the result. Do not rely on an in-band `BOUNDARY_HEADER` inside the same raw prompt text as the untrusted code.

P8

Richiede modificheBlocker di produzione55/100

Rendere espliciti i passaggi, le approvazioni e i blocchi

The validation job handoff is much better: validate and persistence exceptions now call `db.rollback()` before `mark_failed()`, the outer handler rolls back and refreshes `job`, and terminal blockers use typed `failure_kind` values. However, the approval/onboarding handoff can still strand a real applicant outside that durable job model: `approve()` commits `app.approved_at` and `app.user_id`, then `generate_sign_in_link_for_email()` catches `Exception` and simply `return 3` without persisting an application/job blocker; `send_cohort_approval_email()` is not wrapped in a durable failure transition either. Delta: the prior rollback subfinding is improved, but a production handoff gap remains…

Raccomandazione

Move approval-side external handoffs into a durable service-owned state machine, or extend `CohortApplication`/a dedicated onboarding job with typed states such as `approved`, `sign_in_link_failed`, `approval_email_failed`, and `validation_queued`. Before returning from sign-in-link or email failures, persist a safe blocker message and retry eligibility so the operator is not left with only an exit code and an already-approved applicant.

P10

Richiede modificheHardening consigliato35/100

Ottimizzare per la guida, non solo per l'inizio

The code has a real steering primitive in `CohortValidationJob.abort_requested`, `mark_step_started()` checks it before advancing, the validate step now calls `db.refresh(job)` before checking abort, and `run()` calculates a durable `retry_count` from prior jobs. That improves the prior P10 refresh/retry-count gap. The submitted code still does not expose a service-owned steering surface that sets `abort_requested`, retries a failed job, or marks an interrupted job; comments say a separate surface flips the flag, but no `request_abort`/`retry_failed_job` API or CLI is present in the reviewed code. This is a remaining steering gap, though the underlying DB flag/check primitive means the core…

Raccomandazione

Add a small service-owned steering command/API outside the execution loop for `request_abort(job_id)`, `retry_failed_job(job_id)`, and `mark_interrupted(job_id)`, and have the orchestrator refresh before each external or costly step. Keep it as a thin state-transition primitive rather than adding a large orchestration wrapper.

P1

Allineato

Progettare per la delega piuttosto che per la manipolazione diretta

The user/operator delegates the scan at the application level: `approve()` records approval, then `run_cohort_validate(app.id)` creates a `CohortValidationJob`; `_execute_with_job()` owns clone, language detection, file selection, bundling, validation, persistence, and terminal state. Scope and constraints are represented through `repo_url`, `namespace = f"cohort/{application_id}/{owner}/{repo_name}"`, `ValidationContext(task=..., repository=..., files=...)`, and the selected file list rather than requiring the operator to execute each step manually.

P2

Allineato

Assicurarsi che il lavoro in background rimanga percepibile

Background work is made perceptible through a persistent `CohortValidationJob` row created before work begins in `create_job()`, with durable statuses and timestamps for `queued`, `cloning`, `selecting`, `bundling`, `validating`, and terminal states. `mark_step_started()`, `mark_completed()`, `mark_blocked()`, `mark_failed()`, and `mark_aborted()` commit state transitions, and the approval CLI prints the latest terminal job status/failure fields after validation returns.

P3

Allineato

Allineare il feedback al livello di attenzione dell'utente

The code separates low-noise routine progress from attention-demanding conditions: normal progress is persisted as status/timestamps, while blocked/failed states carry `failure_kind`, `safe_display_message`, and `retry_eligible`. `approve()` prints terminal status and failure details only after the run, while deeper validation telemetry is summarized via `_summarize_validate_log()` inside the audit object rather than streamed noisily to the operator.

P4

Allineato

Applicare la divulgazione progressiva all'agenzia del sistema

Primary state is simple (`status`, `failure_kind`, `safe_display_message`, `retry_eligible`), while detailed inspection is available in the persisted `audit_object` containing `source`, `selection`, `validate`, and `job` sections. The code records file hashes, selected paths, skipped reads, latency, usage presence, and `_collect_job_transitions(job)` without forcing those internals into the main terminal message.

P5

Allineato

Sostituire la magia implicita con modelli mentali chiari

The workflow exposes a clear mental model through explicit state-machine comments in `cohort_validation_job.py` and `CohortValidationJob`, bounded repository support in `_looks_like_public_github_https()`, language detection in `_detect_language()`, selector rejection via `SelectionRejected`, and a visible untrusted-input boundary constant `BOUNDARY_HEADER`. Failure messages distinguish unsupported language, invalid repository URL, clone timeout/failure, repository size, read failure, validator failure, persistence failure, and abort.

P6

Allineato

Esporre uno stato operativo significativo, non la complessità interna

Operational state is represented in user/action-relevant terms: `TERMINAL_STATUSES`, `FAILURE_KINDS`, `mark_blocked()`, `mark_failed()`, and `safe_display_message` avoid exposing raw stack traces as the main status surface. The current code also addresses the prior P6 gap: `FetchError.kind == "invalid_url"` is explicitly mapped to `"invalid_repo_url"` in `kind_map`, and an all-read-failed bundle now blocks with `failure_kind="read_failed"` instead of validating an empty/materially incomplete bundle.

P9

Allineato

Rappresentare il lavoro delegato come un sistema, non solo come una conversazione

Delegated work is represented as a structured system rather than a conversation: `CohortValidationJob` stores lifecycle state, timestamps, abort/retry fields, terminal failure fields, validation-run linkage, commit/bundle hashes, and selected/skipped counts. `_execute_with_job()` follows explicit steps, while the persisted `audit_object` captures source, selection, validation, and job-transition substructures.

Aggiungi al tuo README

Due varianti embeddabili: una piccola e una a card più ricca.

Score card (consigliata)

Blueprint Readiness Score card
[![Blueprint Readiness Score card](https://aidesignblueprint.com/api/badge/run/659a695a-2bf6-4b28-a52f-b6098c20ee0b/card.svg)](https://aidesignblueprint.com/en/readiness-review/659a695a-2bf6-4b28-a52f-b6098c20ee0b)

Badge piatto

Blueprint Readiness Score badge
[![Blueprint Readiness Score](https://aidesignblueprint.com/api/badge/run/659a695a-2bf6-4b28-a52f-b6098c20ee0b.svg)](https://aidesignblueprint.com/en/readiness-review/659a695a-2bf6-4b28-a52f-b6098c20ee0b)

Inizia qui, parte 3 di 3

Guarda come nascono questa pagina e il suo badge, dal primo run al README.

Dettagli baseline e iterazione
Baseline: usedDoctrine: same doctrineRace: checked clear

Delta iterazione

3 chiusi in questa iterazione0 riaperti0 finding ad alto rischio ancora aperti

Miglioramenti (3)

P6Esporre uno stato operativo significativo, non la complessità internaneeds_changesaligned
P8Rendere espliciti i passaggi, le approvazioni e i blocchineeds_changesneeds_changes
P10Ottimizzare per la guida, non solo per l'inizioneeds_changesneeds_changes
Rubric: 2026-05-04Voto limitato da 0 finding ad alto rischio

ID del run: 659a695a-2bf6-4b28-a52f-b6098c20ee0b

La review di questo artefatto rispetto alla doctrine al momento del run, non un audit di sicurezza né una garanzia sul runtime.

Cosa copre una review e come vengono trattati i dati

Run by agents. Governed by humans. Validated by the AI Design Blueprint.