Verification-First Software Factory — Mission Control Case Study
An agent can generate code, run a test, and confidently report success while still misunderstanding the request, exceeding its authority, weakening the test system, or validating a different artifact from the one placed in a pull request. T
A focused view of boundaries, contracts, state, authority, failure paths, and tradeoffs drawn from this chapter.
Reconstruct and defend this chapter’s architecture.
Reconstruct the architecture, name each boundary, and defend the tradeoffs.
Open the source exercise
Exercise 1 — the assurance chain
From memory, draw Mission → Plan → WorkOrder → Attempt → Candidate → Verification Run → Evidence → Gate Decision → Approval → Publication Permit → Pull Request. Annotate each edge with the identity or authority that prevents a stale subject from advancing.
Success means you can explain why no box can mark itself accepted.
Exercise 2 — trust boundaries
Draw browser, Convex, Hono/orchestration, agent process, worktree, verifier, GitHub, and CI. Mark credentials, untrusted inputs, immutable subjects, and external side effects. Walk through candidate substitution, evidence replay, test weakening, and cross-tenant evidence access.
Success means every threat has both a prevention control and a detection or reconciliation path.
Exercise 3 — three audiences
Explain verification-first architecture in:
- 30 seconds to a CEO, emphasizing accountable speed;
- two minutes to a CTO, emphasizing policy, evidence, and risk; and
- ten minutes to a principal engineer, including state, identity, failure, and tradeoffs.
Core domain model
The verification-first model adds assurance concepts without replacing the authoritative delivery hierarchy.
| Concept | Responsibility | What it does not prove |
|---|---|---|
| Quality Contract | Defines requirements, constraints, verification methods, gates, and approvals before execution | That implementation succeeded |
| Change Budget | Bounds files, change size, protected paths, and permitted change types | That an in-budget change is correct |
| Attempt | Preserves one immutable execution try and its authority | That the result is acceptable |
| Candidate | Identifies the exact committed source subject | That checks passed |
| Verification Run | Records the execution of defined checks against an exact subject | That the overall WorkOrder may advance |
| Evidence Envelope | Binds a typed claim, producer, method, time, and artifact to a subject | That the claim is sufficient or authoritative |
| Quality Gate Decision | Applies a versioned policy to the contract and evidence set | Permission for every future side effect |
| Publication Permit | Grants one scoped, expiring external action | Merge, deployment, or Mission acceptance |
| Proof Package | Projects the trace needed for human review and audit | A second source of truth |
The hierarchy remains Mission → Plan → WorkOrder → Task → Attempt → Evidence → Pull Request. The assurance records explain why a transition is eligible; they do not erase the separate ownership and acceptance boundaries in that hierarchy.
Tradeoffs
Verification-first architecture adds latency, storage, policy design, and operator complexity. Independent environments cost more than self-review. Immutable records require explicit supersession instead of convenient edits. Failing closed can delay work when a verifier is unavailable. Strong candidate binding makes seemingly harmless post-verification changes require another run.
These costs should be proportional to risk. Low-risk documentation work does not need the same verifier set as authorization or migration code. However, risk proportionality must not become an excuse to remove identity, authority, lineage, or evidence integrity. A low-risk change can use fewer checks; it cannot publish a different SHA from the one checked.
There is also a modeling tradeoff. Mission Control can create a separate Quality Contract record or treat it as a versioned projection of the approved Plan frozen into the WorkOrder. A separate record can clarify ownership and reuse, but it can create parallel truth. A projection preserves the existing hierarchy, but requires disciplined versioning and may produce a larger WorkOrder contract. The product ADR set intentionally requires this question to be settled before unnecessary schema expansion.
Current Mission Control Implementation
At Mission Control commit
ff0524e,
the P0 vertical slice is materially implemented. The WorkOrder contract can
carry typed requirements, negative constraints, a three-boundary Change
Budget, and a verification contract. The runtime creates candidate-bound
Verification Runs and Evidence Envelopes, recomputes verdicts server-side,
persists WorkOrder-level receipts, pauses for required human review, and issues
a continuation/publication authority before the durable GitHub path proceeds.
Useful implementation traces include:
packages/workflow-engine/src/verification.tsfor deterministic check and verdict semantics;apps/orchestration-server/src/factoryVerification.tsfor verifier command execution;apps/orchestration-server/src/factoryAttemptWorker.tsfor candidate, verification, review suspension, resume, and publication sequencing;convex/lib/verificationPersistence.tsfor persisted verification evidence;convex/factory/attempts.tsfor Attempt authority, approval, and terminal behavior; andconvex/schema.tsfor current durable records.
The implementation status is partial P0, not complete factory assurance.
The product documentation records a proposed explicit Quality Gate lifecycle,
a V1 verification profile, a threat model, recovery rules, and an integrated
golden-path manifest. Those documents now exist on main, but proposed records
and states remain design until source, tests, and browser evidence prove them.
The most important current boundary is evidence level. Component and runtime tests demonstrate mechanisms. They do not yet satisfy the full browser-operated Mission-to-verified-PR manifest with a deliberate failure and recovery.
Curriculum maturity is not implementation proof.
This case study records scoped implementation claims. Inspect the exact evidence, commit references, gaps, and verification boundaries in the source below.
Review this chapter.
Challenge a claim, boundary, missing failure mode, unclear term, or unsupported evidence statement.
- Claim
- Boundary
- Failure
- Evidence