ADO or JSON/YAML
Epic/Feature hierarchy or versioned whole-application blueprint.
ADO/JSON to production-shaped application
Architecture first.
TDD evidence for every behavior.
testgen app turns a versioned application blueprint or Azure DevOps hierarchy into an approved full-stack plan, deterministic monorepo, criterion-by-criterion TDD workflow, system evidence report, and idempotent draft PR.
Hash-bound approval
Transactional writes
Frozen-test receipts
React + Fastify + PostgreSQL
Human-reviewed draft PR
Lifecycle
One provider-neutral application pipeline
ADO and local documents normalize before planning. Downstream generation never branches on the original source provider.
Canonical package
Stories, revisions, evidence, content hashes, and the 200-item limit.
Architecture plan
Routes, components, APIs, data, authorization, tests, and trace graph.
Human approval
Approval covers the exact package and plan hashes. Drift invalidates it.
Deterministic shell
Transactional monorepo, lockfile, migration, containers, and CI.
TDD slices
Valid RED, bounded implementation, GREEN, and regression-safe refactor.
Draft PR only
All gates, revision recheck, exact branch, linked work items, audit comment.
Fail-closed rule: unresolved architecture decisions, revision drift, invalid RED, modified frozen tests, unsafe writes, missing required tools, failing migrations, or incomplete receipts block forward progress. They are never converted into PASS.
Versioned contracts
Hashes make every decision reviewable
JSON Schema Draft 2020-12 validates input. Public V1 contracts carry the normalized truth through approval, TDD, resumption, verification, and delivery.
ApplicationBlueprintV1
Application, actors and roles, features, criteria, entities, integrations, routes, non-functional requirements, OIDC mode, and quality policy.
CanonicalApplicationPackageV1
Normalized root and descendants, authoritative stories, complete revision set, source evidence, package hash, and provider-independent blueprint.
ApplicationArchitecturePlanV1
Concrete route, component, API, data, authorization, test and trace graphs plus blockers, inferences, planned files, and plan hash.
TddReceiptV1
Requirement hash, frozen-test hash, source-tree hashes, exact commands, exit codes, RED classification, GREEN and refactor regression results.
GenerationRunManifestV1
Run state, owned files and hashes, completed slices, blocked reasons, versions, materialized graph index, quality evidence, and delivery result.
ApplicationQualityReportV1
PASS, FAIL, BLOCKED, or NOT_RUN for every required gate. Missing mutation or security tooling remains NOT_RUN and blocks delivery.
Target architecture
Graphs first, then files
The planner establishes ownership and traceability before the scaffold writer materializes a file. After generation, indexes must reconcile exactly with the approved plan.
Generated npm-workspaces monorepo
apps/ web/ React, Vite, React Router Data Mode api/ Fastify modular monolith packages/ contracts/ trusted schemas, OpenAPI, typed client ui/ accessible primitives and design tokens prisma/ schema + committed SQL migrations docker/ multi-stage non-root images azure-pipelines.yml build and evidence, no deploy
Architecture enforcement
- Nested layouts, lazy route modules, loaders/actions, access metadata, and route error boundaries.
- Protected access is enforced in both route loaders/actions and Fastify authorization hooks.
- Only generator-owned files with matching provenance hashes may be regenerated.
- Path traversal, symlink segments, cross-feature imports, circular dependencies, and human-owned collisions are rejected.
- Existing symbols use evidence confidence; greenfield symbols use planned → materialized → indexed → verified states.
Existing-code mapping: the evidence model records its version, enabled signals, normalized weights, and reachable ceiling. Review remains 0.65 and auto-map remains 0.85; thresholds are never lowered to compensate for incomplete signals. Deterministic history, adjacency, ownership, call-graph, lexical, reference, and validated runtime-history evidence contribute only when present.
TDD architecture
A passing test is not enough; the sequence must be proven
Each approved criterion advances independently. The receipt proves that the test existed and failed for the intended missing behavior before implementation changed.
Approved criterion
Requirement and architecture hashes are current and the permitted source scope is explicit.
Write and freeze test
The executable test hash is recorded before behavior implementation.
Classify RED
The test compiles, runs, and fails because the approved observable behavior is missing.
Bounded patch
A typed replacement plan may modify only approved source files with matching old hashes.
Focused GREEN
The unchanged frozen test passes and the source-tree hash proves implementation changed.
Regression + refactor
Full regression passes; refactoring is allowed only afterward and affected tests rerun.
Complete receipt
Sanitized evidence is stored; the manifest can resume at the next unverified slice.
Invalid RED → BLOCKED: compile errors, unresolved imports, broken fixtures, test setup failures, missing environment, database connection errors, timeouts, or artificial failures such as
expect(true).toBe(false) do not prove missing business behavior.Requirement integrityApproved criterion hash and architecture plan hash remain unchanged.
Test integrityFrozen test hash is identical for RED and GREEN; weakening or replacement is rejected.
Source integrityBefore/after tree hashes prove implementation changed inside the approved scope.
Execution integrityExact command, exit code, framework result, and valid RED classification are recorded.
Regression integrityFocused GREEN and full regression GREEN are both required before completion.
Refactor integrityRefactoring follows GREEN and re-runs every affected focused and regression suite.
Claim language: existing work with passing tests is described as regression-tested or test-covered. A slice is described as TDD-verified only when its stored receipt proves this complete sequence.
Production gates
System evidence before delivery
The verifier evaluates the generated application as a system. Any unavailable required tool reports NOT_RUN and blocks promotion.
Build and structure
- Strict TypeScript, lint, formatting, Vite production build
- Route/component graph reconciliation
- Architecture boundaries and circular-dependency checks
- OpenAPI and generated-client compatibility
Behavior and resilience
- One executable test per criterion and route
- Unit, component, API integration, contract, and journey tests
- Permitted and denied role coverage
- Loading, empty, validation, conflict, forbidden, and failure states
Depth
- 85% lines/statements/functions and 80% branches
- Critical modules: 90% lines and 85% branches
- 70% mutation score with no surviving critical mutant
- Focused and full-regression receipts
Database
- Migration replay from an empty PostgreSQL database
- Upgrade from previous fixture schema
- Constraints, optimistic concurrency, and immutable audit events
migrate deploylimited to CI/production workflows
Accessibility and security
- WCAG 2.2 AA automated checks
- Keyboard and focus journeys
- OWASP ASVS 5 L1 baseline
- Dependency audit, secret scan, and non-root container scan
Operations
- Structured logs and request IDs
- Health and readiness endpoints
- Server telemetry hooks
- Browser telemetry isolated behind a provider adapter
Operator workflow
Plan, approve, scaffold, prove, verify, deliver
Run the scaffold inside a pre-created initialized Git worktree on the exact delivery branch.
# Normalize, plan, lint, and approve exact hashes testgen app plan --file .testgen/fixtures/applications/expense-operations.v1.json --output .testgen/applications/EXP-9000.plan.json testgen app lint --plan .testgen/applications/EXP-9000.plan.json testgen app approve --plan .testgen/applications/EXP-9000.plan.json --by product.owner@example.test # Scaffold in the exact delivery worktree git worktree add ../expense-operations codex/EXP-9000-expense-operations-platform testgen app scaffold --plan .testgen/applications/EXP-9000.plan.json --target ../expense-operations # Prove one approved requirement through RED, implementation, GREEN, refactor testgen app tdd red --plan <plan> --target <worktree> --requirement <id> --test <test-file> --source <source-file> testgen app tdd implement --plan <plan> --target <worktree> --requirement <id> testgen app tdd green --plan <plan> --target <worktree> --requirement <id> testgen app tdd refactor --plan <plan> --target <worktree> --requirement <id> # All receipts and system gates must pass before draft delivery testgen app verify --plan <plan> --target <worktree> testgen app deliver --plan <plan> --target <worktree> --repository <ado-repository> --target-branch main
ApplicationSourceProvider
Reads hierarchy, work-item revisions, relations, and changes. Local JSON/YAML implements only this read boundary.
- Epic or Feature root
- Epic → Feature → Story
- Tasks are non-authoritative notes
- Maximum 200 work items in v1
ApplicationDeliveryProvider
Opt-in ADO write boundary used only after verification and revision recheck.
- Push exact
codex/<ticket>-<slug>branch - Create or update one linked draft PR
- Upsert one audit comment
- Never merge, deploy, transition work items, or bypass policy
Authentication: interactive runs use Microsoft Entra delegated authentication; unattended runs use service-principal or workload identity. PAT is an explicit development fallback and is rejected by production delivery profiles. Work-item read,
vso.work_write, and vso.code_write remain separate least-privilege capabilities.Evidence and promotion
Implemented is not the same as production-promoted
The local verification below supports the generator implementation. Promotion additionally requires complete application evidence in controlled external environments.
| Evidence | Current result | Meaning |
|---|---|---|
| TestGen package | PASS 50 suites, 539 passed, 5 intentional skips | Generator and regression behavior covered in the current workspace. |
| ADO adapter | PASS 3 suites, 22 passed | Provider, authentication, batching, and idempotent delivery behavior covered. |
| Typecheck and claims | PASS both packages; 0 public-claim violations | Contracts compile and documentation avoids unsupported TDD/production claims. |
| Disposable scaffold | PASS install, Prisma, format, lint, architecture, typecheck, contracts, build, audit | The deterministic generated shell is internally coherent and buildable. |
| Expense all-slice pilot | REQUIRED | Every approved criterion needs a valid complete TDD receipt and every system gate must pass. |
| Second application pilot | REQUIRED | Prevents expense-domain overfitting and must independently satisfy the same gates. |
| Live ADO sandbox | REQUIRED | Must prove revision stability, least privilege, linked draft PR, updateable comment, and unchanged rerun idempotency. |
Expense Operations golden pilot
- Employee, manager, and finance OIDC roles
- Dashboard, expense CRUD, approvals, reports, and administration
- Receipts, categories, saved filters, pagination, export, audit events
- Database constraints, optimistic concurrency, API authorization
- Responsive accessible UI with observable failure states
Delivery remains blocked when
- Input revisions drift after approval
- A RED is invalid or a frozen test changes
- Any planned graph node is missing from the materialized index
- Any criterion lacks a complete receipt
- A required quality tool is NOT_RUN or a gate fails
- A write would overwrite human-owned or changed generated content