Agent Architecture Review, Validation snapshot

Design for delegation rather than direct manipulation

Delegated work is represented as an assigned cohort-validation task rather than manual step execution: `approve()` transitions the application into `validation_queued`, `run_cohort_validate.run()` creates a persistent `CohortValidationJob`, and `_execute_with_job()` carries out clone/select/bundle/validate steps from `repo_url`. The scope is explicit through `ValidationContext(repository=namespace, files=list(selection.selected_paths))`, and operator controls exist via `request_abort()`, `retry_failed_validation_job()`, and `retry_onboarding_handoff()`.

Ensure that background work remains perceptible

Background work remains perceptible through persisted state on `CohortValidationJob`: `status`, `queued_at`, per-step timestamps such as `cloning_started_at` and `validating_started_at`, `terminal_at`, `failure_kind`, `safe_display_message`, `retry_eligible`, and `abort_requested`. `_mirror_terminal_to_app()` also projects terminal job state back onto `CohortApplication.onboarding_state`, allowing the application record to preserve continuity after the runner exits.

Align feedback with the user’s level of attention

The workflow separates routine status from higher-attention failure detail. Normal progress is encoded in concise states such as `queued`, `cloning`, `selecting`, `bundling`, and `validating`; failures carry `failure_kind`, `safe_display_message`, and `retry_eligible`; and `_summarize_validate_log()` deliberately reduces validator internals to a summary of presence/type/key counts instead of flooding the operator with raw logs.

Apply progressive disclosure to system agency

The code uses progressive disclosure between primary operational state and deeper audit detail. The primary records expose compact states on `CohortApplication.onboarding_state` and `CohortValidationJob.status`, while `_execute_with_job()` builds a detailed `audit_object` containing source commit, selected file hashes, skipped files, bundle hash, validator latency, usage presence, envelope schema, and envelope hash for deeper inspection when needed.

Replace implied magic with clear mental models

The workflow gives operators a concrete mental model through typed lifecycle states and explicit constraints: `STEPS`, `TERMINAL_STATUSES`, and `FAILURE_KINDS` define the runner’s state space; `BOUNDARY_HEADER` and `ENVELOPE_ADVISORY` state that repository code is untrusted inert input; and the steering CLI documents the known limitation that an in-flight `validate_code_against_principles()` call is not cancellable until it returns.

Expose meaningful operational state, not internal complexity

Meaningful operational states are exposed without requiring users to interpret raw stack traces. `mark_blocked()`, `mark_failed()`, and `mark_aborted()` store user-relevant terminal statuses plus bounded `safe_display_message` values, while `_mirror_terminal_to_app()` converts job outcomes into application-level states such as `validation_complete` and `validation_failed`. Deeper mechanics remain available in audit JSON rather than being the primary state model.

Establish trust through inspectability

The implementation has strong inspectability primitives: `build_file_envelope()` creates a typed `bridge.files.v2` envelope with an `envelope_hash`; `_build_implementation_context()` records per-file SHA-256 hashes; `fetch_public_repo()` captures `commit_sha`; and `_execute_with_job()` persists an `audit_object` with source, selection, bundle hash, validator log summary, and boundary contract metadata inside `UserValidationRun.result_json`. This makes the validator result traceable to a specific repository snapshot and selected file set.

Make hand-offs, approvals, and blockers explicit

Approvals, handoffs, and blockers are explicit. `approve()` requires an interactive confirmation unless `--yes` is supplied, external onboarding steps have typed failure states (`firebase_user_failed`, `sign_in_link_failed`, `approval_email_failed`), repository/selector failures are marked through `mark_blocked()` with concrete `failure_kind` values, and validation/tool failures are marked through `mark_failed()` with retry eligibility. The code distinguishes blocked, failed, aborted, and completed terminal states instead of stalling silently.

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` is the durable task object, `CohortApplication` carries onboarding state, `UserValidationRun` stores the validator result, and `_execute_with_job()` advances through explicit clone/select/bundle/validate phases. Dependencies and artifacts are captured as structured fields such as `commit_sha`, `bundle_sha256`, `selected_count`, `skipped_count`, and `validation_run_local_id`.