Agent Architecture Review, Validation snapshot

Design for delegation rather than direct manipulation

Delegation is modeled as assigned work rather than manual execution: approve() gates the applicant handoff, then run_cohort_validate.run creates a persistent CohortValidationJob and _execute_with_job performs cloning, selecting, bundling, validating, and persistence. The user/operator supplies intent through application fields such as repo_url and approval state while the workflow executes the operational steps.

Ensure that background work remains perceptible

Background work is made perceptible through durable CohortValidationJob fields: status, queued_at, cloning_started_at, selecting_started_at, bundling_started_at, validating_started_at, terminal_at, failure_kind, retry_eligible, and abort_requested. _mirror_terminal_to_app also maps terminal job outcomes back to CohortApplication.onboarding_state so the applicant-level record remains inspectable after the worker exits.

Align feedback with the user’s level of attention

Feedback is calibrated by layer: routine progress is represented by concise states such as validation_queued, cloning, validating, completed, blocked, failed, and aborted, while elevated attention paths carry failure_kind, safe_display_message, retry_eligible, and onboarding_failure_reason. _summarize_validate_log deliberately compresses validator logs into high-level signals instead of exposing noisy internals by default.

Apply progressive disclosure to system agency

The code uses progressive disclosure: primary flow state is exposed through CohortApplication.onboarding_state and CohortValidationJob.status, while deeper evidence is stored in audit_object under source, selection, validate, and job. The detailed result is persisted in UserValidationRun.result_json, and _summarize_validate_log avoids dumping raw validation logs into the main status path.

Replace implied magic with clear mental models

The workflow gives a clear mental model through explicit state and boundary names: TERMINAL_STATUSES, FAILURE_KINDS, onboarding states such as firebase_user_failed and approval_email_failed, and operator messages in retry_failed_validation_job explaining non-terminal and non-retryable conditions. The validation bundle is also labeled with BOUNDARY_HEADER and ENVELOPE_ADVISORY, making the untrusted-code boundary explicit.

Expose meaningful operational state, not internal complexity

Operational state is expressed in actionable terms rather than raw implementation detail: queued, cloning, selecting, bundling, validating, completed, blocked, failed, and aborted. mark_blocked, mark_failed, and _mirror_terminal_to_app translate tool and dependency failures into failure_kind, safe_display_message, retry_eligible, and onboarding_failure_reason fields that support operator action.

Establish trust through inspectability

Inspectability is supported by a typed reproducibility envelope and audit trail. build_file_envelope records envelope_schema, boundary_contract, advisory, file metadata, and envelope_hash; _build_implementation_context records each selected file's path, byte_size, and sha256; audit_object stores commit_sha, selected_files, skipped_during_read, bundle_sha256, envelope_hash, validator latency, log_signals, and job_id in UserValidationRun.result_json.

Make hand-offs, approvals, and blockers explicit

Approvals, handoffs, and blockers are explicit in the main lifecycle. approve() requires an affirmative confirmation unless the operator passes --yes, reject() records a rejection_reason, external handoff failures are typed as firebase_user_failed, sign_in_link_failed, or approval_email_failed, and validation blockers are persisted through mark_blocked with failure_kind and safe_display_message. retry_failed_validation_job also refuses non-terminal or non-retryable jobs with a specific operator-facing explanation.

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

Delegated work is represented as a structured system rather than a message stream. CohortValidationJob links application_id, user_id, repo_url, status, step timestamps, retry_count, abort_requested, validation_run_local_id, commit_sha, bundle_sha256, and selection counts; the execution loop is separated from the persisted UserValidationRun result and audit metadata.