DEV Community: Charlie Hu

Weekend Build Log: A Clock-Gated Cut List for a One-Weekend Release-Notes Bot

Charlie Hu — Tue, 27 Oct 2026 13:27:22 +0000

A weekend side project fails in a predictable way: not from bad code, but from a scope list that grows faster than the clock shrinks. The fix in this build log is mechanical. Every task carries one of three states — keep, cut, or fixture — and a small script refuses to let the kept work exceed the hours actually left before the demo. The demo path stays green because a smoke test runs the whole pipeline against an injected fake model reply, with no network involved.

This is a build log for a release-notes bot: it reads git log between two tags, asks a model to write one bullet per meaningful commit, and posts the result to a webhook. The interesting part is not the bot. It is the triage loop that made the bot demoable in two days.

Why a checklist loses to a clock

A feature checklist is a wish list. It has no opinion about time.

A clock gate has one job: compare planned hours against remaining hours and exit non-zero when the plan is a lie. That exit code is the whole value. It fires on Saturday afternoon, when the temptation to add "just one more" surface is strongest, and it fires again on Sunday when the same task list is suddenly 40% too big.

Three rules make it work:

Only keep tasks count toward the hour budget. cut and fixture are free.
A task is on the demo path or it is not. Demo-path tasks must be keep; nothing else gets a keep.
fixture means "the demo shows this, but a static value stands in for the real implementation". It is a promise, not a shortcut — and it gets deleted or labeled before anyone else sees it.

The artifact: a cut list with three states

The ledger is a tab-separated file, cutlist.tsv, checked into the repo next to the code. It is boring on purpose.

id	task	state	est_h	demo_path
T1	git-log to prompt builder	keep	1.5	yes
T2	model transport + one retry	keep	1.0	yes
T3	webhook server with `/healthz`	keep	1.0	yes
T4	markdown renderer for the changelog widget	keep	1.5	yes
T5	history store in sqlite	cut	2.0	no
T6	per-repo auth tokens	fixture	2.5	no
T7	settings page	cut	3.0	no
T8	Slack block formatting	cut	1.5	no

The kept column totals five hours. The cut column totals nine. That ratio is the real output of Saturday morning, and it is the reason the demo exists at all.

State rules that survive contact with a real weekend

keep requires an estimated hour count. Unknown estimates are treated as 3h, which is a lie that hurts.
cut means the code path does not exist yet. Not disabled, not commented out — absent.
fixture requires a named file under fixtures/ so the stand-in is visible in review.

`checkpoint.py`: the gate that refuses work

Standard library only. It reads the ledger, sums the kept hours, and compares against wall-clock time remaining before the rehearsal slot.

#!/usr/bin/env python3
"""checkpoint.py - refuse to keep more scope than the clock allows."""
import csv
import sys
from datetime import datetime

HARD_STOP = datetime.fromisoformat("2026-10-25T17:30:00")  # rehearsal starts
NOW = datetime.now()


def load(path="cutlist.tsv"):
    with open(path, newline="") as f:
        return list(csv.DictReader(f, delimiter="\t"))


def hours_left(now=NOW, stop=HARD_STOP):
    return max(0.0, (stop - now).total_seconds() / 3600)


def report(rows, now=NOW):
    kept = [r for r in rows if r["state"] == "keep"]
    planned = sum(float(r["est_h"]) for r in kept)
    left = hours_left(now)
    print(f"kept={len(kept)} planned_h={planned:.1f} left_h={left:.1f}")
    for r in kept:
        print(f"  KEEP    {r['id']:<4} {float(r['est_h']):>4.1f}h  {r['task']}")
    for r in rows:
        if r["state"] != "keep":
            print(f"  {r['state'].upper():<7} {r['id']:<4} {float(r['est_h']):>4.1f}h  {r['task']}")
    return planned <= left


if __name__ == "__main__":
    sys.exit(0 if report(load()) else 1)

Example output on Sunday morning, when the plan is already too big:

$ python checkpoint.py; echo "exit=$?"
kept=4 planned_h=5.0 left_h=3.2
  KEEP    T1    1.5h  git-log to prompt builder
  KEEP    T2    1.0h  model transport + one retry
  KEEP    T3    1.0h  webhook server with /healthz
  KEEP    T4    1.5h  markdown renderer for the changelog widget
  CUT     T5    2.0h  history store in sqlite
exit=1

Exit code 1 is the useful signal. The response is not "work faster"; it is to demote one keep row to cut or fixture and re-run until the exit code is 0. In this log, T4 dropped to fixture — the demo renders plain bullets from a fixture file and the widget formatting stays out of scope.

The demo-path smoke test, with the model faked

A demo breaks when a hidden network call is slow, or when the output shape drifts. Both are testable without a network. The pipeline takes an injected transport, so the smoke test swaps in a deterministic string.

# notes.py
import re
from dataclasses import dataclass

NOISE = re.compile(r"^(chore|test|ci)(\(|:)")


@dataclass
class Notes:
    bullets: list[str]
    body: str


def filter_commits(commits):
    return [c for c in commits if not NOISE.match(c["subject"])]


def build_prompt(commits):
    lines = "\n".join(f"- {c['subject']}" for c in commits)
    return "One markdown bullet per commit. No SHAs. Max 110 chars.\n" + lines


def draft_notes(commits, transport):
    kept = filter_commits(commits)
    raw = transport(build_prompt(kept))  # network or fixture, caller decides
    bullets = [l.lstrip("- ").strip() for l in raw.splitlines() if l.strip()]
    return Notes(bullets=bullets, body="\n".join(f"- {b}" for b in bullets))

# smoke_demo.py
import sys
from notes import draft_notes, filter_commits

COMMITS = [
    {"sha": "a1b2c3d", "subject": "feat: add /webhook endpoint"},
    {"sha": "b2c3d4e", "subject": "chore: bump deps"},
    {"sha": "c3d4e5f", "subject": "fix: handle empty tag range"},
]


def fake_transport(prompt: str) -> str:
    return "- add /webhook endpoint\n- handle empty tag range\n"


def main() -> int:
    out = draft_notes(COMMITS, transport=fake_transport)
    expected = len(filter_commits(COMMITS))
    failures = []
    if len(out.bullets) != expected:
        failures.append(f"bullets={len(out.bullets)} expected={expected}")
    if any("chore" in b for b in out.bullets):
        failures.append("noise commit leaked into public notes")
    if any(len(b) > 110 for b in out.bullets):
        failures.append("bullet too long for the widget")
    if "a1b2c3d" in out.body:
        failures.append("raw sha leaked into public notes")
    for f in failures:
        print("FAIL", f)
    print("PASS demo path" if not failures else "demo path broken")
    return 1 if failures else 0


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

The SHA leak check is the one that earned its place. Model-written notes happily inline a commit hash when the prompt does not forbid it, and a hash in a public changelog is a small but real information leak. The test now blocks it before rehearsal, not after.

Wiring the real transport once

The production path calls a model with the same signature. This is where the free model access matters: the transport can be pointed at a free endpoint during the weekend and swapped later without touching draft_notes. MonkeyCode's free model access and free server option are operator-supplied availability claims; no quota, model list, or latency figure is asserted here, and the scripts above do not depend on any of them.

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

# transport_http.py - keep the shape, swap the endpoint
import json
import urllib.request


def http_transport(prompt: str, url: str, token: str, timeout: float = 20.0) -> str:
    body = json.dumps({"prompt": prompt}).encode()
    req = urllib.request.Request(
        url, data=body,
        headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"},
    )
    with urllib.request.urlopen(req, timeout=timeout) as resp:
        return json.loads(resp.read())["text"]

Two rules keep the injection honest. The transport is the only place that knows about the network, and the timeout is shorter than the shortest acceptable demo pause. If the call exceeds it, the pipeline falls back to the last fixture — visibly, with a banner in the output.

Preflight before the demo, on a free server

A free server option makes the deployment step short, but it does not make it instant. The preflight is three commands, run before rehearsal, not during it.

BASE="https://$HOST"
curl -sS -m 5 "$BASE/healthz" || echo "cold start - retry in 30s"
curl -sS -m 20 -X POST "$BASE/webhook" \
  -H 'Content-Type: application/json' \
  -d '{"range":"v0.1..v0.2"}' | head -c 400
python smoke_demo.py && echo "demo path green"

If /healthz times out and the second call succeeds, the service was cold and the fix is a warm-up ping two minutes before the demo, not a rewrite. That distinction is worth writing down once, because it saves twenty minutes of panic later.

What got skipped, and why that was the point

History store (T5). Cut. Re-running the demo means re-posting the same range; a viewer cannot tell, and sqlite would have eaten two hours.
Per-repo auth (T6). Fixture. A single static token outside the repo is enough for one demo, and the fixture is labeled in the README.
Settings page (T7). Cut. Configuration lives in environment variables.
Slack formatting (T8). Cut. Plain markdown bullets render fine in the widget used for the demo.

The skipped list is nine hours of work. None of it appears in the demo, and all of it appears in the "next" section of the README, which is the honest place for it.

Limitations and known failure modes

Clock gates assume one developer on one machine. Timezone drift or a shared laptop silently moves the deadline; the stop time is hardcoded and should be an environment variable in any shared setup.
Fixture mode can lie. A fixture that returns perfect output makes a broken pipeline look healthy. The smoke test catches shape drift, not prompt quality.
Free tiers change. The preflight exists because availability and cold-start behavior are not contractual. Treat any free server as a demo venue, not an uptime guarantee.
Model output is not stable. The bullet-count assertion will fail on a chatty reply; the retry in T2 exists for that, and the fixture fallback covers the rest.
No cost or performance claims are made here. Nothing in this log was benchmarked, and the scripts do not measure tokens, latency percentiles, or throughput.

Who should not use this approach

Skip the clock gate if the project has an external deadline set by someone else, since the script would only restate pressure the team already feels. Skip fixture fallbacks entirely for anything user-facing with real data, where a stand-in value is a correctness bug rather than a demo choice. And skip this whole loop for production services with an SLA — a two-day build log is not a substitute for a release process.

Reproduce it in six steps

Create cutlist.tsv with four columns plus est_h and demo_path, and fill it before writing any code.
Run python checkpoint.py until it exits 0. Demote rows instead of extending the deadline.
Write the pipeline with an injected transport and no network calls in the core module.
Add smoke_demo.py with the SHA-leak and bullet-count assertions, then run it before every deploy.
Deploy the webhook, then run the three-command preflight twice: once cold, once warm.
Move every fixture row into a "next" section of the README before anyone else reads the repo.

If the ledger gets reused on another weekend build, the free model access and free server option are enough to run that loop end to end without a billing decision getting in the way of the first commit.

Reserve, Then Reconcile: A Token Ledger That Stops a Free-Tier Side Project at the Cap

Charlie Hu — Mon, 26 Oct 2026 11:58:52 +0000

A free throughput allowance behaves like a budget only when a program refuses to spend past it. Everything else is a dashboard that reports the overspend after the fact.

This build log covers a one-weekend side project: a reservation-based token ledger, roughly 90 lines of Python over SQLite, wrapped around every model call. Two findings came out of the exercise — one about concurrent retries, one about the free server that hosts the demo.

What shipped, and what was cut

A weekend is enough for a guard that fails closed. It is not enough for a platform.

Shipped:

ledger.py — a reserve/settle/sweep API over a single SQLite table.
guard.py — a wrapper that reserves before a request and reconciles after it.
Three pytest cases, including a thread-based overspend test.
smoke.sh — five wake-ups against the deployed demo, reporting time-to-first-200 and whether the ledger survived.

Skipped on purpose:

Authentication and multi-tenant caps. One operator, one cap, one file.
Dollar pricing. Tokens are counted; currency conversion is a separate problem that changes weekly.
Dashboards. The sqlite3 CLI answered every question asked that weekend.
Distributed caps. One host, one ledger. Cross-machine coordination was deferred, not half-built.

The core idea: charge the estimate, reconcile with the actual

A reservation system needs one row per call, not two. Each row starts charged at its estimate and is rewritten to the actual count when the response lands.

CREATE TABLE IF NOT EXISTS ledger (
    id       TEXT PRIMARY KEY,
    ts       REAL    NOT NULL,
    estimate INTEGER NOT NULL,
    actual   INTEGER,            -- NULL means the call is still in flight
    note     TEXT    NOT NULL
);

The charged total is SUM(COALESCE(actual, estimate)). In-flight calls therefore count against the cap immediately, which is the entire point: a retry storm cannot slip through a window between request and billing.

# ledger.py
import os, sqlite3, time, uuid
from pathlib import Path

DB_PATH = Path(os.environ.get("LEDGER_DB", "ledger.sqlite3"))

DDL = """
CREATE TABLE IF NOT EXISTS ledger (
    id TEXT PRIMARY KEY, ts REAL NOT NULL,
    estimate INTEGER NOT NULL, actual INTEGER, note TEXT NOT NULL
);
"""

def connect(path: Path = DB_PATH) -> sqlite3.Connection:
    conn = sqlite3.connect(path, timeout=5, isolation_level=None)
    conn.execute("PRAGMA journal_mode=WAL")
    conn.execute("PRAGMA busy_timeout=5000")
    conn.execute(DDL)
    return conn

def charged(conn: sqlite3.Connection) -> int:
    return conn.execute(
        "SELECT COALESCE(SUM(COALESCE(actual, estimate)), 0) FROM ledger"
    ).fetchone()[0]

def reserve(conn, cap: int, estimate: int, note: str) -> str:
    conn.execute("BEGIN IMMEDIATE")          # serialise writers
    try:
        used = charged(conn)
        if used + estimate > cap:
            raise RuntimeError(f"budget: {used + estimate} > cap {cap}")
        rid = uuid.uuid4().hex
        conn.execute(
            "INSERT INTO ledger VALUES (?,?,?,NULL,?)",
            (rid, time.time(), estimate, note),
        )
        conn.execute("COMMIT")
        return rid
    except Exception:
        conn.execute("ROLLBACK")
        raise

def settle(conn, rid: str, actual: int) -> None:
    conn.execute(
        "UPDATE ledger SET actual = ? WHERE id = ? AND actual IS NULL",
        (actual, rid),
    )

def sweep(conn, older_than_s: float = 900) -> int:
    """Crashed reservations are charged at their estimate, never forgotten."""
    cur = conn.execute(
        "UPDATE ledger SET actual = estimate WHERE actual IS NULL AND ts < ?",
        (time.time() - older_than_s,),
    )
    return cur.rowcount

sweep is the least elegant function in the file and the most important one. A process that dies mid-call leaves an in-flight row forever; sweeping charges the estimate so the cap stays conservative across restarts.

The guard wrapper and the timeout rule

The wrapper reserves first, then calls. The hard part is not the happy path — it is deciding what an exception costs.

# guard.py
TIMEOUT_IS_CHARGED = True   # conservative default, see the table below

def guarded(client, prompt: str, cap: int, estimate: int):
    conn = connect()
    sweep(conn)
    rid = reserve(conn, cap, estimate, note=prompt[:60])
    try:
        resp = client.complete(prompt, max_tokens=estimate)
    except TimeoutError:
        settle(conn, rid, estimate if TIMEOUT_IS_CHARGED else 0)
        raise
    except ConnectionError:
        settle(conn, rid, 0)        # request never left the process
        raise
    settle(conn, rid, resp.usage.total_tokens)
    return resp

Failure	Did the provider charge?	Ledger default
Connection refused / DNS failure	No	Settle at 0
Timeout after the request body was sent	Unknown	Settle at the estimate
HTTP 4xx before generation starts	Usually no	Settle at 0
2xx with truncated usage data	Yes	Settle at the estimate

The timeout row is the honest one. No client can know whether a remote generator billed tokens for a request that died in transit, so the conservative choice is to assume it did. Overcharging a local ledger costs headroom; undercharging costs the cap.

Pair max_tokens = estimate with the reservation. That bound is what keeps the gap between estimate and actual from turning into a silent overshoot.

Tests that a dashboard cannot replace

Three cases cover the behaviour that matters. Each worker thread opens its own connection, because the locking is part of what is being tested.

# test_ledger.py
import pytest, threading
from ledger import connect, reserve, settle, charged

def test_refuses_over_cap(tmp_path):
    conn = connect(tmp_path / "l.db")
    reserve(conn, cap=1000, estimate=600, note="a")
    with pytest.raises(RuntimeError):
        reserve(conn, cap=1000, estimate=600, note="b")

def test_settle_releases_the_difference(tmp_path):
    conn = connect(tmp_path / "l.db")
    rid = reserve(conn, cap=1000, estimate=800, note="a")
    settle(conn, rid, 120)
    assert charged(conn) == 120
    reserve(conn, cap=1000, estimate=800, note="b")   # now it fits

def test_concurrent_reservations_do_not_overspend(tmp_path):
    db = tmp_path / "l.db"
    ok = []

    def worker(i):
        conn = connect(db)                  # own connection, shared file
        try:
            reserve(conn, cap=1000, estimate=300, note=str(i))
            ok.append(i)
        except RuntimeError:
            pass

    threads = [threading.Thread(target=worker, args=(i,)) for i in range(10)]
    [t.start() for t in threads]
    [t.join() for t in threads]
    assert len(ok) == 3                     # 3 x 300 <= 1000, the 4th is refused

Run with python -m pytest -q test_ledger.py. The third test is the one that fails on a naive SELECT-then-INSERT implementation: without BEGIN IMMEDIATE, several threads read the same total and all reserve.

Deploying to the free server: one smoke test, one uncomfortable finding

A cap that resets on redeploy is not a cap. That is precisely what the first deployment did.

#!/usr/bin/env bash
# smoke.sh — five wake-ups, 60 s apart, then a ledger survival check
set -u
URL="https://${DEMO_HOST}/health"

for i in $(seq 1 5); do
  sleep 60
  curl -s -o /dev/null -w "wake %{http_code} %{time_total}s\n" \
       --max-time 30 "$URL"
done

curl -s --max-time 30 "$URL" | tee /dev/stderr | grep -q '"ledger_rows"' \
  || echo "WARN: ledger_rows missing from health payload"

The health endpoint reports ledger_rows and charged, so the smoke test checks two things at once: whether the host wakes within the timeout, and whether the ledger was still there afterwards. Five wake-ups produce a spread, not a benchmark; a single cold-start number from one run says almost nothing.

The finding: after a redeploy, ledger_rows was back to 0. The default container filesystem is ephemeral, and a fresh instance had started with a fresh, empty cap. Two fixes exist — mount a volume and point LEDGER_DB at it, or accept a per-instance cap and document it loudly. The first costs a configuration line; the second costs trust in the number on the dashboard.

Choosing between three controls

Control	Catches	Misses	Effort
`max_tokens` per request	One runaway completion	Cumulative drift over hundreds of retries	Zero
Provider usage dashboard or alert	Eventual overspend	Tonight's batch job	Minutes, with lag
Reservation ledger (this)	Spend before it happens, including concurrent calls	Caps shared across machines without a shared DB	One file, one table

The three stack. max_tokens bounds a call, the ledger bounds a run, and the dashboard explains what happened yesterday. Anyone building a demo on a metered free tier benefits from all three; anyone calling a model once does not need the ledger at all.

Where the free tier actually fits

This particular project runs on MonkeyCode's free model access, which changes the ledger's unit: the cap is measured in tokens, not currency, so the numbers in the table above are directly comparable to the allowance itself. The free server option puts the demo and the ledger on the same host, which is exactly why the ephemeral-filesystem finding surfaced in a weekend rather than in week three.

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

The allowance quoted when the project started was on the order of ten million tokens, and the free server option was available then too. Both are availability claims rather than guarantees: free-tier terms and allowances change, so read the current project page before sizing a cap around a number from a blog post — this one included.

If the caps match the workload, the free tier is a reasonable place to run a demo of this size, and the ledger is worth keeping regardless of where the calls go.

Limitations and who should skip this

Single-node SQLite only. Two hosts need a shared store, typically Postgres, plus the same BEGIN IMMEDIATE discipline.
Estimates must be plausible. Set estimate well under actual usage and the cap leaks by the difference on every in-flight call; max_tokens = estimate closes that gap.
The sweep overcharges after a crash. Conservative by design, but it means the cap can shrink without any tokens being spent.
Tokens are not money. Any reconciliation against an invoice needs a price table this artifact does not have.
Skip it entirely if the provider already enforces hard pre-request caps, or if the project needs a real LLM gateway with routing, retries, and central accounting. A gateway does this better; this is a weekend's version of one.

The reusable part is the shape, not the code: reserve before spending, reconcile after, and make a crash cost something. Four columns and a lock are enough to turn an allowance into a limit that a program actually respects.

Weekend Build Log: Expiring Feature Flags That Cut Scope at Runtime

Charlie Hu — Tue, 20 Oct 2026 10:07:57 +0000

Weekend Build Log: Expiring Feature Flags That Cut Scope at Runtime

A scope cut that lives in a planning document survives roughly four hours into a weekend build. A cut that lives in the request path survives the whole demo. This build log wires an expiry timestamp into every feature flag, so an unfinished feature stops answering requests on its own — no 1 a.m. redeploy, no verbal promise to remember to disable it.

The demo is deliberately small: a text utility with three AI-backed features behind one free server instance. The constraint is the interesting part. Two days of calendar time, one process, and a model-call budget that should not be spent on a branch that is not finished.

The artifact below has four moving parts:

A frozen Feature record that carries expires_at and an estimated model_calls cost.
A FastAPI dependency that returns 503 with a fallback message once the clock passes.
A test that proves the expiry path without waiting for wall-clock time.
A pre-deploy guard that fails when a flag outlives the demo window.

Why planning cuts decay

A cut made on Saturday morning is a decision. A cut made on Sunday night is a negotiation with a tired person who wants the demo to look complete. The gap between those two states is where half-built features get flipped back on and quietly break the demo.

Expiry moves the decision out of the tired person's hands. The feature is not "off for now"; it is "off after 21:00 UTC on Sunday," and that fact is in source control.

Rule one: every feature carries an expiry

The registry stays boring on purpose. Frozen dataclasses, explicit UTC timestamps, and a cost estimate that the planner can read later.

# flags.py
from dataclasses import dataclass
from datetime import datetime, timezone
from typing import Optional

@dataclass(frozen=True)
class Feature:
    name: str
    expires_at: datetime          # UTC, hard stop
    fallback: Optional[str] = None
    model_calls: int = 1          # rough fan-out cost per request

    def open_now(self, now: Optional[datetime] = None) -> bool:
        return (now or datetime.now(timezone.utc)) < self.expires_at

DEMO_END = datetime(2026, 10, 25, 21, 0, tzinfo=timezone.utc)

FEATURES = {
    f.name: f
    for f in [
        Feature('summary', DEMO_END, model_calls=1),
        Feature('compare', DEMO_END, model_calls=3),
        Feature('rewrite', datetime(2026, 10, 24, 12, 0, tzinfo=timezone.utc),
                fallback='rewrite is off for this build', model_calls=1),
    ]
}

Two details matter more than they look. model_calls is an estimate, not a measurement, and it is only used to order what gets cut first. And open_now takes an injectable clock, which is what makes the test in rule three possible.

Rule two: expiry is enforced in the request path

A flag read only at startup is a config file with extra steps. The check has to run per request, so a container that started at noon still refuses work at midnight.

# api.py
from fastapi import APIRouter, Depends, HTTPException
from flags import FEATURES

router = APIRouter()

def require(name: str):
    def dependency():
        feature = FEATURES[name]
        if not feature.open_now():
            raise HTTPException(
                status_code=503,
                detail={'feature': name, 'fallback': feature.fallback},
            )
        return feature
    return dependency

@router.post('/api/summary')
def summary(_: object = Depends(require('summary'))):
    ...

503 is the honest status here. The route exists, the flag says no, and the client gets a fallback string it can render instead of a stack trace. Keeping the route mounted also means the frontend does not need a second code path for "feature missing."

Rule three: prove it with a test that never waits

The useful assertion is not "the flag is closed." It is "the flag is closed and the model was never called." A closed flag that still bills a request is the failure mode worth testing for.

# test_flags.py
from datetime import datetime, timezone
from fastapi.testclient import TestClient
from flags import FEATURES, Feature
import main

def test_expired_flag_returns_503_and_skips_the_model(monkeypatch):
    calls = []
    monkeypatch.setattr(main, 'call_model', lambda *a, **k: calls.append(1) or 'text')
    past = datetime(2026, 10, 20, 9, 0, tzinfo=timezone.utc)
    monkeypatch.setitem(FEATURES, 'summary', Feature('summary', past))

    client = TestClient(main.app)
    response = client.post('/api/summary', json={'text': 'hello'})

    assert response.status_code == 503
    assert response.json()['detail']['feature'] == 'summary'
    assert calls == []

Because require() reads FEATURES[name] at call time rather than import time, monkeypatch.setitem is enough. No sleeping, no frozen-clock dependency, no flaky test on a slow laptop.

Rule four: refuse to deploy flags that outlive the demo

Expiry only helps if it is checked before the code ships. A twenty-line script in the deploy path is cheaper than remembering.

# check_flags.py
import sys
from datetime import timedelta
from flags import FEATURES, DEMO_END

GRACE = timedelta(minutes=30)
bad = [f.name for f in FEATURES.values() if f.expires_at > DEMO_END + GRACE]

if bad:
    names = ', '.join(bad)
    print(f'FAIL: flags outlive the demo window: {names}')
    sys.exit(1)

print(f'OK: {len(FEATURES)} flags expire inside the window')

Run the whole loop locally in about a minute:

python -m venv .venv && source .venv/bin/activate
pip install fastapi uvicorn pytest httpx
python check_flags.py
uvicorn main:app --port 8000 &
curl -s -o /dev/null -w '%{http_code}\n' -X POST localhost:8000/api/summary \
  -H 'content-type: application/json' -d '{"text":"hello"}'

A 200 means the flag is open, 503 means the cut already happened, and check_flags.py failing means the cut was never scheduled.

The cut policy

Ordering the cuts is the part people skip. The table below is the rule used for this build; the order is what matters, not the specifics.

Tier	Feature shape	Action at cutoff
1	Fans out to N model calls per request	Expire first, hard `503`, no fallback copy
2	Single model call, partial UI	Expire mid-weekend, show fallback text
3	No model call, pure formatting	Keep, no expiry
4	Anything needing a schema change	Never scheduled

Tier 1 goes first because it is the only tier where a half-working feature can drain the request budget in minutes. Tier 3 has no marginal cost, so cutting it buys nothing.

Where the free server and free model access change the math

MonkeyCode offers free model access and a free server option, which is exactly the shape this harness assumes: one small process, outbound model calls, no control plane. The flags exist because model calls are the metered part. A route that fans out three calls per request is a different risk class from a route that formats text, and the registry should say so.

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

Two cautions before planning around any free tier. Free quotas, model lists, and instance terms change without notice, so confirm the current details on the project page rather than trusting a number from a blog post — including this one. And a free tier is not a reliability guarantee; the expiry design assumes the process can disappear at any moment, which is a useful assumption to hold even on paid infrastructure. If the demo shape fits, the free path is a reasonable place to run it before spending anything.

What got skipped

Streaming responses. The cut flag returns a complete 503; a half-streamed answer is a worse user experience than a clean refusal.
Per-user targeting. No percentage rollouts, no allowlists. One clock, one decision.
Flag persistence. Flags live in source, not a database. Changing one is a commit.
Retry and backoff on model calls. Out of scope for a two-day build, and the flag makes it unnecessary for the risky routes.
A metrics dashboard. The 503 count in the server log is the dashboard.

Limitations and who should not do this

Expiry in source code is not a feature-flag system. It has no audit log, no gradual rollout, no kill switch faster than a redeploy.

Teams with long-lived features should use a real flag service (Unleash, LaunchDarkly, or a database-backed equivalent) rather than timestamps in a dataclass.
Products where the feature must survive the weekend should not encode a hard stop at all; an expiry that has to be edited after launch is just a scheduled outage.
Anything multi-instance with cached config will see skewed behaviour, because each process reads its own copy of FEATURES.
Mid-request expiry is not handled. A request that starts at 20:59:59 completes; only the next one is refused.
Cost control is per-feature, not per-request. The model_calls field orders cuts; it does not cap spend.

Closing note

The reason this pattern survived the weekend is that it made the boring decision once, in code, and then stopped asking. If a similar demo is coming up, start with check_flags.py and write the expiry before the feature.

Weekend Build Log: Rehearsing a Free-Tier AI Demo With Four Injected Faults

Charlie Hu — Mon, 19 Oct 2026 08:48:05 +0000

The shippable part of this weekend's side project was not the feature. It was a roughly 60-line rehearsal suite that rate-limits, hangs, and corrupts its own model endpoint on purpose, then asserts the demo reports degraded instead of throwing a 500.

The feature itself — a single page that turns a changelog into three support-friendly bullets — took an afternoon. The rest of the weekend went into making failure the normal case, because a demo that only works when the model endpoint is healthy is not a demo, it is a coin flip.

The build, and the cut that made it fit two days

The project is deliberately small: one HTML page, one Python process, one outbound call. A pasted changelog goes to a chat-completions endpoint, comes back as text, gets parsed into at most three bullets, and renders with a banner showing whether the answer came from the model or from the fallback.

The constraint that shaped everything: both the model access and the host are free options. Neither is something to build a latency budget or an availability assumption on. So the architecture question changed from "how do we keep the model up" to "what does the page show in the two seconds after the model does not answer".

The cut list, written before any code

Scope was cut on paper first, with a rule instead of a mood: anything that needs a database or a second network hop is out. The table below is the actual list, kept in the repo as CUTS.md so the next weekend does not relitigate it.

Candidate	Decision	Reason
Multi-turn refinement	Cut	Needs conversation state, which needs persistence
Streaming tokens	Cut	Adds a second failure surface with no demo value
Login	Cut	Single-user demo; auth would hide the interesting bugs
Saved history	Cut	Database, and the only user is the author
Retry with backoff	Cut	Turns one prompt failure into three, and hides degradation
Fallback banner	Kept	One line of UI, and it is the whole point
Dated smoke log	Kept	Prevents stale "it works" claims

One attempt plus one fallback replaced retries. That decision is the reason the rehearsal suite below is short: with a single attempt, there is exactly one failure path to prove.

Artifact 1: a model endpoint that misbehaves on command

The stub speaks just enough of the chat-completions shape to be swapped in via an environment variable. It is stdlib only, so the suite runs on a clean machine with no install step.

# stub_model.py — a switchable stand-in for the model endpoint
import json, time
from http.server import BaseHTTPRequestHandler, HTTPServer

MODE = "ok"  # ok | rate_limited | hang | malformed

class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        self.rfile.read(int(self.headers.get("Content-Length", 0)))
        if MODE == "rate_limited":
            self.send_response(429)
            self.send_header("Content-Type", "application/json")
            self.end_headers()
            self.wfile.write(b'{"error":"rate_limited"}')
            return
        if MODE == "hang":
            time.sleep(30)  # deliberately longer than the client budget
        if MODE == "malformed":
            body = b'{"choices":[{"message":{"content":"plain prose, no bullets"}}]}'
        else:
            body = json.dumps({"choices": [{"message": {"content": "- fix login\n- bump deps\n- ship it"}}]}).encode()
        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, *args):
        pass

def serve(port=8765):
    return HTTPServer(("127.0.0.1", port), Handler)

The four modes map to the four ways a free endpoint actually disappoints: it answers, it pushes back, it stalls, or it returns a shape the parser did not expect. No fifth mode was added, because unmodeled failures cannot be rehearsed anyway.

Artifact 2: one attempt, one budget, one honest fallback

The client has no retry loop. It has a timeout, a parser, and a return value that always has the same keys.

# summarizer.py — one attempt, one budget, one honest fallback
import json, os, urllib.request

BUDGET_SECONDS = 2.0

def summarize(changelog, base_url=None, timeout=BUDGET_SECONDS):
    base_url = base_url or os.environ["MODEL_BASE_URL"]
    req = urllib.request.Request(
        base_url.rstrip("/") + "/chat/completions",
        data=json.dumps({"messages": [{"role": "user", "content": changelog}]}).encode(),
        headers={
            "Content-Type": "application/json",
            "Authorization": "Bearer " + os.environ.get("MODEL_KEY", ""),
        },
    )
    try:
        with urllib.request.urlopen(req, timeout=timeout) as resp:
            text = json.load(resp)["choices"][0]["message"]["content"]
        bullets = [l.lstrip("- ").strip() for l in text.splitlines() if l.strip().startswith("-")]
    except Exception as exc:  # timeout, 429, bad JSON, shape drift
        return {"ok": False, "reason": type(exc).__name__, "bullets": [], "degraded": True}
    if not bullets:
        return {"ok": False, "reason": "empty_or_unparsed", "bullets": [], "degraded": True}
    return {"ok": True, "bullets": bullets[:3], "degraded": False}

The broad except is intentional and narrow in scope: the only thing inside the try is the network call and the parse, so nothing else can be swallowed. Every exit path returns the same schema, which is what lets the UI render one banner instead of a stack trace.

Artifact 3: the rehearsal suite

# test_rehearsal.py
import threading, time, unittest
import stub_model, summarizer

class Rehearsal(unittest.TestCase):
    @classmethod
    def setUpClass(cls):
        cls.server = stub_model.serve()
        threading.Thread(target=cls.server.serve_forever, daemon=True).start()

    @classmethod
    def tearDownClass(cls):
        cls.server.shutdown()

    def run_mode(self, mode, budget=1.0):
        stub_model.MODE = mode
        result = summarizer.summarize("- fix login\n- bump deps",
                                       base_url="http://127.0.0.1:8765", timeout=budget)
        stub_model.MODE = "ok"
        return result

    def test_happy_path(self):
        r = self.run_mode("ok")
        self.assertTrue(r["ok"])
        self.assertEqual(len(r["bullets"]), 3)

    def test_rate_limited_degrades(self):
        r = self.run_mode("rate_limited")
        self.assertTrue(r["degraded"])
        self.assertFalse(r["ok"])

    def test_hang_hits_budget(self):
        started = time.monotonic()
        r = self.run_mode("hang", budget=0.5)
        self.assertLess(time.monotonic() - started, 1.5)
        self.assertTrue(r["degraded"])

    def test_malformed_payload_degrades(self):
        r = self.run_mode("malformed")
        self.assertTrue(r["degraded"])

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

Run it with python -m unittest -v test_rehearsal. The hang case is capped at 0.5 seconds by design, so the whole suite cannot exceed two seconds even on a slow laptop — that follows from the budgets in the code, not from a benchmark.

The suite is not a quality test of any model. It is a contract test of the demo: whatever the endpoint does, the page renders. Model output quality is a separate, unsolved problem that this weekend did not touch.

Where the free model access and the free server option fit

MonkeyCode is the reason this particular weekend was possible at all: it provides free model access and a free server option, both as described by the operator rather than measured here.

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

Those two facts changed the design in two concrete ways. Free model access meant the endpoint had to be treated as intermittent, which is why summarize() returns a degraded flag instead of retrying. The free server option meant the deployment target was one process with no database, which is why persistence landed on the cut list.

Nothing about the workflow depends on a specific provider. The stub is local, and MODEL_BASE_URL decides where the live call goes. Quotas, model names, and host specifications are deliberately absent from this log because they change; the project's own pages are the place to read the current terms.

A dated smoke log instead of a stale claim

Free tiers move. A sentence like "the endpoint works" has a shelf life measured in days, so the demo writes evidence instead of asserting it.

MODEL_BASE_URL=... MODEL_KEY=... python - <<'PY'
import json, os, time, summarizer
t0 = time.monotonic()
r = summarizer.summarize("- fix login\n- bump deps\n- ship it", timeout=8)
host = os.environ["MODEL_BASE_URL"].split("//")[1].split("/")[0]
print(json.dumps({"ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
                  "host": host,
                  "ms": round((time.monotonic() - t0) * 1000),
                  **r}))
PY

Each run appends one JSON line to smoke.log. The /healthz endpoint reads the last line and returns stale when it is more than a day old, and the page shows that state in the same banner used for fallback. A demo that reports its own staleness is more useful than one that pretends to be fresh.

What the demo skips, and who should not copy this

Skipped, deliberately and on the record:

No auth, no multi-tenancy, no saved history.
No streaming, no multi-turn, no prompt templates per customer.
No retry storm; one attempt, one fallback, one log line.
No answer-quality eval. The parser only checks shape, not usefulness.

This approach is a poor fit for anyone who needs an audit trail, per-user isolation, sub-second responses, or model output treated as authoritative. It is also the wrong base for a product with a guaranteed quota, because the entire design assumes the endpoint can disappear mid-request. For a weekend demo that has to survive being posted publicly, the trade is the right one.

The reusable part is small: a stub that fails on command, a client with one attempt and one budget, and a log with timestamps. Point the smoke script at whatever endpoint is in use this weekend, keep the log dated, and let the rehearsal suite — not optimism — decide whether the demo is ready.

Weekend Build Log: An Idempotent Batch Worker for a Free-Model Side Project

Charlie Hu — Sun, 18 Oct 2026 07:25:07 +0000

A weekend batch job rarely fails because the model is bad. It fails because a retry re-sends work that already succeeded, and the second pass quietly doubles your cost, your labels, or both. This build log is about the boring machinery around one model call: an idempotency key, a bounded worker pool, and a retry table that decides which errors deserve another attempt.

The demo is small on purpose. It reads open issues from a single repository, asks a model for one of four labels, and writes a JSONL result file. No UI, no database of labels, no multi-repo support. The whole thing fits in one file and one SQLite table.

The scope cut, before any code

The weekend had roughly ten usable hours. That number drove the cut list more than any technical preference.

Shipped:

A CLI that takes a JSON file of issues and emits results.jsonl.
A content-hash idempotency key stored in SQLite, so a re-run skips finished work.
Bounded concurrency of two in-flight requests.
A dead-letter file for payloads that should never be retried.
A self-imposed character budget that stops the run instead of discovering the ceiling mid-demo.

Skipped, deliberately:

A web UI. The demo shows the JSONL file in a terminal split pane.
Vector search over past issues. Keyword dedupe was enough for forty items.
Multi-provider routing. One endpoint, one model, one prompt.
Label taxonomy learning. Four fixed labels beat a clustering step nobody asked for.

The skipped items are not future work promises. They were costs the demo did not need to pay.

The failure worth designing for

Two failure modes dominate a naive loop. The first is a rate-limited request that succeeds on attempt three after a long backoff. The second is a timeout where the server actually completed the work and only the response was lost.

The second one is the nasty case. Retrying it duplicates output. Skipping it loses work. There is no perfect answer without server-side idempotency tokens, so the worker picks a policy and records it: a timeout gets exactly one retry, and if that also times out the item goes to the dead-letter file for a human decision. Boring, auditable, and it does not silently double anything.

The artifact: one worker, four policies

The script below is a reference implementation for this post. It was written to be read and rerun, not benchmarked; no throughput numbers are claimed anywhere in it.

#!/usr/bin/env python3
"""Idempotent batch labeling against a free model endpoint."""
import asyncio, hashlib, json, os, random, sqlite3, sys
from pathlib import Path
import httpx

ENDPOINT = os.environ["MC_ENDPOINT"]        # OpenAI-compatible base URL
API_KEY  = os.environ["MC_API_KEY"]
MODEL    = os.environ.get("MC_MODEL", "default")

MAX_INFLIGHT = 2        # keep the pool small; free tiers punish bursts
MAX_ATTEMPTS = 4
BASE_DELAY   = 1.5      # seconds, doubled per attempt, plus jitter
CHAR_BUDGET  = 400_000  # my own ceiling, not a vendor quota

DB   = Path("state.sqlite3")
DEAD = Path("dead_letter.jsonl")

class Transient(Exception): ...
class Permanent(Exception): ...

def key_for(issue):
    """Key on id + text, so an edited issue is reprocessed."""
    h = hashlib.sha256()
    h.update(str(issue["id"]).encode())
    h.update(issue.get("title", "").encode())
    h.update(issue.get("body", "").encode())
    return h.hexdigest()[:16]

def open_state():
    con = sqlite3.connect(DB)
    con.execute("""CREATE TABLE IF NOT EXISTS done(
        key TEXT PRIMARY KEY, label TEXT, ts REAL)""")
    con.commit()
    return con

async def classify(client, issue):
    prompt = (
        "Label this issue as one of: bug, docs, question, other.\n"
        f"Title: {issue['title']}\n\nBody: {issue.get('body','')[:2000]}"
    )
    r = await client.post(
        f"{ENDPOINT}/chat/completions",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"model": MODEL, "temperature": 0,
              "messages": [{"role": "user", "content": prompt}]},
        timeout=60.0,
    )
    if r.status_code in (429, 500, 502, 503, 504):
        raise Transient(f"http {r.status_code}")
    if r.status_code >= 400:
        raise Permanent(f"http {r.status_code}: {r.text[:200]}")
    return r.json()["choices"][0]["message"]["content"].strip().lower()

async def handle(sem, client, con, issue, stats):
    key = key_for(issue)
    if con.execute("SELECT 1 FROM done WHERE key=?", (key,)).fetchone():
        stats["skipped"] += 1
        return
    approx = len(issue.get("title", "")) + len(issue.get("body", ""))
    if stats["chars"] + approx > CHAR_BUDGET:
        stats["budget_stop"] = True
        return
    async with sem:
        for attempt in range(1, MAX_ATTEMPTS + 1):
            try:
                label = await classify(client, issue)
            except Transient as e:
                if attempt == MAX_ATTEMPTS:
                    DEAD.write_text(DEAD.read_text() + json.dumps(
                        {"key": key, "reason": str(e)}) + "\n" if DEAD.exists()
                        else json.dumps({"key": key, "reason": str(e)}) + "\n")
                    stats["dead"] += 1
                    return
                delay = BASE_DELAY * 2 ** (attempt - 1) + random.uniform(0, 0.5)
                await asyncio.sleep(delay)
                continue
            except Permanent as e:
                with DEAD.open("a") as f:
                    f.write(json.dumps({"key": key, "reason": str(e)}) + "\n")
                stats["dead"] += 1
                return
            con.execute("INSERT OR REPLACE INTO done VALUES (?,?,?)",
                        (key, label, __import__("time").time()))
            con.commit()
            stats["chars"] += approx
            stats["ok"] += 1
            print(json.dumps({"key": key, "label": label}))
            return

async def main(path, dry_run=False):
    issues = json.loads(Path(path).read_text())
    if dry_run:
        for i in issues:
            print(key_for(i), "|", i["title"][:60])
        return 0
    con, stats = open_state(), {"ok": 0, "skipped": 0, "dead": 0,
                                "chars": 0, "budget_stop": False}
    sem = asyncio.Semaphore(MAX_INFLIGHT)
    async with httpx.AsyncClient() as client:
        await asyncio.gather(*(handle(sem, client, con, i, stats) for i in issues))
    print(json.dumps(stats), file=sys.stderr)
    if stats["budget_stop"]:
        return 3
    return 2 if stats["dead"] else 0

if __name__ == "__main__":
    raise SystemExit(asyncio.run(main(sys.argv[1], "--dry-run" in sys.argv)))

Why the key is a content hash

Keying on the issue id alone means an edited issue is never relabeled. Keying on the body alone means two issues with identical text collapse into one. Hashing id, title, and body gives the property the demo needs: identical input is skipped, changed input is reprocessed.

The trade-off is visible. Any whitespace-only edit forces a re-run. For a forty-issue demo that is cheap; for a large backlog it is not, and a normalized body hash would be the next cut to make.

A retry decision table

Condition	Action	Reason
429, 500, 502, 503, 504	Retry with exponential backoff plus jitter	Transient by definition
400, 401, 403, 422	Dead-letter, no retry	The payload or key is wrong; retrying repeats the bug
Client timeout	One retry, then dead-letter	Outcome is ambiguous; cap the duplicate risk
Key already in SQLite	Skip	Idempotency
Character budget exceeded	Stop, exit code 3	Fail on a known boundary, not a surprise one
Empty model response	Dead-letter	A malformed answer is not a network problem

Exit codes matter for the demo: 0 is clean, 2 means dead letters exist and someone should look, 3 means the budget stopped the run. A shell set -e around the script then does something useful.

Where the runs actually live

The worker was written against an OpenAI-compatible endpoint, which keeps the client portable. MonkeyCode provides free model access and a free server option (per the operator; current limits and terms should be checked before planning around them), so the API key and base URL come from environment variables rather than being baked into the script.

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

Putting the worker on the free server option is the part that makes it a weekend project rather than a laptop babysitting job: the script keeps running after the terminal closes. Uptime was not measured for this post, and the idempotency table is what makes restarting safe either way.

# plan first: no network calls, just keys and titles
export MC_ENDPOINT="$MC_ENDPOINT" MC_API_KEY="$MC_API_KEY"
python worker.py issues.json --dry-run

# then a real run; re-running is safe because of the key table
python worker.py issues.json; echo "exit=$?"

What this approach does not give you

Exact token accounting. CHAR_BUDGET counts characters, which is a crude proxy. It is wrong for code-heavy or non-Latin text, and it does not know how a given endpoint tokenizes.
Cross-machine idempotency. SQLite is local. Two workers on two hosts will both process the same issue.
Ordering. asyncio.gather finishes in whatever order the network allows.
Correct labels. The prompt is four lines. It is a demo of plumbing, not a classifier.

Skip this pattern if you need exactly-once semantics, if labels must be reviewed before they touch a real repository, or if your issue bodies are large enough that a character budget is the wrong control entirely.

The part worth carrying to the next project is the table, not the code. Decide which errors earn a retry before the first request goes out, write the decision down, and let the script enforce it. If you want to try the free model access and free server option yourself, the two environment variables above are the only integration points the worker needs.

Weekend Build Log: A Model-Swap Harness for a Side Project on Free Endpoints

Charlie Hu — Sat, 17 Oct 2026 06:26:53 +0000

Three commands decide whether a weekend side project survives a backend change. The app built this weekend is deliberately small: it turns a build log into a release note. The thing worth keeping is the harness around it — twelve fixed cases, a runner that validates response shape, and a diff that names the exact cases that flipped.

That framing is the whole article. The app is replaceable. The harness is the part that keeps working after the endpoint, the model id, or the free allowance changes under you.

The scope cut came first

Saturday started with a list of nine features and ended with four. The cut was not taste, it was arithmetic: one person, two days, no on-call.

Kept	Cut	Reason for the cut
CLI that reads a `git log --oneline` dump	Web UI	No user but me; a UI doubles the surface to test
Twelve fixed prompt cases	Live prompt editing	Untestable when the input moves every run
Shape validation (valid JSON, required keys)	Quality scoring	Needs a human reviewer; cannot finish in a weekend
One endpoint at a time via env vars	Multi-provider routing	Routing is a month-two problem

Shape validation is the key decision. It does not ask "is this release note good?" It asks "did the response stay parseable and keep the two keys the downstream code reads." That question is answerable by a machine at 2 a.m.

What shipped: one file, twelve cases, three commands

Repository layout, complete:

release-notes/
  cases.jsonl
  run_eval.py
  results/

No dependencies. Python standard library only, because a pip install on a Sunday afternoon is how weekends die.

The case file

Each line is self-contained: its own system message, its own expected keys. Two examples of the twelve:

{"id":"empty-diff","required_keys":["summary","risk"],"messages":[{"role":"system","content":"Reply with JSON only: {\"summary\": string, \"risk\": \"low\"|\"high\"}"},{"role":"user","content":"Two commits: typo fix in README, version bump to 0.3.1."}]}
{"id":"removed-flag","required_keys":["summary","risk"],"messages":[{"role":"system","content":"Reply with JSON only: {\"summary\": string, \"risk\": \"low\"|\"high\"}"},{"role":"user","content":"Removed --legacy from the CLI; three call sites updated."}]}

The remaining ten cover the boring edges that break parsers: an empty commit list, a commit subject containing quotes, a 500-character subject, a message with a code block, non-ASCII author names, and a diff with no file changes.

The runner

#!/usr/bin/env python3
"""run_eval.py — replay a fixed prompt set against any OpenAI-compatible endpoint.

  LLM_BASE_URL=... LLM_API_KEY=... LLM_MODEL=... \
    python3 run_eval.py --cases cases.jsonl --out results/run-a.json
"""
import argparse, json, os, time, urllib.error, urllib.request


def call(base_url, api_key, model, messages, timeout):
    req = urllib.request.Request(
        base_url.rstrip("/") + "/chat/completions",
        data=json.dumps({"model": model, "messages": messages,
                         "temperature": 0}).encode(),
        headers={"Content-Type": "application/json",
                 "Authorization": "Bearer " + api_key},
    )
    start = time.perf_counter()
    with urllib.request.urlopen(req, timeout=timeout) as resp:
        body = json.loads(resp.read().decode())
    elapsed_ms = int((time.perf_counter() - start) * 1000)
    return body["choices"][0]["message"]["content"], elapsed_ms, body.get("usage", {})


def check_shape(text, required):
    try:
        obj = json.loads(text)
    except json.JSONDecodeError as exc:
        return False, "not-json: " + exc.msg
    if not isinstance(obj, dict):
        return False, "not-object"
    missing = [k for k in required if k not in obj]
    return (False, "missing:" + ",".join(missing)) if missing else (True, "ok")


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--cases", required=True)
    ap.add_argument("--out", required=True)
    ap.add_argument("--timeout", type=int, default=60)
    args = ap.parse_args()

    base_url, api_key = os.environ["LLM_BASE_URL"], os.environ["LLM_API_KEY"]
    model = os.environ["LLM_MODEL"]

    cases = [json.loads(l) for l in open(args.cases, encoding="utf-8") if l.strip()]
    results = []
    for case in cases:
        record = {"id": case["id"]}
        try:
            text, ms, usage = call(base_url, api_key, model,
                                   case["messages"], args.timeout)
            ok, note = check_shape(text, case.get("required_keys", []))
            record.update(ok=ok, note=note, ms=ms,
                          completion_tokens=usage.get("completion_tokens"),
                          output=text[:400])
        except (urllib.error.URLError, KeyError, TimeoutError) as exc:
            record.update(ok=False, note="error:" + type(exc).__name__, ms=None, output="")
        results.append(record)

    passed = sum(1 for r in results if r["ok"])
    with open(args.out, "w", encoding="utf-8") as fh:
        json.dump({"model": model, "base_url": base_url, "passed": passed,
                   "total": len(results), "cases": results}, fh, indent=2)
    print(f"{passed}/{len(results)} shape-ok -> {args.out}")


if __name__ == "__main__":
    main()

temperature: 0 is not a reproducibility guarantee, only a variance reducer. The output is still recorded verbatim so a reviewer can see what actually came back.

The diff

Run the same case file before and after a swap, then compare the pass flags:

jq -s '[ (.[0].cases | map({key:.id, value:.ok}) | from_entries) as $a
       | (.[1].cases | map({key:.id, value:.ok}) | from_entries) as $b
       | $a | keys[] | select($a[.] != $b[.]) ]' \
  results/run-a.json results/run-b.json

A crude latency read, good enough for spotting a 10x regression:

jq -r '"\(.passed)/\(.total) crude-p50=\(.cases|map(.ms)|sort|.[length/2|floor])ms"' results/run-b.json

The swap test plan

Freeze cases.jsonl before the first run. Editing cases between runs invalidates the diff.
Run against endpoint A. Commit results/run-a.json.
Change only LLM_BASE_URL and LLM_MODEL. Nothing else in the environment.
Run again into results/run-b.json.
Diff pass flags. Every id that appears is a case to read by hand.
Record the date and endpoint in results/NOTES.md. Undated results are folklore.

Step 3 is the one people skip. If the prompt, the temperature, and the case file all move at once, the diff tells you nothing.

Reading the diff without overclaiming

The table below is a schema to fill with your own numbers, not a measurement from this build:

Field	Run A	Run B
shape-ok count	`<n>/12`	`<n>/12`
cases that flipped	—	`<list of ids>`
crude p50 latency	`<ms>`	`<ms>`
failure notes	`<not-json / missing:...>`	`<same>`

Two failure classes matter. not-json means the new backend wrapped the object in prose or a Markdown fence, and the fix is a stricter system message or a one-line extraction step. missing:risk means the schema instruction was ignored, which is a prompt problem, not a transport problem. Separating those two saves an hour of blaming the network.

Twelve cases prove parseability, nothing more. It is a smoke test with a memory, not an eval suite.

Where free access and a free server fit

A weekend project dies between Saturday night and Monday morning, when the laptop closes and the demo link goes dark. Two pieces of infrastructure remove that specific failure: free model access, so the twelve cases can be run repeatedly without a billing decision, and a free server option, so the CLI can be reached from a browser on Sunday evening.

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

Both are operator-supplied availability claims, and both change over time. Check the current terms page for live limits before planning around any number — quotas, model lists, and machine specs are exactly the kind of detail that goes stale between one blog post and the next. The architecture above is deliberately indifferent to those values: it reads LLM_BASE_URL, LLM_API_KEY, and LLM_MODEL from the environment precisely so the endpoint is a configuration detail rather than a commitment.

Limitations and who should not use this

Shape is not quality. A perfectly parseable release note can still be wrong. Nothing here catches that.
Twelve cases is a sample. It catches regressions in the edges it names, and misses every edge it does not.
No load or cost modeling. One request at a time, no concurrency, no retry budget.
Not for production traffic. No retries, no backoff, no idempotency keys, no request logging beyond the JSON file.
Not for sensitive input. Real commit logs contain internal hostnames and ticket references. Do not paste them into any endpoint you have not cleared.
Not a benchmark. Latency numbers from a single run on a shared network are noise; treat them as a tripwire, not a measurement.

Anyone needing an SLA, per-tenant isolation, or auditable prompt history should build on a paid contract with a written data-handling agreement instead.

The skip list, with un-skip triggers

What was skipped matters as much as what shipped, but only if each skip has a condition attached:

Skipped	Un-skip when
Streaming	A single response exceeds the demo's patience threshold
Retries and backoff	One timeout is observed twice in the same week
Response caching	The same case is run more than three times a day
Auth on the demo server	Anyone other than me has the URL
A second provider	The diff shows a flip that blocks the golden path
Quality review	Shape-ok is 12/12 on two consecutive runs

That last row is the honest one. The harness answers its own question, and then it is finished.

Sunday night checklist

python3 run_eval.py --cases cases.jsonl --out results/run-final.json exits 0.
jq -r '.passed, .total' results/run-final.json prints two equal numbers.
results/NOTES.md names the endpoint, the model, and the date.
The demo server answers once from a browser, not just from curl on localhost.
The skip table is committed, so the next session starts with constraints instead of ambitions.

The harness is roughly ninety lines. Point it at whatever endpoint is already wired into your project, run the swap test once, and the weekend stops depending on infrastructure you do not control.

Weekend Build Log: A Cold-Start Test for Free-Tier Demo Hosts

Charlie Hu — Fri, 16 Oct 2026 05:28:54 +0000

A weekend demo ships in one of two states: it works on the author's laptop, or it works from a cold start on the host where reviewers will open it. The gap between those two states is almost never the application code. It is three host properties that most build logs never measure.

Core conclusion: before a side project is called "done", measure cold-start time, disk durability, and idle/restart behavior on the actual host. Treat everything else — UI polish, extra endpoints, model choice — as optional.

The scope cut: three tiers, one weekend

The build log below is written so it can be replayed on any free-tier host. No product benchmark numbers appear in it, because free-tier behavior differs by region and changes without notice. The scripts are the artifact; the numbers are yours to fill in.

Tier assignment used for the build:

Tier 1 — must ship. One /healthz endpoint, one read-only route, the cold-start probe, the durability probe, and a README with copy-pasteable commands.
Tier 2 — ship only if Friday's measurements allow. Seed fixtures, one write path behind an environment flag, a short demo script.
Tier 3 — explicitly never this weekend. Auth, multi-tenant data, background workers, dashboards, and any migration of real data.

One rule keeps the tiers honest: adding a Tier 2 item requires removing a Tier 1 item or shortening the demo script by the same amount of time. Otherwise the tier list becomes a wish list with deadlines attached.

Why free hosts break demos in three specific ways

Cold start after idle. A host that sleeps the process turns a 200 ms request into a multi-second one. The first reviewer to open the link pays that cost.
Ephemeral disk. Files written at runtime disappear on restart. SQLite in a container without a mounted volume is the classic case.
Unknown restart policy. Whether the supervisor restarts a crashed process, and how quickly, is usually undocumented on free tiers.

None of these are reasons to avoid a free host. They are reasons to measure before the demo depends on them.

Artifact 1: the cold-start probe

The probe clones the repository into a temporary directory, installs it, boots it, and polls until the health endpoint answers.

#!/usr/bin/env bash
# cold-start.sh  <git-url>
# Measures: clean checkout -> first successful /healthz response.
set -euo pipefail

REPO="${1:?usage: cold-start.sh <git-url>}"
PORT="${PORT:-8080}"
BUDGET_MS="${BUDGET_MS:-0}"   # 0 = measure only, no assertion
WORK="$(mktemp -d)"

git clone --depth 1 "$REPO" "$WORK/app" >/dev/null
cd "$WORK/app"

START=$(date +%s%3N)
if [ -f package.json ]; then
  npm ci --silent
  (PORT="$PORT" npm start >"$WORK/boot.log" 2>&1 &)
elif [ -f requirements.txt ]; then
  python -m venv .venv
  ./.venv/bin/pip install -q -r requirements.txt
  (PORT="$PORT" ./.venv/bin/python -m app >"$WORK/boot.log" 2>&1 &)
else
  echo "no known manifest; add a branch for your stack"
  exit 2
fi

until curl -sf "http://127.0.0.1:$PORT/healthz" >/dev/null 2>&1; do
  sleep 0.2
done
END=$(date +%s%3N)

ELAPSED=$(( END - START ))
echo "cold_start_ms=$ELAPSED budget_ms=$BUDGET_MS"

if [ "$BUDGET_MS" -gt 0 ] && [ "$ELAPSED" -gt "$BUDGET_MS" ]; then
  echo "FAIL: cold start over budget"
  exit 1
fi
echo "PASS"

Run it three times locally and three times on the host, then set BUDGET_MS to roughly twice the slowest observed value. The assertion exists to catch regressions between Friday and Sunday, not to publish a speed claim.

Artifact 2: the durability probe

Durability is a yes/no question and takes about two minutes to answer. Gate the debug route behind an environment variable, and delete it after the measurement.

# Before a restart
curl -s -X POST "$BASE/debug/token" -d "value=$(date +%s)" -o before.txt
# Restart the service using the host's own control panel or CLI
curl -s "$BASE/debug/token" -o after.txt

if diff -q before.txt after.txt >/dev/null; then
  echo "durable: state survived restart"
else
  echo "ephemeral: treat the disk as scratch space"
fi

An ephemeral result does not kill the demo. It changes the design: the read path is served from a fixture baked into the image, and any runtime writes are declared in the README as lost-on-restart.

Artifact 3: the triage table

Property	How to measure	If it fails	Ship the demo anyway?
Cold start	`cold-start.sh` against the host	Show a static warming-up page and ping before review	Yes, with a warm-up step in the runbook
Disk durability	Token probe across a restart	Serve fixtures from the image; no runtime writes	Yes, if the demo is read-only
Restart on crash	Kill the process via the host CLI	Add a manual restart step to the runbook	Yes, for a short review window
Outbound network	One `curl` to a known endpoint from the app	Precompute anything fetched at runtime	Only if the demo has no live-data need

The rule applied to the table: a failed property becomes a documented demo step, never an unstated assumption.

Where free model access fits

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode offers free model access and a free server option; both are operator-supplied availability claims here, and model names, quotas, regions, and terms can change, so verify current details on the project's own pages before planning around them. No quota figures, hardware specs, or benchmark results are stated in this article, because none were measured for it.

Free model access covers exactly three of the weekend's chores:

Generating fixture variations from a small hand-written example.
Drafting the README from the final diff, which a human then corrects.
Triaging boot logs into cause and noise after a failed deploy.

It does not belong on the request path of a live demo. A demo that calls out to a model on every page load adds a network dependency to the one thing the reviewer will click. Keep the call count explicit instead:

MAX_MODEL_CALLS = 3  # chores only: fixtures, README draft, log triage
calls = 0

def ask(prompt: str) -> str:
    global calls
    if calls >= MAX_MODEL_CALLS:
        raise RuntimeError('weekend model budget exhausted; do it by hand')
    calls += 1
    return client.complete(prompt)   # placeholder: wire to any provider

The free server option is the natural host for a demo of this size, with one caveat: the probes above decide whether it can hold the demo, not a product page. Measure on the free tier first, then decide what the README promises.

What got skipped, on purpose

Authentication. The demo has no users, so it has no user model.
Persistence for writes. The read path carries the demo; writes stay in memory.
CI beyond the two probes. The probes are the only tests that protect the review experience.
A custom domain. A default hostname is one fewer thing to break on Sunday night.

Every item on that list belongs in the README under known gaps. A reviewer who finds an unlisted gap assumes the rest is guesswork too.

Limitations and who should not use this

Demos that hold real user data need durability guarantees a free tier may not offer.
Anything with an uptime or latency commitment to a customer needs a paid host with a stated SLA.
Teams already running infrastructure should reuse it; adding a second platform for one weekend costs more than it saves.
The durability probe writes and reads a debug route. Remove that route after measuring, and confirm the host's terms allow the traffic the probe generates.

Sunday-night runbook

Run cold-start.sh against the deployed URL and record the number.
Restart the service, open the demo link, and confirm the first request path works cold.
Walk the demo script out loud, once, end to end.
Confirm every skipped item is listed in the README.
Freeze the branch. No commits after step 5.

A weekend side project is not judged by how much it contains. It is judged by whether a stranger can open it on Monday and see the one thing it does. If that trade-off fits your next weekend, the free server option is a reasonable place to start — run the cold-start probe before writing the README, and let the measurement set the scope.

A Machine-Checked Scope Budget for One-Weekend AI Demos

Charlie Hu — Thu, 15 Oct 2026 11:32:48 +0000

A Machine-Checked Scope Budget for One-Weekend AI Demos

The demo ships or it does not. What decides which is a file, not an intention.

Weekend AI side projects usually fail at the same place: the plan grows faster than the clock. A single-path demo needs a much smaller surface than most people budget for, and that surface has to be enforced by something other than willpower at 11 p.m. on Sunday.

The pattern below uses three artifacts: a golden-path smoke test, a scope budget that a script is allowed to veto, and a cut table that decides in advance what gets deleted rather than deferred. The running example is a small "summarize one file into a changelog stub" service with exactly one model call in the path.

MonkeyCode's free model access and free server option are relevant here for one narrow reason: they remove two classic weekend sinks, key provisioning and deploy plumbing. The pattern itself is independent of any provider. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Rule one: the golden path is a command, not a paragraph

Write the demo as one shell command that either exits 0 or exits non-zero. If the golden path cannot be expressed as a command, the scope is not yet small enough to start.

#!/usr/bin/env bash
# smoke.sh - the golden path end to end, no mocks, no manual steps
set -euo pipefail

BASE_URL="${BASE_URL:-http://localhost:8080}"
FIXTURE="${FIXTURE:-fixtures/tiny_repo.txt}"
OUT="$(mktemp)"

# 1. the service is up and self-reports
curl -fsS --max-time 5 "$BASE_URL/health" | grep -q '"status":"ok"'

# 2. one real request against a frozen fixture
curl -fsS --max-time 45 -X POST "$BASE_URL/summarize" \
  -H 'content-type: text/plain' \
  --data-binary "@$FIXTURE" \
  -o "$OUT"

# 3. the response is markdown with a heading, not an error page
grep -q '^## ' "$OUT" || { echo "FAIL: no markdown heading"; exit 1; }
grep -qi 'summary' "$OUT" || { echo "FAIL: no summary section"; exit 1; }

echo "GOLDEN PATH OK ($(wc -c <"$OUT") bytes)"

The important property is that step 2 crosses a real network boundary. A smoke test that stubs the model call proves nothing about the demo, because the model call is the part most likely to break during a live walkthrough.

Rule two: the plan is a file a script can reject

Scope creep is easier to catch as a validation error than as a feeling. Put the whole weekend in weekend.yml, then let a small checker refuse plans that cannot fit.

# weekend.yml - the plan the checker is allowed to veto
budget_hours: 12
golden_path:
  name: "summarize one file into a changelog stub"
  must_pass_by: "sunday 20:00"
items:
  - id: read-fixture
    hours: 1
    tier: must
  - id: model-call
    hours: 2
    tier: must
  - id: render-markdown
    hours: 2
    tier: must
  - id: deploy-hosted
    hours: 1
    tier: must
  - id: auth
    hours: 4
    tier: later
    tripwire: "only if the demo needs more than one user"
  - id: history-db
    hours: 6
    tier: later
    tripwire: "only if a reviewer asks for past runs"
  - id: settings-ui
    hours: 5
    tier: later
    tripwire: "only if a config value must be edited by a non-developer"

#!/usr/bin/env python3
"""scope-check.py - reject the plan before the weekend rejects it."""
import sys
import yaml  # pip install pyyaml

MAX_MUST_ITEMS = 4
MAX_MUST_HOURS_PER_ITEM = 3


def load(path):
    with open(path, encoding="utf-8") as fh:
        return yaml.safe_load(fh)


def check(plan):
    problems = []
    budget = plan["budget_hours"]
    musts = [i for i in plan["items"] if i["tier"] == "must"]
    must_hours = sum(i["hours"] for i in musts)

    if must_hours > budget:
        problems.append(f"must items need {must_hours}h, budget is {budget}h")
    if len(musts) > MAX_MUST_ITEMS:
        problems.append(f"{len(musts)} must items; the ceiling is {MAX_MUST_ITEMS}")
    for item in musts:
        if item["hours"] > MAX_MUST_HOURS_PER_ITEM:
            problems.append(
                f"must item '{item['id']}' is {item['hours']}h; split or demote it"
            )
    for item in plan["items"]:
        if item["tier"] != "must" and not item.get("tripwire"):
            problems.append(f"deferred item '{item['id']}' has no tripwire")
    return problems


def main():
    path = sys.argv[1] if len(sys.argv) > 1 else "weekend.yml"
    problems = check(load(path))
    if problems:
        print("SCOPE CHECK FAILED")
        for problem in problems:
            print(f"  - {problem}")
        return 1
    print("SCOPE CHECK PASSED")
    return 0


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

Example transcript for the plan above:

$ python3 scope-check.py weekend.yml
SCOPE CHECK PASSED

$ python3 scope-check.py weekend.yml   # after adding a 4h 'oauth' must-item
SCOPE CHECK FAILED
  - must items need 13h, budget is 12h
  - must item 'oauth' is 4h; split or demote it

The tripwire requirement matters more than the hour math. A deferred item with a written tripwire has a condition for returning; a deferred item without one is just a wish that will resurface mid-demo.

Rule three: keep one network dependency in the path

Each additional service in the golden path multiplies the number of things that can be down at demo time. In this build, the path has exactly two: the app host and the model endpoint.

The request shape below is a sketch, not a verified contract. Endpoint paths and model identifiers change between releases, so read the project's current documentation instead of copying a blog snippet, including this one.

# shape sketch: confirm base URL and model id against current docs
export MC_BASE="${MC_BASE:?set from docs}"
export MC_MODEL="${MC_MODEL:?set from docs}"

curl -fsS --max-time 45 "$MC_BASE/chat/completions" \
  -H "authorization: bearer $MC_TOKEN" \
  -H 'content-type: application/json' \
  -d "$(jq -n --arg m "$MC_MODEL" --rawfile f fixtures/tiny_repo.txt \
        '{model:$m,messages:[{role:"user",content:("Summarize as markdown:\n" + $f)}]}')"

Two properties are worth copying regardless of provider. First, the model identifier lives in an environment variable, so switching providers is a config change rather than a code change. Second, every model call has a wall-clock timeout shorter than the smoke test's patience, so a hung request fails loudly instead of stalling a walkthrough.

Gate the whole thing behind one command and run it before every rehearsal:

check:
    python3 scope-check.py weekend.yml
    ./smoke.sh

The cut table

Decisions get easier when the response to a scope item is chosen by rule instead of by mood.

Signal	Action	Reason
Item is not on the golden path	Delete it	Deferral keeps the cost in the plan
Must-item exceeds 3 hours	Split or demote	Long must-items are where weekends die
Requires a second stateful service	Stub it with a file or constant	A database is a second failure domain
Requires a secret that is not on hand	Replace with a public fixture	Provisioning is not demo work
Only improves visual polish	Skip, and log it	Polish is the first thing viewers forgive
Triggered by a real reviewer question	Re-promote to must	Evidence beats aesthetics

What this weekend skipped, on purpose

Authentication. The demo runs as a single anonymous user. Multi-user auth was deferred with a concrete tripwire rather than half-built.
Persistence. Results are not stored. A file-backed stub would have added a migration story and a second failure mode.
A settings interface. Configuration stays in environment variables, which is honest about who the demo is for.
Model comparison. One model, one prompt, one output shape. Comparing providers is a separate project with its own budget.
Streaming output. The response arrives whole. Streaming is a latency feature, and the demo has no latency claim to defend.
Test coverage beyond the golden path. Unit tests exist where they were cheap; the smoke test is the gate.

Recent community discussion has been heavy on AI fatigue, and this cut list is the practical response to it. A smaller AI surface is easier to defend to a reader, a reviewer, or a future maintainer.

Limits, and who should not copy this

The scope checker validates a plan, not a product. It cannot tell whether the golden path is worth building.
A 12-hour budget suits a single developer with a known stack. Teams coordinate more than they code, so the numbers do not transfer.
Anything with real users, credentials, or regulated data should not run on a demo-grade setup with no auth and no persistence.
Free-tier availability, allowances, and server specifications are set by the provider and change over time. Verify current terms on the project's own pages before planning around them, and do not treat a free tier as a production SLA.
If verification is impossible for a given claim, remove the claim instead of softening it. The scripts above are the only parts that need to be true for the pattern to work.

Closing

A weekend side project succeeds when the golden path runs, the plan is small enough to enforce, and the skipped list is written down. The checker and the smoke test take under an hour to write and they pay for themselves the first time a demo survives a rehearsal it should have failed.

If the free model access or the free server option is what decides whether the weekend happens at all, read the project's current terms first, then start from the smoke test rather than from the feature list. The repository is open source, so the fastest way to verify any capability claim is the source itself.

A Source-Locked Claim Gate for a One-Path Weekend Demo

Charlie Hu — Tue, 13 Oct 2026 02:31:34 +0000

A weekend side project should refuse to print a number it cannot point at. That is the conclusion, and the rest of this log is the cut that makes the conclusion enforceable. A longer prompt does not hold the line. A local allowlist does.

The working demo is deliberately small. It reads one markdown note, checks every detected number and link against a hand-edited allowlist, and writes a JSON receipt. If the receipt is not clean, the note does not ship. Optional static hosting comes after that check, not before it.

Why this cut, this weekend

Agent demos fail in a specific way. The prose sounds finished, then a quota, a latency figure, or a documentation link appears that nobody opened. The failure is not mystical. It is an untracked claim.

Public developer discussion has spent energy on retries, agreeable models, and the gap between model progress and ordinary software discipline. Those threads are context, not a source of figures for this log. No statistic from a third-party post is repeated here. The engineering move is local: treat unsourced numbers as build errors.

This account's recent notes already covered attempt caps, fixture locks, read-only routes, and status cards. The missing piece is the claim itself. A frozen fixture can still contain a made-up capacity line. The gate below targets that line, and nothing wider.

Scope that fits in a weekend

Four artifacts and one command define the path. The checker does not import an SDK. The hot path does not open a socket.

Files that stay

notes/demo.md holds the only prose the demo is allowed to show.
claims/allowlist.toml holds the only numbers, phrases, and URLs the prose may repeat.
gate_claims.py is a local checker with a boring exit code.
receipts/latest.json is the pass or fail record a reviewer can diff.

Work that does not get built

The skip list is part of the design, not a backlog apology.

No automatic retry after a red receipt.
No write tool pointed at the repository.
No multi-model comparison and no named-model bake-off.
No token meter and no cost chart.
No account system on the optional host.
No live search inside the demo process.

A side project that implements that list stops being a weekend demo. The cut keeps the path teachable, and it keeps a bad figure from hiding inside extra machinery.

Hand-write the allowlist first

Suggestions can arrive later. Authority starts in a file a human can read without a model session. The shape below is a proposal, not a verified product sheet.

# claims/allowlist.toml
# Unexecuted proposal. Rows show file shape, not measured product facts.

[[claim]]
kind = "phrase"
text = "free model access"
source = "operator-supplied availability note, re-check before publish"

[[claim]]
kind = "phrase"
text = "free server option"
source = "operator-supplied availability note, re-check before publish"

[[claim]]
kind = "url"
text = "https://dev.to/devlab_1905"
source = "this account home, open once on publish day"

A token allotment does not belong in the example. Neither does a server size, a region, or a promise that an offer lasts. If a primary page is checked on demo day and a human adds a sourced row, the gate can allow that exact text. Until then, the prose must not invent it.

Proposed checker

The program below is a proposal. It is labeled unexecuted. It is not a benchmark, and it is not a claim that this account ran it on 2026-10-13.

#!/usr/bin/env python3
"""Fail markdown that prints numbers or links missing from an allowlist.

Proposal only. Not a recorded test run.
"""

from __future__ import annotations

import json
import re
import sys
from pathlib import Path

NUM = re.compile(r"\b\d[\d,]*(?:\.\d+)?%?\b")
URL = re.compile(r"https?://[^\s)]+")
BANNED = ("forever", "unlimited", "fastest", "guaranteed")


def load_allowlist(path: Path) -> set[str]:
    allowed: set[str] = set()
    for raw in path.read_text(encoding="utf-8").splitlines():
        line = raw.strip()
        if line.startswith("text = "):
            value = line.split("=", 1)[1].strip().strip('"')
            allowed.add(value)
    return allowed


def gate(markdown: str, allowed: set[str]) -> dict:
    failures = []
    lowered_allowed = {item.lower() for item in allowed}
    for word in BANNED:
        if word in markdown.lower() and word not in lowered_allowed:
            failures.append({"kind": "wording", "text": word})
    for match in NUM.findall(markdown):
        if match not in allowed:
            failures.append({"kind": "number", "text": match})
    for match in URL.findall(markdown):
        if match not in allowed:
            failures.append({"kind": "url", "text": match})
    return {
        "ok": not failures,
        "failure_count": len(failures),
        "failures": failures,
    }


def main() -> int:
    if len(sys.argv) != 3:
        print("usage: gate_claims.py NOTE.md ALLOWLIST.toml", file=sys.stderr)
        return 2
    note = Path(sys.argv[1]).read_text(encoding="utf-8")
    allowed = load_allowlist(Path(sys.argv[2]))
    receipt = gate(note, allowed)
    out = Path("receipts")
    out.mkdir(exist_ok=True)
    (out / "latest.json").write_text(
        json.dumps(receipt, indent=2) + "\n",
        encoding="utf-8",
    )
    print(json.dumps(receipt, indent=2))
    return 0 if receipt["ok"] else 1


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

Run it from the demo root after the two input files exist.

mkdir -p receipts notes claims
python3 gate_claims.py notes/demo.md claims/allowlist.toml
echo "exit=$?"

Exit code 0 means the detected claims were already allowlisted. Exit code 1 means the note stays unpublished. Exit code 2 means the command was called wrong. The receipt file is the review object. A model transcript is not.

Two notes, two expected receipts

These fixtures are specifications for a later run. They are not recorded outputs.

Passing note

This demo reads one local note and writes a receipt.
It may mention free model access only as an operator-supplied option.

That note has no bare number and no URL. The checker should return ok: true when the phrase row exists and the banned-word list stays quiet. The sample script does not yet prove that an allowlisted phrase occurs in the note. That gap is intentional. A weekend can ship the failure mode first, then add a presence check only if a real run shows a need.

Failing note

The free tier includes 8192 tokens and stays unlimited.
Docs live at https://example.com/pricing.

Expected failures include the number 8192, the word unlimited, and the unlisted URL. The demo stops. Nobody repairs it by asking for another draft. The human deletes the sentences, or replaces them with sourced rows after opening a primary page on the same day.

Decision table

Signal in the note	Result	Next edit
Number absent from `text` rows	Fail	Remove it, or add a row whose source was opened that day
URL absent from `text` rows	Fail	Drop the link
Banned wording such as unlimited	Fail	Use a dated check instead of a permanence claim
Allowlisted operator phrase, no new number	Pass	Keep a single plain mention
Step index such as a digit in a list	Often fail	Spell the step, or allowlist the digit as a structural index
Image-only claim	Not detected	Do not use images for figures in this demo

The last two rows are why the gate is a lock for a side project, not a general truth machine. Lists that need digits should be rewritten, or the digits should be added as explicit rows with source structural index, not a product fact.

One model pass, after the file exists

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

MonkeyCode is relevant only after claims/allowlist.toml exists. The operator describes it as an open-source project and states that free model access and a free server option are available. This log does not add model names, quotas, hardware, regions, or a duration. Those details were not verified against a primary source for 2026-10-13, and an unverified figure would fail the gate this article is arguing for.

Use free model access for one classification pass on the note. Ask for labels only: plain, numeric, or needs-source. Paste the labels beside the note in a scratch file. Merge nothing automatically. If the labels are wrong, shrink the note. A second call is a skip, not a remedy.

Use the free server option, if it is still offered when the receipt is green, as a static file host for receipts/latest.json and a single HTML page. The page may print ok and failure_count. It gets no form, no upload, and no proxy to a model endpoint. If that option is down, or the terms differ from what was assumed, skip hosting. The local command remains the demo either way.

Readers comparing this cut with their own side project can confirm the repository license and the current free-access terms, then run the checker against one note they already trust. A local red receipt is a better introduction than a hosted tour.

Static page, still optional

A few lines of HTML are enough for a reviewer who wants the receipt visible. They load JSON only when both files sit on the same origin. This snippet is also a proposal, not a deployed site.

<pre id="out">receipt not loaded</pre>
<script>
fetch("./latest.json")
  .then((res) => res.json())
  .then((data) => {
    document.getElementById("out").textContent = JSON.stringify(data, null, 2);
  })
  .catch(() => {
    document.getElementById("out").textContent = "local receipt missing";
  });
</script>

That page teaches the receipt shape. It does not teach product capacity. Leaving it offline is a valid weekend outcome, and it should be the default if the host terms were not re-read that day.

Test plan before anyone treats the script as done

No run is claimed here. A reviewer would still want a fixed sequence before trusting the exit code.

Sequence

Empty-claim note. Expect ok: true and failure_count: 0.
Note containing 8192. Expect a number failure and exit 1.
Note containing an unlisted URL. Expect a URL failure.
Note containing guaranteed. Expect a wording failure.
Note whose only URL is copied exactly from an allowlist row. Expect that URL not to fail.
Run the same command with the network interface disabled. Expect an identical receipt, because the checker should not dial out.
Point the command at a missing file. Expect a traceback or a usage error, then decide whether a cleaner message is worth a later weekend. It is not required for this cut.

Record the seven results in the receipt directory only after a real run. Until then, the plan and the script stay labeled as proposals. A green reading invented in the write-up would be the same class of defect the gate exists to catch.

Who should walk away

The regex misses spelled-out numbers and claims split across markup. A determined draft can smuggle a figure in an image or in HTML entities. The sample loader is a line scan, not a TOML parser, so a wrapped string can fool it. Those are reasons to keep the input small, not reasons to trust the script on a large corpus.

Do not use this path for pricing pages, incident reports, security advisories, medical text, or legal text. Do not use it as evidence in a launch review. Do not point a write-capable agent at the allowlist and call the result independent.

People who need signed provenance, citation graphs, or policy approval need a different system. People who want a model to retry until the exit code turns green are outside the cut. The red receipt is the feature that retry loop would automate away.

What shipped, on paper

The weekend artifact is a scope decision plus a proposed command. One note in. One allowlist. One receipt out. Hosting is a trailing option tied to a free server offer that must be re-read before use. Free model access, if still available, may label sentences once. It does not get to mint numbers.

That is a build log, not a product announcement. The demo is finished when an unsourced figure cannot pass, even if the optional page never goes up.

Stop After One Call: A Weekend Export Tour With a Hard Attempt Cap

Charlie Hu — Sun, 11 Oct 2026 22:01:36 +0000

A weekend agent demo is done when one lane returns one valid payload. Another call is a different project. This proposed build log keeps an export tour inside that limit: one canned file list, a local stub, an optional hosted run, and a hard cap of one attempt per lane.

The tour names exports from a folder list. It does not edit files, open a pull request, or rank assistants. The stub lane is the demo. The hosted lane is a switch that stays off until a URL has been checked the same day.

What the cut protects

Recent public discussion has treated model quality as the main variable and ordinary software work as an afterthought. That framing is a poor fit for a side project. The failure mode on a weekend is smaller and duller: an unset variable, a second call that quietly changes the result, or a paragraph that sounds finished while the JSON is wrong.

Path that stayed

The surviving path has four parts.

samples/exports.json stores the canned file list and sets allow_writes to false.
lane_runner.py runs a deterministic stub with no network.
--lane both may perform one hosted call when HOSTED_BASE_URL is present.
lane-report.json records the payload, the attempt count, and any skip reason.

Path that left

Work that did not survive the cut:

backoff, jitter, and a backup model
install, format, or commit steps
a vendor scoreboard
signup automation
any numeric claim about token grants, machine size, or how long a free tier lasts

The cut is the artifact. A longer prompt would only lengthen the skip list.

Working stub

The script in the next section is a proposal. It has not been executed for this article. No latency number is claimed, because none was measured.

Expected stub behavior is narrow. Given src/app.py, src/__init__.py, and README.md, the export list contains app and nothing else. attempts equals 1 and writes is empty. A visitor can inspect that result with the network disconnected.

A non-zero exit means the shape check failed. The demo is not mostly working in that case. The stub gets fixed, then the same command runs again. That later local run is a human edit cycle, not a model retry.

Commands for the local lane

mkdir -p samples
printf '%s\n' '{"allow_writes":false,"files":["src/app.py","src/__init__.py","README.md"]}' > samples/exports.json
python lane_runner.py --lane stub
python -m json.tool lane-report.json

Runner, one attempt per lane

#!/usr/bin/env python3
"""Proposal only. Not executed for this article. One attempt per lane."""

import argparse
import json
import os
import sys
import urllib.error
import urllib.request
from pathlib import Path

ROOT = Path(__file__).resolve().parent
SAMPLE = ROOT / "samples" / "exports.json"
REPORT = ROOT / "lane-report.json"
MAX_ATTEMPTS = 1


def load_sample() -> dict:
    data = json.loads(SAMPLE.read_text(encoding="utf-8"))
    if data.get("allow_writes") is not False:
        raise SystemExit("sample must set allow_writes to false")
    files = data.get("files")
    if not isinstance(files, list) or not files:
        raise SystemExit("sample needs a non-empty files list")
    return data


def stub_lane(sample: dict) -> dict:
    exports = []
    for name in sample["files"]:
        if name.endswith(".py") and not name.endswith("__init__.py"):
            exports.append(Path(name).stem)
    return {
        "exports": exports,
        "attempts": 1,
        "writes": [],
        "source": "stub",
    }


def hosted_lane(sample: dict) -> dict:
    base = os.environ.get("HOSTED_BASE_URL", "").rstrip("/")
    if not base:
        return {
            "skipped": True,
            "reason": "HOSTED_BASE_URL unset",
            "attempts": 0,
        }
    payload = json.dumps(
        {
            "files": sample["files"],
            "allow_writes": False,
            "attempts_allowed": MAX_ATTEMPTS,
        }
    ).encode("utf-8")
    req = urllib.request.Request(
        base + "/export-tour",
        data=payload,
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    try:
        with urllib.request.urlopen(req, timeout=8) as resp:
            body = json.loads(resp.read().decode("utf-8"))
    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
        # One failure ends the lane. There is no retry branch.
        return {"skipped": True, "reason": type(exc).__name__, "attempts": 1}
    body["attempts"] = 1
    body["skipped"] = False
    body["source"] = "hosted"
    return body


def problems(result: dict) -> list[str]:
    if result.get("skipped"):
        return []
    found = []
    if result.get("attempts") != 1:
        found.append("attempts must equal 1")
    if result.get("writes"):
        found.append("writes must stay empty")
    if not isinstance(result.get("exports"), list):
        found.append("exports must be a list")
    return found


def main() -> int:
    parser = argparse.ArgumentParser(description="Run one attempt per lane")
    parser.add_argument("--lane", choices=("stub", "both"), default="stub")
    args = parser.parse_args()
    sample = load_sample()
    report = {"demo": "export-tour", "max_attempts": MAX_ATTEMPTS, "lanes": {}}
    stub = stub_lane(sample)
    report["lanes"]["stub"] = {"result": stub, "problems": problems(stub)}
    if args.lane == "both":
        hosted = hosted_lane(sample)
        report["lanes"]["hosted"] = {
            "result": hosted,
            "problems": problems(hosted),
        }
    REPORT.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
    bad = [name for name, lane in report["lanes"].items() if lane["problems"]]
    if bad:
        print("failed lanes: " + ",".join(bad), file=sys.stderr)
        return 1
    print("wrote", REPORT)
    return 0


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

Report the runner should write

A passing stub report looks like the sample below. The values come from the canned file list, not from a live service.

{
  "demo": "export-tour",
  "max_attempts": 1,
  "lanes": {
    "stub": {
      "result": {
        "exports": ["app"],
        "attempts": 1,
        "writes": [],
        "source": "stub"
      },
      "problems": []
    }
  }
}

problems must be empty. A witty summary field is ignored on purpose, because the tour did not ask for one. Extra prose is how a weekend demo starts pretending to be finished.

Hosted lane, without invented limits

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

The operator brief for this draft describes MonkeyCode as an open-source project and supplies two availability claims: free model access, and a free server option. Both belong only to the hosted lane. They are not benchmark results.

This article names no model, states no token grant, describes no hardware, and does not say how long either option remains in place. No primary quota or pricing page was attached for a check on 2026-10-12. Stale numbers would be worse than silence, so the numbers stay out.

A free server, when the project still offers one, is a convenient place to boot this same runner. It does not raise MAX_ATTEMPTS. A failed free call is still one attempt. The skip reason goes in the report, and the process stops.

export HOSTED_BASE_URL="https://example.invalid"
python lane_runner.py --lane both
unset HOSTED_BASE_URL

example.invalid is a placeholder, not a service. It should be replaced only after the current project documentation has been read. Running the hosted lane before the stub is green reverses the weekend: the interesting failure moves onto a network, and the local bug stays hidden.

Situation	Lane to trust	What the report should show
No account, laptop only	stub	one stub result, hosted key absent
Host URL checked that day	both	hosted shape matches, or one recorded skip
URL missing or docs stale	stub	hosted skipped, attempts 0
Timeout or bad JSON	stub	hosted skipped, attempts 1, no second call
Demo needs writes or an SLA	neither	stop; this runner does not cover that

Free model access changes the location of the single call. It does not change the pass rule. Shape still beats fluency.

Order of work

The weekend order is fixed so the hosted option cannot sneak in early.

Write the canned file list and refuse writes in that file.
Run the stub lane until problems is empty.
Read the current host documentation. Stop if the free server option is unclear or gone.
Run --lane both once. Record a skip if the call fails.
Leave retries unimplemented.

A demo that starts at step 4 has no baseline. The stub result is the baseline. Hosted output is interesting only when it matches that shape or admits a skip.

This order also keeps a free model call from becoming the first test. The first test should pass on a laptop with the cable unplugged. That constraint is ordinary engineering, not a comment on any vendor.

What this weekend skips

The skip list is part of the log, not a second tool.

Retry helpers of every kind. One miss ends the lane.
Shell side effects, patches, and commits. The tour describes exports.
Multi-account orchestration and any script that signs a person up.
A comparison post against other assistants. One folder list cannot carry that weight.
Persistence past a single JSON report. There is no database in this demo.
Portfolio layout, launch copy, and a public uptime claim.

Those items can return on a later weekend. They are not required to show the export tour.

Checks before the demo is called done

The checks below describe control flow. They are not measured timings, and they were not executed for this article.

env -u HOSTED_BASE_URL python lane_runner.py --lane stub
env -u HOSTED_BASE_URL python lane_runner.py --lane both
python - <<'PY'
import json
report = json.load(open("lane-report.json"))
hosted = report["lanes"]["hosted"]["result"]
assert report["max_attempts"] == 1
assert hosted["attempts"] == 0
assert hosted["skipped"] is True
print("hosted lane skipped without a second call")
PY

One more check belongs on a scratch branch. Change stub_lane so attempts is 2, run the stub lane, and expect exit code 1. Revert the edit after the failure appears. That failure is the point of the cap.

A green process that called a host twice would be the bug the cap is meant to catch. The report is the place that bug should show up, as a non-zero exit rather than a second request.

Who should leave this approach alone

The cap is a scope lock for a side project. It is a bad default in other settings.

An on-call debug of idempotent reads, where a documented retry policy may be appropriate.
A procurement note that needs a contractual quota, a named model, or a hardware spec.
A security review. An empty writes list in a stub does not prove a real tool cannot touch disk.
A leaderboard, a hackathon ranking, or any claim that one canned file measures assistant quality.
A production agent with customer data. lane-report.json is not an audit log.

A free host makes the extra attempt feel cheap. Cheap is not the same as finished. Extra calls also risk rate limits that this draft refuses to guess.

The runner stays useful if every product name is removed. Keep the canned file list, the single attempt, and the report. A reader who still wants the hosted lane can read the project's current notes on free model access and the free server option, then decide whether that second command belongs in the same weekend.

One Status Card and a Three-Column Cut Log for a Weekend Agent Demo

Charlie Hu — Sat, 10 Oct 2026 18:40:57 +0000

A weekend agent demo fails when a second screen appears. One read-only status card, fed by one bounded fetch, is enough to show the path. Everything else belongs in a cut log, not in the repository opened on Saturday morning.

This build log keeps that cut explicit. It records what stays in the demo, what is deferred, and what is refused. It does not claim a production agent, a measured latency, or a hosting plan that will still be free next week.

The constraint that actually holds

Side-project agents expand by tool count. A status lookup becomes a ticket writer, then an email draft, then a schema change added for the demo. The room sees motion. The operator cannot point to the single call that was allowed to leave the machine.

Visibility is the constraint that survives the weekend. A stranger should be able to name the input, the output, and the stop condition from one card. When that explanation needs another panel, the scope has already slipped.

Public conversation this week has circled generated portfolios and the cost of trusting generated code. Those posts are topic signals, not sources for this log. The transferable lesson is narrower: a small artifact with a written cut list is easier to defend than a wide demo.

What the build keeps

The kept path is a read-only status card. The input is a local JSON fixture. The transform is a pure admission function. The output is a headline, a detail line, and the remaining call budget.

service is a short public name, such as billing-read.
state is one of up, degraded, or down.
checked_at is an ISO-8601 timestamp supplied by the fixture, never invented by a model.
budget_left is a local counter. It is not a provider invoice and not a token meter.

The card may describe a service state. It may not change that state. Network side effects and multi-step planning stay outside the Saturday repository.

A second service is not a small addition. It doubles the fixture rules, the failure copy, and the chance that a prompt picks up a field nobody reviewed. The build therefore stops at one name.

Where a hosted option is allowed to enter

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

Two availability claims are treated as operator-supplied for this draft: free model access, and a free server option. This log does not name models, invent a token quota, or treat hardware, duration, or pricing as stable. Those details change. The current project page is the source of truth before anyone moves a demo off localhost.

MonkeyCode participates only as an optional host for the one card. The admission logic is ordinary Python and does not require a hosted runtime. A hosted model is worth a look only when the weekend needs a short plain-language headline and the laptop will not stay open. A free server option is worth a look only after the operator confirms, the same day, that the option still exists and that the fixture contains no secrets.

Decision table

Situation	Decision	Reason
Fixture holds only public status fields	Local run is enough	No need to spend a hosted call
Headline must be one plain sentence	Hosted model is optional	Prompt stays limited to fixture fields
Free-server terms are unverified today	Stay on localhost	An availability claim is not a capacity plan
Prompt would include keys, customer text, or private logs	Refuse	Free access does not relax data rules
Demo needs a write, a payment, or an email send	Refuse this weekend	Out of scope, hosted or local
Quota, model name, or uptime is unknown	Do not print a number	Unverified figures go stale quickly

The table is a gate, not a ranking. It does not claim that one host is faster, cheaper, or more accurate than another. It states when a hosted option may enter the log at all.

The artifact

The module below is a proposed, unexecuted example. It has not been benchmarked, and it does not open a socket. It is the contract the demo should enforce before any hosted request is considered.

Secret rejection happens before the budget increments. A poisoned fixture should not burn the only Saturday admission. Incomplete fixtures are deferred for the same reason: a missing timestamp is a data bug, not a model task.

from dataclasses import dataclass, field

ALLOWED_STATES = {'up', 'degraded', 'down'}
REFUSED_KEYS = {'api_key', 'token', 'password', 'email', 'customer_id'}

@dataclass
class CutLog:
    kept: list[str] = field(default_factory=list)
    deferred: list[str] = field(default_factory=list)
    refused: list[str] = field(default_factory=list)

@dataclass
class Budget:
    limit: int = 3
    spent: int = 0

    def admit(self) -> bool:
        if self.spent >= self.limit:
            return False
        self.spent += 1
        return True

def reject_secrets(payload: dict) -> str | None:
    found = REFUSED_KEYS.intersection(payload)
    if found:
        return 'refused:' + ','.join(sorted(found))
    return None

def build_card(payload: dict, budget: Budget, log: CutLog) -> dict:
    secret = reject_secrets(payload)
    if secret:
        log.refused.append(secret)
        return {'ok': False, 'reason': secret}
    state = payload.get('state')
    service = payload.get('service')
    checked = payload.get('checked_at')
    if state not in ALLOWED_STATES or not service or not checked:
        log.deferred.append('incomplete-fixture')
        return {'ok': False, 'reason': 'incomplete-fixture'}
    if not budget.admit():
        log.deferred.append('budget-empty')
        return {'ok': False, 'reason': 'budget-empty'}
    log.kept.append('status-card')
    return {
        'ok': True,
        'headline': f'{service} is {state}',
        'detail': f'checked_at={checked}',
        'budget_left': budget.limit - budget.spent,
    }

A manual driver can sit in the same file. It is still a proposal, not a recorded test from this drafting session.

def _demo():
    log = CutLog()
    budget = Budget(limit=1)
    good = {
        'service': 'billing-read',
        'state': 'degraded',
        'checked_at': '2026-10-10T09:00:00Z',
    }
    bad = {
        'service': 'billing-read',
        'state': 'up',
        'checked_at': '2026-10-10T09:00:00Z',
        'api_key': 'do-not-send',
    }
    first = build_card(good, budget, log)
    second = build_card(good, budget, log)
    third = build_card(bad, Budget(), log)
    assert first['ok'] and first['budget_left'] == 0
    assert second['reason'] == 'budget-empty'
    assert third['reason'].startswith('refused:')
    assert 'status-card' in log.kept
    assert 'budget-empty' in log.deferred

Intended local check, after the file is saved as weekend_card.py:

python -m py_compile weekend_card.py
python -c 'import weekend_card; weekend_card._demo()'

If those asserts hold, the shape is one kept card, one deferred budget miss, and one refused secret. No latency number belongs next to that shape. A green local run also does not prove that a hosted rewrite will preserve the fixture.

Failure messages the card should show

A demo that only shows the happy path hides the gate. The card view should have three visible outcomes, each mapped from the function result.

Kept. Headline is the service name plus the state. Detail repeats checked_at exactly. Budget drops by one.
Deferred. Reason is incomplete-fixture or budget-empty. The view shows the reason and does not call a model to fill the gap.
Refused. Reason starts with refused:. The forbidden field value is not copied into the headline, the log, or a prompt.

That third outcome matters more than the headline. A weekend audience can forgive a dull sentence. It should not be shown a demo that forwards an api_key because the field happened to sit beside a status.

Render the reason in the same panel as the headline. A separate debug console will be ignored once the room is watching the card. If the reason cannot fit on the card, the scope is again too wide.

What this weekend skips

The cut log is part of the demo, not a footnote after the applause.

No write path. The card cannot open a ticket, restart a service, or edit a file outside the fixture.
No second tool. Search, shell, and mail stay deferred even if a hosted server would make them easy to attach.
No model-name theater. String formatting already produces a true headline from the fixture. A hosted model may rephrase that headline later, and only after the gate passes.
No quota on the slide. If a free allotment exists, its size is whatever the project page says on demo day, not a number frozen into this article.
No multi-service map. One service name is the whole stage. A second service is a second weekend.

Deferred work can return later. Refused work should not return under a renamed prompt. Renaming api_key to notes is a bypass, not a scope change, and the weekend rule is to stop rather than teach the filter a new synonym list.

Manual test plan

Run this plan before anyone else sees the card.

Load a fixture with only service, state, and checked_at. Confirm ok is true and budget_left drops by one.
Repeat the same fixture until the budget returns budget-empty. Confirm no extra headline is produced.
Add api_key to a copy of the fixture. Confirm the reason starts with refused: and the value never appears in headline.
Remove checked_at. Confirm the result is incomplete-fixture, not a guessed timestamp.
Pass an unknown state such as maybe. Confirm it is deferred, not coerced to up.
If a hosted call is still desired, send only the three allowed fields. Compare the returned sentence with the local headline. Keep the local headline if the hosted one adds a claim that was not in the fixture.
Re-read the project page the same day for free model access and the free server option. If either claim is gone or newly qualified, leave the demo on localhost.

Step 6 is the only point where a hosted model should see data. If that comparison is skipped, the demo has not tested the host. It has only tested the laptop.

Limitations, and who should walk away

This approach is a weekend gate. It is not an evaluation harness, a security review, or a capacity plan.

The budget counts local admissions, not provider tokens. A real hosted call can consume more than one unit even when this script records one.
Free access can be rate-limited, region-limited, or withdrawn. A demo script must not promise that a server will still be free on Monday.
The secret check is a key-name filter. It misses secrets stored under unusual names, inside nested text, or in a fixture comment. Treat it as a tripwire, not a scanner.
String formatting can still embarrass the operator if service contains markup. Escape the value before any HTML render.
No accuracy benchmark is claimed. Do not cite this log as evidence that a hosted model is correct.
The example timestamp is fixture data. It is not a record of a live incident.

Walk away when the audience needs write access, when the fixture holds private data, when compliance requires a named retention period, or when the demo cannot proceed without a guaranteed quota. Those projects need a reviewed environment and a written contract. A Saturday card will not supply either.

Teams that already have a staging gate, a secret scanner, and an on-call path also do not need this log. The module would duplicate lighter checks they already run, without adding the audit trail those systems keep.

How to file the log

Keep three short lines in the repository README, next to the module. Update them when the scope changes. Do not let the README drift ahead of the code.

Kept: read-only status card from three fixture fields, local budget of one to three admissions.
Deferred: hosted headline rewrite, second service, any tool beyond the pure function.
Refused: secrets in the prompt, write actions, printed quotas that were not checked the same day.

If a hosted pass is used, add one more line: the date the project page was read, and whether free model access and the free server option were still stated. Omit the line rather than guess. A missing line is easier to explain than a stale number.

Closing the log

The working demo is the card plus the cut log. The skipped work is the result that matters: a second screen, a write tool, and an unverified number never earned a place in the build. Operators who still want a hosted pass can set MonkeyCode's current free-model and free-server terms beside the decision table, and stop when the page and the table disagree.

Leave the Write Path at Home: One Read, a Route Contract, and a Skip Ledger

Charlie Hu — Fri, 09 Oct 2026 15:03:27 +0000

A weekend agent demo stays showable when the public slice does one read, rejects every write, and fails closed if that contract drifts. A larger prompt does not create that boundary. A route contract, a skip ledger, and a checker that runs before any process listens do. This build log treats that cut as the whole product for the weekend. Hosting and a model call stay optional, and every skipped write is named before the demo starts.

The failure mode is familiar. A second tool appears, a scratch file changes, and the walkthrough cannot be repeated from a clean directory. Moving that surface onto a free server does not repair it. The host only makes the unfinished path easier for someone else to open.

The cut this log actually ships

The working slice is small on purpose.

One user-facing path looks up a note by id.
One optional model call summarizes that same note.
Mutating tools stay at zero.
A skip ledger records what was not built, and why.

That list is the product. A portfolio page, a multi-step agent, or a write-back bot is a different weekend. Those ideas can wait in the ledger without being smuggled into the handler "just for the demo."

What "done" means before noon

Done is a local GET that returns one note, a POST that returns 405, a contract file that names both results, and a checker that exits zero. A free server is not part of done. It is a later choice, used only if the local contract still holds.

The samples below are a proposal for that cut. They are not a recorded run from this account, and the note text is illustrative.

The working read path

The process binds to localhost first. Nothing in the handler creates, updates, or deletes a note. Unknown ids return 404. Unknown paths return 404. Writes return 405 even if a client guesses a route that might exist next weekend.

# demo_app.py — proposal, not a recorded service
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
import json

NOTES = {
    "n1": "One read. No writes. Every skip is written down.",
}

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path.startswith("/notes/"):
            note_id = self.path.rsplit("/", 1)[-1]
            text = NOTES.get(note_id)
            body = {"id": note_id, "text": text}
            status = 200 if text else 404
        else:
            body, status = {"error": "only /notes/{id}"}, 404
        raw = json.dumps(body).encode()
        self.send_response(status)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(raw)))
        self.end_headers()
        self.wfile.write(raw)

    def do_POST(self):
        self.send_error(405, "writes are out of this weekend's cut")

    def do_PUT(self):
        self.send_error(405, "writes are out of this weekend's cut")

    def do_DELETE(self):
        self.send_error(405, "writes are out of this weekend's cut")

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

The local check is a plan, not a published timing result.

python3 demo_app.py
curl -sS http://127.0.0.1:8765/notes/n1
curl -sS -o /dev/null -w "%{http_code}\n" -X POST http://127.0.0.1:8765/notes/n1
curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8765/notes/missing

The expected shape is simple. The first request returns the note. The second returns 405. The third returns 404. If any of those differ, the weekend stops. No extra route is added to make the demo feel larger.

A route contract the checker can fail

A contract file sits beside the app. It is the source the checker trusts, not the README. If the file and the handler disagree, the file wins and the process does not get a public bind.

# demo_contract.yaml — illustrative flat file
listen: 127.0.0.1
port: 8765
allowed_methods: ["GET"]
allowed_paths: ["/notes/{id}"]
model_calls_max: 1
tools_effect: read
skip_ledger: skips.md

# check_contract.py — proposal, flat keys only
import sys
from pathlib import Path

REQUIRED = ("allowed_methods", "allowed_paths", "tools_effect", "skip_ledger", "listen")
WRITE_MARKERS = ("POST", "PUT", "PATCH", "DELETE")

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

def main(path: str) -> int:
    contract_path = Path(path)
    data = load_flat(contract_path)
    missing = [key for key in REQUIRED if key not in data]
    if missing:
        print("missing:", ", ".join(missing))
        return 1
    methods = data["allowed_methods"].upper()
    if any(marker in methods for marker in WRITE_MARKERS):
        print("write method is outside the weekend cut")
        return 1
    if data["tools_effect"] != "read":
        print("tool effect must stay read")
        return 1
    if data["listen"] != "127.0.0.1":
        print("listen must stay on localhost until the local check passes")
        return 1
    ledger = contract_path.parent / data["skip_ledger"]
    if not ledger.is_file() or not ledger.read_text().strip():
        print("skip ledger missing or empty")
        return 1
    print("contract ok")
    return 0

if __name__ == "__main__":
    target = sys.argv[1] if len(sys.argv) > 1 else "demo_contract.yaml"
    sys.exit(main(target))

printf "- No note creation: a write needs validation and undo.\n" > skips.md
python3 check_contract.py demo_contract.yaml

Why the parser stays tiny

The loader ignores indented lines and does not understand nested YAML. That is a limitation, not a hidden feature. If the contract grows nested keys, this checker will pass a file it did not actually read. The next change, if one is earned, is a real parser plus a fixture file. Until then the contract stays flat, and the limitation stays in the build log.

Decision table for the weekend

Choice	This weekend	Left out	Reason
GET `/notes/{id}`	Keep		The walkthrough has a start and an end
One summary of that note	Optional		Shows model access without a tool loop
Create or edit notes		Skip	A write needs validation, storage, and undo
Accounts on a public host		Skip	A free server demo is not an identity system
Live secrets in the tree		Skip	The demo must run without production credentials
Latency table		Skip	This proposal has no measured timings

The table is the review surface. A teammate can reject a row without reading the handler. If a row cannot name a reason, it does not belong in the cut.

Where free model access and a free server fit

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

MonkeyCode enters this method in one place. A side project can use its free model access and its free server option after the localhost contract already passes. Those two availability claims are the only product facts this log uses. Model names, token quotas, hardware size, and how long a free option lasts are not assumed here. They change, and a weekend plan that hard-codes them will go stale before the demo is shown.

The sequence stays ordered.

check_contract.py exits zero on a clean tree.
The GET and the rejected POST both match the expected status codes on 127.0.0.1.
Only then is a free server considered.
The same contract travels with the process. Spare capacity is not a reason to add a write route.
The single model call uses whatever free model access the current docs list. If that list is empty, the note lookup still ships.

The lookup is the demo. The summary is color. A missing model must not expand the tool list, and a free host must not become the place where an untested write is tried "because the machine is already up."

Before any bind past localhost, the operator reads the current project documentation and stops if the documented limits do not cover a one-call read. No quota figure in a chat thread replaces that check.

What the skip ledger holds

The ledger is a file in the tree, not a memory of what felt hard on Saturday.

Note creation stays out, because a write path needs validation and a rollback story.
A tool loop stays out, because a second call hides cost and makes the walkthrough non-deterministic.
Login stays out, because accounts on a public free server are a different product.
A benchmark table stays out, because this proposal was not timed.
Any claim that a free option is permanent stays out, because permanence was not verified.

Skipped work is still work. Naming it keeps the next weekend from pretending the cut was an accident.

# skips.md
- No create/update/delete: needs storage and undo.
- No second model call: one summary is the ceiling.
- No accounts: public hosting is not an identity system.
- No quota or hardware claims: confirm current docs instead.

Who should not use this cut

This approach is a bad fit when the side project is the write. A form that must save data, a bot that must open a pull request, or a demo whose point is multi-step tool use will be distorted by a read-only contract. Forcing those projects through this checker produces a demo that cannot show the actual behavior.

Teams that need audited production controls should not treat the script as a security review. It does not parse full YAML, does not scan dependencies, and does not prove that a model will refuse a harmful request. It only checks a flat contract and an empty-or-missing ledger.

Anyone pasting live credentials into the demo to see whether a free server responds is outside the method. The read path is designed to run without production tokens. A secret that appears in the tree has already failed the weekend, even if the HTTP status codes look right.

Close the weekend on the contract

The weekend ends when one GET works, one write is rejected, the skip ledger is non-empty, and the checker exits zero. Hosting and model access remain optional layers on top of that result. Readers who want to try the same cut can review MonkeyCode's current free model access and free server option, then confirm the docs before binding anything past localhost.

DEV Community: Charlie Hu

Weekend Build Log: A Clock-Gated Cut List for a One-Weekend Release-Notes Bot

Why a checklist loses to a clock

The artifact: a cut list with three states

State rules that survive contact with a real weekend

checkpoint.py: the gate that refuses work

The demo-path smoke test, with the model faked

Wiring the real transport once

Preflight before the demo, on a free server

What got skipped, and why that was the point

Limitations and known failure modes

Who should not use this approach

Reproduce it in six steps

Reserve, Then Reconcile: A Token Ledger That Stops a Free-Tier Side Project at the Cap

What shipped, and what was cut

The core idea: charge the estimate, reconcile with the actual

The guard wrapper and the timeout rule

Tests that a dashboard cannot replace

Deploying to the free server: one smoke test, one uncomfortable finding

Choosing between three controls

Where the free tier actually fits

Limitations and who should skip this

Weekend Build Log: Expiring Feature Flags That Cut Scope at Runtime

Weekend Build Log: Expiring Feature Flags That Cut Scope at Runtime

Why planning cuts decay

Rule one: every feature carries an expiry

Rule two: expiry is enforced in the request path

Rule three: prove it with a test that never waits

Rule four: refuse to deploy flags that outlive the demo

The cut policy

Where the free server and free model access change the math

What got skipped

Limitations and who should not do this

Closing note

Weekend Build Log: Rehearsing a Free-Tier AI Demo With Four Injected Faults

The build, and the cut that made it fit two days

The cut list, written before any code

Artifact 1: a model endpoint that misbehaves on command

Artifact 2: one attempt, one budget, one honest fallback

Artifact 3: the rehearsal suite

Where the free model access and the free server option fit

A dated smoke log instead of a stale claim

What the demo skips, and who should not copy this

Weekend Build Log: An Idempotent Batch Worker for a Free-Model Side Project

The scope cut, before any code

The failure worth designing for

The artifact: one worker, four policies

Why the key is a content hash

A retry decision table

Where the runs actually live

What this approach does not give you

Weekend Build Log: A Model-Swap Harness for a Side Project on Free Endpoints

The scope cut came first

What shipped: one file, twelve cases, three commands

The case file

The runner

The diff

The swap test plan

Reading the diff without overclaiming

Where free access and a free server fit

Limitations and who should not use this

The skip list, with un-skip triggers

Sunday night checklist

Weekend Build Log: A Cold-Start Test for Free-Tier Demo Hosts

The scope cut: three tiers, one weekend

Why free hosts break demos in three specific ways

Artifact 1: the cold-start probe

Artifact 2: the durability probe

Artifact 3: the triage table

Where free model access fits

What got skipped, on purpose

Limitations and who should not use this

Sunday-night runbook

A Machine-Checked Scope Budget for One-Weekend AI Demos

A Machine-Checked Scope Budget for One-Weekend AI Demos

Rule one: the golden path is a command, not a paragraph

Rule two: the plan is a file a script can reject

Rule three: keep one network dependency in the path

The cut table

What this weekend skipped, on purpose

`checkpoint.py`: the gate that refuses work