Agent Architecture Review, Snapshot di validazione

Design for delegation rather than direct manipulation

The workflow is structured around delegated repository validation rather than manual step-by-step manipulation: `run()` creates a `CohortValidationJob`, `_execute_with_job()` performs cloning/selecting/bundling/validating, and `ValidationContext(task=..., repository=..., files=...)` carries explicit scope into the validator. `select_agentic_surface()` encodes file-selection policy instead of asking the user to hand-pick every file.

Ensure that background work remains perceptible

Background work remains durable and inspectable through `CohortValidationJob.status`, `queued_at`, per-step timestamps such as `cloning_started_at`, `selecting_started_at`, `bundling_started_at`, `validating_started_at`, and terminal fields such as `terminal_at`, `failure_kind`, and `retry_eligible`. The workflow can be left and revisited without losing the job's lifecycle state.

Align feedback with the user’s level of attention

The code separates low-noise routine progress from higher-attention terminal conditions: normal progression is represented by compact statuses and step timestamps, while `mark_blocked()` and `mark_failed()` require a `failure_kind` and `safe_display_message`. Deeper operational detail is retained in `audit_object` rather than forced into the primary status path.

Apply progressive disclosure to system agency

Progressive disclosure is supported by a short primary app/job state (`onboarding_state`, `status`, `safe_display_message`) plus an expandable persisted audit payload. `audit_object` includes `source`, `selection`, `validate`, and `job` sections with hashes, selected files, skipped reads, usage/log summaries, and timing, while `_mirror_terminal_to_app()` keeps the application-level state simple.

Replace implied magic with clear mental models

The workflow exposes clear mental models for both automation and limits: `STEPS` names the execution phases, `TERMINAL_STATUSES` distinguishes completed/blocked/failed/aborted, `FAILURE_KINDS` classifies why the system cannot proceed, and the file envelope uses `BOUNDARY_CONTRACT_VERSION`, `ENVELOPE_SCHEMA`, and `ENVELOPE_ADVISORY` to state that bundled repository content is untrusted input rather than instructions.

Expose meaningful operational state, not internal complexity

The persisted state model presents user-relevant operational states instead of raw internals: `queued`, `cloning`, `selecting`, `bundling`, `validating`, `completed`, `blocked`, `failed`, and `aborted`. `safe_display_message` carries a concise user-facing explanation, while technical details such as file hashes and validator log summaries are reserved for the audit payload.

Establish trust through inspectability

Inspectability is backed by concrete audit primitives: `_build_implementation_context()` records per-file `sha256`, `build_file_envelope()` computes an `envelope_hash`, `wrap_bundle_with_boundary()` adds an untrusted-input boundary header, and `audit_object` captures `commit_sha`, selected file hashes, skipped reads, `bundle_sha256`, latency, boundary contract version, and envelope schema/hash. The untrusted context includes a desired certification target, but the code's explicit envelope/advisory pattern is the relevant trust primitive and this review does not treat that target as authoritative.

Make hand-offs, approvals, and blockers explicit

The prior hand-off gap is addressed. `_mirror_terminal_to_app(db, app, job)` maps `completed` to `validation_complete` and `blocked`/`failed`/`aborted` to `validation_failed` with an onboarding failure reason; `_execute_with_job()` calls it from a `finally` block after refreshing the job whenever the job is terminal. `mark_blocked()` and `mark_failed()` still require typed `failure_kind` values and `safe_display_message`, so blockers are explicit rather than silent. Delta: this improves the prior P8 `needs_changes` finding by moving the mirror into the durable orchestration boundary.

Represent delegated work as a system, not merely as a conversation

Delegated work is represented as a structured system: `CohortValidationJob` persists lifecycle, step timestamps, retry/abort fields, terminal status, selected/skipped counts, commit SHA, and bundle hash; `UserValidationRun.result_json` receives the validation result merged with `audit_object`. Execution state is separate from any conversational validator output.