# Project export: Release Assurance This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: OpenAI Build Week - Tagline: Codex proposes. Humans approve. Auditors get receipts. Release Assurance catches silent banking migration failures and turns every fix into audit-ready evidence. - Devpost: https://devpost.com/software/release-assurance - GitHub: https://github.com/MeLinResearch/CodexBuildWeek2026 - Video: https://www.youtube.com/embed/XkCuBTbo8Og?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Team: 2 GitHub contributor(s) — Melinda Emerson (48 commits), Pavel Ivanov (29 commits) ## Devpost submission (written by the team) No Devpost description available. ## README (from the GitHub repository) # Release Assurance: Codex-Gated Migration Testing for Banks Release Assurance catches silent banking migration defects before they ship. It turns a conversion specification into traceable requirements, runs deterministic checks, maps each failure to the requirement it violates, presents a bounded Codex patch proposal for human review, and produces an audit-ready evidence pack after the approval-gated rerun. **Codex proposes. Humans approve. Auditors get receipts.** ## Judge quickstart The supported judging path is deterministic fixture mode. It uses canonical synthetic banking data, requires zero secrets, and makes zero live GPT-5.6 or Codex calls while exercising the same persisted API, approval, rerun, and evidence flow shown in the submitted demo. Requirements: - Python 3.12 or newer - Bun 1.3.x - GNU Make on macOS, Linux, or Windows From the repository root: ```bash make setup make test make demo ``` `make test` runs the Python backend tests, frontend lint and tests, and the production frontend build. `make demo` runs the complete FastAPI fixture smoke path from failure through approval, rerun, a green traceability matrix, and evidence generation. For the visual application: ```bash make dev ``` Then open `http://127.0.0.1:9000`. The API runs on `127.0.0.1:9001`. Press `Ctrl-C` once to stop both processes. CI runs `make setup`, `make test`, and `make demo` on Ubuntu, macOS, and Windows. ## What the product proves Release Assurance implements a bounded operating model for AI in regulated workflows: 1. GPT-5.6 translates implementation prose into a schema-validated control manifest with provenance. 2. Deterministic checks decide whether the migrated records satisfy those requirements. 3. Every failure maps back to a stable requirement and evidence artifact. 4. Codex analyzes the failure and returns a narrowly scoped, reviewable patch proposal. 5. A human must inspect the complete diff, enter a decision note, and explicitly approve it. 6. The approved patch is verified in a disposable workspace. 7. The evidence pack preserves provenance, traceability, the decision record, verification results, and the state-transition audit trail. Models interpret and propose. Deterministic systems verify. Humans authorize consequential actions. ## How GPT-5.6 and Codex were used ### During development GPT-5.6 was used as a planning, requirements-analysis, and review partner throughout Build Week. It helped inspect repository state, translate human product and architecture decisions into bounded implementation tasks, review actual patches and CI evidence, diagnose cross-platform failures, and keep the fixture and live claims explicit. Codex executed narrowly scoped engineering tasks across the repository. Its work included backend and frontend implementation slices, schema and patch-safety validation, test generation and refinement, Windows and browser-automation debugging, cross-platform demo tooling, and final workflow hardening. The human team retained the product, architecture, scope, and approval decisions. Representative evidence: - [Codex feedback session](https://chatgpt.com/s/cd_6a5e9a0b4798819183a1ebf3d0250d84) - [PR #27: isolated live GPT-5.6 and Codex proposal boundaries](https://github.com/MeLinResearch/CodexBuildWeek2026/pull/27) - [Dated pull-request history](https://github.com/MeLinResearch/CodexBuildWeek2026/pulls?q=is%3Apr) ### Inside Release Assurance The model boundaries are deliberately narrow: - GPT-5.6 may extract structured requirements, but it cannot determine whether the migration passed. - Codex may propose a patch, but it cannot approve or silently apply its own work. - Model-shaped outputs are validated before entering deterministic processing. - Raw model text is quarantined. - Patch scope and applicability are checked before the proposal reaches the reviewer. - Human approval remains mandatory before verification. ## Deterministic fixture mode `make demo` is the supported offline, clean-laptop, and judge-runnable path. The fixture replay uses frozen canonical banking inputs and model-shaped outputs while preserving the real application workflow: - requirements and provenance - deterministic failures - traceability matrix - complete patch diff - reviewer note and approval - disposable rerun - green verification state - downloadable evidence pack Fixture artifacts are labeled as fixture evidence and are never represented as live model output. ## Optional credentialed live runtime `make demo-live` starts the optional credentialed GPT-5.6 and Codex path. It requires: - a nonempty `OPENAI_API_KEY` - an API model available to the key, configured with `RELEASE_ASSURANCE_GPT_MODEL` - an installed and authenticated Codex CLI, or an executable selected with `RELEASE_ASSURANCE_CODEX_EXECUTABLE` Starting `make demo-live` performs prerequisite checks but makes no paid model call. The paid flow begins only when **Run Live GPT + Codex** is clicked in the application. On Windows PowerShell: ```powershell $env:OPENAI_API_KEY = "" bun run scripts/demo-live.ts ``` The submitted video and supported judging path use deterministic fixture mode. The optional live adapters demonstrate the isolated GPT-5.6 extraction and read-only Codex proposal boundaries without making live credentials a judging requirement. ## Windows without GNU Make Activate the virtual environment and install the dependencies from the repository root: ```powershell .\.venv\Scripts\Activate.ps1 python -m pip install -e "backend[dev]" cd frontend bun install --frozen-lockfile bun dev ``` For the equivalent test path, run the backend tests from the repository root, then the frontend lint, tests, and build: ```powershell python -m pytest backend/tests cd frontend bun lint bun test bun run build ``` ## Build Week scope and provenance The base deterministic migration engine in `reconcile/` is pre-existing work originally developed in [MeLinResearch/Reconcile](https://github.com/MeLinResearch/Reconcile). It was imported under the MIT License from commit `b280ed49388791f3cae7fa2fc88144c2c706bd9d` and was not created during OpenAI Build Week. Detailed provenance and the exact vendoring changes are documented in [`reconcile/README.md`](reconcile/README.md). The work created during the July 13 to July 21, 2026 submission period is Release Assurance around that engine: - frozen contracts and canonical synthetic fixtures - the GPT-5.6 requirement-extraction boundary - deterministic banking controls and failure evidence - the Codex patch-proposal and patch-safety boundary - the FastAPI workflow, state machine, persistence, and API - the React traceability, diff-review, approval, rerun, and evidence experience - disposable verification and evidence generation - cross-platform CI, testing, and demo tooling Initial project scaffolding used Claude/Fable and is not represented as Codex work. The linked Codex session, Codex-linked pull requests, and dated commit history distinguish the later GPT-5.6 and Codex contributions. ## Safety boundaries Only defined model-shaped objects, including the control manifest and patch proposal, are schema validated. Reports and logs are not universally schema validated. In both fixture and live approved-patch verification, the patched Python executes with the user's normal machine permissions. The disposable workspace protects the repository from modification, but it is not a security sandbox. Human inspection of the complete diff is the execution-control boundary. The deterministic acceptance verifier is specifically designed for the canonical banking fixture. It is not represented as a general-purpose migration-verification engine. Browser actions use only canonical repository input paths, and dropped files select the deterministic fixture replay rather than uploading arbitrary contents. ## Media attribution The demo uses [Background Music Soft Calm](https://pixabay.com/music/upbeat-background-m [README truncated for size] ## Detected evidence (automated analysis) Indexed codebase: 163 recognized source files, 583 KB. - CSS (language) — detected in the code - FastAPI (technology) — detected in the code - HTML (language) — detected in the code - OpenAI (technology) — detected in the code - Python (language) — detected in the code - React (technology) — detected in the code - SQL (language) — detected in the code - Tailwind CSS (technology) — detected in the code - TypeScript (language) — detected in the code - AI coding agent: Claude Code — evidence: commit authorship or trailers - AI coding agent: Codex — evidence: config files committed to the repository ## Codebase structure (from repository index) ### Files (120 of 215) ``` .env.example .gitattributes .github/workflows/ci.yml .gitignore .python-version ARCHITECTURE.md backend/app/__init__.py backend/app/codex/__init__.py backend/app/codex/client.py backend/app/codex/live_client.py backend/app/codex/live_spike.md backend/app/codex/sandbox.py backend/app/codex/validate.py backend/app/config.py backend/app/director/__init__.py backend/app/director/live_client.py backend/app/director/models.py backend/app/evidence/__init__.py backend/app/evidence/render.py backend/app/fixture_loader.py backend/app/llm/__init__.py backend/app/llm/client.py backend/app/llm/fixture_client.py backend/app/llm/live_client.py backend/app/llm/validate.py backend/app/main.py backend/app/pipeline/__init__.py backend/app/pipeline/live_checks.py backend/app/pipeline/live_pipeline.py backend/app/pipeline/live_rerun.py backend/app/pipeline/mock_pipeline.py backend/app/pipeline/repair_verifier.py backend/app/routers/__init__.py backend/app/routers/approvals.py backend/app/routers/director.py backend/app/routers/evidence.py backend/app/routers/runs.py backend/app/store/__init__.py backend/app/store/db.py backend/app/store/models.py backend/app/store/schema.sql backend/app/store/state_machine.py backend/pyproject.toml backend/README.md backend/tests/conftest.py backend/tests/test_api_fixture_mode.py backend/tests/test_api_store_backed.py backend/tests/test_codex_live_client.py backend/tests/test_codex_sandbox.py backend/tests/test_codex_spike_documentation.py backend/tests/test_codex_validate.py backend/tests/test_contracts.py backend/tests/test_director_api.py backend/tests/test_director_client.py backend/tests/test_evidence_render.py backend/tests/test_fixture_patch_applicability.py backend/tests/test_fixtures.py backend/tests/test_live_api.py backend/tests/test_live_checks.py backend/tests/test_live_pipeline.py backend/tests/test_live_rerun.py backend/tests/test_llm_fixture_client.py backend/tests/test_llm_live_client.py backend/tests/test_llm_validate.py backend/tests/test_mock_pipeline.py backend/tests/test_no_fake_dependencies.py backend/tests/test_planted_migration.py backend/tests/test_reconcile_agent.py backend/tests/test_reconcile_fixture.py backend/tests/test_reconcile_heuristic.py backend/tests/test_reconcile_validate.py backend/tests/test_state_machine.py backend/tests/test_store_live_ids.py backend/tests/test_store.py contracts/control_manifest.schema.json contracts/failed_record.schema.json contracts/mapping_proposal.schema.json contracts/patch_proposal.schema.json contracts/provenance.schema.json contracts/README.md contracts/run_request.schema.json contracts/run_status.schema.json contracts/summary_stats.schema.json contracts/traceability_row.schema.json contracts/VERSION design-system.md docs/superpowers/specs/2026-07-14-frontend-ui-ux-design.md fixtures/api/failed_record_FAIL-001.fixture.json fixtures/api/failed_record_FAIL-002.fixture.json fixtures/api/failed_record_FAIL-003.fixture.json fixtures/api/patch_PATCH-001.fixture.json fixtures/api/run_status.fixture.json fixtures/api/summary_stats.fixture.json fixtures/api/traceability_matrix.fixture.json fixtures/implementation_doc.md fixtures/model_outputs/codex_test_artifacts.fixture.json fixtures/model_outputs/control_manifest.fixture.json fixtures/model_outputs/patch_proposal.fixture.json fixtures/planted_defects/DEFECTS.md fixtures/README.md fixtures/schemas/target_schema.json fixtures/source_data/accounts.csv frontend/.agents/instructions/code-style.md frontend/.agents/instructions/collaboration.md frontend/.agents/instructions/react.md frontend/.agents/instructions/typescript.md frontend/.nvmrc frontend/.vscode/extensions.json frontend/.vscode/settings.json frontend/AGENTS.md frontend/biome.json frontend/bun.lock frontend/components.json frontend/index.html frontend/knip.json frontend/package.json frontend/public/demo-inputs/core-banking/accounts.csv frontend/public/demo-inputs/core-banking/implementation_doc.md frontend/public/demo-inputs/core-banking/target_schema.json frontend/README.md [95 more files omitted for size] ``` ### Dependencies - backend/pyproject.toml: fastapi@>=0.111, httpx@>=0.27, jsonschema@>=4.22, openai@>=2.38,<3, pydantic@>=2.7, pytest@>=8.2, uvicorn@>=0.30 - frontend/package.json: @base-ui/react@^1.6.0, @biomejs/biome@2.5.3, @fontsource-variable/geist@^5.2.9, @fontsource-variable/geist-mono@^5.2.8, @pierre/diffs@^1.2.12, @pivanov/utils@^1.0.0, @tailwindcss/vite@^4.3.2, @tanstack/react-query@^5.101.2, @tanstack/react-router@^1.170.17, @tanstack/router-cli@^1.167.18, @tanstack/router-plugin@^1.168.19, @types/bun@^1.3.14, @types/react@^19.2.17, @types/react-dom@^19.2.3, @vitejs/plugin-react@^6.0.3, class-variance-authority@^0.7.1, clsx@^2.1.1, knip@^6.26.0, lucide-react@^1.24.0, motion@^12.42.2, react@^19.2.7, react-dom@^19.2.7, react-markdown@^10.1.0, shadcn@^4.13.0, tailwind-merge@^3.6.0, tailwindcss@^4.3.2, tw-animate-css@^1.4.0, typescript@^7.0.2, vite@^8.1.4, zustand@^5.0.14 ### Recent commits (newest first) - Polish submission copy for readability - Strengthen README for Build Week judging - Merge pull request #34 from MeLinResearch/prepare-the-demo - Make live demo automation explicitly opt-in - Harden live demo portability and CI coverage - Finalize demo timing, decisions, and speech pipeline - Refactor demo director into React components - Add branded avatars and scripted demo finale - Polish the live intro transition - Upgrade speech generation and viewport choreography - Synchronize narration, cursor, and approval choreography - Build Codex-directed live demo runtime - Merge pull request #33 from MeLinResearch/fix/final-demo-hardening - Document final demo trust boundaries - Render canonical metadata for live requirement IDs - Verify approved fixture patches before reporting success - Close diff prefix validation bypass - Merge pull request #32 from MeLinResearch/codex/add-runnable-live-demo-entrypoint - Add live demo entrypoint - Merge pull request #31 from MeLinResearch/agent/approval-gated-live-rerun ## Key source files (fetched from GitHub, selected and truncated for size) ### design-system.md ```markdown ## 0. Your task Build a design system. The product feels like modern serious SaaS — Linear / Vercel. Calm, precise, editorial-but-technical. **Not** playful, not brutalist, not "AI-gradient slop." Deliver: 1. A **Tailwind v4 theme** (`@theme` block in CSS with all design tokens as CSS variables). 2. **shadcn/ui** component overrides (`components.json` config + restyled primitives) that match the tokens below. 3. **Base UI** for headless interactive primitives (dropdowns, dialogs, popovers, tabs) styled to match. 4. A **living style guide page** demonstrating every token and component. Follow the tokens below **exactly** — they are extracted from shipped product code, not invented. --- ## 1. Brand & aesthetic principles - **Modern serious SaaS.** Restraint over decoration. Every element earns its place. - **Off-white canvas**, never pure white page background. White is reserved for raised surfaces (cards, app chrome, inputs). - **One accent only: indigo.** Use it sparingly — for the primary action, active states, citations, and the emphasis gradient. Never flood a surface with it. - **Monospace is functional chrome only** — citation numbers, judge axes, metadata, counts, keyboard hints, plan labels. **Never** body prose, never headings. - **No italics, no serif, no decorative fonts.** Emphasis in headings is done with a dark→indigo gradient on the emphasized words (see §3). - **Hairline borders + soft shadows** define hierarchy, not heavy strokes or big radii. - Avoid: aggressive gradients as backgrounds, emoji, rounded-corner-with-left-accent-border cards, "data slop" (decorative stats/icons), Inter/Roboto/Arial. --- ## 2. Color tokens All shipped as hex / rgba. Convert to CSS variables in `@theme`. Provide both a raw palette and semantic aliases. ### Core neutrals | Token | Value | Use | |---|---|---| | `--bg` | `#fafaf9` | Page background (off-white). The default canvas. | | `--surface` | `#ffffff` | Raised surfaces: cards, app chrome, inputs, dropdowns. | | `--surface-sunken` | `#f7f6f4` | App title bars, subtle sunken panels. | | `--surface-muted` | `#f4f3ef` | Chips, tags, tag backgrounds, count pills. | | `--ink` | `#0a0a0a` | Near-black. Primary text, headings, primary button bg. | | `--ink-2` | `#1a1a18` | Body prose in article context. | | `--ink-3` | `#2a2a27` | Quote/secondary body. | | `--text-secondary` | `#3a3a37` | Nav links, secondary UI text. | | `--text-muted` | `#4a4a48` | Descriptions, captions. | | `--text-faint` | `#8a8a85` | Metadata, placeholder, timestamps, section labels. | | `--text-faintest` | `#c4c4be` / `#d4d4d0` | Separator dots, disabled ticks. | ### Borders (all as rgba over ink) | Token | Value | |---|---| | `--border` | `rgba(10,10,10,.06)` — default hairline (nav, cards, sidebar dividers) | | `--border-strong` | `rgba(10,10,10,.08)` — buttons/inputs at rest | | `--border-hover` | `rgba(10,10,10,.12)`–`.18` — hover / emphasis | ### Accent — indigo | Token | Value | Use | |---|---|---| | `--accent [truncated — 8618 more characters] ``` ### fixtures/implementation_doc.md ```markdown # Bank Migration Demo Implementation Doc Requirements: preserve account identifiers verbatim; debits equal credits by branch; no silent value substitution. ``` ### backend/pyproject.toml ``` [project] name = "release-assurance-backend" version = "0.1.0" requires-python = ">=3.12" dependencies = ["fastapi>=0.111", "pydantic>=2.7", "uvicorn>=0.30", "jsonschema>=4.22", "openai>=2.38,<3"] [project.optional-dependencies] dev = ["pytest>=8.2", "httpx>=0.27"] [build-system] requires = ["setuptools>=68"] build-backend = "setuptools.build_meta" [tool.setuptools.packages.find] where = ["."] include = ["app*"] ``` ### frontend/package.json ``` { "scripts": { "routes:generate": "tsr generate", "dev": "bun run ../scripts/dev.ts", "build": "bun run routes:generate && tsc -b && vite build", "preview": "vite preview", "format": "biome check --write .", "lint": "bun run routes:generate && bun run lint:biome && bun run lint:types && bun run lint:knip", "lint:fix": "biome check --write . && bun lint", "lint:biome": "biome check . ../scripts", "lint:types": "tsc -b --pretty false", "lint:knip": "knip", "test": "bun test" }, "dependencies": { "@base-ui/react": "^1.6.0", "@fontsource-variable/geist": "^5.2.9", "@fontsource-variable/geist-mono": "^5.2.8", "@pierre/diffs": "^1.2.12", "@pivanov/utils": "^1.0.0", "@tanstack/react-query": "^5.101.2", "@tanstack/react-router": "^1.170.17", "class-variance-authority": "^0.7.1", "clsx": "^2.1.1", "lucide-react": "^1.24.0", "motion": "^12.42.2", "react": "^19.2.7", "react-dom": "^19.2.7", "react-markdown": "^10.1.0", "tailwind-merge": "^3.6.0", "zustand": "^5.0.14" }, "devDependencies": { "@biomejs/biome": "2.5.3", "@tailwindcss/vite": "^4.3.2", "@tanstack/router-cli": "^1.167.18", "@tanstack/router-plugin": "^1.168.19", "@types/bun": "^1.3.14", "@types/react": "^19.2.17", "@types/react-dom": "^19.2.3", "@vitejs/plugin-react": "^6.0.3", "knip": "^6.26.0", "shadcn": "^4.13.0", "tailwindcss": "^4.3.2", "tw-animate-css": "^1.4.0", "typescript": "^7.0.2", "vite": "^8.1.4" } } ``` ### backend/app/main.py ```python from fastapi import FastAPI from app.routers import approvals, director, evidence, runs app = FastAPI(title="Release Assurance API") app.include_router(runs.router) app.include_router(approvals.router) app.include_router(evidence.router) app.include_router(director.router) ``` ### frontend/src/main.tsx ```typescript import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; import { createRouter, RouterProvider } from '@tanstack/react-router'; import React from 'react'; import { createRoot } from 'react-dom/client'; import { installDemoDirector } from '@/components/director/director'; import { initializeTheme } from '@/lib/theme'; import { routeTree } from '@/routeTree.gen'; import '@/index.css'; const queryClient = new QueryClient({ defaultOptions: { queries: { retry: 1, staleTime: Number.POSITIVE_INFINITY, }, }, }); const router = createRouter({ routeTree, context: { queryClient, }, defaultPreload: 'intent', }); declare module '@tanstack/react-router' { interface Register { router: typeof router; } } const rootElement = document.getElementById('root'); if (!rootElement) { throw new Error('Root element not found'); } initializeTheme(); createRoot(rootElement).render( , ); const directorEnabled = new URLSearchParams(window.location.search).get('director') === '1'; if (directorEnabled) { installDemoDirector(); } ``` ### frontend/src/routes/index.tsx ```typescript import { createFileRoute } from '@tanstack/react-router'; import { StartView } from '@/views/start-view'; export const Route = createFileRoute('/')({ component: StartView, }); ``` ### reconcile/__init__.py ```python from .agent import ReconcileResult, reconcile, to_json __all__ = ["ReconcileResult", "reconcile", "to_json"] ``` ### frontend/index.html ```html
``` ### frontend/vite.config.ts ```typescript import path from 'node:path'; import tailwindcss from '@tailwindcss/vite'; import { tanstackRouter } from '@tanstack/router-plugin/vite'; import react from '@vitejs/plugin-react'; import { defineConfig } from 'vite'; export default defineConfig({ plugins: [tanstackRouter({ target: 'react', autoCodeSplitting: true }), react(), tailwindcss()], build: { // The diff renderer emits syntax grammars as lazy chunks. Some individual // Shiki grammars exceed Vite's 500 kB default but are not startup payloads. chunkSizeWarningLimit: 800, }, resolve: { alias: { '@': path.resolve(import.meta.dirname, './src'), }, }, server: { host: '127.0.0.1', port: 9000, strictPort: true, proxy: { '/api': 'http://127.0.0.1:9001', }, }, }); ``` [145 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]