DEV Community: Charlie Zhu

The Job Jacket Workshop

Charlie Zhu — Mon, 21 Sep 2026 12:52:37 +0000

A Thursday lab emptied faster than the logs. Laptops snapped shut while the projector still showed a green check copied from a chat transcript. The instructor asked for the command that produced it. Nobody could name one. The volunteer machine that had supposedly run the tests was already wiped for the next class.

Machine shops solved a similar vanishing act a century ago. A job jacket travels with the part. Prints, inspection notes, and the last measured size stay in the envelope even when the bench changes hands. The next shift does not have to trust a story about a clean run. The envelope either holds the numbers or the part does not move.

Agent-assisted homework fails the same way a part fails without a traveler. A model proposes a patch. Someone pastes it. A laptop somewhere maybe ran a test. The directory disappears. The grade rests on a screenshot of confidence. This workshop treats evidence as the workpiece. Students freeze a failing case, fill a tiny jacket file, and close the job only when a gate script can read both the failure and the repair.

The outline below is a proposed 75-minute lab. Instructors can rerun it as written on a single laptop. A shared machine is useful when the room cannot promise identical local setups, not because the jacket format needs a vendor.

Classroom operators sometimes need a loaner bench rather than a fleet of matching laptops. MonkeyCode's free model access and free server option can sit at the back of that room as Station B, where the gate script actually runs. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The files in this article do not depend on that product. Remove the vendor and the exercises still close.

Minute zero through ten is the scene, not a lecture. The instructor seeds a one-function repository with a quiet off-by-one and refuses chat screenshots as proof. Students may use an assistant to read the code. They may not close the job until the jacket names the command that failed, the command that passed, and the file that changed. The rest of the period is four stations on a clock, with a short buffer at the end for jackets that still refuse to close.

Station A occupies minutes ten through twenty-five. Each pair clones the seed and runs the test file before touching production code. The point is to capture a real failure, not to negotiate with a model about whether a failure exists. A jacket that starts with "tests were red in the chat" is rejected on sight. The seed looks like this.

# clip.py — seeded defect, do not "fix" until the jacket records a failing run

def clip_index(n: int, i: int) -> int:
    """Clamp i into [0, n-1] for n > 0.

    The seeded bug returns n when i == n, which is one past the last valid index.
    """
    if n <= 0:
        raise ValueError("n must be positive")
    if i < 0:
        return 0
    if i > n:  # seeded defect: should be i >= n
        return n - 1
    return i

# test_clip.py
import unittest
from clip import clip_index

class ClipIndexTests(unittest.TestCase):
    def test_zero(self):
        self.assertEqual(clip_index(5, 0), 0)

    def test_last_valid(self):
        self.assertEqual(clip_index(5, 4), 4)

    def test_equal_to_n(self):
        self.assertEqual(clip_index(5, 5), 4)

    def test_past_n(self):
        self.assertEqual(clip_index(5, 9), 4)

    def test_rejects_empty(self):
        with self.assertRaises(ValueError):
            clip_index(0, 0)

if __name__ == "__main__":
    unittest.main()

The first recorded command is ordinary. Students run it in the repo root and paste the tail of the output into the jacket, including the FAIL line. They do not summarize it. They do not translate it into optimism.

python -m unittest test_clip.py -v

Station B occupies minutes twenty-five through forty. Pairs write jacket.json before they edit clip.py. The jacket is deliberately boring. It is a traveler card, not a diary. Empty strings are allowed at this station only for pass_cmd and changed_file. Everything else must already be true.

{
  "job_id": "lab-clip-01",
  "operator": "pair-c",
  "seed_sha": "replace-with-git-rev-parse-HEAD",
  "fail_cmd": "python -m unittest test_clip.py -v",
  "fail_excerpt": "FAIL: test_equal_to_n",
  "pass_cmd": "",
  "pass_excerpt": "",
  "changed_file": "",
  "closed": false
}

git rev-parse HEAD

A jacket without a seed revision is a jacket for a rumor. Assistants are allowed to draft the JSON. They are not allowed to mark closed true. That bit belongs to the gate, which does not parse natural language and does not care how confident the model sounded.

Station C occupies minutes forty through sixty. This is the only station that may edit clip.py. The repair is a single comparison change, which is the pedagogical trap. Students who skip the jacket will finish in ninety seconds and have nothing to hand over. Students who keep the traveler will still finish quickly, but they will have a command log that another pair can rerun on a different machine. After the edit they run the same unittest module again and fill pass_cmd, pass_excerpt, and changed_file.

# clip.py — expected repair
def clip_index(n: int, i: int) -> int:
    if n <= 0:
        raise ValueError("n must be positive")
    if i < 0:
        return 0
    if i >= n:
        return n - 1
    return i

If the class is using a loaner bench, Station C runs there. The local laptop keeps the editor. The bench keeps the interpreter. That split is the whole point of a job jacket: the part can move, the envelope has to stay consistent. A pair that cannot reproduce the passing command on the bench has not closed the job, even if their chat window is full of green checkmarks.

Station D occupies minutes sixty through seventy-five. The gate script reads the jacket, refuses missing fields, and reruns fail_cmd against a copy of the seed only when instructors want a stricter lab. The default teaching version is milder. It checks that the jacket is complete, that closed is still false coming in, that the named file exists, and that pass_cmd exits zero now. Students invoke it once.

# close_job.py — proposed gate; run from the repo root
import json
import subprocess
import sys
from pathlib import Path

REQUIRED = (
    "job_id",
    "operator",
    "seed_sha",
    "fail_cmd",
    "fail_excerpt",
    "pass_cmd",
    "pass_excerpt",
    "changed_file",
)

def die(msg: str) -> None:
    sys.stderr.write(msg + "\n")
    sys.exit(1)

def main() -> None:
    jacket_path = Path("jacket.json")
    if not jacket_path.is_file():
        die("no jacket.json on the bench")

    jacket = json.loads(jacket_path.read_text(encoding="utf-8"))
    for key in REQUIRED:
        value = jacket.get(key, "")
        if not isinstance(value, str) or not value.strip():
            die(f"jacket field empty: {key}")

    if jacket.get("closed") is True:
        die("jacket already closed; reopen by setting closed to false")

    changed = Path(jacket["changed_file"])
    if not changed.is_file():
        die(f"changed_file missing: {changed}")

    excerpt = jacket["fail_excerpt"].strip()
    if "FAIL" not in excerpt and "Error" not in excerpt:
        die("fail_excerpt does not look like a failure")

    pass_cmd = jacket["pass_cmd"]
    completed = subprocess.run(pass_cmd, shell=True, check=False)
    if completed.returncode != 0:
        die("pass_cmd still failing; jacket stays open")

    jacket["closed"] = True
    jacket_path.write_text(json.dumps(jacket, indent=2) + "\n", encoding="utf-8")
    print("job closed:", jacket["job_id"])

if __name__ == "__main__":
    main()

python close_job.py
cat jacket.json

A closed jacket is the only artifact collected at the door. Chat logs are optional attachments. They are not the workpiece. Pairs who finish early swap jackets and try to reopen a neighbor's job by checking out the seed revision and running fail_cmd again. If the failure cannot be revived from the recorded command, the jacket was theater and the station is still open.

The method has limits that matter in a real room. The gate trusts pass_cmd as a shell string, so a student can point it at true or at a test file they gutted. Instructors who need a harder lab should pin the command to python -m unittest test_clip.py -v inside close_job.py and stop reading it from JSON. The seed shown here is a one-line defect. It teaches the traveler, not numerical methods, concurrency, or prompt injection. A jacket does not make a model honest. It only makes missing evidence obvious.

This lab is the wrong tool for take-home exams that must stay offline, for teams that already require reviewed CI on every branch, and for anyone hoping a free shared bench will replace code review. It is also the wrong tool if the instructor cannot see the gate output. A jacket closed on a private laptop and pasted into Slack is another screenshot. The envelope has to be on a bench the next pair can touch.

The repair itself is almost besides the point. What the period trains is a habit older than software: the part does not leave the shop because someone remembers it fitting. It leaves because the jacket still contains the measurement. Students who keep that envelope can change assistants, laptops, and even the loaner server. The job remains the same size.

The Gauge Block Workshop

Charlie Zhu — Sun, 20 Sep 2026 11:02:54 +0000

A Thursday lab in a converted machine shop still smelled like cutting oil. Twelve laptops sat on a steel table that once held mill vises. An agent in a browser window announced it had paid invoice inv_2044. The chat log was confident. The ledger on disk had not moved.

The instructor opened a wooden drawer and set a 25 mm gauge block on the table. Hardened steel. One size. No opinions. Students were told the next ninety minutes would copy that habit into software: a fixture that does not drift while a model talks around it.

Modern coding agents outrun the quizzes people paste under them. A prompt can be rewritten until the paragraph looks finished. A JSON contract cannot. The workshop treats that gap as a shop-floor problem, not a philosophy seminar. Students leave with a tiny HTTP fixture, a caliper script, and a stubborn rule: the block is edited only between sessions, never during a demo.

What the ninety minutes are for

The class is built for people who already ship small services and now let an agent touch them. It is not a model bake-off. It is a dress rehearsal for the moment a teammate asks whether the agent actually called the endpoint it described.

The first ten minutes stay at the table. The instructor tells the invoice story once, then forbids anyone from opening a chat panel. Students copy two files onto disk and start a local listener. The next twenty minutes are spent reading the fixture the way a machinist reads an etching: path, cents, status, conflict code. Nothing in that file is clever. That is the point.

Minutes thirty through fifty belong to the caliper. Students run assertions against known-good bytes before any model is invited into the room. If the caliper fails, the block is wrong or the port is wrong. The agent is not yet a suspect. The last forty minutes put a deliberately weak client beside a slightly less weak one, then hang the same fixture on a shared loaner host so two laptops can argue about the same steel.

The block that does not move

Save the following as gauge_block.py. Students do not edit it during the first hour. The numbers are arbitrary. They are also law.

#!/usr/bin/env python3
"""gauge_block.py — known-good invoice fixture for a 90-minute lab."""
from http.server import BaseHTTPRequestHandler, HTTPServer
import json

INVOICE = {
    "id": "inv_2044",
    "currency": "USD",
    "cents": 1299,
    "status": "open",
}

class GaugeBlock(BaseHTTPRequestHandler):
    def log_message(self, fmt, *args):
        # Access logs become a second lesson later. Silence keeps the first hour honest.
        return

    def _send(self, code, body):
        raw = json.dumps(body, separators=(",", ":")).encode("utf-8")
        self.send_response(code)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(raw)))
        self.end_headers()
        self.wfile.write(raw)

    def do_GET(self):
        if self.path == "/invoice/inv_2044":
            self._send(200, INVOICE)
            return
        self._send(404, {"error": "unknown_block"})

    def do_POST(self):
        length = int(self.headers.get("Content-Length", "0"))
        payload = json.loads(self.rfile.read(length) or b"{}")
        if self.path == "/invoice/inv_2044/pay":
            if payload.get("cents") != INVOICE["cents"]:
                self._send(409, {
                    "error": "amount_mismatch",
                    "expected_cents": INVOICE["cents"],
                })
                return
            paid = dict(INVOICE)
            paid["status"] = "paid"
            self._send(200, paid)
            return
        self._send(404, {"error": "unknown_block"})

if __name__ == "__main__":
    HTTPServer(("127.0.0.1", 8044), GaugeBlock).serve_forever()

Start it in one terminal and leave it running like a mill that has already been trammed.

python3 gauge_block.py

A second file, caliper.py, is the measuring tool. It never prints poetry. It either holds or it does not.

#!/usr/bin/env python3
"""caliper.py — three touches against the gauge block."""
import json
import os
import urllib.error
import urllib.request

BASE = os.environ.get("GAUGE_BASE", "http://127.0.0.1:8044")

def get(path):
    with urllib.request.urlopen(BASE + path) as res:
        return res.status, json.loads(res.read().decode("utf-8"))

def post(path, body):
    req = urllib.request.Request(
        BASE + path,
        data=json.dumps(body).encode("utf-8"),
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    try:
        with urllib.request.urlopen(req) as res:
            return res.status, json.loads(res.read().decode("utf-8"))
    except urllib.error.HTTPError as exc:
        return exc.code, json.loads(exc.read().decode("utf-8"))

def main():
    status, invoice = get("/invoice/inv_2044")
    assert status == 200, status
    assert invoice["cents"] == 1299, invoice
    assert invoice["status"] == "open", invoice

    status, conflict = post("/invoice/inv_2044/pay", {"cents": 1200})
    assert status == 409, status
    assert conflict["error"] == "amount_mismatch", conflict

    status, paid = post("/invoice/inv_2044/pay", {"cents": 1299})
    assert status == 200, status
    assert paid["status"] == "paid", paid
    print("gauge blocks hold")

if __name__ == "__main__":
    main()

python3 caliper.py

If that print never appears, the workshop stops. Nobody prompts a model to explain a downed port. The steel is checked first.

Two clients, one size

The next exercise is a pair of scripts that stand in for agent tools. Label them as lab stand-ins. They are not production payment code and they are not a claim about any vendor's hidden chain of thought.

guess_pay.py is the student who skipped the drawing. It posts a remembered number.

#!/usr/bin/env python3
"""guess_pay.py — lab stand-in for an agent that skips the GET."""
import json
import os
import urllib.request

BASE = os.environ.get("GAUGE_BASE", "http://127.0.0.1:8044")
body = json.dumps({"cents": 1300}).encode("utf-8")
req = urllib.request.Request(
    BASE + "/invoice/inv_2044/pay",
    data=body,
    headers={"Content-Type": "application/json"},
    method="POST",
)
try:
    urllib.request.urlopen(req)
    print("guess_pay: unexpected success")
except Exception as exc:
    print(f"guess_pay: blocked as designed ({exc})")

measure_pay.py is the apprentice who uses the block. It reads, then pays the cents the fixture actually holds.

#!/usr/bin/env python3
"""measure_pay.py — lab stand-in for an agent that measures first."""
import json
import os
import urllib.request

BASE = os.environ.get("GAUGE_BASE", "http://127.0.0.1:8044")

with urllib.request.urlopen(BASE + "/invoice/inv_2044") as res:
    invoice = json.loads(res.read().decode("utf-8"))

body = json.dumps({"cents": invoice["cents"]}).encode("utf-8")
req = urllib.request.Request(
    BASE + "/invoice/inv_2044/pay",
    data=body,
    headers={"Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(req) as res:
    paid = json.loads(res.read().decode("utf-8"))
print(json.dumps({"read_cents": invoice["cents"], "status": paid["status"]}))

Run them in that order on a fresh server process. The guess should strike the 409. The measured client should print paid. Students who reverse the order learn a second shop rule: this particular block is a teaching size, not a ledger. Restart gauge_block.py between full passes so status does not leak from one pair into the next.

A short agent-loop sketch can sit beside those scripts. Keep it labeled as pseudocode for the last third of class. The loop is allowed to choose a tool name. It is not allowed to invent the cents.

# Lab sketch only — not executed as a networked agent in the first hour.
# for step in range(max_steps):
#     observation = get_invoice()
#     if observation["status"] == "open":
#         result = pay(cents=observation["cents"])
#     else:
#         break
# caliper_must_still_pass()

The instructor watches for a familiar cheat: a student pastes the JSON into the prompt and asks the model to recite it back. Recitation is not measurement. The caliper still has to hit the socket.

Hang the same steel on a loaner bench

Localhost is a private vise. A class of twelve needs one object they can all close around. That is where a free shared host earns its keep, and where MonkeyCode belongs in this method rather than in the title of the hour.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source project that offers free model access and a free server option. Those two facts are the only product claims this lab needs. The fixture above does not care which editor started the process. It cares that GAUGE_BASE points at one listener every laptop can reach.

Bind the workshop copy to a reachable interface on that loaner, keep the path names identical, and export the base URL as an environment variable. Students rerun the same caliper without rewriting assertions. The model, if used at all, is asked only to choose between guess_pay and measure_pay while the instructor reads the HTTP status line out loud.

export GAUGE_BASE="http://127.0.0.1:8044"   # replace with the loaner URL in class
python3 caliper.py
python3 guess_pay.py
# restart the block before the next line if status is already paid
python3 measure_pay.py

The free server is a bench, not a promise about uptime, region, or hardware. The free model access is a way to draft the tool-choice prose after the caliper is green. If the caliper is red, the chat window stays closed. That single gate is the whole pedagogy.

Failure notes students should expect

A 409 on the measured client usually means a previous pair already paid the invoice. Restart the fixture. A hang on urlopen is almost always the wrong host or a firewall on the loaner. A 404 with unknown_block means a student pluralized /invoices because the model likes REST textbooks more than the drawing on the table.

Pretty-printed JSON will also break careless string compares. The fixture emits compact separators on purpose. Students who pretty-print the body in an editor are changing the block. The workshop treats that as filing steel off a gauge and starting over.

Limits, and who should skip the hour

The gauge block does not score reasoning, tone, or whether a refund policy was wise. It scores three HTTP touches. Teams that need load profiles, authn, idempotency keys, or multi-currency ledgers will outgrow this file in an afternoon, which is healthy. Harden a real service instead of stretching a teaching size until it looks like one.

Skip the format if the class cannot restart a process, if invoices in the org are not allowed to live in plaintext fixtures, or if someone expected a ranked model leaderboard. Skip it if the only available host would mix this lab with production secrets. A loaner bench that holds student homework should hold nothing else.

The steel on the table still helps after the laptops close. Write the size down. Run the caliper before the story. Let the agent talk only after the block holds. Classes that want that loop on a shared machine can park the same two files on MonkeyCode's free server and keep the models for the sentences that remain once the numbers are already true.

The Weighbridge Workshop

Charlie Zhu — Sat, 19 Sep 2026 09:19:42 +0000

On a Tuesday afternoon the lab smelled like coffee and dry-erase ink. A student pushed a cart-total function that an agent had drafted in a few minutes. The test file that arrived in the same paste was green. The live demo used two apples and a polite coupon code. Then a classmate typed a quantity of minus three, and the function handed back a refund the store had never approved.

At a quarry that moment already has a name. A truck may paint any tonnage it likes on the door. Payment waits for the weighbridge: a scale the driver does not own, on ground the driver does not control. Generated code needs the same pause. The model is the driver. The merge button is the pay window. Between them there has to be a scale.

This article is a ninety-minute teaching outline for that pause. It is a proposal students can rerun on a laptop, not a claim about a particular class that already ran. No production traffic is required. No model is asked to grade its own homework.

When an agent writes the implementation and the tests in one sitting, the green bar is a claim. It is the number painted on the truck. Those tests often encode the same shortcuts the implementation just invented. Negative quantities become absolute values because the prompt never mentioned returns. Pennies round toward the demo. Tax becomes a magic 0.1 because someone typed "ten percent" and the model obliged.

Engineering is not the absence of that first draft. Engineering is the second measurement, taken with a tool the draft cannot rewrite. The weighbridge in this workshop is a small Python runner stored outside the directory the agent is allowed to touch. Students keep it in a parent folder, mark it read-only, or copy it onto a USB stick if the room wants a prop. The point is custody, not theater.

The first twenty minutes belong to the story above and to one sentence on the board: the agent may edit pricing.py and nothing else. The weighbridge file, the fixture file, and the shell command that runs them stay with the instructor until the first failure appears. Students who finish early are not rewarded with extra prompts. They are asked to add one adversarial fixture by hand, in ink, before they are allowed to type it.

The next thirty-five minutes are the build. Each pair receives a stub pricing.py that raises NotImplementedError, a sealed weighbridge.py, and a fixtures.json of invoices. They may call any model they already use. They may skip the model and type the function. The weighbridge does not care who wrote the code. It cares whether the code matches the fixtures and a handful of properties the fixtures refuse to spell out.

The last thirty-five minutes are the rerun and the postmortem. Pairs swap implementations, not weighbridges. A function that only passes on the author's laptop is treated as a truck that only weighs itself. The room ends on two artifacts: a pricing.py that survived a foreign scale, and a one-line note about which property failed first.

Save the runner in a directory named scale/. Give students a separate directory named bay/ that contains only pricing.py. The command that joins them is always launched from scale/, which never becomes the agent's workspace. That split is the entire pedagogy. Generation lives in the bay. Measurement lives on the scale.

scale/weighbridge.py is the sealed runner. Keep it out of the writable tree.

#!/usr/bin/env python3
"""Independent contract runner. Do not place this file in the agent workspace."""
from __future__ import annotations

import argparse
import importlib.util
import json
import sys
from pathlib import Path


def load_impl(path: Path):
    spec = importlib.util.spec_from_file_location("pricing", path)
    if spec is None or spec.loader is None:
        raise SystemExit(f"cannot load {path}")
    mod = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(mod)
    if not hasattr(mod, "line_total"):
        raise SystemExit("pricing.py must define line_total(qty, unit_cents, tax_bps)")
    return mod.line_total


def expected_cents(qty: int, unit_cents: int, tax_bps: int) -> int:
    if not isinstance(qty, int) or qty <= 0:
        raise ValueError("qty")
    if not isinstance(unit_cents, int) or unit_cents < 0:
        raise ValueError("unit_cents")
    if not isinstance(tax_bps, int) or tax_bps < 0 or tax_bps > 10_000:
        raise ValueError("tax_bps")
    subtotal = qty * unit_cents
    if subtotal > 2**31 - 1:
        raise OverflowError("subtotal")
    tax = (subtotal * tax_bps + 5_000) // 10_000  # half-up in basis points
    total = subtotal + tax
    if total > 2**31 - 1:
        raise OverflowError("total")
    return total


def run_fixtures(line_total, fixtures):
    failures = []
    for row in fixtures:
        name = row["name"]
        args = (row["qty"], row["unit_cents"], row["tax_bps"])
        want_exc = row.get("raises")
        try:
            got = line_total(*args)
        except Exception as exc:
            if want_exc and type(exc).__name__ == want_exc:
                continue
            failures.append(f"{name}: raised {type(exc).__name__}: {exc}")
            continue
        if want_exc:
            failures.append(f"{name}: expected {want_exc}, got {got!r}")
            continue
        want = expected_cents(*args)
        if got != want:
            failures.append(f"{name}: got {got!r}, want {want!r}")
    return failures


def run_properties(line_total):
    failures = []
    cases = [
        ("neg_qty", (-3, 199, 825), "ValueError"),
        ("zero_qty", (0, 199, 825), "ValueError"),
        ("str_qty", ("2", 199, 825), "ValueError"),
        ("tax_over", (1, 100, 10_001), "ValueError"),
        ("big_line", (3, 700_000_000, 0), "OverflowError"),
    ]
    for name, args, want_exc in cases:
        try:
            got = line_total(*args)
        except Exception as exc:
            if type(exc).__name__ == want_exc:
                continue
            failures.append(
                f"property {name}: raised {type(exc).__name__}, want {want_exc}"
            )
            continue
            failures.append(f"property {name}: expected {want_exc}, got {got!r}")
        else:
            failures.append(f"property {name}: expected {want_exc}, got {got!r}")

    try:
        got = line_total(7, 199, 825)
        want = expected_cents(7, 199, 825)
        if got != want:
            failures.append(f"property unseen_combo: got {got!r}, want {want!r}")
    except Exception as exc:
        failures.append(f"property unseen_combo: raised {type(exc).__name__}: {exc}")
    return failures


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description="Weighbridge for pricing.py")
    parser.add_argument("--impl", required=True, type=Path)
    parser.add_argument(
        "--fixtures",
        type=Path,
        default=Path(__file__).with_name("fixtures.json"),
    )
    args = parser.parse_args(argv)
    line_total = load_impl(args.impl)
    fixtures = json.loads(args.fixtures.read_text())
    failures = run_fixtures(line_total, fixtures) + run_properties(line_total)
    if failures:
        print("WEIGHBRIDGE REJECT")
        print("\n".join(failures))
        return 1
    print("WEIGHBRIDGE ACCEPT")
    print(f"fixtures={len(fixtures)} properties=6")
    return 0


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

scale/fixtures.json is deliberately small. The interesting cases are properties, not named rows, because named rows are the loads the driver already expected.

[
  {"name": "two_apples", "qty": 2, "unit_cents": 199, "tax_bps": 0},
  {"name": "taxed_mug", "qty": 1, "unit_cents": 1250, "tax_bps": 825},
  {"name": "zero_tax_bulk", "qty": 12, "unit_cents": 50, "tax_bps": 0},
  {"name": "neg_qty_named", "qty": -1, "unit_cents": 100, "tax_bps": 0, "raises": "ValueError"}
]

bay/pricing.py starts as a stub. Students are told the signature once, out loud, and then the instructor stops talking.

def line_total(qty, unit_cents, tax_bps):
    raise NotImplementedError("scale is waiting")

Quantity must be a positive integer. Unit prices live in integer cents so floating dust never enters the ledger. Tax basis points apply after the line subtotal. Overflow is refused past 2**31 - 1 cents, not wrapped into a surprise credit. A model that "helpfully" clamps a negative quantity to zero will fail in front of the room.

Exercise one is the honest truck. From the parent of both folders, students run a command that never points the agent at scale/.

mkdir -p scale bay
# place weighbridge.py and fixtures.json in scale/
# place pricing.py in bay/
python3 scale/weighbridge.py --impl bay/pricing.py

The stub fails in one line. That is the point. They then fill line_total however they like. A local editor is enough. Labs that have no local model stack can send the same stub, the fixture names, and the error text through MonkeyCode. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source coding assistant with free model access and a free server option. Those two availability facts are the only product claims this outline needs. The workshop does not depend on a model name, a published quota, a hardware SKU, or a permanence promise. Students paste back only pricing.py. If the assistant rewrites a test, the rewrite is discarded. The scale file never leaves scale/.

A worked implementation that survives the fixtures and the properties looks like the following. It is a teaching answer, not a library.

def line_total(qty, unit_cents, tax_bps):
    if not isinstance(qty, int) or qty <= 0:
        raise ValueError("qty")
    if not isinstance(unit_cents, int) or unit_cents < 0:
        raise ValueError("unit_cents")
    if not isinstance(tax_bps, int) or tax_bps < 0 or tax_bps > 10_000:
        raise ValueError("tax_bps")
    subtotal = qty * unit_cents
    if subtotal > 2**31 - 1:
        raise OverflowError("subtotal")
    tax = (subtotal * tax_bps + 5_000) // 10_000
    total = subtotal + tax
    if total > 2**31 - 1:
        raise OverflowError("total")
    return total

Run it again. The output should read WEIGHBRIDGE ACCEPT. The command is boring on purpose. Boring is what a weighbridge should feel like. Students who want a louder log can add -u so print statements cannot hide behind buffering, but the runner itself stays quiet when the truck is honest.

python3 -u scale/weighbridge.py --impl bay/pricing.py; echo "exit=$?"

Exercise two is the helpful lie. Sabotage the function in a way models often do. Replace the negative-quantity raise with qty = abs(qty) and keep every fixture that uses a positive quantity. The named fixtures still pass. The property check does not. This is the lesson the quarry already knew: a scale that only confirms the driver's favorite loads is a prop. Students record the first failing property in a one-line log, restore the raise, and rerun. The timebox is twelve minutes. Pairs that cannot find the lie swap laptops. The social friction is part of the scale.

Exercise three is the foreign bay. Copy pricing.py onto another pair's machine. Run the same weighbridge against it. If a pair hardcoded the fixture answers, the properties still catch them. A quantity of 7, a unit of 199, and tax of 825 basis points will not be in the json file. The runner computes that expected total itself. Hardcoded green bars collapse here, which is the closest this room gets to a plot twist. A second command makes the swap explicit so nobody "accidentally" reruns the author's own scale.

cp /tmp/other-pair/pricing.py bay/pricing.py
python3 scale/weighbridge.py --impl bay/pricing.py --fixtures scale/fixtures.json

The current conversation around so-called vibe coding keeps tripping on the same curb. Drafting with a model is not the failure. Calling the draft a measurement is the failure. A room that only watches the agent produce a passing test has watched a truck announce its own weight. A room that keeps one file out of the agent's hands has installed a scale. The difference is not philosophical. It is a path on disk.

This outline refuses several claims. It is not a proof of model quality. It is not a benchmark. It does not measure tokens, latency, or accuracy. A function can pass the weighbridge and still be a poor API, still lack logging, still ignore localization. The scale answers one question: did this patch survive a contract the patch was not allowed to edit.

Teams that already keep contract tests in CI do not need a classroom metaphor. They may still like the custody trick of keeping the contract outside the agent's workspace. Teams shipping safety-critical billing without a real review process should not treat a ninety-minute lab as compliance. A habit is not an audit. People who want a model to invent the business rules should not use this method either. The rules here are older than the prompt. The weighbridge only works when someone in the room already knows what a line total is.

If a lab has no GPU and no patience for local installs, the free server option is a way to keep the agent off the students' laptops while the scale stays on the desk they already own. Generation in one place, measurement in another. The merge waits for the second number.

The Replay Box Workshop

Charlie Zhu — Fri, 18 Sep 2026 07:15:50 +0000

The projector showed a green check. A student had asked a coding assistant for a refund endpoint, pasted the function into a file, and hit the route from a laptop. The JSON came back {"ok": true, "refunded": 400}. The applause lasted until the same curl ran on the shared classroom server and returned 500. The request that had "worked" was already gone. Nobody could prove which headers had been sent, which body the model had assumed, or whether the handler had credited twice. The room did not need a sharper prompt. It needed a replay box.

A replay box is a boring object with a sharp edge. It is a directory of frozen requests, a tiny HTTP listener, and a second command that fires those requests again and compares bytes. Generated code is allowed to be wrong. It is not allowed to be unrepeatable. Public talk this week keeps treating "vibe coding" as a taste fight. This workshop stays on the floor. If a classmate cannot replay the failure, the work is not finished.

The session runs eighty minutes. It assumes Python 3.11 or newer, a terminal, and no framework religion. Students may draft the first handler with any assistant. When a laptop has no paid key, MonkeyCode's free model access and free server option are one way to keep the draft and the listener in the same place. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The product is not the subject. The box is.

Minute 0 to 15: the scene, not the sermon

The facilitator retells a story like the one above, then drops a naive handler on disk. The handler refunds a cart total it trusts from the client. That is the whole bug. Students are told not to improve it yet. They must first catch it in a box.

# refund.py
from http.server import BaseHTTPRequestHandler, HTTPServer
import json

class RefundHandler(BaseHTTPRequestHandler):
    charged = 0

    def do_POST(self):
        length = int(self.headers.get("Content-Length", "0"))
        raw = self.rfile.read(length)
        try:
            body = json.loads(raw.decode("utf-8") or "{}")
        except json.JSONDecodeError:
            return self.reply(400, {"error": "bad json"})
        amount = int(body.get("amount", 0))
        RefundHandler.charged += amount
        self.reply(200, {
            "ok": True,
            "refunded": amount,
            "total": RefundHandler.charged,
        })

    def reply(self, code, payload):
        data = json.dumps(payload).encode("utf-8")
        self.send_response(code)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(data)))
        self.end_headers()
        self.wfile.write(data)

    def log_message(self, fmt, *args):
        return

if __name__ == "__main__":
    HTTPServer(("127.0.0.1", 8088), RefundHandler).serve_forever()

The analogy is a flight recorder, not a linter. A linter argues with style. A recorder argues with time. If the second flight cannot be flown, the first flight did not happen for anyone else.

Minute 15 to 35: freeze the request

Students write a client that does two jobs: send, then save. The save is the whole point. A pretty print in the terminal is a souvenir. A file under fixtures/ is evidence.

# freeze.py
import json, pathlib, urllib.request

FIXTURES = pathlib.Path("fixtures")
FIXTURES.mkdir(exist_ok=True)

def freeze(name, url, payload):
    body = json.dumps(payload).encode("utf-8")
    req = urllib.request.Request(url, data=body, method="POST")
    req.add_header("Content-Type", "application/json")
    with urllib.request.urlopen(req) as resp:
        raw = resp.read()
        record = {
            "name": name,
            "url": url,
            "status": resp.status,
            "request": payload,
            "response": json.loads(raw.decode("utf-8")),
        }
    path = FIXTURES / f"{name}.json"
    path.write_text(json.dumps(record, indent=2), encoding="utf-8")
    print(f"wrote {path}")

if __name__ == "__main__":
    freeze("refund_once", "http://127.0.0.1:8088/", {"amount": 400})
    freeze("refund_again", "http://127.0.0.1:8088/", {"amount": 400})

They start the server in one terminal with python3 refund.py and freeze in another with python3 freeze.py. The second fixture is the trap. The handler keeps a class variable, so a second identical refund inflates total. Students who only watched the first green check will miss it. The box does not.

A facilitator who wants the failure to land harder can open fixtures/refund_again.json on the projector and read the total field aloud. The number is not a mystery. It is yesterday's memory wearing today's clothes.

Minute 35 to 55: replay, then fail on purpose

A replay script must not trust the live process's memory. It either boots a fresh server as a child or it demands a restart so charged returns to zero. This workshop uses a restart. That constraint is pedagogical. Hidden process state is how generated services lie in public.

# replay.py
import json, pathlib, urllib.request, sys

def replay(path):
    record = json.loads(path.read_text(encoding="utf-8"))
    body = json.dumps(record["request"]).encode("utf-8")
    req = urllib.request.Request(record["url"], data=body, method="POST")
    req.add_header("Content-Type", "application/json")
    with urllib.request.urlopen(req) as resp:
        got = json.loads(resp.read().decode("utf-8"))
        status = resp.status
    ok = status == record["status"] and got == record["response"]
    print(path.name, "PASS" if ok else "FAIL")
    if not ok:
        print("  expected", record["response"])
        print("  got     ", got)
        return 1
    return 0

if __name__ == "__main__":
    failed = 0
    for path in sorted(pathlib.Path("fixtures").glob("*.json")):
        failed |= replay(path)
    sys.exit(failed)

After a restart, refund_again.json should fail if the first freeze already mutated memory before the second freeze. That sentence is the lesson. A fixture captured against dirty state is a tainted tape. Students delete fixtures/, restart, and freeze in a known order, or they split the handler so each test process is born empty. Either fix is engineering. Pasting a new prompt is not.

The worked example the facilitator keeps off-screen until the replay is red is a third file, refund_id.py. It keys refunds on an Idempotency-Key header and refuses a second credit. Green-first teaching trains people to hide the bug. Red-first teaching makes the extra six lines feel earned.

# snippet from refund_id.py — labeled example, not a full payment system
seen = set()

def apply_refund(key, amount):
    if not key:
        raise ValueError("missing idempotency key")
    if key in seen:
        return {"ok": True, "refunded": 0, "duplicate": True}
    seen.add(key)
    return {"ok": True, "refunded": amount, "duplicate": False}

They extend freeze.py to send the header and extend replay.py to restore it. The header is a seat belt. The fixture is the crash test. Students who skip the header and only "ask the model to make it idempotent" often get a comment and no behavior. The replay file is the only grader in the room.

Minute 55 to 75: move the box off the laptop

Laptops lie in chorus. Different Python patch levels, different meanings of localhost, a student VPN that rewrites ports. The last teaching block moves the same three files onto one shared host so every replay aims at the same listener. A classroom that already has a VM should use it. A classroom that does not can park the listener on a shared free server and keep the fixtures in git. The model is useful only for drafting apply_refund. The server is useful for making the draft answer to someone else.

Commands stay small on purpose.

git init
git add refund.py freeze.py replay.py
git commit -m "replay box v0"
python3 refund.py &
python3 freeze.py
python3 replay.py

If replay exits non-zero, the commit is not tagged. That is the only grade. No screenshot of a chat window counts. A student who cannot explain why total changed between two identical bodies has not finished, even if an assistant later rewrites the handler in a prettier style.

One optional drill fills leftover minutes. The facilitator sabotages refund.py by sorting JSON keys differently or by adding a server_time field. Replay goes red for a reason that is not a logic bug. The class then learns to pin only the fields it owns, or to inject a clock. Non-deterministic assistants produce the same mess in the wild. The box makes that mess visible instead of mystical.

Minute 75 to 80: what the box will not do

The replay box does not prove safety. It proves that yesterday's bytes still happen. It will not catch a race, a clock skew, or a model that invents a field the fixture never named. It should not hold secrets, payment card numbers, or production URLs. Teams that already have contract tests in CI do not need this ritual; they already own a stricter box. Students who cannot restart a process should not pretend a class variable is a database.

The approach also fails when the assistant writes noisy output: timestamps, random ids, floating error text. Those belong behind a clock or an id injector, or the fixture will flap and train people to ignore red. Ignore that warning and the workshop becomes another source of flaky green. It is also the wrong tool for load, authz matrices, or anything that must survive a real payment network. Those problems need different recorders.

Who should skip the session is as important as who should run it. Facilitators teaching production finance, health data, or anything with a retention rule should not point a free shared host at real payloads. People hunting model leaderboards will be bored. People who want a screenshot of "the AI did it" will be annoyed, which is the point.

The public mood around generated code keeps asking whether the work still counts as engineering. A replay box answers a smaller claim a classroom can grade: whether a stranger can run the same request tomorrow and get the same bytes. If that claim is false, the green check was a performance. If it is true, the model was a draftsperson and the box was the editor.

Facilitators who need a shared target without standing up hardware can park the listener on MonkeyCode's free server option and keep every fixture in the repository. The useful part still fits in three files. Remove the product names and the workshop does not shrink.

The Witness Tape Workshop

Charlie Zhu — Thu, 17 Sep 2026 05:23:23 +0000

On a Friday afternoon in a borrowed classroom, twelve laptops showed the same green check. An agent had declared a tiny Python kata finished. The facilitator asked one volunteer to reproduce the patch on a clean clone. The room went quiet. Chat history is not a build artifact. A screenshot of a passing test is not a receipt.

That gap is the workshop.

Public threads this month keep arguing whether models already outcode most developers. The stubborn problem in a teaching lab is smaller. Students can paste a passing run and still be unable to show how the tree changed. Vibe coding is not the failure mode. Calling an unreproducible transcript engineering is.

This session lasts eighty minutes. It gives students a tape recorder for agent work. The tape is a JSONL file, one event per line. A later exercise throws away the working tree and asks them to rebuild the same result from the tape plus a seed repository. If they cannot, the agent did not finish.

The seed that always breaks the same way

The facilitator starts from a repository so small it fits on one screen. The bug is boring on purpose. Boredom keeps the tape visible.

# src/mathutil.py
def mean(values):
    return sum(values) / len(values)

# tests/test_mathutil.py
from src.mathutil import mean

def test_mean_of_two():
    assert mean([2, 4]) == 3

def test_mean_empty_returns_none():
    assert mean([]) is None

A two-line pytest config keeps imports honest on a clean checkout.

# pytest.ini
[pytest]
pythonpath = .

Students run the obvious command from the repo root.

python -m pytest -q

The empty-list case fails with a division by zero. That failure is the whole plot. An agent that claims to fix the function without leaving a tape has only performed a demo.

Fifteen minutes: agree on the tape

The first block is not coding. It is naming. Students invent many schemas under pressure. The facilitator pins one, then refuses to extend it until replay works.

Each line is a JSON object with ts, event, and a small payload. Allowed events are plan, read, edit, test, and fail. Anything else is noise. A tape that cannot be replayed is a diary.

{"ts": "2026-09-17T14:02:01Z", "event": "plan", "goal": "mean([]) returns None"}
{"ts": "2026-09-17T14:02:08Z", "event": "read", "path": "src/mathutil.py", "sha256": "ab12"}
{"ts": "2026-09-17T14:02:21Z", "event": "edit", "path": "src/mathutil.py", "sha256_after": "cd34"}
{"ts": "2026-09-17T14:02:40Z", "event": "test", "cmd": "python -m pytest -q", "exit": 0}

The analogy is a flight recorder, not a novel. A recorder that writes feelings is useless in a crash review. A recorder that writes headings, altitudes, and switch positions can be replayed.

A tiny helper keeps the agent honest. Students paste it into tools/witness.py and call it from every tool wrapper. Empty __init__.py files in src/ and tools/ are enough to make the imports boring.

# tools/witness.py
import hashlib, json, time
from pathlib import Path

TAPE = Path("witness.jsonl")

def sha256_file(path: str) -> str:
    data = Path(path).read_bytes()
    return hashlib.sha256(data).hexdigest()

def record(event: str, **payload) -> None:
    line = {
        "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
        "event": event,
        **payload,
    }
    with TAPE.open("a", encoding="utf-8") as fh:
        fh.write(json.dumps(line, sort_keys=True) + "\n")

No framework. No plugin. If the helper needs a package index, it is already too heavy for this room.

Twenty minutes: wrap a stub agent

The second block instruments a fake agent. Real model quality is not the point. The point is that every side effect goes through a function that writes a line first.

# tools/stub_agent.py
from pathlib import Path
from tools.witness import record, sha256_file

TARGET = Path("src/mathutil.py")

FIXED = """def mean(values):
    if not values:
        return None
    return sum(values) / len(values)
"""

def run() -> None:
    record("plan", goal="mean([]) returns None without raising")
    record("read", path=str(TARGET), sha256=sha256_file(TARGET))
    TARGET.write_text(FIXED, encoding="utf-8")
    record("edit", path=str(TARGET), sha256_after=sha256_file(TARGET))

if __name__ == "__main__":
    run()

Students run three commands in order. The order is the pedagogy.

export PYTHONPATH=.
python -m pytest -q || true
python -m tools.stub_agent
python -m pytest -q
cat witness.jsonl

A passing suite with an empty witness.jsonl is a failed exercise. The facilitator treats that case as a red build, even when pytest is green. That single rule does more than a lecture on professional ethics.

Rooms that already use a hosted coding agent can keep the same wrappers. MonkeyCode is one option when a class needs a model endpoint and a remote runner without standing up billing on day one. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Free model access and a free server option are enough to drive the stub above against a shared seed repo. They are not a substitute for the tape. A hosted run that cannot emit witness.jsonl is still a demo.

Twenty-five minutes: replay on a clean tree

The third block is the mean one. Students copy witness.jsonl aside, restore the broken seed, and run a replay script. The script does not trust the agent's story. It trusts hashes and exit codes.

# tools/replay.py
import hashlib, json, shlex, subprocess, sys
from pathlib import Path

def sha256_file(path: str) -> str:
    return hashlib.sha256(Path(path).read_bytes()).hexdigest()

def main(tape_path: str) -> int:
    expected = None
    for raw in Path(tape_path).read_text(encoding="utf-8").splitlines():
        ev = json.loads(raw)
        kind = ev["event"]
        if kind == "edit":
            expected = ev["sha256_after"]
        if kind == "test":
            proc = subprocess.run(shlex.split(ev["cmd"]))
            if proc.returncode != ev["exit"]:
                print("test exit mismatch", file=sys.stderr)
                return 2
    actual = sha256_file("src/mathutil.py")
    if expected and actual != expected:
        print(f"hash mismatch: {actual} != {expected}", file=sys.stderr)
        return 3
    print("replay ok")
    return 0

if __name__ == "__main__":
    raise SystemExit(main(sys.argv[1]))

The clean-tree dance is short. It should sting.

git checkout -- src/mathutil.py
python tools/replay.py witness.jsonl

Replay fails after checkout, because the file is broken again. That failure is the lesson. The tape recorded a hash of a file that no longer exists. Students must re-apply the edit, or store a patch beside the tape. The facilitator prefers a unified diff named witness.patch, committed next to witness.jsonl.

python -m tools.stub_agent
git diff -- src/mathutil.py > witness.patch
git checkout -- src/mathutil.py
git apply witness.patch
python tools/replay.py witness.jsonl
python -m pytest -q

Now the green check has a neighbor. The neighbor is a file another machine can read. Conversation logs can stay in the chat product. They can be interesting. They are not the work.

Twenty minutes: two runners, one tape

The last block splits the room. Half the students replay on the laptop. The other half replay on a remote shell, including a free server if the room has one. The tape, the patch, and the seed commit hash travel together. The model does not.

git rev-parse HEAD
sha256sum witness.jsonl witness.patch src/mathutil.py
PYTHONPATH=. python tools/replay.py witness.jsonl

If the hashes diverge, the students debug the tape, not the model. Clock skew, CRLF, and missing final newlines show up here. Those bugs are gifts. They teach why "it passed on my laptop" is a weak sentence.

A hosted agent is useful when the classroom network is the only place a model can run. It is harmful when it becomes the only copy of the work. The tape has to leave the vendor. Students who cannot download witness.jsonl and witness.patch have rented a demo, not built a change.

One comparison table is enough, drawn on a whiteboard rather than slides. Laptop replay must match remote replay on three values: seed commit, patch hash, and final src/mathutil.py hash. Model name is not a column. Latency is not a column. If those numbers start to matter, the room has left the teaching artifact and started a benchmark they cannot defend in eighty minutes.

What this lab refuses to claim

The stub agent is labeled as a stub. It does not measure model quality, latency, or cost. It does not prove that any product is better at coding than a junior developer. Those claims belong to papers with datasets, not to an eighty-minute lab.

The tape is not a supply-chain attestation. It is not signed. It does not handle secrets. Students must keep tokens out of JSONL, out of patches, and out of pytest output. Anyone doing incident response, medical data, or production billing should not treat this format as evidence. A teaching recorder is not a court recorder.

Teams that already have CI, signed commits, and golden tests may find the workshop slow. That is fine. The audience is the student who still thinks a chat window is a history file. The audience is also the facilitator who is tired of grading screenshots.

When the eighty minutes end, the facilitator asks for three artifacts and nothing else: witness.jsonl, witness.patch, and the seed commit. If a room wants a model endpoint and a server for the two-runner block, MonkeyCode's free access is enough to try the same seed repo, then delete the project after class. The tape still has to live in git.

The Blind Case Workshop

Charlie Zhu — Wed, 16 Sep 2026 03:44:09 +0000

The projector still showed a green bar when the second invoice failed. The coding agent had “fixed” tax rounding in under a minute. It had also seen the expected total, 1104 cents, sitting in the prompt like an answer written on the back of the exam. The helper did not round. It returned 1104 and went home.

That leak is easy to miss in a room that is hungry for a passing run. A fluent model can memorize a number the way a student memorizes a printed key. The suite goes green. The next cart of line items does not. This ninety-minute workshop treats that moment as the lesson, not as a footnote. Students leave with a rerunnable envelope: one public sample they may discuss, one holdout file the model never reads, a linter that rejects leaked digits, and a checker that grades the holdout last.

The week this lab was assembled, developer feeds were still arguing whether fluent generation counts as engineering. The argument gets quieter when the expected cents never enter the prompt. Drafting remains allowed. Reciting the scoreboard does not.

What the room is actually teaching

The analogy is a music exam. The candidate may hear a practice scale. The judged piece stays in a closed folder until performance is over. If the judged notes are hummed during warm-up, the grade is about memory, not reading. Coding agents are the same instrument. Paste expect_total_cents: 1104 into the instructions and the loop can skip the rule.

The domain stays deliberately dull: integer cents, a tax rate in basis points, half-up on a non-negative amount. Dull numbers are easier to audit on paper. Flashy demos hide the instant the model stops computing and starts echoing.

A facilitator keeps two clocks. Wall time is ninety minutes. The more important clock is the moment the holdout is revealed, which must be after the agent is told to stop editing.

Minute 0–15: restage the leak

Students begin with a truncated helper and a generous prompt. The prompt includes the holdout lines, the rate, and the expected total. Most agents then hardcode the total or special-case the triple 499, 499, 17. The public suite, if it only contains that triple, will lie.

The starting tree is small enough to sketch on a whiteboard.

lab/
  src/tax.py
  prompts/task.txt
  oracle/public_sample.json
  oracle/holdout.json
  tools/lint_prompt.py
  tools/check.py

src/tax.py is the only file an agent may edit. prompts/task.txt is the only file a human may edit during the agent session. Both oracle files stay closed. The public sample is fair to describe in words. The holdout is not.

A truncated helper makes the first failure honest.

# src/tax.py
from typing import List


def tax_cents(lines_cents: List[int], rate_bp: int) -> int:
    base = sum(lines_cents)
    return (base * rate_bp) // 10_000  # truncates


def total_cents(lines_cents: List[int], rate_bp: int) -> int:
    return sum(lines_cents) + tax_cents(lines_cents, rate_bp)

Facilitators run the public sample by hand. One hundred plus one hundred cents at 1000 basis points is twenty cents of tax under half-up. Truncation also yields twenty here, which is the trap. A sample that does not distinguish truncation from rounding will bless a cheat. The public sample is for conversation. The holdout is for judgment.

Minute 15–35: split the envelope

Students copy two JSON files from a paper handout, not from chat history. The public sample may be mentioned in prompts/task.txt. The holdout may not. Digits from the holdout are contraband in the prompt, including line items, the rate, and both expected fields.

{
  "id": "public-100-100-1000bp",
  "lines_cents": [100, 100],
  "rate_bp": 1000,
  "expect_tax_cents": 20,
  "expect_total_cents": 220,
  "note": "conversation only; does not distinguish truncate from half-up"
}

The holdout uses a fraction that truncation gets wrong. 499 + 499 + 17 is 1015 cents. 875 basis points produces 88.8125 cents of tax. Half-up on a non-negative value becomes 89. The sealed total is 1104. Truncation yields 88 and 1103. Students should compute that on paper before they trust the file.

{
  "version": 1,
  "cases": [
    {
      "id": "holdout-three-lines-875bp",
      "lines_cents": [499, 499, 17],
      "rate_bp": 875,
      "expect_tax_cents": 89,
      "expect_total_cents": 1104
    }
  ]
}

tools/lint_prompt.py is the usher at the door. It does not grade tax. It only refuses a prompt that contains holdout digits.

# tools/lint_prompt.py
from __future__ import annotations
import json, re, sys
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
PROMPT = ROOT / "prompts" / "task.txt"
HOLDOUT = ROOT / "oracle" / "holdout.json"


def tokens_from_holdout(payload: dict) -> set[str]:
    found: set[str] = set()
    for case in payload["cases"]:
        for key in ("rate_bp", "expect_tax_cents", "expect_total_cents"):
            found.add(str(case[key]))
        for n in case["lines_cents"]:
            found.add(str(n))
    return found


def main() -> None:
    text = PROMPT.read_text()
    banned = tokens_from_holdout(json.loads(HOLDOUT.read_text()))
    hits = sorted({t for t in banned if re.search(rf"(?<!\d){re.escape(t)}(?!\d)", text)})
    if hits:
        raise SystemExit(f"holdout digits leaked into prompt: {hits}")
    print("prompt lint passed")


if __name__ == "__main__":
    main()

The linter is crude on purpose. It will also fire if a student writes a harmless 875 in a comment about an unrelated rate. That friction is cheaper than a hardcoded 1104. Facilitators can allow a spoken discussion of the rounding rule without reciting the holdout arithmetic.

Minute 35–60: a prompt that names a rule, not a score

The allowed prompt talks like a spec, not like a scoreboard. Students should feel the difference in their hands. One version is enough.

Edit only src/tax.py.
Do not read or mention files under oracle/.
Implement tax_cents(lines_cents, rate_bp) in integer cents.
Tax is half-up of (sum(lines) * rate_bp / 10000) for non-negative sums.
total_cents is sum plus tax.
You may reason about a public sample of two 100-cent lines at 1000 bp.
Stop after python tools/lint_prompt.py and python tools/check.py --public both succeed.
Do not ask for other expected numbers.

tools/check.py runs in two modes. --public is what the agent may see on the screen. --holdout is a later human step. Mixing them in one default command invites the model to peek at the failure string, which often reprints the expected cents. The workshop keeps the holdout output off the agent’s transcript until the stop rule fires.

# tools/check.py
from __future__ import annotations
import argparse, json, sys
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]


def half_up(n: float) -> int:
    return int(n + 0.5) if n >= 0 else int(n - 0.5)


def load_cases(name: str) -> list[dict]:
    payload = json.loads((ROOT / "oracle" / name).read_text())
    if name == "public_sample.json":
        return [payload]
    return payload["cases"]


def run(name: str) -> None:
    sys.path.insert(0, str(ROOT / "src"))
    import tax  # noqa: E402
    failures = []
    for case in load_cases(name):
        paper = half_up(sum(case["lines_cents"]) * case["rate_bp"] / 10_000)
        if paper != case["expect_tax_cents"]:
            raise SystemExit(f"oracle {case['id']} is internally inconsistent")
        got_tax = tax.tax_cents(case["lines_cents"], case["rate_bp"])
        got_total = tax.total_cents(case["lines_cents"], case["rate_bp"])
        if got_tax != case["expect_tax_cents"] or got_total != case["expect_total_cents"]:
            failures.append(case["id"])
    if failures:
        raise SystemExit(f"mismatch on {name}: {failures}")
    print(f"{name} passed")


def main() -> None:
    p = argparse.ArgumentParser()
    p.add_argument("--public", action="store_true")
    p.add_argument("--holdout", action="store_true")
    args = p.parse_args()
    if args.public == args.holdout:
        raise SystemExit("choose exactly one of --public or --holdout")
    run("public_sample.json" if args.public else "holdout.json")


if __name__ == "__main__":
    main()

A repaired helper is short. Integer-only students can use (base * rate_bp + 5000) // 10000 for the same non-negative half-up. Either form is acceptable. Returning 1104 as a literal is not, and the holdout exists to catch that once the public sample has already gone green.

# src/tax.py
from typing import List


def tax_cents(lines_cents: List[int], rate_bp: int) -> int:
    base = sum(lines_cents)
    return int((base * rate_bp) / 10_000 + 0.5)


def total_cents(lines_cents: List[int], rate_bp: int) -> int:
    return sum(lines_cents) + tax_cents(lines_cents, rate_bp)

Minute 60–75: reveal the holdout

Hands off the keyboards. Facilitators run python tools/check.py --holdout on a machine the agent cannot see. A hardcoded 1104 from a leaked prompt fails as soon as the handout gains a second holdout case; even a single case fails if the model truncated and never read 1104. The debrief names three failure modes in ordinary language. Echoing is reciting a number from the prompt. Special-casing is an if on the public sample. Truncation is the original bug, still alive because the public sample could not detect it.

Students who passed --public and failed --holdout did not fail the course. They failed the cheat. They then get one more constrained edit, still without holdout digits in the prompt. The second attempt is usually the rounding rule they should have written first.

A second holdout can be added after class without changing the prompt at all. 250 + 250 at 333 basis points is a useful extra: 500 * 333 / 10000 is 16.65, which half-up makes 17. Truncation makes 16. If the helper only memorized 89, this case breaks it. The prompt linter still has nothing new to leak if nobody pastes those numbers into task.txt.

Minute 75–90: rerun on a shared endpoint

The last quarter hour is logistics. A class that depends on fourteen personal API keys will spend this block on billing pages. The same envelope should rerun on one shared box so the holdout command is identical for every student.

MonkeyCode’s free model access and free server option can host that shared rerun when the group has no other common agent endpoint. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The lab does not require that host. A local editor, a vendor key, or a human typing into tax.py all count if the holdout stays out of the prompt. The free path is a classroom convenience, not a quality ranking, a quota promise, or an uptime claim. Facilitators still print the holdout ids on the board only after lint has passed.

The rerun is two commands, in order, on a clean checkout.

python tools/lint_prompt.py
python tools/check.py --public
# agent session, if any, ends here
python tools/check.py --holdout

If lint fails, the agent session is void even when both checks would have passed. A green holdout bought with leaked digits is a different course, closer to open-book recitation than to implementation.

Limits, and who should skip this lab

A digit linter is not cryptography. A model can still infer 89 from a verbose failure string, a stack trace, or a helpful teammate. Facilitators must keep --holdout output off the transcript until the stop rule. The public sample must not be a disguised copy of the holdout. If both files share the same lines, the envelope is theater.

The JSON cases are not a tax specification. They will not catch a helper that special-cases two or three memorized carts. Teams that ship money need property tests, fuzzing, and a review that never happened in this room. The half-up helper also ignores refunds, mixed signs, and jurisdiction tables. Those absences are intentional. They are also reasons not to paste this file into production.

Skip the workshop when the acceptance criteria are a handful of golden numbers the model is supposed to match exactly, such as a fixture dumped from a legacy system. Skip it when students cannot keep a file unread. Skip it when the grade is speed to a green bar. A loop that recites 1104 in twenty seconds should score zero.

The artifact worth keeping is not tax.py. It is the habit of holding out at least one case the agent was never told, then grading that case after the hands stop. The invoice cents are bait. The closed folder is the craft.

Teaching an Agent Loop to Stop: A 90-Minute Workshop

Charlie Zhu — Mon, 14 Sep 2026 21:32:28 +0000

The first time this exercise ran, two students watched their agent rewrite settings.py twelve times in ninety seconds. Every edit looked defensible on its own. The ledger told a different story: the same twelve-character fingerprint appeared on every pass, meaning the model had found a loop and moved in. Nobody had taught the loop when to quit.

That gap is the whole workshop. Recent DEV threads argued that most agents are thin control flow wearing a costume (one example) and that loop engineering has predictable failure modes (another). Both are useful framing, and neither is the point here. The point is that stop conditions can be tested like anything else, and a class of twelve people can prove it in ninety minutes without a single network call.

What the ninety minutes buy

The session is built for pairs, one laptop per pair, Python 3.11 or newer, git, and a terminal. No cloud account is required for the first sixty minutes. The schedule is deliberately front-loaded, because the failure is easier to show than to explain.

Minutes	Block	Artifact produced
0–10	Reproduce a runaway loop	One ledger file with a repeated fingerprint
10–35	Read the guard, run four tests	A green suite and a named `stop_reason` per test
35–60	Add a fifth stop condition	A new reason string plus its test
60–80	Swap the scripted proposer for a live model	One real run, one real ledger line
80–90	Pair review of ledgers	A written exit ticket

The teaching sequence matters more than the timing. Students see a loop burn budget first, instrument it second, and only then connect it to a hosted model. Reversing those steps turns the exercise into a configuration tutorial, which is a different and much weaker class.

The artifact: a loop with testable exits

Everything below runs offline. The scripted propose function stands in for a model so the tests stay deterministic.

# loop_guard.py
"""A bounded agent loop with testable stop conditions. No network required."""
from __future__ import annotations

import hashlib
import json
import time
from pathlib import Path

MAX_STEPS = 6
MAX_SECONDS = 20.0
LEDGER = Path("ledger.jsonl")


def fingerprint(action: str, payload: str) -> str:
    blob = f"{action}\x00{payload}".encode("utf-8")
    return hashlib.sha256(blob).hexdigest()[:12]


def write_ledger(row: dict) -> None:
    with LEDGER.open("a", encoding="utf-8") as fh:
        fh.write(json.dumps(row, sort_keys=True) + "\n")


def _stop(n: int, action: str, payload: str, reason: str, elapsed: float) -> dict:
    row = {
        "step": n,
        "action": action,
        "fp": fingerprint(action, payload),
        "stop_reason": reason,
        "seconds": round(elapsed, 3),
    }
    write_ledger(row)
    return row


def run(task, propose, apply, max_steps=MAX_STEPS, max_seconds=MAX_SECONDS) -> dict:
    """propose(task, n) -> (action, payload); apply(action, payload) -> None."""
    seen: set[str] = set()
    started = time.monotonic()
    step = 0
    for step in range(1, max_steps + 1):
        elapsed = time.monotonic() - started
        if elapsed > max_seconds:
            return _stop(step, "halt", "", "budget:wallclock", elapsed)
        action, payload = propose(task, step)
        fp = fingerprint(action, payload)
        if fp in seen:
            return _stop(step, action, payload, "loop:repeat", elapsed)
        seen.add(fp)
        if action == "done":
            return _stop(step, action, payload, "goal:reached", elapsed)
        apply(action, payload)
    return _stop(step, "halt", "", "budget:steps", time.monotonic() - started)

Four exit paths, four names: goal:reached, loop:repeat, budget:steps, budget:wallclock. Students are asked to say out loud which one they expect before each test runs. The habit of predicting the exit is the actual lesson.

# test_loop_guard.py
import loop_guard as lg


def _script(seq):
    def propose(task, n):
        return seq[min(n - 1, len(seq) - 1)]
    return propose


def test_goal_wins_before_budget():
    row = lg.run("t", _script([("done", "")]), lambda a, p: None, max_steps=5)
    assert row["stop_reason"] == "goal:reached", row


def test_repeat_is_caught():
    row = lg.run("t", _script([("edit", "a")]), lambda a, p: None, max_steps=5)
    assert row["stop_reason"] == "loop:repeat", row


def test_step_budget():
    seq = [("edit", "a"), ("edit", "b"), ("edit", "c")]
    row = lg.run("t", _script(seq), lambda a, p: None, max_steps=3)
    assert row["stop_reason"] == "budget:steps", row


def test_wallclock_budget():
    row = lg.run("t", _script([("edit", "a")]), lambda a, p: None,
                 max_steps=5, max_seconds=-1)
    assert row["stop_reason"] == "budget:wallclock", row

Run python -m pytest -q test_loop_guard.py and the suite reports four passed. Delete ledger.jsonl between runs, or point LEDGER at a temp path, because rows append and old lines look like fresh failures to a reader in a hurry.

The fifth exercise is open-ended. Common additions include a token-delta ceiling, a diff-size cap, and a stop when two consecutive fingerprints share a prefix. Each addition needs its own test; an untested stop reason is a comment with extra steps.

Swapping in a live model

The adapter below is a sketch, not a tested client. It assumes the access you were given speaks an OpenAI-compatible chat endpoint. Adapt the parsing to whatever shape you actually receive.

# adapter_sketch.py — shape only, adapt before use
import json
import os
import urllib.request

ENDPOINT = os.environ["AGENT_ENDPOINT"]
KEY = os.environ["AGENT_KEY"]


def propose(task, n):
    body = {
        "model": os.environ["AGENT_MODEL"],
        "messages": [
            {"role": "system", "content": SYSTEM_PROMPT},
            {"role": "user", "content": f"{task}\nstep {n}"},
        ],
        "temperature": 0,
    }
    req = urllib.request.Request(
        ENDPOINT,
        data=json.dumps(body).encode("utf-8"),
        headers={"Content-Type": "application/json", "Authorization": f"Bearer {KEY}"},
    )
    with urllib.request.urlopen(req, timeout=30) as resp:
        reply = json.load(resp)["choices"][0]["message"]["content"]
    return parse_action(reply)  # ("edit", "path::patch") or ("done", "")

For classes that need a model but not a setup lecture, MonkeyCode's free model access fits this step cleanly, and its free server option covers students whose machines cannot run the harness or who join remotely. The operator states a free allowance on the order of ten million tokens as of September 2026. Treat that number the way the workshop treats every allowance: read the current terms on the project page before scheduling a session around it, and never write a quota into a stop condition. Step and time budgets stay stable when a pricing page does not.

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

Local runner or hosted runner

Situation	Local	Hosted free server
Deterministic tests, no network	Yes	Unnecessary
Live model calls from a shared laptop	Possible	Reasonable
Regulated or personal data	Only here	Avoid without a written agreement
Long jobs needing durable queues	Neither	Neither

Two limits belong on the whiteboard before anyone leaves. The harness proves a loop stops; it says nothing about whether the work is correct, so a green suite is not a quality signal. And the wall-clock check is cooperative — it fires between steps, so a hung call inside propose still needs a process-level timeout and supervisor. The flat JSONL ledger tolerates one writer; concurrent runs interleave and a compliance reviewer will not accept it as an audit log.

Teams with data-residency requirements, anyone building durable job infrastructure, and anyone who needs the ledger to be evidence should skip this approach rather than stretch it. Everyone else leaves with a file that names why their agent quit, a test that proves the name, and one habit that survives the workshop: predict the exit before you run the loop.

If the exercise sounds useful, port loop_guard.py into your own repository and bring a fifth stop_reason to the next session.

The Budget Card Workshop

Charlie Zhu — Sun, 13 Sep 2026 19:46:19 +0000

A lab room at 3:40 p.m. still had one process running. The previous session had asked a coding assistant for a robust HTTP client with retries, then pointed that client at a tiny charging endpoint that failed on purpose. The assistant produced a while loop. The loop treated every timeout as a reason to try again. No ceiling. No receipt. Students packed laptops while the terminal kept printing the same line, like a metronome that refused to leave the stage.

That scene is the whole workshop. AI-generated clients often sound careful. They mention backoff. They mention transient errors. They still forget an old machine-room rule: every outbound call spends a card, and when the card is empty the machine stops.

This outline lasts two hours. It is for people who review patches they did not fully type. It is not a product tour. The artifact is a budget card: a small Python object that travels with each request, counts hops, preserves one request stamp, and fails closed. Students can rerun the worked example on a laptop with only the standard library.

The first ten minutes belong to the upstream. Students save flaky_upstream.py and start it on port 8765. The server is intentionally rude. The first two POST requests to /charge for a given stamp return 503. The third returns 200 and echoes the stamp. That pattern is the classroom weather: enough failure to trigger retries, enough success to prove a ceiling worked.

#!/usr/bin/env python3
"""Flaky charging endpoint for the Budget Card Workshop."""
from collections import defaultdict
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
import json

FAILS_BEFORE_OK = 2
HITS = defaultdict(int)

class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        if self.path != "/charge":
            self.send_error(404)
            return
        stamp = self.headers.get("X-Request-Stamp", "")
        length = int(self.headers.get("Content-Length", "0"))
        body = self.rfile.read(length)
        HITS[stamp] += 1
        hop = HITS[stamp]
        payload = {"ok": hop > FAILS_BEFORE_OK, "hop": hop, "stamp": stamp}
        raw = json.dumps(payload).encode("utf-8")
        status = 200 if payload["ok"] else 503
        self.send_response(status)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(raw)))
        self.send_header("X-Echo-Stamp", stamp)
        self.end_headers()
        self.wfile.write(raw)

    def log_message(self, fmt, *args):
        print("upstream", args[0])

if __name__ == "__main__":
    server = ThreadingHTTPServer(("127.0.0.1", 8765), Handler)
    print("flaky upstream on 127.0.0.1:8765")
    server.serve_forever()

Start it in its own terminal. The room should see one line that names the port.

python3 flaky_upstream.py

If the bind fails, another process still owns 8765. Change the port in the server and in the client together. Do not wrestle the operating system for a number.

The next twenty minutes are for capturing a naive client. Students may type it by hand. They may also ask a coding assistant for a robust retrying client, which is how the runaway loop usually arrives. MonkeyCode can host that generation step if the classroom already uses it. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The project offers free model access and a free server option, which is enough for this lab when a second upstream is useful later. No model name is required. The lesson is the shape of the loop, not the label on the prompt box.

A typical naive client looks calm. It is not.

# naive_client.py — proposed classroom foil, not production code
import json, time, urllib.error, urllib.request

URL = "http://127.0.0.1:8765/charge"

def charge(payload):
    body = json.dumps(payload).encode("utf-8")
    attempt = 0
    while True:
        attempt += 1
        req = urllib.request.Request(URL, data=body, method="POST")
        req.add_header("Content-Type", "application/json")
        try:
            with urllib.request.urlopen(req, timeout=2) as resp:
                print("ok", attempt, resp.read().decode())
                return
        except urllib.error.HTTPError as exc:
            print("retry", attempt, exc.code)
            time.sleep(0.2)

if __name__ == "__main__":
    charge({"sku": "lab-seat", "cents": 1})

Run it against the flaky server. Three attempts can look like design. Change FAILS_BEFORE_OK to 6 and the same client will sit there, polite and endless. The analogy is a subway turnstile that never counts passengers. The gate keeps swinging.

Minute thirty begins the budget card. Students add a tiny dataclass. The card holds a hop ceiling, a hop counter, and a request stamp created once. The client must refuse to send when no hops remain. That refusal is the lesson. Retries are not virtue. They are a spent resource.

# budget_card.py — worked example students can rerun
from __future__ import annotations

from dataclasses import dataclass, field
import json, time, uuid, urllib.error, urllib.request

URL = "http://127.0.0.1:8765/charge"

@dataclass
class BudgetCard:
    max_hops: int
    hops_used: int = 0
    stamp: str = field(default_factory=lambda: uuid.uuid4().hex)

    def remaining(self) -> int:
        return self.max_hops - self.hops_used

    def punch(self) -> None:
        if self.remaining() <= 0:
            raise RuntimeError(f"CEILING stamp={self.stamp} hops={self.hops_used}")
        self.hops_used += 1

def charge(payload: dict, card: BudgetCard) -> dict:
    body = json.dumps(payload).encode("utf-8")
    last_error = None
    while True:
        try:
            card.punch()
        except RuntimeError as exc:
            print(f"receipt stamp={card.stamp} hops={card.hops_used} status=CEILING")
            raise
        req = urllib.request.Request(URL, data=body, method="POST")
        req.add_header("Content-Type", "application/json")
        req.add_header("X-Request-Stamp", card.stamp)
        try:
            with urllib.request.urlopen(req, timeout=2) as resp:
                echo = resp.headers.get("X-Echo-Stamp", "")
                raw = resp.read().decode("utf-8")
                if echo != card.stamp:
                    raise RuntimeError(f"stamp drift sent={card.stamp} echo={echo}")
                print(f"receipt stamp={card.stamp} hops={card.hops_used} status={resp.status}")
                return json.loads(raw)
        except urllib.error.HTTPError as exc:
            last_error = exc
            print(f"hop {card.hops_used} http {exc.code}")
            time.sleep(0.2)
        except urllib.error.URLError as exc:
            last_error = exc
            print(f"hop {card.hops_used} url {exc.reason}")
            time.sleep(0.2)
    raise RuntimeError(f"exhausted without receipt: {last_error}")

if __name__ == "__main__":
    tight = BudgetCard(max_hops=2)
    try:
        charge({"sku": "lab-seat", "cents": 1}, tight)
    except RuntimeError as exc:
        print("expected tight failure:", exc)
    loose = BudgetCard(max_hops=3)
    print(charge({"sku": "lab-seat", "cents": 1}, loose))

The instructor should force a mismatch on purpose. Leave the server at two failures before success. Set max_hops to 2 first. Students watch a clean CEILING instead of a hang. Then they raise the ceiling to 3 and watch the echo come back. The two runs are the same script. Only the card changes.

python3 budget_card.py

After a short break, twenty minutes go to the sticky stamp. Assistant patches often mint a new UUID on every retry, which turns a retry into a new order. The budget card creates the stamp once and copies it onto X-Request-Stamp for every hop. The server echoes it. Students compare the echoed value to the card. If the two strings differ, the client is lying about identity, even if the HTTP status looks fine.

A quick probe makes that lie visible. Students can temporarily move uuid.uuid4().hex inside the while loop, rerun, and read stamp drift on the third hop. Then they move the stamp back onto the dataclass. The failure is the teaching object. The fix is one field that does not get reborn.

The next block is fail-closed logging. The client already prints a one-line receipt: stamp, hops used, and either a status code or the word CEILING. Keep that line boring. Reviewers can grep it. A dashboard can wait. A classroom does not need a metrics vendor to learn that unbounded retry is just a loop with better copy.

The last twenty minutes are optional and remote. A local flaky server teaches the mechanism. A hosted upstream teaches the other failure: extra latency, a cold process, and the temptation to raise the ceiling just this once. Classrooms that already have MonkeyCode’s free server option can point URL at that base path instead of localhost, still sending only the synthetic lab-seat payload. Do not send customer records. Do not send secrets. A budget card is not an access-control system, and a free shared host is not a vault.

Limitations are part of the lab, not a footnote. The server counts hits in process memory, so a restart wipes the flaky weather. The client uses urllib on purpose, which means no connection pool and no HTTP/2 puzzles. Backoff is a fixed 200 milliseconds, which is a metronome, not a production jitter policy. The receipt is stdout. It will not survive a crashed terminal. None of that is accidental. The workshop isolates one idea: hops are finite, and identity must not reset when a hop is spent.

This approach is a poor fit for teams that need load tests, circuit breakers across many hosts, or idempotency stored in a real ledger. It is also the wrong tool for anyone pointing a classroom script at a live billing API. Students who cannot keep synthetic payloads synthetic should stop at the local server. Instructors who cannot read the receipt line in a code review should not add more retries to hide that fact.

The closing exercise is a one-file replay. Students delete __pycache__, restart flaky_upstream.py, and run budget_card.py twice. The tight card must print CEILING. The loose card must print status=200 with the same stamp the server echoed. If those two sentences do not hold, the room has not finished. If they hold, the assistant’s original while True can be thrown away without ceremony.

Readers who want a second upstream after the local run can point the same budget card at MonkeyCode’s free server option and leave the punch logic untouched. The card does not care where the 503 came from. It only cares that the next hop is still allowed.

The Ticket Stub Workshop

Charlie Zhu — Sat, 12 Sep 2026 17:44:54 +0000

The projector still held a stack trace when the student hit send. Ninety minutes remained on the lab clock. The brief had asked for a refund endpoint that returned four fields. The model answered with a cache, a worker queue, and a table the syllabus had never named.

That scene now repeats in intro AI-coding rooms. A loop without a ticket wanders. Invented infrastructure fills the repo. The tests never get an honest first failure, and the clock dies on setup the assignment did not request.

This workshop treats the missing ticket as the lesson. It runs in two hours. Students leave with a stub file, a failing test, and a loop that may edit one path only. The same directory can be unpacked later on another laptop and rerun without the original chat.

A refund is a boring object on purpose. It carries an id, a status, an integer amount, and a currency. When the object is that small, a model that “helps” by adding Redis is easy to catch. The ticket stub is a JSON file that names the object and nothing else. It behaves like a coat-check tag. The coat can be elaborate. The tag is not.

Hour one belongs to the contract, not the model. The first twenty minutes are for copying the stub and changing one field so the file is the student’s. The next thirty minutes are for a test that must fail against an empty handler. A ten-minute break follows. After the break, forty minutes go to a bounded patch loop with a hard stop. The last twenty minutes are a scorecard: did the handler match the stub, and did the loop touch any other file.

Instructors who need a spare box for that loop can use a coding assistant that already offers free model access and a free server option. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is one such option. The lab files do not depend on it. A laptop and pytest are enough, and the scorecard still works if the class never leaves localhost.

The worked example below is a teaching fixture, not a payment system. Save the four files in an empty directory. Students should run the test once before any model is invited in. The red result is the starting gun, not a defect in the harness.

ticket_stub.json is the coat-check tag. Keep it tiny. If a later prompt tries to grow the object, the test will say no.

{
  "name": "refund_ticket",
  "response_keys": ["ticket_id", "status", "amount_cents", "currency"],
  "allowed_statuses": ["pending", "approved", "denied"],
  "example_input": {
    "ticket_id": "r-1042",
    "amount_cents": 2500,
    "currency": "USD"
  }
}

app.py starts as a locked door. The handler exists so imports succeed. It must not pass the test yet.

# Teaching fixture: empty handler for The Ticket Stub Workshop.

def refund_handler(payload: dict) -> dict:
    raise NotImplementedError("workshop start: implement against ticket_stub.json")

test_refund.py is the only grader. It does not inspect style, comments, or extra helpers. It checks shape, allowed status, and the example amounts from the stub.

import json
from pathlib import Path

from app import refund_handler


def test_handler_matches_ticket_stub():
    stub = json.loads(Path("ticket_stub.json").read_text(encoding="utf-8"))
    sample = stub["example_input"]
    got = refund_handler({"ticket_id": sample["ticket_id"]})
    assert set(got.keys()) == set(stub["response_keys"])
    assert got["ticket_id"] == sample["ticket_id"]
    assert got["status"] in stub["allowed_statuses"]
    assert got["amount_cents"] == sample["amount_cents"]
    assert got["currency"] == sample["currency"]

Install the test runner once, then take the first snapshot. That snapshot is what students compare against after the loop.

python -m pip install pytest
pytest -q test_refund.py

The expected first run is a single failure from NotImplementedError. If the test is green at this point, the fixture was edited too early. Restore app.py and start again. Green too soon teaches the wrong reflex.

hourglass.py is the bounded loop. It is a proposal students can execute locally. It does not call a vendor API. It writes a prompt file, waits for a unified diff in patch.diff, and applies that diff only when every touched path is app.py. Three turns is the teaching cap. The cap is a kitchen timer, not a claim about model quality.

#!/usr/bin/env python3
"""Bounded patch loop for the Ticket Stub workshop (local harness)."""
from __future__ import annotations

import subprocess
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parent
ALLOWED = {"app.py"}
MAX_TURNS = 3
PROMPT = ROOT / "PROMPT.md"
PATCH = ROOT / "patch.diff"


def run_tests() -> int:
    proc = subprocess.run(
        [sys.executable, "-m", "pytest", "-q", "test_refund.py"],
        cwd=ROOT,
    )
    return proc.returncode


def write_prompt(turn: int) -> None:
    stub = (ROOT / "ticket_stub.json").read_text(encoding="utf-8")
    app = (ROOT / "app.py").read_text(encoding="utf-8")
    PROMPT.write_text(
        "Turn {turn} of {max_turns}. Edit app.py only.\n"
        "Honor ticket_stub.json. Do not add caches, queues, or files.\n\n"
        "ticket_stub.json:\n{stub}\n\n"
        "app.py:\n{app}\n".format(
            turn=turn, max_turns=MAX_TURNS, stub=stub, app=app
        ),
        encoding="utf-8",
    )


def paths_in_diff(text: str) -> set[str]:
    names: set[str] = set()
    for line in text.splitlines():
        if line.startswith(("--- ", "+++ ")):
            raw = line[4:].split("\t", 1)[0].strip()
            if raw in {"/dev/null", "a/dev/null", "b/dev/null"}:
                continue
            if raw.startswith(("a/", "b/")):
                raw = raw[2:]
            names.add(Path(raw).name if "/" not in raw else raw.split("/", 1)[-1] if raw.startswith(("a/", "b/")) else raw)
            names.add(raw)
    return {n for n in names if n not in {"/dev/null"}}


def apply_patch() -> None:
    text = PATCH.read_text(encoding="utf-8")
    if not text.strip():
        raise SystemExit("patch.diff is empty")
    touched = paths_in_diff(text)
    illegal = {p for p in touched if Path(p).name not in ALLOWED and p not in ALLOWED}
    if illegal:
        raise SystemExit(f"refusing patch; illegal paths: {sorted(illegal)}")
    subprocess.run(["git", "apply", "--unsafe-paths", str(PATCH)], cwd=ROOT, check=True)


def main() -> None:
    if not (ROOT / ".git").exists():
        subprocess.run(["git", "init"], cwd=ROOT, check=True)
        subprocess.run(["git", "add", "app.py", "ticket_stub.json", "test_refund.py"], cwd=ROOT, check=True)
        subprocess.run(["git", "commit", "-m", "workshop start"], cwd=ROOT, check=True)
    for turn in range(1, MAX_TURNS + 1):
        if run_tests() == 0:
            print(f"green on turn {turn - 1 or 'preflight'}")
            return
        write_prompt(turn)
        print(f"wrote {PROMPT.name}; save a unified diff as {PATCH.name}, then press Enter")
        input()
        apply_patch()
    if run_tests() != 0:
        raise SystemExit("still red after hourglass stop")
    print("green under the turn cap")


if __name__ == "__main__":
    main()

The path check above is deliberately strict and a bit blunt. Workshop diffs are small. Students who paste a patch that creates cache.py should see a refusal, not a silent extra module. If git apply is unavailable, instructors can replace that line with a manual copy of app.py after a visual review. The rule does not change. Only app.py moves.

A sample legal patch, for instructors who want a worked answer after the room has struggled, looks like this. Label it as a key. Hand it out only in the debrief.

--- a/app.py
+++ b/app.py
@@ -1,4 +1,14 @@
-# Teaching fixture: empty handler for The Ticket Stub Workshop.
-
 def refund_handler(payload: dict) -> dict:
-    raise NotImplementedError("workshop start: implement against ticket_stub.json")
+    ticket_id = payload["ticket_id"]
+    return {
+        "ticket_id": ticket_id,
+        "status": "pending",
+        "amount_cents": 2500,
+        "currency": "USD",
+    }

That key is intentionally dull. It hard-codes the example amounts from the stub. Dull is a feature. Students who chase a general ledger in forty minutes are practicing a different course. This one rewards a handler that can pass a frozen example without growing a platform.

The scorecard is a spoken pass at the end of hour two. A table keeps the room honest when demos get theatrical.

Check	Pass	Fail
First pytest run was red	Empty handler raised	Handler was prefilled
`ticket_stub.json` unchanged after the loop	File hash matches start	Keys or amounts drifted
Only `app.py` changed	Harness accepted the diff	Extra files or lockfiles appeared
Final pytest run is green	Shape and example match	Status outside the allow-list
Turn count ≤ 3	Hourglass stopped the chat	Students kept pasting after the cap

The analogy holds if someone tries to grade “effort.” A coat-check clerk does not score the embroidery on the coat. The clerk matches the tag. Workshops that praise a model for adding retries, metrics, and a Dockerfile are scoring embroidery. Those extras can be a later lab. They do not belong inside the two-hour stub.

Limitations are part of the method. The harness does not prove the handler would survive a second example. The hard-coded key above would fail a second ticket id if the test ever grew. Three turns do not measure intelligence. They measure whether the room can stop. Free model access and a free server option, when a class uses them, are availability notes rather than an uptime contract. This article does not assign model names, quotas, hardware, or duration to that option, because those figures change and were not verified here against a primary source.

Several groups should skip this pattern. Payment teams must not drop real payer data into a classroom prompt. Anyone who needs a service-level agreement should not treat a free server as production. Instructors who grade by whether the chat “finished” will fight the hourglass and should pick a different assignment. Students who have not yet seen a JSON object can still run the fixture, but they will need a five-minute tour of keys before the first pytest.

The portable result is the directory, not the transcript. A student can zip the stub, the test, the handler, and hourglass.py, open them on a bus, and press the same commands. If a class later wants a shared box so everyone reruns that zip after the local test is green, the free server option mentioned above is there to try. The ticket still has to match. The coat still stays at the door.

The File Fence Lab

Charlie Zhu — Fri, 11 Sep 2026 15:26:25 +0000

A Friday review often begins with a polite subject line. The patch claims to fix a 504 on /invoice. Then the file list arrives: a new Redis helper, a line in requirements.txt, a port in docker-compose.yml, and a comment that the timeout was “probably a cache miss.” Nobody asked for a cache. The timeout lived in one function. The model widened the job because nothing in the repo told it where the fence was.

This lab treats that leak as a teaching object, not a personality debate. AI coding loops are good at local edits and reckless at scope. A file fence is a boring control: a short allowlist, a checker that reads git diff, and a golden test that still fails if the timeout is missing. Students can rerun the whole path on a laptop in ninety minutes. The point is not to win an argument about agents. The point is to make an out-of-scope file fail before a human has to notice Redis.

The fence is a garden gate, not a vault. It stops accidental sprawl. It does not sandbox the model, and it does not replace code review. Treat it as a seatbelt for a lab, then keep the skepticism.

A ninety-minute room

The session opens with a ten-minute story and a broken invoice handler. The instructor shows the 504, the single function that calls an upstream billing API, and a failing test that expects timeout=3. No architecture diagrams. The class can see the leak coming.

Minutes ten through thirty belong to the fence file. Each pair writes fence.txt with two paths: the production module and its test. They are told the next prompt will “fix the 504.” They are not told that a typical model will offer a cache. The constraint has to exist before the prompt, or the prompt will invent a subsystem to look busy.

Minutes thirty through sixty are the checker. Students implement a script that runs git diff --name-only against HEAD and exits nonzero if any path sits outside the fence. The script is allowed to be ugly. It is not allowed to parse unified diffs by hand when Git already knows the names. A green checker on an empty tree is a trap; they must commit the broken handler first so the later patch has a base.

The last half hour is a replay. The same prompt is applied twice: once with the fence ignored, once with the checker in the loop. The golden test stays in both runs. A patch that adds Redis and still forgets timeout=3 fails twice, which is the lesson. A patch that only sets the timeout passes the fence and the test. The debrief is short. Students compare file lists, not vibes.

Worked example students can rerun

The sample app is one module and one test. Save this as app/invoices.py.

# app/invoices.py
from __future__ import annotations

import json
from urllib.request import Request, urlopen


UPSTREAM = "https://billing.example.invalid/invoice"


def fetch_invoice(invoice_id: str) -> dict:
    # Lab bug: the call can hang. The fix is a timeout, not a cache.
    req = Request(UPSTREAM, method="GET")
    with urlopen(req) as resp:  # missing timeout=
        return json.loads(resp.read().decode("utf-8"))

Save the test as tests/test_invoices.py. It does not hit the network. It inspects the call the handler should have made.

# tests/test_invoices.py
from unittest.mock import patch, MagicMock

from app.invoices import fetch_invoice


def test_fetch_invoice_sets_a_timeout():
    fake = MagicMock()
    fake.read.return_value = b'{"id": "inv_1"}'
    with patch("app.invoices.urlopen", return_value=fake) as mocked:
        # urlopen is used as a context manager in the handler.
        mocked.return_value.__enter__.return_value = fake
        mocked.return_value.__exit__.return_value = False
        fetch_invoice("inv_1")
        kwargs = mocked.call_args.kwargs
        assert kwargs.get("timeout") == 3

The fence is two lines. Anything else is a teaching failure waiting to happen.

# fence.txt
app/invoices.py
tests/test_invoices.py

The checker is the artifact that makes the lab replayable. It refuses mystery files even when the model writes a confident commit message.

# check_fence.py
from __future__ import annotations

import subprocess
import sys
from pathlib import Path


FENCE = Path("fence.txt")


def tracked_names() -> list[str]:
    out = subprocess.check_output(
        ["git", "diff", "--name-only", "HEAD"],
        text=True,
    )
    return [line.strip() for line in out.splitlines() if line.strip()]


def allowed() -> set[str]:
    lines = FENCE.read_text(encoding="utf-8").splitlines()
    return {line.strip() for line in lines if line.strip() and not line.startswith("#")}


def main() -> int:
    names = tracked_names()
    if not names:
        print("check_fence: no diff against HEAD; nothing to prove")
        return 0
    extra = [name for name in names if name not in allowed()]
    if extra:
        print("check_fence: files outside fence.txt")
        for name in extra:
            print(f"  {name}")
        return 1
    print("check_fence: diff stays inside the fence")
    return 0


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

A clean replay starts from a tiny Git repo. The commands below assume a POSIX shell and Python 3.11 or newer. Students should not skip the first commit. Without it, git diff HEAD has no fence post to lean on.

mkdir fence-lab && cd fence-lab
git init
mkdir -p app tests
# paste the three files, plus an empty app/__init__.py
printf '' > app/__init__.py
git add app tests fence.txt check_fence.py
git commit -m "lab: broken invoice fetch"
python -m pytest -q || true
python check_fence.py

The first pytest run should fail. The checker should pass, because nothing has been patched yet. That pair of results is the baseline. A lab without a baseline will treat any later green bar as success.

The bad patch, then the small one

Give the model a prompt that sounds helpful and under-specified: “Production is throwing 504 on invoice fetch. Make it reliable.” Leave the fence file in the tree. Many loops will add a client, a dependency, and a comment about caching. Students apply that patch on a branch, then run the two gates.

git checkout -b leaky
# apply the generated patch, then:
python check_fence.py
python -m pytest -q

The checker should fail as soon as redis_client.py or requirements.txt appears. The test may still fail if the timeout never landed. That double failure is useful. It shows that extra architecture did not buy a passing contract.

Reset and try the intended edit. The handler needs one argument, not a new service.

# intended body of fetch_invoice
req = Request(UPSTREAM, method="GET")
with urlopen(req, timeout=3) as resp:
    return json.loads(resp.read().decode("utf-8"))

git checkout main
git checkout -b tight
# edit only app/invoices.py
python check_fence.py
python -m pytest -q

A tight patch prints a calm checker line and a passing test. Students keep both command transcripts. The workshop is not finished until those two transcripts exist. Memory is a poor lab notebook.

If the class needs a shared runner so every pair hits the same Git HEAD, a small always-on box is enough to host check_fence.py as a hook target. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode's free model access and free server option can sit under that shared runner so the lesson stays on the fence file rather than on each student wiring a personal key. The product is scaffolding here, not the subject of the test.

What the fence refuses to be

The checker reads names, not semantics. A model can still replace fetch_invoice with a stub that returns {"ok": true} and stay inside the fence. That is why the golden test exists. A fence without a contract is a dress code. Anyone can wear a tie and still skip the timeout.

Untracked files are another hole. git diff --name-only HEAD will not see a brand-new Redis module until it is staged or committed, depending on how the class applies patches. Instructors should require git add -A before the checker, or extend the script to include git ls-files --others --exclude-standard. The lab should name that hole out loud. Hidden files are how “tiny helpers” sneak past a gate that only watches tracked paths.

The fence is also not an authorization system. It does not stop a prompt from reading secrets in the working tree. It does not replace branch protection. Teams that need isolation still need containers, policy, and a human. This exercise teaches scope discipline for generated diffs. It does not teach production security.

Skip the lab when the change is an incident hotfix under a clock, when the repo has no tests, or when the model is being asked to invent an API that does not exist yet. A fence around a blank folder only trains people to rubber-stamp empty allowlists. Skip it for binary assets and generated lockfiles unless the instructor writes those paths down on purpose. A surprise package-lock.json rewrite is a real review event; hiding it behind a two-line fence teaches the wrong reflex.

Current public threads keep circling the same fatigue: loops that look like agents, patches that look like products, and developers who cannot tell a fix from a side quest. None of that requires a new slogan. It requires a file the checker can read and a test that still cares about timeout=3. After ninety minutes the room should have two transcripts, one leaky and one tight. That pair travels better than a take-home opinion about whether the model is “better at coding.” The fence either held or it did not. The test either saw a timeout or it did not. Everything else can wait for the next lab.

The Prompt Book Workshop

Charlie Zhu — Wed, 09 Sep 2026 15:42:05 +0000

A teaching assistant leaned on the back wall of a Friday lab and watched a deploy bot fail with confidence. The student had wired a loop that looked alive: notice a 502, sleep, retry, then heal. The healing step sent a PATCH to /v2/readyz. The service had never registered that path. The room went quiet in the way rooms go quiet when a demo invents a door that the set does not have.

This workshop exists for that silence. It is a two-hour classroom session that treats an AI coding pass as a fill-in-the-blank beat, not as an autonomous coworker. Students freeze a tiny HTTP service, write a prompt book with one UNKNOWN cell, let a model propose a patch, then run a jealous witness that fails the patch if it invents routes, files, or environment keys.

The analogy is a theater prompt book. Actors may improvise inside a marked beat. They may not hang a new door on the scenery. A model that writes /v2/readyz has hung a door. The rest of the afternoon is practice at catching that door before anyone calls the loop an agent.

What the room actually needs

Each pair needs git, Python 3.11 or newer, and a directory they are allowed to delete. A shared CPU box is enough. When a class does not want to babysit GPUs, the same loop can call MonkeyCode's free model access and host the witness on MonkeyCode's free server option.

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

Those two pieces matter only as a classroom endpoint and a shared scorer. The lab still works if an instructor swaps them for any other model URL already on the syllabus. Students must not paste production secrets into the prompt. A free shared server is also the wrong place for customer traces. The fixture below is public on purpose.

Minutes 0–15: freeze the set

The instructor starts from a repository that already boots. Not a skeleton that will work later. A boring service that answers two paths and nothing else.

mkdir -p prompt-book/{app,tests,contracts,patches}
cd prompt-book
git init

The entire stage is one file.

# app/server.py
from http.server import BaseHTTPRequestHandler, HTTPServer
import json
from urllib.parse import urlparse, parse_qs

ROUTES = {
    "/health": {"status": "ok"},
    "/deploy/status": {"phase": "idle", "last_error": None},
}

class Handler(BaseHTTPRequestHandler):
    def log_message(self, fmt, *args):
        return

    def do_GET(self):
        parsed = urlparse(self.path)
        body = ROUTES.get(parsed.path)
        if body is None:
            self.send_response(404)
            self.end_headers()
            self.wfile.write(b'{"error":"no such route"}')
            return
        payload = json.dumps(body).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(payload)

if __name__ == "__main__":
    HTTPServer(("127.0.0.1", 8088), Handler).serve_forever()

A contract file pins the scenery. That file is the set. Everything else is a prop the model is not allowed to carry onstage.

{
  "allowed_routes": ["/health", "/deploy/status"],
  "allowed_files": [
    "app/server.py",
    "contracts/surface.json",
    "contracts/prompt_book.py",
    "tests/test_surface.py",
    "tests/witness.py"
  ],
  "allowed_env": [],
  "unknown_cell": "surface last_error on GET /deploy/status when fail=1 is present, without adding routes"
}

Students commit the tree and tag it. The tag is the freeze. If a pair is still installing Python at minute fifteen, they are behind, and that delay is useful information rather than a personal failure.

git add app contracts tests
git commit -m "freeze: two routes, no healer"
git tag lab-freeze-1
python3 -m http.server 8088 --bind 127.0.0.1 &
# stop that; the real server is app/server.py
python3 app/server.py &
curl -s http://127.0.0.1:8088/health
curl -s http://127.0.0.1:8088/deploy/status
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8088/v2/readyz

The last curl must print 404. That number is the door that must stay missing.

Minutes 15–40: write the book, not the loop

Most classroom agents are a while-loop wearing a trench coat. Retry, backoff, call a model, hope. This lab forbids the coat until the prompt book is written by hand. Paper first. Then a file the witness can read.

# contracts/prompt_book.py
BOOK = [
    {
        "beat": "GET /deploy/status returns phase idle",
        "allowed": "leave the process running",
        "forbidden": "POST anywhere; invent /readyz or /v2/*",
        "evidence": "keys of ROUTES in app/server.py",
    },
    {
        "beat": "GET /health is 200",
        "allowed": "print the JSON and stop",
        "forbidden": "restart the server or add a sidecar",
        "evidence": "curl -s localhost:8088/health",
    },
    {
        "beat": "UNKNOWN: last_error never changes",
        "allowed": "patch app/server.py so fail=1 writes last_error inside existing ROUTES",
        "forbidden": "add routes, files, or environment variables",
        "evidence": "git diff --name-only lab-freeze-1",
    },
]

The UNKNOWN row is the only invitation the model receives. That is the whole trick. The model is not asked to make deploys reliable. It is asked to fill one cell. A small cell is a kindness to the next pair, who has to grade the result in a noisy room.

Minutes 40–60: one pass, one diff, no chatter

Students copy a prompt that quotes the contract and the UNKNOWN beat. They do not paste the entire repository. They do not ask for production readiness. A short prompt is part of the teaching object.

Fill only the UNKNOWN cell in contracts/prompt_book.py.
Do not add routes.
Do not add files.
Do not add environment variables.
Return a unified diff against app/server.py that sets last_error
to a string when GET /deploy/status?fail=1 is served.
If you cannot stay inside that file, return the single word REFUSE.

They save whatever comes back as patches/round1.diff and strip markdown fences by hand. That stripping is not busywork. A model that cannot stay inside a diff fails the lab even if the idea was clever. Instructors should grade the file on disk, not the chat window.

A worked example that should pass stays on the existing path and reuses urlparse already imported in the freeze. Students can type this by hand if the model refuses, because the witness does not care who authored the hunk.

--- a/app/server.py
+++ b/app/server.py
@@ -16,6 +16,12 @@ class Handler(BaseHTTPRequestHandler):
     def do_GET(self):
         parsed = urlparse(self.path)
+        if parsed.path == "/deploy/status":
+            qs = parse_qs(parsed.query)
+            if qs.get("fail") == ["1"]:
+                ROUTES["/deploy/status"] = {
+                    "phase": "failed",
+                    "last_error": "deploy exploded on purpose",
+                }
         body = ROUTES.get(parsed.path)
         if body is None:

A worked example that must fail invents scenery.

--- /dev/null
+++ b/app/healer.py
@@ -0,0 +1,7 @@
+import urllib.request
+
+def heal():
+    urllib.request.urlopen("http://127.0.0.1:8088/v2/readyz")

Keep both diffs. The failing one is the teaching object. The passing one is only proof the witness can say yes. Pairs that delete the failing diff because it looks embarrassing have thrown away the lesson.

Minutes 60–80: the witness stays rude

The witness is not another model. It clones the freeze, applies the student diff, and compares names and tokens to the contract. Polite tools miss invented doors. This one is supposed to be jealous.

# tests/witness.py
import json, pathlib, shutil, subprocess, sys, tempfile

ROOT = pathlib.Path(__file__).resolve().parents[1]
CONTRACT = json.loads((ROOT / "contracts/surface.json").read_text())
FORBIDDEN = ("/readyz", "/v2/", "os.environ", "getenv(")

def run(diff_path: str) -> int:
    work = pathlib.Path(tempfile.mkdtemp(prefix="prompt-book-"))
    try:
        subprocess.check_call(["git", "clone", "--quiet", str(ROOT), str(work)])
        subprocess.check_call(["git", "checkout", "--quiet", "lab-freeze-1"], cwd=work)
        applied = subprocess.run(["git", "apply", str(pathlib.Path(diff_path).resolve())], cwd=work, capture_output=True)
        if applied.returncode != 0:
            print("apply failed; treat as REFUSE")
            return 2
        names = subprocess.check_output(
            ["git", "diff", "--name-only", "lab-freeze-1"], cwd=work, text=True
        ).split()
        extra = [n for n in names if n not in CONTRACT["allowed_files"]]
        if extra:
            print("invented files:", extra)
            return 1
        text = (work / "app/server.py").read_text()
        for token in FORBIDDEN:
            if token in text:
                print("invented surface:", token)
                return 1
        print("witness ok")
        return 0
    finally:
        shutil.rmtree(work)

if __name__ == "__main__":
    sys.exit(run(sys.argv[1]))

They run it twice, in that order, and they read the exit codes out loud.

python3 tests/witness.py patches/round1.diff
python3 tests/witness.py patches/invented-healer.diff

The first command should print witness ok. The second should name app/healer.py. If both pass, the witness is too polite, and the pair debugs the witness rather than the model. That inversion is the point of the hour. A class that only ever sees green diffs learns nothing about invented infrastructure.

A tiny behavior test belongs beside the witness so a patch cannot pass by deleting the status handler. Keep it stupid.

# tests/test_surface.py
import json, threading, time, urllib.request
import app.server as server

def _serve():
    server.HTTPServer(("127.0.0.1", 8099), server.Handler).serve_forever()

def test_fail_query_sets_last_error():
    t = threading.Thread(target=_serve, daemon=True)
    t.start()
    time.sleep(0.2)
    urllib.request.urlopen("http://127.0.0.1:8099/deploy/status?fail=1")
    body = json.load(urllib.request.urlopen("http://127.0.0.1:8099/deploy/status"))
    assert body["last_error"]
    assert body["phase"] == "failed"

If the class has no extra minutes, skip the pytest file and keep the witness. The jealous script is the artifact. The behavior test is a seatbelt.

Minutes 80–110: debrief on objects, not mythology

The instructor collects three artifacts from each pair: the prompt book, the diff, and the witness exit code. Conversation stays on those objects. A pair that received a beautiful paragraph and no diff has an incomplete lab, not a creative one. A pair that got REFUSE and then wrote the hunk by hand has finished the lab. Authorship is not the scoring axis. Invention is.

Students notice a pattern by minute one hundred. When the UNKNOWN cell is small, the model stays inside the set. When the prompt says make it production ready, the trench coat comes back and new doors appear. The book is what keeps the coat on the hook. The public week of posts about agents that assume too much is useful only as weather. This room measures invention with git diff --name-only and a forbidden-token scan. That is enough for a Friday.

Limitations, and who should skip it

The witness is syntactic. A patch can turn /deploy/status into a confusing mess and still pass because no new path appeared. Teams that need semantic review still need tests that hit the server. The fixture is tiny on purpose. It will not teach Kubernetes, prompt injection, or a monorepo merge. Forbidden-token lists go stale the moment a model invents /ready_z with an underscore. Instructors should extend the list after every class, the way a stage manager tapes down a cable that someone tripped on.

Skip this workshop if the class cannot freeze a git tag. Skip it if the repo contains credentials. Skip it if someone expects a general agent framework at the end of two hours. Skip it for live incident response. A jealous script that rejects unknown files is the wrong tool when the unknown file is the actual fix. Free shared model endpoints and free shared servers are the wrong place for proprietary logs. The outreach offer is useful for a public teaching fixture. It is not a data-processing agreement.

What to copy into Monday's notes

Clone the freeze, fill one UNKNOWN cell, keep the witness rude. That sequence is the reusable artifact. Instructors who want a shared box for the scoring step can point the same scripts at MonkeyCode's free server option and leave the contract files in git where students can read them on the bus home.

The silent door stays closed unless the prompt book opens it.

The Frozen Route Workshop

Charlie Zhu — Sun, 06 Sep 2026 20:57:53 +0000

The projector showed a 201. A student clapped once, then went quiet when the whiteboard still said 200. The JSON body also carried an owner_email field the room had never written down. Twelve laptops were two hours into a parking-hold lab, and the model had been more generous than the contract.

Cheap generation does not cheapen the interface. It makes the interface the only thing worth freezing before anyone opens a chat window. This outline is a two-hour workshop a facilitator can run with stock Python. Students leave with a scorer they can rerun, not a story about velocity.

The scene above is the teaching problem. A model that writes handlers from a paragraph will invent verbs, status codes, and PII-shaped fields because English is not a schema. The lab treats that invention as expected weather. The route is taped to the wall first. The scorer is written second. Only then does anyone ask a model for code.

What the room freezes

The whole product for the evening is one route. POST /holds accepts a lot identifier, a plate, and a duration in minutes. A 200 response echoes the lot, returns a hold_id, and includes an expires_at timestamp. Anything else is a story the scorer is allowed to fail.

Save this file as contract.json and keep it in the repo root. Students may not edit it after minute fifteen. The freeze is the pedagogy.

{
  "method": "POST",
  "path": "/holds",
  "request_required": ["lot_id", "plate", "minutes"],
  "request_types": {
    "lot_id": "string",
    "plate": "string",
    "minutes": "integer"
  },
  "minutes_min": 15,
  "minutes_max": 180,
  "status": 200,
  "response_required": ["hold_id", "lot_id", "expires_at"],
  "forbidden_response_fields": ["price", "owner_email", "ssn", "token"]
}

A frozen route is a fence, not a novel. The analogy that lands in a noisy lab is a parking boom, not a city map. The boom either lifts or it does not. A generated README about "the future of curb inventory" does not lift it.

Minutes 0–20: write the scorer first

Facilitators who skip this block get a room full of green unit tests that never hit the extra fields. The scorer talks HTTP, not frameworks. It posts a fixture, checks the status, checks required keys, rejects forbidden keys, and parses expires_at as UTC.

# score_holds.py
from __future__ import annotations

import json
import sys
import urllib.error
import urllib.request
from datetime import datetime, timezone
from pathlib import Path

CONTRACT = json.loads(Path("contract.json").read_text())
BASE = sys.argv[1] if len(sys.argv) > 1 else "http://127.0.0.1:8080"
FIXTURE = {"lot_id": "LOT-A", "plate": "TEST-001", "minutes": 30}


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


def main() -> None:
    req = urllib.request.Request(
        BASE.rstrip("/") + CONTRACT["path"],
        data=json.dumps(FIXTURE).encode(),
        headers={"Content-Type": "application/json"},
        method=CONTRACT["method"],
    )
    try:
        with urllib.request.urlopen(req, timeout=5) as resp:
            status = resp.status
            body = json.loads(resp.read().decode())
    except urllib.error.HTTPError as exc:
        fail(f"status {exc.code}, expected {CONTRACT['status']}")
    except Exception as exc:  # lab scorer: surface transport errors plainly
        fail(f"transport: {exc}")

    if status != CONTRACT["status"]:
        fail(f"status {status}, expected {CONTRACT['status']}")
    if not isinstance(body, dict):
        fail("response is not an object")

    for key in CONTRACT["response_required"]:
        if key not in body:
            fail(f"missing {key}")
    extra = [k for k in CONTRACT["forbidden_response_fields"] if k in body]
    if extra:
        fail(f"forbidden fields present: {extra}")
    if body.get("lot_id") != FIXTURE["lot_id"]:
        fail("lot_id was not echoed")

    try:
        stamp = datetime.fromisoformat(str(body["expires_at"]).replace("Z", "+00:00"))
    except ValueError:
        fail("expires_at is not ISO-8601")
    if stamp.tzinfo is None:
        fail("expires_at is naive")
    if stamp <= datetime.now(timezone.utc):
        fail("expires_at is not in the future")

    print("PASS")


if __name__ == "__main__":
    main()

Run it against nothing on purpose. The first failure is the lesson that the harness exists without an implementation.

python3 score_holds.py http://127.0.0.1:8080

Students who start by generating a server have already left the workshop. The scorer is the product. The handler is disposable clay.

Minutes 20–40: a stub that fails honestly

Hand out a server that listens and lies. It returns 201, a price, and an email, which is exactly the shape a chatty model likes to invent. The room should watch score_holds.py print FAIL three different ways before anyone prompts a model.

# bad_server.py — intentional contract drift for the first demo
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
import json

class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        length = int(self.headers.get("Content-Length", "0"))
        _ = self.rfile.read(length)
        payload = {
            "hold_id": "temp",
            "lot_id": "WRONG",
            "price": 4.5,
            "owner_email": "desk@example.com",
        }
        raw = json.dumps(payload).encode()
        self.send_response(201)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(raw)))
        self.end_headers()
        self.wfile.write(raw)

    def log_message(self, fmt, *args):
        return

if __name__ == "__main__":
    ThreadingHTTPServer(("127.0.0.1", 8080), Handler).serve_forever()

Start it in one terminal and score it in another. The failures are the curriculum: wrong status, wrong lot, forbidden fields. A facilitator who narrates those three lines saves twenty minutes of later debate about whether the model was "basically right."

Minutes 40–70: generate against the freeze

The prompt is boring on purpose. Students paste contract.json and this sentence, nothing else: implement a Python 3 stdlib server that satisfies this contract and listens on 8080. No product pitch. No parking manifesto. No authentication subplot.

Facilitators who do not want to provision GPUs can run that generation step against MonkeyCode's free model access and point the resulting process at its free server option. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Those two availability claims are the only product facts this lab needs. Model names, token ceilings, and hardware details are out of scope here because they change and because the scorer does not care which vendor emitted the bytes.

The worked implementation students can rerun looks like the following. Label it as a reference solution, not as a transcript of a particular model run. A real lab will produce messier files. The scorer is what keeps the mess from shipping.

# holds_server.py — reference solution for the freeze, not a model transcript
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from datetime import datetime, timedelta, timezone
from uuid import uuid4
import json

class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        if self.path != "/holds":
            self.send_error(404)
            return
        length = int(self.headers.get("Content-Length", "0"))
        try:
            body = json.loads(self.rfile.read(length).decode() or "{}")
        except json.JSONDecodeError:
            self.send_error(400)
            return
        lot_id = body.get("lot_id")
        plate = body.get("plate")
        minutes = body.get("minutes")
        if not isinstance(lot_id, str) or not isinstance(plate, str):
            self.send_error(400)
            return
        if not isinstance(minutes, int) or not (15 <= minutes <= 180):
            self.send_error(400)
            return
        payload = {
            "hold_id": str(uuid4()),
            "lot_id": lot_id,
            "expires_at": (
                datetime.now(timezone.utc) + timedelta(minutes=minutes)
            ).isoformat().replace("+00:00", "Z"),
        }
        raw = json.dumps(payload).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(raw)))
        self.end_headers()
        self.wfile.write(raw)

    def log_message(self, fmt, *args):
        return

if __name__ == "__main__":
    ThreadingHTTPServer(("0.0.0.0", 8080), Handler).serve_forever()

python3 holds_server.py
python3 score_holds.py http://127.0.0.1:8080

A PASS here is not a product launch. It is proof that the frozen route and the process agree for one fixture. That is the entire bar for hour one.

Minutes 70–100: mutate the fence

Change one number in contract.json. Raise minutes_min from 15 to 45, or add spot_id to response_required. Do not touch the server. Run the scorer again and wait for FAIL.

This is the week’s actual argument about cheap code. When generation is fast, drift is also fast. A route that is not re-scored after a one-line contract edit is already folklore. Students should feel the FAIL in the same terminal that printed PASS twenty minutes earlier. The contrast teaches more than a slide about technical debt.

A second mutation is enough. Point GET at /holds with curl and confirm the scorer still speaks only POST. Then post a body with minutes as a string. The reference server rejects it. Many generated servers will coerce the string and look helpful. Helpful coercion is still a broken freeze.

curl -sS -D - -o /tmp/hold.json \
  -H 'Content-Type: application/json' \
  -d '{"lot_id":"LOT-A","plate":"TEST-001","minutes":"30"}' \
  http://127.0.0.1:8080/holds

Facilitators keep a parking lot of extra mutations and do not run them unless the room is early. Extra fields in the request, a naive expires_at, a 201 that otherwise looks perfect. Each one is a five-minute drill, not a new lecture.

Minutes 100–120: debrief without a victory lap

Name the three failures the stub produced. Name the mutation that broke the passing server. Collect one generated file that added token or price and read that object aloud. The room now has language for a review comment that is not "the AI did a pretty good job."

The artifact to keep is the pair of files: contract.json and score_holds.py. The handler can be deleted. Next week’s lab can freeze a different route and reuse the same scoring shape. That reuse is the point. Workshops that ship a framework tour do not transfer. A scorer transfers.

Limitations

The harness is syntactic. It does not prove that hold_id values are unique, that holds expire, or that two overlapping plates conflict. It does not speak TLS, auth, or idempotency keys. A 200 with the right keys can still be a lie about the parking lot.

Free model access and a free server are lab plumbing. They are not an SLA. Shared or short-lived hosts drop connections. Generated code may bind 127.0.0.1 when the scorer runs elsewhere, or it may listen on a different path because the prompt drifted. The freeze does not prevent that. It only makes the miss loud.

This outline also refuses several audiences on purpose. It is the wrong tool for a production permitting system, a graded exam that still needs human design review, or a team that will not freeze a contract before prompting. Facilitators who let students describe "a parking app" in a paragraph will reproduce the opening scene. People hunting for model leaderboards will be bored. The lab does not rank vendors.

Clock time assumes a room that already has Python 3. If half the laptops are installing runtimes, cut the second mutation and keep the honest stub. The stub is the cheaper half of the teaching.

Print the contract. Score a liar. Generate against the freeze. Score again. Mutate one field. Score a third time. That sequence is the workshop. The model is a guest in it, not the host.