# Project export: PolicyProof 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: Turn written policy into verifiable controls, exact evidence, deterministic conclusions, and recorded human decisions. - Devpost: https://devpost.com/software/policyproof - GitHub: https://github.com/selisensei/policyproof - Demo: https://policyproof-green.vercel.app/ - Video: https://www.youtube.com/embed/5mKyIxU138M?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Team: 1 GitHub contributor(s) — Ilies Sampaio Fernandes (40 commits) ## Devpost submission (written by the team) No Devpost description available. ## README (from the GitHub repository) # PolicyProof **Policy review with exact evidence and a recorded human decision.** PolicyProof is a verification layer for procurement review. It turns written policy into reviewable controls, links each conclusion to exact evidence, runs objective checks deterministically, and keeps the final decision human. > GPT-5.6 reads and locates. > > TypeScript checks. > > A human decides. PolicyProof is a solo OpenAI Build Week 2026 project for the **Work & Productivity** track. It is designed for finance, procurement, and internal-control reviewers who need conclusions they can inspect and reproduce. ## Quick verification ```shell pnpm install --frozen-lockfile pnpm demo:verify pnpm dev ``` Open [http://localhost:3000](http://localhost:3000). `pnpm demo:verify` needs no API key, browser, development server, or live provider. It validates the three controlled scenarios, 21 conclusions, seven mutations, ten named adversarial cases, Review Fingerprints, Receipt Integrity, TypeScript, and the evaluation no-network guard. ## Product overview A reviewer can load a controlled policy and case, inspect seven controls, run a deterministic review, follow supporting or contradictory excerpts, record a final human decision, and export a locally verifiable receipt. The default Focused Demo makes the evidence path easy to present; Full Workspace retains the complete review, audit, comparison, and export surfaces. PolicyProof is a review aid. It does not approve a payment, certify compliance, establish document authenticity, or replace professional judgment. ## Primary controlled example Northstar is a fictional vendor-change and procurement case. The shared engine produces: | Outcome | Count | | --- | ---: | | PASS | 3 | | FAIL | 2 | | MISSING | 1 | | WARNING | 1 | The clearest evidence moment is a purchase order for **12,480 EUR** and an invoice for **12,480 USD**. PolicyProof shows both exact excerpts and fails currency consistency while amount match still passes. With one approver, changing the policy threshold from EUR 10,000 to EUR 15,000 changes only the approval control from FAIL to PASS; the other six conclusions remain unchanged. ## Why the workflow is structured The model does not make the final control result. GPT-5.6 proposes structured controls and locates structured facts and exact excerpts. Strict schemas and source checks reject unsupported references. The TypeScript engine then performs supported amount, currency, date, threshold, evidence-presence, and role comparisons. A reviewer confirms or overrides the final review with comments. ## Architecture ```mermaid flowchart LR R["Reviewer"] --> UI["Focused Demo or Full Workspace"] UI --> D["Controlled local fixtures"] UI --> API["Next.js server routes"] API --> G["GPT-5.6 Responses API"] G --> Z["Strict Zod output validation"] Z --> E["Exact excerpt verification"] D --> T["Deterministic TypeScript engine"] E --> T T --> H["Evidence-led human decision"] H --> P["Locally verifiable receipt"] ``` The deterministic path stops at local fictional fixtures and the TypeScript engine. The optional live path crosses the server boundary only after an explicit user action. The OpenAI key remains server-only. ## GPT-5.6 responsibilities - Interpret the written procurement policy. - Propose structured, editable controls. - Extract structured facts from explicitly selected fictional text documents. - Locate exact evidence excerpts. - Support the historically validated Northstar evidence pipeline. Northstar has one separate historical live GPT-5.6 validation at commit `eb120feaca78bf3cdbc71b7b7198045f86a44852`. The release checks do not rerun it. See [Live GPT-5.6 validation](docs/evaluation/LIVE_GPT56_VALIDATION.md). ## TypeScript responsibilities - Validate scenario, provider-output, evidence, fingerprint, receipt, and evaluation schemas. - Reject unknown documents and unsupported exact excerpts. - Calculate the seven supported deterministic control types. - Reproduce same-input conclusions and Review Fingerprints. - Isolate threshold mutations and scenario state. - Generate and verify receipt integrity locally. ## Human responsibilities - Confirm or edit model-proposed controls. - Interpret business context and exceptions. - Review supporting, contradictory, and missing evidence. - Record the final decision and comments. - Decide whether a case is ready for operational action. Neither GPT-5.6 nor the deterministic engine issues a legal or compliance certification. ## Focused Demo Focused Demo is the default Northstar-first presentation. Its path is: 1. Run review. 2. Inspect the EUR/USD contradiction. 3. Reproduce all seven conclusions with the same Review Fingerprint. 4. Change the threshold and inspect the one-control difference. 5. Record a human decision. 6. Generate and verify the decision receipt. It uses the same application state and engine as Full Workspace; it is not a scripted or precomputed second application. ## Full Workspace Full Workspace adds the Case Library, policy and document registers, editable controls, full result and evidence views, search and filters, current-session comparison, safe audit details, reviewer queue, print, JSON, Markdown, and CSV exports. Switching presentation level preserves active review state. ## Three controlled scenarios All scenarios use the same procurement policy, seven control types, typed scenario contract, and deterministic engine. | Scenario | Profile | PASS | FAIL | MISSING | WARNING | Validation boundary | | --- | --- | ---: | ---: | ---: | ---: | --- | | Northstar | Mixed risk | 3 | 2 | 1 | 1 | Deterministic now; historical live GPT-5.6 evidence | | Meridian | Complete, below threshold | 7 | 0 | 0 | 0 | Deterministic and mocked | | Atlas | Evidence deficient | 4 | 1 | 2 | 0 | Deterministic and mocked | Expected fixture outcomes are test assertions. Displayed results are calculated at runtime. See the [scenario validation matrix](docs/evaluation/SCENARIO_VALIDATION_MATRIX.md). ## Review Fingerprint `policyproof.review-fingerprint.v1` is a lowercase SHA-256 digest of canonical semantic review content: policy, enabled controls and parameters, controlled documents and facts, exact evidence references, and deterministic conclusions. Same semantic inputs reproduce the same fingerprint. Human decisions, comments, language, audit events, receipt identifiers, and timestamps are excluded. The Review Fingerprint is not a digital signature, identity proof, authorship proof, or trusted timestamp. See the [Review Fingerprint model](docs/REVIEW_FINGERPRINT_MODEL.md). ## Receipt Integrity `policyproof.receipt-integrity.v1` protects one exact `policyproof.decision-receipt.v1` instance, including the Review Fingerprint, human decisions, comments, safe audit events, receipt identifier, language, and generation time. Current or exported JSON receipts can be checked entirely in the browser. The integrity check confirms that the receipt content matches its recorded hash. Because the hash is not digitally signed, it does not establish origin, identity, authorship, authenticity or trusted time. Someone who can replace both the content and hash can create a new internally consistent pair. See the [Verifiable Receipt model](docs/VERIFIABLE_RECEIPT_MODEL.md). ## Competition Evaluation Harness `pnpm eval:competition` exercises the production scenario schemas and shared engine without a browser or provider. Its deterministic report covers: - 3 of 3 scenarios; - 21 of 21 controlled conclusions; - 34 controlled evidence references; - exact excerpt and evidence-to-control validation; - scenario isolation and deterministic reproduction; - threshold sensitivity and Review Fingerprints; - Receipt Integrity and modification detection; - 7 of 7 isolated business-rule mutations; - 10 of 10 named adversarial boundaries; - zero attempted external calls under its scoped network guard. The harness distinguishes execute [README truncated for size] ## Detected evidence (automated analysis) Indexed codebase: 180 recognized source files, 3825 KB. - CSS (language) — detected in the code - HTML (language) — detected in the code - Next.js (technology) — detected in the code - OpenAI (technology) — detected in the code - React (technology) — detected in the code - Tailwind CSS (technology) — detected in the code - TypeScript (language) — detected in the code - Vercel (technology) — claimed on Devpost, not found in the code - AI coding agent: Codex — evidence: config files committed to the repository ## Codebase structure (from repository index) ### Files (120 of 197) ``` .env.example .github/workflows/ci.yml .gitignore .nvmrc AGENTS.md app/api/ai/analyze/route.ts app/api/ai/policy/route.ts app/api/ai/status/route.ts app/globals.css app/layout.tsx app/page.tsx CHANGELOG.md components/brand/brand-logo.tsx components/demo-review-workspace.tsx components/workspace/app-header.tsx components/workspace/case-library.tsx components/workspace/competition-tools.tsx components/workspace/controls-panel.tsx components/workspace/decision-panel.tsx components/workspace/documents-panel.tsx components/workspace/focused-demo.tsx components/workspace/guided-demo.tsx components/workspace/intro-panel.tsx components/workspace/policy-panel.tsx components/workspace/presentation.ts components/workspace/receipt-integrity-panel.tsx components/workspace/review-fingerprint-panel.tsx components/workspace/review-intelligence-panels.tsx components/workspace/review-panel.tsx components/workspace/section-shell.tsx components/workspace/status-badge.tsx components/workspace/step-navigation.tsx components/workspace/types.ts components/workspace/workspace-summary.tsx DECISIONS.md docs/ADVERSARIAL_TEST_MATRIX.md docs/ARCHITECTURE.md docs/BUSINESS_RULE_MUTATION_MATRIX.md docs/CODEX_AND_GPT56_USAGE.md docs/DATA_DICTIONARY.md docs/DEPLOYMENT.md docs/design/FINAL_COPY_STYLE_GUIDE.md docs/design/FINAL_HUMAN_PRODUCT_AUDIT.md docs/design/FOCUSED_VERIFIABILITY_AUDIT.md docs/design/proofroom-ui/CODEX_IMPLEMENTATION_PLAN.md docs/design/proofroom-ui/COMPONENT_INVENTORY.md docs/design/proofroom-ui/DESIGN_HANDOFF.md docs/design/proofroom-ui/DESIGN_TOKENS.md docs/design/proofroom-ui/IMPLEMENTATION_MAPPING.md docs/design/proofroom-ui/MOTION_SPEC.md docs/design/proofroom-ui/PolicyProof-App.html docs/design/proofroom-ui/Proofroom-Boards.html docs/design/proofroom-ui/README_DESIGN_PACKAGE.md docs/design/proofroom-ui/RESPONSIVE_SPEC.md docs/design/proofroom-ui/VISUAL_VALIDATION.md docs/design/REVIEW_INTELLIGENCE_AUDIT.md docs/design/UI_AUDIT.md docs/EVALUATION_HARNESS.md docs/evaluation/COMPETITION_EVALUATION_REPORT.md docs/evaluation/competition-evaluation-report.json docs/evaluation/LIVE_GPT56_VALIDATION.md docs/evaluation/PERFORMANCE_AND_RUNTIME_CHECK.md docs/evaluation/SCENARIO_VALIDATION_MATRIX.md docs/FEATURE_GUIDE.md docs/PRODUCT_NARRATIVE.md docs/progress/AUTONOMOUS_REVIEW_INTELLIGENCE_LOG.md docs/progress/BUILD_WEEK_RELEASE_PHASE_LOG.md docs/progress/COMPETITION_EVALUATION_PHASE_LOG.md docs/progress/COMPETITION_HARDENING_LOG.md docs/progress/FOCUSED_VERIFIABILITY_PHASE_1_LOG.md docs/progress/VERIFIABLE_RECEIPT_PHASE_LOG.md docs/release/ACCESSIBILITY_RELEASE_CHECKLIST.md docs/release/CLEAN_ROOM_VERIFICATION.md docs/release/CODE_FREEZE.md docs/release/PRODUCTION_DEPLOYMENT_RUNBOOK.md docs/release/RELEASE_MANIFEST.md docs/REVIEW_FINGERPRINT_MODEL.md docs/SECURITY_AND_LIMITATIONS.md docs/submission/DEMO_RUNBOOK.md docs/submission/DEMO_SCRIPT.md docs/submission/DEVPOST_DRAFT.md docs/submission/DEVPOST_FINAL_DRAFT.md docs/submission/FINAL_SUBMISSION_CHECKLIST.md docs/submission/JUDGE_QA.md docs/submission/LICENSE_RECOMMENDATION.md docs/submission/REPOSITORY_REVIEW.md docs/submission/SCREENSHOT_PLAN.md docs/submission/SHOT_LIST.md docs/submission/SUBMISSION_CHECKLIST.md docs/submission/VIDEO_SCRIPT_FINAL.md docs/USER_GUIDE.md docs/VERIFIABLE_RECEIPT_MODEL.md eslint.config.mjs LICENSE next-env.d.ts next.config.ts package.json PLAN.md playwright.config.ts pnpm-workspace.yaml postcss.config.mjs PRODUCT.md public/brand/site.webmanifest README.md scripts/check-doc-links.mjs scripts/check-human-copy.mjs scripts/check-release-hygiene.mjs scripts/clean-room-verify.mjs scripts/live-gpt56-final-analysis.ts scripts/print-demo-verification.mjs scripts/release-verify.mjs scripts/run-next.mjs SECURITY.md src/domain/ai-schemas.ts src/domain/control-references.ts src/domain/review-fingerprint-schema.ts src/domain/scenario-schema.ts src/domain/schemas.ts src/evaluation/adversarial-corpus.ts src/evaluation/business-rule-mutations.ts [77 more files omitted for size] ``` ### Dependencies - package.json: @playwright/test@1.61.1, @tailwindcss/postcss@4.3.2, @testing-library/dom@10.4.1, @testing-library/react@16.3.2, @testing-library/user-event@14.6.1, @types/node@26.1.1, @types/react@19.2.17, @types/react-dom@19.2.3, eslint@9.39.5, eslint-config-next@16.2.10, jsdom@29.1.1, next@16.2.10, openai@6.46.0, react@19.2.7, react-dom@19.2.7, tailwindcss@4.3.2, typescript@6.0.3, vitest@4.1.10, zod@4.4.3 ### Recent commits (newest first) - docs: align verified test counts - chore: ignore generated lint artifacts - test: align current release test count - docs: align final test counts - test: normalize release text line endings - feat: improve evidence context and review clarity - style: improve final PolicyProof presentation - style: integrate final PolicyProof brand - fix: resolve final publication blockers - test: validate final product polish - style: refine PolicyProof judge experience - refactor: humanize PolicyProof product copy - docs: finalize Build Week submission package - ci: add reproducible release verification - chore: prepare PolicyProof public release - docs: finalize PolicyProof verification workflow - test: add business rule mutation and adversarial coverage - feat: add PolicyProof competition evaluation harness - test: harden receipt integrity workflow - feat: add verifiable decision receipt ## Key source files (fetched from GitHub, selected and truncated for size) ### CHANGELOG.md ```markdown # Changelog All notable repository milestones are summarized here. PolicyProof remains a focused Build Week prototype for one controlled procurement-policy domain. ## Build Week 2026 release candidate - Added a policy-to-control workflow with explicit human approval of proposed controls. - Added a shared deterministic TypeScript review engine for Northstar, Meridian, and Atlas. - Added exact evidence references for every controlled conclusion, including explicit missing evidence. - Added the versioned `policyproof.review-fingerprint.v1` Review Fingerprint. - Added locally verifiable decision receipts using `policyproof.receipt-integrity.v1`. - Added Focused Demo and Full Workspace presentations over the same review state. - Added the deterministic Competition Evaluation Harness for 3 scenarios and 21 conclusions. - Added seven isolated business-rule mutations and ten named adversarial boundary cases. - Added `pnpm demo:verify` for provider-free technical verification. Historical live GPT-5.6 evidence applies to Northstar only and is documented separately. This release does not claim universal policy coverage, legal certification, identity proof, or a digitally signed receipt. ``` ### AGENTS.md ```markdown # PolicyProof Repository Instructions ## Project context PolicyProof is a solo OpenAI Build Week 2026 submission for the Work & Productivity track. It converts a written procurement policy into reviewable controls, evaluates one fictional document-based business case, and shows evidence for every result. This repository must remain understandable to a first-time application builder and easy for hackathon judges to run and test. ## Communication - Explain technical concepts and actions to the builder in clear French. - Write code, filenames, documentation, UI copy, commit messages, and submission materials in English. - Do not assume prior software development experience. - After every important change, provide exact verification steps. ## Working method - Inspect the existing project before modifying it. - State a brief plan before substantial work. - Keep most core development in the primary Codex thread. - Prefer a narrow, reliable, end-to-end workflow over extra features. - Document major product and engineering decisions in `DECISIONS.md` before or with the related change. - Add and run relevant tests after each important implementation. - Never claim that something works unless it has been tested. - Report errors, limitations, and uncertainty honestly. ## Safety and scope - Work only inside this repository unless the builder explicitly approves otherwise. - Never request, display, log, or commit API keys, tokens, passwords, personal data, or confidential business documents. - Use fictional demonstration data only. - Do not enable full computer access. - Do not run destructive Git or filesystem commands without explicit approval. - Do not delete or overwrite substantial work without first explaining the consequences. - Do not add authentication, payments, ERP integrations, multi-tenancy, unnecessary databases, or multi-agent application architecture. - Avoid unnecessary dependencies and fake functionality. ## Product constraints - The working product must meaningfully use GPT-5.6. - The initial prototype covers one fictional procurement and vendor-change case only. - A human must be able to review controls and confirm or override the final review. - Every Pass, Fail, Missing, or Warning result must include traceable supporting or contradictory evidence, or an explicit explanation that evidence is missing. - The final application must be functional, testable, deployed, and documented in English. ## Verification expectations Before handing off an important change: 1. Run the relevant automated checks. 2. Perform the documented manual check when UI or model behavior changed. 3. Report exactly which checks passed, failed, or were not run. 4. Update `TESTING.md` when the verification process changes. ``` ### package.json ``` { "name": "policyproof", "version": "0.1.0", "private": true, "license": "MIT", "packageManager": "pnpm@11.9.0", "engines": { "node": ">=24.0.0" }, "scripts": { "dev": "node scripts/run-next.mjs dev", "build": "node scripts/run-next.mjs build", "start": "node scripts/run-next.mjs start", "lint": "eslint .", "typecheck": "tsc --noEmit", "test": "vitest run", "test:watch": "vitest", "test:e2e": "playwright test", "eval:competition": "vitest run tests/evaluation/competition-evaluation.cli.test.ts --reporter=dot", "demo:verify": "pnpm eval:competition && vitest run tests/evaluation/competition-evaluation.test.ts tests/evaluation/business-rule-mutations.test.ts tests/evaluation/adversarial-corpus.test.ts --reporter=dot && tsc --noEmit && node scripts/print-demo-verification.mjs", "release:docs": "node scripts/check-doc-links.mjs", "release:hygiene": "node scripts/check-release-hygiene.mjs", "release:copy": "node scripts/check-human-copy.mjs", "release:clean-room": "node scripts/clean-room-verify.mjs", "release:verify": "node scripts/release-verify.mjs" }, "dependencies": { "next": "16.2.10", "openai": "6.46.0", "react": "19.2.7", "react-dom": "19.2.7", "zod": "4.4.3" }, "devDependencies": { "@tailwindcss/postcss": "4.3.2", "@playwright/test": "1.61.1", "@testing-library/dom": "10.4.1", "@testing-library/react": "16.3.2", "@testing-library/user-event": "14.6.1", "@types/node": "26.1.1", "@types/react": "19.2.17", "@types/react-dom": "19.2.3", "eslint": "9.39.5", "eslint-config-next": "16.2.10", "jsdom": "29.1.1", "tailwindcss": "4.3.2", "typescript": "6.0.3", "vitest": "4.1.10" } } ``` ### app/page.tsx ```typescript import { DemoReviewWorkspace } from "@/components/demo-review-workspace"; import { LocaleProvider } from "@/src/i18n/locale-context"; export default function Home() { return ( ); } ``` ### app/layout.tsx ```typescript import type { Metadata } from "next"; import "./globals.css"; const metadataBase = new URL( process.env.VERCEL_PROJECT_PRODUCTION_URL ? `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}` : "http://localhost:3000", ); export const metadata: Metadata = { metadataBase, title: "PolicyProof — Evidence-led control review", description: "Turn written policies into reviewable controls and inspect the exact evidence behind every conclusion.", icons: { icon: [ { url: "/brand/favicon.svg", type: "image/svg+xml" }, { url: "/brand/favicon-32x32.png", sizes: "32x32", type: "image/png" }, { url: "/brand/favicon-16x16.png", sizes: "16x16", type: "image/png" }, { url: "/brand/favicon.ico", sizes: "64x64" }, ], apple: [{ url: "/brand/apple-touch-icon.png", sizes: "180x180", type: "image/png" }], }, manifest: "/brand/site.webmanifest", openGraph: { title: "PolicyProof — Evidence-led control review", description: "Turn written policies into reviewable controls and inspect the exact evidence behind every conclusion.", images: [ { url: "/brand/policyproof-social-preview-1200x630.png", width: 1200, height: 630, alt: "PolicyProof", }, ], }, }; export default function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) { return ( {children} ); } ``` ### src/fixtures/scenarios/index.ts ```typescript import type { ReviewScenario } from "@/src/domain/scenario-schema"; import { atlasScenario } from "@/src/fixtures/scenarios/atlas"; import { meridianScenario } from "@/src/fixtures/scenarios/meridian"; import { northstarScenario } from "@/src/fixtures/scenarios/northstar"; export const reviewScenarios: readonly ReviewScenario[] = [northstarScenario, meridianScenario, atlasScenario]; export const defaultScenarioId = northstarScenario.id; export { atlasScenario, meridianScenario, northstarScenario }; ``` ### app/api/ai/status/route.ts ```typescript import { isOpenAIConfigured } from "@/src/openai/client"; import { OPENAI_MODEL } from "@/src/openai/config"; export const runtime = "nodejs"; export const dynamic = "force-dynamic"; export function GET() { return Response.json({ available: isOpenAIConfigured(), model: OPENAI_MODEL }); } ``` ### app/api/ai/analyze/route.ts ```typescript import { createCaseAnalysisHandler } from "@/src/openai/api-handlers"; import { analyzeCaseWithOpenAI } from "@/src/openai/case-analyzer"; import { getOpenAIClient, isOpenAIConfigured } from "@/src/openai/client"; export const runtime = "nodejs"; export const POST = createCaseAnalysisHandler({ isConfigured: isOpenAIConfigured, analyze: (request) => analyzeCaseWithOpenAI(getOpenAIClient(), request), }); ``` ### app/api/ai/policy/route.ts ```typescript import { createPolicyCompilationHandler } from "@/src/openai/api-handlers"; import { getOpenAIClient, isOpenAIConfigured } from "@/src/openai/client"; import { compilePolicyWithOpenAI } from "@/src/openai/policy-compiler"; export const runtime = "nodejs"; export const POST = createPolicyCompilationHandler({ isConfigured: isOpenAIConfigured, compile: (policyText) => compilePolicyWithOpenAI(getOpenAIClient(), policyText), }); ``` ### pnpm-workspace.yaml ```yaml allowBuilds: sharp: true unrs-resolver: true minimumReleaseAgeExclude: - postcss@8.5.19 overrides: postcss: 8.5.19 ``` [166 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]