> ## Documentation Index > Fetch the complete documentation index at: https://tashfiq.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Fix Engine > How charter fix works: diff-first, backup-before-write, and why some rules are intentionally not auto-fixable. Charter never mutates a file silently. Every fix goes through diff → review → apply — in that order, always. The alternative was a one-shot apply that minimizes output noise, but that removes the last human checkpoint between the scanner's judgment and your codebase. ## The diff-first loop Every fix moves through the same three stages, in this order, always: * **Scan** — `charter doctor` marks each finding with a `fixable` indicator when a deterministic remediation exists. Findings without a fixer (secrets, dangerous hook configurations) are flagged but never offered as automated fixes. * **Preview** — `charter fix --dry-run` prints the unified diff for every proposed change and writes nothing. It exits with the same code the apply step would, so it slots into review scripts. * **Apply** — `charter fix` copies each original file to `.charter/backups//` before writing, then applies the diff. For the exact commands, recovery steps, and a reviewer's checklist, see [Use charter fix Safely](/docs/how-to/use-charter-fix-safely). charter fix dry run showing unified diff for each proposed change ## Fixable rules | Rule | Fixer action | Safety class | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [`AE-CTX-001`](/rules/AE-CTX-001) | Creates `AGENTS.md` from a standard template if the file is absent | ✅ Create-only — never overwrites | | [`AE-CTX-004`](/rules/AE-CTX-004) | Creates or appends `.gitignore` with agent artifact patterns (`.charter/`, `*.charter-session`, `.claude/local/`, `.cursor/cache/`) | ✅ Append-only — never removes existing entries | | [`AE-CI-002`](/rules/AE-CI-002) | Creates `.github/workflows/charter.yaml` with the standard scan workflow | ✅ Create-only — never overwrites | | [`AE-MCP-001`](/rules/AE-MCP-001) | Updates an MCP server package reference to the catalog's current stable version | ✅ Token replace — single version string, full diff shown | These fixers are safe to automate because the correct output is fully determined by the rule specification. There is no ambiguity and no judgment call required. That is why these four — and only these four — have automated fixers in v1. ## Why secrets are never auto-fixed [`AE-SEC-001`](/rules/AE-SEC-001) and [`AE-SEC-002`](/rules/AE-SEC-002) are never auto-fixed. A fix that only removes the literal value from a file without rotating the credential is not a remediation — it is a false sense of resolution. The secret is still active, still in git history if committed, and still in any system that cached it. Charter shows you the file path and line number (never the raw value), and tells you exactly what to do. The rotation and removal steps are yours to execute. The same logic applies to dangerous hook configurations ([`AE-CC-001`](/rules/AE-CC-001)). Rules that flag unrestricted shell execution or broad glob allowlists in agent configs require a human to evaluate the intent behind the configuration and decide on a safer alternative. Charter cannot know whether the hook is a legitimate use case that needs a narrow permission or an oversight that should be removed entirely. These are deliberate boundaries, not gaps to fill in a future release. ## Backup mechanism Before every write, Charter copies the original file to `.charter/backups//`, where `` is a compact UTC timestamp such as `20260601T143022Z`. If the fixer modifies `.github/workflows/ci.yml`, the original is preserved at: ``` .charter/backups/20260601T143022Z/.github/workflows/ci.yml ``` The backup directory is created fresh for each `charter fix` invocation. Charter **never deletes backup directories** and never truncates existing ones — they accumulate until you remove them, so the AE-CTX-004 fixer adds `.charter/` to `.gitignore` to keep them local. If a fixer produces an unexpected result, the original is always recoverable from the most recent backup directory. ## MCP catalog-aware pin bumps The `AE-MCP-001` fixer has special logic for the three distinct cases it may encounter: * **Advisory-affected version** → bumps to the `fixedIn` version recorded in the catalog advisory. Charter will not bump to a version that is itself subject to a known advisory. * **Unpinned or behind catalog stable** → bumps to the catalog's `stableVersion` for that package. * **Deprecated or archived package** → NOT auto-fixed. The package requires migration to a successor, which is a manual step. Charter provides the successor package name in the finding detail. ## Next steps The full recipe: dry-run, review, apply, re-scan, and recover. Every flag the fix command accepts. How a successful fix moves the score. Why the AE-MCP-001 fixer bumps to catalog versions, not the latest release.