ScopeShield：為自由工作者而設的開源範圍蔓延偵測器

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

What I Built

Freelancers and boutique digital agencies bleed revenue through "death by a thousand cuts"—incremental scope creep. A client rarely breaches a contract explicitly; instead, they ask for "one more quick revision," "a secondary blog page," or "just a tiny change before launch." Checking a dense 20-page Master Services Agreement (MSA) during a fast-paced Slack exchange takes too much time, and pushing back carries emotional friction.

ScopeShield turns a static PDF contract into an active, deterministic reference engine. You upload your signed agreement and paste the client's latest email. ScopeShield decomposes the message into atomic asks, evaluates them against the contract, and returns a verified verdict (In Scope, Out of Scope, or Ambiguous). It then drafts a calibrated, polite change-request email that quotes the exact contract clauses to defend your boundaries.

The Business Case: Freelance designers, developers, and copywriters would happily pay a $9/month subscription or a $99 lifetime deal for this. It acts as an automated project manager, directly saving them unbilled hours and eliminating the anxiety of writing "no" to a client.

Demo

Live App: https://scopeshield-app.onrender.com (Hosted on Render)
Video Walkthrough: [YouTube Link]

Code

ScopeShield

Protect your scope. Preserve your client relationships.

ScopeShield analyzes client requests against a signed contract. A self-hosted Gemma model proposes typed atomic asks; a Mastra workflow orchestrates the analysis; strict Zod schemas validate it; and deterministic TypeScript verifies every citation and scope rule before a response is drafted.

Run locally

npm install
cp .env.example .env.local
npm run dev

The default mock mode is deterministic and requires no API credentials. Select a sample contract or paste canonical contract text, paste a client request, and analyze it at http://localhost:3000.

The API accepts either the sample-contract shape:

{ "contractId": "software-msa", "message": "Could we add a mobile app?", "tone": "neutral" }

or raw contract text:

{ "contractText": "1. Services\nBuild the web application.", "clientMessage": "Could we add a mobile app?", "tone": 

…

How I Built It

ScopeShield is built strictly around Google Gemma 4 (running locally via Ollama) and orchestrated by Mastra. The Next.js 16 (App Router) frontend is hosted on Render.

Instead of relying purely on an LLM's inherently flawed reasoning for legal checks, I built a hybrid architecture:

1. Typed Orchestration: A Mastra workflow ingests the PDF via unpdf and segments it into numbered clauses.
2. Decomposition: Gemma 4 breaks the client's email into individual tasks and proposes a verdict and a supporting contract quote, validated via Zod schemas.
3. The Anti-Hallucination Gate: This is the core innovation. A deterministic TypeScript function takes the model's generated quote and performs an exact normalized substring match against the ground-truth contract. If the model hallucinated the citation or the text isn't a 100% match, the verdict is forcibly downgraded to AMBIGUOUS and flags a prominent Lucide ShieldAlert warning.
4. Drafting: Mastra triggers a second Gemma pass to draft the email, strictly limiting its context to only the citations that passed deterministic verification.

To keep my hackathon budget at exactly $0, I deployed the Next.js/Mastra app to Render's Free Tier and exposed my local Ollama instance (running gemma2) to the cloud using a free Cloudflare Tunnel.

Why Does Open Innovation Matter?

Open innovation is the only reason ScopeShield can exist as a viable business.

1. NDA & Privacy Compliance: Client proposals, commercial trade agreements, and hourly billing rates are bound by strict non-disclosure obligations. Sending this data to closed, proprietary APIs creates massive third-party data-leakage liabilities. Using an open-weight model like Gemma guarantees that intellectual property never leaves developer-controlled infrastructure.
2. Zero Marginal Cost: Scope checking is a high-frequency, low-margin utility. If I had to pay per-token cloud API fees for every 10,000-token MSA evaluation, the $9/month micro-SaaS margins would evaporate. Running an open model on fixed-cost infrastructure (or directly on a local machine) makes the unit economics of this side hustle actually work.
3. No RAG Fragility: Standard independent contractor agreements fit perfectly inside Gemma 4's context window. I didn't have to build brittle vector databases or chunking logic that might accidentally split a crucial legal clause in half.

My First User

I shared the local build with a freelance UI/UX designer friend who constantly battles "one last revision" requests. They uploaded an active Statement of Work and pasted a real client email asking for a "quick interactive payment calculator."

ScopeShield correctly flagged it as an explicit exclusion (Custom Backend Code), verified the citation, and generated a firm "Out of Scope" response with a placeholder for a separate hourly estimate. They loved the ShieldAlert confidence system and mentioned that having a neutral "robot" point out the contract boundaries completely removed their usual anxiety about pushing back.

Prize Categories

• Best Use of Render: Next.js application, Mastra orchestration, and API routes hosted seamlessly on Render.
• Best Use of Gemma: Utilized Gemma 4 for atomic task extraction and tone-calibrated drafting, demonstrating its power in processing large, complex legal contexts.
• Best Use of Mastra: Orchestrated the entire multi-step pipeline (Extract -> Verify -> Draft) using Mastra workflows with strict Zod schema enforcement.
• Best Use of Entire: Recorded and published the agent reasoning sessions behind the deterministic architecture.
• Best Use of GitHub Copilot: Used Copilot to accelerate the Zod schemas, UI scaffolding, and unit test generation for the verification engine.