Agent Architecture Review, Validation snapshot

Design for delegation rather than direct manipulation

The workflow is designed around delegated work rather than manual execution: approve() delegates repository validation after an application approval, create_job() persists application_id/user_id/repo_url, and _execute_with_job() carries out cloning → selecting → bundling → validating. Scope and constraints are explicit through repo_url, ValidationRequest(context=ValidationContext(...)), MAX_FILES, MAX_BUNDLE_BYTES, MAX_FILE_BYTES, and the selected file list.

Ensure that background work remains perceptible

Background work is made perceptible through CohortValidationJob.status plus queued_at, cloning_started_at, selecting_started_at, bundling_started_at, validating_started_at, terminal_at, failure_kind, retry_eligible, and abort_requested. mark_step_started(), mark_completed(), mark_blocked(), mark_failed(), and mark_aborted() commit durable transitions so the workflow can be inspected after the initiating CLI/process moves on.

Align feedback with the user’s level of attention

Feedback is calibrated by audience and attention level: CohortApplication.onboarding_state gives a coarse applicant/founder-facing state, CohortValidationJob.failure_kind and safe_display_message expose actionable blocker/failure information, and audit_object plus _summarize_validate_log() preserve deeper diagnostic detail without forcing it into the primary status path.

Apply progressive disclosure to system agency

The code separates primary status from inspection detail. Primary fields include onboarding_state, job.status, safe_display_message, selected_count, skipped_count, commit_sha, and bundle_sha256; detailed evidence is available in audit_object with source, selection, validate, and job sections, and in the typed file envelope built by build_file_envelope().

Replace implied magic with clear mental models

The workflow provides clear mental models through explicit state-machine comments, STEPS, TERMINAL_STATUSES, FAILURE_KINDS, onboarding_state values, BOUNDARY_CONTRACT_VERSION, ENVELOPE_SCHEMA, BOUNDARY_HEADER, and ENVELOPE_ADVISORY. The code distinguishes approval, validation queueing, blocked validation, failed validation, and completed validation rather than presenting the validator as opaque magic.

Expose meaningful operational state, not internal complexity

Operational state is expressed in user-relevant terms such as queued, cloning, selecting, bundling, validating, completed, blocked, failed, aborted, validation_queued, validation_complete, and validation_failed. Low-level details like log_context are summarized by _summarize_validate_log(), while safe_display_message gives a cleaner operator-facing explanation.

Establish trust through inspectability

Inspectability is supported by load-bearing primitives: RepoSnapshot.commit_sha captures git rev-parse HEAD, _build_implementation_context() records per-file sha256 values, build_file_envelope() creates an envelope_hash over canonical JSON, and audit_object records source, selected files, skipped reads, bundle_sha256, envelope_schema, envelope_hash, latency, and job transitions. The selector is now deterministic and fixes the prior priority inversion: SORT_PRIORITY includes coordinator/planner/router/evaluator and unmatched positive-signal files default to priority 12, ahead of fallback priority 50. Delta: this improves the prior P7 needs_changes finding by addressing the cited selector bug.

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

Delegated work is represented as a structured system, not a message stream. CohortValidationJob models the job lifecycle, cohort_validation_job.py defines explicit state transitions, _collect_job_transitions() records the timeline, and audit_object preserves source, selection, validation, and job substructures for later review.