DEV Community: Riley Zhang

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.

Weekend Build Log: Stdout Is the Demo, Not a UI

Riley Zhang — Fri, 11 Sep 2026 15:19:52 +0000

You sit down on Saturday with one goal.
You want a tiny status reporter for later.

The coding agent already has a full plan.
It wants a dashboard, a worker, and Redis.

You did not ask for that extra surface.
You asked for a green or red result.
This log shows the cut you should make.

The Saturday scene

The repo is a quiet side project.
It holds one script and a data folder.

You type a loose prompt anyway.
"Make a status page I can demo."
The agent treats "page" as a product.

That wording is the first real leak.
"Page" invites HTML, CSS, and routes.
"Demo" invites extra moving parts fast.

You stop the run before files land.
You rewrite the ask as a hard contract.
Stdout will be the entire weekend demo.

What you actually need

You need one command that exits cleanly.
You need a JSON blob on stdout only.

You need a non-zero exit on failure.
You do not need a browser tab today.

You do not need a bound network port.
You do not need a login form either.

Write the contract before any new code.
Keep it small enough to read aloud.
If you cannot recite it, cut more scope.

Freeze a stdout contract first

Save this file as STATUS_CONTRACT.md.
Commit it before the agent touches code.

# Status contract (weekend freeze)

Demo command:
  make status

Stdout: one JSON object, no mixed logs.
Exit 0 if the check passes.
Exit 1 if the check fails.

Required keys:
  ok: boolean
  checked_at: ISO-8601 string
  source: string
  detail: string

Forbidden this weekend:
  HTTP servers
  HTML templates
  extra dependencies
  background workers
  new config files

This file is the only weekend gate.
The agent may edit status.py after that.
It may also edit the Makefile target.

It may not add a second surface.
Point at this file when plans grow.
Do not argue from memory or vibes.

Numbered build, not a brainstorm

Follow these steps in this exact order.
Do not skip ahead to a status UI.

Freeze the contract in git first.
Add a failing test for stdout JSON.
Write the smallest checker script.
Wire make status and nothing else.
Run the happy path and the miss.
Dump rejected ideas into OUT_OF_SCOPE.md.

The order matters more than raw speed.
A failing test keeps the demo honest.
An out-of-scope list keeps prompts honest.

Step 1: commit the freeze

git add STATUS_CONTRACT.md
git commit -m "freeze weekend status contract"

Commit before the agent writes any code.
A frozen file is cheaper than a debate.
You can quote it when scope creeps back.

Step 2: add a failing stdout test

This test is a labeled proposal only.
Run it on your machine before you trust it.
Do not treat the snippet as measured proof.

# test_status.py
import json
import subprocess
import unittest


class StatusStdoutTests(unittest.TestCase):
    def test_make_status_prints_one_object(self):
        proc = subprocess.run(
            ["make", "status"],
            check=False,
            capture_output=True,
            text=True,
        )
        self.assertNotIn("Traceback", proc.stderr)
        payload = json.loads(proc.stdout)
        self.assertIn(proc.returncode, (0, 1))
        self.assertIsInstance(payload["ok"], bool)
        self.assertEqual(
            set(payload),
            {"ok", "checked_at", "source", "detail"},
        )


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

The test talks to Make, not a server.
That choice blocks a hidden local port.
If stdout is dirty, json.loads fails.

Step 3: write the smallest script

Keep the checker in one Python file.
Use the standard library and nothing else.
Print JSON, then exit with a status.

# status.py
from __future__ import annotations

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

DATA = Path("data")


def main() -> int:
    exists = DATA.exists() and DATA.is_dir()
    payload = {
        "ok": exists,
        "checked_at": datetime.now(timezone.utc).isoformat(),
        "source": "data/",
        "detail": "data dir present" if exists else "data dir missing",
    }
    json.dump(payload, sys.stdout)
    sys.stdout.write("\n")
    return 0 if exists else 1


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

The check is deliberately boring on purpose.
A missing folder is enough for a demo.
You can swap the predicate next weekend.

Step 4: one Makefile target

.PHONY: status test

status:
    python3 status.py

test:
    python3 test_status.py

Do not add a serve target this weekend.
Do not add a docker target this weekend.
Do not add a dev target that boots UI.

Step 5: run it like a demo

mkdir -p data
make status
echo $?
make test

You should see one JSON object only.
You should see exit code zero after that.
You should see the unit test pass cleanly.

Now break the check on purpose.

rmdir data
make status
echo $?

You should see "ok": false in stdout.
You should see exit code one from Make.
That red path is part of the demo.

When stdout gets dirty

The agent will try to be extra helpful.
It will print Running status check....
That single line breaks the JSON parse.

Treat dirty stdout as a failed demo.
Do not parse "the last line only".
The contract says one object, nothing else.

Debug with this exact command sequence.

Run make status | cat -A and inspect marks.
Keep traces on stderr, never on stdout.
Run json.loads against the full stdout.
Fail the test if extra text exists anywhere.

make status 2>/tmp/status.err | python3 -c "import sys,json; json.load(sys.stdin); print('clean')"

If that pipeline errors, stop adding features.
Fix the script before you touch scope again.
Silence on stdout is part of the interface.

Step 6: name what you refused

Do not hide the extra ideas in chat.
Write them down so they cannot sneak back.

# OUT_OF_SCOPE.md

- React status board
- websocket live feed
- Redis and a worker process
- FastAPI health route
- Docker Compose stack
- auth tokens and API keys

Read that list before the next agent prompt.
If an item is absent from the contract, refuse it.
You can reopen the list on a later weekend.

A Saturday decision table

Use this table before you accept any plan.
If the plan needs a new column, stop cold.

Prompt smell	Likely extra surface	Cut back to
"status page"	HTML, CSS, routes	`make status`
"live updates"	websockets, a queue	one JSON snapshot
"so we can share it"	auth, deploy, DNS	stdout in the terminal
"just a small API"	framework, CORS	a function and exit codes
"add logging later"	config files, sinks	empty stderr on success

The table is the real weekend tool.
Code is only the proof of the cut.
Plans that ignore the table waste Saturday.

Where a coding agent still helps

A weekend agent is useful for glue code.
It is poor at protecting product scope.
You have to protect that scope yourself.

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

If you want model access without a paid key, MonkeyCode's free model access can run this same constrained loop. If you do not want the laptop as the only host, the free server option can hold the tiny repo. Neither one replaces STATUS_CONTRACT.md. Paste that file before the first prompt if you try it there.

Keep the product off the critical path.
The demo must work with plain Python three.
Remove the agent and these steps still hold.

Limitations

This demo proves a checker, not a product.
It does not watch production traffic at all.
It does not measure model quality either.

JSON on stdout is easy to break later.
One debug print fails the whole contract.
That brittleness is useful for one weekend.

The data-folder check is only a stand-in.
Replace it with a real predicate later on.
Do not expand the command surface with it.

Free model access and a free server can change.
Do not build a launch plan on those options.
Do not treat them as a capacity promise.

Who should not use this cut

Do not use this if you need a public URL today.
Do not use this if auditors require HTTP health.
Do not use this if your audience cannot run Make.

Teams with an existing health endpoint should keep it.
This log is for a side project with no users.
It is a scope knife, not a platform design.

Close the laptop

You asked for a demo you can actually show.
You shipped one command and a frozen contract.
You skipped the board the agent wanted first.

That is a successful Saturday side project.
The JSON blob is enough to screenshot later.
Next weekend can earn a second surface, maybe.

Weekend Build Log: One Curl Demo, Zero Extra Surfaces

Riley Zhang — Thu, 10 Sep 2026 04:13:37 +0000

You sit down Saturday with a two-hour window.
You want one POST that stores a note.
The agent replies with a six-surface plan.
The plan adds login, dashboards, WebSockets, retries, and CI.
None of that proves the note path works.
Your weekend just became a product kickoff.

This log is about cutting that surface.
You will freeze the demo as one curl.
You will skip every path the curl never hits.
You will still leave with a working spike.

The scene that keeps repeating

You paste a short goal into the agent.
Store a note, then return the saved JSON.
The plan comes back sounding strangely complete.
It wants /login before any write exists.
It wants a React shell for a JSON body.
It wants exponential backoff for a laptop POST.

You did not ask for a launch checklist.
You asked for a demo you can replay.
Those are different jobs on a short Saturday.
Agents fill empty product space with extra surfaces.
Your job is to remove that empty space early.

Freeze the demo, not the whole repo

Do not freeze file count in this round.
Do not freeze library count in this round.
Freeze the public demo instead of the tree.
One recorded curl is the entire weekend contract.
If a change does not serve that curl, cut it.

Paste this block before any generated plan:

WEEKEND DEMO CONTRACT
Allowed command: scripts/demo.sh
Allowed method: POST
Allowed path: /notes
Allowed proof: HTTP 200 plus JSON keys id, body
Forbidden: extra routes, UI, auth, retries, CI
If the plan needs forbidden work, rewrite the plan.

That block is blunt on purpose.
Agents treat silence as permission to expand.
You remove the silence before the first file lands.

Step 1: Write the curl before the server

You record the demo first, on purpose.
No server exists yet, and that stays fine.
The script is the spec, not a later souvenir.

Create scripts/demo.sh with this spike-only command:

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

base="${DEMO_URL:-http://127.0.0.1:8787}"

curl -sS -f -X POST "$base/notes" \
  -H "content-type: application/json" \
  -d '{"body":"ship the spike"}'
echo

Keep the flags boring and easy to read.
You need a JSON body and failure on HTTP errors.
You do not need a pretty printer this morning.

Mark the script executable before the agent starts:

chmod +x scripts/demo.sh

If the agent adds extra curl tools, reject them.
The demo has one verb, and you protect it.
A second verb is next weekend, not this one.

Step 2: Pin a scope file the agent must honor

Create weekend-scope.yml before any handler code.
This is not production configuration for later deploys.
This is a Saturday fence around the demo surface.

# Proposed weekend spike. Not a product spec.
name: notes-spike
demo:
  command: scripts/demo.sh
  method: POST
  path: /notes
  expect:
    status: 200
    json_keys: ["id", "body"]
skip:
  - authentication
  - html_ui
  - extra_http_verbs
  - background_retries
  - websockets
  - ci_workflows
  - admin_pages
rules:
  - one process
  - one listen port
  - in-memory store only

Read the skip list out loud once.
If an item is not required for curl, it stays skipped.
You can restore a skipped item on a later weekend.
Do not restore it because the plan sounded mature.

Step 3: Allow one tiny process, nothing else

Do not ask the agent for a framework tour.
Ask for one process that satisfies the yaml.
The example below is a labeled weekend spike.
It is not a service you should bill against.

server.py using only the Python standard library:

#!/usr/bin/env python3
"""Weekend spike: one POST /notes path. Nothing else."""

from http.server import BaseHTTPRequestHandler, HTTPServer
import json
import uuid

NOTES = {}


class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        if self.path != "/notes":
            self.send_error(404)
            return
        length = int(self.headers.get("Content-Length", "0"))
        raw = self.rfile.read(length)
        payload = json.loads(raw.decode("utf-8") or "{}")
        note = {
            "id": str(uuid.uuid4()),
            "body": payload.get("body", ""),
        }
        NOTES[note["id"]] = note
        body = json.dumps(note).encode("utf-8")
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

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


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

Notice the absences before you praise the code.
There is no GET list and no DELETE path.
There is no HTML page and no token header.
There is no retry wrapper around a local POST.
That absence is the whole point of the weekend.

Start the process in one terminal only:

python3 server.py

Run the recorded demo in a second terminal:

./scripts/demo.sh

You should see JSON with id and body.
If you see a login form, the gate already failed.
Delete the extra surface before you keep prompting.

Step 4: Add a checker the agent cannot charm

Humans get talked into extra routes after lunch.
A checker does not care about a confident plan.
Put the proof in a script, then refuse debate.

scripts/check-demo.sh:

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

base="${DEMO_URL:-http://127.0.0.1:8787}"
out="$(mktemp)"
trap 'rm -f "$out"' EXIT

code="$(curl -sS -o "$out" -w "%{http_code}" -X POST "$base/notes" \
  -H "content-type: application/json" \
  -d '{"body":"ship the spike"}')"

test "$code" = "200"
python3 - "$out" <<'PY'
import json, sys
path = sys.argv[1]
data = json.load(open(path))
assert "id" in data and "body" in data, data
assert data["body"] == "ship the spike", data
print("demo contract ok")
PY

Run the checker after every agent edit:

chmod +x scripts/check-demo.sh
./scripts/check-demo.sh

If the checker still passes, you can stop.
Passing is the definition of done today.
A green checker beats a prettier architecture sketch.

Step 5: Reject extra surfaces with a table

Use this table when the agent improves the spike.
Ask it to fill the middle column before writing code.
If the answer is No, the work is out of scope.

Agent proposal	Serves `scripts/demo.sh`?	Saturday action
POST `/notes`	Yes	Keep
GET `/notes`	No	Skip
Login and JWT	No	Skip
React settings page	No	Skip
Retry with backoff	No	Skip
Dockerfile and compose	No	Skip
GitHub Actions workflow	No	Skip
WebSocket status feed	No	Skip
Second listen port	No	Skip

Print the table inside the prompt itself.
Do not negotiate rows after the agent starts coding.
The table is cheaper than a two-hour rollback.

What you skip on purpose

You skip auth because the spike is local only.
You skip UI because curl is the interface today.
You skip retries because failure should stay loud.
You skip CI because nobody else runs this yet.
You skip extra verbs because listing is not the demo.

That list would look reckless on a work Monday.
It is responsible on a two-hour Saturday spike.
A finished happy path beats a half-built platform.
Ship the replayable curl, then close the laptop.

Where a free model loop fits

You can run this gate in any coding agent.
The yaml and checker stay tool-agnostic on purpose.
A free model path helps when plans expand too fast.
A free server path helps when your laptop is busy.

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

MonkeyCode matters here only as a host for that loop.
It offers free model access for the planning passes.
It also offers a free server option for the checker.
Use those if you want the fence off your laptop.
Do not treat the sandbox as a reason to grow scope.
The recorded curl still wins over the extra machine.

If you run the same Saturday fence there, glue the skip list to the prompt.

Limitations

This workflow is for spikes, not launches.
It hides real product work on purpose.
Do not use it for payment or billing flows.
Do not use it for private user data.
Do not use it when compliance needs audit logs.
Do not use it as your only test suite.

The in-memory map dies on process restart.
That is acceptable for a demo transcript.
It is not acceptable for anything you bill.
Restart the process and the notes are gone.

The checker proves one happy path only.
It does not prove security, load, or auth.
It will not catch a missing rate limit.
You skipped those items. Remember that Monday.

Who should not use this

Skip this gate if you ship to users today.
Skip it if authentication is the actual problem.
Skip it if the demo must be a visible UI.
Skip it if your team needs public staging now.
Skip it if you cannot explain the skipped list.

This is a weekend knife, not a process religion.
Do not drop it onto a regulated codebase.
Do not confuse a green curl with production readiness.

Close the laptop with a replay

Before you stop, run three things in order.
Start the process, run the demo, run the checker.
If all three work, the weekend actually shipped.
If the agent added a dashboard, delete that surface.
Your recorded curl is the product for today.

You can add GET lists next Saturday if needed.
You can add auth when a second user exists.
You cannot add those hours back tonight.
Leave the skip list in the repo as a warning.

Sunday Demo Gate: Keep a Skip Log or Overbuild

Riley Zhang — Wed, 09 Sep 2026 15:32:01 +0000

You sit down Saturday with a long feature list.
Your coding agent treats every idea as in scope.
You need a Sunday demo, not a half-built platform.

This is a scope cut, not a launch plan.
You freeze one user path before any code lands.
You keep a skip log so extra work stays extra.

The Saturday overbuild scene

You paste a vague goal into the agent chat.
It replies with auth, dashboards, queues, and extra APIs.
You asked for a working demo. It planned a company.

That habit is the current agent default, not a bug.
Models can draft almost any feature in minutes.
Minutes are cheap. Sunday night is not cheap.

You do not win by generating more files.
You win by naming what the demo is not.
Write that refusal down before the first patch.

Artifact: the weekend one-path card

Create WEEKEND.md in the repository root tonight.
Keep the file short, brutal, and mechanically checkable.
If a task is not on the card, you skip it.

# Weekend one-path card

## Demo path (only this)
Visitor opens /receipt.html
Visitor sees the frozen one-path sentence
Visitor sees a skip count greater than zero

## Skip log lives in SKIPLOG.md
Every rejected idea gets one table row.
Rows are not tickets for this weekend.

## Demo gate
./scripts/demo_gate.sh must exit 0
No second HTML page. No new dependency.

Paste the card into every later prompt.
Do not renegotiate it after the agent gets excited.
Excitement is how weekend scope dies.

Step 1: freeze the path in one sentence

Write one sentence you can click on Sunday.
"A visitor can open /receipt.html and see the cut."
That sentence is the whole product this weekend.

Put the sentence at the top of the prompt.
Tell the agent to refuse work outside it.
Ask for a skip list, not a backlog of extras.

Use this labeled starter prompt:

Read WEEKEND.md first.
Build only the demo path in that file.
Do not add files for skipped items.
After the plan, print a skip log table.
Do not implement any row from that table.
Stop when ./scripts/demo_gate.sh exits 0.

If the plan mentions login, you stop the run.
If the plan mentions a second route, you stop.
Point the agent back at the one sentence.

Step 2: write the skip log before code

Skipped work is a deliverable, not a footnote.
Agents hide extra scope inside "while we are here."
A table makes that visible on Saturday morning.

Create SKIPLOG.md with this shape:

# Skip log — 2026-09-09

| Idea | Why it sounds useful | Why it waits |
| --- | --- | --- |
| JWT login | Receipt looks more "real" | Demo has no private data |
| Postgres | Skip count might need history | A static number is enough |
| Email digest | Feels like a real product | There are no users yet |
| Component kit | Page looks unfinished | One HTML file is a demo |
| Extra /admin page | You might edit skips later | Sunday is for the gate |

Review the table before any generate step.
If a row is not the demo path, it stays skipped.
Do not delete the row to soothe the agent.

Step 3: define working demo as a command

A screenshot is not a demo this weekend.
A passing command is the only done definition.
If the command fails, you are not finished.

Create scripts/demo_gate.sh as a labeled starter:

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

root="$(cd "$(dirname "$0")/.." && pwd)"
cd "$root"

port="${PORT:-8787}"
log="$(mktemp)"
pid=""

cleanup() {
  if [[ -n "${pid}" ]] && kill -0 "${pid}" 2>/dev/null; then
    kill "${pid}" 2>/dev/null || true
    wait "${pid}" 2>/dev/null || true
  fi
  rm -f "${log}"
}
trap cleanup EXIT

test -f public/receipt.html
test -f SKIPLOG.md
test -f WEEKEND.md

python3 -m http.server "${port}" --directory public >"${log}" 2>&1 &
pid="$!"
sleep 0.4

html="$(curl -fsS "http://127.0.0.1:${port}/receipt.html")"

echo "${html}" | grep -q "Demo path"
echo "${html}" | grep -q "Skipped:"

rows="$(grep -c '^|' SKIPLOG.md || true)"
if [[ "${rows}" -lt 3 ]]; then
  echo "skip log is too thin" >&2
  exit 1
fi

echo "demo gate passed"

The script is intentionally shallow.
It checks the one path. It ignores polish.
Do not grow it into a full suite this weekend.

Then run:

chmod +x scripts/demo_gate.sh
./scripts/demo_gate.sh

Failing output is useful. Passing output means stop.
You do not add a second page after a pass.
The gate is a brake, not a trophy.

Step 4: give the agent a hard stop rule

"Looks good" is not an exit condition.
"We can add this quickly" is not an exit condition.
demo_gate.sh exiting 0 is the exit condition.

Add this block under the path sentence:

Stop when all of these are true:
1. public/receipt.html shows the frozen path.
2. ./scripts/demo_gate.sh exits 0.
3. SKIPLOG.md lists every rejected extra.
4. git diff --name-only stays on the card files.

Check the file list yourself after each run:

git diff --name-only
git status --short

If a new stylesheet framework appears, revert it.
If a second HTML file appears, revert it.
The skip log already explained why it waits.

Step 5: keep the laptop free with a remote run

Local setup can burn half of Saturday.
Port clashes, language versions, and leftover processes stack up.
A free server is useful when that noise starts winning.

MonkeyCode fits this step if you lack spare hardware.
Disclosure: This article was prepared as part of MonkeyCode's product outreach.
It provides free model access and a free server option.
Use both as a quiet place to run the same gate, not as extra product scope.

Same WEEKEND.md. Same skip log. Same script.
If the gate fails on the remote box, the demo failed.
If you want that isolated weekend run, try those free options on this card.

A labeled remote check looks like this:

# labeled example — replace host and path
ssh weekend-box 'cd ~/receipt-demo && ./scripts/demo_gate.sh'

You still read the diff. The box does not ship for you.
Free compute does not unlock a second feature.
It only lets the gate fail before Sunday panic.

A starter page that matches the gate

Label this HTML as an unexecuted starter example.
Put it in public/receipt.html and stop there.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>Weekend receipt</title>
</head>
<body>
  <h1>Demo path</h1>
  <p>Visitor opens /receipt.html and sees the cut.</p>
  <p>Skipped: 4 items on purpose</p>
</body>
</html>

Run the gate after the file exists.
If it passes, the weekend build is complete.
Do not "just add" an edit form after that.

What you skip on purpose

Skip auth. The receipt page is public on purpose.
Skip a database. A skip count does not need tables.
Skip a design system. One HTML file can prove the path.

Skip extra routes. /receipt.html is the product.
Skip notifications. Nobody is on call for this demo.
Skip coverage theater. The gate is the only proof.

Write future tickets if that calms you down.
Do not let those tickets leak into Sunday's diff.
A passing demo plus a skip log is the ship.

Limitations

This method is rude to product ambition.
It will reject good ideas that miss the path.
That rudeness is the two-day constraint working.

The gate is shallow. It does not prove security.
It does not prove load. It does not prove taste.
It only proves the one path still responds.

Free model access can still invent extra files.
A free server can still host an overbuilt tree.
The card and the skip log remain the control.

Do not use this for production authentication work.
Do not use this when you need compliance evidence.
Do not use this if the demo path is still fuzzy.

Close

Saturday is for cutting. Sunday is for the gate.
You ship one path. You publish the skip log.
That pair is a finished weekend side project.

Weekend Build Log: One Ping Command, Zero Extra Flags

Riley Zhang — Tue, 08 Sep 2026 03:23:30 +0000

You sit down Saturday morning at 9:12. The coffee on your desk is already cooling. You want one command that pings one URL.

It should print ok or fail, then exit. That is the entire weekend plan on purpose.

Then the coding agent starts planning extra features. The plan adds auth, retries, and extra flags. It also adds a second subcommand for history.

You never asked for that extra surface. Cheap generation still creates extra review work later. Review work will eat your Sunday night.

This log is a scope cut with a working demo. You freeze the public CLI before helpers land. You skip every feature that grows the contract.

The inside of the binary can stay ugly. The outside of the binary stays tiny. That split is the whole method.

The Saturday failure mode

You paste a fuzzy prompt into the agent. The plan looks helpful, complete, and oversized. It invents --json, --timeout, and --retries.

It invents STATUS_PING_TOKEN without a source. It invents status-ping history as a second command. Your one-file tool becomes a platform sketch.

You will not finish a platform this weekend. You also should not merge mystery flags. Mystery flags become an accidental public API.

Accidental API becomes debt when generation is cheap. You need a gate that fails the plan. The gate is a contract card plus checker.

Both files live in the repo root. Neither file needs a paid cloud account. You run them after every agent diff.

The freeze card

Create CONTRACT.md at the repo root. Keep the file under twenty lines. Write names, not wishes or later ideas.

If a flag is missing here, it does not exist. Print the card before you prompt the agent. Paste the card into the prompt itself.

# CLI contract (frozen for this weekend)

Binary: status-ping
Commands: status-ping
Required flag: --url <absolute-http-url>
Optional flags: none
Env vars: none
Exit 0: stdout is exactly ok
Exit 2: stdout is exactly fail
Exit 1: usage error on stderr
Network: one GET, no redirects followed
Files allowed: status_ping.py, CONTRACT.md, contract_check.py, README.md
Forbidden: extra commands, extra flags, extra env, extra HTTP methods

Tell the agent the checker will fail the branch. Do not debate a flag that is absent here. Absence on this card is a hard no.

1. Scaffold the stub yourself

Do not let the agent invent the entrypoint. Write a stub that already obeys the card. You are locking the outside first.

The agent may fill request details later. It may not add flags while filling. Save the stub as status_ping.py.

#!/usr/bin/env python3
"""status-ping: one GET, two happy strings."""
from __future__ import annotations

import argparse
import sys
import urllib.error
import urllib.request


def parse_args(argv: list[str]) -> argparse.Namespace:
    parser = argparse.ArgumentParser(prog="status-ping")
    parser.add_argument("--url", required=True)
    return parser.parse_args(argv)


def ping(url: str) -> int:
    if not url.startswith(("http://", "https://")):
        print("usage: --url must be absolute http(s)", file=sys.stderr)
        return 1
    req = urllib.request.Request(url, method="GET")
    try:
        with urllib.request.urlopen(req, timeout=5, context=None) as resp:
            ok = 200 <= getattr(resp, "status", 200) < 300
    except (urllib.error.URLError, TimeoutError, ValueError):
        print("fail")
        return 2
    print("ok" if ok else "fail")
    return 0 if ok else 2


def main() -> None:
    args = parse_args(sys.argv[1:])
    raise SystemExit(ping(args.url))


if __name__ == "__main__":
    main()

Run a usage check before any agent edit. Confirm the missing-flag path without guessing.

chmod +x status_ping.py
python3 status_ping.py; echo exit:$?
python3 status_ping.py --url https://example.com; echo exit:$?

You should see exit 1 without --url. You should see ok or fail with a URL. That pair is the demo spine.

Do not add JSON output yet. Do not add a timeout flag yet. Those belong on the skip list later.

2. Add a checker that reads the freeze

The checker is the original artifact. It is deliberately dumb on purpose. Dumb gates are hard to argue with.

Label this as a local helper script. It is not a security scanner. It only freezes this weekend CLI.

#!/usr/bin/env python3
"""Fail the branch if the public CLI grew."""
from __future__ import annotations

import pathlib
import re
import sys

ROOT = pathlib.Path(__file__).resolve().parent
SOURCE = (ROOT / "status_ping.py").read_text(encoding="utf-8")
CONTRACT = (ROOT / "CONTRACT.md").read_text(encoding="utf-8")

FORBIDDEN_FLAG = re.compile(r"add_argument\(\s*[\"']--(?!url\b)[\w-]+")
FORBIDDEN_ENV = re.compile(r"os\.environ|getenv\(")
FORBIDDEN_CMD = re.compile(r"add_subparsers\(")
FORBIDDEN_METHOD = re.compile(r"method\s*=\s*[\"'](?!GET)[A-Z]+[\"']")


def main() -> int:
    errors: list[str] = []
    if "Binary: status-ping" not in CONTRACT:
        errors.append("CONTRACT.md missing frozen binary name")
    if FORBIDDEN_FLAG.search(SOURCE):
        errors.append("extra argparse flags are not in the contract")
    if FORBIDDEN_ENV.search(SOURCE):
        errors.append("env reads are forbidden this weekend")
    if FORBIDDEN_CMD.search(SOURCE):
        errors.append("subcommands are forbidden this weekend")
    if FORBIDDEN_METHOD.search(SOURCE):
        errors.append("only GET is allowed this weekend")
    if 'print("ok")' not in SOURCE and "print('ok')" not in SOURCE:
        errors.append("happy path must print ok")
    if errors:
        print("contract failed:")
        for item in errors:
            print(f"- {item}")
        return 2
    print("contract ok")
    return 0


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

Run it on every agent diff. Keep the command in your notes.

python3 contract_check.py; echo exit:$?

If the agent adds --json, this exits 2. You reject that diff immediately. You do not negotiate the extra flag.

3. Prompt the agent against the card

Keep the prompt short and file-specific. Point at the freeze before any edit. Ban invention in plain language.

Read CONTRACT.md and contract_check.py first.
Edit only status_ping.py.
Do not add flags, env vars, or subcommands.
Keep stdout exactly ok or fail.
Keep one GET and no extra files.
Stop after python3 contract_check.py exits 0.

If you run this loop on a laptop, that is enough. If you want the agent off your machine, you can use MonkeyCode for the same freeze loop.

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

MonkeyCode offers free model access and a free server option. Treat those as weekend capacity for this loop. Do not assume named models, quotas, hardware, or duration.

Put CONTRACT.md in the project you open there. Run the same checker after the agent edits. The card still owns the public surface.

4. Prove the demo, then stop

Use a URL you control when you can. A public example host is fine for a stub. This is a demo, not a monitor.

python3 status_ping.py --url https://example.com
python3 contract_check.py

Expected shape on a healthy fetch:

ok
contract ok

Fail path, still frozen:

python3 status_ping.py --url https://127.0.0.1:1; echo exit:$?

You should see fail and exit 2. You should not see a Python stack trace. Stack traces are extra surface on stdout.

If the agent prints tracebacks, send it back. Point at the exit table in CONTRACT.md. Ask for the two strings only.

5. Write the skip list before you get clever

Scope cut only counts if you record skips. Put the list in README.md beside the demo. Do not let the agent turn it into a roadmap.

## Skipped on purpose (this weekend)

- No JSON output
- No retry loop
- No timeout flag
- No auth header
- No config file
- No history command
- No database
- No dashboard
- No Docker
- No extra HTTP methods

That list is part of the product. The ping command is only the demo. Readers can copy the list into an agent prompt.

Cheap code is not the weekend risk. Unnamed surface is the weekend risk. Name the outside, then stop.

What this does not catch

The checker is a regex net. It will miss clever parsing code. It will miss handmade sys.argv branches.

It will miss a second module the agent creates. Pair it with a four-file list if needed. Add that list to the card if your agent keeps expanding paths.

It also does not measure latency numbers. It does not prove TLS behavior. It does not replace a real API review.

It freezes a weekend CLI. That is all it claims. Keep that limit visible in the README.

Who should not use this

Do not use this approach for a real service contract. Do not use it for auth, payments, or personal data. Do not use it as production monitoring.

A five second GET with no redirects is a teaching stub. It is not an SLO and not an incident tool. Treat a green checker as a freeze, not as proof.

Skip this method if your team already has OpenAPI tests. Those tests are better than a regex card. This card exists for a solo Saturday.

It exists when the agent is faster than your review habits. It does not exist to replace design. It exists to stop Saturday from becoming a platform.

Why freeze beats another helper file

Agents like adding helpers. Helpers feel like architecture in the plan. Architecture without a freeze becomes a pile.

You already know that pile from other weekends. You have seen clients, mixins, and adapters for one GET. You cut that pile by naming the outside first.

Numbered steps keep you honest:

Freeze names in CONTRACT.md.
Scaffold the stub yourself.
Run contract_check.py on every diff.
Prompt against the card only.
Demo ok / fail, then stop.
Publish the skip list with the demo.

If a step starts spawning files, you are off the card. Return to step 1 without a debate. Delete the extra flag instead of renaming it.

Keep the loop boring

Free model access is enough for this loop. A free server is enough to keep the checker near the agent. Neither makes the contract smarter by itself.

You still have to refuse extra surface. If the run is slow, wait on the checker. If the model ignores the card, the checker still fails.

That failure is the feature you wanted. You can copy these four files into any repo. You do not need one particular host to use the freeze.

Keep the freeze, the stub, the checker, and the skip list. That set is the whole weekend method. Ship the ping, then leave the extras off the card.

Stop Your Weekend Agent From Adding Libraries

Riley Zhang — Mon, 07 Sep 2026 14:07:30 +0000

You open the laptop at 9:12 Saturday.
The side project still has no public demo.
You paste a vague prompt into an agent.
The reply suggests three extra helper libraries.

That is how a whole weekend disappears.
New packages look cheap when generation is cheap.
They stop looking cheap during Sunday deploy.
You wanted one boring working request path.
You almost bought another package supply chain.

This post records a practical weekend workflow.
The article is not a product review piece.
You freeze dependencies for one full weekend.
You still ship a tiny public demo.
You skip every feature that needs libraries.

The Saturday failure mode

Your repo already contains Express and core Node.
The agent does not respect that existing inventory.
It reaches for a retry HTTP client next.
It reaches for a schema validation kit too.
It reaches for an ORM just in case.

Each add looks reasonable in isolation today.
Together they explode the lockfile by Sunday.
You spend the evening reading package changelogs.
The public demo still does not exist yet.

Cheap generation hides a real invoice later.
That invoice is dependency churn after merge.
You pay it when the agent goes quiet.
Agents also invent extra infrastructure in prose.
You do not need that argument on Saturday.

Write the freeze note first

Write the rule down before any prompt.
Keep the note in the repository root.
Name the file WEEKEND_FREEZE.md without debate.
The agent must read that file first.
You will score every plan against it.

Follow these five freeze rules without local exceptions:

Application source files may change freely.
package.json may not gain new names.
Lockfiles may not change this weekend.
New network services stay out of scope.
Required libraries mean you cut the feature.

Copy this freeze note into the repo root.

# WEEKEND_FREEZE.md

Goal: ship one demo path by Sunday 18:00.
Allowed paths: src/, README.md, tests/, data/.
Forbidden: package.json edits and lockfile edits.
Forbidden: new Docker services and new queues.
Demo path: POST /shorten and GET /:code.
Storage: local data/urls.json only.
If a task needs a new package, drop it.

This note is a proposal you can adapt.
Do not treat it as a security boundary.
It is only a scope tool for Sunday.

Scope you cut on purpose

The original sketch listed four extra features.
You keep a single request path only.
You park the rest on a later list.

Cut this list before generation starts:

OAuth because imaginary users might exist.
A metrics dashboard for later imagined scale.
Email sharing links for viral growth theater.
Redis because memory feels more official.

What remains is ugly and still shippable.
One POST handler writes a JSON file.
One GET handler reads that same file.
There is no dedicated uniqueness server here.
There is also no click analytics pipeline.

That cut is the actual design work.
The agent is usually bad at cutting.
You perform the cut before generation starts.

Artifact: a freeze checker script

Do not trust the model to obey English.
Trust a script that diffs manifest files.
Save this file as scripts/check-freeze.sh.
Treat it as sample code until you run it.

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

BASE="${1:-HEAD}"
PLAN="${2:-}"
FAIL=0

changed="$(git diff --name-only "$BASE" -- \
  package.json package-lock.json yarn.lock pnpm-lock.yaml 2>/dev/null || true)"

if [[ -n "$changed" ]]; then
  echo "FREEZE FAIL: manifest or lockfile changed:"
  printf '%s\n' "$changed"
  FAIL=1
fi

if git diff "$BASE" -- package.json | grep -E '^\+\s*"' >/dev/null 2>&1; then
  echo "FREEZE FAIL: package.json entries were altered."
  FAIL=1
fi

if [[ -n "$PLAN" && -f "$PLAN" ]]; then
  if grep -Ei 'npm install|npm i |yarn add|pnpm add|pip install' "$PLAN" >/dev/null; then
    echo "FREEZE FAIL: plan installs packages."
    FAIL=1
  fi
fi

if [[ "$FAIL" -ne 0 ]]; then
  echo "Reject the plan. Cut the feature instead."
  exit 1
fi

echo "FREEZE OK: no new dependencies in this diff."

Make the script executable on your machine.

chmod +x scripts/check-freeze.sh

Run it against last night's commit and plan.

./scripts/check-freeze.sh HEAD~1 agent-plan.md

If it fails, you do not negotiate terms.
You delete the blocked feature from the plan.
Then you generate a narrower plan again.

A demo that survives the freeze

You need a path the script cannot block.
Use Node built-ins plus existing Express only.
Label this as sample code for a brownfield repo.
Wire it only when Express already exists there.

// src/shorten.js
const fs = require("fs");
const path = require("path");
const express = require("express");

const DATA = path.join(__dirname, "..", "data", "urls.json");
const app = express();
app.use(express.json());

function load() {
  if (!fs.existsSync(DATA)) return {};
  return JSON.parse(fs.readFileSync(DATA, "utf8"));
}

function save(map) {
  fs.mkdirSync(path.dirname(DATA), { recursive: true });
  fs.writeFileSync(DATA, JSON.stringify(map, null, 2));
}

app.post("/shorten", (req, res) => {
  const url = String((req.body && req.body.url) || "");
  if (!/^https?:\/\//.test(url)) {
    return res.status(400).json({ error: "url must be http(s)" });
  }
  const code = Math.random().toString(36).slice(2, 8);
  const map = load();
  map[code] = url;
  save(map);
  res.json({ code, url });
});

app.get("/:code", (req, res) => {
  const map = load();
  const target = map[req.params.code];
  if (!target) return res.status(404).json({ error: "not found" });
  res.redirect(target);
});

app.listen(3000, () => {
  console.log("demo on :3000");
});

Use this manual test plan after server startup.

Start the server with node src/shorten.js.
POST a valid https URL to /shorten.
Open the returned code in your browser.
POST a non-http value and expect 400.
Confirm package.json is still unchanged.

That is the entire weekend demo surface.
It is enough for a short screenshot.
It is not a production shortening product.

Score the plan before you apply it

Agents hide installs inside friendly prose.
"Pull in a small UUID helper" means install.
You want a boring local scoring script.
Save this file as scripts/score-plan.js.

#!/usr/bin/env node
const fs = require("fs");

const file = process.argv[2] || "plan.md";
const text = fs.readFileSync(file, "utf8");

const rules = [
  [/npm i(nstall)?|yarn add|pnpm add/i, "package install"],
  [/package\.json/i, "manifest mention"],
  [/redis|rabbitmq|kafka|elasticsearch/i, "new infrastructure"],
  [/docker-compose|new service/i, "new service"],
  [/uuid|lodash|axios|prisma|mongoose/i, "popular extra library"],
];

let score = 10;
const hits = [];
for (const [re, label] of rules) {
  if (re.test(text)) {
    score -= 3;
    hits.push(label);
  }
}

console.log(JSON.stringify({ score, hits }, null, 2));
if (score < 7) process.exit(1);

A plan that mentions Axios should fail.
A plan that edits one route should pass.
Keep the threshold harsh on weekend nights.
Run the scorer before any git apply step.

node scripts/score-plan.js agent-plan.md

How the weekend actually runs

Use this sequence and do not reorder it.

Write WEEKEND_FREEZE.md before opening the agent.
Paste the freeze note into the first prompt.
Save the model plan as agent-plan.md locally.
Run node scripts/score-plan.js agent-plan.md first.
Run ./scripts/check-freeze.sh HEAD agent-plan.md next.
Apply source changes only after both pass.
Execute the five HTTP checks on port 3000.
Record skipped features in README.md before sleep.

If any numbered step fails, stop generation.
Cut scope again instead of adding packages.
The demo gets smaller and more honest then.

Draft the plan, then run the checker

You still need a model to draft plans.
You still need a machine to run checks.

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

MonkeyCode's free model access can draft the plan.
The free server option can run check-freeze.sh.
Do not hand the model a blank weekend.
Hand it the freeze note and demo path.
Ask for files, not packages, in the plan.
Score that plan on the server next.
Only then apply a bounded source diff.

Paste a prompt with this exact shape.

Read WEEKEND_FREEZE.md before you answer.
Propose a patch for POST /shorten validation only.
Do not add packages or new services.
List every file you will touch.
If the freeze blocks the idea, reply SKIP.

If the reply contains an install, reject it.
The script remains the source of truth.
The model remains a draft engine only.

This article does not claim latency numbers.
It does not claim quotas or model names.
Those details change and stay unverified here.
Use free model access you already have.
Keep the checker local if that is simpler.

What you skipped on purpose

You skipped pretty HTML for the landing page.
You skipped login and session cookies.
You skipped rate limits on POST /shorten.
You skipped unique codes under collision risk.
You skipped extra test matchers from new packages.
You skipped deploy automation for this weekend.

Write the skip list into the README now.
Future you will thank present you later.
The agent will try to finish skipped items.
The freeze note is how you refuse that.

Add this fragment to README.md today.

## Out of scope this weekend
- auth
- unique codes
- analytics
- custom domains
- new npm dependencies

If it is not the demo path, skip it.
A skip list is part of the working demo.
Readers should see what you refused.

Limitations

This workflow fails closed on purpose tonight.
It will block legitimate library needs too.
That is the point for forty-eight hours.
It is wrong for a framework upgrade weekend.

The grep rules stay crude by design.
They can flag a harmless comment line.
They can miss a vendored copy-paste tree.
A copied node_modules folder still burns you.

The JSON file store corrupts under parallel writes.
You accepted that trade for a demo.
A weekend demo is not a multiplayer system.

Do not treat the freeze as license review.
It does not scan licenses or CVEs.
It only stops accidental dependency adds.

Who should not use this

Skip this during a production on-call shift.
Skip this when the task upgrades Express itself.
Skip this when compliance needs a new client.
Skip this if you cannot read the diff.
Skip this if uniqueness must be guaranteed.

People learning package managers should not freeze yet.
They still need to feel a real install.
This note is for repos with too many already.

Sunday checklist

Work through these five checks in order.

Re-run ./scripts/check-freeze.sh HEAD~20 on the branch.
Re-run the five manual HTTP checks again.
Paste the skip list into the README file.
Commit application files and data fixtures only.
Stop before adding just a little logging.

If step one fails, revert the diff.
If step two fails, fix code, not dependencies.
If you still want Redis, wait until Monday.

Close

Weekend agents optimize for looking complete fast.
You optimize for a demo you can explain.
A frozen lockfile is a design decision.
The script makes that decision visible locally.

If you try this, keep the note tiny.
Keep the demo path to two routes.
Let the skip list do the talking.

Weekend Gate: Give Your Agent a Five-File Diff Budget

Riley Zhang — Sun, 06 Sep 2026 20:51:35 +0000

You sit down Saturday with one small feature.
The agent returns a plan that spans the repo.
You asked for a CLI flag, not a new framework.

Weekend side projects often rot inside oversized diffs.
Cheap generation never means a cheap review later.
You still pay for every extra file during review.

You need a gate that fails in the open.
A polite prompt will not hold the line.
A file budget can, because git still enforces it.

The actual weekend failure

Agents optimize for a complete-looking patch.
They add helpers, wrappers, and spare modules.
You wanted a demo you can run by Sunday.

This is not a model-quality problem first.
It is a scope problem you can measure.
Diff size is the measurement that does not lie.

Current agent write-ups keep hitting the same wall.
The model assumes missing architecture and extra packages.
Your repo then inherits that assumption as files.

You freeze three numbers before any generation starts.
Max files touched. Max lines added. Allowed path prefixes.
The agent may argue in chat. Git still rejects the branch.

Scope cut for this working demo

You will ship a local checker in one sitting.
You will not ship a bot platform this weekend.
The demo is a card, a script, and a hook.

Skip these on purpose before you open the chat:

GitHub Actions and required status checks
Language-specific AST parsing or formatters
Auto-rewriting the agent patch in place
Auth, billing, users, and hosted dashboards
A second service just to store scores

If a step needs a new package, it is out.
If a step needs a new config file, it is out.
The working demo must run on a dirty git tree.

Artifact: freeze card plus a budget file

Create two files at the repo root before coding.
Commit both while the tree is still clean.
Treat them as product constraints, not comments.

1. Write the human card

DIFFBUDGET.md is for you and the agent.
Keep the goal to one testable sentence.
If you cannot run the done line, cut the goal.

# DIFFBUDGET.md

Goal: add `--json` to the existing `report` command.
Deadline: Sunday 18:00 local.
Max files touched: 5
Max lines added: 120
Max lines deleted: 40
Allowed prefixes:
- src/cli/
- src/report/
- tests/cli/
Forbidden:
- new packages
- new config files
- containers
- HTTP clients
Done means:
- `python -m src.cli report --json` prints valid JSON
- existing text output still works
- `python3 scripts/check_diff_budget.py` exits 0

2. Write the machine card

Markdown is easy to skim and easy to ignore.
Put the numbers in DIFFBUDGET.json as well.
The checker reads JSON only. Do not parse prose.

{
  "base": "main",
  "max_files": 5,
  "max_lines_added": 120,
  "max_lines_deleted": 40,
  "allowed_prefixes": [
    "src/cli/",
    "src/report/",
    "tests/cli/"
  ]
}

Change the prefixes to match your tree.
Keep max_files at five for a weekend CLI change.
Raise it only after a failed run, never before.

Artifact: the checker script

Save this as scripts/check_diff_budget.py.
It needs Python 3 and git. No extra packages.
Label this as a local gate you can copy and run.

#!/usr/bin/env python3
"""Fail if the current git diff exceeds DIFFBUDGET.json."""
from __future__ import annotations

import json
import subprocess
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
BUDGET_PATH = ROOT / "DIFFBUDGET.json"


def git(*args: str) -> str:
    proc = subprocess.run(
        ["git", *args],
        cwd=ROOT,
        check=False,
        text=True,
        capture_output=True,
    )
    if proc.returncode != 0:
        raise SystemExit(f"git {' '.join(args)} failed:\n{proc.stderr}")
    return proc.stdout


def load_budget() -> dict:
    if not BUDGET_PATH.exists():
        raise SystemExit(f"missing {BUDGET_PATH}")
    return json.loads(BUDGET_PATH.read_text(encoding="utf-8"))


def unique(seq: list[str]) -> list[str]:
    seen: list[str] = []
    for item in seq:
        if item not in seen:
            seen.append(item)
    return seen


def changed_files(base: str) -> list[str]:
    named = git("diff", "--name-only", "--diff-filter=ACMR", base)
    tracked = [n for n in named.splitlines() if n]
    extra = git("ls-files", "--others", "--exclude-standard")
    untracked = [n for n in extra.splitlines() if n]
    return unique(tracked + untracked)


def line_stats(base: str, untracked: list[str]) -> tuple[int, int]:
    added = 0
    deleted = 0
    out = git("diff", "--numstat", base)
    for line in out.splitlines():
        parts = line.split("\t")
        if len(parts) < 3:
            continue
        a, d = parts[0], parts[1]
        if a == "-" or d == "-":
            continue
        added += int(a)
        deleted += int(d)
    for path in untracked:
        file_path = ROOT / path
        if not file_path.is_file():
            continue
        try:
            text = file_path.read_text(encoding="utf-8")
        except UnicodeDecodeError:
            continue
        added += len(text.splitlines())
    return added, deleted


def main() -> int:
    budget = load_budget()
    base = budget.get("base", "main")
    allowed = tuple(budget["allowed_prefixes"])
    files = changed_files(base)
    untracked = [
        n for n in git("ls-files", "--others", "--exclude-standard").splitlines() if n
    ]
    added, deleted = line_stats(base, untracked)
    errors: list[str] = []

    if len(files) > int(budget["max_files"]):
        errors.append(f"files {len(files)} > {budget['max_files']}")
    if added > int(budget["max_lines_added"]):
        errors.append(f"added {added} > {budget['max_lines_added']}")
    if deleted > int(budget["max_lines_deleted"]):
        errors.append(f"deleted {deleted} > {budget['max_lines_deleted']}")

    outside = [f for f in files if not f.startswith(allowed)]
    if outside:
        listing = "\n  ".join(outside)
        errors.append(f"paths outside allowed prefixes:\n  {listing}")

    print(f"base={base}")
    print(f"files={len(files)}/{budget['max_files']}")
    print(f"added={added}/{budget['max_lines_added']}")
    print(f"deleted={deleted}/{budget['max_lines_deleted']}")
    for path in files:
        print(f"  {path}")

    if errors:
        print("BUDGET FAIL")
        for err in errors:
            print(f"- {err}")
        return 1

    print("BUDGET OK")
    return 0


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

Untracked files count toward the file cap.
Their lines count only when the file is text.
Binary untracked files are a documented gap, not magic.

Weekend workflow in five steps

1. Freeze the cards on a clean tree

git status --short
git rev-parse --abbrev-ref HEAD

Do not start the agent on a dirty branch.
You need a honest baseline against main.
Commit the two cards and the script first.

mkdir -p scripts
chmod +x scripts/check_diff_budget.py
git add DIFFBUDGET.md DIFFBUDGET.json scripts/check_diff_budget.py
git commit -m "Add weekend diff budget gate"

2. Run the gate on an empty diff

python3 scripts/check_diff_budget.py

You want BUDGET OK and zero files listed.
If this fails, your base ref is wrong.
Fix the base name before you generate code.

3. Constrain the agent with the card

Paste DIFFBUDGET.md at the top of the prompt.
Tell the agent the checker is the merge rule.
Tell it not to add prefixes. Tell it not to raise caps.

Ask for a file list before any patch.
If the list is already six files, cut scope now.
Do not let it "just add a util."

4. Run the gate before you read the patch

python3 scripts/check_diff_budget.py; echo exit:$?
git diff --stat main

Read the gate output first, not the model prose.
A red budget means you do not review yet.
Review time is the scarce weekend resource.

5. Cut scope when the gate fails

Do not raise max_files as the first move.
Delete the extra helper and rerun the script.
Keep the done line. Drop the extra design.

Typical cuts that save a Sunday:

Drop a new config loader. Hard-code one flag.
Drop a shared util package. Keep a local function.
Drop extra output formats. Ship JSON only.
Drop refactors in untouched modules. Leave them.
Drop docs rewrites unless the done line needs them.

Decision table: raise the cap or cut the demo

Use this table when the gate fails.
Pick one row. Do not mix raises with new features.

Signal	Action	Skip
Sixth file is a test next to the CLI	Keep the test. Cut a helper file.	Do not add `tests/` as a free-for-all prefix.
Sixth file is `utils.py` in a new folder	Delete it. Inline ten lines.	Do not raise `max_files`.
Line cap fails on a lockfile	Put lockfiles in a ignore list later	Do not ignore `src/` noise.
Agent needs a new HTTP client	Stop. That is a different weekend.	Do not expand prefixes.
Done line cannot run in five files	Shrink the done line.	Do not keep the old done line.

The table is the product of this demo.
The script only makes the table unavoidable.
Without the fail, you will negotiate with the model.

Local hook, still not CI

You skipped GitHub Actions on purpose.
A local pre-commit hook is enough this weekend.
Install nothing hosted. Keep the hook in the repo.

# .git/hooks/pre-commit
#!/bin/sh
exec python3 scripts/check_diff_budget.py

chmod +x .git/hooks/pre-commit

This hook is local and easy to bypass.
That is acceptable for a solo weekend branch.
It is not acceptable as your only production control.

Reproducible test plan

Do not trust a green run from one happy path.
Walk these four cases on a throwaway branch.
Stop if any case disagrees with the table.

Clean tree versus main must print BUDGET OK.
Six tiny files under allowed prefixes must fail.
One file under docs/ must fail on prefixes.
A 121-line add under src/cli/ must fail lines.

Commands for case 2 look like this:

mkdir -p src/cli
printf 'x\n' > src/cli/a.py
printf 'x\n' > src/cli/b.py
printf 'x\n' > src/cli/c.py
printf 'x\n' > src/cli/d.py
printf 'x\n' > src/cli/e.py
printf 'x\n' > src/cli/f.py
python3 scripts/check_diff_budget.py; echo exit:$?

You should see BUDGET FAIL and files 6 > 5.
Reset the throwaway files after the check.
Keep the test plan in DIFFBUDGET.md if you forget.

What you skipped, and why that is the demo

You skipped CI because the lesson is the freeze.
You skipped auto-fix because failed diffs teach faster.
You skipped a database because scores do not need storage.

The working demo is a red exit code on Saturday.
The working demo is a green exit code on Sunday.
Anything beyond that is next weekend, not this one.

Limitations

This gate does not read code quality.
A five-file patch can still be wrong.
You still have to run the done-line command.

Prefix checks are string prefixes, not owners.
src/cli/../secret is not a solved case here.
Do not treat this script as a security boundary.

git diff --numstat skips binary tracked files.
Untracked binary files also skip line counts.
Lockfiles can burn the line budget without warning.

The hook is local. Anyone can --no-verify.
Teams with real release trains need real CI later.
This article does not claim hosted runtime numbers.

Who should not use this

Do not use this as your only review on production patches.
Do not use this if you will ignore a red gate.
Do not use this to justify merging unread agent code.

Skip it when an incident needs a wide, careful diff.
Skip it when CODEOWNERS already block path drift.
Skip it when the weekend goal is learning a new stack.

Where a free model box fits

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

The gate is just git plus a JSON file.
You can plan the five-file change with MonkeyCode free model access if you have no paid API key this weekend, and you can run the checker on its free server option if you want that process off your laptop. Keep DIFFBUDGET.json in your repo either way. If you need a free-model box for the planner, try that server and leave the budget file in git.

The article still works if you never do that.
The scarce resource remains your Sunday review time.
Five files is enough for a real demo. Stop there.

Weekend Build Log: Stop Agent Plans That Invent Files

Riley Zhang — Sat, 05 Sep 2026 19:23:45 +0000

You sit down Saturday with too much ambition. You want an agent that reviews pull requests. Then the plan cites a helper you never wrote.

That miss is the whole weekend risk. You do not need a larger model today. You need a smaller demo and a path check.

The scene you already know

You paste a repo tree into a chat window. You ask for a short implementation plan. The plan names three files that do not exist.

You feel tempted to let the agent create them. Invented files become invented functions by lunch. Your Sunday then pays for Saturday's optimism.

What this weekend actually ships

You ship one working checker, not a product. The checker compares claimed paths with the real tree. A missing path stops the plan immediately.

You also ship a one-page scope card. The card lists the demo, the skips, and the stop rule. That pair is the complete weekend deliverable.

Pick one repo you already own today.
Freeze a two-hour demo target right now.
Ban new hosted services for this weekend.
Require a path ledger before any code edits.

Write the scope card first

Create the WEEKEND_SCOPE.md file before you send any prompt. Keep the scope card ugly and short. Pretty writing steals the only free morning.

# Weekend scope — assumption trap

Demo: print missing paths from an agent plan.
Success: exit 1 when any claimed file is absent.
Skip: PR comments, web UI, extra database, auth.
Stop: if the checker needs a network call.

Read the finished card out loud once. Cut any step that needs a vendor account. Cut any step that starts a second process.

Build an assumption ledger

The ledger is a JSON object, not a paragraph. You extract every path the plan claims. You refuse to trust free-form prose here.

Ask the model for JSON output only. Reject extra commentary in the same reply. Save the object as claimed_paths.json immediately.

{
  "task": "add a dry-run lint command",
  "claimed_paths": [
    "src/lint.ts",
    "scripts/dry_run.sh",
    "docs/LINT.md"
  ],
  "new_paths_allowed": [
    "scripts/dry_run.sh"
  ]
}

new_paths_allowed is the only door for new files. Every other claimed path must already exist. That single field is your scope cut.

A checker you can run

Treat this script as a proposal, not production control. Save the checker script as tools/check_claimed_paths.py locally. Run it before you accept any generated patch.

#!/usr/bin/env python3
"""Fail if an agent plan cites missing paths."""

from __future__ import annotations

import json
import sys
from pathlib import Path


def load_ledger(path: Path) -> dict:
    data = json.loads(path.read_text(encoding="utf-8"))
    if "claimed_paths" not in data:
        raise ValueError("claimed_paths missing")
    if "new_paths_allowed" not in data:
        raise ValueError("new_paths_allowed missing")
    return data


def check(repo: Path, ledger: dict) -> list[str]:
    allowed = set(ledger["new_paths_allowed"])
    missing: list[str] = []
    for raw in ledger["claimed_paths"]:
        rel = Path(raw)
        if rel.is_absolute() or ".." in rel.parts:
            missing.append(f"illegal path: {raw}")
            continue
        target = repo / rel
        if target.exists() or raw in allowed:
            continue
        missing.append(raw)
    return missing


def main() -> int:
    if len(sys.argv) != 3:
        print(
            "usage: check_claimed_paths.py REPO LEDGER.json",
            file=sys.stderr,
        )
        return 2
    repo = Path(sys.argv[1]).resolve()
    ledger = load_ledger(Path(sys.argv[2]))
    missing = check(repo, ledger)
    if not missing:
        print("ok: all claimed paths are present or allowed")
        return 0
    print("blocked: agent cited missing paths")
    for item in missing:
        print(f"  - {item}")
    return 1


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

The script stays boring on purpose today. Boring checks survive a tired Saturday brain. Fancy retry loops do not survive that.

Prove it with a fixture

Do not skip tests because the file is small. A two-path fixture catches the weekend bug. Use a throwaway directory, not your main clone.

mkdir -p /tmp/assumption-demo/src
printf 'export function lint() { return 0 }\n' > /tmp/assumption-demo/src/lint.ts
cat > /tmp/claimed_paths.json <<'EOF'
{
  "task": "add a dry-run lint command",
  "claimed_paths": ["src/lint.ts", "scripts/dry_run.sh", "docs/LINT.md"],
  "new_paths_allowed": ["scripts/dry_run.sh"]
}
EOF
python3 tools/check_claimed_paths.py /tmp/assumption-demo /tmp/claimed_paths.json
echo "exit=$?"

You should see docs/LINT.md blocked in the output. src/lint.ts should pass because it exists. scripts/dry_run.sh should pass because you allowed it.

If the exit code is not 1, stop immediately. Fix the checker before you touch the agent. A silent miss is worse than no checker.

Add one more illegal-path case after that. Point the ledger at ../.env and run again. The script must print illegal path and refuse the plan.

cat > /tmp/claimed_escape.json <<'EOF'
{
  "task": "should hard-fail",
  "claimed_paths": ["../.env"],
  "new_paths_allowed": []
}
EOF
python3 tools/check_claimed_paths.py /tmp/assumption-demo /tmp/claimed_escape.json
echo "exit=$?"

Where a free draft box still helps

You still need a draft of the JSON ledger. You also need a box that runs Python. Keep both steps cheap and local when you can.

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

MonkeyCode provides free model access and a free server option. You can draft the ledger there and run this checker on that server. Drop the product and the same loop still runs on your laptop.

Keep secrets off any hosted prompt you use. Copy a throwaway tree without env files. Never put keys inside claimed_paths.json at all.

Numbered Saturday sequence

Follow this exact order on Saturday morning. Do not rearrange steps under time pressure.

Clone a throwaway copy of your application repo.
Write WEEKEND_SCOPE.md in ten focused minutes only.
Prompt for JSON paths, not for code.
Save claimed_paths.json without any hand-edited fields.
Then execute python3 tools/check_claimed_paths.py against your claimed_paths.json file.
If it fails, revise the plan, not the tree.
Only then allow writes in the allowed list.
Record every skipped idea in the same markdown file.

Step six is the whole weekend lesson. You change the plan when paths are missing. You do not invent files to make the plan true.

What you skip on purpose

You skip a web dashboard this weekend entirely. You skip storing ledgers in a Postgres instance. You skip Slack alerts and auto-created files.

You also skip making the agent look smarter. Smarter prompts still invent missing paths anyway. The filesystem does not invent those paths.

Skipped:
- GitHub Action matrix
- Embedding index of the repo
- Comment bot on pull requests
- Retry loop that creates missing files

If a skipped item sneaks back, stop the weekend. Ship the checker in its current shape. Do not open a second feature branch.

Failure analysis you can reuse

When the checker fails, classify the miss first. Use the table instead of arguing in chat. Speed matters more than a clever rebuttal.

Miss type	Example	Weekend action
Invented helper	`src/utils/secret.ts`	Delete from plan
Wrong extension	`app.js` vs `app.ts`	Correct the ledger
Case mismatch	`Readme.md`	Normalize on disk
Allowed new file	`scripts/dry_run.sh`	Keep if scope says so
Path escape	`../.env`	Hard fail, do not run

Print the table next to your terminal window. Decision speed matters on a short Saturday. You have hours, not a full sprint.

Honest limits

This does not prove the plan is correct. It only proves cited files exist or were allowed. A present file can still be the wrong file.

The script does not parse generated patches yet. It does not verify imports or types. It will not stop a bad refactor inside a real file.

Symlinks can fool a simple exists check. Nested parent segments can still look nasty. Treat the checker as a seatbelt, not a vault.

Who should not use this

Do not use this as a production gate yet. Do not run it on working trees that hold secrets. Do not use it if you cannot read the JSON.

Skip it if your task is purely documentation. Skip it if a code owner bot already blocks unknown paths. Skip it if you need a networked multi-agent demo.

If you cannot cut scope, do not start. An uncut agent demo turns Saturday into Monday. Protect the calendar before you protect the prompt.

Close the log

Your working demo is a red exit code. That signal is enough for this weekend. You learned where the plan diverges from disk.

Keep the scope card next to the script. Reuse both files on the next free Saturday. Change only the allowed paths list next time.

Make Your Weekend Agent List Unknowns First

Riley Zhang — Fri, 04 Sep 2026 17:08:49 +0000

You sit down Friday with one messy GitHub issue. You want a usable plan before Monday morning. You paste the text into a chat agent.

The reply looks polished, complete, and very sure. It adds Kafka, Redis, and a new auth service. The issue never named those systems.

You do not have a brownfield budget this weekend. You also do not want fake architecture. You need a gate that blocks invented specs.

The failure you are fixing

Agents fill gaps with confident guesses. That habit wrecks small side projects. You ship a plan that your repo cannot support.

A recent wave of agent write-ups repeats the same pain. The model assumes missing APIs, queues, and owners. You then spend Sunday deleting those guesses.

This article builds a tiny assumption gate. You feed an issue. You get facts, unknowns, and a pass or fail. You skip dashboards, vector stores, and multi-agent graphs.

What you will ship tonight

You will ship a stdin tool in Python. It extracts claimed nouns from the issue. It asks a model for a plan only after that list exists.

The tool rejects any plan that introduces new systems. It prints a JSON report you can paste into a PR. It runs without a database.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. If you need free model access and a free server for this weekend check, MonkeyCode is one place to run it. You can keep the same script on your laptop either way.

Scope you will cut on purpose

You will not call GitHub. You will not store history. You will not rank models.

You will not add embeddings. You will not add a web UI. You will not chain tools.

Those cuts keep the demo honest. A weekend agent dies from extra moving parts. You want a gate, not a platform.

Decision table before you write code

Use this table before you add any feature.

Idea	Keep this weekend?	Why
Stdin issue text	Yes	You already have the file.
Fact list from the issue	Yes	The gate needs ground truth.
Unknowns list	Yes	This is the actual product.
Plan JSON from a model	Yes	You still want a draft.
Invented-system scanner	Yes	This is the fail path.
GitHub API	No	Auth and rate limits steal hours.
Vector database	No	One issue does not need retrieval.
Multi-agent debate	No	Two models invent twice as much.
Pretty dashboard	No	JSON in the terminal is enough.

If a row says no, you delete that ticket. You do not park it in a backlog. Weekend scope is a knife, not a parking lot.

Step 1: Freeze the contract

Create assumption_gate.py. Keep the contract tiny and strict. The script must print JSON and an exit code.

#!/usr/bin/env python3
"""Reject AI plans that invent unstated systems."""

from __future__ import annotations

import json
import os
import re
import sys
from pathlib import Path
from typing import Any

STOP = {
    "a", "an", "the", "and", "or", "to", "of", "in", "on",
    "for", "with", "we", "you", "it", "this", "that",
}

SYSTEM_HINTS = {
    "redis", "kafka", "rabbitmq", "postgres", "mysql", "mongo",
    "s3", "sqs", "lambda", "kubernetes", "auth0", "okta",
    "elasticsearch", "opensearch", "graphql", "grpc",
}


def load_issue(path: str) -> str:
    text = Path(path).read_text(encoding="utf-8")
    if len(text.strip()) < 40:
        raise SystemExit("issue file is too short to gate")
    return text

You now have a hard floor on input size. Short prompts invite fiction. The gate should refuse thin issues early.

Step 2: Pull facts without a model

You extract candidate systems with boring regex. This list is your ground truth. The model may not expand it.

def tokenize(text: str) -> set[str]:
    words = re.findall(r"[A-Za-z][A-Za-z0-9+_.-]{1,}", text.lower())
    return {w for w in words if w not in STOP}


def stated_systems(text: str) -> set[str]:
    tokens = tokenize(text)
    found = {name for name in SYSTEM_HINTS if name in tokens}
    # Keep explicit TitleCase services from the issue only.
    titled = re.findall(r"\b([A-Z][A-Za-z0-9]+(?:Service|Queue|Store|API))\b", text)
    found.update(name.lower() for name in titled)
    return found

This extractor is deliberately dumb. Dumb is a feature here. You want recall of named systems, not creative inference.

Step 3: Define the plan schema

You force the model into three lists. Plans, facts, and unknowns must stay separate. Mixing them is how Kafka appears.

SCHEMA = {
    "type": "object",
    "required": ["facts", "unknowns", "steps", "systems"],
    "properties": {
        "facts": {"type": "array", "items": {"type": "string"}},
        "unknowns": {"type": "array", "items": {"type": "string"}},
        "steps": {"type": "array", "items": {"type": "string"}},
        "systems": {"type": "array", "items": {"type": "string"}},
    },
}

PROMPT = """You write an implementation plan.
Use only systems named in the issue.
If a system is missing, put a question in unknowns.
Never invent queues, databases, or vendors.
Return JSON with keys facts, unknowns, steps, systems.
ISSUE:
{issue}
"""

You should paste that schema into your notes. The gate scores systems against the issue. unknowns is the success path, not a failure.

Step 4: Add a local mock so the demo runs

You may lack an API key tonight. The mock still proves the gate. It invents Kafka on purpose so you see a fail.

def mock_plan(issue: str) -> dict[str, Any]:
    return {
        "facts": ["The issue asks for a faster digest email."],
        "unknowns": [],
        "steps": [
            "Add a Kafka topic for digest events.",
            "Write a worker that sends email.",
        ],
        "systems": ["kafka", "email"],
    }

Run the mock first. You want a red result before any network call. A green-only demo teaches nothing.

Step 5: Optional live call, no secrets in git

Keep the live path optional and boring. Read the base URL from the environment. Never print the key.

def live_plan(issue: str) -> dict[str, Any]:
    import urllib.request

    url = os.environ.get("LLM_URL", "").rstrip("/")
    key = os.environ.get("LLM_KEY", "")
    model = os.environ.get("LLM_MODEL", "")
    if not url or not model:
        raise SystemExit("set LLM_URL and LLM_MODEL, or use --mock")

    payload = json.dumps({
        "model": model,
        "messages": [{"role": "user", "content": PROMPT.format(issue=issue)}],
        "temperature": 0,
    }).encode("utf-8")
    req = urllib.request.Request(
        url + "/chat/completions",
        data=payload,
        headers={"Content-Type": "application/json"},
    )
    if key:
        req.add_header("Authorization", "Bearer " + key)
    with urllib.request.urlopen(req, timeout=45) as resp:
        body = json.loads(resp.read().decode("utf-8"))
    content = body["choices"][0][message_key(body)]["content"]
    return json.loads(extract_json(content))


def message_key(body: dict[str, Any]) -> str:
    return "message"


def extract_json(text: str) -> str:
    start = text.find("{")
    end = text.rfind("}")
    if start < 0 or end < 0:
        raise ValueError("model did not return JSON")
    return text[start:end + 1]

You still own the URL and model name. This article will not invent product model names. Point the env vars at whatever endpoint you already trust.

Step 6: Score invented systems

The scorer is the whole product. Compare plan systems to stated systems. Unknowns do not fail the run. Inventions do.

def score(issue: str, plan: dict[str, Any]) -> dict[str, Any]:
    allowed = stated_systems(issue)
    claimed = {s.lower().strip() for s in plan.get("systems", [])}
    invented = sorted(s for s in claimed if s and s not in allowed and s not in {"email", "http"})
    unknowns = [u for u in plan.get("unknowns", []) if str(u).strip()]
    ok = not invented
    return {
        "pass": ok,
        "allowed_systems": sorted(allowed),
        "plan_systems": sorted(claimed),
        "invented_systems": invented,
        "unknowns": unknowns,
        "steps": plan.get("steps", []),
        "facts": plan.get("facts", []),
    }

Email and HTTP stay on a tiny allowlist. Almost every issue implies them. Kafka does not get that courtesy.

Step 7: Wire the command

Finish with a small CLI. Exit 1 on invented systems. Exit 0 when the plan stays inside the issue.

def main() -> None:
    if len(sys.argv) < 2:
        raise SystemExit("usage: assumption_gate.py ISSUE.md [--mock]")
    issue = load_issue(sys.argv[1])
    use_mock = "--mock" in sys.argv[2:]
    plan = mock_plan(issue) if use_mock else live_plan(issue)
    report = score(issue, plan)
    json.dump(report, sys.stdout, indent=2)
    sys.stdout.write("\n")
    raise SystemExit(0 if report["pass"] else 1)


if __name__ == "__main__":
    main()

Save a sample issue next to the script. Keep it ugly and incomplete. Perfect specs hide the bug you are hunting.

# Digest email is late

Users wait until noon for the daily digest.
We already send mail from `mailer.py`.
Please make the existing job faster.
No new vendors.

Step 8: Run the red path, then the live path

chmod +x assumption_gate.py
python3 assumption_gate.py sample_issue.md --mock; echo exit:$?

You should see kafka under invented_systems. The process should exit 1. That is the demo working.

Then try a live model only if you already have an endpoint.

export LLM_URL="http://127.0.0.1:8080/v1"
export LLM_MODEL="local-or-hosted-model"
python3 assumption_gate.py sample_issue.md; echo exit:$?

A good live result lists unknowns instead of vendors. "What is the current job runtime?" is a win. "Add Redis" is a fail.

What you skipped, and why it matters

You skipped a second agent that critiques the first. Debate often adds more invented systems. One strict scorer beats two polite liars.

You skipped issue fetch from GitHub. Tokens, permissions, and pagination eat the weekend. A pasted markdown file is enough evidence.

You skipped a database for plan history. History is tempting and useless tonight. You need one honest report, not analytics.

Limitations you should say out loud

The noun list will miss odd product names. Teams invent unique service titles. Extend SYSTEM_HINTS when your repo uses them.

The JSON parse is brittle. Models still wrap objects in markdown. extract_json is a seatbelt, not a parser library.

The allowlist can hide real scope creep. "Email" might mean a new vendor. Read the steps, not only the score.

This gate does not measure code quality. It only blocks unstated infrastructure. You still review the steps as a human.

Who should not use this

Do not use this on regulated production agents. You need evals, logs, and an owner. A weekend script is not that layer.

Do not use this when the issue is a research spike. Exploration needs guesses. The gate is for implementation plans.

Do not use this if you cannot name current systems. The extractor needs words in the issue. Empty context makes every plan look invented.

A short checklist for Monday

Paste the real issue into sample_issue.md.
Run --mock and confirm a red Kafka fail.
Run a live model with temperature zero.
Treat unknowns as tickets, not as shame.
Delete any step that names a new system.
Ship the smallest change inside the repo you have.

You now have a working demo with a brutal scope cut. The agent may still be wrong on details. It is much less free to invent a platform.

Keep the script in the repo root. Run it before you accept any AI plan. That habit is the whole weekend win.

Stop the Extra Database: A Weekend Constraint Card for AI Plans

Riley Zhang — Fri, 04 Sep 2026 06:22:16 +0000

You sit down on Saturday with two free hours.
You want a tiny digest of failed CI logs.
A chat window is already open beside your editor.

You paste the idea and wait for a plan.
The reply looks complete and very confident.
Then you notice Redis and a worker pool.

You asked for a script, not a platform.
The model assumed scale you do not have.
Your Saturday is already half gone.

The problem you are actually solving

AI plans invent architecture you will not run.
They add queues, caches, and extra databases.
They treat a weekend toy like a funded product.

You do not need a bigger model for this.
You need a gate that fails before you code.
The gate should live in your repo as files.

This recipe is a proposed weekend workflow you can copy.
Run the examples on your machine before you trust them.
Do not treat the sample plans as production advice.

What you will ship by Sunday

You will write one JSON constraint card.
You will write a small Python checker script.
You will keep two fixture plans next to it.

The checker prints PASS or FAIL with reasons.
You run it before any implementation starts.
That is the whole working demo for this weekend.

What you will cut on purpose

Skip the web UI. Skip the Slack bot.
Skip GitHub comments and auto-opened issues.
Skip agents that rewrite the plan in a loop.

Skip Kubernetes. Skip a second database.
Skip paid search and paid embedding APIs.
If a step needs a credit card, cut it.

1. Write the constraint card first

Create a folder named plan-gate.
Put a file named card.json inside it.
Keep every rule short enough to read aloud.

{
  "project": "ci-log-digest",
  "goal": "Summarize one failed CI log into five bullets",
  "max_services": 1,
  "allowed_storage": ["sqlite", "local files"],
  "paid_apis": false,
  "forbidden": [
    "redis",
    "kafka",
    "rabbitmq",
    "kubernetes",
    "elasticsearch",
    "microservices",
    "second database",
    "worker pool"
  ],
  "required_phrases": ["single process", "local files"]
}

Read that card out loud once.
If a line feels like theater, delete it.
A useful card is boring and short.

2. Save one bad plan and one good plan

Save this as fixtures/bad_plan.txt.
It should look like a typical chat dump.

Build a CI digest platform with three microservices.
Use Redis for job state and Kafka for log streams.
Add a worker pool and a second database for archives.
Deploy on Kubernetes with an autoscaling API gateway.

Save this as fixtures/good_plan.txt.
It should match the weekend goal only.

Build a single process CLI named cidigest.
Read one log file from local files.
Write five bullets to stdout.
Store an optional sqlite cache of prior runs.
No extra services and no paid APIs.

The bad plan is inflated on purpose.
The good plan names one process and files.
Your checker should split them without mercy.

3. Write the checker in plain Python

Save this as check_plan.py.
It uses only the Python standard library.
Label it as an example until you run it.

#!/usr/bin/env python3
"""Fail AI plans that invent extra architecture."""

from __future__ import annotations

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


def load_card(path: Path) -> dict:
    data = json.loads(path.read_text(encoding="utf-8"))
    required = {
        "project",
        "goal",
        "max_services",
        "allowed_storage",
        "paid_apis",
        "forbidden",
        "required_phrases",
    }
    missing = required - set(data)
    if missing:
        raise ValueError(f"card missing keys: {sorted(missing)}")
    return data


def tokenize(text: str) -> str:
    return " " + re.sub(r"\s+", " ", text.lower()) + " "


def count_service_mentions(text: str) -> int:
    labels = [
        "service",
        "microservice",
        "worker",
        "queue",
        "cluster",
        "gateway",
    ]
    blob = tokenize(text)
    return sum(blob.count(" " + word) for word in labels)


def check_plan(card: dict, plan: str) -> list[str]:
    blob = tokenize(plan)
    violations: list[str] = []

    for token in card["forbidden"]:
        needle = " " + token.lower() + " "
        if needle in blob:
            violations.append(f"forbidden architecture: {token}")

    for phrase in card["required_phrases"]:
        needle = " " + phrase.lower() + " "
        if needle not in blob:
            violations.append(f"missing required phrase: {phrase}")

    if card["paid_apis"] is False:
        paid_hints = ["stripe key", "paid api", "credit card", "prod account"]
        for hint in paid_hints:
            if " " + hint + " " in blob:
                violations.append(f"paid API hint: {hint}")

    service_hits = count_service_mentions(plan)
    if service_hits > card["max_services"]:
        violations.append(
            f"service mentions {service_hits} exceed max_services {card['max_services']}"
        )

    storage_hits = [
        name
        for name in card["allowed_storage"]
        if " " + name.lower() + " " in blob
    ]
    if not storage_hits:
        allowed = ", ".join(card["allowed_storage"])
        violations.append(f"no allowed storage named ({allowed})")

    return violations


def main() -> int:
    parser = argparse.ArgumentParser(description="Reject inflated AI plans")
    parser.add_argument("--card", required=True, type=Path)
    parser.add_argument("--plan", required=True, type=Path)
    args = parser.parse_args()

    card = load_card(args.card)
    plan = args.plan.read_text(encoding="utf-8")
    violations = check_plan(card, plan)

    print(f"project: {card['project']}")
    print(f"goal: {card['goal']}")
    print(f"plan: {args.plan}")

    if violations:
        print("result: FAIL")
        for item in violations:
            print(f"- {item}")
        return 1

    print("result: PASS")
    print("plan stays inside the weekend card")
    return 0


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

4. Run the demo until the fixtures split

Use these commands from plan-gate.
Do not skip the exit codes.

python3 check_plan.py --card card.json --plan fixtures/bad_plan.txt
echo $?
python3 check_plan.py --card card.json --plan fixtures/good_plan.txt
echo $?

The first command should exit with status 1.
You should see forbidden architecture lines.
The second command should exit with status 0.

If both pass, your fixtures are too soft.
Tighten the forbidden list and run again.
The card is the product, not the model.

5. Use this table when a plan feels almost fine

Print the table beside your editor window.
If you argue with a FAIL, the card is winning.
That argument is the whole point.

Signal in the plan	Weekend action	Why you cut it
Extra cache or broker	FAIL	You will not operate it
Second database	FAIL	One sqlite file is enough
Kubernetes or a cluster	FAIL	Saturday has no ops budget
Paid API or usage keys	FAIL	Free-tier surprises add up
Single process plus files	PASS	You can finish and demo
"We can add Redis later"	FAIL	Later becomes this weekend

Treat "later" as a FAIL this weekend.
Later is how a script becomes a platform.
Write the cut in the card, not in chat.

Where a free model still helps

The checker does not write the plan.
A model can draft the first version.
You then force a rewrite against the card.

Paste the FAIL list back into the chat.
Ask for a plan that clears every line.
Run the checker until it prints PASS.

You can do that loop on your laptop.
You can also park the checker on a free server.
Keep the card in git either way.

You may want a hosted model for rewrites.
MonkeyCode offers free model access and a free server.
Disclosure: This article was prepared as part of MonkeyCode's product outreach.
Use them only to run the same script.
Do not let the host invent a wider stack.

Stay inside the card when the model replies.
If it adds a queue, fail the plan again.
Free hosting still does not change the rules.

6. Follow this numbered weekend schedule

Write card.json before you open a chat.
Save one bad plan and one good plan.
Run check_plan.py until the fixtures split.
Draft your real idea with a free model.
Paste the draft through the checker.
Rewrite until you get PASS.
Freeze the PASS plan in the repo.
Stop. Do not code the app yet.

Do not add a dashboard in step eight.
The working demo is PASS versus FAIL.
Ship the cut, not the imaginary platform.

Honest limits

This checker is a keyword gate.
It will miss clever synonyms.
It will also flag quoted refusals.

"We will not use Redis" can still FAIL.
Add tests for your own phrasing later.
Do not pretend this is formal architecture review.

It will not measure token cost.
It will not review security.
It will not deploy anything.

False confidence is the remaining risk.
A PASS plan can still be technically wrong.
Read the plan after the script smiles.

Who should not use this

Skip this if you already have an architecture board.
Skip this for medical, payroll, or identity systems.
Skip this if several teams share on-call.

Skip this if you need streaming pipelines today.
A weekend digest is not that job.
Use a real design review instead.

What you skipped, written down

You skipped agents that keep calling tools.
You skipped MCP servers and browser drivers.
You skipped a pretty report in HTML.

You skipped auto-commits to a public repo.
You skipped "just one more microservice."
Write those skips into the project README.

The skip list protects Monday-you.
Monday-you will want to add Redis.
Show Monday-you the FAIL output from Saturday.

Close

You started with two hours and a chat window.
You end with a card, a checker, and a PASS plan.
The extra database never makes it into git.

Keep the card next to the code.
Run the checker before every generation.
That is the weekend, and it is enough.

Need a hosted box for that same loop?
Try the free model and free server path.
Leave the constraint card in version control.

DEV Community: Riley Zhang

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

Why "just add an agent loop" ruins the weekend

1. Write the job in one sentence

2. Score every feature, then cut

3. Prove the endpoint before you build anything

4. Measure the spread, not one lucky call

5. Ship the smallest surface that survives a reboot

6. Where free access actually changed my plan

7. What I skipped on purpose

8. Limits you should assume

9. Who should not use this workflow

Takeaways

Weekend Build Log: The Timeout Is the Product

The Saturday trap

Cut the job to one verb

Freeze three files first

Put a kill switch on the process

Write a receipt after every run

Make the demo one command

Decision table for the next hour

When a free model is actually useful

What you skip on purpose

A five-step Saturday checklist

Limitations

Who should not use this

Close the weekend

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

Why loops eat Saturday

Freeze the command before code

The one-pass rule

Four files, then stop

Step 1: Fail the demo on purpose

Step 2: Ban loop markers

Step 3: One prompt, then hands off

Step 4: Put the pass somewhere you can close

Step 5: Ship a boring notes.py

The cut list you publish

Decision table

Failure analysis

Who should not use this

Monday morning

Weekend Build Log: Stdout Is the Demo, Not a UI

The Saturday scene

What you actually need

Freeze a stdout contract first

Numbered build, not a brainstorm

Step 1: commit the freeze

Step 2: add a failing stdout test

Step 3: write the smallest script

Step 4: one Makefile target

Step 5: run it like a demo

When stdout gets dirty

Step 6: name what you refused

A Saturday decision table

Where a coding agent still helps

Limitations

Who should not use this cut

Close the laptop

Weekend Build Log: One Curl Demo, Zero Extra Surfaces

The scene that keeps repeating

Freeze the demo, not the whole repo

Step 1: Write the curl before the server

Step 2: Pin a scope file the agent must honor

Step 3: Allow one tiny process, nothing else

Step 4: Add a checker the agent cannot charm

Step 5: Reject extra surfaces with a table

What you skip on purpose

Where a free model loop fits

Limitations

Who should not use this

Close the laptop with a replay

Sunday Demo Gate: Keep a Skip Log or Overbuild

The Saturday overbuild scene

Artifact: the weekend one-path card

Step 1: freeze the path in one sentence

Step 2: write the skip log before code

Step 3: define working demo as a command

Step 4: give the agent a hard stop rule

Step 5: keep the laptop free with a remote run

Step 5: Ship a boring `notes.py`