Summary

• Total Breaking Changes: 1
• Severity: CRITICAL
• Commits Analyzed: 1 (751d39f)
• Status: ⚠️ Requires Immediate Review

A breaking schema change was detected and incorrectly categorized as minor. The removal of the top-level sandbox: false option (boolean format) should be a major version bump, not minor.

Critical Breaking Changes

Detailed Analysis

// Handle boolean format: sandbox: false (NO LONGER SUPPORTED)
// This format has been removed - only sandbox.agent: false is supported
if _, ok := sandbox.(bool); ok {
    frontmatterExtractionSecurityLog.Print("Top-level sandbox: false is no longer supported")
    // Return nil to trigger schema validation error
    return nil
}

require.Error(t, err, "Expected error when using sandbox: false (top-level boolean no longer supported)")

---
sandbox: false
---

---
sandbox:
  agent: false
---

---
"gh-aw": minor
---
Removed the deprecated top-level `sandbox: false` option and replaced it with `sandbox.agent: false`, so only the agent firewall can be disabled while the MCP gateway stays enabled. Add `gh aw fix` to migrate existing workflows.

Action Checklist

Complete the following items to address this breaking change:

• Correct the changeset type from minor to major - Rename .changeset/minor-disable-agent-sandbox-only.md to .changeset/major-disable-agent-sandbox-only.md and change the YAML frontmatter from minor to major
• Enhance migration guidance in changeset - Add explicit before/after code examples showing the migration path
• Document in CHANGELOG.md - Add entry under "Breaking Changes" section with clear user-facing migration instructions
• Verify gh aw fix handles migration - Confirm that the gh aw fix command mentioned in the changeset actually migrates sandbox: false to sandbox.agent: false
• Consider deprecation period - Evaluate whether this should have been deprecated with a warning first, rather than an immediate breaking change

Recommendations

Immediate Actions

1. Update Changeset Type - Change from minor to major:

   mv .changeset/minor-disable-agent-sandbox-only.md .changeset/major-disable-agent-sandbox-only.md

   Then update the content:

   ---
   "gh-aw": major
   ---
   
   **⚠️ BREAKING CHANGE**: Removed support for top-level `sandbox: false` (boolean format)
   
   The deprecated `sandbox: false` syntax is no longer supported. Use `sandbox.agent: false` instead.
   
   **Migration guide:**
   
   Before:
   \`\`\`yaml
   ---
   sandbox: false
   ---
   \`\`\`
   
   After:
   \`\`\`yaml
   ---
   sandbox:
     agent: false
   ---
   \`\`\`
   
   **Automatic migration**: Run `gh aw fix workflow-name` to automatically migrate your workflows.
   
   **Reason**: This change separates agent sandbox configuration from MCP gateway configuration, allowing users to disable the agent firewall while keeping the MCP gateway enabled.

2. Verify Migration Tool - Test that gh aw fix correctly handles this migration:

   # Test with a workflow that has sandbox: false
   gh aw fix test-workflow.md

3. Update Breaking CLI Rules - Consider adding this as an example in scratchpad/breaking-cli-rules.md under Schema Changes.

Best Practices for Future Changes

According to the breaking CLI rules, this change should have followed this deprecation path:

1. Version N: Add deprecation warning when sandbox: false is detected (keep functionality working)
2. Version N+1 (minor): Continue showing warning, document scheduled removal
3. Version N+2 (major): Remove support with clear migration guidance

For immediate breaking changes like this one, always:

• Mark changeset as major
• Provide detailed migration examples
• Include automatic migration tooling
• Document the rationale for breaking compatibility

Reference

• Commit: 751d39fdf
• Breaking CLI Rules: scratchpad/breaking-cli-rules.md
• Changeset System: scratchpad/changesets.md

Once all checklist items are complete, close this issue.

AI generated by Breaking Change Checker