ContractGuard AI

ContractGuard AI is a VS Code extension that treats Markdown requirements as a software contract and compiles them into development artifacts while reviewing the relationship between requirements, architecture, and the existing codebase.

What it does

• Markdown requirements as the source of truth
• AI-assisted ambiguity and conflict detection
• Missing-constraint and validation-gap detection
• TypeScript type generation
• SQL schema generation
• OpenAPI generation
• Jest test generation
• Requirement traceability
• Architecture and technology recommendations with trade-offs
• Requirement-to-code drift detection
• Change-impact analysis across likely affected areas/files
• Persistent requirement snapshots so later compilations can compare changes
• VS Code diagnostics for requirement issues
• Dashboard sidebar
• Optional automatic compilation

Generated reports

Every compile writes a contractguard-generated/ directory containing the generated artifacts plus:

• architecture-advice.md - suggested stack or architecture improvements and trade-offs
• drift-report.md - evidence-based requirement-to-code alignment/drift findings
• change-impact.md - likely affected areas and suggested changes when requirements change
• requirements.snapshot.json - the previous requirement baseline used for the next compile

JSON versions of the analysis reports are also generated.

Setup

1. Install Node.js 18+.
2. Run npm install.
3. Run npm run compile.
4. Open this folder in VS Code.
5. Press F5 to launch the Extension Development Host.
6. In the new VS Code window run ContractGuard: Configure OpenRouter API Key.
7. Open a .md requirements file and make sure the Markdown editor is active.
8. Run ContractGuard: Compile Specification.

The API key is stored in VS Code SecretStorage and is not written into the workspace. Project files sent for analysis are limited to a small source snapshot and obvious API-key/password patterns are redacted before the snapshot is sent.

How the new analysis works

Architecture Advisor

ContractGuard inspects the requirements and a limited project snapshot. It may recommend keeping the current stack or considering an alternative database, framework, language, API approach, testing tool, security approach, or deployment pattern. Recommendations include rationale, trade-offs, and expected impact. The extension does not automatically change the stack.

Requirement-to-Code Drift

ContractGuard compares requirements with the source snapshot. A requirement is reported as drift only when the supplied project context contains evidence that implementation does not match it. When the evidence is insufficient, the status is unknown instead of a guess.

Change Impact

On each compile ContractGuard loads requirements.snapshot.json from the previous compile and compares it with the current requirements. The AI then identifies likely affected areas and files such as API, database, backend, frontend, tests, and documentation.

Example

Create requirements.md:

# Student Room Booking

Students can book available rooms.

A booking must contain:
- Student ID
- Room ID
- Date
- Start time
- End time

A room cannot have two bookings at the same time.

Only authenticated students can create bookings.

Run Compile Specification. Generated files appear under contractguard-generated/.

Notes

The source Markdown remains the authoritative input. Generated code and recommendations should be reviewed before production use.