Agent Architecture Review, Validation snapshot

Make hand-offs, approvals, and blockers explicit

Some blockers are explicit now, including malformed owner/repo parsing routed to `_mark_no_agentic_surface(reason="invalid_repo_url")`, `SelectionRejected`, and typed `FetchError.kind`. But important handoff failures still stall silently: `run()` only catches `FetchError`, so validation, JSON serialization, DB flush/commit, and audit construction exceptions propagate; then `approve()` catches all exceptions around `run_cohort_validate(app.id)` and silently `pass`es. After Firebase user creation and email delivery, that leaves no durable blocker reason or required action.

Ensure that background work remains perceptible

Long-running validation is perceptible only through transient CLI `print()` calls and final DB fields. `approve()` sends the approval email and then runs `run_cohort_validate()` inline, while `run()` creates no durable `queued`/`active` run row before clone/selection/LLM validation; `UserValidationRun` is only added after the validator succeeds, and graceful failures only overload `app.rejection_reason`. If the process crashes or the LLM call hangs after the email is sent, the applicant can be left in a silent pending state.

Establish trust through inspectability

The audit envelope is a substantial improvement: `audit_object` records `schema_version`, `captured_at`, source `repo_url`/`commit_sha`, selected file hashes, skipped reads, `bundle_sha256`, validator latency, and shape-only log signals. However, the bridge still constructs the validator payload by concatenating raw untrusted repo content in `_build_implementation_context()` via `chunks.append(f"# === FILE: {path} ===\n{content}\n")` and then sends it as `ValidationRequest(code=bundle, ...)`. This file does not establish or record an inert untrusted-input boundary, so repo comments or filenames containing instruction-like text could steer the validator unless a hidden downstream service comp…

Expose meaningful operational state, not internal complexity

Operational state is not represented in user-relevant durable terms. The code stores final success as `app.validation_run_id`, but blocked/failure states are encoded into `app.rejection_reason` strings like `bridge_exit:selector_rejected` and `fetch_failed:{kind}: ...`. There is no first-class status model for `active`, `blocked`, `failed`, `awaiting retry`, or `complete`, and no persisted state at all while clone/validate is running.

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

The delegated work is implemented as sequential script control flow rather than a durable system of tasks. The docstring lists eight phases, but the database only receives a final `UserValidationRun` after success or a coarse `rejection_reason` on selected graceful exits. Substeps such as clone, language detection, selection, file-read skipping, LLM validation, and persistence are not represented as resumable or inspectable task states while they are happening.

Align feedback with the user’s level of attention

Feedback is not calibrated to attention level. The active operator sees console messages such as `✓ Cloned`, `✗ Selector rejected`, and skipped-read warnings, but absent users receive only eventual dashboard effects. More seriously, `approve()` catches any exception from `run_cohort_validate(app.id)` and executes `pass`, so an intervention-worthy validation failure after account creation/email is neither logged nor persisted for the applicant or founder.

Optimise for steering, not only initiating

The workflow supports initiation and manual rerun, but not steering while underway. Once `run_cohort_validate()` starts, there is no durable pause, abort, resume, retry-from-step, or constraint-update primitive; the only practical controls are Ctrl-C, waiting, or rerunning if `validation_run_id` was never set. The approval path also commits user creation before downstream email/validation phases, without a rollback or recovery state beyond comments about manual rerun.