DEV Community: Sam Rivera

Your Readiness Checklist Is Lying: Add Expiry Dates to Every Gate

Sam Rivera — Sun, 18 Oct 2026 06:44:18 +0000

Last month a teammate asked me one question before a Friday deploy: "Is the summarizer ready?"

I answered from memory. That was the bug.

I had run the tests. I had done one manual canary. But I had no artifact that said when, or what changed since. My confidence was real. My evidence was a vibe.

So I built something small. Not a bigger checklist. A checklist where every pass expires.

The problem with green checkmarks

A green checkmark has no timestamp. It never says when it was earned.

So a pass from three weeks ago looks identical to a pass from this morning. The checklist stays green while the code moves underneath it. That is a silent failure mode, and silent failures are the expensive ones.

The fix is boring. Treat evidence like milk. Give it a date, give it a shelf life, and refuse to serve it after that.

What the dossier looks like

Five gates. One evidence file each. No prose, no opinions in the file — just a result and a timestamp.

readiness/
  gates.json
  readiness.py
  evidence/
    g1_input_contract.txt
    g2_canary.txt
    g3_cost_ceiling.txt
    g4_rollback_drill.txt
    g5_owner_handoff.txt

The config stays tiny on purpose.

{
  "ttl_days": 14,
  "gates": [
    { "id": "G1", "claim": "inputs are validated before the model sees them", "owner": "sam", "evidence": "evidence/g1_input_contract.txt" },
    { "id": "G2", "claim": "one canary task passed on the free tier", "owner": "sam", "evidence": "evidence/g2_canary.txt" },
    { "id": "G3", "claim": "worst-case cost per 1k calls is bounded", "owner": "sam", "evidence": "evidence/g3_cost_ceiling.txt" },
    { "id": "G4", "claim": "rollback was executed, not imagined", "owner": "sam", "evidence": "evidence/g4_rollback_drill.txt" },
    { "id": "G5", "claim": "someone other than me can turn it off", "owner": "sam", "evidence": "evidence/g5_owner_handoff.txt" }
  ]
}

Each evidence file is two lines. Nothing else.

RESULT: pass
RUN_AT: 2026-10-17T21:40:00Z

Step 1: Write the checker before you write the gates

I wrote the checker first. That forced me to decide what a valid pass actually is.

The whole thing is stdlib Python and about 65 lines.

#!/usr/bin/env python3
"""readiness.py - fail-closed evidence checker. Exit 0 only when every gate is green and fresh."""
import json, sys, pathlib, datetime as dt

ROOT = pathlib.Path(__file__).resolve().parent
STAMP = "%Y-%m-%dT%H:%M:%SZ"


def parse_stamp(line):
    if not line.startswith("RUN_AT: "):
        raise ValueError(f"missing RUN_AT line: {line!r}")
    return dt.datetime.strptime(line[8:].strip(), STAMP).replace(tzinfo=dt.timezone.utc)


def check_gate(gate, ttl_days, now):
    path = ROOT / gate["evidence"]
    if not path.exists():
        return "MISSING", f"{gate['id']} evidence file not found"
    lines = [l.strip() for l in path.read_text().splitlines() if l.strip()]
    if len(lines) < 2 or not lines[0].startswith("RESULT: "):
        return "MISSING", f"{gate['id']} needs RESULT then RUN_AT"
    result = lines[0][8:].strip().lower()
    if result != "pass":
        return "FAIL", f"{gate['id']} last run reported {result!r}"
    try:
        ran = parse_stamp(lines[1])
    except ValueError as exc:
        return "MISSING", f"{gate['id']} bad timestamp: {exc}"
    age = (now - ran).days
    if age > ttl_days:
        return "STALE", f"{gate['id']} evidence is {age}d old, ttl is {ttl_days}d"
    return "PASS", f"{gate['id']} ok ({age}d old, owner {gate['owner']})"


def main():
    cfg = json.loads((ROOT / "gates.json").read_text())
    now = dt.datetime.now(dt.timezone.utc)
    rows = [check_gate(g, cfg["ttl_days"], now) for g in cfg["gates"]]
    for status, msg in rows:
        print(f"{status:7} {msg}")
    bad = [r for r in rows if r[0] != "PASS"]
    print(f"\n{len(rows) - len(bad)}/{len(rows)} gates green")
    if bad:
        print("readiness: BLOCKED")
        return 1
    print("readiness: CLEAR")
    return 0


if __name__ == "__main__":
    sys.exit(main())

Notice what it refuses to do. It does not run your tests. It does not judge quality. It only asks one question per gate: is there a recent, well-formed pass on disk?

Step 2: Make each gate produce its own evidence

The gate is not the check. The gate is the file the check leaves behind.

# G1: input contract
python -m pytest tests/test_input_contract.py -q \
  && printf 'RESULT: pass\nRUN_AT: %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  > readiness/evidence/g1_input_contract.txt

Repeat that shape for G4. Run the rollback for real, then record it.

# G4: rollback drill - flip the flag, confirm the fallback path, then restore
./scripts/flag.sh off && curl -s localhost:8080/health | grep -q degraded \
  && ./scripts/flag.sh on \
  && printf 'RESULT: pass\nRUN_AT: %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  > readiness/evidence/g4_rollback_drill.txt

For G2 I use one tiny canary task against free hosted model access instead of a paid endpoint. That keeps the gate cheap enough to re-run weekly, which is the whole point.

I have been doing this with MonkeyCode's free model access. I also run readiness.py on the free server option, so the check does not depend on anyone's laptop staying awake.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Step 3: Test the checker with a broken dossier

A checker you never saw fail is a checker you cannot trust.

So I keep a fixture with one stale file. It passes its own check and still blocks the deploy.

$ python readiness.py
PASS    G1 ok (2d old, owner sam)
PASS    G2 ok (2d old, owner sam)
STALE   G3 evidence is 41d old, ttl is 14d
PASS    G4 ok (3d old, owner sam)
MISSING G5 evidence file not found

3/5 gates green
readiness: BLOCKED
$ echo $?
1

That STALE line is the one I care about most. Nobody lied. The evidence was simply too old to mean anything.

The timebox that keeps this honest

A checklist that takes two days to satisfy gets deleted. Mine has a hard budget.

Gate	Time budget	If it blows the budget
G1 input contract	45 min	ship behind a flag, keep the gate red
G2 canary	20 min	do not deploy to real users
G3 cost ceiling	30 min	cap the feature, re-measure next week
G4 rollback drill	30 min	no deploy; rollback is not optional
G5 owner handoff	15 min	treat as unshipped

Total worst case is under three hours. If the feature is not worth three hours, it is not worth a Friday deploy.

Abandon and rollback criteria

Write these down before you need them. Mine are three lines.

Any gate stays red after two remediation attempts. Park the feature.
G3 exceeds the declared ceiling twice in a row. Cut scope, not the gate.
G5 has no secondary owner. Do not ship, no exceptions.

Rollback is one command and one file restore. If it needs a meeting, the gate failed.

Who should not use this

This is not for a weekend prototype with no users. It is also the wrong tool if you have no deploy path yet, or if nobody owns the feature.

And it will not save a team that treats evidence as paperwork. The script only checks freshness. It cannot check whether the canary was meaningful.

The thing that actually changed

My teammate stopped asking me if it was ready. She runs the checker and reads five lines.

That is the win. Not more confidence. Less of mine required.

If you try this, my one real question is about G5: who is the second person who can turn your feature off, and have they actually done it once? That field is where most small-team dossiers break, and I would like to know how yours holds up.

You can reproduce the whole thing in an afternoon. Free model access covers the canary, and the free server option covers the checker run — no card, no CI runner.

Seven Executable Gates Before a Free Model Touches Real Data

Sam Rivera — Sat, 17 Oct 2026 05:52:21 +0000

The goal is small. Let a free model tidy one config file. The risk is not small. A model that writes files is a program with your permissions.

I have written enough of these checklists as prose. Nobody runs prose. So this time the checklist is a script. It exits non-zero. It writes evidence. It refuses to continue.

Here is the whole thing: seven gates, one evidence file, and a hard rule that a machine cannot approve itself.

Why exit codes beat checkboxes

A checkbox is a promise. An exit code is a fact. When the gate fails, set -e stops the pipeline before the write happens.

That is the difference between "we usually check" and "it cannot proceed". Ask yourself which one you have right now.

Step 1: Pick the smallest job you can actually gate

Do not start with a refactor. Start with one input file and one output file. My rule: the job must fit in a single diff a human can read in 60 seconds.

Write the plan down as text first. The plan is an input to the gates, not documentation for later.

job: tidy-config
reads: ./input/app.toml
writes: ./out/app.toml
budget: 20000 tokens, 3 requests
rollback: git stash + file snapshot

If you cannot fill in the writes line, stop. The scope gate has nothing to enforce.

Step 2: Put the gates in one file

Every gate is a command. Pass means exit 0. Anything else means stop.

#!/usr/bin/env bash
# readiness.sh — fail-closed checklist for one AI task
set -euo pipefail

JOB="${1:?usage: readiness.sh <job-dir>}"
EVID="$JOB/evidence.jsonl"
: > "$EVID"

gate() {  # gate <name> <command...>
  local name="$1"; shift
  local stamp; stamp="$(date -u +%FT%TZ)"
  if "$@" >/dev/null 2>&1; then
    printf '{"gate":"%s","status":"pass","at":"%s"}\n' "$name" "$stamp" >> "$EVID"
  else
    printf '{"gate":"%s","status":"fail","at":"%s"}\n' "$name" "$stamp" >> "$EVID"
    echo "FAIL-CLOSED: $name" >&2
    exit 1
  fi
}

gate boundary  ./checks/secrets.sh   "$JOB/input"
gate scope     ./checks/paths.sh     "$JOB/plan.txt"
gate budget    ./checks/budget.sh    "$JOB"
gate failure   ./checks/inject.sh    "$JOB"
gate rollback  ./checks/snapshot.sh  "$JOB"
gate diff      ./checks/diffsize.sh  "$JOB"
gate signoff   ./checks/signature.sh "$JOB"

echo "ready: $EVID"

Seven lines of gate calls. That is the whole checklist, and it is diffable in review.

Step 3: Know what each gate actually proves

A gate that proves nothing is decoration. Here is the honest column.

Gate	Automatable	Evidence written	Fail action
boundary	yes — regex + deny-list	matched file list	stop, redact, re-run
scope	yes — allowlist diff	unexpected write paths	stop, revert
budget	yes — hard counter	request/token count	stop mid-run
failure	yes — bad fixture	non-zero exit + stderr	stop, file a bug
rollback	yes — snapshot hash	restore test log	stop, fix restore
diff	yes — line count	diffstat	stop, split the job
signoff	no — human only	name + timestamp	stop, ask

Six of seven gates are mechanical. The seventh is a person. Keep it that way.

Step 4: Give the budget gate teeth

A budget that logs and continues is not a budget. Wrap the call and count before you send.

# call.py — one request, one ceiling, no retries
import os, json, urllib.request

BASE = os.environ["BASE_URL"]      # your provider's endpoint
MODEL = os.environ["MODEL"]
CAP = int(os.environ.get("TOKEN_CAP", "20000"))
spent = 0

prompt = open("input/app.toml").read()
estimate = len(prompt) // 4          # rough, deliberately pessimistic
if estimate > CAP:
    raise SystemExit("FAIL-CLOSED: budget")

body = json.dumps({"model": MODEL, "messages": [{"role": "user", "content": prompt}]}).encode()
req = urllib.request.Request(BASE, data=body, headers={"Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=60) as r:
    out = json.load(r)

spent += estimate
open("evidence/budget.json", "w").write(json.dumps({"estimate": spent, "cap": CAP}))
print(out.get("choices", [{}])[0].get("message", {}).get("content", ""))

No retry loop. A retry loop is how a 20k budget becomes a 60k bill. If the call fails, the gate fails, and a human decides.

Step 5: Where a free host fits

MonkeyCode is an open-source project, and the hosted side advertises free model access plus a free server option. The team currently lists a free token allowance in the 10-million range; free-tier numbers move, so read the project page for today's figure instead of trusting a blog post — including this one.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

What that buys you here is the ability to run the failure gate against a real endpoint without spending money. That is the point of a free tier in a checklist workflow: you need to see the bad path, not just the happy one.

The free server also removes a hardware decision from the critical path. You can run the same readiness.sh on a box that is not your laptop, which is exactly what the rollback gate wants.

Set BASE_URL and MODEL from whatever the provider documents. Do not hardcode a model name into a gate script. Names age badly and your checklist should outlive them.

Step 6: Ship a failure fixture before you ship the feature

Write one input that must fail. Mine is a config with a duplicate key and a trailing secret-shaped string.

./readiness.sh jobs/tidy-config
# FAIL-CLOSED: boundary
# exit 1

The output above is the shape to expect, not a benchmark. If your bad fixture passes, your boundary gate is a comment with extra steps.

When to abandon the whole thing

Set kill criteria before you start. Mine, in order:

Two gates cannot be automated in one hour → park the job.
The rollback restore fails twice → the write is not safe yet.
The diff exceeds 60 lines → the job was too big, split it.
The free tier queues past your patience → pay or shrink the job, do not remove the gate.

Criteria 4 matters. The temptation is to disable a gate when the host is slow. Delete the gate, delete the evidence, and you are back to vibes.

Limitations, stated plainly

These gates prove process, not model quality. A model can pass all seven and still produce wrong config. You still need a test.

They also assume you control the write path. If your tool writes directly to a database, the snapshot gate is a fiction — do not use this pattern there.

Skip this if you handle regulated data, need an SLA, or cannot get a human signature within the same day. The signoff gate will block you forever, and that is correct behavior for you.

For solo builders and small teams shipping one small AI feature, the script is roughly 80 lines, one afternoon, zero dependencies.

One question that would change the next build

What is the gate you cannot automate — the one where you keep adding a manual step and it keeps getting skipped? That specific step is where I would put the signature check next.

Seven Executable Gates Before a Free Model Touches Real Data

Sam Rivera — Sat, 17 Oct 2026 05:46:03 +0000

The goal is small. Let a free model tidy one config file. The risk is not small. A model that writes files is a program with your permissions.

I have written enough of these checklists as prose. Nobody runs prose. So this time the checklist is a script. It exits non-zero. It writes evidence. It refuses to continue.

Here is the whole thing: seven gates, one evidence file, and a hard rule that a machine cannot approve itself.

Why exit codes beat checkboxes

A checkbox is a promise. An exit code is a fact. When the gate fails, set -e stops the pipeline before the write happens.

That is the difference between "we usually check" and "it cannot proceed". Ask yourself which one you have right now.

Step 1: Pick the smallest job you can actually gate

Do not start with a refactor. Start with one input file and one output file. My rule: the job must fit in a single diff a human can read in 60 seconds.

Write the plan down as text first. The plan is an input to the gates, not documentation for later.

job: tidy-config
reads: ./input/app.toml
writes: ./out/app.toml
budget: 20000 tokens, 3 requests
rollback: git stash + file snapshot

If you cannot fill in the writes line, stop. The scope gate has nothing to enforce.

Step 2: Put the gates in one file

Every gate is a command. Pass means exit 0. Anything else means stop.

#!/usr/bin/env bash
# readiness.sh — fail-closed checklist for one AI task
set -euo pipefail

JOB="${1:?usage: readiness.sh <job-dir>}"
EVID="$JOB/evidence.jsonl"
: > "$EVID"

gate() {  # gate <name> <command...>
  local name="$1"; shift
  local stamp; stamp="$(date -u +%FT%TZ)"
  if "$@" >/dev/null 2>&1; then
    printf '{"gate":"%s","status":"pass","at":"%s"}\n' "$name" "$stamp" >> "$EVID"
  else
    printf '{"gate":"%s","status":"fail","at":"%s"}\n' "$name" "$stamp" >> "$EVID"
    echo "FAIL-CLOSED: $name" >&2
    exit 1
  fi
}

gate boundary  ./checks/secrets.sh   "$JOB/input"
gate scope     ./checks/paths.sh     "$JOB/plan.txt"
gate budget    ./checks/budget.sh    "$JOB"
gate failure   ./checks/inject.sh    "$JOB"
gate rollback  ./checks/snapshot.sh  "$JOB"
gate diff      ./checks/diffsize.sh  "$JOB"
gate signoff   ./checks/signature.sh "$JOB"

echo "ready: $EVID"

Seven lines of gate calls. That is the whole checklist, and it is diffable in review.

Step 3: Know what each gate actually proves

A gate that proves nothing is decoration. Here is the honest column.

Gate	Automatable	Evidence written	Fail action
boundary	yes — regex + deny-list	matched file list	stop, redact, re-run
scope	yes — allowlist diff	unexpected write paths	stop, revert
budget	yes — hard counter	request/token count	stop mid-run
failure	yes — bad fixture	non-zero exit + stderr	stop, file a bug
rollback	yes — snapshot hash	restore test log	stop, fix restore
diff	yes — line count	diffstat	stop, split the job
signoff	no — human only	name + timestamp	stop, ask

Six of seven gates are mechanical. The seventh is a person. Keep it that way.

Step 4: Give the budget gate teeth

A budget that logs and continues is not a budget. Wrap the call and count before you send.

# call.py — one request, one ceiling, no retries
import os, json, urllib.request

BASE = os.environ["BASE_URL"]      # your provider's endpoint
MODEL = os.environ["MODEL"]
CAP = int(os.environ.get("TOKEN_CAP", "20000"))
spent = 0

prompt = open("input/app.toml").read()
estimate = len(prompt) // 4          # rough, deliberately pessimistic
if estimate > CAP:
    raise SystemExit("FAIL-CLOSED: budget")

body = json.dumps({"model": MODEL, "messages": [{"role": "user", "content": prompt}]}).encode()
req = urllib.request.Request(BASE, data=body, headers={"Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=60) as r:
    out = json.load(r)

spent += estimate
open("evidence/budget.json", "w").write(json.dumps({"estimate": spent, "cap": CAP}))
print(out.get("choices", [{}])[0].get("message", {}).get("content", ""))

No retry loop. A retry loop is how a 20k budget becomes a 60k bill. If the call fails, the gate fails, and a human decides.

Step 5: Where a free host fits

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The free server also removes a hardware decision from the critical path. You can run the same readiness.sh on a box that is not your laptop, which is exactly what the rollback gate wants.

Set BASE_URL and MODEL from whatever the provider documents. Do not hardcode a model name into a gate script. Names age badly and your checklist should outlive them.

Step 6: Ship a failure fixture before you ship the feature

Write one input that must fail. Mine is a config with a duplicate key and a trailing secret-shaped string.

./readiness.sh jobs/tidy-config
# FAIL-CLOSED: boundary
# exit 1

The output above is the shape to expect, not a benchmark. If your bad fixture passes, your boundary gate is a comment with extra steps.

When to abandon the whole thing

Set kill criteria before you start. Mine, in order:

Two gates cannot be automated in one hour → park the job.
The rollback restore fails twice → the write is not safe yet.
The diff exceeds 60 lines → the job was too big, split it.
The free tier queues past your patience → pay or shrink the job, do not remove the gate.

Criteria 4 matters. The temptation is to disable a gate when the host is slow. Delete the gate, delete the evidence, and you are back to vibes.

Limitations, stated plainly

These gates prove process, not model quality. A model can pass all seven and still produce wrong config. You still need a test.

They also assume you control the write path. If your tool writes directly to a database, the snapshot gate is a fiction — do not use this pattern there.

Skip this if you handle regulated data, need an SLA, or cannot get a human signature within the same day. The signoff gate will block you forever, and that is correct behavior for you.

For solo builders and small teams shipping one small AI feature, the script is roughly 80 lines, one afternoon, zero dependencies.

One question that would change the next build

What is the gate you cannot automate — the one where you keep adding a manual step and it keeps getting skipped? That specific step is where I would put the signature check next.

Fail Closed: A Production-Readiness Contract for Small AI Features

Sam Rivera — Fri, 16 Oct 2026 04:42:30 +0000

The gate I skip is always the one that bites

The DEV front page keeps arguing about AI output quality. Fair. But that debate skips the boring part.

Features ship without release criteria. Criteria get written after the incident, not before.

So here is a different approach. A readiness contract that fails closed, stored in the repo.

It is not a vibe check. It is a file, a runner, and three tests.

Three rules before any YAML

Write these on the repo wall. They are short on purpose.

Missing evidence is a failure, never a warning.
Exit code 0 is not proof. Empty output fails.
A waiver without an expiry and reason is invalid.

Rule two is the one people fight me on. A command that exits 0 and prints nothing tells you nothing.

Step 1: Put the gates in readiness.toml

I use TOML because tomllib ships with Python 3.11. No dependencies. No lockfile churn.

[defaults]
max_age_hours = 72
evidence_dir = "artifacts/readiness"

[[gate]]
id = "unit-tests"
run = "pytest -q"
evidence = "pytest.txt"
max_age_hours = 24
owner = "sam"

[[gate]]
id = "budget-headroom"
run = "python tools/token_budget.py --max-tokens 12000 --json"
evidence = "budget.json"
max_age_hours = 12
owner = "sam"
expect_json = { field = "spent_ratio_max", max = 0.6 }

[[gate]]
id = "rollback-drill"
run = ""
evidence = "rollback.exit"
max_age_hours = 168
manual = true
owner = "sam"

[[waiver]]
gate = "concurrent-load"
expires = "2026-11-01"
reason = "single-tenant canary, no concurrent load yet"

Two details matter. The manual = true gate runs nothing and only validates an evidence file a human produced. The expect_json predicate is a field comparison, not an expression, so nothing gets eval-ed.

Step 2: Write a pure core and a dumb shell

The bug in most checkers is mixed concerns. Shell edges stay dumb. The verdict logic stays pure.

#!/usr/bin/env python3
"""Fail-closed readiness runner. Missing evidence is a failure, not a warning."""
from __future__ import annotations

import json, subprocess, sys, time, tomllib
from dataclasses import dataclass, field
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
CFG = ROOT / "readiness.toml"


@dataclass
class Verdict:
    gate: str
    issues: list[str] = field(default_factory=list)
    owner: str = "unassigned"

    @property
    def ok(self) -> bool:
        return not self.issues


def evaluate(gate_id, exit_code, evidence_path, max_age_hours,
             expect_json=None, now=None, owner="unassigned") -> Verdict:
    now = now or time.time()
    verdict = Verdict(gate=gate_id, owner=owner)
    path = Path(evidence_path)

    if not path.exists():
        verdict.issues.append("missing_evidence")
        return verdict

    if (now - path.stat().st_mtime) / 3600 > max_age_hours:
        verdict.issues.append("stale")
    if path.stat().st_size == 0:
        verdict.issues.append("empty_evidence")
    if exit_code != 0:
        verdict.issues.append("nonzero_exit")

    if expect_json and not verdict.issues:
        try:
            data = json.loads(path.read_text())
        except json.JSONDecodeError:
            verdict.issues.append("bad_json")
        else:
            value = data.get(expect_json["field"])
            if value is None or value > expect_json["max"]:
                verdict.issues.append("predicate_failed")
    return verdict


def active_waiver(waivers, gate_id, today=None):
    today = today or time.strftime("%Y-%m-%d")
    for w in waivers:
        if w["gate"] != gate_id:
            continue
        if not w.get("reason", "").strip():
            continue          # no reason means no waiver
        if w["expires"] < today:
            continue          # expired means fail closed
        return w
    return None


def run_gate(gate, defaults, evdir):
    evdir.mkdir(parents=True, exist_ok=True)
    path = evdir / gate["evidence"]
    code = 0
    if gate.get("run"):
        proc = subprocess.run(gate["run"], shell=True, cwd=ROOT,
                              capture_output=True, text=True)
        code = proc.returncode
        path.write_text(proc.stdout + proc.stderr)
    return evaluate(
        gate["id"], code, path,
        gate.get("max_age_hours", defaults["max_age_hours"]),
        gate.get("expect_json"),
        owner=gate.get("owner", "unassigned"),
    )


def main() -> int:
    cfg = tomllib.loads(CFG.read_text())
    defaults = cfg.get("defaults", {})
    evdir = ROOT / defaults.get("evidence_dir", "artifacts/readiness")
    verdicts = [run_gate(g, defaults, evdir) for g in cfg.get("gate", [])]
    blocked = []
    for v in verdicts:
        if v.ok:
            continue
        w = active_waiver(cfg.get("waiver", []), v.gate)
        if w:
            print(f"WAIVED {v.gate} until {w['expires']}: {w['reason']}")
            continue
        blocked.append(v)
    print(f"{len(verdicts) - len(blocked)}/{len(verdicts)} gates green")
    for v in blocked:
        print(f"FAIL {v.gate} {','.join(v.issues)} owner={v.owner}")
    return 1 if blocked else 0


if __name__ == "__main__":
    sys.exit(main())

Run it with python tools/readiness.py. Exit code 1 blocks the release. Exit code 0 means every gate produced fresh, non-empty evidence.

Step 3: Add the failure fixture

A checker you never tested against failure is decoration. Two fixtures catch most of it.

# tests/test_readiness.py
from tools.readiness import active_waiver, evaluate


def test_silent_pass_is_a_failure(tmp_path):
    ev = tmp_path / "probe.txt"
    ev.write_text("")               # exited 0, printed nothing
    v = evaluate("health-probe", 0, ev, max_age_hours=24)
    assert "empty_evidence" in v.issues


def test_expired_waiver_does_not_apply():
    waivers = [{"gate": "load", "expires": "2020-01-01", "reason": "old"}]
    assert active_waiver(waivers, "load", today="2026-10-16") is None


def test_missing_evidence_is_a_failure(tmp_path):
    v = evaluate("canary", 0, tmp_path / "nope.log", max_age_hours=1)
    assert v.issues == ["missing_evidence"]

The first fixture is the important one. true exits 0 and produces nothing. Your checker must call that a failure.

The decision table

Copy this into the repo next to the TOML. Each row needs one owner name, not a team name.

Gate	Evidence	Fails closed when	Max age
Unit tests	`pytest.txt`	empty, nonzero, stale	24h
Budget headroom	`budget.json`	`spent_ratio_max > 0.6`	12h
Prompt hash	`prompt.sha256`	hash differs from reviewed commit	current commit
Canary traffic	`canary.log`	zero lines, any 5xx	1h
Rollback drill	`rollback.exit`	missing file	7d
Waiver hygiene	`readiness.toml`	expired or empty reason	n/a

Nothing here needs a dashboard. Six files and one exit code are enough for a solo builder.

Where free model access and a free server actually help

Two gates in that table cost money if you run them naively. That is where a free allowance changes the experiment.

Gate two measures budget headroom. I point it at a throwaway endpoint first, so a bad prompt loop burns nothing. MonkeyCode's free model access is the free tier I use for that pass, and its free server option gives me a disposable host for the canary gate instead of probing production.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Treat availability claims as claims. The free tier is advertised with a token allowance and a free server, but quotas, model lists, and terms change. Read the current terms on the project page before you wire a gate to them. Do not hardcode a number from a blog post into readiness.toml. Read it from the provider or from a config file you control.

Limitations and who should not use this

This is a release gate, not a security review. It proves evidence exists and is fresh. It proves nothing about correctness.

Skip it if you have no rollback path yet. Every gate will fail closed, and you will learn nothing.

Skip it in regulated environments where evidence needs formal sign-off chains. A TOML file is not an audit trail.

Skip it past roughly five services. At that size you want a platform team and real policy tooling, not one Python file.

Try it today in about 20 minutes

touch readiness.toml and add the unit-test gate only.
Write tools/readiness.py from the block above.
Add the empty-evidence fixture and watch it fail on purpose.
Run python tools/readiness.py and check the exit code.
Add one waiver with a real expiry date, then let it expire in a test.
Wire the runner into CI as a required step, not a report.

That is the whole artifact. One file, one runner, three tests, six rows.

Which field does your team keep forgetting in a gate like this: the evidence path, the owner, or the waiver expiry date? Tell me the missing one and I will fold it into the next version of the template.

Build a Free-Tier Preflight Gate Before Your CLI Trusts a Hosted Model

Sam Rivera — Thu, 15 Oct 2026 11:06:45 +0000

It was 23:40 on a Tuesday. My CLI had been talking to a free model endpoint for two weeks.

It returned HTTP 200 all night. Then it handed me half a JSON object. My build broke at 07:00 and nobody had measured anything.

That is the real problem with free tiers. They rarely fail loudly. They fail politely.

So I wrote a preflight script. It runs before my CLI is allowed to touch a hosted model. Every gate writes an evidence file. Missing evidence counts as failure, not as a pass.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source project whose free tier lists 10,000,000 tokens and a free server option, as described by the team. I treat those two claims as operator-supplied, not as numbers I measured. The harness below works against any OpenAI-style chat endpoint.

Why a checklist beats a vibe check

A vibe check answers one question: did it work just now? A preflight gate answers a better one: what evidence proves it still works?

Free lineups rotate, rate limits shift, and servers get cold. So pin a model id in your environment and re-run the gates whenever that pin changes. Six minutes of checks beats a broken morning.

What usually goes unmeasured? Latency, truncation, and token accounting. Those three cause most of my silent failures.

The seven gates

Each gate must produce a file. If you cannot point at the file, the gate did not run.

#	Gate	Evidence written	Fail-closed rule
1	Key present	hashed key prefix, env var names	missing key exits 2 before any network call
2	Reachability	status code, endpoint path, model id	any non-200 fails
3	Latency budget	three timing samples in ms	max sample over `MC_LATENCY_BUDGET_MS` fails
4	Schema conformance	raw body plus parsed keys	unparsable JSON or missing keys fails
5	Truncation visibility	`finish_reason` from a tiny `max_tokens` call	missing `finish_reason` fails
6	Usage accounting	`usage` object	missing token counts fails
7	Repeatability	two runs of one prompt, unified diff	two identical failures fail the run

Gate 5 is the one people skip. If the endpoint never tells you it truncated, you cannot detect truncation downstream. Ask for a deliberately tiny answer and check the reason field.

Gate 6 matters for budgets. You cannot audit a free allowance without per-call usage numbers.

The harness

Here is the whole thing. Standard library only, about 90 lines.

#!/usr/bin/env python3
"""preflight.py - fail-closed gates before a CLI trusts a hosted model."""
import json, os, sys, time, hashlib, urllib.request, urllib.error
from pathlib import Path

STAMP = time.strftime("%Y%m%dT%H%M%SZ", time.gmtime())
EVID = Path("preflight") / STAMP
EVID.mkdir(parents=True, exist_ok=True)

BASE = os.environ["MC_BASE_URL"].rstrip("/")
PATH = os.environ.get("MC_CHAT_PATH", "/v1/chat/completions")
KEY = os.environ["MC_API_KEY"]
MODEL = os.environ["MC_MODEL"]
BUDGET_MS = int(os.environ.get("MC_LATENCY_BUDGET_MS", "4000"))

results = []

def gate(name, ok, detail):
    results.append({"gate": name, "ok": bool(ok), "detail": detail})
    print(f"[{'PASS' if ok else 'FAIL'}] {name}: {detail}")

def call(messages, max_tokens=64, timeout=25):
    body = json.dumps({"model": MODEL, "messages": messages,
                       "max_tokens": max_tokens}).encode()
    req = urllib.request.Request(
        BASE + PATH, data=body,
        headers={"Content-Type": "application/json",
                 "Authorization": f"Bearer {KEY}"})
    t0 = time.time()
    with urllib.request.urlopen(req, timeout=timeout) as resp:
        raw = resp.read()
        status = resp.status
    return status, raw, (time.time() - t0) * 1000

# Gate 2 + 3: reachability and latency samples
samples = []
try:
    for _ in range(3):
        status, raw, ms = call([{"role": "user", "content": "ping"}], max_tokens=8)
        samples.append(round(ms, 1))
    (EVID / "latency.json").write_text(json.dumps({"model": MODEL, "samples_ms": samples}))
    gate("reachability", status == 200, f"status={status} model={MODEL}")
    gate("latency_budget", max(samples) <= BUDGET_MS, f"max={max(samples)}ms budget={BUDGET_MS}ms")
except Exception as exc:
    gate("reachability", False, repr(exc))
    gate("latency_budget", False, "not measured")

# Gate 4: schema conformance
SCHEMA_PROMPT = ('Reply with JSON only: {"ok": true, "n": 3}.')
try:
    _, raw, _ = call([{"role": "user", "content": SCHEMA_PROMPT}], max_tokens=48)
    (EVID / "schema-raw.txt").write_bytes(raw)
    parsed = json.loads(raw.decode())
    content = parsed["choices"][0]["message"]["content"]
    payload = json.loads(content)
    ok = set(payload) == {"ok", "n"}
    gate("schema_conformance", ok, f"keys={sorted(payload)}")
except Exception as exc:
    gate("schema_conformance", False, repr(exc))

# Gate 5: truncation visibility, gate 6: usage accounting
try:
    _, raw, _ = call([{"role": "user", "content": "Count from 1 to 200."}], max_tokens=5)
    parsed = json.loads(raw.decode())
    choice = parsed["choices"][0]
    (EVID / "truncation.json").write_text(json.dumps(choice))
    gate("truncation_visible", "finish_reason" in choice, f"finish_reason={choice.get('finish_reason')}")
    usage = parsed.get("usage") or {}
    gate("usage_accounting", "total_tokens" in usage, f"usage_keys={sorted(usage)}")
except Exception as exc:
    gate("truncation_visible", False, repr(exc))
    gate("usage_accounting", False, repr(exc))

# Gate 1: key presence, recorded last so it can never mask network results
gate("key_present", bool(KEY), "sha256 prefix=" + hashlib.sha256(KEY.encode()).hexdigest()[:8])

(EVID / "summary.json").write_text(json.dumps(results, indent=2))
failed = [r["gate"] for r in results if not r["ok"]]
print(f"evidence: {EVID}  failed: {failed or 'none'}")
sys.exit(1 if failed else 0)

The example output you would see is illustrative, not a measured run. Replace the endpoint path with whatever your provider documents.

Running it

export MC_BASE_URL="https://your-endpoint.example"
export MC_CHAT_PATH="/v1/chat/completions"
export MC_API_KEY="..."
export MC_MODEL="your-pinned-model-id"
export MC_LATENCY_BUDGET_MS="4000"
python3 preflight.py; echo "exit=$?"

Then wire it into the CLI you already have. One line at the top of your wrapper:

python3 preflight.py || { echo "model gate failed; using local fixtures"; exec ./fallback.sh; }

Now the CLI cannot run on an unverified endpoint. That is the whole point of fail-closed.

One failure fixture: the truncated object

Here is the shape that broke my build. The endpoint returned valid JSON with a cut-off inner string:

{"choices":[{"message":{"content":"{\"files\":[\"src/a.ts\",\"src/b"},
 "finish_reason":"length"}]}

Gate 4 fails this, because the inner content will not parse. Gate 5 passes, because finish_reason is present. That split matters. Truncation is visible; schema conformance is not. Keep them as separate gates so you know which one to fix.

If you strip finish_reason before parsing, gate 5 catches the real risk and tells you why.

A token ledger you can actually audit

Gate 6 gives you per-call usage. Multiply by call volume to see how long a free allowance lasts. The numbers below are my assumed workloads, not measured quotas.

Task	Calls/day	Tokens/call (assumed)	Tokens/day
Commit message drafting	40	350	14,000
Test-name suggestions	20	900	18,000
JSON repair pass	5	1,500	7,500
Total	65	-	39,500

Against a supplied 10,000,000-token free allowance, 39,500 tokens a day is roughly 250 days of that workload. That arithmetic is mine. The allowance figure is the project's claim, not my benchmark.

Log usage per call and sum it weekly. A budget you never count is a story, not a budget.

Rollback and abandonment criteria

Decide the exit before you need it.

If gate 4 fails twice on a pinned model in one day, switch that task to local fixtures.
If the latency budget fails for a full working day, move the task back to a local model.
If usage fields disappear, stop counting and stop trusting the free tier for anything billable-adjacent.
If the same prompt fails identically twice, do not retry it a third time. Store it as a regression fixture.

Write these down, in the repo, next to the script. Future you will not remember the thresholds.

Who should not use this

Skip this approach if you need documented latency SLAs, contractual data handling, or reproducible outputs across days. A hosted free tier cannot promise those, and gates only detect the gap, they do not close it.

Also skip it if your payloads contain customer data. Preflight gates check shape and timing, not data policy.

If you want a free endpoint to test the harness against, MonkeyCode publishes its repo, a free server option, and a free tier that the team lists at 10,000,000 tokens. Read the current docs before you pin a model id, because the lineup moves.

What is the one gate you would add as number eight, and what evidence file would it write? That answer decides whether my checklist is finished or just long.

Build a Handoff Card Before a Free-Tier CLI Leaves Your Laptop

Sam Rivera — Mon, 12 Oct 2026 22:50:04 +0000

I want to hand a friend one small CLI tonight. I still lack a host log and a ceiling line. Those two gaps are enough to ban the share.

A laptop pass is not a real handoff. A free server can sleep, and a free model can wander. I want a fail-closed card before I paste any repo link.

The job of the card

This card does not try to grade model quality. It answers one narrower question for a solo builder. Can another person run one task and stop cleanly?

You copy the checker, fill one JSON file, and run it. A missing field exits with code 2. A soft warning would only train you to ignore it.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode is the free-model lane and free server in this walkthrough. I am not stating a quota, a machine size, or a lasting plan. Those facts belong on the live console, not in a blog sentence.

If you cannot screenshot the ceiling today, take the ban. Leave that field blank and let the checker refuse you. A remembered number from a post is not evidence.

Gates you can actually fail

Read each gate out loud before you edit the JSON. If you cannot point at evidence, the gate is closed. Hope is not a field in this file.

Name the task in one sentence with one outcome. A second outcome means you need a second card.
Lock the paths the tool is allowed to touch. Any extra path in git status fails this gate.
Record the free-model ceiling you saw on today's console. An empty ceiling fails this gate on purpose.
Name the free server as the host under test. Write when you abandon it if the host sleeps.
Save the dry-run command and prove it refused writes. A dry-run that writes files is just a normal run.
Feed one known-bad input and store the refusal log. A quiet success on garbage fails this gate.
Name one command that restores the worktree cleanly. If rollback needs a hero, you are not ready.

Would you skip gate three because the console felt fine? That skip is the bug this checker exists to catch. A tired builder should not negotiate a blank field.

What proves the dry-run actually refused writes? A clean status log, saved beside the command, proves it. Your memory of a green terminal does not prove it.

Who rolls this back if you are offline tomorrow? A friend can, but only with a command you already rehearsed. If the answer is only you, the tool is not shared yet.

Evidence each gate must carry

A gate without a pasteable proof is still closed. Write the proof in the JSON, not in a chat scroll. If the proof lives only in your head, it does not count.

Task evidence is the sentence a friend can repeat. If they add a second job, the card is already wrong.
Path evidence is the short status after a dry-run. An empty status is the proof you actually wanted.
Ceiling evidence is a same-day line from the console. A blog number, including any in this post, is not proof.
Host evidence names the free server and the abandon trigger. Sleep, a blank ceiling, or a dropped session all count.
Dry-run evidence is the command plus a clean status. A written file means you failed closed too late.
Fixture evidence is the bad input and the exit code. Exit code 0 on garbage means the tool is unsafe.
Rollback evidence is a command you already ran once. Untested rollback text is only a wish.

Is a blank ceiling really safer than a wrong number? Yes, because a blank gets banned and a rumor gets shipped. A copied figure from an old post is worse than empty.

A friendly model will agree with a bad edit if you let it. That is the yes-man failure, and the fixture is the antidote. Retrying the same prompt is not evidence of a fix.

Fill the card in order

Do these steps on a clean branch only. Stop at the first blank field you hit. Do not backfill a number from memory tomorrow.

Write the task sentence and the allowed path list.
Open the free-model console and copy today's ceiling line.
Mark the free server as host and write the abandon rule.
Run the dry-run and confirm that no file changed.
Run the bad fixture and paste the refusal log.
Write the rollback command and rehearse it once locally.
Run the checker and keep exit code 2 until every field is real.

How long should this small handoff take you? Give it ninety minutes, then stop for the night. A second evening means the tool is not small enough yet.

The checker, labeled as a template

This script is a proposal you can run locally. It is not a benchmark, and it is not a hosted service. It only checks that required fields exist and flags are strict.

It does not read your worktree or call any model. You can still lie in a string field and earn a pass. The ban helps a tired builder, not a hostile one.

#!/usr/bin/env python3
"""Fail-closed handoff card. Template: fill fields from your own run."""
import json
import sys
from pathlib import Path

REQUIRED = [
    "task",
    "allowed_paths",
    "model_ceiling_seen",
    "ceiling_source",
    "host_kind",
    "abandon_rule",
    "dry_run_cmd",
    "dry_run_refused_writes",
    "bad_fixture_log",
    "rollback_cmd",
]

def load_card(path):
    data = json.loads(Path(path).read_text())
    missing = [key for key in REQUIRED if data.get(key) in (None, "", [])]
    return data, missing

def main():
    if len(sys.argv) != 2:
        print("usage: handoff_card.py card.json")
        return 2
    data, missing = load_card(sys.argv[1])
    if missing:
        print("BAN: missing evidence")
        for key in missing:
            print(f"- {key}")
        return 2
    if data["dry_run_refused_writes"] is not True:
        print("BAN: dry-run did not refuse writes")
        return 2
    if data["host_kind"] != "free_server":
        print("BAN: this card is only for a free server handoff")
        return 2
    paths = data["allowed_paths"]
    if not isinstance(paths, list) or not paths:
        print("BAN: allowed_paths must be a non-empty list")
        return 2
    print("PASS: one-task handoff may leave your laptop")
    print(data["task"])
    return 0

if __name__ == "__main__":
    raise SystemExit(main())

A pass shape, with placeholders called out

Replace every placeholder before you trust a PASS line. Shipping the sample JSON would be cheating the gate. The sample only shows the expected shape, nothing more.

{
  "task": "rewrite the README usage block only",
  "allowed_paths": ["README.md"],
  "model_ceiling_seen": "paste-console-line-from-today",
  "ceiling_source": "provider console, same calendar day",
  "host_kind": "free_server",
  "abandon_rule": "stop if the host sleeps or the ceiling line is blank",
  "dry_run_cmd": "python3 tool.py --dry-run --path README.md",
  "dry_run_refused_writes": true,
  "bad_fixture_log": "empty diff requested; tool exited 2; worktree clean",
  "rollback_cmd": "git checkout -- README.md"
}

Commands worth pasting into the README

Put this short sequence above the fold in the README. Your friend should not invent flags at midnight. Three commands are enough for the first careful share.

python3 handoff_card.py card.json
python3 tool.py --dry-run --path README.md
git status --short

Did status show a file outside the allowed list? Stop, fix the tool, and rebuild the card. A surprise file is a failed scope gate, not a nit.

The bad card you should keep

Store this fixture next to the checker in the repo. It looks nearly done, which is why it is dangerous. Your checker must ban this file on every run.

{
  "task": "rewrite the README usage block only",
  "allowed_paths": ["README.md"],
  "model_ceiling_seen": "",
  "ceiling_source": "",
  "host_kind": "free_server",
  "abandon_rule": "stop if the host sleeps",
  "dry_run_cmd": "python3 tool.py --dry-run --path README.md",
  "dry_run_refused_writes": false,
  "bad_fixture_log": "",
  "rollback_cmd": "git checkout -- README.md"
}

Run both lines and expect a hard ban. Exit code 2 is the success case for this fixture. A pass here means you delete the checker, not the fixture.

python3 handoff_card.py bad_card.json
echo $?

A small decision table

Use this table when you feel the urge to negotiate. The left column is the excuse you will hear. The right column is the only allowed move.

Excuse you will hear	Required move
Yesterday's console note is not today's evidence.	Recopy today's ceiling line or accept the ban.
A probable refusal is not a saved dry-run log.	Re-run the dry-run and keep the new log.
Usual uptime is not a written abandon rule.	Write the abandon rule or stop the share.
The bad input feels too silly to keep around.	Keep it, because quiet passes are the real bug.
An obvious rollback still needs a written command.	Write that command before you share the repo.

What a PASS still does not mean

A pass means the card is complete, not that the diff is right. You still read the README change with your own eyes. The checker never opened your files and never will.

It also does not freeze the free tier in place. Free model access and a free server can change quietly. That is why the ceiling source must include the day.

Next week you fill a new card or you do not share. I am not naming a model or quoting a token pack. I am not quoting a region, a chip, or a speed number.

If a post states those without today's primary page, treat it as stale. Your card should cite the console you saw, not this paragraph. Stale numbers are how a small share becomes a bad promise.

Who should not use this card

Skip this card if paying users depend on the CLI. One JSON file is a solo handoff, not a release train. You need owners, alerts, and a real rollback drill.

Skip this if the change touches secrets or production data. The fixture assumes a README-sized edit and nothing wider. A wider blast radius needs a different, stricter gate.

Skip this if you cannot rehearse rollback in one command. Sharing a tool you cannot undo turns favors into incidents. Keep that build on your laptop until rollback is boring.

Cost and time boundary

Budget ninety minutes and add zero new services. The checker is one file, and the card is one file. If you are writing a dashboard, you left the experiment.

Abandon the share when the free server will not stay awake. Abandon it when the free-model console hides the ceiling. Your local demo can remain a local demo without shame.

That is a clean exit, not a failure of nerve. Small tools need a stop rule more than they need a sequel. Write the stop rule on the card before you feel brave.

Before the next iteration

Which blank field shows up first on a free server? I want the ceiling line, the dry-run proof, or the fixture log. That answer changes the next checker, not a slogan around it.

MonkeyCode is one place offering that free model lane and free server. Read the live limits before you copy any number down. Then let the checker ban you when the evidence is thin.

Build a Path-Scope Ledger Before a One-File AI Edit

Sam Rivera — Sun, 11 Oct 2026 20:03:00 +0000

I want a one-file title fixer to stay inside one file. A model draft can still offer a second path beside it. Would I catch that slip on a tired weeknight?

I doubt it, so the gate has to catch the slip. The gate is a tiny path-scope ledger for one edit. It names every file the job is allowed to touch.

It refuses the rest and writes evidence only after a pass. A friendly diff is how small tools grow sharp edges. Scope creep is the bug I am trying to make loud.

Vibe-coded patches fail the same way, by touching an unnamed file. The model got faster, but the apply step did not get safer. A ledger is the small brake I want before that speed lands.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. I use MonkeyCode for two narrow jobs in this workflow. Free model access drafts the one-file patch as text only.

A free server runs the gate away from my laptop repo. I do not treat either option as a permanent promise. I also do not assume a named model or a fixed quota.

Check the current product docs before you depend on either. Those pages should beat any number you remember from a post.

What this ledger actually guards

This ledger is not a substitute for human review. It answers one blunt question before any apply command. Which exact paths may change during this single job?

A fuzzy answer means the job stops immediately. A clean diff with a wide path is still a failure. Missing evidence is a failure, not a soft warning.

Step 1: Freeze the allowed path

Pick one file and write it down before the model speaks. That file becomes the whole contract for tonight's edit. If you need a second file, start a second job.

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

Why freeze one file instead of a whole directory? A second file hides scope creep inside a friendly diff. Can you explain both edits in one honest sentence?

If the answer takes a paragraph, the job is already two jobs. Split them before you ask the model for help. A wide prompt invites a wide patch you did not request.

Step 2: Capture the proposal, not the apply

Ask the model for a unified diff and save that file. Do not apply it, commit it, or stage it yet. The saved diff is a proposal, not a permission slip.

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

The check command only validates that the patch can apply. It does not prove the path stays inside your allowlist. That proof belongs to the ledger in the next step.

Keep the model prompt boring on purpose for this job. Name the allowed file in the prompt text. Tell it to refuse every other path in the reply.

Step 3: Run the scope ledger

Save the script below as scope_ledger.py in the repo. It is a complete gate you can copy and run tonight. Treat it as a workflow artifact, not a measured outage story.

#!/usr/bin/env python3
"""Fail closed unless a proposed diff stays on the allowlist."""

import argparse
import json
import re
import sys
from pathlib import Path

SECRET = re.compile(
    r"(AKIA[0-9A-Z]{16}|-----BEGIN |api[_-]?key\s*[:=])",
    re.I,
)
DIFF_PATH = re.compile(r"^\+\+\+ b/(.+)$", re.M)


def load_allow(path: Path) -> set[str]:
    lines = path.read_text(encoding="utf-8").splitlines()
    return {line.strip() for line in lines if line.strip()}


def judge(allow: set[str], diff: str, max_files: int) -> dict:
    paths = DIFF_PATH.findall(diff)
    unique = sorted(set(paths))
    extra = sorted(set(paths) - allow)
    reasons: list[str] = []
    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,
    }


def main() -> int:
    parser = argparse.ArgumentParser(description="Path-scope ledger")
    parser.add_argument("--allow", required=True)
    parser.add_argument("--diff", required=True)
    parser.add_argument("--out", required=True)
    parser.add_argument("--max-files", type=int, default=1)
    args = parser.parse_args()
    card = judge(
        load_allow(Path(args.allow)),
        Path(args.diff).read_text(encoding="utf-8"),
        args.max_files,
    )
    out = Path(args.out)
    out.parent.mkdir(parents=True, exist_ok=True)
    target = out if card["pass"] else out.with_suffix(".fail.json")
    if not card["pass"] and out.exists():
        out.unlink()
    target.write_text(json.dumps(card, indent=2) + "\n", encoding="utf-8")
    print(json.dumps(card))
    return 0 if card["pass"] else 2


if __name__ == "__main__":
    sys.exit(main())

The script targets Python 3.9 or newer on purpose. Older interpreters will choke on the builtin type hints. Install nothing else, because the standard library is enough.

Run the ledger against the proposal before you touch git. Exit zero means the pass card was written to disk. Exit two means stop, because the pass card must not remain.

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

Would you let an apply script ignore that exit code? I would not, even when the diff is only a few lines. Wire the next command so a missing card aborts the shell.

Step 4: Keep a failure fixture

A gate without a red test is only a wish. Store a bad diff that touches a second path on purpose. The fixture also plants a fake key string so the sniff 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
python3 scope_ledger.py \
  --allow evidence/allowlist.txt \
  --diff fixtures/two-files.diff \
  --out evidence/scope-card.json
status=$?
echo "exit=${status}"
test "${status}" -eq 2
test -f evidence/scope-card.fail.json
test ! -f evidence/scope-card.json

This block is the expected fixture print, not a captured server log. Sort order on paths is alphabetical, so notes come first. If your print differs, fix the script before you trust a pass.

{"pass": false, "allow": ["src/titles.py"], "paths": ["src/notes.py", "src/titles.py"], "reasons": ["path-outside-allowlist:src/notes.py", "file-count-over-budget", "secret-pattern"]}
exit=2

You want exit code two from that fixture run. You also want the fail json file and no pass card. If this fixture passes, the ledger is lying to you.

Do not delete the fixture after a green demo. The red file is the regression lock for this script. Run it again after every edit to the script.

Step 5: Apply only behind the card

Read the pass card before any apply command runs. Reject the job when the pass field is missing or false. Then apply with the index flag and list the cached names.

test -f evidence/scope-card.json
python3 - << 'PY'
import json, sys
card = json.load(open("evidence/scope-card.json", encoding="utf-8"))
sys.exit(0 if card.get("pass") is True else 3)
PY
git apply --index proposal.diff
git diff --cached --name-only > evidence/staged.txt

Stop again if those cached names exceed the allowlist. The ledger already checked the diff text for path scope. This second look catches a sloppy apply that drifted anyway.

python3 - << 'PY'
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)
PY

Fail-closed rules you can copy

Copy these gates into the repo notes beside the script. Each row names the evidence file and the stop condition. A missing row is a hole, not a future improvement.

Gate	Evidence	Fail closed when
Path freeze	`evidence/allowlist.txt`	Missing, empty, or more than one path
Proposal saved	`proposal.diff`	Missing, empty, or `git apply --check` fails
Scope match	`evidence/scope-card.json`	Any path outside the allowlist
File budget	card field `paths`	More than one file in the diff
Secret sniff	card field `reasons`	Pattern hit, even on a placeholder
Apply lock	exit code `0`	Card missing, `pass` false, or staged name drifts

Three abandon rules sit next to that small table. Stop if the allowlist grows past a single directory. Stop if the model cannot emit a unified diff tonight.

Also stop if the free server cannot run the script. Waiting one night is cheaper than a surprise commit. Abandon the job rather than widening the path to proceed.

A crash is also a stop, because the shell sees a non-zero exit. Do not catch that error and print a friendly success line. Friendly success on a traceback is how quiet failures ship.

Where the free server fits

I do not run unreviewed model output on my daily laptop. The free server is only a canary host for this gate. Copy the script, the allowlist, and the diff over there.

Run the ledger on that host and copy back the card. Leave the patch file behind if the card says fail. Free model access drafts text and never earns apply rights.

python3 scope_ledger.py \
  --allow evidence/allowlist.txt \
  --diff proposal.diff \
  --out evidence/scope-card.json

If the server is down, the job waits until it returns. I will not quote a token cap, a hardware size, or an uptime promise. Those facts change, so read the current MonkeyCode docs before you plan around them.

If the free path is gone, keep the ledger anyway. Run it locally on a scratch clone with the same fixture. The gate matters more than the host that executes it.

Time box and rollback

Budget thirty minutes to add the script and the fixture. Budget ten more minutes for one dry-run on a scratch branch. If setup passes forty minutes, drop the idea for today.

Rollback here is deletion, not a clever migration plan. Remove the proposal diff and leave the branch unmerged. Delete a pass card if you never applied the patch.

Nothing in this workflow should touch the main branch. If main moved, you already skipped a gate somewhere. Reset the scratch branch and start from the allowlist again.

Who should skip this

Skip this if you need a multi-service release tonight. Skip it if counsel expects a formal control framework. Skip it when the edit renames symbols across many files.

The ledger will scream on a wide rename, and it should. Also skip it if you cannot read a unified diff yet. Learn the apply check before you trust any card output.

Solo builders with one file and a scratch branch are the fit. Small teams that already review every hunk can still use the red fixture. Everyone else should keep a human diff review and stop here.

Limits I am not hiding

The secret check is a blunt regular expression, nothing more. It misses real leaks and can false-alarm on documentation. Treat every hit as a stop, then read the hunk yourself.

The allowlist does not judge behavior inside the allowed file. A one-file diff can still delete a function you need. Read the hunk, because the card only proves path scope.

A stale fail file can sit beside a new pass card. Delete both cards before each run if that mix confuses you. The exit code is the real lock, not the leftover filename.

I have not published timing numbers for this small script. It is a few dozen lines, so time it on your own machine. Do not treat a local sketch as your benchmark result.

MonkeyCode is one way to get a free draft and a free server run. It is not required for the ledger to stay useful. Any local model plus a scratch clone can feed the same gate.

If a free MonkeyCode server is already on your account, start there. Point the red fixture at that host before any green run. A red run is the only demo that should impress you.

What single path would you freeze before the next model edit? Which second path keeps sneaking into your generated diffs?

Build a Fail-Closed Ship Card Before an AI CLI Leaves Dry-Run

Sam Rivera — Sat, 10 Oct 2026 16:10:05 +0000

I stare at a green dry-run and still hesitate to ship. One passing fixture is not a write-mode signal for me. Would you let that helper touch a shared branch tonight?

A solo CLI can look finished and still be unsafe to run. The missing piece is saved evidence, not another clever prompt. I keep a ship card beside the tool for that pause.

What the card decides

The card is a small JSON file committed next to the CLI. It names gates, proof files, and a stop rule. If any proof is missing, the process exits.

I am not asking the model to bless itself. I am asking a local script to refuse the run. Can a missing proof file count as a feature here?

This is a template you can copy tonight. It is not a benchmark from my laptop. Fill every field from a run you actually saved.

Four gates, then write mode

1. Lock the paths

Name every directory the CLI is allowed to read. Name every file the CLI is allowed to write. Anything outside those lists is out of scope.

I keep the write list painfully short on purpose. A helper that may touch the whole repo is not ready. Why hand it the whole tree this early?

2. Save the dry-run

Run the helper once with writes turned off. Save stdout, the patch, and the exit code. Put those three files under an evidence directory.

An empty evidence directory means you stop immediately. A chat log is not a patch you can review. Did you actually save the diff this time?

3. Bound the blast radius

Set a maximum changed-file count on the card. Set a maximum added-line count beside it. Refuse deletes unless the card explicitly allows them.

A surprise rename should fail this gate immediately. A secret-shaped string in the patch should fail it too. Would you merge that change while half asleep?

4. Declare the exit

Write the exact command that restores the tree. Write the condition that abandons the whole experiment. Write what you do if the runner is gone.

No exit plan means the card is still incomplete. I would rather shelve the branch than improvise. Shipping without rollback is how tiny tools linger.

Decision table

Gate	Evidence you commit	Fail closed when
Path lock	allowed reads and writes	a list is empty, or a patch path is outside
Dry-run	stdout, diff.patch, exit code	any file is missing or the code is not zero
Blast radius	max files, max lines, delete flag	caps are blank, or a delete appears
Exit plan	rollback command, abandon rule	either string is empty or untested

Read the row before you argue with the script. The script is the boring coworker in this workflow. Are you willing to lose an argument to it?

Steps before write mode

Create a branch and a fresh evidence directory.
Run the CLI in dry-run and redirect stdout to a file.
Save the git diff, even when the diff is empty.
Write the exit code into exit_code.txt with no extra words.
Fill ship-card.json from those files, not from memory.
Run the checker and accept a red result as a real gate.
Consider write mode only on that same allowlist.

Skip a step and the card becomes theater. A skipped step turns the later review into mush. Which step do you usually skip under time pressure?

Copy the checker

This script is a starter, not a sandbox product. It checks presence, a zero exit, deletes, and write paths. It does not call a network, and it does not score a model.

#!/usr/bin/env python3
"""Fail-closed ship card checker. Template, not a benchmark."""
import json
import sys
from pathlib import Path

REQUIRED = [
    "allowed_reads",
    "allowed_writes",
    "evidence_dir",
    "max_changed_files",
    "max_added_lines",
    "allow_deletes",
    "rollback_cmd",
    "abandon_if",
]

def fail(msg: str) -> None:
    print(f"SHIP_CARD_FAIL: {msg}")
    raise SystemExit(2)

def main() -> None:
    card_path = Path(sys.argv[1] if len(sys.argv) > 1 else "ship-card.json")
    if not card_path.is_file():
        fail(f"missing card: {card_path}")
    card = json.loads(card_path.read_text(encoding="utf-8"))
    for key in REQUIRED:
        if key not in card or card[key] in ("", [], None):
            fail(f"empty gate: {key}")
    for key in ("max_changed_files", "max_added_lines"):
        if not isinstance(card[key], int) or card[key] < 0:
            fail(f"{key} must be a non-negative integer")
    evidence = Path(card["evidence_dir"])
    needed = ["stdout.txt", "diff.patch", "exit_code.txt"]
    for name in needed:
        file = evidence / name
        if not file.is_file() or file.stat().st_size == 0:
            fail(f"missing evidence: {file}")
    code = (evidence / "exit_code.txt").read_text(encoding="utf-8").strip()
    if code != "0":
        fail(f"dry-run exit was {code}")
    diff = (evidence / "diff.patch").read_text(encoding="utf-8")
    if "diff --git" not in diff:
        fail("diff.patch has no git diff header")
    if card["allow_deletes"] is not False and card["allow_deletes"] is not True:
        fail("allow_deletes must be a boolean")
    if not card["allow_deletes"] and "\ndeleted file mode " in f"\n{diff}":
        fail("delete found but allow_deletes is false")
    writes = card["allowed_writes"]
    for line in diff.splitlines():
        if not line.startswith("+++ b/"):
            continue
        path = line[6:]
        allowed = path in writes or any(
            path.startswith(prefix.rstrip("/") + "/") for prefix in writes
        )
        if not allowed:
            fail(f"write outside allowlist: {path}")
    print("SHIP_CARD_OK")

if __name__ == "__main__":
    main()

Sample card

{
  "allowed_reads": ["src/", "tests/fixtures/"],
  "allowed_writes": ["src/format.py"],
  "evidence_dir": "evidence/dry-run-01",
  "max_changed_files": 1,
  "max_added_lines": 40,
  "allow_deletes": false,
  "rollback_cmd": "git checkout -- src/format.py",
  "abandon_if": "runner missing, empty diff, or secret-like token in patch"
}

The numeric caps must be integers, or the checker stops. It still does not count lines inside the patch. Add that counter before you trust write mode.

Commands

Make the evidence folder, then run the checker. A missing patch should end with exit code 2. Do not catch that error and keep going.

mkdir -p evidence/dry-run-01
python3 ship_card.py ship-card.json
echo $?

Capture a real dry-run with the commands below. Adjust the CLI name to your own tool. Keep writes off until the card is green.

python3 rewrite_cli.py --dry-run src/format.py > evidence/dry-run-01/stdout.txt
printf '%s\n' "$?" > evidence/dry-run-01/exit_code.txt
git diff -- src/format.py > evidence/dry-run-01/diff.patch

Save the CLI status before any later command runs. Otherwise you will record git, not the helper. rewrite_cli.py is only a placeholder name.

Failure fixture

Use a bad patch when you want a guaranteed red run. This one deletes a file the card should protect. Your card should reject it if deletes are forbidden.

diff --git a/src/format.py b/src/format.py
deleted file mode 100644
index 1111111..0000000
--- a/src/format.py
+++ /dev/null
@@ -1,3 +0,0 @@
-def normalize(text):
-    return text.strip()

Point evidence_dir at that folder and rerun the checker. Confirm the printed failure and the non-zero exit. Then point the card back at the good folder.

Also search the patch before you widen writes. The starter script does not scan for secrets. A green card can still hide a leaked key.

rg -n "AKIA|sk-|BEGIN PRIVATE" evidence || echo "no obvious token"

Add that search to your own local wrapper. I would not call the card done without it. Did the bad fixture fail loudly on your machine?

A free runner is just another field

Disclosure: This article was prepared as part of MonkeyCode's product outreach. I treat MonkeyCode free model access as one optional dry-run runner. A free server option can host that small canary off your laptop.

I will not invent a token cap, a model name, or a hardware tier. Those two availability claims are only useful after you read them today. A stale screenshot is a failed evidence gate.

Quotas, names, and duration can change without this article updating. If you use that path, add only fields you personally verified. Leave them blank when the page will not load.

Blank means abandon the write, not guess a limit. The checker never calls MonkeyCode on your behalf. You still run your own command on the machine.

{
  "model_access": "free-model-access",
  "compute": "free-server-option",
  "limits_checked_on": "YYYY-MM-DD",
  "limits_source": "account page reviewed today"
}

The card only records that the limits were looked up. Remove the product name and the four gates still stand. Path locks do not need a vendor to matter.

If MonkeyCode is the runner you picked, open the account page first. Paste only the free-model and free-server facts you can see today. Then let the checker argue, not your memory.

Time box and rollback

Give this experiment one evening, not an open-ended week. I would stop after two red fixtures in a row. More retries usually mean the task itself is muddy.

Practice the rollback before you actually need it. Dirty status after rollback is an abandon signal. Do not continue on a tree you cannot explain.

git status --short
git checkout -- src/format.py
git status --short

If the second status is not clean, shelve the branch. Write the reason into the abandon_if field. Tomorrow you should not have to guess why it stopped.

Who should not use this

Do not use this card on customer data, payments, or auth code. Do not use it as a security audit or a compliance pack. Do not point it at secrets or production credentials.

Skip it when your team already has a required change tool. A second checklist will rot within a week. Also skip it if you cannot store a local diff.

Free model access can be wrong, slow, or simply unavailable. A free server option can vanish during the canary. This card does not promise uptime, capacity, or a lasting free tier.

Limits you should know

The path check is plain string matching, not a real sandbox. A tricky relative path can still slip through it. Treat the allowlist as a seatbelt, not a vault.

Line caps and file caps are stored, not counted, in this version. That is a real gap, not a footnote to ignore. Add counters before write mode, or stay in dry-run.

I am not publishing timings, prices, or model comparisons here. I do not have a fresh primary measurement to cite. If you need numbers, measure them yourself and date the note.

One pass today

Copy the checker, the sample card, and the bad fixture. Run the red case first, then one dry-run of your own CLI. Stop when a required field is still empty.

What evidence file is still missing before you allow writes? That gap is the next build, not a new feature.

Build a Receipt Card Before a Vibe-Coded CLI Leaves Scratch

Sam Rivera — Fri, 09 Oct 2026 11:52:24 +0000

Tonight I am writing a gate, not a victory lap. The fixture is a small CLI draft on a scratch branch. A free model may write that first pass. One sample run can still print a neat table. Would you merge on that smile alone? I would not ship it on a smile.

DEV is full of vibe-code arguments this week. I am not relitigating portfolios or website taste. My fight is smaller, and meaner. A solo CLI can look finished after one lucky run. Where is the receipt that proves you can leave?

The failure I keep seeing

You ask for a status command. The draft prints three rows and exits zero. Your shoulders drop. The branch name even says wip-ok. Did the happy path become a test? It did not.

I want one small thing you can try today. Fill a receipt card before the diff leaves scratch. If the card fails, you delete the branch. That is the clean exit. No heroics, and no silent promote.

What the free lane is allowed to do

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode's free model access can draft the CLI text. Its free server option can host the scratch run. I am not stating a token quota, a chip type, or an uptime number. I have not verified those for this draft. Treat both free options as a cheap lane, not a promise.

Would you put real keys on that lane? I would not. The free server is a scratch box. The free model is a drafter. You still own the receipt, the rollback, and the abandon line.

Time box for this pass: forty-five minutes. Cost box: the free lane only, or you stop. If either box breaks, the branch dies. That boundary is part of the card, not a footnote.

The seven files that count as evidence

Keep these files next to the CLI. Empty files do not count. Secrets do not count. A screenshot of a green terminal does not count.

File	Evidence it must hold	Fail closed when
`GOAL.txt`	One job, one user, one output	The goal names two products
`BUDGET.txt`	Forty-five minutes, free lane only	A paid hop appears
`FIXTURE.txt`	Sanitized sample input	A key or password shape appears
`REPRO.md`	Commands that redo the failure	The steps need your laptop memory
`DIFF_SCOPE.txt`	Files the draft may touch	A path outside the CLI appears
`ROLLBACK.txt`	Exact undo commands	Undo is "I will figure it out"
`ABANDON.txt`	The line that kills the branch	You cannot say when to quit

This table checks presence and shape. It does not prove the CLI is correct. You still read the diff. A gate that pretends to judge quality will lie to you.

Numbered steps

1. Write the abandon line first

Open ABANDON.txt before you prompt. Mine says the branch dies after two failed gate runs. It also dies if the free server cannot take the scratch job. Why first? Because hope gets louder after a pretty table.

2. Bound the draft

Put the goal in one sentence. Name the command, the input file, and the output. If you cannot fit it, the CLI is already too big. Split it, or walk away.

3. Draft on the free model lane

Ask for one file, not a framework. Paste your goal and your fixture. Refuse extra services, daemons, and hidden network calls. Did the draft add a dependency you did not name? That is a scope miss. Record it in DIFF_SCOPE.txt, or revert.

4. Run once on the free server

Copy the CLI to the free server scratch box. Run the command from REPRO.md. Save stdout and the exit code into that same file. Do not point the box at production hosts. Do not mount a real home directory.

5. Run the receipt gate locally

The script below is a template. I am not pasting a timed production log from a live server. Run it on your receipt folder. A missing file must exit non-zero.

6. Read, promote, or delete

If the gate passes, read every changed line anyway. Promote only the paths in DIFF_SCOPE.txt. If the gate fails twice, run the rollback and delete the branch. Would a third prompt save you? Maybe. The card still says stop.

The gate script

Save this as receipt-gate.sh beside the seven files. It is intentionally boring. Boring is the point.

#!/usr/bin/env bash
# Template: fail closed unless the receipt files exist and look safe.
set -euo pipefail

root="${1:-.}"
need=(
  GOAL.txt
  BUDGET.txt
  FIXTURE.txt
  REPRO.md
  DIFF_SCOPE.txt
  ROLLBACK.txt
  ABANDON.txt
)

for f in "${need[@]}"; do
  path="$root/$f"
  if [[ ! -s "$path" ]]; then
    echo "FAIL closed: missing or empty $f" >&2
    exit 1
  fi
done

if grep -Eiq 'sk-|api_key|password|BEGIN PRIVATE' "$root/FIXTURE.txt"; then
  echo "FAIL closed: fixture looks like a secret" >&2
  exit 2
fi

if grep -Eq '^[^#[:space:]]' "$root/DIFF_SCOPE.txt" && \
   grep -Ev '^[[:space:]]*(#|$)' "$root/DIFF_SCOPE.txt" | \
   grep -vqE '^[A-Za-z0-9_./-]+$'; then
  echo "FAIL closed: scope has an odd path" >&2
  exit 3
fi

echo "PASS: receipt present. Still review the diff yourself."

Make it executable, then point it at the folder.

chmod +x receipt-gate.sh
./receipt-gate.sh .

A pass line is not a merge approval. It only says the receipt exists. You can still hate the code. You should, at least once.

A failure fixture you can copy

Create a bad fixture on purpose. Confirm the gate screams. Then fix the file. This is the drill, not the product.

mkdir -p /tmp/receipt-drill && cd /tmp/receipt-drill
printf 'Show disk free space for one path.\n' > GOAL.txt
printf '45 minutes. Free lane only. Stop if paid.\n' > BUDGET.txt
printf 'path=/tmp\n' > FIXTURE.txt
printf '## Repro\n\npython3 dfcli.py --path /tmp\n\nExpect exit 0.\n' > REPRO.md
printf 'dfcli.py\n' > DIFF_SCOPE.txt
printf 'git switch -\ngit branch -D scratch-df\n' > ROLLBACK.txt
printf 'Abandon after two failed gate runs.\n' > ABANDON.txt

Now poison the fixture and watch the exit code.

printf 'path=/tmp\napi_key=demo-not-real\n' > FIXTURE.txt
./receipt-gate.sh /tmp/receipt-drill; echo "exit:$?"

You want FAIL closed and a non-zero exit. Restore path=/tmp only. Run the gate again. If you skip this drill, you own a script you have never seen fail. That is not a gate. That is a poster.

Fail-closed rules I will not bend

No receipt file, no promote. A chat log is not a file.
No secret-shaped fixture, no run. Sanitize before the free server sees it.
No path outside DIFF_SCOPE.txt, no commit. Extra files are a new draft.
No second budget, no retry. The free lane is the whole wallet here.
No human read, no merge. The script cannot see a bad flag name.

Who should skip this approach? Skip it if the CLI touches payments, customer data, or production credentials. Skip it if your team needs a formal change board. Skip it if you wanted the script to score code quality. This card is for a solo scratch CLI, not a release train.

Limits, stated plainly

The grep for secrets is a tripwire, not a scanner. A clever leak can still pass. The free model can invent flags your fixture never hits. The free server can refuse the job, or go away, and this draft does not claim a duration. I did not benchmark latency, cost, or model quality here. If you need those numbers, measure them yourself and date the note.

Rollback stays dumb on purpose.

git switch -
git branch -D scratch-df

If the branch never existed on a remote, you are done. If you already pushed, delete the remote branch too. Then stop. Do not "just try one more prompt" after ABANDON.txt fires.

What I would add next

The card still misses a field for flaky output. A table that changes column order would pass this gate. Which missing field would make you abandon a draft faster: a golden output file, a timeout, or a banned-dependency list?

If MonkeyCode's free model lane and free server already sit in your scratch flow, drop this card on the next CLI. Tell me the gate you had to add. I will keep the next version smaller, not louder.

Build a Cutover Checklist Before a Dry-Run Hits a Free Server

Sam Rivera — Thu, 08 Oct 2026 09:07:56 +0000

Your local changelog helper just printed a clean note. You want that same script on a free server before lunch. Would you ship the swap with no receipt at all?

I would not ship that swap on a hunch. A local green run is not a real cutover. This card is the receipt I would require first.

I am not inventing an outage, a bill, or a benchmark. Treat the script below as a proposal you can paste. Run it in a scratch repo before you trust the exit code.

The decision in front of you

You are allowing one swap, and only that swap. The dry-run may call a hosted model on a free path. It may also sit on a free server option.

It may not write to main or open a pull request. It may not touch customer notes or private keys. Does that scope feel almost too small to bother?

Small is the point of a solo cutover. You can finish the card before the laptop sleeps. If the five proof files will not fit in one sitting, abandon the attempt.

Where the hosted path enters

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

I place MonkeyCode in one spot in this workflow. It is the free model path and the free server option. The operator supplied those two availability claims only.

I will not invent model names or token caps here. I will not invent box sizes or a free-tier duration. Need the live numbers before you boot anything?

Read the project docs on the day you actually run. A token headline from a launch post goes stale fast. Treat that headline as a claim you must recheck.

Pull the product name out and these gates still stand. Any hosted model with a staging box can use them. The operator also describes the project as open source.

I am not pasting a star count or a repo URL. Inspect the tree yourself if you care about the license. A badge is not evidence for this cutover.

Files this card needs

Keep the cutover card inside the repo you already ship. Three paths are enough for a one-person job. You do not need a platform team for this.

The status file stores the gate flags you flip. The evidence folder stores the proof files beside it. The checker exits non-zero when any gate stays open.

No proof file means the cutover fails closed. A missing key means the cutover fails closed too. A production-looking host means the same hard stop.

Would you rather crash in CI than explain a bad note? I would take that early crash every time.

1. Freeze one fixture

Do not point the first remote call at a live ticket. Use one public line you can commit without fear. A changelog fragment is enough fuel for this drill.

mkdir -p cutover/fixtures cutover/evidence
printf '%s\n' 'feat: add retry budget to the importer' > cutover/fixtures/input.txt

Can a teammate rerun that file next week alone? If the answer is no, this gate stays shut. A fixture only you can find is not frozen.

2. Save the offline note

Run your helper with the network disabled first. If you have no helper yet, write the note by hand. The gate cares about the file, not a vendor SDK.

printf '%s\n' 'Add a retry budget to the importer.' > cutover/evidence/local.txt
test -s cutover/evidence/local.txt

Keep stdout only, and drop every secret before saving. Empty output leaves this gate closed on purpose. A note that names a customer leaves it closed too.

You want a dull sentence, not a private diary. The handwritten line above is a stand-in for your real offline run. Swap it for real stdout when you have it.

3. Shadow one hosted reply

Call the free model once, then stop calling it. Save the reply next to the local note. Do not post either file to chat or to main.

printf '%s\n' 'Add a retry budget to the importer now.' > cutover/evidence/remote.txt
diff -u cutover/evidence/local.txt cutover/evidence/remote.txt > cutover/evidence/diff.txt || true

That printf is a stand-in, not a live API call. Replace it with your real one-shot command when the docs check out. Did the remote note invent a version number?

Did it drop the fixture verb you froze earlier? Leave the remote flag false until both answers are no. One extra adjective in the note is fine.

A brand new release claim is not fine. Spend one remote call on this fixture, then stop. A second call is already past this card's cost boundary.

4. Scan your own fixture

The free server may run the checker for you. It still must not hold your production keys. Write the scan result even when the scan looks clean.

if grep -R -n -E 'sk-|API_KEY|BEGIN PRIVATE' cutover/fixtures cutover/evidence; then
  echo HIT > cutover/evidence/secret_scan.txt
else
  echo CLEAN > cutover/evidence/secret_scan.txt
fi

A hit is not a task you fix after launch. Delete the bad file, rotate the key, and stop. Why keep a cutover alive after a leak line?

This grep is a tripwire for your own drill files. It is not a company-wide scanner and it will miss clever leaks. If your fixture needs a clever scanner, you are holding the wrong text.

5. Pin a staging host

Write the host name you will actually boot. Reject names that look like the production box. A free server option is not a shared-hostname license.

printf '%s\n' 'staging.example.test' > cutover/evidence/host.txt

A leading prod label fails the checker immediately. The word production inside the name fails it too. Use a name you can delete without paging anyone.

6. Fill the status file

Flip a flag only after the matching proof exists. Leave every unfinished flag set to false for now. The sample below is supposed to fail the run.

{
  "fixture_frozen": true,
  "local_saved": true,
  "remote_saved": false,
  "no_secrets": true,
  "staging_host_only": false,
  "abandon_if": "any gate false or any evidence file missing"
}

Do you see the false fields in the sample? That card is not allowed to deploy anywhere. A half-true JSON file is how quiet launches happen.

The flag must be JSON true, not the string true. A string true will fail the checker on purpose. Save this file beside the checker before you run anything.

7. Run the fail-closed checker

Paste the script into the checker path shown below. It is a proposal, not a service I host for you. I have not timed it, and I will not pretend I did.

#!/usr/bin/env python3
"""Fail closed unless every cutover gate has evidence."""
import json
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parent
STATUS = ROOT / "status.json"
EVIDENCE = {
    "fixture_frozen": ROOT / "fixtures" / "input.txt",
    "local_saved": ROOT / "evidence" / "local.txt",
    "remote_saved": ROOT / "evidence" / "remote.txt",
    "no_secrets": ROOT / "evidence" / "secret_scan.txt",
    "staging_host_only": ROOT / "evidence" / "host.txt",
}
REQUIRED = list(EVIDENCE)

def fail(msg: str) -> None:
    print(f"CUTOVER_FAIL {msg}")
    sys.exit(2)

def main() -> None:
    if not STATUS.is_file():
        fail("missing status.json")
    try:
        data = json.loads(STATUS.read_text())
    except json.JSONDecodeError:
        fail("status.json is not valid JSON")
    if not isinstance(data, dict):
        fail("status.json must be an object")
    for gate in REQUIRED:
        if gate not in data or data[gate] is not True:
            fail(f"gate closed {gate}")
        path = EVIDENCE[gate]
        if not path.is_file() or path.stat().st_size == 0:
            fail(f"empty evidence {path.name}")
    scan = (ROOT / "evidence" / "secret_scan.txt").read_text()
    if "HIT" in scan:
        fail("secret scan hit")
    host = (ROOT / "evidence" / "host.txt").read_text().strip()
    if host.startswith("prod.") or "production" in host:
        fail("host looks like production")
    print("CUTOVER_OK")

if __name__ == "__main__":
    main()

python cutover/check_cutover.py; echo "exit=$?"

You want exit code 2 while the remote flag is false. That red exit is the drill, not a bug. Only a full card should print the ok line.

8. Break a proof file on purpose

Rename the host proof, run the checker, then restore it. This rename is the failure fixture for the card. A checker you never break is an untested checker.

mv cutover/evidence/host.txt cutover/evidence/host.txt.bak
python cutover/check_cutover.py; echo "exit=$?"
mv cutover/evidence/host.txt.bak cutover/evidence/host.txt

Did the job stay green after that rename? Then the checker is not actually on the job. Wire it to the step that would boot the server.

How to read the red line

A missing status file means you never started the card. A closed remote flag means the shadow note is not accepted yet. An empty host file means the host pin is still missing.

A secret scan hit means you stop and rotate keys. A production-looking host means you rename before any boot. None of these lines are warnings you click through.

Abandon rules

Stop when any gate flag is still false. Stop when any evidence file is missing or empty. Stop when the secret scan file contains a hit.

Stop when the host name looks like production. Also stop after two identical errors on the free path. Do not loop until a token headline is exhausted.

A retry storm is a quiet cost, even on a free option. Set a clock for one sitting, then walk away. If the shadow diff is still unexplained, abandon the cutover.

Come back later with a smaller fixture file. That exit is a clean stop, not a personal failure. Rollback is just the false flags plus no server boot.

Who should skip this card

Skip this card if you need a contractual uptime promise. A free server option is availability, not an SLA. Skip it if you need a signed audit trail tomorrow.

Skip it when the prompt holds customer text or private keys. This card never makes that kind of input safe. Skip it if the job must write files or push tags.

Those actions need a different permit than this one. Skip it if your team will ignore a red exit code. A checklist that nobody runs is just theater.

Limits to say out loud

The checker does not score the summary quality at all. A human still has to read the saved diff. I am not publishing accuracy numbers in this draft.

I did not run a benchmark, so I will not fake one. Free model access can change without a fresh blog post. The free server option can change the same quiet way.

The host check is only a string tripwire, not DNS policy. A weird alias can still slip past that string. Write the doc date only after you open the docs.

Do not commit a date you did not actually check. If that free path is already in your toolbox, use it here. Run this card before the first server boot.

Which gate fails first when you try this on your repo?

Build a Scratch-Exit Checklist for a Free-Model Patch

Sam Rivera — Thu, 08 Oct 2026 06:23:16 +0000

I wanted one gate before a free model edited code. The budget was zero extra paid services this week. The missing piece was evidence, not another clever prompt.

Solo builders still ship a tiny tool the same day. A same-day patch can feel like real progress. Then the diff lands with no rollback note attached.

Would you merge a patch that cannot be undone? I would not, yet the shortcut still looks tempting. Speed without an exit is how small tools rot.

What a free run is not

A free model can draft a small patch today. A free server can host one scratch run tonight. Neither availability claim counts as a production permit.

Did you write the exit path before the run started? If not, the job is still only a draft. A draft does not get to touch main.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. Two operator-stated options are the only product claims here. Those options are free model access and a free server.

I state no token quota, hardware size, uptime, or permanence. The operator also describes MonkeyCode as open source. I will not link a repository I have not verified here.

Use the install docs you already trust for setup steps. Re-check those docs on the day you actually run. Terms for a free option can move without a warning.

The promise and the clean exit

You get one command that fails closed on purpose. Missing evidence returns exit code two every time. A bad marker also returns exit code two.

Only a complete pass is allowed to return zero. The time box for this exercise is sixty minutes. The cost box is local files and no paid calls.

Abandon the job if scope evidence cannot be shown. Abandon it if rollback or a human ack is missing. Do not delete a red gate just to look green.

Step 1: Write the evidence contract

Start inside a scratch directory, never on main. Ask what would prove this job is still small. If you cannot answer, stop before any model runs.

Save this contract in the same folder as the checker. It is a template, not a live audit record. Change the scope line to match your real task.

# readiness.yml — template, not a live audit record
job: side-project-patch
scratch_dir: ./scratch
fail_closed: true
evidence:
  scope_file: evidence/scope.txt
  secret_scan: evidence/secret-scan.log
  rollback: evidence/rollback.md
  cost_cap: evidence/cost-cap.txt
  server_note: evidence/server-ephemeral.txt
  human_ack: evidence/human-ack.txt
gates:
  - id: scope
    evidence: scope_file
    must_contain: "OUT OF SCOPE"
  - id: secrets
    evidence: secret_scan
    must_contain: "NO_HITS"
  - id: rollback
    evidence: rollback
    must_contain: "git restore"
  - id: cost
    evidence: cost_cap
    must_contain: "ABORT_OVER"
  - id: server
    evidence: server_note
    must_contain: "EPHEMERAL"
  - id: human
    evidence: human_ack
    must_contain: "ACK"

Each gate needs a real file and a visible marker. A blank file is not evidence of a review. Why trust a file that never names a boundary?

Step 2: Plant the failure fixture

I want the red path before any green path. Create the evidence folder, then omit one required file. The missing human ack is the failure fixture.

The gate must fail while that ack file is absent. If the checker passes, stop and fix the script. A green result on a broken fixture is useless.

mkdir -p evidence scratch
printf 'IN SCOPE: README typos only\nOUT OF SCOPE: auth, billing, migrations\n' > evidence/scope.txt
printf 'scanner=local-grep\nNO_HITS\n' > evidence/secret-scan.log
printf 'rollback: git restore --source=HEAD --worktree -- path\n' > evidence/rollback.md
printf 'cap: local scratch only\nABORT_OVER: any paid call or secret file\n' > evidence/cost-cap.txt
printf 'EPHEMERAL: free server is scratch, not a system of record\n' > evidence/server-ephemeral.txt
# human-ack.txt is intentionally missing

Step 3: Run the fail-closed checker

The checker below is a proposal you can run locally. It uses only the Python standard library on purpose. I am not claiming a benchmark or a model score.

#!/usr/bin/env python3
"""ready_gate.py — fail closed unless every evidence marker exists.

Proposal script. Not a measured production control.
"""
import sys
from pathlib import Path

GATES = [
    ("scope", "evidence/scope.txt", "OUT OF SCOPE"),
    ("secrets", "evidence/secret-scan.log", "NO_HITS"),
    ("rollback", "evidence/rollback.md", "git restore"),
    ("cost", "evidence/cost-cap.txt", "ABORT_OVER"),
    ("server", "evidence/server-ephemeral.txt", "EPHEMERAL"),
    ("human", "evidence/human-ack.txt", "ACK"),
]

def check(root: Path) -> int:
    failed = False
    for name, rel, marker in GATES:
        path = root / rel
        if not path.is_file():
            print(f"FAIL {name}: missing {rel}")
            failed = True
            continue
        text = path.read_text(encoding="utf-8", errors="replace")
        if not text.strip() or marker not in text:
            print(f"FAIL {name}: missing marker {marker!r}")
            failed = True
            continue
        print(f"PASS {name}")
    if failed:
        print("RESULT fail-closed")
        return 2
    print("RESULT pass")
    return 0

if __name__ == "__main__":
    root = Path(sys.argv[1]) if len(sys.argv) > 1 else Path(".")
    raise SystemExit(check(root))

Run the checker from the folder that holds evidence/. You should see a human-gate failure and exit two. Did a missing file somehow slip through as a pass?

python3 ready_gate.py .
echo "exit=$?"

Then the script is wrong and this exercise stops. Do not continue to a model call after a bad fail. Fix the checker before you trust any later green.

Step 4: Add the human ack

A human ack is a sentence you can defend later. It is not a vibe, a hunch, or a shrug. Write it only after you read the planned diff.

printf 'ACK: I read scope, rollback, and the secret scan\n' > evidence/human-ack.txt
python3 ready_gate.py .
echo "exit=$?"

Exit zero means the files exist and the markers match. It does not mean the patch itself is correct. Can you see the gap between those two claims?

Step 5: Bind the run to scratch

Keep every model write inside the scratch directory only. Copy only files already named in the scope note. Refuse the run whenever the readiness gate is red.

python3 ready_gate.py . || exit 2
test -d scratch || mkdir scratch
cp README.md scratch/README.md

If you use a free server, treat that box as disposable. The server note must contain the marker EPHEMERAL. Do not store the only copy of your work there.

What happens if that free box vanishes tonight? Free model access can draft a small README tweak. It should not invent new gates or edit the checker.

Why give the writer the keys to its own lock? Split drafting work from the gate that permits a run. A model may propose text, not approve its own text.

Copy this fail-closed table

Read these rows as hard stops, not gentle suggestions. A secret hit is a stop, not a soft warning. Quarantine the file and write a fresh scan log.

Gate	Evidence you must show	Fail closed when
Scope	`scope.txt` contains `OUT OF SCOPE`	File missing, or no boundary line
Secrets	scan log contains `NO_HITS`	Log missing, or any hit remains
Rollback	note contains `git restore`	No restore command is written
Cost	note contains `ABORT_OVER`	No abort line for paid calls
Server	note contains `EPHEMERAL`	Box treated as durable storage
Human	ack contains `ACK`	Nobody records a real read

Do not weaken NO_HITS into a hopeful maybe. Do not mark the server durable just to skip a backup. Would you bet your only copy on a free box?

Limits, and who should skip this

This checklist is not a process sandbox at all. It does not isolate a model or prove privacy. It does not scan generated output for hostile edits.

A tired human can type ACK and still be wrong. You still need a second look outside scratch. The gate catches missing files, not bad judgment.

I am not publishing latency, spend, or a model name. Those figures were not supplied as current primary facts. Quotas and free-server terms can change without notice.

Re-read the vendor docs on the day you run. Do not freeze an old quota into this script. A checklist that hard-codes a number will rot.

Do not use this flow on production customer data. Do not use it for auth, billing, or migrations. Do not pretend it is an enterprise control framework.

A solo README typo job is the intended fit. A regulated system needs a different and heavier process. If policy already names a change tool, use that tool.

A second checklist will only become a rubber stamp. Skip this gate when another system is mandatory. Two paper trails are worse than one enforced trail.

How to abandon without a mess

Stop when any gate stays red after one fix. Delete the scratch tree when it holds unreviewed files. Leave the evidence folder in place as the postmortem.

rm -rf scratch
git status --short

If git status shows edits outside scratch, restore them. Restore those files before you close the laptop tonight. Did you actually run the rollback line you wrote?

One rehearsal, then stop

MonkeyCode's free model access and a free server can host this rehearsal. Try the red path, then the green path, then stop. Do not promote that rehearsal into a real deploy.

Which missing field keeps biting your small team now? Is it the secret scan, the rollback line, or the ack? Send the failure step, not a generic take on models.

Build a Promotion Checklist Before an AI Comment Diff Moves

Sam Rivera — Thu, 24 Sep 2026 18:14:24 +0000

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

Create a folder named comment-exit and change into that folder.
Save the checker as promote_check.py from the block below.
Make an evidence directory and add the three JSON fixtures.
Run the checker, then break one fixture on purpose.
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())

Evidence fixtures

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

{"commit": "abc1234deadbeef", "frozen": true}

{"files_changed": 1, "lines_added": 4}

{"reviewer": "sam", "ack": true, "ticket": "COMMENT-12"}

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=$?"

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

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=$?"

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=$?"

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

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

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.