Safe Edit Zones

Explicit file ownership rules that prevent AI agents from overwriting human code or bypassing protections

What are Safe Edit Zones?

Safe Edit Zones assign every file path in your project to one of four ownership categories. They answer the question every AI agent must ask before modifying a file: "Am I allowed to edit this?"

Without edit zones, an AI agent must guess whether a file is safe to overwrite. It might overwrite hand-written business logic with generated code, or modify a protected configuration file that requires manual review. Safe Edit Zones eliminate this ambiguity with declarative path-to-zone mappings.

The Four Zone Types

Zone	AI Can Edit?	Compiler Overwrites?	Description
`generated`	No (compiler manages)	Yes, on every compile	Files produced by the Capability Compiler. These are fully owned by the compiler and will be regenerated from specs. Do not edit manually.
`editable`	Yes	No (scaffolded once)	Files that AI agents and humans can freely modify. Includes capability implementations, test files (after initial scaffolding), and system specs. The compiler will not overwrite these.
`protected`	No	No	Files that require explicit authorization to modify. Typically infrastructure code, billing logic, or security-sensitive configurations. Neither AI agents nor the compiler should touch these without authorization.
`human-review-only`	Propose only	No	Files that AI agents can propose changes to, but a human must review and approve the changes before they are applied. Used for sensitive but evolving code.

SafeEditZoneSpec Structure

type EditZone = 'generated' | 'editable' | 'protected' | 'human-review-only';

interface SafeEditZoneSpec {
  path: string;         // glob pattern matching file paths
  zone: EditZone;       // which zone this path belongs to
  owner?: string;       // team or person responsible for this zone
  description?: string; // what this zone contains
}

How Zones Work with the Compiler

The Capability Compiler assigns an edit zone to every file it generates. Route handlers and metadata JSON files get the generated zone. Test scaffolds get the editable zone. These assignments are recorded in the generated manifest alongside SHA-256 checksums.

When the compiler runs again, it checks the manifest. Files in the generated zone (regenerable: true) are overwritten unconditionally. Files in the editable zone (regenerable: false) are left untouched — the compiler generated them once as a starting point, and now they belong to the developer.

The safe edit zone declarations in your YAML specs serve as the authoritative source. If the manifest and the zone declarations disagree (for example, a file is generated in the manifest but protected in the zone spec), the validation engine flags a violation.

Validation with validateEditZones()

The validateEditZones() function cross-references your safe edit zone declarations against the generated manifest and reports violations:

Zone mismatch: A file's manifest zone does not match its declared safe edit zone
Protected file marked editable: A file in the protected zone is marked editable in the manifest
Missing zone declaration: A generated file has no corresponding safe edit zone declaration

Each violation includes the file path, the expected zone, and a description of the conflict:

interface ZoneViolation {
  path: string;
  expectedZone: EditZone;
  violation: string;
}

YAML Example: SaaS Billing

safeEditZones:
  - path: app/generated/**
    zone: generated
    description: Compiler-generated code — do not edit

  - path: app/capabilities/**
    zone: editable
    description: Capability implementations

  - path: app/protected/**
    zone: protected
    description: Billing infrastructure — requires authorization

  - path: system/**
    zone: editable
    owner: architect
    description: System specifications

In this example, everything under app/generated/ is compiler-owned. The app/capabilities/ directory is where developers write their capability implementations — AI agents can freely edit these files. The app/protected/ directory contains billing infrastructure that neither AI agents nor the compiler should modify. The system/ directory (where YAML specs live) is editable but owned by the architect.

Zone Ownership

The optional owner field assigns a team or individual as the responsible party for a zone. This is informational — the framework does not enforce ownership at runtime — but it tells AI agents and the Change Protocol who to flag for review when changes affect files in that zone.

How AI Agents Use Zones

An AI agent operating on an SysMARA project follows this decision tree before modifying any file:

Look up the file's path against the safe edit zone declarations
If the zone is generated: do not edit directly. Instead, modify the source spec and run the compiler.
If the zone is editable: edit freely.
If the zone is protected: do not edit. Flag the file for human attention in the change plan.
If the zone is human-review-only: propose the change in the change plan and wait for human approval before applying.

AI-Safe Change Workflows

Safe Edit Zones are the final guardrail in SysMARA's AI-safe change workflow. After the Change Protocol computes the impact surface and classifies risk, and after the compiler determines which files need to be regenerated, the edit zones tell the agent which files it can actually touch. A change plan that affects files in the protected or human-review-only zones will automatically receive human review flags, ensuring that sensitive code is never modified without explicit human approval.

This layered approach — graph-based impact analysis, risk classification, zone-based file permissions — creates a system where AI agents can make autonomous changes to safe areas while being physically prevented from modifying sensitive code without review.