MilestoneProof: Verifying Subcontractor Deliverables Against SOW Acceptance Criteria with Open-Weight AI

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

What I Built

MilestoneProof is an automated milestone audit engine designed for boutique software agencies, solo founders, and technical leads who outsource code deliverables to subcontractors on platforms like Upwork, Contra, or direct contract agreements.

When a contractor submits a milestone for review, project leads face three critical problems:

1. Inspection Overhead: Manually checking dozens of source files against a Statement of Work (SOW) to confirm that acceptance criteria are actually met consumes substantial unbilled engineering attention.
2. Incomplete Delivery Risk: Subcontractors sometimes overlook critical requirements—such as omitting cryptographic signature verification on webhooks or writing minimal happy-path tests. If accepted without inspection, the hiring developer inherits technical debt and unbilled rework.
3. Subjective Communication Friction: Flagging missing deliverables without concrete, line-level evidence can feel confrontational.

Who would pay for it?
Boutique agency owners, fractional CTOs, and freelance technical leads. Catching a single incomplete deliverable before releasing milestone payment prevents hundreds of dollars in unbilled remediation, while automated AST triage highlights implemented functions and routes immediately so reviewers can jump directly to missing requirements.

MilestoneProof produces:

• An Evidence-Linked Traceability Matrix mapping each SOW requirement to verified files, functions, and lines on disk, with transparent evaluator attribution (AI_MODEL, DETERMINISTIC_ENGINE, or DETERMINISTIC_FALLBACK).
• An Informative Scope Valuation Reference calculating a proportional completion score based on weighted criteria (leaving final approval decisions to the human lead).
• A Collaborative Contractor Review Letter citing exact files and lines with polite, actionable remediation steps.
• Exportable Audit Dossiers in Markdown and HTML.

Demo

• 🌐 Live Web Application: https://milestoneproof.onrender.com/

How to Try It in 1 Click:

1. Open the live app at https://milestoneproof.onrender.com/.
2. Click "Load Demo SOW" in the top header to load a sample $2,500 milestone contract (Authentication & Stripe Webhooks).
3. Ensure "Use bundled benchmark deliverable" is checked (or upload your own deliverable .zip), and click "Run Milestone Audit".
4. Review the generated Traceability Matrix, Proportional Scope Valuation, and Contractor Review Draft.

Screenshots

1. SOW Input & Codebase Upload Workspace:

2. Evidence-Linked Traceability Matrix & Findings:

Code

• 💻 GitHub Repository: https://github.com/ayushg-1506/milestoneproof
• 📜 License: MIT Open Source

The repository is built with Python 3.10+, Flask, and native Abstract Syntax Tree (ast) inspection, with 28 automated unit and integration tests passing.

How I Built It

MilestoneProof combines deterministic code parsing with an open-weight model integration layer:

1. Secure ZIP Ingestion & Sandboxing (app.py): Accepts deliverable .zip archives directly in the browser, enforces Zip Slip validation to block path traversal, and unpacks files into an isolated temporary directory cleaned up immediately after the audit.
2. Deterministic AST Scanner (ast_scanner.py): Parses deliverable files using Python's native ast module to extract exact functions, classes, decorators (e.g., @app.get, @app.post), and test assertions, mapping every citation to an exact (file_path, line_start, line_end) tuple verified on disk.
3. Open-Weight Model Connector & Deterministic Engine (llm_engine.py): Architected to connect via environment variables (MODEL_API_BASE, MODEL_API_KEY, MODEL_NAME) to any OpenAI-compatible open-weight inference provider (Groq, Hugging Face Serverless, OpenRouter) or local Ollama.
   • Honest AI Status: The application defaults to 100% deterministic analysis out of the box with zero API keys or model downloads required. Live open-weight model inference is an optional architectural integration that has not been verified on this deployment due to local memory constraints and absent external API credentials; all demonstrated benchmark findings were generated by the deterministic AST engine.
   • Transparent Attribution: Findings are explicitly labeled (DETERMINISTIC_ENGINE, AI_MODEL, or DETERMINISTIC_FALLBACK) so heuristic results are never misattributed as AI output.

Why Does Open Innovation Matter?

1. Client Confidentiality & NDA Protection: Contract deliverables and client Statements of Work frequently contain proprietary business logic and trade secrets. Routing private codebases to closed, multi-tenant commercial LLM APIs can violate client agreements. Open-weight models (Llama 3.2, Gemma 2, Qwen 2.5) self-hosted or run on dedicated endpoints keep data strictly within authorized boundaries.
2. Evidence-Grounded Verification: Pairing open-source code parsers with model evaluation grounds analysis in concrete line numbers and symbols on disk, preventing free-form model hallucinations.
3. Zero Vendor Lock-In: Users can run completely offline with deterministic rules or swap open-weight model providers via environment variables without rewriting application logic.

Prize Categories

Best Use of Render ($200)

MilestoneProof is packaged for production on Render:

• 1-Click Blueprint (render.yaml): Declarative infrastructure deploying directly on Render's Python web service runtime with zero manual configuration.
• Free-Tier Design: Built specifically for Render's plan: free tier with zero mandatory paid dependencies or database requirements.
• Production Server: Uses gunicorn with 2 worker processes binding dynamically to 0.0.0.0:$PORT.
• Automated Health Checks: Monitored via /api/health for zero-downtime deploys.
• Safe Ephemeral Cleanup: Uploaded archives are processed in ephemeral sandboxes and immediately released to respect Render container memory limits.