DEV Community: Riley Zhang

Weekend Build Log: Freeze the Scope Card First

Riley Zhang — Thu, 24 Sep 2026 19:21:19 +0000

You sit down on Saturday with a side project idea.
The idea is a helper that reviews a local git diff.
You want comments, a summary, and a patch suggestion.

Two hours later the notes include a web UI.
You still have no command that runs on your laptop.
Scope grew faster than the demo you promised yourself.

You fix that with a scope card on disk.
The card is a small JSON file you write first.
No model call is allowed before that file exists.

This is a plan you can run this weekend.
It is not a report of measured results.

What you are actually building

You are building a weekend gate, not a product.
The gate answers three questions in one file.
What stays in scope for this single demo.

What did you cut on purpose this weekend.
Which single step is allowed to call a model.
You keep the tool local and boring on purpose.

A Python script writes the card to disk.
A second command checks the card before you continue.
You can read that file in any text editor.

The scene you already know

You told yourself the demo needed a dashboard.
Then you added login, because dashboards need users.
Then you added a queue, because login needs jobs.

None of that helps you judge a diff today.
Cut the dashboard before you write more code.
Cut login, queues, and streaming from the plan.

Keep one input path and one output file.
That is enough for a Sunday afternoon demo.
You can add surfaces later, after the gate works.

Step 1: Put the card on disk

Create a file named scope_card.py in an empty folder.
The script below is a proposal you can run locally.
It was not executed as part of this draft.

Treat the sample paths as examples, not as your repo.
The script only writes JSON and checks required keys.
It does not read secrets and it does not open a network socket.

#!/usr/bin/env python3
"""Write a weekend scope card before any model call."""

import json
import sys
from datetime import datetime, timezone
from pathlib import Path

REQUIRED = ("goal", "in_scope", "cut", "model_step", "skip_until")

def build_card(goal: str) -> dict:
    return {
        "goal": goal,
        "in_scope": [
            "read a unified diff from stdin",
            "write one scope card",
        ],
        "cut": [
            "web UI",
            "auth",
            "job queue",
            "multi-file patch apply",
        ],
        "model_step": "summarize the diff in one paragraph",
        "skip_until": "card file exists and checks pass",
        "written_at": datetime.now(timezone.utc).isoformat(),
    }

def main() -> int:
    if len(sys.argv) != 3:
        print("usage: scope_card.py write|check CARD.json", file=sys.stderr)
        return 2
    command, raw_path = sys.argv[1], sys.argv[2]
    path = Path(raw_path)
    if command == "write":
        card = build_card("Review one local diff this weekend.")
        path.write_text(json.dumps(card, indent=2) + "\n", encoding="utf-8")
        print(f"wrote {path}")
        return 0
    if command == "check":
        card = json.loads(path.read_text(encoding="utf-8"))
        missing = [key for key in REQUIRED if not card.get(key)]
        if missing:
            print("missing: " + ", ".join(missing))
            return 1
        print("scope card ok")
        return 0
    print("unknown command", file=sys.stderr)
    return 2

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

Run the write command before you open a chat window.

python3 scope_card.py write ./scope-card.json
python3 scope_card.py check ./scope-card.json

You should see a write line, then a pass line.
If the check fails, you do not call a model yet.
Fix the card, then run the check command again.

A missing card file raises an error from the script.
Treat that error as a failed check, not a surprise.

Step 2: Freeze the cut list

Open the JSON file and edit the cut array.
Write the features you will not build this weekend.
Be specific, or the list will not hold you.

Good cuts name a surface you were tempted to add.
Bad cuts say polish, or later, without a boundary.
Your demo is the check command plus one summary.

Everything else stays in the cut list until Monday.
If you feel a new idea, append it to cut.
Do not promote it into scope during the same sitting.

Step 3: Place the free option behind the gate

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

MonkeyCode matters only after the check command passes.
The operator describes free model access for that step.
The operator also describes a free server option.

Outreach notes also mention a large free token pool.
Some of those notes say ten million tokens.
This draft does not verify that number, or any quota.

Do not plan the weekend around an unverified allowance.
Model names, hardware, and duration are also unverified here.
Read the current project docs before you rely on a limit.

The operator presents the project as open source.
Confirm the license in a repository you actually trust.
This article does not link a repo and does not quote a license.

Use the table as a stop rule, not as a benchmark.
No timing numbers were measured for this article.
No quality scores were collected for this draft either.

Your constraint	Stay local	Free model or free server	Stop
Card file missing	Write the card	Do not call yet	Stop
Diff is short enough to read yourself	Optional dry run	One summary call	Stop after one call
Prompt would include a secret	Redact first	Only after redaction	Stop if you cannot redact
You want a hosted run, not a local GPU	Skip GPU plans	Free server option may fit	Stop if docs show no fit
You need a named model or a fixed quota	Do not invent one	Check live docs	Stop if docs disagree

The free server option is a convenience claim, not a spec.
This log does not name a region, a size, or a duration.
If the docs do not match your need, keep the script local.

The scope card still works with no network at all.
That is the fallback when a free tier is unclear.
You do not lose the demo if the signup page changes.

Step 4: Unlock one model step

After the check passes, you may send the diff once.
Send the diff text, not your whole repository.
Ask for one paragraph, not a rewritten project.

Save the reply next to the card, in a file you choose.
Do not paste the reply back into a second prompt.
One pass is the contract you wrote in the card.

python3 scope_card.py check ./scope-card.json && echo "model step unlocked: one summary, then stop"

That shell line does not contact any service.
It only shows the gate you should keep in front.
Wire your own client after the check command succeeds.

If the client errors, stop and read the error text.
Do not add retries, a queue, or a second prompt.
A failed call is a stop, not a new feature request.

Step 5: Write down the skips

Add a short note under the card before you close the laptop.
List what you skipped, in the same words as the cut field.
This is the part future you will thank yourself for.

You skipped the web UI on purpose this weekend.
You skipped auth and the job queue entirely.
You skipped applying a patch to the work tree.

You skipped streaming tokens into a browser pane.
You skipped comparing providers on speed or price.
Those skips are the point of this weekend build.

A working demo is the card plus one summary file.
A larger demo can wait until the cut list changes.
Changing the list is a new weekend, not a midnight edit.

Step 6: Run the local test plan

You can run these checks without creating an account.
They prove the gate, not a model quality score.
Run them in the same empty folder as the script.

First, run write, then check, and expect a zero exit code.
Second, delete the goal key and expect the check to fail.
Third, restore the goal key and expect the check to pass.

Fourth, run the sample shell line and read the unlock text.
Fifth, confirm no command in this log sends your diff out.
If a check fails, fix the script before any signup.

Do not treat a green check as a product test.
It only means the card has the required keys.
Model quality is outside the scope you froze.

Limits that stay in force

This workflow will not review a huge diff well.
A few hundred lines is a judgment call, not a measured cap.
The script does not parse git, and it does not call git.

You still produce the diff yourself and paste with care.
Secrets in that diff are your problem to remove first.
Never put tokens, keys, or private URLs into the prompt.

Free model access can change without this article updating.
Free server access can change in the same way.
This page is not a status board and not a contract.

If a current doc contradicts a sentence here, trust the doc.
If a quota page is missing, assume you do not have that quota.
The card workflow does not depend on either free claim.

Who should skip this

Skip this approach if your demo needs a hosted UI today.
Skip it if you must apply patches without a human review.
Skip it if the diff holds secrets you cannot redact.

Skip it if you need a guaranteed quota for a public launch.
Skip it if you wanted a benchmark of model quality.
This log has no quality scores and no latency numbers.

Use the gate if extra features keep eating your Saturday.
Use it if one local JSON file will keep you honest.
Use it if you can stop after a single summary.

What you should leave with

You leave with a command that writes a scope card.
You leave with a check that blocks the model step.
You leave with a written list of cuts you can defend.

That is a demo, even without a fancy screen.
If you already have MonkeyCode access, keep it behind the check.
One summary after a passing card is enough for this weekend.

Preflight the Prompt Like You Preflight the Compiler

Riley Zhang — Wed, 23 Sep 2026 16:13:58 +0000

The lab clock read 18:12. Twenty-eight laptops sat on one long table, each unzipped from the same starter archive. Course staff had pointed office hours at a shared coding-assistant endpoint so nobody had to paste a personal key into a homework README. Then the first wave of requests left the room, and the endpoint went quiet in the same way a compiler farm goes quiet when every job ships a tarball.

Nobody had written a clever exploit. Students had been told to give the assistant enough context. Enough, in this room, meant the solution file, the README, a 1.8 MB weather extract, and in two cases a stray node_modules tree that should never have landed on a lab image. The endpoint did not fail closed. It just got slow. Slow looks like thoughtfulness on one screen. From the TA desk it looks like a baggage carousel that never stops.

A compiler would have refused the blob before the link step. A prompt packer often does the opposite. It treats every extra path as kindness. This note is a proposed lab playbook, not a war story from a named campus. Label every snippet below as a throwaway sketch until you run it on your own image.

The room failed on weight, not on wit

Shared endpoints punish variance more than they punish bad ideas. One student sends 4 KB of normalize.py. The next student sends that file plus stations.csv plus a copied lecture PDF. Both think they followed the same instruction. Only one of those payloads is a homework question. The other is a moving van.

Airports already solved the social part of this. A bag that does not fit the scale does not board because the owner smiled. The scale is public. The cap is printed. The receipt is boring on purpose. A 90-minute lab needs that object more than it needs another slide about “being careful with context.”

The assignment, then, is not “get a patch from a model.” The assignment is to produce a receipt the autograder can read, then maybe spend one remote call. If the receipt is wrong, the remote call never happens. That ordering is the whole intervention.

What the receipt has to prove

A useful receipt is smaller than a chat log and stricter than a screenshot. It has to name every path that entered the prompt, the raw byte size of each path, a class-defined cap, and a boolean that says whether the packer would have boarded the bag. It also has to be local. Students without a network path still need a gradeable artifact.

Treat token estimates as a labeled heuristic, not as a tokenizer. Character count divided by four is a ruler you can explain in one sentence. It is not a claim about any vendor’s bill. Print both bytes and that estimate. Grade the bytes. The estimate exists so a student can see order of magnitude before they argue with the cap.

Keep secrets out of the receipt body. A CSV that contains a column named api_key is still a CSV. The packer should refuse that filename pattern the same way it refuses .env. The point is not cryptography. The point is that a homework zip should not become an egress channel because someone wanted “more context.”

Artifact: a compiler-shaped prompt scale

Create a disposable homework tree. Do not point this at a real course repo until the exit codes are boring.

mkdir -p lab_scale/{src,data,hidden}
cat > lab_scale/src/normalize.py <<'PY'
"""Normalize station rows. Keep this file small on purpose."""
COLUMNS = ("station_id", "celsius")

def row_ok(parts):
    return len(parts) == 2 and parts[1].replace(".", "", 1).isdigit()
PY
printf '%s\n' 'station_id,celsius' 's1,12.0' 's2,bad' > lab_scale/data/stations.csv
python - <<'PY'
from pathlib import Path
p = Path("lab_scale/data/stations_big.csv")
p.write_text("station_id,celsius\n" + "s,1\n" * 80000, encoding="utf-8")
print(p.stat().st_size)
PY
echo 'TOKEN=lab-demo-not-a-secret' > lab_scale/hidden/dummy.env

stations_big.csv exists to fail. dummy.env exists to fail louder. The only file that should board in the happy path is src/normalize.py.

The packer below walks an allowlist, skips denylisted names, and writes prompt_receipt.json next to the homework. It never opens a socket. Network access is a later hop with a different exit code.

# prompt_scale.py
from __future__ import annotations

import json
import os
import sys
from pathlib import Path

ALLOW_SUFFIX = {".py", ".md", ".txt"}
DENY_NAME = {".env", ".git", "node_modules", "__pycache__"}
DENY_SUFFIX = {".csv", ".pdf", ".zip", ".png"}
MAX_FILE_BYTES = 8_000
MAX_PROMPT_BYTES = 12_000
ROOT = Path(os.environ.get("LAB_ROOT", ".")).resolve()


def blocked(path: Path) -> str | None:
    parts = set(path.parts)
    if parts & DENY_NAME:
        return "denied_name"
    if path.name in DENY_NAME:
        return "denied_name"
    if path.suffix.lower() in DENY_SUFFIX:
        return "denied_suffix"
    if path.suffix.lower() not in ALLOW_SUFFIX:
        return "suffix_not_allowed"
    return None


def weigh() -> dict:
    files = []
    refused = []
    total = 0
    for path in sorted(ROOT.rglob("*")):
        if not path.is_file():
            continue
        rel = str(path.relative_to(ROOT)).replace("\\", "/")
        reason = blocked(path)
        size = path.stat().st_size
        if reason:
            refused.append({"path": rel, "bytes": size, "reason": reason})
            continue
        if size > MAX_FILE_BYTES:
            refused.append({"path": rel, "bytes": size, "reason": "file_cap"})
            continue
        text = path.read_text(encoding="utf-8", errors="replace")
        files.append({"path": rel, "bytes": len(text.encode("utf-8"))})
        total += len(text.encode("utf-8"))
    estimate = total // 4  # heuristic ruler, not a vendor tokenizer
    boarded = total <= MAX_PROMPT_BYTES and any(f["path"].startswith("src/") for f in files)
    return {
        "root": str(ROOT),
        "files": files,
        "refused": refused,
        "prompt_bytes": total,
        "char_div_4_estimate": estimate,
        "caps": {"file": MAX_FILE_BYTES, "prompt": MAX_PROMPT_BYTES},
        "boarded": boarded,
    }


def main() -> int:
    receipt = weigh()
    out = ROOT / "prompt_receipt.json"
    out.write_text(json.dumps(receipt, indent=2) + "\n", encoding="utf-8")
    print(out)
    print(f"PROMPT_BYTES={receipt['prompt_bytes']}")
    print(f"BOARDED={str(receipt['boarded']).lower()}")
    if not receipt["boarded"]:
        print("preflight_refused")
        return 2
    return 0


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

Run it from the homework root. The command is the lab’s compiler invocation. Students should learn that exit code 2 is a successful refusal, not a broken laptop.

cd lab_scale
LAB_ROOT=. python ../prompt_scale.py; echo EXIT:$?
python -m json.tool prompt_receipt.json | head

Expect data/stations.csv and data/stations_big.csv in refused with denied_suffix. Expect hidden/dummy.env in refused with denied_name. Expect src/normalize.py under files. If BOARDED=true on this tree, the allowlist drifted. Fix the packer before you add a network hop.

Autograder contract, not a vibe check

Staff can grade the receipt with a second script that never calls a model. That split matters in a room where twenty-eight machines share one wireless hop. The grader below is intentionally dull. Dull is what you want at 18:40 when three students still have a CSV in the prompt.

# grade_receipt.py
import json
import sys
from pathlib import Path

needed = {"files", "refused", "prompt_bytes", "boarded", "caps"}

def grade(path: Path) -> int:
    data = json.loads(path.read_text(encoding="utf-8"))
    missing = needed - set(data)
    if missing:
        print(f"schema_missing={sorted(missing)}")
        return 2
    boarded_csv = [r for r in data["files"] if r["path"].endswith(".csv")]
    boarded_env = [r for r in data["files"] if r["path"].endswith(".env")]
    if boarded_csv or boarded_env:
        print("egress_path_in_files")
        return 2
    if data["prompt_bytes"] > data["caps"]["prompt"] and data["boarded"]:
        print("cap_and_flag_disagree")
        return 2
    print("receipt_ok")
    return 0

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

python grade_receipt.py lab_scale/prompt_receipt.json; echo EXIT:$?

A student who cannot reach any remote host can still submit a zip that contains prompt_receipt.json and a packer log. The course can mark that work without pretending the wireless hop was part of the learning objective.

Keep the last hop as an environment variable

Only after the receipt is green should a staff image offer a single POST. Leave the host name out of the homework zip. Bake a timeout. Send the already-weighed text, not a second walk of the tree. The sketch uses the standard library so a lab image does not need a vendor SDK.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. If course staff already have MonkeyCode's free model access and free server option, MODEL_HTTP_URL can point at that hop once the receipt is local and boring. The syllabus still grades the scale. The product is a last mile, not the assignment.

# last_hop.py
import json
import os
import urllib.error
import urllib.request
from pathlib import Path

ROOT = Path(os.environ.get("LAB_ROOT", ".")).resolve()

def pack_prompt(receipt: dict) -> str:
    chunks = []
    for item in receipt["files"]:
        text = (ROOT / item["path"]).read_text(encoding="utf-8")
        chunks.append(f"# {item['path']}\n{text}")
    return "\n\n".join(chunks)

def main() -> None:
    receipt = json.loads((ROOT / "prompt_receipt.json").read_text(encoding="utf-8"))
    if not receipt["boarded"]:
        raise SystemExit("refusing last hop: receipt not boarded")
    url = os.environ.get("MODEL_HTTP_URL", "").strip()
    if not url:
        print("NO_REMOTE=1")
        print("prompt_chars", len(pack_prompt(receipt)))
        return
    body = json.dumps({"prompt": pack_prompt(receipt), "receipt_bytes": receipt["prompt_bytes"]}).encode("utf-8")
    req = urllib.request.Request(url, data=body, headers={"Content-Type": "application/json"}, method="POST")
    try:
        with urllib.request.urlopen(req, timeout=20) as resp:
            print(resp.status)
            print(resp.read()[:400])
    except urllib.error.URLError as exc:
        raise SystemExit(f"last_hop_failed:{exc}")

if __name__ == "__main__":
    main()

LAB_ROOT=lab_scale python last_hop.py
# MODEL_HTTP_URL remains unset on purpose during the first drill

Unset MODEL_HTTP_URL is a feature. It lets a student on a train finish the weighed prompt without turning network loss into a zero. Staff can export the variable on the lab image later. Do not print the URL into the receipt. Receipts get zipped. Zips get uploaded. Uploads outlive the office-hour VLAN.

Three drills that should fail in public

Run these as a projected demo, not as a surprise on homework night. The first drill adds the big CSV to the allowlist in a local fork and shows the file cap fire. The second drill copies dummy.env to src/notes.env and shows that a src/ prefix does not launder a denylisted name. The third drill raises MAX_PROMPT_BYTES in a student copy and shows the grader catching cap_and_flag_disagree if they also force boarded to true by hand.

# drill 1: prove the CSV never boards even if a student edits ALLOW_SUFFIX
python - <<'PY'
from pathlib import Path
text = Path("prompt_scale.py").read_text()
assert ".csv" not in text.split("ALLOW_SUFFIX")[1].split("}")[0]
print("allowlist_does_not_admit_csv")
PY

# drill 2: name check beats directory prefix
cp lab_scale/hidden/dummy.env lab_scale/src/notes.env
LAB_ROOT=lab_scale python prompt_scale.py || true
python - <<'PY'
import json
from pathlib import Path
data = json.loads(Path("lab_scale/prompt_receipt.json").read_text())
hits = [r for r in data["refused"] if r["path"].endswith("notes.env")]
print(hits[0]["reason"] if hits else "MISSING_REFUSAL")
PY
rm lab_scale/src/notes.env

Public failure is the teaching aid. If the only demo is a green hop, students learn that the scale is ceremonial. Ceremonial scales get deleted the night before the deadline.

Decision table for the 90-minute session

Object	In the zip	Why
`prompt_receipt.json`	Yes	Autograder can mark a dead wireless hop
Packer source	Yes	Staff can see who widened the allowlist
`src/*.py` that boarded	Yes	That is the actual question
Large CSV or PDF	No	Weight, not “context”
`.env` and key-shaped files	No	Homework is not an egress path
Absolute `MODEL_HTTP_URL`	No	Receipts outlive the lab VLAN
Vendor SDK	No	Lab images stay small
Multi-file agent loop	No	Congestion returns under a new name

Print the table in the assignment PDF. Future staff will try to replace it with a paragraph about responsibility. Paragraphs do not produce exit codes.

Limits of a byte scale

This playbook measures weight and obvious filename classes. It does not understand that two short Python files can still leak a production hostname. It does not parse CSV headers for PII. It does not prove that a remote model will return a useful patch. A boarded receipt is permission to spend a hop, not evidence that the hop was wise.

The character-div-four figure will disagree with whatever tokenizer a host uses. Teach that disagreement in the first ten minutes or students will treat the receipt as a billing document. It is a baggage tag. Billing, if it exists at all, lives on the operator side of MODEL_HTTP_URL and is out of scope for this sketch.

Timeouts, auth headers, and retries are omitted. A hung last hop can still freeze a row of laptops if staff skip the unset-URL drill. Free remote capacity can change or disappear. Keep the local scale so the session still completes when the hop does not.

Do not use this as production policy for a company monorepo. Company egress needs review paths, secret scanners with real detectors, and an owner who is not a TA with a stopwatch. Do not use it as a substitute for test fixtures. A model that never sees stations.csv cannot be blamed for failing to clean s2,bad. That case belongs in tests/, which this packer never boards.

Who should skip the scale

Skip this design if you already meter prompts in CI with an enforced tokenizer and a budget account. Skip it if the course goal is long-horizon agents that must read data files to finish the task. Skip it if students are working on personal machines with no shared bottleneck and no zip-based hand-in.

A 30-seat room is a fairness problem before it is a model-quality problem. The compiler already taught that lesson with object files that grew too large to link. Put the same refusal in front of the prompt packer. Check the receipt into the homework zip. Leave the host name out of the zip. Students who never reach a remote still pass when the preflight refuses for a documented reason.

Weekend Build Log: Replay the Tool Call From Disk

Riley Zhang — Tue, 22 Sep 2026 14:32:24 +0000

Saturday at 2 p.m. you promised a working agent demo.
The live model call hangs for forty painful seconds.
Your guest watches a spinner instead of a result.

You do not have a product problem today.
You have a demo problem mixed with network risk.
The model is not the bottleneck you think.

This log cuts the live path on purpose.
You freeze one tool schema and one fixture.
Then you replay the call from disk every time.

The scene you are actually in

You want a tiny weekend agent that answers.
It should call one tool and print one result.
That sentence hides three unstable moving systems.

The model may rename arguments without warning you.
The third-party API may rate-limit your cafe demo.
Your laptop may drop Wi-Fi at the worst moment.

A live demo that needs all three will flake.
Flaky demos teach nothing and burn the hour.
You need a path that fails on your terms.

Why live tool calling flakes on Saturday

Tool calling looks simple in clean architecture slides.
The model emits a function name plus arguments.
Your code then executes that call against something.

Each arrow can fail in a different way.
Wrong key names break your handler immediately.
Wrong types pass JSON and fail one layer later.

A weekend guest cannot debug that stack with you.
They came to see one result, not your traceback.
So you freeze the arrow that leaves the model.

What you keep this weekend

You keep one tool with a frozen JSON schema.
You keep one local handler with no HTTP client.
You keep one fixture file checked into git.

The CLI must print a result from that fixture.
The handler must reject any live URL it sees.
That is the whole working demo this Saturday.

What you cut without apology

You skip the chat UI this weekend completely.
You skip streaming tokens and fake typing indicators.
You skip OAuth, retries, and multi-tool routing logic.

You also skip one live call during the demo.
Live calls belong in a later gated command.
The Saturday demo must run with Wi-Fi off.

The artifact: four small files

Create a folder named replay_demo on disk.
Put four files in it with boring names.
You should read every file in one sitting.

schema.json holds the frozen tool contract.
fixture.json holds one captured tool call.
handler.py holds local logic and no HTTP.
replay.py holds the only demo command.

Skip frameworks, agent SDKs, and extra config files.
Guests can follow the files in numbered order.

Step 1: Freeze the tool schema first

Do not ask a model to invent this contract.
You write the schema by hand on purpose.
The model may fill values later, never keys.

{
  "name": "lookup_order",
  "description": "Return a local order summary",
  "parameters": {
    "type": "object",
    "additionalProperties": false,
    "required": ["order_id"],
    "properties": {
      "order_id": {
        "type": "string",
        "pattern": "^ORD-[0-9]{6}$"
      }
    }
  }
}

Notice there is no url field present.
There is no api_key field either here.
The contract cannot request the public network.

Step 2: Write the fixture by hand

A fixture is one captured call, not a dump.
Use one object and one allowed order_id value.
You should be able to diff it during review.

{
  "tool": "lookup_order",
  "arguments": {
    "order_id": "ORD-100042"
  },
  "source": "disk"
}

The "source": "disk" field is your gate.
Replay code must refuse any other source value.
That stops a future you from wiring live calls.

Step 3: Build a handler that cannot fetch

The handler maps order_id to a local dict.
It never imports urllib, httpx, or requests.
If a URL sneaks in, it raises immediately now.

# handler.py
from __future__ import annotations

ALLOWED_PREFIX = "ORD-"
ORDERS = {
    "ORD-100042": {"status": "shipped", "item": "USB cable"},
}


def lookup_order(order_id: str) -> dict:
    if "://" in order_id:
        raise ValueError("live urls are not allowed")
    if not order_id.startswith(ALLOWED_PREFIX):
        raise ValueError("order_id failed the local prefix")
    row = ORDERS.get(order_id)
    if row is None:
        raise KeyError("unknown order_id in local map")
    return {"order_id": order_id, **row}

This file is the demo core, not a toy.
Guests can read it in about thirty seconds.
You can run it with the Wi-Fi fully killed.

Step 4: Replay from disk, not from a model

The replay command loads schema and fixture together.
It validates keys against the frozen schema first.
Then it calls the local handler exactly once.

# replay.py
from __future__ import annotations
import json
import sys
from pathlib import Path
from handler import lookup_order

ROOT = Path(__file__).parent


def load_json(name: str) -> dict:
    return json.loads((ROOT / name).read_text())


def validate(schema: dict, fixture: dict) -> None:
    if fixture.get("source") != "disk":
        raise SystemExit("refusing a non-disk fixture")
    if fixture.get("tool") != schema.get("name"):
        raise SystemExit("fixture tool does not match schema")
    args = fixture.get("arguments") or {}
    required = schema["parameters"]["required"]
    for key in required:
        if key not in args:
            raise SystemExit(f"missing argument: {key}")
    extra = set(args) - set(schema["parameters"]["properties"])
    if extra:
        raise SystemExit(f"unknown arguments: {sorted(extra)}")


def main() -> None:
    schema = load_json("schema.json")
    fixture = load_json("fixture.json")
    validate(schema, fixture)
    result = lookup_order(fixture["arguments"]["order_id"])
    json.dump(result, sys.stdout, indent=2)
    sys.stdout.write("\n")


if __name__ == "__main__":
    main()

Run it like a normal weekend Python script.

cd replay_demo
python3 replay.py

Expected output stays tiny, boring, and stable.

{
  "order_id": "ORD-100042",
  "status": "shipped",
  "item": "USB cable"
}

If that print works, the demo already works.
You do not need a model for Saturday guests.
You need a contract that you can actually trust.

Step 5: Add one test that kills live paths

Do not test the model this weekend at all.
Test the fence around URLs and source flags.
The replay must reject a live source value.

# test_replay.py
import json
import tempfile
import unittest
from pathlib import Path

import handler
import replay


class ReplayFenceTests(unittest.TestCase):
    def test_handler_rejects_urls(self):
        with self.assertRaises(ValueError) as ctx:
            handler.lookup_order("https://example.invalid/ORD-100042")
        self.assertIn("live urls", str(ctx.exception))

    def test_replay_rejects_live_source(self):
        with tempfile.TemporaryDirectory() as raw:
            root = Path(raw)
            (root / "schema.json").write_text(Path("schema.json").read_text())
            live = {
                "tool": "lookup_order",
                "arguments": {"order_id": "ORD-100042"},
                "source": "live-model",
            }
            (root / "fixture.json").write_text(json.dumps(live))
            old = replay.ROOT
            replay.ROOT = root
            try:
                with self.assertRaises(SystemExit) as ctx:
                    replay.main()
                self.assertIn("non-disk", str(ctx.exception))
            finally:
                replay.ROOT = old


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

Run the tests before you invite any guest.

python3 test_replay.py

Green tests mean the demo cannot wander online.
That is the gate, not a screenshot or vibe.
Broken fences get fixed before any live capture.

Step 6: Prove it with the network off

Turn on airplane mode before the guest arrives.
Run the same replay command one more time.
Confirm the JSON still prints without a network.

python3 replay.py
python3 test_replay.py

If either command waits on DNS, you failed.
Find the import that talks to the network.
Delete that import. Do not patch around it.

This is the working demo you actually show.
Schema, fixture, handler, replay, and two commands.
No spinner. No API key. No surprise bill.

Step 7: Optional live capture after replay is green

Only now do you consider a live model call.
The live path writes a new capture file.
It must not overwrite fixture.json inside git.

A safe layout looks like the tree below.

replay_demo/
  schema.json
  fixture.json          # committed, disk only
  live_capture.json     # gitignored, optional
  handler.py
  replay.py
  test_replay.py

Put live_capture.json into .gitignore immediately.
Your Saturday demo still reads fixture.json only.
Monday experiments can read a capture file instead.

Keep the capture command optional and clearly later.

# proposal only: never run this during the demo
python3 capture.py --out live_capture.json

The demo script never imports capture.py at all.
That split is the point of this weekend build.
Guests should not even see the capture file.

When you want a hosted model for capture, keep it gated.
Disclosure: This article was prepared as part of MonkeyCode's product outreach.
MonkeyCode's free model access and free server option can host that capture step.
They do not replace the disk fixture for Saturday.
Use them after replay, tests, and airplane mode all pass.

If you try that path, reuse the same schema.
Refuse extra keys and refuse URL-shaped arguments.
Write the capture beside the fixture, never over it.

A decision table you can print

Use this table before you add any live call.

Question	Disk replay	Live model capture
Network required?	No	Yes
Schema can drift?	No, file is frozen	Yes, unless you validate
Demo-safe on Saturday?	Yes	No
Needs a model call?	No	Yes
Good for guests?	Yes	Only as a backup
Writes git-tracked files?	Fixture only	Capture file, gitignored

If two answers land in the live column, stop.
Return to the fixture and cut scope again.
The weekend is for a demo, not a platform.

Limitations, said plainly

This workflow will not train a serious agent.
It will not measure model quality or latency.
It will not replace tests against a real API.

The local ORDERS map is a stub dataset.
The order_id prefix check is a fence only.
You still need auth before any customer traffic.

Schema freeze also has a real product cost.
You will reject useful new fields on purpose.
That is correct for a two-hour demo, not production.

Who should not use this approach

Do not use this if you grade model accuracy.
Do not use this if the live contract is the deliverable.
Do not use this if reviewers must watch live tool calls.

Do not use this for anything that can spend money.
A replay handler should never charge a card.
A fixture should never contain secrets or personal data.

If your weekend goal is a pretty chat skin, skip this.
Build the UI another weekend after the contract holds.
Pretty UIs hide broken tool calls very well.

What you skipped, listed in the open

You skipped a planner that picks among many tools.
You skipped conversation memory and automatic retries.
You skipped tracing, metrics, and prompt versioning work.

You skipped a hosted queue and a worker pool.
You skipped fine-tuning and eval dashboard screens.
You skipped every SDK that demanded an API key first.

Those cuts are the build, not leftover chores.
A weekend demo that does one frozen call is honest.
A weekend demo that almost does ten things is not.

Close the laptop on a green replay

Turn the Wi-Fi off and run python3 replay.py.
If JSON prints, you have a real demo.
If it fails, you have a local bug to fix.

Invite the guest after that print already works.
Walk four files with one command and no spinner.
Ship the disk replay as the only guest path.

Leave live capture for a quieter Monday night.

Weekend Build Log: The Demo Writes One JSONL Line

Riley Zhang — Mon, 21 Sep 2026 12:48:46 +0000

Weekend Build Log: The Demo Writes One JSONL Line

You open the laptop at nine on Saturday. The idea is an AI classifier for bug reports. You want a chat box and a clever model.

By noon you have a page that looks finished. You cannot replay what the model actually said. Sunday you will not remember the original prompt.

That Saturday page is not a real demo. It is theater with a glowing text box.

This weekend you will cut that path. The demo is one transcript file on disk. One JSONL line proves the classifier ran.

The chat UI waits for another weekend. You will not paint a box around missing proof.

The weekend rule

You ship a classifier with a paper trail. The model stays optional until that trail works.

Live model calls come last, not first. You keep the weekend scope small and brutal.

You allow one verb, one fixture, one live ping. Everything else belongs in a written skip list.

What you will actually ship

You will ship four files and one command. The command appends exactly one transcript line. That line is the only demo you give.

prompt.txt holds the frozen instruction for every run.
fixture.json holds one known bug report only.
SKIPPED.md lists what you refused to build.
classify.py replays, pings once, and appends JSONL.

Step 1: Name the one verb

You do not build an open-ended AI assistant. You classify one bug report this weekend. The output is one label and one reason.

Keep the label set tiny on purpose. Allow only bug, docs, or unknown labels. The reason must stay one short sentence.

Write the contract on disk before any model call.

{
  "label": "bug",
  "reason": "Stack trace in the report body."
}

Reject extra JSON keys without any debate. The transcript must record that schema rejection. Do not clean up the payload by hand.

Step 2: Freeze the prompt on disk

Do not type prompts into a throwaway chat box. Keep the full instruction in prompt.txt only. Hash the file before every recorded run.

Classify the bug report.
Return JSON with keys label and reason.
label must be bug, docs, or unknown.
reason must be one sentence.
Do not invent extra keys.

shasum -a 256 prompt.txt

Store that hash inside each transcript line. Old lines become invalid if the hash changes. Do not mix prompt versions in one JSONL file.

Step 3: Write the skip list first

Write SKIPPED.md before you write any Python. This file is part of the demo itself. Print it at the end of every run.

# Skipped this weekend

- No chat UI
- No user accounts
- No streaming tokens
- No retry storms
- No vector store
- No dashboard
- No mobile layout

You will want a UI around hour two. You will not add it this weekend. The skip list is the real product constraint.

Step 4: Replay a fixture before any live call

Live answers can hide last hour's failure. A fixture keeps the failure in view. Store one bug report you already understand.

{
  "id": "rpt-001",
  "title": "Null pointer in checkout",
  "body": "TypeError: Cannot read properties of null (reading 'id')\n    at checkout.js:41"
}

The offline path uses boring keyword rules. It is not intelligence and does not pretend. You must pass this path before a live call.

# classify.py — local example, not a vendor SDK
from __future__ import annotations

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

ROOT = Path(__file__).parent
PROMPT = (ROOT / "prompt.txt").read_text(encoding="utf-8")
PROMPT_HASH = hashlib.sha256(PROMPT.encode()).hexdigest()
TRANSCRIPT = ROOT / "transcripts.jsonl"


def rule_classify(report: dict) -> dict:
    text = f"{report['title']}\n{report['body']}".lower()
    if "typeerror" in text or "null" in text:
        return {
            "label": "bug",
            "reason": "Stack trace in the report body.",
        }
    if "typo" in text or "readme" in text:
        return {
            "label": "docs",
            "reason": "The report points at documentation text.",
        }
    return {
        "label": "unknown",
        "reason": "No stack trace or docs cue found.",
    }


def valid_payload(row: dict) -> bool:
    if set(row.keys()) != {"label", "reason"}:
        return False
    if row["label"] not in {"bug", "docs", "unknown"}:
        return False
    if not isinstance(row["reason"], str):
        return False
    words = row["reason"].split()
    if not words or len(words) > 14:
        return False
    return True

This core uses no network and no hidden state. You can demo it on a train ride. That is the point of Saturday morning.

Step 5: Append one transcript line

A green printout is not the real demo. The demo is a JSONL append you can cat. Each transcript line must stand alone later.

def append_transcript(row: dict) -> None:
    with TRANSCRIPT.open("a", encoding="utf-8") as handle:
        handle.write(json.dumps(row, ensure_ascii=False) + "\n")


def build_row(report: dict, result: dict, source: str, ok: bool) -> dict:
    return {
        "ts": datetime.now(timezone.utc).isoformat(),
        "report_id": report["id"],
        "prompt_hash": PROMPT_HASH,
        "source": source,
        "ok": ok,
        "result": result,
    }

The source field is fixture or live only. ok is a schema check, not a vibe. Never mark a row ok because it looked clever.

Step 6: One live ping, then stop

Wait until the fixture row is ok. Then try the live path at most once. Do not loop the live call at all.

Do not retry the live call five times. Use one HTTP request and one timeout. Then stop and file the live result.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. Need a live ping after the fixture passes? MonkeyCode offers free model access and a free server option.

Point the script at a base URL you control. Treat the path below as an example only. Adapt the request body to your server.

def live_classify(report: dict, timeout_s: float = 20.0) -> dict:
    base = os.environ.get("MODEL_BASE_URL", "").rstrip("/")
    if not base:
        raise RuntimeError("MODEL_BASE_URL is not set")
    payload = json.dumps({
        "prompt": PROMPT,
        "report": report,
    }).encode("utf-8")
    req = urllib.request.Request(
        url=f"{base}/classify",
        data=payload,
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=timeout_s) as resp:
        body = json.loads(resp.read().decode("utf-8"))
    if not valid_payload(body):
        raise ValueError("schema rejected")
    return body

Keep that HTTP timeout tight on purpose. A hung call is a failed weekend demo. File the error instead of waiting around.

Wire the command path in main next. Keep fixture logic above the live branch. Exit non-zero on schema or network failure.

def main() -> int:
    fixture = json.loads((ROOT / "fixture.json").read_text(encoding="utf-8"))
    skipped = (ROOT / "SKIPPED.md").read_text(encoding="utf-8")

    offline = rule_classify(fixture)
    offline_ok = valid_payload(offline)
    append_transcript(build_row(fixture, offline, "fixture", offline_ok))
    print("fixture", "ok" if offline_ok else "FAIL", offline)
    if not offline_ok:
        print(skipped)
        return 1

    if "--live" not in sys.argv:
        print("live skipped; pass --live for one ping")
        print(skipped)
        return 0

    try:
        live = live_classify(fixture)
        append_transcript(build_row(fixture, live, "live", True))
        print("live ok", live)
    except Exception as err:
        append_transcript(
            build_row(fixture, {"error": str(err)}, "live", False)
        )
        print("live FAIL", err)
        print(skipped)
        return 1

    print(skipped)
    return 0


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

Run the fixture path first every time. You should see one new line in transcripts.jsonl. Open that line and read it aloud.

That spoken JSONL line is the demo. Do not skip reading the raw file.

python3 classify.py

Only then try live against your server. If live fails, you still have the fixture line. The weekend artifact is still not empty.

Do not delete JSONL because live looked ugly. Ugly live rows are still useful evidence.

export MODEL_BASE_URL="http://127.0.0.1:8080"
python3 classify.py --live

The demo gate

Do not screenshot a chat window as proof. Cat the last transcript line instead of that. Then print the skip list to stdout.

tail -n 1 transcripts.jsonl | python3 -m json.tool
cat SKIPPED.md

Ask one question before you call it done. Can a stranger replay this without your voice? If they need your memory, you failed the gate.

A tiny decision table

Use this table when you feel tempted to add features.

Gate	Pass	Fail next action
prompt hash matches `prompt.txt`	append the row	start a new JSONL file
fixture schema is valid	allow `--live`	stop, no live call
live timeout returns JSON	append `source=live`	append error, stop
extra keys in the payload	reject the row	keep the fixture row
skip list still true	ship the command	delete the extra feature

Read the fail column twice before coding. Most weekend bloat dies in that column. You do not need a fifth library.

What you skipped, and why

You skipped the UI because UIs hide the contract. You skipped retries because retries hide flaky servers. You skipped embeddings because they start a second product.

You skipped streaming because a stream is hard to file. A JSON object files cleanly on local disk. You skipped auth because nobody else has this repo yet.

The skip list is not a confession of shame. It is how you finish on Sunday. Keep it in the demo script output.

Limitations

This workflow will not train a model. It will not rank any model quality. It will not replace a real eval suite.

The rule classifier is a stub on purpose. It only exists to prove the pipe. Do not ship those keywords as intelligence.

The live POST uses a single timeout. It will fail on slow home networks. That failure is useful for this weekend.

Do not wrap it in retries yet. Transcript files also grow without a bound. This pattern is for a weekend, not a platform.

Prompt hashes do not prove the server used your prompt. They only prove what you sent from disk. Believe the local transcript, not a landing page.

Who should not use this

Do not use this if you need a public chatbot. Do not use this for production incidents. Do not use this as a vendor benchmark.

Do not use this if your reports are private. JSONL on disk is not a vault. Keep every fixture synthetic and very dull.

Do not use this if you already have an eval harness. You would be stepping backward on purpose. Use that harness instead of this script.

Sunday check

You should have one frozen prompt file. You should have one fixture row that passes. You may have one live row beside it.

You should still respect the skip list. If you added a UI, you broke the rule. Delete the UI and keep the JSONL.

The model did not do your engineering work. You did the scoping and the filing. The transcript is the proof you can show.

Weekend Build Log: Demo the Failure Path First

Riley Zhang — Sun, 20 Sep 2026 10:54:47 +0000

Saturday morning hits 10:14 with an empty repo.
You promised a live demo at two o'clock.
The coffee on your desk is already cold.

A model window waits on the second screen.
It offers a full product in one paste.
You should refuse that offer until the 400 exists.

Most weekend crashes are bad input, not missing features.
Friends will send empty JSON. They always do.
A green 200 with no failure path is a costume.

The scene you are actually in

You are building a tiny URL check API.
One POST /check route. One JSON body. One honest error.
That is the whole afternoon, not a starter for a platform.

Last demo you showed a clean happy path first.
Someone posted {"url": ""} and the process died.
The room remembered the crash, not your feature list.

Today you invert the order on purpose.
The 400 is the first feature. The 200 is leftover glue.
If time dies, the failure path still stands on stage.

Cut the scope in writing

Write the cut before you touch a prompt.
Paper beats a chat thread when the clock is loud.
If a task is missing here, it is not this weekend.

POST /check reads a JSON object with url.
Invalid bodies return HTTP 400 and one frozen error.
Valid bodies return HTTP 200 and a tiny OK payload.
You do not fetch the remote URL during the demo.

Fetching looks serious. Fetching also hangs at two o'clock.
Auth looks mature. Auth also explodes the diff.
You skip both. The error body is the product today.

Artifact: a hand-written error contract

Do not let the model invent the 400 shape.
You type the file. Tests import that file.
The handler imports the same file. Nobody "improves" it.

Proposed weekend loop. Run it locally before you demo.

mkdir -p contract tests scripts
touch contract/__init__.py tests/__init__.py

contract/errors.py:

# Hand-written. Do not regenerate this module.
ERROR_INVALID_PAYLOAD = {
    "error": "invalid_payload",
    "field": "url",
    "hint": "url must be an https URL",
}

OK_PAYLOAD = {
    "ok": True,
    "checked": "syntax",
}

That module is the demo script in disguise.
If a patch rewrites it, you revert the file and stop.
Green output against a new shape is not a win.

Numbered build, ninety minutes

1. Pin the contract with tests you typed

tests/test_contract.py:

import unittest
from contract.errors import ERROR_INVALID_PAYLOAD, OK_PAYLOAD


class ContractTests(unittest.TestCase):
    def test_error_keys_are_frozen(self):
        self.assertEqual(
            set(ERROR_INVALID_PAYLOAD),
            {"error", "field", "hint"},
        )

    def test_error_values_do_not_drift(self):
        self.assertEqual(
            ERROR_INVALID_PAYLOAD["error"],
            "invalid_payload",
        )
        self.assertEqual(ERROR_INVALID_PAYLOAD["field"], "url")

    def test_ok_payload_stays_tiny(self):
        self.assertEqual(
            OK_PAYLOAD,
            {"ok": True, "checked": "syntax"},
        )


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

Run the tests before any HTTP server exists:

export PYTHONPATH=.
python -m unittest tests.test_contract -v

You now own a gate the model did not author.
Fail this gate and you do not open the chat tab.
Passing it does not mean the service works yet.

2. Write the smallest handler that can fail

Stdlib only. No framework debate. No extra install.

app.py:

from http.server import BaseHTTPRequestHandler, HTTPServer
import json
from urllib.parse import urlparse

from contract.errors import ERROR_INVALID_PAYLOAD, OK_PAYLOAD

HOST = "127.0.0.1"
PORT = 8787


def check_url(payload):
    if not isinstance(payload, dict):
        return 400, ERROR_INVALID_PAYLOAD
    url = payload.get("url")
    if not isinstance(url, str):
        return 400, ERROR_INVALID_PAYLOAD
    parsed = urlparse(url)
    if parsed.scheme != "https" or not parsed.netloc:
        return 400, ERROR_INVALID_PAYLOAD
    return 200, OK_PAYLOAD


class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        if self.path != "/check":
            self._send(404, {"error": "not_found"})
            return
        length = int(self.headers.get("Content-Length", "0"))
        raw = self.rfile.read(length)
        try:
            payload = json.loads(raw.decode("utf-8") or "null")
        except json.JSONDecodeError:
            self._send(400, ERROR_INVALID_PAYLOAD)
            return
        status, body = check_url(payload)
        self._send(status, body)

    def _send(self, status, body):
        data = json.dumps(body).encode("utf-8")
        self.send_response(status)
        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((HOST, PORT), Handler).serve_forever()

Notice the 404 is not the frozen contract.
Only the 400 body is shared with tests.
Keep extra codes boring so the demo stays sharp.

3. Smoke the 400 first, then the 200

scripts/smoke.sh:

#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")/.."
export PYTHONPATH=.
BASE="${BASE_URL:-http://127.0.0.1:8787}"

bad=$(curl -sS -o /tmp/bad.json -w "%{http_code}" \
  -H "Content-Type: application/json" \
  -d '{"url":"ftp://example.com"}' \
  "$BASE/check")

test "$bad" = "400"
python - <<'PY'
import json
from contract.errors import ERROR_INVALID_PAYLOAD
body = json.load(open("/tmp/bad.json"))
assert body == ERROR_INVALID_PAYLOAD, body
print("400 contract held")
PY

good=$(curl -sS -o /tmp/good.json -w "%{http_code}" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/x"}' \
  "$BASE/check")

test "$good" = "200"
python - <<'PY'
import json
from contract.errors import OK_PAYLOAD
body = json.load(open("/tmp/good.json"))
assert body == OK_PAYLOAD, body
print("200 payload held")
PY

Start the server in one terminal:

export PYTHONPATH=.
python app.py

Run the smoke in another terminal:

chmod +x scripts/smoke.sh
./scripts/smoke.sh

If the 400 fails, you do not show the 200.
Demo order is the whole point of this cut.
A passing happy path after a broken error is theater.

4. Only then ask a model for glue

Now the model may write a Makefile or README.
It may not edit contract/errors.py.
It may not weaken scripts/smoke.sh to stay green.

Paste a short prompt with the freeze in it:

Keep contract/errors.py unchanged.
Keep scripts/smoke.sh failing on any 400 drift.
Add a Makefile with targets: test, serve, smoke.
Do not add fetching, auth, or HTML.

A Makefile worth accepting looks like this:

.PHONY: test serve smoke

export PYTHONPATH := .

test:
    python -m unittest tests.test_contract -v

serve:
    python app.py

smoke:
    ./scripts/smoke.sh

If you want a spare remote workbench for that loop, MonkeyCode can host it.
Disclosure: This article was prepared as part of MonkeyCode's product outreach.
MonkeyCode offers free model access and a free server option.
Treat both as a spare workbench, not as production hosting.
You still paste the same prompt. You still run the same smoke.

When the smoke turns red

Do not start by asking the model what went wrong.
Print the bodies. Diff them against the frozen file.
The repair order matters more than the stack trace.

Dump /tmp/bad.json and /tmp/good.json to the terminal.
Diff each file against contract/errors.py by eye.
If the handler drifted, revert the handler, not the test.
If the contract changed, revert the contract immediately.
Re-run make test before you re-run make smoke.

A common failure is pretty-printed JSON with extra keys.
Another is a rewritten hint that sounds friendlier.
Friendly is not the contract. Exact bytes are the contract.

python - <<'PY'
import json
from contract.errors import ERROR_INVALID_PAYLOAD
got = json.load(open("/tmp/bad.json"))
print("got ", sorted(got.items()))
print("want", sorted(ERROR_INVALID_PAYLOAD.items()))
PY

If those two lines disagree, the demo is not ready.
Do not narrate the mismatch as a style issue.
Call it a broken feature and fix the handler.

What you skip on purpose

Write the skip list in the README before the demo.
Future-you will try to "finish" the toy on Sunday night.
The list is a fence, not a backlog you must burn.

No live HTTP fetch of the submitted URL.
No database and no user accounts.
No retry policy, queue, or worker process.
No frontend, tokens, cookies, or rate limits.

Crawling a real site introduces jitter you cannot defend.
Accounts introduce password reset theater you cannot finish.
A form hides status codes from the people you must convince.

You skipped them because the 400 already proves existence.
Existence is the weekend bar. Polish is a weekday job.
Say that out loud when someone asks for one more thing.

Decision table for the remaining hour

Idea that pops up	Ship today?	Why
Pretty HTML form	No	Demo is curl. Forms hide status codes.
Real site crawl	No	Network jitter becomes your product.
Model-generated tests	No	The contract must outrank the model.
Extra error codes	No	One frozen 400 is easier to defend.
Makefile plus README	Yes	You need a one-command rerun.
Log redaction	Later	No secrets live in this payload.

If a row says No, you close the tab.
Do not renegotiate the table after 1:30 p.m.
The table is part of the demo, not private notes.

Limitations you should say out loud

This workflow does not measure latency under load.
It does not prove the URL is safe or reachable.
It does not replace review of any model patch.

A frozen 400 can still be a bad 400.
If your hint misleads users, you shipped a clean lie.
Read the JSON. Do not worship the green smoke.

Syntax checks are not security reviews.
https:// plus a host is not a safe fetch target.
Do not pretend otherwise when a friend asks.

Free model access will not choose scope for you.
A free server is not an SLA and may change.
Keep the contract and the smoke in your own git repo.

Who should not use this approach

Do not use this cut if you must ship real fetching today.
Do not use it for regulated data or paid user traffic.
Do not use it if your reviewer needs load numbers.

Security teams need more than a scheme check.
On-call teams need timeouts, metrics, and runbooks.
This article is a weekend gate, not a platform guide.

Teams with an existing public error catalog should ignore this.
Do not fork a second 400 shape beside a living standard.
Match the catalog you already owe, or do not start.

The two o'clock demo

You open a terminal. You run the 400 curl first.
The body matches the file you wrote that morning.
Then you run the 200. It is boring. Boring is shippable.

Someone asks for crawling. You point at the skip list.
The demo ends on time. The repo stays small.
Monday-you can add fetch behind a flag, if anyone still cares.

Weekend Build Log: Git Status Is the Demo Gate

Riley Zhang — Sat, 19 Sep 2026 09:12:42 +0000

You sit down Saturday with a half-built coding helper. The model prints a warm, finished-sounding summary. You almost paste that summary into README.md.

Then you run git status and the story collapses. Twelve paths changed under the working tree. One test file is simply gone.

The helper praised a change that never actually landed. This log rebuilds the demo around git status. You cut scope until one command remains.

The helper may write two paths, then it must stop. Prose cannot be your merge gate this weekend. The working tree has to stay the judge.

The Failure You Can Reproduce

Open a throwaway repo and ask for a small cleanup. Watch the model narrate a perfect, tidy patch. Do not trust that narration yet.

Run this command before you smile at the terminal:

git status --porcelain

If the list is long, the demo already failed. English success is not a merge gate. The working tree is the only honest log you have.

You do not need a larger prompt for this lesson. You need a smaller surface and a local checker. That local checker should fail loudly on leaks.

Cut Scope Until One Command Remains

Keep a single public command named make demo. That target packs input, runs one helper, then checks the tree. Anything else waits for a later weekend.

The helper may write only these two paths:

out/verdict.txt
out/note.md

verdict.txt holds one token: PASS, FAIL, or SKIP. note.md holds a short human note. No third path is allowed to appear.

You skip a chat window on purpose this weekend. A window hides dirty files behind friendly prose. A Makefile target cannot hide a dirty tree.

The Exit Code Table

Do not parse the model's tone or hedges. Parse exit codes, file bytes, and paths. Pin this table in the repository root.

Code	Meaning	What you do next
0	Allowed files exist; no extra dirty paths	Keep the demo
2	Helper refused the job	Read `out/note.md`
3	Input exceeded the byte budget	Cut the fixture
4	Git status shows a forbidden path	Fail the weekend demo
other	Wrapper bug	Fix the script, not the prompt

Print that table in README.md after the first green run. Future you will need it after coffee. The table is the contract, not the chat transcript.

Build It as Four Files

Create an isolated folder for the experiment. Do not practice inside a real work repo. Cleanup should cost one rm -rf command.

mkdir -p weekend-gate/{out,src,fixtures}
cd weekend-gate
git init
touch out/.gitkeep src/.gitkeep
printf 'sample input for a one-line verdict\n' > fixtures/sample.txt
git add .
git commit -m "start weekend gate"

You now have a clean tree to measure against. The helper must keep that tree almost clean. Only the two output paths may show up later.

1. Freeze the path allowlist

Create src/allowlist.txt with exactly two lines. Use no globs, comments, or blank lines. Two literal paths fit in a review.

out/verdict.txt
out/note.md

You can review that file without a meeting. A glob would hide a surprise write. Literal paths keep the weekend honest.

2. Pack a bounded fixture

Add src/pack_input.py. This script reads one fixture file. It refuses to pass a blob over 32768 bytes.

#!/usr/bin/env python3
"""Proposed local packer. Not a hosted service."""
from pathlib import Path
import sys

BUDGET = 32768


def main() -> int:
    if len(sys.argv) != 2:
        print("usage: pack_input.py FIXTURE", file=sys.stderr)
        return 2
    path = Path(sys.argv[1])
    data = path.read_bytes()
    if len(data) > BUDGET:
        print(f"input {len(data)} exceeds {BUDGET}", file=sys.stderr)
        return 3
    sys.stdout.buffer.write(data)
    return 0


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

Label this script as a proposed local packer. You should run it on your machine. It does not call a network by itself.

3. Wrap the helper once

Add src/run_helper.sh. This wrapper is a local proposal, not a vendor SDK. It reads stdin and writes the two allowed files.

#!/usr/bin/env bash
set -euo pipefail

# Proposed one-shot wrapper. No retry loop lives here.
mkdir -p out
input="$(cat)"

if [[ "${FORCE_EXTRA_WRITE:-}" == "1" ]]; then
  printf 'oops\n' > out/extra.log
fi

if [[ "${FORCE_REFUSE:-}" == "1" ]]; then
  printf 'SKIP\n' > out/verdict.txt
  printf 'fixture looked unsafe\n' > out/note.md
  exit 2
fi

printf 'PASS\n' > out/verdict.txt
printf 'stdin bytes: %s\n' "${#input}" > out/note.md

The FORCE_EXTRA_WRITE switch exists for the failure drill. Do not ship that switch in production code. You want a reproducible bad path this weekend.

Swap the stub later for one real completion call. Keep the rest of the wrapper tiny. A second call would hide the first failure.

4. Check the working tree

Add src/check_tree.py. This checker file is the actual weekend product. The script stays boring on purpose here.

#!/usr/bin/env python3
"""Fail the demo when git status leaves the allowlist."""
from pathlib import Path
import subprocess
import sys

ALLOWED = {
    line.strip()
    for line in Path("src/allowlist.txt").read_text().splitlines()
    if line.strip()
}
VERDICT_VALUES = {"PASS", "FAIL", "SKIP"}
NOTE_BUDGET = 4000


def porcelain() -> list[str]:
    raw = subprocess.check_output(
        ["git", "status", "--porcelain", "-uall"],
        text=True,
    )
    paths = []
    for line in raw.splitlines():
        if not line:
            continue
        path = line[3:]
        if " -> " in path:
            path = path.split(" -> ", 1)[1]
        paths.append(path)
    return paths


def main() -> int:
    verdict = Path("out/verdict.txt")
    note = Path("out/note.md")
    if not verdict.is_file() or not note.is_file():
        print("missing allowed output file", file=sys.stderr)
        return 4
    token = verdict.read_text().strip()
    if token not in VERDICT_VALUES:
        print(f"bad verdict {token!r}", file=sys.stderr)
        return 4
    if note.stat().st_size > NOTE_BUDGET:
        print("note.md exceeds byte budget", file=sys.stderr)
        return 4
    dirty = porcelain()
    extra = [p for p in dirty if p not in ALLOWED]
    if extra:
        print("forbidden paths:", *extra, sep="\n", file=sys.stderr)
        return 4
    print(f"gate ok verdict={token} dirty={dirty}")
    return 0


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

The checker never reads the model prose. It reads files and git status --porcelain. That split is the whole point of the weekend.

Wire `make demo`

Add a Makefile with three targets. Humans run make demo and stop there. The other targets exist for the failure drill.

.PHONY: demo refuse dirty

demo:
    python3 src/pack_input.py fixtures/sample.txt | bash src/run_helper.sh
    python3 src/check_tree.py

refuse:
    python3 src/pack_input.py fixtures/sample.txt | FORCE_REFUSE=1 bash src/run_helper.sh
    python3 src/check_tree.py

dirty:
    python3 src/pack_input.py fixtures/sample.txt | FORCE_EXTRA_WRITE=1 bash src/run_helper.sh
    python3 src/check_tree.py

make demo is the definition of done. A screenshot in a chat window does not count. If this target fails, you are not finished.

Run the Happy Path

Make the scripts executable, then run the happy path. You should see gate ok and exit code 0.

chmod +x src/pack_input.py src/run_helper.sh src/check_tree.py
make demo
echo $?
git status --porcelain

Expected porcelain is only the two allowed files. Anything else means the wrapper leaked a write. Stop and inspect before you add features.

If out/.gitkeep also appears as dirty, commit it first. The allowlist should name every path you accept. Hidden extra files are still extra files.

Run the Failure Path

Now plant a forbidden file on purpose. This is the drill that trains your eye. A green verdict must not outrank a dirty tree.

make dirty
echo $?

You want exit code 4 from this drill. out/extra.log sits outside the allowlist. The demo must fail, even if verdict.txt says PASS.

Reset the tree and try the refuse path too:

git clean -fd
make refuse
echo $?

A planned SKIP can still pass the tree gate. A surprise extra path must never pass it. That difference is the whole product this weekend.

What You Skipped On Purpose

You skipped a web UI for the helper. You skipped token streaming in the terminal. You skipped a public HTTP endpoint.

You skipped multi-file refactors across the app. You skipped an "explain this patch" mode. You skipped retry storms after a vague failure.

You also skipped hosting this as a shared service. A weekend demo should not become an auth problem. Keep it local until the gate is boring.

Those skips are not laziness in disguise. They are how the demo stays honest. Extra surface area gives the helper more places to lie.

Where a Free Model Call Fits

You still need somewhere to try a real one-shot completion later. Billing should not become the weekend's main plot. A free model path keeps the experiment about the gate.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. It offers free model access and a free server option. Use that pair for the one-command loop above.

Swap the stub in run_helper.sh for one completion call. Keep the allowlist checker unchanged after the swap. If the model writes a third path, the gate still fails.

Do not treat free access as a production SLA. This article does not claim quotas, model names, or uptime numbers. The working tree remains the judge either way.

Limitations

This gate is not a sandbox for untrusted code. A helper that runs destructive commands can still win. You are checking leftovers, not intercepting every syscall.

git status misses ignored files by design. Do not add broad gitignore rules for out/. If you ignore outputs, the checker goes blind.

The byte budgets are local constants in scripts. They are not security boundaries around the model. They only stop accidental huge fixtures and huge notes.

The stub helper does not prove any vendor. It proves your Makefile and your allowlist. Wire a real model only after make dirty fails.

Renames can still fool a sloppy porcelain parser. The sample checker splits -> on purpose. Read git status docs before you copy this into a larger repo.

Who Should Skip This Approach

Skip this if you must ship a multi-file refactor today. Two output paths will not hold that work. Cut a different weekend, or drop the model.

Skip this during a production incident on call. You need humans and known runbooks then. A fresh git gate is the wrong tool.

Skip this if you cannot isolate a throwaway repo. Running the helper against payroll code is unsafe. Copy a fixture out instead of pointing at secrets.

Skip this if your team needs audit logs, SSO, or signed artifacts. This Makefile will not satisfy that bar. It is a side-project receipt, not a platform.

Keep the Demo Small

Ship the gate when make demo is green. Ship it when make dirty is red. That pair is enough for Sunday night.

Do not add a dashboard after the gate works. Do not add a second helper "just in case." The dirty tree was the original bug.

If you later connect a free server, keep this same contract. One command. Two paths. Git status as the demo gate.

Weekend Build Log: The Patch Cannot Touch Tests

Riley Zhang — Fri, 18 Sep 2026 07:08:01 +0000

Liquid syntax error: Unknown tag 'endraw'

Weekend Build Log: Cap the Diff Before You Call the Model

Riley Zhang — Thu, 17 Sep 2026 05:15:57 +0000

You sit down on Saturday at 9:12.
The task looks tiny on paper.
Parse one custom header from a log line.
You paste the file into a chat window.
The model rewrites three unrelated modules.
It adds a packaging dependency you never requested.
Your original test still fails on the header.
You close the tab and start over.

The model is not the weekend problem.
An unbounded patch is the weekend problem.
Side projects die when the diff explodes.
You need a budget before any model call.

The real constraint

You do not need a better prompt tonight.
You need a gate that can say no.
A forty-line cap keeps the demo honest.
A required test name keeps the patch on task.

This is not a product launch.
This is a Saturday scope cut.
You will ship a checker, not a platform.
The commands below are a proposed weekend workflow.
Run them locally before you trust the gate.

What you keep

Keep one failing test under tests/.
Keep one function in src/header.py.
Keep a hard cap of forty changed lines.
Keep a forbid list for docs and lockfiles.
That list is the whole weekend product.

You are not building an agent.
You are not building a review bot.
You are building a cheap reject path.
Cheap reject paths save Saturday afternoons.

What you skip

Skip chat history and follow-up turns.
Skip whole-repository context dumps.
Skip "make this production ready."
Skip new third-party dependencies.
Skip README rewrites and extra files.
Skip a web UI and an agent loop.
The demo is one Makefile target.
Stdout from the gate is enough proof.

If a step needs a second prompt, cut it.
If a step needs a new library, cut it.
If a step needs a dashboard, cut it.
Weekend scope is a deletion exercise.

Frozen contract

Write these three checks before any call.

The patch must mention test_parse_x_request_id.
Added plus removed lines must stay under 40.
Paths outside src/ and tests/ are rejected.

If any check fails, you discard the patch.
You do not negotiate with the output.
The budget is the product this weekend.
Oral rules will not survive lunch.

Why forty lines

Forty lines is not a scientific constant.
It is a Saturday constraint you can count.
A header parser should fit in that budget.
If it cannot fit, the task is still too big.

Count added lines and removed lines together.
A rewrite can hide inside a deletion.
A rename can hide inside a tiny add.
The gate must see both directions.

Do not raise the cap mid-session.
Raising the cap is how the rewrite sneaks back.
Sunday can change the number.
Saturday cannot.

Step 1: Write the failing test first

Create the smallest test you can stand.
Name the test like a contract, not a novel.

# tests/test_header.py
from src.header import parse_x_request_id


def test_parse_x_request_id():
    line = "GET / 200 x-request-id=abc-123"
    assert parse_x_request_id(line) == "abc-123"

Run it once before you touch a model.

python -m pytest tests/test_header.py -q

You want a red result on purpose.
Green tests invite the model to wander.
A named failure pins the weekend goal.
If pytest cannot collect the test, stop.
Fix the harness before any generated patch.

Step 2: Stub the tiny source file

Keep the source honest and empty.
Do not pre-write a clever parser.

# src/header.py
def parse_x_request_id(line: str) -> str:
    raise NotImplementedError("weekend: implement only this function")

The model may only fill this hole.
Anything else should fail the budget.
A stub also makes revert trivial.
git checkout -- src/header.py is your undo.

Step 3: Freeze the budget file

Put numbers in a file, not a chat.
Chat limits evaporate after one scroll.

# budget.txt
max_lines=40
required_test=test_parse_x_request_id
allow_prefix=src/,tests/

You will read this file in the gate.
You will not "remember" the limits.
Weekend rules die when they stay oral.
Commit budget.txt with the failing test.
The contract should move with the code.

Step 4: Build a local patch gate

This script is the original artifact.
It does not call a model by itself.
It only accepts or rejects a unified diff.

# tools/diff_budget.py
from pathlib import Path
import sys


def load_budget(path: Path) -> dict:
    data = {}
    for raw in path.read_text().splitlines():
        line = raw.strip()
        if not line or line.startswith("#"):
            continue
        key, value = line.split("=", 1)
        data[key.strip()] = value.strip()
    data["max_lines"] = int(data["max_lines"])
    data["allow_prefix"] = tuple(
        p.strip() for p in data["allow_prefix"].split(",") if p.strip()
    )
    return data


def parse_diff(diff: str) -> tuple[int, list[str]]:
    total = 0
    files: list[str] = []
    for line in diff.splitlines():
        if line.startswith("+++ b/"):
            files.append(line[6:])
        elif line.startswith("+") and not line.startswith("+++"):
            total += 1
        elif line.startswith("-") and not line.startswith("---"):
            total += 1
    return total, files


def main() -> int:
    budget = load_budget(Path("budget.txt"))
    diff = sys.stdin.read()
    total, files = parse_diff(diff)
    errors = []
    if budget["required_test"] not in diff:
        errors.append(f"missing {budget['required_test']}")
    if total > budget["max_lines"]:
        errors.append(
            f"diff has {total} lines, cap is {budget['max_lines']}"
        )
    for name in files:
        if name == "/dev/null":
            continue
        if not name.startswith(budget["allow_prefix"]):
            errors.append(f"forbidden path: {name}")
    if errors:
        print("REJECT")
        print("\n".join(errors))
        return 1
    print("ACCEPT")
    print(f"lines={total} files={files}")
    return 0


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

Save a sample patch and run the gate.

python tools/diff_budget.py < sample.patch
echo $?

Exit code 1 means you throw the patch away.
Exit code 0 means you may apply it.
No third status exists this weekend.
Warnings without an exit code are theater.

Step 5: One model call, or a stub

Do not open a chat window.
Write a request file with one job.

# request.txt
Implement parse_x_request_id in src/header.py.
Keep tests/test_header.py as the only test.
Return a unified diff only.
Do not touch README or dependencies.
Stay under forty changed lines.

If you have no host yet, use a stub.
The stub proves the Makefile path.

# tools/stub_patch.sh
cat << 'EOF'
--- a/src/header.py
+++ b/src/header.py
@@ -1,3 +1,8 @@
 def parse_x_request_id(line: str) -> str:
-    raise NotImplementedError("weekend: implement only this function")
+    marker = "x-request-id="
+    if marker not in line:
+        raise ValueError("missing header")
+    return line.split(marker, 1)[1].split()[0]
EOF

Point the same target at a real host later.
Keep request.txt unchanged when you switch.
The host is not the weekend lesson.
The reject path is the weekend lesson.

When you need a hosted model, MonkeyCode can sit behind that same target. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Free model access and a free server option are enough for this workflow. Treat them as an optional backend for request.txt. Do not add a vendor dashboard to Saturday's demo.

Leave the URL in an environment variable.
Do not hard-code a host into the gate.
The gate should not know who wrote the diff.

# proposed later swap, not required today
# curl -sS "$MODEL_URL" --data-binary @request.txt > /tmp/weekend.patch

That line is labeled on purpose.
Do not invent a vendor payload for it.
If the variable is empty, keep the stub.

Step 6: Wire a single Makefile target

One target. One happy path. One stop.

.PHONY: weekend
weekend:
    python -m pytest tests/test_header.py -q || true
    ./tools/stub_patch.sh > /tmp/weekend.patch
    python tools/diff_budget.py < /tmp/weekend.patch
    git apply --check /tmp/weekend.patch

Run one command. Then stop.

chmod +x tools/stub_patch.sh
make weekend

If the gate rejects, you do not apply.
If git apply --check fails, you do not apply.
You do not "just this once" raise the cap.
The Makefile is the demo script.
People can replay it without a tour.

Failure analysis: a bad patch

Here is a patch the gate should kill.
Study the reject reasons before you relax rules.

--- a/src/header.py
+++ b/src/header.py
@@ -1,3 +1,20 @@
+import json
+import os
 def parse_x_request_id(line: str) -> str:
-    raise NotImplementedError("weekend: implement only this function")
+    return os.environ.get("REQUEST_ID", json.dumps(line))
--- a/README.md
+++ b/README.md
@@ -1,1 +1,30 @@
-# header toy
+# Production-ready header platform

Run it through the same command.

python tools/diff_budget.py < bad.patch

You should see REJECT.
You should see a missing test name.
You should see a line-count failure.
You should see forbidden path: README.md.
Three failures beat one vague "looks off."

Notice the source change also drifted.
It stopped parsing the log line.
It started reading an environment variable.
The required test name would have caught that drift.
Even a comment-only mention is a weak signal.
You still read the patch before apply.
The gate is a filter, not a reviewer.

Decision table

Signal	Action	Why
Missing test name	Reject	The patch left the weekend goal
More than 40 lines	Reject	Unbounded diffs hide extra work
File outside `src/` and `tests/`	Reject	Docs and lockfiles are out of scope
`git apply --check` fails	Reject	The patch is not even applyable
Pytest still red after apply	Revert	The budget is not a quality prize
Pytest green and gate green	Stop	The demo is done

Print this table near your desk.
The table beats another prompt tweak.
If you cannot name the action, you are improvising.
Improvisation is how Saturday becomes a rewrite.

Apply, verify, and keep an undo

Only after ACCEPT, try a checked apply.

git apply --check /tmp/weekend.patch && git apply /tmp/weekend.patch
python -m pytest tests/test_header.py -q

If you are still exploring, revert at once.

git checkout -- src/header.py

The last line matters on a Saturday.
You should undo the demo in one command.
A weekend demo that cannot revert is a trap.
Keep generated patches out of main until green.
A file in /tmp is a feature, not a mess.

Limitations

This gate does not prove the code is safe.
It does not catch logic bugs or injections.
It does not replace a human code review.
Forty lines can still contain harm.
The required test name can be faked in comments.
You should read the patch before git apply.

The stub is not a benchmark.
No latency numbers belong in this log.
No model ranking belongs in this log.
Switching hosts must not change the budget.
If a host cannot return a unified diff, skip it.
Do not weaken the gate to flatter a backend.

Line counting is also crude.
Binary files will confuse the parser.
Rename-heavy diffs can look huge.
That is acceptable for this toy.
A header parser should not rename the tree.

Who should not use this

Do not use this for a production incident.
Do not use this for auth or crypto changes.
Do not use this for a multi-package refactor.
Do not use this if review bots already exist.
Do not use this to generate a full application.
Juniors still need a human to read the diff.
The cap is a scope tool, not a skill substitute.

If your real task needs twenty files, stop.
Split the task until one file is enough.
If you cannot split it, this workflow is wrong.
Wrong tools waste a weekend faster than no tools.

What done means Saturday

Done means the failing test is now green.
Done means the gate printed ACCEPT.
Done means you did not touch the README.
Done means you stopped after one pass.
If you still want a UI, wait until next week.

The interesting part is the reject path.
A model that cannot fail your budget is not helping.
Cap the diff before you call anything.
Then ship the tiny parser and go outside.

Weekend Build Log: Freeze Four JSON Fields First

Riley Zhang — Wed, 16 Sep 2026 03:35:31 +0000

You open the laptop at 9:14 on Saturday. A messy folder of receipt photos sits nearby. You want one command that prints four JSON fields.

The chat pane already wants a dashboard. It also wants OAuth, retries, and a queue. That is how quiet weekends disappear.

This walkthrough stays small on purpose. You freeze a JSON contract before any model runs. Then you ship one command and one validator.

Treat the steps below as a proposed weekend plan. Nothing here is a production benchmark. Your git history is the only scoreboard.

Why helpers inflate a Saturday

You have maybe six focused hours. You do not have a product team. Scope is the only lever you still control.

A coding helper fills empty hours with new surfaces. Extra surfaces demand extra tests. Extra tests steal the Sunday demo.

So you lock the output shape first. The schema is the product this weekend. Everything else waits in a reject file.

Recent AI coding talk mixes speed with engineering. Speed without a freeze is just churn. A frozen contract is the missing gate.

What you will ship

You will ship three files and one command. That is the whole demo surface.

A frozen contract file in git.
One fixture receipt stored as JSON.
A validator that exits non-zero on drift.

You will not ship a UI. You will not ship an agent loop. You will not stream tokens into business logic.

Step 1: Write the contract by hand

Create contract.json before you open any helper. Keep four fields only. Name them like an API, not like chat.

{
  "version": "1",
  "fields": {
    "merchant": {"type": "string", "max": 80},
    "total_cents": {"type": "integer", "min": 0},
    "currency": {"type": "string", "enum": ["USD", "EUR", "CNY"]},
    "purchased_on": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"}
  }
}

Print that file. Read each field name out loud. If a field feels fuzzy, delete it now.

Do not add tax, tips, or line_items today. Those fields invite parsers you will not finish. Fuzzy money fields also hide rounding bugs.

Commit the contract before any parser exists. The commit message can be one line. freeze: four-field receipt contract v1 is enough.

Step 2: Pin one fixture

Create fixtures/receipt_001.json next. This is the only legal demo input. A second fixture is a later product.

{
  "raw_text": "ORBIT CAFE\n2026-09-14\nLatte 4.50\nTotal $4.50",
  "expected": {
    "merchant": "ORBIT CAFE",
    "total_cents": 450,
    "currency": "USD",
    "purchased_on": "2026-09-14"
  }
}

One fixture proves the contract path. It does not prove OCR. It does not prove every cafe in town.

If the helper asks for a corpus, refuse. You are proving a shape, not a dataset. Extra photos belong in the reject file.

Redact any real merchant names before you paste. Fake the cafe. Fake the total. Keep private receipts off the prompt.

Step 3: Write a boring validator

Create validate.py and keep it short. No framework. No JSON Schema plugin this weekend.

#!/usr/bin/env python3
import json
import sys
from pathlib import Path

CONTRACT = json.loads(Path("contract.json").read_text())
FIELDS = CONTRACT["fields"]

def fail(msg: str) -> None:
    print(f"CONTRACT FAIL: {msg}", file=sys.stderr)
    raise SystemExit(1)

def check(obj: dict) -> None:
    if set(obj) != set(FIELDS):
        fail(f"keys {sorted(obj)} != {sorted(FIELDS)}")
    merchant = obj["merchant"]
    if not isinstance(merchant, str) or not merchant or len(merchant) > 80:
        fail("merchant")
    total = obj["total_cents"]
    if not isinstance(total, int) or isinstance(total, bool) or total < 0:
        fail("total_cents")
    if obj["currency"] not in FIELDS["currency"]["enum"]:
        fail("currency")
    date = obj["purchased_on"]
    if not isinstance(date, str) or len(date) != 10:
        fail("purchased_on")
    if date[4] != "-" or date[7] != "-":
        fail("purchased_on")
    y, m, d = date.split("-")
    if not (y.isdigit() and m.isdigit() and d.isdigit()):
        fail("purchased_on")

def main() -> None:
    payload = json.loads(sys.stdin.read())
    check(payload)
    print("CONTRACT OK")

if __name__ == "__main__":
    main()

Run it against the fixture expected block first. You want a green path now. The model has not written anything yet.

python3 -c 'import json,pathlib; p=json.loads(pathlib.Path("fixtures/receipt_001.json").read_text()); print(json.dumps(p["expected"]))' | python3 validate.py

You should see CONTRACT OK on stdout. If you do not, stop immediately. Fix the contract by hand, not the helper.

Add a second command that must fail. Feed it a renamed key on purpose. The gate is real only when it rejects drift.

echo '{"merchant":"X","amount":1,"currency":"USD","purchased_on":"2026-09-14"}' | python3 validate.py; echo exit:$?

That run should print CONTRACT FAIL and a non-zero status. Save both commands in README.md. Those two lines are the demo script.

Step 4: Add a tiny parser stub

Create parse.py after the validator is green. Hard-code the fixture path. Do not walk a photo directory.

#!/usr/bin/env python3
import json
import re
from pathlib import Path

fx = json.loads(Path("fixtures/receipt_001.json").read_text())
text = fx["raw_text"]
merchant = text.splitlines()[0].strip()
date = re.search(r"(\d{4}-\d{2}-\d{2})", text).group(1)
cents = int(round(float(re.search(r"Total \$([0-9.]+)", text).group(1)) * 100))
out = {
    "merchant": merchant,
    "total_cents": cents,
    "currency": "USD",
    "purchased_on": date,
}
print(json.dumps(out))

This stub is allowed to look ugly. Ugly and finished beats elegant and open. You can rewrite it next month.

Pipe the stub into the validator.

python3 parse.py | python3 validate.py

Green output is the weekend demo. Record that pipe in README.md. Do not open a browser to prove it.

If the regex fails, edit parse.py yourself. Do not start a second helper session yet. Hands-on edits keep the schema honest.

Step 5: Reject work in a file

Create REJECT.md beside the contract. Write refusals as concrete items. Vague principles will not stop a chatty model.

# Reject this weekend
- web dashboard
- auth and sessions
- PDF OCR pipeline
- second fixture
- retry loop around the model
- streaming UI
- database
- extra money fields

Read that list before every helper prompt. If the reply adds a rejected surface, discard the reply. Do not negotiate with the extra files.

The reject file is a build tool. It is not a confession. You are buying a Sunday demo with Saturday restraint.

Step 6: One helper pass, then stop

If you use a coding helper, paste contract.json first. Paste REJECT.md second. Ask only for a four-field parse.py.

Do not ask it to make this production ready. That phrase deletes weekends. Ask for stdout JSON that matches the contract.

After the first patch, stop the helper. Run the validator again. If it fails, you edit the stub by hand.

This is a gate, not a leaderboard. It does not measure model quality. It measures whether your weekend still has a shape.

Decision table for Saturday changes

Use this table when the helper gets generous. Print it. Keep it above the keyboard.

Incoming request	Saturday action
Add a fifth JSON field	Refuse; append it to `REJECT.md`
Rename `total_cents`	Refuse; keep the frozen key
Stand up a React app	Refuse
Add a second fixture	Refuse until the pipe stays green
Validator false positive	Fix `validate.py` by hand
Parser misses the date	Edit `parse.py`; no new loop
"Make it robust"	Refuse
Public URL with open prompt	Refuse

The table is the original artifact. Code can drift. The table states the policy in one glance.

Where a free helper can sit

You may want a model for the first parse.py draft. You may later want a throwaway host for one JSON endpoint. Both come after the contract exists.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode provides free model access and a free server option you can use for that bounded weekend pass. Keep contract.json in your repo either way. The helper does not own the shape.

A later endpoint should accept one JSON body. It should return four fields or an error. Reuse validate.py as the server gate if you host anything.

Do not point a public URL at an unbounded prompt. A free server is not a license for a dashboard. The reject file still wins.

Failures you should expect

The parser will choke on missing dollar signs. That is acceptable this weekend. Document the miss in REJECT.md and move on.

The helper will rename total_cents to amount. The validator must reject that rename. Do not stretch the contract to match the model.

Currency enums will feel rude. Keep them rude. Open string fields become soup by Sunday night.

Dates without hyphens will fail the gate. Good. Your demo is a contract, not a guesser. Guessers do not survive the next fixture.

Boolean true must not pass as total_cents. Python treats bool as int without the extra check. That is why the validator excludes bool explicitly.

Limitations

This approach ignores real OCR. It ignores multi-line merchant names. It ignores tax-inclusive totals and tips.

It also ignores load, auth, and retention. Those are product problems. They are not Saturday problems.

The validator is not a schema platform. It is a weekend gate. Replace it later if the contract survives a month.

Free model output can drift across sessions. You do not pin a vendor by hoping. You pin a file in git and a failing command.

A free server is not a production posture. Treat it as a demo host only. Put secrets nowhere near that host.

This article does not name models, quotas, or hardware. Those claims go stale fast. Your contract file does not.

Who should not use this

Do not use this if Monday needs every receipt parsed. You need a real pipeline then. A stub will lie to finance.

Do not use this if compliance needs an audit trail. A weekend script is not that trail. You will fake safety and regret it.

Do not use this if your team already owns a registry. Follow that registry instead. Do not fork a toy schema beside it.

Do not paste private receipts into any helper. Redact the fixture. Fake the cafe. Keep personal amounts local.

Skip this if you cannot freeze keys. If every chat can rename fields, you do not have a product. You have a conversation.

Close on a green pipe

Your done state is one pipe that prints CONTRACT OK. That is enough for Sunday. Anything past that is next weekend.

If the helper still wants a dashboard, reread REJECT.md. Then close the chat. Ship the command and walk away.

Cut the Scope First: A Weekend Side Project With One Endpoint and One Smoke Test

Riley Zhang — Tue, 15 Sep 2026 03:10:25 +0000

Friday, 9:40 pm. Three side-project ideas. One Sunday deadline.

By Saturday noon I had killed two of them. That decision is the whole article.

Most weekend projects die from scope, not from code. That is the boring truth.

Why "just add an agent loop" ruins the weekend

A loop needs state, retries, and a stop condition. That is a week of work.

You have two days. So I keep one rule: one job, one endpoint, one smoke test.

Everything below is a build log for a helper that reads stdin and prints stdout. It is small on purpose.

1. Write the job in one sentence

If you cannot say the job in one sentence, you do not have a project yet.

Bad: "An AI assistant that helps me organize my notes."

Good: "Read a raw meeting transcript on stdin, print five action items on stdout."

The second version has a falsifier. You can fail it in ten seconds. Ambition does not ship; a falsifier does.

Write that sentence in a notes file. Do not open an editor yet.

2. Score every feature, then cut

List every feature you want. Then score each one honestly.

Anything above 30 minutes of debug risk gets cut on pass one. You can add it next weekend.

Candidate	Build (min)	Debug risk	Cut?	Reason
stdin/stdout CLI	20	low	no	this is the demo
one retry with backoff	25	medium	no	networks fail
plain text log to disk	10	low	no	you will need it
web UI	120	high	yes	stdout is enough
agent loop	180	high	yes	no stop condition
accounts and auth	90	high	yes	one user: you

The table is the real artifact here. Rebuild it for your own idea. Print it and tape it next to the monitor.

Then say the painful part out loud: "This weekend, the demo is a terminal command." Nobody is watching anyway.

3. Prove the endpoint before you build anything

Do not write application code until a single HTTP call returns real output.

This is the step people skip. They build a UI first, then discover the request shape is wrong.

Save this as smoke.sh. It is a template, not a finished tool.

#!/usr/bin/env bash
# smoke.sh - template. Fill variables from the docs you were given.
set -euo pipefail

: "${BASE_URL:?export BASE_URL from your dashboard}"
: "${API_KEY:?export API_KEY from your dashboard}"
: "${MODEL:?export MODEL from your documentation}"

# Never guess this path. Copy it from the docs you were given.
PATH_SUFFIX="${PATH_SUFFIX:-/v1/chat/completions}"
BUDGET_SECONDS="${BUDGET_SECONDS:-20}"

payload() {
  cat <<JSON
{"model":"${MODEL}","messages":[{"role":"user","content":"Reply with one word: ok"}],"max_tokens":8}
JSON
}

run_once() {
  curl --silent --show-error \
    --max-time "${BUDGET_SECONDS}" \
    --write-out '\n%{http_code} %{time_total}\n' \
    --header "Authorization: Bearer ${API_KEY}" \
    --header 'Content-Type: application/json' \
    --data "$(payload)" \
    "${BASE_URL}${PATH_SUFFIX}"
}

out="$(run_once)"
code="$(printf '%s' "$out" | tail -n1 | awk '{print $1}')"
secs="$(printf '%s' "$out" | tail -n1 | awk '{print $2}')"
body="$(printf '%s' "$out" | sed '$d' | sed '$d')"

printf 'http=%s time=%ss\n' "$code" "$secs"
[ "$code" = "200" ] || { echo "FAIL: non-200. Body:"; echo "$body"; exit 1; }

# Adjust this field name to your provider's response shape.
printf '%s' "$body" | grep -q '"content"' || { echo "FAIL: no content field"; exit 1; }
echo "PASS in ${secs}s"

Run it with three exported variables. Read the failure text, not just the status code.

export BASE_URL='https://...'   # from your dashboard
export API_KEY='...'            # from your dashboard
export MODEL='...'              # from the docs you were given
chmod +x smoke.sh && ./smoke.sh

The script asserts three things: a 200, a non-empty content field, and a time budget. Each assertion maps to one class of weekend bug.

4. Measure the spread, not one lucky call

One fast call proves nothing. Shared capacity is shared.

for i in 1 2 3 4 5; do ./smoke.sh | tail -n1; done

Record five numbers. Drop the first one, that is your cold start. The rest is your real budget.

Now set your timeout from the spread, not from your hopes. I have never regretted measuring this before writing UI code.

5. Ship the smallest surface that survives a reboot

My helper is one script and one long-running process. That is the entire deployment.

If your free server is a Linux box you can SSH into, a systemd unit is the smallest durable thing.

[Unit]
Description=weekend helper
After=network-online.target

[Service]
EnvironmentFile=/home/me/.helper.env
ExecStart=/home/me/helper/run.sh
Restart=on-failure
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Enable it, then watch the logs:

sudo systemctl enable --now weekend-helper
journalctl -u weekend-helper -f

If your server is not a Linux box, use whatever supervisor it exposes. The rule is the same. One process, restart on failure, logs to stdout.

6. Where free access actually changed my plan

Two decisions simply disappeared from this weekend's list.

First, billing. Free model access deleted the "add a payment method, add usage caps, add a quota screen" branch. That branch is not hard, but it costs an afternoon.

Second, the deploy target. A free server option deleted the provider comparison. I stopped reading pricing pages and started writing the smoke test.

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

I am deliberately not publishing latency or throughput numbers for it. I do not have a reproducible benchmark, and shared capacity varies by hour and region. Run the loop in step 4 and trust your own measurements instead.

7. What I skipped on purpose

Web UI. The terminal demo is enough for one user.
A database. Append JSON lines to a file instead.
Multi-step retries. One retry with backoff covers most transient failures.
Model switching. Two models means two behaviors to debug.
Test suite beyond smoke.sh. One assertion beats zero, and five would be theater.

Each skip has a trigger. Add the feature when a real user asks for it, not before.

8. Limits you should assume

Free capacity is shared. Expect variance you did not cause.
There is no SLA here. Accept a broken demo, or build a fallback path.
Do not send client, health, or personal data to a service you have not reviewed yourself.
Free access can change. Keep an exit plan: isolate the call in one function so you can swap it.
Model output is unverified text. Validate it before it touches anything real.

9. Who should not use this workflow

Skip this approach if you need contractual uptime, pinned model versions for audits, or data residency guarantees. Skip it if your "weekend" is really a product launch with a date.

This is a build log for a disposable helper. Treat it that way.

Takeaways

One job. One endpoint. One smoke test. One process.

Cut the table until Sunday feels boring. A boring Sunday ships.

If you try it, run smoke.sh before you write the app. Tell me which assertion caught your first bug.

Weekend Build Log: The Timeout Is the Product

Riley Zhang — Sun, 13 Sep 2026 19:35:21 +0000

You sit down Saturday with one failing test file. The stack trace is ugly and long. You want a tiny helper that groups those failures.

Ninety minutes later you are still retrying a model. The helper never became a demo. The weekend dissolved into another chat.

This log cuts that loop. You freeze three files. You wrap the run in a timeout. You write a receipt. Then you stop.

The Saturday trap

You do not lack ideas on Saturday morning. You lack a stop rule. Chat tools invite one more retry.

Each retry feels cheap in the moment. The clock still moves. The demo stays imaginary.

Treat the timeout as the product. If the job misses the window, it failed. You ship the failure, not another prompt tweak.

Cut the job to one verb

Pick one verb before you open an editor. Group. Summarize. Rank. Stop there.

Write the verb on a sticky note. If a second verb appears, it waits. Sunday is not a second product.

Here is a tight job statement you can reuse.

Job: group pytest failures by file path.
Input: tests/last-run.txt
Output: groups.json
Limit: 90 seconds wall clock.

That statement is the scope cut. Everything else is skip work.

Freeze three files first

Do not start inside a chat window. Create three files on disk. They outlive the session.

job.md holds the verb, input, and output.
prompt.txt holds the only instruction you will send.
budget.yaml holds time, retries, and output path.

Keep those files boring. Boring files survive Saturday better than clever agents.

# budget.yaml
job: group-failures
wall_clock_seconds: 90
max_attempts: 1
input: tests/last-run.txt
output: groups.json
receipt: receipts/saturday.json

max_attempts: 1 is the point. A second attempt is a new weekend.

Label this layout as a proposal until you run it. Do not fake a green build.

Put a kill switch on the process

Unix already ships the feature. Use timeout. Do not write a scheduler.

mkdir -p receipts tests

cat > tests/last-run.txt << 'EOF'
FAILED tests/test_api.py::test_timeout
FAILED tests/test_api.py::test_retry
FAILED tests/test_auth.py::test_expired_token
EOF

timeout 90s python3 group_failures.py \
  --input tests/last-run.txt \
  --output groups.json \
  --receipt receipts/saturday.json
echo "exit:$?"

Exit 124 means the clock won. That is a valid demo. Write it down.

Do not catch that exit and retry. Retry is how Saturday dies.

Write a receipt after every run

A chat log is not evidence. A receipt file is. You want four fields only.

# group_failures.py
# Proposed weekend helper. Run it locally before you trust it.
from __future__ import annotations

import argparse
import json
import time
from collections import defaultdict
from pathlib import Path


def group_lines(raw: str) -> dict[str, list[str]]:
    groups: dict[str, list[str]] = defaultdict(list)
    for line in raw.splitlines():
        line = line.strip()
        if not line.startswith("FAILED "):
            continue
        body = line[len("FAILED "):]
        path = body.split("::", 1)[0]
        groups[path].append(body)
    return dict(groups)


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--input", required=True)
    parser.add_argument("--output", required=True)
    parser.add_argument("--receipt", required=True)
    args = parser.parse_args()

    started = time.time()
    source = Path(args.input)
    grouped = group_lines(source.read_text(encoding="utf-8"))
    Path(args.output).write_text(
        json.dumps(grouped, indent=2) + "\n",
        encoding="utf-8",
    )

    receipt = {
        "job": "group-failures",
        "seconds": round(time.time() - started, 3),
        "input": args.input,
        "output": args.output,
        "groups": len(grouped),
        "timed_out": False,
    }
    receipt_path = Path(args.receipt)
    receipt_path.parent.mkdir(parents=True, exist_ok=True)
    receipt_path.write_text(json.dumps(receipt, indent=2) + "\n")
    print(receipt_path.read_text(), end="")
    return 0


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

The script does no model call. That is the scope cut talking. You can add a model later. You may not need one.

Make the demo one command

Your demo is not a UI. Your demo is a command a friend can paste.

python3 group_failures.py \
  --input tests/last-run.txt \
  --output groups.json \
  --receipt receipts/saturday.json

cat groups.json
cat receipts/saturday.json

Expected groups.json looks like this.

{
  "tests/test_api.py": [
    "tests/test_api.py::test_timeout",
    "tests/test_api.py::test_retry"
  ],
  "tests/test_auth.py": [
    "tests/test_auth.py::test_expired_token"
  ]
}

If those two files exist, the weekend shipped. If they do not, you failed closed. Either result is honest.

Decision table for the next hour

Use this table when the helper feels small. Small is the goal.

Urge	Do this	Skip this
Add retries	Keep `max_attempts: 1`	Sleep loops
Add a web page	Print `groups.json`	Flask, auth, CSS
Add a model	Freeze `prompt.txt` first	Agent memory
Add flags	Keep three flags	Config frameworks
Miss the timeout	Commit the receipt	"One more run"

Read the skip column twice. That column is the build.

When a free model is actually useful

Sometimes the grouping rule is messy. Regex will lie. A short model pass can draft group_lines.

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

MonkeyCode is relevant here only as a place with free model access and a free server option. Use those two things to draft the helper. Then run the same timeout on the result. Do not turn the server into a chat room.

Keep the model outside the kill switch at first. Generate group_failures.py once. Paste it into git. Run timeout 90s against the file you saved. If the draft needs a second generation, that is Sunday work.

Do not invent extra surfaces around that draft. No dashboard. No plugin. No background worker. The receipt still decides whether the hour counted.

If you try MonkeyCode for this gate, keep the same three files. The product should not replace budget.yaml.

What you skip on purpose

Write the skip list in job.md. A skip list is part of the demo.

No retry loop around the model.
No extra libraries for HTTP or agents.
No UI beyond stdout and two JSON files.
No streaming tokens into a log you will never read.
No "memory" file that grows every run.

You already published helpers that refuse extra flags. This log is different. The clock is the contract. The receipt is the proof.

A five-step Saturday checklist

Follow the order. Do not reorder under stress.

Write job.md with one verb only.
Freeze prompt.txt and budget.yaml.
Implement the smallest local function.
Run it under timeout 90s.
Commit groups.json plus the receipt.

If step 4 fails, commit the failure receipt. Then close the laptop. That is still a shipped weekend.

Limitations

This gate is blunt. Blunt tools miss nuance. A ninety-second wall clock cannot see queue delay.

The sample script only groups FAILED lines. Real pytest output is richer. You will need more parsing later.

A free model draft can still be wrong. The timeout will not catch logic bugs. It only catches hangs.

A free server option does not remove your review duty. You still read the diff. You still own the exit code.

Do not treat this article as a benchmark. No latency numbers were claimed. No quota numbers were claimed. No model names were claimed.

Who should not use this

Do not use this if you are paging production at 2am. On-call work needs a real runbook.

Do not use this if your job needs multi-step tools. A single timeout will starve that design.

Do not use this if you cannot freeze the prompt. If stakeholders change the verb hourly, the receipt lies.

Do not use this if you need a hosted UI today. You will overbuild before lunch.

Close the weekend

You started with a noisy test file. You end with two JSON files and a clock. That is enough product for Saturday.

Keep the kill switch in the Makefile. Keep the skip list in git. Let Monday argue with the receipt, not with your memory.

One Pass Then Stop: A Weekend Helper With No Agent Loop

Riley Zhang — Sat, 12 Sep 2026 17:34:03 +0000

You sit down at ten on Saturday morning.
The idea is a tiny notes helper.
You still paste a vague prompt into an agent.

Noon hits and the file tree looks serious.
A planner folder sits beside three new tools.
Sunday has no command a friend can run.

This is a weekend gate, not a memoir.
You freeze one acceptance command first.
Then you allow exactly one generation pass.

Why loops eat Saturday

A retry loop looks like progress on screen.
The model rereads files and calls more tools.
Your scope grows with every extra call.

A side project needs a Monday rerun.
It does not need a private agent runtime.
If the demo needs a loop, cut the demo.

You are not arguing about research agents here.
You are arguing about a two-hour helper.
Keep those jobs in different repos.

Freeze the command before code

Open ACCEPT.txt before you open an editor.
Write one command and one expected line.
Stop when that sentence looks boring.

Proposed file, labeled as a template:

# ACCEPT.txt
# Command:
python3 notes.py --add "buy milk"
# Must print:
added: buy milk
# Must exit:
0

That file is the weekend product.
Code exists only to keep it true.
If a patch breaks it, you revert the patch.

Do not add a second command "for later."
Later is how Saturday becomes a platform.
One line is enough to prove the helper.

The one-pass rule

You get one model pass against frozen paths.
No planner. No tool loop. No second chat.
A failed check means you cut scope.

Treat this as a proposed workflow.
It is not a measured win-rate study.
You are buying a demo, not an agent OS.

Write the allowed paths on paper first.
If a file is missing from that list, refuse it.
Refusal is the actual engineering this weekend.

Four files, then stop

Keep the tree tiny on purpose.

ACCEPT.txt holds the frozen command.
notes.py must pass that command.
check_demo.sh reruns the command.
check_no_loop.py bans retry markers.

Skip Make until both checks stay green.
A Makefile is another surface to explain.
Sunday does not owe anyone extra surfaces.

Step 1: Fail the demo on purpose

Write check_demo.sh while notes.py is missing.
You want red output in the first five minutes.
Green output without a red start is theater.

#!/usr/bin/env bash
set -euo pipefail

cmd=$(grep '^python3' ACCEPT.txt | head -n 1)
expect=$(awk '/^# Must print:/{getline; print; exit}' ACCEPT.txt)
set +e
got=$(eval "$cmd" 2>&1)
code=$?
set -e

if [[ "$code" -ne 0 ]]; then
  echo "FAIL: exit $code"
  echo "$got"
  exit 1
fi

if [[ "$got" != "$expect" ]]; then
  echo "FAIL: got [$got] want [$expect]"
  exit 1
fi

echo "PASS: $cmd"

Run it once and read the failure.
Do not "fix" the checker to stay quiet.
The checker is the only honest reviewer.

Step 2: Ban loop markers

Weekend helpers grow while True under stress.
They grow sleep, retry, and max_steps next.
Those tokens are not features this weekend.

Proposed detector, unexecuted until you run it:

#!/usr/bin/env python3
from pathlib import Path
import re
import sys

path = Path("notes.py")
if not path.exists():
    print("FAIL: notes.py missing")
    sys.exit(1)

text = path.read_text(encoding="utf-8")
needles = [
    r"while\s+True\b",
    r"for\s+\w+\s+in\s+range\(\s*\d{2,}",
    r"time\.sleep\(",
    r"\bretry\b",
    r"max_steps",
    r"tool_calls",
    r"max_iterations",
]
hits = [p for p in needles if re.search(p, text, re.I)]
if hits:
    print("LOOP RISK: " + ", ".join(hits))
    sys.exit(1)
print("PASS: no loop markers in notes.py")

This is a tripwire, not a proof of safety.
Clever loops will walk around it.
It still catches the usual Saturday overbuild.

Step 3: One prompt, then hands off

Write the prompt like a contract.
Name the only file allowed to change.
Say ACCEPT.txt is read-only law.

Proposed prompt draft:

Change notes.py only.
Do not add files, tools, or planners.
Do not retry, sleep, or loop.
Make ./check_demo.sh pass.
If a feature misses ACCEPT.txt, drop it.

Send it once. Read the diff slowly.
Run both checks before you type praise.
Praise is how a second session starts.

If a check fails, you edit by hand.
You do not open another agent turn.
Hand cuts are cheaper than new loops.

Step 4: Put the pass somewhere you can close

Your laptop should not sit open for generation.
A throwaway helper is not worth a paid key.
You want one pass, then a closed lid.

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

MonkeyCode fits this gate in two narrow ways.
Free model access covers that single pass.
A free server option runs the pass off your laptop.

This article will not name models or quotas.
It will not invent hardware or time limits.
Those claims rot fast without primary sources.

Keep ACCEPT.txt at the repo root on that box.
The server runs the pass and the two checks.
It does not invite an agent framework.

Step 5: Ship a boring `notes.py`

The file should look almost rude.
Rude and small still reruns on Monday.

Proposed example, not a live benchmark:

#!/usr/bin/env python3
import argparse
from pathlib import Path

STORE = Path("notes.txt")

def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--add", required=True)
    args = parser.parse_args()
    line = args.add.strip()
    if not line:
        print("empty note")
        return 1
    with STORE.open("a", encoding="utf-8") as handle:
        handle.write(line + "\n")
    print(f"added: {line}")
    return 0

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

It appends a line and prints a receipt.
No embeddings. No chat memory. No HTTP.
A friend can rerun it without a tour.

The cut list you publish

Put cuts in the commit message body.
Saturday-you will forget them by Sunday.
Monday-you needs the refusals in git.

Proposed cuts for this helper:

No planner package and no step JSON.
No MCP server and no tool registry.
No retry loop and no backoff sleep.
No browser UI and no extra port.
No second model pass to "review" code.

Each cut defends ACCEPT.txt.
You are not underbuilding for sport.
A looping agent is a different weekend.

If a cut hurts, write why in the message.
"Dropped retries because ACCEPT has one path."
That sentence saves you on Sunday night.

Decision table

Fill this table before you touch a prompt.

Situation	Loop this weekend?	Move
One happy-path CLI	No	One pass, then stop
Flaky third-party API	Not now	Cut the API
Unknown research steps	Later	Wait for a weekday
Friend must rerun Monday	No	Freeze `ACCEPT.txt`
You cannot name the exit code	No	The idea is not ready

If a cell is blank, do not start generation.
Blank cells turn into tool folders.
Tool folders turn into a skipped Sunday.

Failure analysis

Here are three failures this gate should catch.

Failure A: the model wraps stdin in while True.
check_no_loop.py exits 1 on that marker.
You delete the loop and keep --add.

Failure B: the model prints JSON instead of the receipt.
check_demo.sh compares the exact line.
You revert the JSON "improvement."

Failure C: the model creates agent.py beside notes.py.
Your prompt forbade new files.
You drop agent.py without reading it twice.

None of these failures are exotic.
They are the default Saturday path.
The gate only works if you honor red.

Run the full sequence in this order:

chmod +x check_demo.sh check_no_loop.py
./check_demo.sh || true
python3 check_no_loop.py || true
# one generation pass happens here
./check_demo.sh
python3 check_no_loop.py

The first || true is deliberate.
You are recording red, then green.
Do not hide the red with extra flags.

Who should not use this

Skip this gate when the work is a real loop.
On-call incident response needs retries.
Long research needs backtracking.

Do not use this approach when:

You cannot freeze one acceptance command.
You must call flaky vendor APIs tonight.
You are shipping production orchestration.
You need multi-hour tool use with memory.

Those jobs deserve traces and evals.
A notes receipt printer does not.
Mixing them burns the only free day.

Monday morning

Run both checks before you open chat.
Green means the weekend counted.
Red means the demo was a slideshow.

Do not add a reviewer agent to recover.
That is the loop in a nicer coat.
Fix the one command or delete the tree.

You froze a command and banned a loop.
You shipped a receipt printer for notes.
If those two checks stay green, stop there.