Agent Architecture Review, Validation snapshot

Design for delegation rather than direct manipulation

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.

Ensure that background work remains perceptible

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.

Align feedback with the user’s level of attention

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.

Apply progressive disclosure to system agency

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.

Replace implied magic with clear mental models

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.

Expose meaningful operational state, not internal complexity

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.

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

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.