automaker/FEATURE_LIST_PROTECTION.md

Feature List Protection Strategy

Problem

The .automaker/feature_list.json file is the single source of truth for all project features and their status. If an AI agent accidentally clears or corrupts this file, it results in catastrophic data loss - potentially erasing hours or days of planning work.

Incident: An agent attempted to update the feature list and completely cleared it out, leaving only [].

Solution: Multi-Layered Protection

We've implemented a defense-in-depth strategy with multiple layers of protection to prevent this from ever happening again.

---

Layer 1: Explicit Prompt-Level Warnings

Location

All agent system prompts now include prominent warnings at the top:

• app/electron/services/prompt-builder.js:
  • getCodingPrompt() - Used by feature implementation agents
  • getVerificationPrompt() - Used by verification agents
• app/electron/agent-service.js:
  • getSystemPrompt() - Used by the general chat agent
• .automaker/initializer_prompt.md - Used by the initialization agent

Content

Each prompt now starts with:

🚨 CRITICAL FILE PROTECTION - READ THIS FIRST 🚨

THE FOLLOWING FILE IS ABSOLUTELY FORBIDDEN FROM DIRECT MODIFICATION:
- .automaker/feature_list.json

YOU MUST NEVER:
- Use the Write tool on feature_list.json
- Use the Edit tool on feature_list.json
- Use any Bash command that writes to feature_list.json (echo, sed, awk, etc.)
- Attempt to read and rewrite feature_list.json
- UNDER ANY CIRCUMSTANCES touch this file directly

CATASTROPHIC CONSEQUENCES:
Directly modifying feature_list.json can:
- Erase all project features permanently
- Corrupt the project state beyond recovery
- Destroy hours/days of planning work
- This is a FIREABLE OFFENSE - you will be terminated if you do this

THE ONLY WAY to update features:
Use the mcp__automaker-tools__UpdateFeatureStatus tool with featureId, status, and summary parameters.

Why This Works

• Uses attention-grabbing emoji and formatting
• Places warnings at the very top of prompts (high visibility)
• Uses strong language ("CATASTROPHIC", "FIREABLE OFFENSE")
• Explicitly lists all forbidden actions
• Provides the correct alternative (UpdateFeatureStatus tool)

---

Layer 2: Dedicated MCP Tool

Location

app/electron/services/mcp-server-factory.js

How It Works

The UpdateFeatureStatus tool provides a safe, controlled interface for updating features:

tool(
  "UpdateFeatureStatus",
  "Update the status of a feature in the feature list. Use this tool instead of directly modifying feature_list.json...",
  {
    featureId: z.string(),
    status: z.enum(["backlog", "in_progress", "verified"]),
    summary: z.string().optional()
  },
  async (args) => {
    // Calls featureLoader.updateFeatureStatus with validation
  }
)

Why This Works

• Provides a single, well-defined API for status updates
• Only accepts specific, validated parameters
• Cannot be misused to clear the entire file
• Tool description explicitly states it should be used instead of direct edits

---

Layer 3: File-Level Validation & Auto-Backup

Location

app/electron/services/feature-loader.js - updateFeatureStatus() method

Protection Mechanisms

3.1 Automatic Backup Before Every Write

// Create .automaker/feature_list.backup.json before any modification
const backupPath = path.join(projectPath, ".automaker", "feature_list.backup.json");
await fs.writeFile(backupPath, originalContent, "utf-8");

Benefit: If corruption occurs, we can manually restore from the backup.

3.2 Array Validation

if (!Array.isArray(features)) {
  throw new Error("CRITICAL: features is not an array - aborting to prevent data loss");
}

Benefit: Prevents writing if the loaded data is corrupted.

3.3 Empty Array Detection & Auto-Restore

if (features.length === 0) {
  console.warn("WARNING: Feature list is empty. This may indicate corruption.");
  // Try to restore from backup
  const backupFeatures = JSON.parse(await fs.readFile(backupPath, "utf-8"));
  if (Array.isArray(backupFeatures) && backupFeatures.length > 0) {
    features.push(...backupFeatures);
  }
}

Benefit: If the file is somehow cleared, the tool automatically attempts to restore from backup.

3.4 Pre-Write Validation

if (!Array.isArray(toSave) || toSave.length === 0) {
  throw new Error("CRITICAL: Attempted to save empty feature list - aborting to prevent data loss");
}

Benefit: Final safety check - will never write an empty array to the file.

3.5 Backup File Ignored by Git

Created .automaker/.gitignore:

feature_list.backup.json

Benefit: Backup files don't clutter the git repository.

---

Layer 4: Tool Access Control

Location

app/electron/services/feature-executor.js and feature-verifier.js

Allowed Tools

The agents only have access to these tools:

allowedTools: [
  "Read",
  "Write",
  "Edit",
  "Glob",
  "Grep",
  "Bash",
  "WebSearch",
  "WebFetch",
  "mcp__automaker-tools__UpdateFeatureStatus",
]

Future Enhancement Opportunity

We could create a custom wrapper around Write/Edit that blocks access to specific files:

// Potential future enhancement
if (filePath.includes('feature_list.json')) {
  throw new Error('BLOCKED: feature_list.json can only be updated via UpdateFeatureStatus tool');
}

---

Testing the Protection

To verify the protection works:

1. Prompt-Level Protection Test:

   • Ask an agent to update feature_list.json directly
   • Agent should refuse and explain it must use UpdateFeatureStatus tool

2. Tool Protection Test:

   • Use UpdateFeatureStatus with valid data
   • Verify backup is created in .automaker/feature_list.backup.json
   • Verify feature is updated correctly

3. Corruption Recovery Test:

   • Manually corrupt feature_list.json (e.g., set to [])
   • Call UpdateFeatureStatus
   • Verify it auto-restores from backup

4. Empty Array Prevention Test:

   • Attempt to save empty array programmatically
   • Verify the error is thrown and file is not written

---

Recovery Procedures

If feature_list.json Gets Cleared

1. Immediate Recovery:

   cd .automaker
   cp feature_list.backup.json feature_list.json
   

2. Check Git History:

   git log --all --full-history -- .automaker/feature_list.json
   git show <commit>:.automaker/feature_list.json > .automaker/feature_list.json
   

3. Verify Recovery:

   cat .automaker/feature_list.json | jq length
   # Should show number of features, not 0
   

---

Summary

We now have four layers of protection:

1. ✅ Explicit prompt warnings - Agents are told in strong language never to touch the file
2. ✅ Dedicated MCP tool - UpdateFeatureStatus provides the only safe way to update
3. ✅ File validation & auto-backup - Automatic backups and validation prevent corruption
4. ✅ Tool access control - Agents have limited tool access (could be enhanced further)

This defense-in-depth approach ensures that even if one layer fails, others will prevent data loss.

---

Files Modified

1. app/electron/services/prompt-builder.js - Added protection warnings to getCodingPrompt() and getVerificationPrompt()
2. app/electron/agent-service.js - Added protection warnings to getSystemPrompt()
3. .automaker/initializer_prompt.md - Added warning for initializer agent
4. app/electron/services/feature-loader.js - Added backup, validation, and auto-restore logic
5. .automaker/.gitignore - Added backup file ignore rule
6. FEATURE_LIST_PROTECTION.md - This documentation file