Define module boundaries, enforce architectural constraints, configure safety policies, run safety gates, and fail CI on violations — with Mikk's contract system.

Contracts are the source of truth for AI safety

Define your rules in mikk.json. The contract is read by the CLI, MCP server, safety gates, decision engine, and boundary checker — everywhere a change is validated or context is built.

Contract Structure

mikk.json

{
  "version": "1.0.0",
  "project": {
    "name": "my-project",
    "description": "Example contract.",
    "language": "typescript",
    "framework": "nextjs",
    "entryPoints": []
  },
  "declared": {
    "modules": [
      {
        "id": "auth",
        "name": "Authentication",
        "description": "JWT auth and session management",
        "paths": ["src/auth/**"],
        "entryFunctions": ["login", "validateToken"]
      },
      {
        "id": "payments",
        "name": "Payments",
        "description": "Payment processing and billing",
        "paths": ["src/payments/**"]
      }
    ],
    "constraints": [
      "auth must not import from payments"
    ],
    "decisions": [
      {
        "id": "ADR-001",
        "title": "Stateless JWT authentication",
        "reason": "Avoids session storage in distributed deployments",
        "date": "2025-01-15"
      }
    ]
  },
  "overwrite": {
    "mode": "never",
    "requireConfirmation": true
  },
  "policies": {
    "maxRiskScore": 70,
    "maxImpactNodes": 10,
    "protectedModules": ["auth", "billing"],
    "enforceStrictBoundaries": true,
    "requireTestsForChangedFiles": true,
    "requireDocumentationForApiChanges": false
  }
}

Constraints

Constraints live in declared.constraints as string[]. Each is parsed by the boundary checker at runtime.

Constraint string	Effect
`auth must not import from payments`	Module `auth` cannot import files from module `payments`
`payments can only import from db, logger`	`payments` is restricted to those two modules
`users is isolated`	`users` has no cross-module imports allowed
`module:payments cannot import auth`	Explicit `module:id` syntax
`module:cli has no imports`	`cli` has zero cross-module dependencies

Policies

policies configures the enforcement thresholds used by the Decision Engine and Safety Gates.

Policy	Type	Default	Effect
`maxRiskScore`	number	70	WARN above this; BLOCK at risk ≥ 90 (hard-coded, not overridable)
`maxImpactNodes`	number	10	WARN when impact count > this; BLOCK at > `maxImpactNodes × 2`
`protectedModules`	string[]	[]	BLOCK any edit whose file path matches a protected module ID — never bypassable
`enforceStrictBoundaries`	boolean	false	BLOCK on any critical-classified cross-module impact
`requireTestsForChangedFiles`	boolean	true	BLOCK high-risk changes (exported + many callers) if no test files are modified
`requireDocumentationForApiChanges`	boolean	false	BLOCK significant API changes if no `README.md`, `API.md`, `CHANGELOG.md`, or `AGENTS.md` is updated

protectedModules matching checks whether the file path of an impacted node contains the module ID string. Keep module IDs short, specific, and lowercase to avoid false matches. Example: "auth" matches src/auth/login.ts but also src/oauth/callback.ts — be precise.

Generating a Contract

Auto-detect modules

mikk init

Analyzes import coupling, directory structure, and naming conventions to produce a starter mikk.json.

Review and tune

Open mikk.json and verify:

Module paths globs match the right files (no overlapping patterns)
declared.constraints reflect your actual architectural rules
policies.protectedModules lists modules that should never be touched without architecture review
policies.maxRiskScore and policies.maxImpactNodes match your project's risk tolerance

Validate against the current codebase

mikk contract validate

Fix existing violations before adding the contract to CI.

Validating

mikk contract validate                       # check all constraints
mikk contract validate --strict              # exit code 1 on any violation
mikk contract validate --boundaries-only     # fastest: boundary checks only

Example output:

✗ VIOLATION: auth → payments
  src/auth/login.ts imports src/payments/subscription.ts
  Rule: auth must not import from payments

1 violation found.

Architecture Decision Records (ADRs)

ADRs document why a constraint exists. They surface automatically in every mikk_query_context response — AI agents understand the reasoning, not just the rule.

mikk adr list                                                    # list all decisions
mikk adr get ADR-001                                             # full details
mikk adr add --id "use-jwt" --title "Stateless JWT" --reason "No session storage needed"
mikk adr rm use-jwt                                              # remove

ADRs are also used by the Intent Understanding component to detect whether a breaking change aligns with a planned migration. If an ADR mentions a module by name and contains the word "migration" or "deprecat", changes affecting that module are classified as planned — raising confidence that the breaking change is intentional.

CI Integration

.github/workflows/ci.yml

- name: Architecture gate
  run: mikk ci --strict --format json

mikk ci --strict
if [ $? -ne 0 ]; then
  echo "Architecture violations found."
  exit 1
fi

mikk ci --strict exits non-zero on constraint violations. --format json outputs structured results for log ingestion or custom reporting.

Was this page helpful?

Contract & Policies Reference