DEV Community

Sam Rivera
Sam Rivera

Posted on

Build a Promotion Checklist Before an AI Comment Diff Moves

#ai #python #cli #tutorial

I want a boring exit before an AI comment diff moves.
The fixture below is synthetic and not a customer incident.
Copy it only after you read the abandonment rules.

Why a tidy comment still needs a gate

A clearer comment can still hide a risky edit underneath.
Did the helper touch only the comment, or also nearby code?
A green test run is a polite liar, so I will not trust it.

Clean wording is not the same thing as a safe diff.
That split is an old developer worry, not a fresh news claim.
I am using it as a shipping constraint, not as a debate topic.

The box this checklist guards

This checklist guards a one-task helper on a tiny Python repo.
The helper may propose a clearer comment on a single function.
It may not format the file, rename symbols, or edit tests.

You can run that helper on your own laptop today.
You can also try a hosted free model path after the gates exist.
The checker itself stays local and never calls a model.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.
Operator notes say MonkeyCode has free model access and a free server option.
I am not claiming a quota, a hardware size, or a lasting price.

Three gates, then nothing else

Each gate needs its own evidence file before promotion continues.
A missing file, bad JSON, or false flag must stop the run.
That fail-closed rule replaces soft warnings on this narrow path.

Read this table before you trust a green terminal line.

Gate Evidence file Fail closed when
Input freeze input_freeze.json frozen is not true, or commit is under 7 chars
Diff budget diff_budget.json more than 1 file, or more than 20 added lines
Human ack human_ack.json ack is not true, or reviewer or ticket is blank

Gate 1: Freeze the input

What commit did the helper actually read before it wrote?
If that hash is missing, the proposed diff is unmoored.
I refuse to promote a patch that has no frozen input.

Gate 2: Budget the diff

How many files changed, and how many lines were added?
My budget here is one file and twenty added lines.
Cross either line and the checker must exit non-zero.

Gate 3: Record a human ack

Who looked at the comment and agreed it may move?
A reviewer name plus a ticket id is the whole proof.
No ack file means no promotion, and I will not infer consent.

Numbered setup

  1. Create a folder named comment-exit and change into that folder.
  2. Save the checker as promote_check.py from the block below.
  3. Make an evidence directory and add the three JSON fixtures.
  4. Run the checker, then break one fixture on purpose.
  5. Point a comment helper at a scratch branch only after that.

The checker you can copy 

#!/usr/bin/env python3
# Local evidence check only. No model call. No network.

import json
import sys
from pathlib import Path

ROOT = Path("evidence")
MAX_FILES = 1
MAX_LINES = 20

def load(name: str) -> dict:
    path = ROOT / name
    if not path.is_file():
        raise SystemExit(f"FAIL missing {name}")
    try:
        data = json.loads(path.read_text())
    except json.JSONDecodeError as exc:
        raise SystemExit(f"FAIL bad json {name}: {exc}")
    if not isinstance(data, dict):
        raise SystemExit(f"FAIL {name} must be an object")
    return data

def as_int(data: dict, key: str) -> int:
    try:
        return int(data[key])
    except (KeyError, TypeError, ValueError) as exc:
        raise SystemExit(f"FAIL bad int {key}: {exc}")

def main() -> int:
    freeze = load("input_freeze.json")
    budget = load("diff_budget.json")
    ack = load("human_ack.json")

    commit = str(freeze.get("commit", ""))
    if not freeze.get("frozen") or len(commit) < 7:
        raise SystemExit("FAIL input not frozen")

    files = as_int(budget, "files_changed")
    lines = as_int(budget, "lines_added")
    if files < 0 or lines < 0:
        raise SystemExit("FAIL negative diff counts")
    if files > MAX_FILES or lines > MAX_LINES:
        raise SystemExit(f"FAIL budget files={files} lines={lines}")

    reviewer = str(ack.get("reviewer", "")).strip()
    ticket = str(ack.get("ticket", "")).strip()
    if not ack.get("ack") or not reviewer or not ticket:
        raise SystemExit("FAIL human ack incomplete")

    print(f"PASS commit={commit} reviewer={reviewer} ticket={ticket}")
    return 0

if __name__ == "__main__":
    sys.exit(main())
Enter fullscreen mode Exit fullscreen mode

Evidence fixtures

These three files are the smallest evidence pack I will accept.

{"commit": "abc1234deadbeef", "frozen": true}
Enter fullscreen mode Exit fullscreen mode 
{"files_changed": 1, "lines_added": 4}
Enter fullscreen mode Exit fullscreen mode 
{"reviewer": "sam", "ack": true, "ticket": "COMMENT-12"}
Enter fullscreen mode Exit fullscreen mode

Commands 

mkdir -p comment-exit/evidence
cd comment-exit
cat > evidence/input_freeze.json <<'EOF'
{"commit": "abc1234deadbeef", "frozen": true}
EOF
cat > evidence/diff_budget.json <<'EOF'
{"files_changed": 1, "lines_added": 4}
EOF
cat > evidence/human_ack.json <<'EOF'
{"reviewer": "sam", "ack": true, "ticket": "COMMENT-12"}
EOF
python3 promote_check.py
echo "exit=$?"
Enter fullscreen mode Exit fullscreen mode

A passing run prints one PASS line and exits zero.
A missing evidence file prints FAIL and exits non-zero.
Wire that exit code to your apply step and never ignore it.

Count the real diff before you fill the budget file.
Run git diff with numstat on the scratch branch first.
Copy those two numbers into the budget file by hand.

git diff --numstat
Enter fullscreen mode Exit fullscreen mode

One failure you should see

Change the frozen flag to false and run the checker again.
You should see a fail line and a non-zero process exit.
If you still see PASS, stop and fix the script first.

python3 - <<'PY'
import json
from pathlib import Path
p = Path("evidence/input_freeze.json")
d = json.loads(p.read_text())
d["frozen"] = False
p.write_text(json.dumps(d))
PY
python3 promote_check.py
echo "exit=$?"
Enter fullscreen mode Exit fullscreen mode

Delete the human ack file and run the checker once more.
The missing file must fail closed, not warn and then continue.
Restore that file only after the second failure looks right.

rm evidence/human_ack.json
python3 promote_check.py
echo "exit=$?"
Enter fullscreen mode Exit fullscreen mode

Time and abandonment

Budget twenty minutes to copy, break, and restore this checker.
If setup passes thirty minutes, abandon the helper for today.
The checker has no API cost, though your model path might.

I am not giving a dollar figure for any hosted model run.
Prices and free tiers move, so read the current vendor page.
If that page is unclear, do not build a cron job around it.

Where a free model path fits

The checker does not need a hosted product in order to stay useful.
Use a free model only to draft the comment text itself.
Use a free server only when you refuse a local draft run.

Keep every draft on a scratch branch until PASS prints.
Then run a dry apply check before any real apply.
If the dry apply fails, drop the patch and do not hand-merge it.

git apply --check comment.diff
Enter fullscreen mode Exit fullscreen mode

Rollback

Promotion here means copying a patch onto a scratch branch.
Rollback is checking out that branch clean, or deleting the branch.
Do not use this checklist on a shared release branch.

If any gate file is older than the diff, treat it as stale.
I did not encode timestamps in this first cut of the script.
Add a generated-at field before you trust the same files twice.

git checkout -- .
git branch -D scratch-comment
Enter fullscreen mode Exit fullscreen mode

Who should not use this

Skip this path if the helper can edit more than comments.
Skip it for secrets, auth changes, migrations, or production writes.
Skip it when your team needs a signed compliance packet.

This is a solo or small-team exit, not an enterprise control.
It does not score comment quality or claim model accuracy.
A human still has to read the sentence before writing the ack.

Limits I will not paper over

The script trusts the JSON you wrote and does not parse a diff.
You can lie in the file count and still receive a PASS.
Pair the checker with git numstat before you call the gate done.

I have not measured runtime, token use, or server capacity.
Those numbers stay absent on purpose, so please do not invent them.
Check primary docs when you need a current limit or region.

A smaller next step

If you already draft comments on a hosted helper, park this checker first.
One optional path is MonkeyCode free model access, if that offer is still listed.
I will not nudge you past a missing doc or a vanished free button.

What budget field is still missing for your own repo?
Reply with the file cap or the ack field you refuse to skip.

Top comments (0)