ecisions & Rationale

• Markdown over YAML/JSON: Markdown is universally parseable, human-readable, and natively supported by all AI coding agents. It avoids schema validation overhead while maintaining structure.
• Root Location: Placing the artifact at the repository root ensures immediate context injection. Agents scanning the workspace will encounter it first.
• Explicit Metadata Headers: Fields like LAST_REVIEWED and REVIEW_TRIGGER prevent silent drift. They force lifecycle management.
• Scoped Addenda: Domain-specific contracts (ASSETS.CONTRACT.md, AUTH.CONTRACT.md) emerge only when local invariants become dense. This preserves root readability.

Implementation Example (TypeScript)

The following example demonstrates a lightweight invariant parser and validator. It reads a root constraint file, extracts structured rules, and provides a runtime guard for agentic workflows.

import fs from 'fs';
import path from 'path';

interface InvariantRule {
  category: string;
  constraint: string;
  enforcement: 'strict' | 'warning';
}

interface InvariantManifest {
  scope: string;
  lastReviewed: string;
  reviewTrigger: string;
  rules: InvariantRule[];
  boundaries: Record<string, string[]>;
}

export class InvariantParser {
  private manifestPath: string;

  constructor(rootDir: string) {
    this.manifestPath = path.join(rootDir, 'SYSTEM.CONTRACT.md');
  }

  parse(): InvariantManifest {
    const raw = fs.readFileSync(this.manifestPath, 'utf-8');
    const lines = raw.split('\n');

    const manifest: InvariantManifest = {
      scope: '',
      lastReviewed: '',
      reviewTrigger: '',
      rules: [],
      boundaries: {}
    };

    let currentCategory = '';
    let inBoundaries = false;

    for (const line of lines) {
      const trimmed = line.trim();

      if (trimmed.startsWith('SCOPE:')) {
        manifest.scope = trimmed.replace('SCOPE:', '').trim();
      } else if (trimmed.startsWith('LAST_REVIEWED:')) {
        manifest.lastReviewed = trimmed.replace('LAST_REVIEWED:', '').trim();
      } else if (trimmed.startsWith('REVIEW_TRIGGER:')) {
        manifest.reviewTrigger = trimmed.replace('REVIEW_TRIGGER:', '').trim();
      } else if (trimmed.startsWith('## BOUNDARIES')) {
        inBoundaries = true;
        currentCategory = '';
      } else if (trimmed.startsWith('## RULES')) {
        inBoundaries = false;
      } else if (trimmed.startsWith('### ')) {
        currentCategory = trimmed.replace('### ', '').trim();
        if (!manifest.boundaries[currentCategory]) {
          manifest.boundaries[currentCategory] = [];
        }
      } else if (inBoundaries && trimmed.startsWith('- ')) {
        manifest.boundaries[currentCategory]?.push(trimmed.replace('- ', ''));
      } else if (trimmed.startsWith('|') && trimmed.includes('|')) {
        const cells = trimmed.split('|').map(c => c.trim()).filter(Boolean);
        if (cells.length >= 2 && !cells[0].includes('---')) {
          manifest.rules.push({
            category: currentCategory || 'general',
            constraint: `${cells[0]} → ${cells[1]}`,
            enforcement: 'strict'
          });
        }
      }
    }

    return manifest;
  }

  validateRoute(route: string, manifest: InvariantManifest): boolean {
    const allowed = manifest.boundaries['URL Structure'] || [];
    return allowed.some(pattern => {
      const regex = new RegExp(`^${pattern.replace(/:\w+/g, '[^/]+')}$`);
      return regex.test(route);
    });
  }
}

This parser extracts structured constraints from the markdown file, builds a runtime manifest, and provides a validation method for route checking. The design prioritizes simplicity over heavy schema validation, aligning with how AI agents consume context. The validateRoute method demonstrates how invariant rules can be enforced programmatically during scaffolding or migration tasks.

Pitfall Guide

1. Root Document Bloat

Explanation: Teams dump every constraint into the root file, including domain-specific rules, asset conventions, and module-level preconditions. This increases token consumption and degrades agent parsing accuracy. Fix: Enforce the narrowest-scope rule. Create scoped addenda (ASSETS.CONTRACT.md, API.CONTRACT.md) when local invariants exceed 10-15 rules. Keep the root artifact focused on system-wide boundaries.

2. Treating the Artifact as Historical Archive

Explanation: Developers write the contract once, commit it, and never update it. The document becomes a historical record rather than an active enforcement layer. Fix: Tie contract updates to pull request workflows. Require LAST_REVIEWED and REVIEW_TRIGGER metadata. Treat stale contracts as technical debt.

3. Vague Constraint Language

Explanation: Using phrases like "avoid breaking changes" or "keep URLs consistent" provides no actionable boundary for stateless agents. Fix: Use explicit, binary rules. Replace "keep URLs consistent" with "All /blog/:slug routes MUST return 200. Redirects require explicit 301 mapping." Ambiguity invites probabilistic guessing.

4. Missing Review Triggers

Explanation: Without explicit conditions for when the contract should be updated, teams drift into silent violations. Fix: Define REVIEW_TRIGGER as concrete events: "Update when adding new top-level routes", "Update when migrating legacy plugin dependencies", "Update when changing authentication flow".

5. Ignoring Token Budget Constraints

Explanation: Overly verbose contracts consume context window space, leaving less room for code generation and analysis. Fix: Use tables for enumerations, bullet points for constraints, and remove narrative explanations. Prioritize machine-parseable structure over human readability. The agent is the primary consumer.

6. Overlapping Scope Boundaries

Explanation: Multiple contract files define conflicting rules for the same domain. Agents receive contradictory constraints and default to the most recent token. Fix: Establish a clear hierarchy. Root contract governs system-wide invariants. Scoped contracts govern domain-specific rules. Use explicit SCOPE: headers to prevent overlap. Validate conflicts during code review.

7. Static Prompt Injection Without Validation

Explanation: Teams inject the contract into agent prompts but never verify that the agent actually read or respected it. Fix: Implement a validation step. After agent initialization, run a lightweight check that confirms the agent acknowledges the constraints. Use the parser example above to enforce rules programmatically during scaffolding.

Production Bundle

Action Checklist

• Define system boundaries: Identify URL structures, external dependencies, and legacy constraints that must survive migration.
• Create root artifact: Initialize SYSTEM.CONTRACT.md at repository root with metadata headers and structured tables.
• Establish review triggers: Document explicit conditions that require contract updates.
• Implement guided generation: Use AI drafting loop for initial content, followed by human review.
• Integrate into agent workflow: Configure initialization prompts to load the artifact before code generation.
• Add validation layer: Use lightweight parsers or CI checks to enforce critical invariants during scaffolding.
• Monitor drift: Track contract staleness and update LAST_REVIEWED on every relevant PR.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Single-module refactor	Inline function contracts	Local scope, immediate violation detection	Low
System migration / framework upgrade	Root invariant artifact	Cross-module boundaries, prevents silent drift	Medium
Asset/SEO overhaul	Scoped addendum (ASSETS.CONTRACT.md)	Domain-specific rules, prevents root bloat	Low
Legacy system onboarding	Root artifact + guided generation	Surfaces tribal knowledge, reduces clarification loops	Medium
High-frequency agent sessions	Root artifact + CI validation	Enforces constraints programmatically, reduces drift	High (initial), Low (ongoing)

Configuration Template

Copy this template to initialize a root invariant artifact. Replace bracketed fields with project-specific data.

# SYSTEM.CONTRACT.md

SCOPE: [Project Name] — [Migration/Feature Boundary]
LAST_REVIEWED: [YYYY-MM-DD]
REVIEW_TRIGGER: [e.g., Adding new top-level routes, Changing auth flow, Migrating legacy dependencies]

## CRITICAL INVARIANTS — DO NOT BREAK

### 1. Routing Structure
| Route Pattern | Handler Type | Constraints |
|---------------|--------------|-------------|
| `/`           | Static       | Landing layout only |
| `/api/v1/*`   | REST         | Authenticated, rate-limited |
| `/admin/*`    | Admin Panel  | Role-gated, no public access |

### 2. External Dependencies
- Payment processing: Stripe SDK v4.x only. No custom wrappers.
- Email delivery: SendGrid API. Fallback to SMTP disabled.
- File storage: S3-compatible endpoint. No local disk writes.

### 3. Out of Scope
- Legacy WordPress migration paths
- Client-side analytics injection
- Third-party chat widgets

## ENFORCEMENT NOTES
- All route additions MUST update this file before merge.
- External dependency upgrades require security review + contract update.
- Violations will be caught by CI routing validator.

Quick Start Guide

1. Initialize the artifact: Create SYSTEM.CONTRACT.md at the repository root using the configuration template.
2. Define boundaries: List critical routes, external dependencies, and out-of-scope features. Use tables for machine parsing.
3. Set lifecycle metadata: Fill LAST_REVIEWED and REVIEW_TRIGGER. Commit the file.
4. Configure agent onboarding: Add a system directive to your AI coding agent's initialization prompt: Load SYSTEM.CONTRACT.md before generating code. Respect all listed invariants.
5. Validate: Run a test session. Verify the agent references the contract, avoids out-of-scope features, and respects routing boundaries. Iterate as needed.