ScopeGuard

Deterministic code firewall that isolates and purges silent AI regressions in milliseconds.

Comment

Inspiration

We love using AI coding assistants (Claude Code, Cursor, Copilot). They write impressive code with incredible speed, but they introduce a dangerous, hidden failure mode: AI Collateral Damage.

You ask an AI assistant to make a simple, localized tweak—like formatting a currency string in checkout. It does that, but it secretly deletes an existing production try/catch error boundary, wipes out a payment timeout, or breaks a responsive dashboard grid. You don't notice it until things crash in production at 2:00 AM.

We realized that the real bottleneck in AI software development isn't generating code faster—it's guarding against the silent regressions that AI assistants introduce behind our backs. We built ScopeGuard to be the visual safety net and automated pre-commit firewall that catches those mistakes in milliseconds.

What it does

ScopeGuard is an in-browser code firewall and surgical reconstruction engine that enforces strict semantic boundaries between what the developer asked for and what the AI actually changed.

  • Real-time Concordance Telemetry: ScopeGuard compares developer prompt intent against uncommitted git diffs, calculating a live Semantic Concordance Score.
  • Silent Regression Radar: Pinpoints exact enclosing symbols (function processOrder(), rule .dashboard-grid), impact summaries, and deleted safety invariants (try/catch, auth tokens, timeouts).
  • 1-Click Surgical Purge: Instead of manually rewriting broken code, developers click "Purge Regressions". ScopeGuard surgically excises the unrequested mutations while preserving authorized agent work byte-for-byte, restoring code to 100% purity.
  • Offline & Instant: Runs 100% locally in the browser or terminal with sub-5ms lexical analysis. Zero cloud API calls, zero token costs, and zero private code leakage.
  • Git Pre-Commit Firewall: Installs into .git/hooks/pre-commit to prevent corrupted AI diffs from ever entering the git history.

How we built it

We built ScopeGuard using TypeScript 5.5, Vite, and Vitest, adhering to strict clean-code architecture:

  • Myers LCS Diff Engine (src/engine/differ.ts): Groups modified lines into contiguous hunks with exact line mapping.
  • Structural Symbol Resolver (src/engine/astScanner.ts): Identifies the enclosing class, function, or CSS scope of every modification.
  • Lexical Invariant Classifier (src/engine/classifier.ts): Tokenizes developer prompts and flags stripped error handlers, deleted security tokens, and layout drift.
  • Non-Destructive Splicer (src/engine/splicer.ts): Reconstructs working source code byte-for-byte, battle-tested across 20 adversarial edge cases.
  • Tactile Sensory UX: Deep Obsidian Bento chassis (#040810), Web Audio 60Hz mechanical sub-bass frequency synthesis, laser-sweep scanline animations, and HTML5 canvas particle feedback upon milestone completion.
  • Automated Test Fortress: 137 unit and adversarial tests passing with 100% green coverage across 12 test suites.

Challenges we ran into

  1. Handling Pathological Diffs: Edge cases like Windows CRLF vs. Unix LF line endings, out-of-order hunk arrays, and non-ASCII Unicode emojis could corrupt byte offsets during splicing. We wrote a dedicated 20-test adversarial torture suite (tests/pillar3_splicer.test.ts) to prove non-destructive byte fidelity.
  2. Preventing False Alarms: A naive keyword matcher flags legitimate updates when prompts contain related words. We engineered strict invariant precedence rules so that intentional deletions require explicit prompt commands, while preserving authorized refactors.
  3. Concurrency & Git Locks: Running automated pre-commit audits against active repositories risked lockfile contention (.git/index.lock). We stress-tested synthetic lock states to ensure the CLI reports clear diagnostics without crashing.

Accomplishments that we're proud of

  • Achieving sub-5ms deterministic analysis running entirely in-memory with zero external LLM API dependencies.
  • Building a complete, tactile consumer-grade developer interface with real Web Audio frequency synthesis and particle physics.
  • Reaching 137 out of 137 passing automated tests verifying every mathematical and splicing claim with zero failures.

What we learned

We learned that deterministic, AST-based rule engines are dramatically faster, more reliable, and significantly cheaper than re-prompting an LLM to review its own mistakes. AI is great for generative creation, but deterministic code analysis is essential for safety.

What's next for ScopeGuard

  • Publishing npx scopeguard to the global npm registry.
  • Expanding the Model Context Protocol (MCP) server for native IDE integration in Cursor, VS Code, and GitLab Web IDE.
  • Adding whole-codebase cross-file dependency graph resolution to catch regressions spanning multiple files.

Devpost Learn Skill Pack

Yes. ScopeGuard was planned and constructed directly using the Devpost Learn spec-driven workflow. The public repository includes all four generated planning artifacts: devpost/scope.md, devpost/prd.md, devpost/spec.md, and devpost/checklist.md.

Built With

Share this project:

Updates

Submission history