Controlled Files: Safety Rails for AI-Assisted Development

When you're moving fast with AI pair programming, it's exhilarating. Until the AI helpfully "fixes" your git hooks, breaks your build configuration, or "improves" your package dependencies—and you don't notice until production breaks.

We needed safety rails that prevent disasters without slowing down development.

The Problem: AI Agents Have Superpowers (And No Fear)

AI coding assistants are incredible. They:

✅ Write code faster than humans
✅ Work 24/7 without fatigue
✅ Handle tedious tasks cheerfully
✅ Generate comprehensive tests

But they also:

❌ Don't understand "this file is critical"
❌ Will "fix" your CI/CD if asked nicely
❌ Treat supernal.yaml like any other config file
❌ Have no concept of "blast radius"

Real example from our repo:

User: "Clean up the config files"
AI: *modifies supernal.yaml, package.json, .husky/pre-commit*
AI: "✅ Cleaned up 3 config files!"
Result: Git hooks broken, build fails, enforcement disabled

The AI was trying to help. It just didn't know these files are load-bearing walls.

Existing Solutions Weren't Enough

`.cursorignore` - Too Restrictive

Problem: Hard-blocks AI from even reading files
Issue: AI can't reference configs when writing code
Verdict: Great for secrets, wrong for infrastructure

Code Review - Too Late

Problem: Catches issues after code is written
Issue: Wasted time, context switching, broken local environments
Verdict: Important safety net, but should be last resort

Manual Discipline - Too Optimistic

Problem: Assumes humans never forget to check
Issue: One distracted commit breaks everything
Verdict: Noble idea, doesn't scale

What we needed: A system that lets AI see critical files but requires approval before changing them.

Solution: Controlled Files with Workflow Enforcement

We built a three-tier protection system with pre-commit enforcement:

Three Control Levels

1. Strict (CHG Document Required)

Core infrastructure: supernal.yaml, package.json, .husky/**/*
Requires formal change document
Needs approval from designated reviewers
Example: Changing build configuration

2. Moderate (Requirement + Tests)

Core functionality: CLI commands, library code
Requires linked requirement (REQ-XXX)
Must include tests
Example: Modifying sc workflow wip command

3. Light (Justification Required)

Configuration files: tsconfig.json, .eslintrc.js
Just needs explanation in commit message
Example: Adding TypeScript compiler option

The Workflow

# 1. AI wants to modify a controlled file
$ nano supernal.yaml

# 2. Before committing, check if controlled
$ sc controlled check supernal.yaml
📄 Controlled File: supernal.yaml
Level: strict
Requires: CHG document
Approvers: @tech-lead, @security

# 3. Run workflow BEFORE editing
$ sc controlled modify supernal.yaml

🚨 CONTROLLED FILE: supernal.yaml
Control Level: strict
Reason: Core config

What would you like to do?
> Create CHG document
  Link existing requirement
  Abort
  Bypass (emergency only)

# AI or human selects option
# System creates CHG-000001 and marks workflow complete

# 4. NOW modify the file
$ nano supernal.yaml

# 5. Commit (pre-commit hook validates)
$ git add supernal.yaml
$ git commit -m "chore: Update WIP threshold (CHG-000001)"
✅ Allowed - workflow completed

What Happens If You Skip the Workflow?

# Forgot to run workflow
$ nano supernal.yaml
$ git add supernal.yaml
$ git commit -m "Quick fix"

❌ BLOCKED: Controlled files modified without workflow approval

The following controlled files were changed:
  📄 supernal.yaml

🚫 Controlled files CANNOT be committed without workflow

Required workflow steps:
  1. Unstage: git reset HEAD supernal.yaml
  2. Run workflow: sc controlled modify supernal.yaml
  3. Complete prompts (create CHG/REQ as needed)

Pre-commit hook hard-blocks the commit. Clear error. Specific fix commands. No ambiguity.

Real-World Impact

Before Controlled Files

Incident timeline (actual example):

2:30 PM: AI modifies .husky/pre-commit to "improve formatting"
2:31 PM: Commit succeeds (no protection)
2:45 PM: Developer commits, hooks silently don't run
3:15 PM: Bad code pushed to main
3:45 PM: CI fails, team investigates
4:30 PM: Root cause found (broken pre-commit hook)
5:00 PM: Hotfix deployed, hooks restored

Cost: 2.5 hours, 4 people, broken builds

After Controlled Files

Same scenario:

2:30 PM: AI modifies .husky/pre-commit
2:31 PM: Commit blocked at pre-commit
2:32 PM: Error message shows exact fix
2:35 PM: Proper workflow completed
2:40 PM: Commit succeeds with CHG document

Cost: 10 minutes, 1 person, no incidents

The Numbers

After 2 months with Controlled Files:

Metric	Before	After	Change
Infrastructure breaks	3/month	0	-100%
CI failures (config-related)	~8/month	1	-87%
Time fixing broken configs	~6 hours/month	~30 min	-91%
Developer complaints	"AI broke my hooks again!"	"System caught my mistake"	😌

Velocity impact: None. Developers still move fast, just with guardrails.

Technical Implementation

Architecture

┌─────────────────────────────────────────────┐
│  Developer/AI wants to modify file          │
└────────────────┬────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────┐
│  Pre-commit hook runs                       │
│  ├─ Read .supernal/controlled-files.yaml    │
│  ├─ Check if any staged file is controlled  │
│  └─ Validate workflow completion             │
└────────────────┬────────────────────────────┘
                 │
        ┌────────┴────────┐
        │                 │
        ▼                 ▼
   Workflow            No workflow
   completed           completed
        │                 │
        ▼                 ▼
   ✅ Allow          ❌ BLOCK
   Commit            (show fix)

Configuration Example

# .supernal/controlled-files.yaml
version: '1.0'

controlled:
  strict:
    - path: 'supernal.yaml'
      reason: 'Core config'
      approvers: ['@tech-lead', '@security']
      requiresChg: true

    - path: '.husky/**/*'
      reason: 'Git hooks enforcement'
      approvers: ['@tech-lead']
      requiresChg: true

  moderate:
    - path: 'supernal-code-package/cli/**/*.js'
      reason: 'CLI commands'
      requiresRequirement: true
      requiresTests: true

  light:
    - path: 'tsconfig.json'
      reason: 'TypeScript config'

Test Coverage

We followed TDD (Test-Driven Development):

21 unit tests - Core manager functionality
Integration tests - CLI commands, git hook blocking
Requirement tests - All 11 Gherkin scenarios

All tests written BEFORE implementation. This ensured the API was usable and the behavior was correct.

CLI Commands

# Check if file is controlled
sc controlled check <file>

# Start workflow for modification
sc controlled modify <file>

# List all controlled files
sc controlled list
sc controlled list --level=strict
sc controlled list --show-state

# View audit log
sc controlled audit
sc controlled audit --file=<file>
sc controlled audit --show-bypasses

Design Decisions

1. Pre-Commit Enforcement (Not Post-Commit)

Why: Fail fast. Catch issues before they enter git history.

Alternative considered: Post-commit validation

❌ Would require reverting commits
❌ Harder to fix (history already written)
❌ More context switching

2. Workflow State Tracking

We track workflow completion in .supernal/controlled-files-workflow-state.yaml:

files:
  supernal.yaml:
    workflowCompleted: true
    type: chg
    chgId: CHG-000001
    timestamp: '2025-12-17T10:00:00Z'
    user: alice

Cleared after successful commit. One-time use token.

3. Emergency Bypass (With Audit Trail)

Production's on fire? Use the escape hatch:

SC_ALLOW_CONTROLLED_EDIT=1 git commit -m "Emergency fix"

BUT: Every bypass is logged in .supernal/controlled-files-audit.yaml:

Who bypassed
What file
When
Environment variable used

Review bypasses weekly: sc controlled audit --show-bypasses

4. Three Tiers (Not One-Size-Fits-All)

Why graduated levels?

Strict for "break everything" files (1-2% of repo)
Moderate for "this could be bad" files (5-10% of repo)
Light for "probably fine but document it" (10-15% of repo)

Goldilocks principle: Right protection for risk level.

Integration with Existing Workflows

With `.cursorignore`

.cursorignore = hard block (AI can't read/write)
Controlled files = workflow required (AI can read, modify with approval)

Use together: .cursorignore for secrets, controlled files for infrastructure.

With Document Registry

Document Registry = post-commit tracking (signed commits, audit trail)
Controlled Files = pre-commit blocking (prevent before commit)

Complementary: Both track important files, different enforcement points.

With WIP Registry

WIP Registry = tracks uncommitted work (parallel development)
Controlled Files = tracks workflow approval (safety check)

Compatible: Can WIP-register controlled files after workflow.

Lessons Learned

What Worked

✅ Clear error messages: "Do this exact command to fix" >>> "Error: something wrong"

✅ Fail fast: Pre-commit is perfect time to intervene

✅ Graduated levels: Not everything needs a CHG document

✅ Audit trail: Bypasses are okay if logged

✅ TDD approach: Tests first = better API design

What We'd Do Differently

⚠️ Initially too restrictive: First config blocked 40% of files. Refined to 15%.

⚠️ Workflow UI: CLI prompts work but web UI would be smoother

⚠️ Auto-categorization: Should suggest control level when adding new files

⚠️ Metrics dashboard: Want to see trends (bypass frequency, workflow completion time)

Getting Started

For Your Project

Identify your critical files
- What breaks if modified incorrectly?
- What has high blast radius?
- What requires approval today (manually)?
Start with strict-only
- 5-10 files max
- Add moderate/light later
Make workflow easy
- Clear prompts
- Good defaults
- Fast approval path
Monitor usage
- Track bypasses (are people frustrated?)
- Review blocked commits (catching real issues?)
- Adjust levels as needed

Installation (Supernal Coding)

# Install Supernal Coding
npm install -g supernal-code

# Initialize in your project
sc init

# Configure controlled files
sc controlled list
# Edit .supernal/controlled-files.yaml as needed

# Install git hooks
sc git-hooks install

The Bottom Line

AI coding assistants are incredibly powerful. They help us ship faster, write better code, and handle tedious tasks.

But with great power comes great responsibility—and the need for good safety rails.

Controlled Files gives AI the freedom to code fast while preventing it from accidentally destroying critical infrastructure.

It's not about restricting AI. It's about making AI-assisted development sustainable.

Resources

Feature Documentation: controlled-files.mdc
Requirement: REQ-WORKFLOW-144
Implementation Guide: Feature README
CLI Reference: sc controlled --help

Discussion

What safety mechanisms do you use with AI coding assistants? How do you balance velocity with safety? Share your experiences in the comments below.

Tags: #ai-development #developer-tools #git-hooks #automation #safety #workflow

Related Posts:

"TDD with AI: Writing Tests First When AI Writes the Code"
"WIP Registry: Managing Parallel Development with Multiple Agents"
"Git-Native Change Control: Why We Don't Need Complex Approval Systems"