Putting a Safety Lock on Single-File AI Edits: A Path-Scope Ledger in Practice

AI models can generate a fix patch in seconds, but "faster" never means "safer." When you want a title-fixer to touch exactly one file, the model's draft might quietly reach over and nudge a neighboring file — and on a long, exhausting worknight, would you really catch that slip in the moment?

This article introduces a lightweight protection approach: before executing any AI-generated single-file edit, first build a path-scope ledger. It answers one blunt question — which exact paths is this edit actually allowed to change?

What the Ledger Is Actually Guarding

The ledger is not a replacement for human code review. Before any apply command runs, it makes one clean, decisive call: which paths may change in this task?

If the answer is ambiguous, the task stops immediately. Even a clean diff fails if the path scope is too wide; missing evidence also counts as failure — not a gentle warning. The author treats scope creep as the number-one bug worth making visible. "Vibe-coded" patches so often go wrong precisely because they quietly touch a file that was never named.

The core philosophy is fail-closed: unless the patch is proven to stay within the allowlist, execution is denied.

Step 1: Freeze the Allowed Paths

Before the model says a word, pick a file and write it down. That file is the entire contract for tonight's edit. If a second file needs changing, open a separate task.

mkdir -p evidence fixtures
printf '%s\n' 'src/titles.py' > evidence/allowlist.txt
wc -l evidence/allowlist.txt

Why freeze a single file rather than a whole directory? Because a second file hides scope creep inside a diff that looks friendly. The test is: can you explain both changes in one honest sentence? If it takes a paragraph, you actually have two tasks — split them first, then ask the model. Vague prompts attract vague patches you never requested.

Step 2: Capture the Proposal, Don't Apply It

Ask the model for a unified diff and save it to a file. Don't apply, commit, or stage anything yet. The saved diff is a proposal, not a pass.

test -s proposal.diff
git apply --check --verbose proposal.diff

Note that --check only validates whether the patch can be applied — it does not prove that the paths fall within the allowlist. That proof belongs to the ledger in the next step. Keep your model prompt deliberately boring: name the allowed file explicitly in the prompt text and instruct the model to reject every other path in its response.

A unified diff is the most universal patch format in the Unix/Linux world, produced by diff -u. Each file block is annotated with --- a/ and +++ b/ to mark the original and target paths, followed by hunks — each hunk begins with an @@ line marking context position, lines starting with - indicate deletions, lines starting with + indicate additions, and lines with no prefix are context lines. git apply --check simulates applying a patch in this format, verifying that it can be applied to the current code tree without conflict — but it only validates syntax and context legality; it does not interpret path semantics. This is exactly the article's point: --check is necessary but not sufficient. Whether the paths fall within the allowlist is a separate judgment the ledger script must make on its own.

Step 3: Run the Scope Ledger

The heart of the ledger is a Python script, scope_ledger.py, a few dozen lines long with no third-party dependencies — the standard library is enough (targeting Python 3.9+ for built-in type annotations). What the script does is straightforward:

• Parse all target paths beginning with +++ b/ from the diff
• Compare them against the allowlist and list any out-of-scope paths
• Check whether the file count exceeds the budget (default max_files=1)
• Run a rough regex scan for secret patterns (e.g., AKIA..., api_key=, etc.)
• On any match, write a failure card and return with exit code 2

def judge(allow, diff, max_files):
    paths = DIFF_PATH.findall(diff)
    unique = sorted(set(paths))
    extra = sorted(set(paths) - allow)
    reasons = []
    if not diff.strip():
        reasons.append("empty-diff")
    if not unique:
        reasons.append("no-target-path")
    if extra:
        reasons.append("path-outside-allowlist:" + ",".join(extra))
    if len(unique) > max_files:
        reasons.append("file-count-over-budget")
    if SECRET.search(diff):
        reasons.append("secret-pattern")
    return {"pass": not reasons, "allow": sorted(allow),
            "paths": unique, "reasons": reasons}

How to run it:

python3 scope_ledger.py \
  --allow evidence/allowlist.txt \
  --diff proposal.diff \
  --out evidence/scope-card.json
echo "exit=$?"

Exit code 0 means the pass card has been written to disk; exit code 2 means stop — and a pass card must never be left behind. The critical point: do not let the apply script ignore this exit code, even if the diff is only a few lines. Chain subsequent commands so that a missing card aborts the flow.

An exit code is the most reliable communication contract between a Unix process and its caller. A process that ends normally returns 0; any non-zero value signals some kind of error or refusal. The script uses 2 rather than 1 as its failure code as a deliberate semantic distinction: 1 typically signals a generic error, while 2 in shell convention often means "usage error or condition not met" — making it easier for callers to distinguish "script crashed" from "ledger actively rejected" when chaining with &&/|| or in a pipeline. The article specifically stresses "don't let the apply script ignore the exit code" because many automation scripts only check whether a command ran, not whether it agreed to proceed — which is the most common entry point for silent failures.

Step 4: Keep a Failure Fixture

A gate with no red test is wishful thinking. The author recommends keeping a bad diff that deliberately touches a second file and plants a fake secret string — use it to verify that the gate actually fires.

cat > fixtures/two-files.diff << 'EOF'
--- a/src/titles.py
+++ b/src/titles.py
@@ -1 +1 @@
-old title
+new title
--- a/src/notes.py
+++ b/src/notes.py
@@ -1 +1 @@
-note
+api_key=EXAMPLE_DO_NOT_USE
EOF

The expected result is exit code 2, a scope-card.fail.json generated, and no scope-card.json present. This red fixture is the script's regression lock — after the green demo passes, don't delete it. Re-run it every time the script changes. If this fixture somehow "passes," the ledger is lying to you.

The core value of regression testing is that every time you modify code, you immediately know whether scenarios that should have failed still fail. For a security gate, a "red fixture" matters even more than a "green demo" — a gate that never fires is indistinguishable from a gate that doesn't exist. There's an anti-pattern in software engineering called a "false green": the test suite passes entirely, but some tests have broken assertion logic and will never go red. Storing a deliberately violating diff file and running it in every CI or manual regression pass is the minimal practice against this risk — it tests the gate's teeth, not its shell.

Step 5: Apply Only Behind the Pass Card

Before the actual apply, read the pass card — if the pass field is missing or false, reject the task. After applying, run a second check: a "staged-name reconciliation."

git apply --index proposal.diff
git diff --cached --name-only > evidence/staged.txt

import sys
allow = {ln.strip() for ln in open("evidence/allowlist.txt") if ln.strip()}
staged = {ln.strip() for ln in open("evidence/staged.txt") if ln.strip()}
sys.exit(0 if staged and staged <= allow else 4)

The ledger checks the path scope of the diff text; this second check catches cases where the apply process itself drifted. Both layers are essential.

Fail-Closed Rules You Can Copy Directly

The author provides a clear gate reference table — each row names the evidence file and its stop condition:

Gate	Evidence	When to Default-Deny
Path freeze	allowlist.txt	Missing, empty, or more than one path
Proposal saved	proposal.diff	Missing, empty, or git apply --check fails
Scope match	scope-card.json	Any path outside the allowlist
File budget	Card paths field	More than one file in the diff
Secret sniffing	Card reasons field	Pattern matched, even a placeholder
Apply lock	Exit code 0	Card missing, pass is false, or staged names drifted

Three additional "just stop" rules: if the allowlist expands beyond a single directory, stop; if the model can't produce a unified diff tonight, stop; if the free server can't run the script, stop. Waiting one night is far cheaper than one accidental commit. And beware — a program crash is itself a stop signal. Never catch exceptions and print a friendly "success" message; that is exactly how silent failures sneak into production.

Who This Is For — and Who Should Skip It

This approach isn't universal. The author honestly lists scenarios where you should skip it: tonight requires a multi-service release, legal requires a formal control framework, or you're renaming a symbol across multiple files — the ledger will scream at broad renames, and it should. If you can't yet read a unified diff, learn apply --check before trusting any card output.

The best fit is a solo developer on a single-file + temporary-branch workflow; small teams already reviewing every hunk block-by-block can also put the red fixture to use. Everyone else should keep manual diff review.

The Author's Candid Limitations

Rarely, the article is thoroughly honest about its own boundaries:

• The secret check is only a rough regex — it will miss real leaks and produce false positives on documentation. Treat every match as a stop signal and read the hunk yourself.
• The allowlist does not govern behavior inside the allowed file. A single-file diff can still delete a function you need. The card proves path scope, not code correctness.
• A stale failure card may coexist with a fresh pass card. The exit code is the real lock, not a leftover filename.

Disclosure: The original author notes this article is part of MonkeyCode product outreach, using it to obtain free model drafts and free server time to run the gate. But the author repeatedly emphasizes — the ledger itself matters more than whatever host runs it. Any local model plus a throwaway clone repo can feed the same gate.

The real value of this hands-on tutorial isn't any particular tool — it's a way of thinking: give AI a small brake before its speed touches production. Models got faster, but the apply step didn't automatically get safer. And safety is something you have to go freeze that one path yourself.