The build

• Your first agent: what you are installing, and why it starts in a folder holding nothing you would miss.
• Terminal: where you type all of this.
• Working directory: why the agent only sees this folder.
• Exit code: how you tell whether something worked, without trusting the words around it.
• stdin, stdout and stderr: why an error can go somewhere other than the screen.
• Interpreter and runtime: what Bun is doing with your file.

• claude --versionCopy

  Install the agent first, as Your first agent shows: it takes one line from the vendor’s page, and you need a paid plan. This prints a version number. If it says command not found, open a new terminal.

• bun --versionCopy

  Bun runs the code. Install it with the line on bun.sh, then open a new terminal. This prints a version number.

• mkdir kitty && cd kitty && pwdCopy

  Makes the folder, moves into it, and prints where you are. Everything from now on happens here.

• claudeCopy

  Starts the agent in this empty folder. Paste the words below into it.

Writes one file of about 40 lines, runs it once, and tells you what it made. It will ask before running a command: read the sentence it gives you, then say yes. Ours finished in 13 seconds and wrote no other files.

1. Open split.ts in any editor. Find the two lines that work out the base share and the leftover pence.
2. Find the line that prints the error, and the line after it that sets the exit code.
3. Find the comment saying why the shares always add up. You should be able to say it back in your own words.

• bun split.ts 1000 3; echo "exit $?"Copy

  334, 333 and 333 on three lines, then exit 0.

• bun split.ts banana 3; echo "exit $?"Copy

  A one-line error, then exit 1. That 1 is the machine saying no.

• bun split.ts 1000 0 2> err.txt; echo "exit $?"; cat err.txtCopy

  The screen stays quiet and says exit 1, and the error is in err.txt. You sent stderr to a file.

• bun: command not found. Your terminal started before Bun was installed. Open a new one.
• The agent wants to run something you don’t understand. Say no, and ask it what that command does and why. That is allowed at every stage of this course.
• It adds a package or a package.json. You asked for neither. Tell it so. Noticing this is the skill.

To undo this stage: Nothing here can hurt anything else. Delete the kitty folder and start again.

Predict, then run.

1. Close the agent with /exit.
2. On paper, write what bun split.ts 1 3 will print, and what bun split.ts 7 2 will print.
3. Run both. If you were wrong, read the two lines that do the sums until you can say why.
4. Run ls -a and say out loud what each thing in the folder is.

Done when: You predicted 1, 0, 0 and 4, 3, and you can explain why someone can owe 0p.

• No commit yet: git arrives in stage 3.Copy

  What you commit by hand. The agent's own commits are already on the branch.

• No row yet. The log arrives in stage 3.Copy

  The row you add to docs/ratchet-log.md, with your own date, your own words and your own commit hash. If what went wrong for you was different, write that instead.

• Localhost: why this server is only reachable from your machine.
• HTTP method: GET reads and POST sends.
• Status code: the prompt asks for 200, 400 and 422 by number. Vague wishes get a 500.
• JSON: what goes in and out of the API.
• Framework: what Hono is for.
• curl: how you test a route with no browser.
• Dependency: this is the first code you did not write.
• Lockfile: the file that records exactly what you installed.

Installs Hono, moves the sums into src/split.ts, writes src/server.ts with the page and the routes, starts it, runs curl five times, and stops it. Ours took about 5 minutes. It admitted it had not opened the page in a browser, so you do that.

1. package.json: is Hono the only dependency? Our run brought in one package.
2. src/split.ts: did the sums move without changing?
3. In src/server.ts, find the place that returns 400, and the place that returns 422. They are different mistakes.
4. Find what runs in the browser (the script inside the page) and what runs on the server.

• bun run devCopy

  In one terminal. It keeps running. Leave it, and open a second terminal for the rest.

• curl -i localhost:3000/api/healthCopy

  HTTP/1.1 200 OK, then headers, then a blank line, then {"ok":true}. Name each part: status, headers, body.

• curl -i -X POST localhost:3000/api/split -d '{"totalPence":1000,"people":3}'Copy

  200 with {"shares":[334,333,333]}.

• curl -s -o /dev/null -w "%{http_code}\n" -X POST localhost:3000/api/split -d 'not json'Copy

  400.

• curl -s -o /dev/null -w "%{http_code}\n" -X POST localhost:3000/api/split -d '{"totalPence":10.5,"people":2}'Copy

  422.

• EADDRINUSE: port 3000 is taken. Something else is using it, often your own earlier server. Stop that with Ctrl-C in its terminal, or ask the agent to change the port.
• The agent leaves its server running in the background. Your own bun run dev then fails with the error above. Ask it to find and stop the process it started.
• It says "works" without having opened the page. Open localhost:3000 in a browser and press the button yourself. Open the Network tab in DevTools and find the POST.

To undo this stage: There is no git yet. Ask the agent to put split.ts back as it was, or start this stage again from a copy of the folder. This is the moment you start wanting stage 3.

Predict five status codes.

1. Close the agent. Keep the server running.
2. Write down the status you expect for: GET /api/split, POST /api/split with people set to 0, POST with no body, GET /nope, and GET /api/health.
3. Run each with curl -i and mark each guess right or wrong.
4. Point at one thing on the screen and say whether it ran in your browser or on the server, and how you know.

Done when: Your five guesses are written down with the real answers. In our run GET /api/split gave 404, which we had not predicted. No GET route exists at that address.

• No commit yet: git arrives in the next stage.Copy

  What you commit by hand. The agent's own commits are already on the branch.

• No row yet. The log arrives in stage 3.Copy

  The row you add to docs/ratchet-log.md, with your own date, your own words and your own commit hash. If what went wrong for you was different, write that instead.

• Repository: what git init makes.
• Commit: your undo points.
• Staging area: how one commit can hold only what you meant.
• .gitignore: keeps installed packages and secrets out for good.
• Commit message: the prompt asks for why as well as what, because later agents read these.
• Diff: what you will read at every later stage.
• Reflog: the real undo. The proof step below depends on it.
• Remote: where your history goes when your laptop dies.

Writes .gitignore first, then makes four small commits with bodies explaining why, then shows you the log. Ours took 1 minute. It may add a Co-Authored-By line to each message, which is honest and worth keeping.

1. git log, with the bodies: does each message say why? Rewrite any that only repeat the diff.
2. git status: node_modules, *.sqlite and err.txt must not appear.
3. git show --stat on each commit: is each one a single idea?

• git log --onelineCopy

  Four lines, newest first.

• git diff --stat HEAD~1 HEADCopy

  Only docs/ratchet-log.md changed in the last commit.

• git status --shortCopy

  Nothing at all, which means everything is committed or ignored.

• git: please tell me who you are. Run git config --global user.name and git config --global user.email with your own details, once.
• It commits node_modules. Your .gitignore came too late. Ask it to remove them from the index with git rm -r --cached node_modules and to add the ignore, in a new commit.
• A commit message says "update files". Ask for a new message with git commit --amend, only while the commit has not been pushed.

To undo this stage: To undo the agent’s last commit but keep the work, run git reset --soft HEAD~1. To go back further, use git reflog.

Lose work on purpose, then get it back.

1. Close the agent.
2. Run git reset --hard HEAD~2, then ls. Your README and ratchet log are gone.
3. Run git reflog and find the commit from before the reset. Run git reset --hard HEAD@{1}. They are back.
4. Now add a line to src/split.ts without committing, and run git reset --hard. Look in git reflog for your edit. It isn’t there, because it was never a commit.
5. Make a place to push: create a public repo on GitHub with no files in it, then git remote add origin with its address, and git push -u origin main. A public repo is free, and you will want to show this one.

Done when: You can say, from having done it, what comes back and what doesn’t.

• No extra commit: the agent made the four.Copy

  What you commit by hand. The agent's own commits are already on the branch.

• No row yet. The table is empty, and the next stage fills it.Copy

  The row you add to docs/ratchet-log.md, with your own date, your own words and your own commit hash. If what went wrong for you was different, write that instead.

• Reading code: you follow one path, not the whole file.
• Reproduction: first make it fail every time.
• Minimal reproduction: then find the smallest input that does.
• Hypothesis: write down what you think, and what would rule it out.
• Logging: how you look inside without a debugger.
• Root cause: fix the cause and not the symptom.
• Test: you write your first one by hand here. Chapter 10 comes later, and this one is short.

Changes one line, commits it with a message that tells you nothing, writes the answer to a file you do not open, and replies with one word. It is told to keep the obvious case working, so your first check will pass.

1. Nothing. Reading the diff is cheating here, and git diff main seeded-bug would hand you the answer. Save it for the end.

• bun split.ts 1000 3Copy

  334, 333, 333, exactly as before. The bug is still there.

• for t in 1 2 3 7 10 11 99 100 101 999 1001 1002; do echo "$t: $(bun split.ts $t 3 | tr '\n' ' ')"; doneCopy

  Add each row up in your head. A rule that must always hold is the best bug-finder there is: shares add to the total, there is one per person, and no two differ by more than 1p.

• Your first check passes, so you think there is no bug. That is why this is useful. Our seeded bug passed a sum check at some inputs and failed at others. Try more inputs, more people, and an odd total.
• You can’t find it after 40 minutes. Try halving: add console.log of each intermediate value to src/split.ts, with a label. If you are still stuck, open the answer file, then close it and write the test anyway.
• bun test says no tests found. The file has to be named something.test.ts.

To undo this stage: Everything happens on the seeded-bug branch. git switch main puts you back, and git branch -D seeded-bug deletes the branch.

This whole stage is the proof. Find it with the agent closed.

1. Close the agent. Do not open .seeded-bug-answer.txt.
2. Find an input that fails, and write it down. That is your reproduction.
3. Write one sentence saying what you think is wrong, and what would rule that out.
4. Write src/split.test.ts by hand: import { expect, test } from "bun:test", import splitPence, and check that for several totals the shares add up to the total. Run bun test and watch it fail.
5. Fix the line. Watch the test go green. Then open the answer file and see whether you were right.
6. Commit on the branch, then git switch main and git merge --no-ff seeded-bug, and push.

Done when: You have a test that failed before your fix and passes after it, and you found the line yourself. Ours was Math.round where Math.floor belonged: 1001p between 3 came to 1004p.

• test: add split invariants, fix rounding in splitPence Round-to-nearest gave wrong totals whenever the fraction was .5 or more: 1001p between 3 came to 1004p. Found by hand by checking the sum over many inputs. 1000 between 3 hid it, because 333.33 rounds down.Copy

  What you commit by hand. The agent's own commits are already on the branch.

• | 2026-11-05 | A seeded Math.round in splitPence: 1001p between 3 came to 1004p, and the one case I tried by eye hid it. | src/split.test.ts checks that the shares add up to the total over several inputs. | f59593c |Copy

  The row you add to docs/ratchet-log.md, with your own date, your own words and your own commit hash. If what went wrong for you was different, write that instead.

• Hallucination: it will name packages that don’t exist, with total confidence.
• Slopsquatting: why an invented name is dangerous, and not only wrong.
• Token: what you are billed in.
• Prompt caching: nearly all of your input tokens will come from cache.
• Token cost: you work out the bill by hand here.
• Model tiers: we used the cheapest rung, and it was enough for this.
• Headless mode: running a task from a script, so you get a file with the numbers in it.

• mkdir -p docs/runsCopy

  Somewhere to keep what this stage produces.

• claude -p "$(cat first-prompt.txt)" > docs/runs/ofx-names.txtCopy

  Save the first prompt below as first-prompt.txt, then run this. No session, no chat: one answer in a file.

• claude -p "$(cat task.txt)" --model claude-haiku-5-5 --output-format json --max-budget-usd 2 --permission-mode acceptEdits --allowedTools "Read,Edit,Write,Glob,Grep,Bash(bun *),Bash(git *)" > docs/runs/storage-run.jsonCopy

  Save the second prompt as task.txt, then run this. It runs with no questions and can only use bun and git, so it stops at anything else. Ours took 3 minutes and cost $0.03 at list price. Delete first-prompt.txt and task.txt when it has finished.

For the first prompt, 15 confident names. For the second, six small commits on a new branch: the tables, a pure balance function, the routes and 19 tests. It stated plainly what it had not tested: starting the real server, and whether the data survives a restart. Those are yours.

1. src/balances.ts first. It is pure sums, with no database. Follow one bill through it.
2. src/db.ts: are amounts INTEGER? Are foreign keys on?
3. Its list of decisions you did not ask for. Ours decided every bill splits between everyone, and that leftover pence go to the first member.
4. Skim the routes in src/server.ts for the order of checks: 404, then 400, then 422.

• for name in $(cat docs/runs/ofx-names.txt); do printf "%s %s\n" "$(curl -s -o /dev/null -w "%{http_code}" https://registry.npmjs.org/$name)" "$name"; doneCopy

  200 means the name exists, 404 means it was invented. Ours: 9 of 15 were 404. Existing proves little either, so open one of the 200s and check it does what was claimed.

• jq "{cost: .total_cost_usd, turns: .num_turns, usage: .usage}" docs/runs/storage-run.jsonCopy

  The cost, turns and tokens by kind. Ours: 76 input, 1,319,977 cache read, 37,467 cache write, 25,604 output.

• bun testCopy

  All pass. Ours: 19.

• bun run devCopy

  In a second terminal, create a group and an expense with curl, read the balances, then stop the server and start it again, and read them once more. They should still be there. That is the thing the agent did not test.

• Permission denials in the JSON. With a narrow allowlist it could not run timeout, or start the server. That is the allowlist doing its job. It told us so honestly, and we ran that check ourselves.
• total_cost_usd looks like a bill. On a subscription you are not charged that number. It is what the tokens would cost at API prices, and that is still what you want to know.
• Your names are all real. Good, and models differ. Try a stranger file format. The habit is what you are after.

To undo this stage: The work is on the storage branch. git switch main leaves it there, and git branch -D storage throws it away.

Recompute the bill by hand.

1. Close the agent.
2. Take the token counts from storage-run.json, by kind. modelUsage in the same file has the exact input count.
3. Use the prices from Model tiers. Haiku 5.5 was $0.10 and $0.50 per million when we read it. Cache reads cost a tenth of input, and one-hour cache writes cost double, which is what makes our sum agree.
4. Add them up on paper. If your number differs from total_cost_usd, find out why.
5. Work out what share of the input came from cache.

Done when: A short table in docs/runs/ agrees with total_cost_usd. Ours: 0.000176 + 0.0128 + 0.0132 + 0.0075 = $0.0337 against a reported $0.0337, with 97% of input from cache.

• docs: record what the storage task cost and which package names were real 9 of the 15 OFX package names the model listed returned 404 from the registry. Storage task: $0.034 on claude-haiku-5-5, 97% of input tokens from cache.Copy

  What you commit by hand. The agent's own commits are already on the branch.

• | 2026-11-05 | Asked for 15 npm packages to read OFX files, and 9 of the names do not exist on the registry. | Check every suggested package name against the registry before installing. Still only a habit. | 651e022 |Copy

  The row you add to docs/ratchet-log.md, with your own date, your own words and your own commit hash. If what went wrong for you was different, write that instead.

• AGENTS.md and CLAUDE.md: the file every session reads first. Yours traces to real mistakes.
• Hook: code that runs before a tool does, and can say no.
• Permission modes: when it asks, and when it doesn’t.
• Allowlist: what it may do without asking.
• Destructive actions: what you are blocking.
• Fail closed: a guard that breaks should say no.

Writes AGENTS.md from your ratchet log, then the hook and the settings, then tests the hook by piping JSON into it and shows you a table. Then, in the second session, it tries the delete and gets refused. It will stop and ask before writing inside .claude/. Read what it is writing, and say yes.

1. AGENTS.md: is each rule from your log? Delete anything that is general advice.
2. .claude/hooks/block-destructive.sh: find where it says exit 2. Find what happens if jq fails.
3. .claude/settings.json: find your deny rules.
4. Its list of what the hook doesn’t catch. Believe that list.

• printf '{"tool_input":{"command":"rm -rf src"}}' | bash .claude/hooks/block-destructive.sh; echo "exit $?"Copy

  A one-line reason, then exit 2.

• printf '{"tool_input":{"command":"bun test"}}' | bash .claude/hooks/block-destructive.sh; echo "exit $?"Copy

  exit 0.

• printf 'not json' | bash .claude/hooks/block-destructive.sh; echo "exit $?"Copy

  exit 2, because it fails closed.

• jq: command not found. The hook will then refuse everything, which is correct, and annoying. On a Mac, brew install jq.
• It says it can’t write in .claude/. That is the agent’s own protection. Claude Code treats that folder as sensitive and asks you. In a session, say yes when it asks. With claude -p there is nobody to ask, so it stops. We hit exactly this.
• It answers only half the second prompt. Ours reported the hook firing and skipped the question about tests. Ask again. A fresh session answering it is the real test of your AGENTS.md.

To undo this stage: git switch main leaves it on the agent-rules branch. If the hook locks you out of something you meant to do, run that command yourself in your own terminal. The hook only sees the agent’s commands.

Attack your own hook.

1. Close the agent.
2. Feed the hook each of these by hand and write down its exit code: rm -r -f src, find src -delete, a python one-liner that calls shutil.rmtree, bash scripts/wipe.sh, X=rm; $X -rf src, git clean -fdx, git checkout -- .
3. For each one that gets through, say what really protects you: a commit, a backup or the sandbox.
4. Delete the throwaway folder by hand, since it was refused.

Done when: A table in docs/ names which spellings the hook stops. In our run, six of those seven got through: rm -r -f was stopped, and find -delete, python, a script file, X=rm, git clean and git checkout were not.

• docs: record which deletes the hook cannot stopCopy

  What you commit by hand. The agent's own commits are already on the branch.

• | 2026-11-05 | My hook stopped rm -rf, but six other ways of deleting a folder walked straight past it when I tried them by hand. | The list is in docs/. Commits and backups cover those, and stage 9 replaces this hook with a stronger one. | your commit |Copy

  The row you add to docs/ratchet-log.md, with your own date, your own words and your own commit hash. If what went wrong for you was different, write that instead.

• Context budget: test output stays in the window and is paid for on every later turn.
• Context-efficient output: what the wrapper is for.
• Starting fresh: you start empty on purpose.
• Handoff note: how work survives an empty session.
• The repo as the system of record: if it is not in the repo, the next session does not know it.
• Instruction budget: why AGENTS.md stays short.

• /contextCopy

  Type this at the start of a session, before anything else. It lists what is already in the window. Ours: AGENTS.md at 470 tokens, and 95% free. Write down the three biggest items.

Writes the wrapper and measures it. Then it builds the settle-up function, stops, and writes a handoff note. Then, in a new session, it reads only that note, says what it would do and what it would avoid, and finishes the route.

1. scripts/quiet.sh: does it keep the exit code? Find the line.
2. docs/handoff.md: mark each claim true or false by running what it says. A note that lies is worse than no note.
3. The new session’s answer: did it get anything wrong? Did it have to rediscover anything?
4. src/settle.ts: it says greedy and not minimum. Does the agent’s description match that?

• bun test 2>&1 | wc -c; bun run check 2>&1 | wc -cCopy

  Two byte counts. Ours: 104 and 46. Honestly small, because bun test is already quiet when it isn’t attached to a terminal. The wrapper earns more on noisy tools later.

• bun run check; echo "exit $?"Copy

  A ✓ line and exit 0.

• bun test src/settle.test.tsCopy

  Seven pass, as the note said.

• The handoff note is long. Ours was. Cut anything the code says. Keep what failed and what is next.
• The new session lists things to avoid that don’t matter. That is the point of the test: you find out what your note implied. Fix the note, not the agent.
• You lost the session before writing the note. Then it is gone, apart from what got committed. This is why the note goes in the repo.

To undo this stage: The work is on two branches, context-tools and settle-up. git switch main leaves them both behind.

Check the note with the agent closed.

1. Close the agent.
2. Read docs/handoff.md and run each command it gives, in order.
3. Find one thing it left out that you had to look up, and add it.
4. Merge: git switch main && git merge --no-ff settle-up && git push.

Done when: The note matches what you saw, and you could hand it to a colleague.

• docs: correct the handoff note after checking it by handCopy

  What you commit by hand. The agent's own commits are already on the branch.

• No row unless something went wrong. Ours went well, and an empty row would be a lie. Leave it out.Copy

  The row you add to docs/ratchet-log.md, with your own date, your own words and your own commit hash. If what went wrong for you was different, write that instead.

• Have it interview you: it asks what you would be annoyed to find it had guessed.
• Spec: the decisions, in a file, that outlast this session.
• Acceptance criteria: each one is something a program can check.
• Non-goal: what stops it building too much.
• Constraint: Web Crypto only, because it has to run on Cloudflare later.
• Vertical slice: the thinnest thing that really works from end to end.
• Stop condition: so it stops when the tests pass, and does not start on something else.
• Ask, don't guess: where it should stop and ask you.

Reads the code, then asks about five good questions. It noticed for itself that nothing links a member to a person who could sign in. Then it writes SPEC.md with about 30 criteria. In a new session it builds accounts only, in about nine commits, with one test per criterion. It will end by asking you something: ours asked whether changing a password should need the current one.

1. SPEC.md, all of it, slowly. This is the most useful thing you read in the whole course. Argue with it.
2. src/accounts.ts: find the hash and the session token. Is the plain password ever stored?
3. In src/accounts.test.ts, do the test names line up with AC1 to AC11?
4. Did it stop? It should not have touched groups.

• bun test src/accounts.test.tsCopy

  Eleven tests or more, named AC1 to AC11.

• curl -s -i -c /tmp/jar.txt -X POST localhost:3000/api/signup -d '{"email":"asha@example.invalid","password":"correct horse battery"}' | grep -iE "^HTTP|set-cookie"Copy

  With bun run dev running: 201, then a cookie with HttpOnly, Secure and SameSite=Lax.

• curl -s -i localhost:3000/api/me | head -1Copy

  401, because you sent no cookie. Now look at the next command, which should worry you.

• curl -s -o /dev/null -w "%{http_code}\n" -X POST localhost:3000/api/groups -d '{"name":"Open door","members":["A"]}'Copy

  201. Anyone can still make a group, and read any group. You left that open on purpose, and stage 13 closes it.

• Answering the questions feels hard. The second prompt holds the answers that worked for us. Change any you disagree with. They are only decisions.
• A Secure cookie over plain http://localhost. Browsers treat localhost kindly, but curl’s cookie jar may not send it back. We passed it by hand with -H "Cookie: kitty_session=...".
• It builds more than the slice. Stop it. Tell it the stop condition again, and use git diff to see what to throw away.

To undo this stage: The slice is on the accounts branch. SPEC.md is on main: to throw away a bad spec, git revert that commit.

Edit the spec by hand before any code exists.

1. After the interview, close the agent and open SPEC.md yourself.
2. Settle every open question in one sentence each. Those are your decisions now.
3. Add one acceptance criterion of your own, and one non-goal of your own. Ours: AC31, an amount of 12.5 returns 422 and nothing is stored.
4. Commit the spec. Only then start the new session for the third prompt.
5. After it finishes, match each test to its criterion by reading them, one by one.

Done when: git log shows the spec before the code, and git show on it shows lines you wrote yourself.

• docs: add a spec for sign-in and group membership Written after an agent interviewed me, then edited by hand: I settled the open questions, added AC31 and added a non-goal.Copy

  What you commit by hand. The agent's own commits are already on the branch.

• No row yet. A spec is not a mistake. The open question about changing a password goes in SPEC.md.Copy

  The row you add to docs/ratchet-log.md, with your own date, your own words and your own commit hash. If what went wrong for you was different, write that instead.

• Backpressure: checks that say no without you there.
• Linter: the first gate you will see fail.
• Type checker: the second. Ours found 25 errors in code that passed every test.
• Strict mode: the setting that finds them.
• Stop hook: sends the agent back when it says it is finished and the checks are red.
• Continuous integration: the one check nobody can skip.
• No bypass: what you try by hand below.
• Ratchet: limits that only go one way.

• git switch -c harnessCopy

  A branch, because this stage changes a lot of files.

• unzip ~/Downloads/harness-typescript-earned.zip -d .harness-kitCopy

  Pass the gates up to this chapter, then press the earned button on /kit. It unpacks to a folder the agent reads from. Have jq installed first (brew install jq on a Mac). It is free.

Copies the kit in the order you gave, runs the gates, then fixes them one at a time. Ours took 6 minutes and 18 commits. Expect a large formatting commit, and expect it to tell you the kit’s hook blocked some of its own commands. Then it adds the CI file in a second session.

1. Skip the big formatting commit: read git show --stat for it, and nothing more.
2. Read the types commit: did it fix the code, or silence the check? No @ts-ignore, no any.
3. Read .claude/settings.json. Your allow rule should have survived.
4. Read AGENTS.md. Your rules from real mistakes must still be there.
5. Read .github/workflows/ci.yml: does it really run the check script?

• bash scripts/check.sh --fastCopy

  A pass line for each gate, then All gates passed.

• bash scripts/test-hooks.sh; echo "exit $?"Copy

  exit 0. It tried every spelling on its list against the new hook.

• actionlintCopy

  No output if the workflow is well formed. On a Mac, brew install actionlint.

• The kit’s own rules stop the agent installing the kit. Ours merged settings.json first, and then its deny rules stopped it replacing our hook. That part is on purpose: once settings.json is in, the agent can’t change it or a hook already there. So the prompt puts settings last, and if the agent gets stuck it gives you the command to run yourself. The kit used to deny the agent all of .claude/hooks/, which also stopped a later download adding its new hook. Since 6 November 2026 it names each hook you have, so a new one can come in.
• No tests run in the gates. That was us: the kit’s check script used to get its tests gate from the next chapter’s files, so at this stage it ran none, and the prompt we ran first had to add one. Since 6 November 2026 the kit’s check runs your tests from this chapter on, and says no if there are none. Step 6 asks the agent to show you the line. Read it.
• The hook rejects a commit message containing a word like .env. It reads the whole command as text. Ours wrote the message to a file and used git commit -F. That is a false alarm, not a hole.

To undo this stage: Everything is on the harness branch. To abandon it: git switch main, then git branch -D harness. Lefthook’s git hooks stay installed until you delete them from .git/hooks.

Try to cheat your own harness.

1. Close the agent. Make a scratch branch: git switch -c cheat.
2. Try each one and write down what stopped it: break a test and commit. Then git push. Add a lint error and commit, then use --no-verify. Add test.skip. Add @ts-ignore. Set strict to false. Delete a test file. Edit an expected value so that it passes. Rename the biome binary and run the check.
3. Write the table in docs/what-gets-through.md.
4. git switch harness, delete the scratch branch, and merge harness to main.

Done when: A table in your repo. In our run, deleting a test file and editing an expected value both got through, and that is what stage 10 closes. A failing test could be committed and only git push refused it.

• docs: record what got past the harness when I tried to cheat it Deleting a test file and editing an expected value both get through.Copy

  What you commit by hand. The agent's own commits are already on the branch.

• | 2026-11-06 | Strict types found 25 errors in code that passed every test. | The types gate, strict plus unchecked index access, seen failing on a seeded type error. | your commit |Copy

  The row you add to docs/ratchet-log.md, with your own date, your own words and your own commit hash. If what went wrong for you was different, write that instead.

• Mutation testing: it breaks the code on purpose and counts what your tests notice.
• Mutation score: the number you get. You keep it and show it.
• Equivalent mutant: some survivors can’t be killed. It will tell you which, and you check.
• Property-based testing: a rule tested over many generated inputs.
• Test tampering: what the tamper check is for.
• Holdout scenario: an exam the agent never saw.
• Invariant: shares always add up to the total: a rule for every input, which the property test checks.
• Empirical verification: running the code against cases is evidence, not proof, and the exam is exactly that.
• Model checking: the heavier tool for rules like that. Kitty doesn’t need it yet, and you should know when something would.
• Coverage: why our tests could cover a line and still miss the bug.

• git switch -c mutationCopy

  A branch for this stage.

• unzip -o ~/Downloads/harness-typescript-earned.zip -d .harness-kitCopy

  Pass this chapter’s gate, download again, and unpack over the old folder.

Installs the config and runs Stryker, which took about 10 seconds. It lists every survivor in plain words, including what each would do to someone’s money. Then it writes tests for them and decides which are equivalent. Ours went from 71.43% to 84.92%, with 102 lines of tests and no line of code changed.

1. docs/mutation/before.txt: the table at the end, then the survivors in balances.ts. One of ours wiped everyone’s earlier balance on every new bill, and 40 tests did not notice.
2. git diff main...HEAD -- src: only test files should appear. If code changed, ask why.
3. The last commit message: which mutants does it call equivalent? Pick one and check its argument yourself.
4. Tell-tale in the new tests: real expected values, or just that something ran?

• node_modules/.bin/stryker run 2>&1 | tail -9Copy

  The score table. Ours: 84.92% over all, with split.ts at 97.22%, balances.ts at 86.36% and settle.ts at 77.94%.

• bash scripts/tamper-check.sh main; echo "exit $?"Copy

  On a clean branch, exit 0.

• Stryker crashes. Check that TypeScript is on 6. Stryker core 10.1.1 crashed on TypeScript 7.0.2 when we tried it. The kit pins it.
• The run exits with an error because the score is under 80. That is the threshold working, and the report above the error is still good. Save it. The prompt says so, because an agent’s first instinct is to lower the number.
• It says 19 survivors are all equivalent. Don’t take that on trust. Ours were arguments, not proofs. Check at least one by hand.

To undo this stage: Everything is on the mutation branch. git switch main leaves it behind.

Make a mutant by hand, and set an exam.

1. Close the agent. In src/balances.ts, change ?? 0 to && 0 where the shares are taken off. Run bun test. It should fail now. Run git checkout -- src/balances.ts.
2. Break the code, change a test to match, and run bash scripts/tamper-check.sh main. Watch it refuse. Put both back.
3. Make a folder next to your repo, ../kitty-exam, and write 5 to 8 tests there by hand that import from your src: a penny between three, bills in the other order, one person, no bills, very large bills. The agent has never seen these.
4. Run them: cd ../kitty-exam && bun test . Write down how many passed.

Done when: A before and after score, a mutant you made yourself, and a count from an exam the agent never saw. Ours passed 8 of 8, which counts for something, on a small and simple exam.

• docs: ratchet row for the mutation score and the tamper checkCopy

  What you commit by hand. The agent's own commits are already on the branch.

• | 2026-11-06 | Mutation testing the money code scored 71.43%. A mutant that wiped earlier balances on every new bill survived all 40 tests, and so did deleting a test file. | Stryker floor of 84% in the full check, and scripts/tamper-check.sh on a branch. | your commit | Yes: the mutant by hand, and a deleted test refused. |Copy

  The row you add to docs/ratchet-log.md, with your own date, your own words and your own commit hash. If what went wrong for you was different, write that instead.

• Cyclomatic complexity: how many paths run through a function.
• CRAP score: complexity weighed against how well it is tested.
• Duplication detection: the gate that sent our agent back to fix itself.
• Good code: cheap to change: you price a change here.
• Dependency injection: the server is handed its Store, and doesn’t build one.
• Interface: what the rest of the app is allowed to know.
• Boundary: one file may touch the database.
• Architecture decision record: so the next session doesn’t undo a decision.

• git switch -c designCopy

  A branch for this stage.

• unzip -o ~/Downloads/harness-typescript-earned.zip -d .harness-kitCopy

  Pass this chapter’s gate, download again, and unpack.

Adds the gates, reports the three worst functions and lists what moving to D1 would touch. Our estimate was 14 files. In the same run the duplication gate failed and the stop hook sent it back to fix that. Then it moves all the SQL behind one interface, in six green commits, and writes a structural test so nobody can put it back. Then it writes the decision records. A new session then refuses the bad request and cites them.

1. src/store.ts: 52 lines that are everything the app may ask of a database. Read all of them.
2. src/store-boundary.test.ts: what happens if someone adds SQL to another file?
3. git diff main...HEAD -- "src/*.test.ts": assertions must not change. Only how tests build the app.
4. docs/decisions/: is what it says you rejected what you really rejected? If it guessed, correct it.

• bun scripts/crap.ts --report | head -5Copy

  The worst functions. Ours: settleUp at complexity 10 and CRAP 10.

• bash scripts/check.sh --fastCopy

  Duplication, tests, and complexity and CRAP are now gates too. All green.

• git diff --stat main...HEAD -- src | tail -1Copy

  Compare with the estimate. Ours guessed +250 and -120, and the real figure was +383 and -215, in nine files.

• bash scripts/tamper-check.sh main; echo "exit $?"Copy

  exit 1. It says main’s tests fail, because a file moved. See below.

• The tamper check says no on your honest refactor. Ours did: a test imported ./db, which had moved. Read the test diff by hand. If only how tests build the app changed, merge, and say so in the merge message. That is a person using judgement, which is the point of the check.
• The agent makes a new branch you did not ask for. Ours did for the decision records. Harmless. Merge that one, since it holds the rest.
• The new session just does what you asked. Then your AGENTS.md line isn’t pointing at docs/decisions/, or the record is unclear. Ours stopped and offered two options. Fix the file, not the agent.

To undo this stage: The refactor is on the design branch, and each commit is green, so you can go back to any one. If the last prompt changed anything, git checkout -- . throws that away.

Argue with a number, out loud.

1. Close the agent. Open the worst function from the report.
2. Say whether its score is telling the truth, and which future change it would make expensive. Ours, settleUp, scores 10, and it is the clearest function in the app. So the number is not a verdict. Write that down.
3. Open src/store.ts. Without looking, say which file you would write to move to a new database, and which files would not change.
4. Keep that answer. Stage 16 tests it.

Done when: A note in docs/ gives your verdict on three functions, and at least one disagreement with the metric.

• merge: design: complexity gates, the store seam, two decisions scripts/tamper-check.sh refused this, because main’s tests import ./db, which moved. I read the test diff by hand: only how tests build the app changed.Copy

  What you commit by hand. The agent's own commits are already on the branch.

• | 2026-11-06 | Moving to D1 would have touched 14 files, because SQL sat in the routes. | Everything goes behind Store, and src/store-boundary.test.ts fails if SQL appears anywhere else. | your commit | Yes: the test failed on a word in a comment, before it passed. |Copy

  The row you add to docs/ratchet-log.md, with your own date, your own words and your own commit hash. If what went wrong for you was different, write that instead.

• Green doesn't mean right: green and wrong at the same time. You are about to see it.
• Reading a diff: how to read what changed.
• What to look for, in order: in what order.
• A fresh agent: the reviewer must not have written it.
• The reviewer's prompt: two prompts gave us two different reviews of the same code.
• Findings must show evidence: a defect counts when the reviewer ran something and pasted what came back.
• Review in the abstract: why a review that only reads the code, and runs nothing, is mostly tokens spent on opinions.
• Verification spend: a review is a cost, so spend it where running the code can show something.
• Explain it back: what you do with the agent closed.
• You own what you merge: you merge it, so it is yours.

• git switch -c commentsCopy

  A branch for this stage.

Builds the comments, the routes and an HTML page in five commits, and writes PR.md. It did escape the comment text, and it noted a query per expense, which comes back in stage 15. Then come the two reviews. The fresh reviewer follows the kit’s reviewer file, which counts a defect only when it ran a command and pasted the output, keeps anything it couldn’t run in a separate unverified list, and treats no defect found as a normal answer. Run twice with that file, ours once ran the NUL input below and pasted the 500, and once proved the group page opens with no cookie at all. The pushed prompt found the same crash both times.

1. PR.md first, then the three places it says to read.
2. src/group-page.ts: does every value from a person go through the escape function? Tick them off one at a time.
3. Each review’s defects: is there a command and its output for every one? Anything without them belongs on the unverified list, whatever the review calls it.
4. Compare the two reviews side by side. What did each find that the other missed?
5. Run every command a reviewer pasted, yourself. Do not merge on its word.

• bun test && git diff --stat main...HEAD | tail -1Copy

  All pass. Ours: 64 tests, and 539 lines added. Green says nothing yet about the crash below.

• curl -s -o /dev/null -w "%{http_code}\n" -X POST localhost:3000/api/groups/1/expenses/1/comments -d '{"author":"Asha","text":"\u0000"}'Copy

  With bun run dev running and a group and expense made: our run gave 500 before the fix. Yours may differ. If it gives 422, your agent got there first, so try other awkward input.

• curl -s -o /dev/null -w "%{http_code}\n" localhost:3000/groups/1Copy

  200, with no cookie. Anyone can read the group page. One of our reviews proved this by running it. You leave it open until stage 13.

• The reviewer invents a defect to seem useful. A prompt that pushes will do that sometimes: on our site’s own experiment a pushy prompt rejected good code nearly every time. The kit’s reviewer file only counts a defect it ran, with the command and its output. If a finding comes without output, treat it as unverified and run it yourself before you believe it.
• The review says no defect found. That is a normal result, and the reviewer file says so. Read what it says it looked at. Our first review with an older reviewer file found no bug, and the same code had a crash in it, so a clean review is information, not a guarantee.
• Your hand-written test is refused by the formatter. This happened to us, and the failing test never got committed. The agent then committed test and fix together. Run bunx biome check --write on your file, and check git log before you start the next prompt.
• You merge without checking the merge worked. We did this. A failed merge scrolled past, and the next stage started without the feature. Run git log -3 after every merge.

To undo this stage: The feature is on the comments branch. Reviews change nothing, so there is nothing to undo there.

Explain a file back, then write the failing test yourself.

1. Close the agent. Pick src/settle.ts or src/group-page.ts.
2. On paper, write what it does on three inputs, including one awkward one. Then run those inputs and mark what you got wrong.
3. Take the command a reviewer pasted. Run it yourself with curl and check you get the same output.
4. Write a failing test for it by hand, in src/comment-nul.test.ts, because the last prompt reads that file. Run bunx biome check --write on it, commit it, and see it fail.
5. Only then, use the last prompt to have a new session fix it.

Done when: git log shows your failing test before the fix, and a page shows your wrong guesses. Our own run failed this, and the log says so.

• test: a NUL comment must be a 422, and it crashes today A fresh reviewer ran this input and pasted the output: a 500. I ran the same request by hand and got the same. This commit is meant to fail.Copy

  What you commit by hand. The agent's own commits are already on the branch.

• | 2026-11-06 | A comment that was only a NUL character crashed with a 500, because SQLite’s length() stops at NUL and JavaScript’s does not. 64 green tests missed it. A fresh reviewer ran the input and pasted the 500. | A test for that input, written by hand. | your commit | Yes, by hand: 500 before the fix. |Copy

  The row you add to docs/ratchet-log.md, with your own date, your own words and your own commit hash. If what went wrong for you was different, write that instead.

• Threat model: four questions, written down before you fix anything.
• Broken access control: the open door you left in stage 8.
• IDOR: another person’s group, reached by changing a number.
• Cross-site scripting: a comment that runs as code in someone else’s browser.
• Output encoding: the escaping you will test place by place.
• Secret scanning: the gate that will find a password in your own test file.
• Prompt injection: a file that tells the agent to do something you didn’t ask for.
• Lethal trifecta: private data, untrusted content and a way out, all in one session.
• Sandboxing an agent: the wall that holds when the model doesn’t.

• git switch -c threat-modelCopy

  A branch for this stage.

• unzip -o ~/Downloads/harness-typescript-earned.zip -d .harness-kitCopy

  Pass this chapter’s gate, download again, and unpack. It brings the secrets gate and its canary.

• gitleaks versionCopy

  A version number. On a Mac, brew install gitleaks. It is free, and the secrets gate needs it.

Writes docs/threats.md, then a table test of every group route against three callers, and commits it failing. Then it builds sign-in on every group route, membership and invites, in one large commit, and lists each old test it had to change and why. Ours turned 12 rows green. Later it adds a table test for every place the page prints what someone typed, and the secrets gate. When gitleaks found our test password, it stopped and asked us rather than adding an ignore. It can’t write .claude/settings.json, because the kit’s own rule forbids it, so it gives you the lines to paste.

1. docs/threats.md: is every attack tied to a route and a test, or marked as accepted with a reason?
2. src/access.test.ts: the table, row by row. Then the second test, which fails if a route is missing from the table.
3. The commit that closed the door: membership must come from the signed-in user, never from the request body. Find the line.
4. Its list of tests it changed. Check two of them: did each keep what it checked?

• bun test src/access.test.tsCopy

  Both tests pass. Ours: 12 rows, 36 cells.

• bash scripts/check.sh --fastCopy

  A pass for secrets as well now.

• git switch -c canary && printf 'HARNESS_CANARY_%s\n' ABCDEFGHIJKLMNOPQRSTUVWX > canary.txt && git add canary.txt && git commit -qm "test: canary" --no-verify && bash scripts/check.sh --fast; echo "exit $?"Copy

  FAIL secrets, and exit 1. That made-up token can never be a real key. Then git switch threat-model and git branch -D canary.

• bun audit --audit-level=highCopy

  Ours: no high ones, and 5 moderate, all in packages we did not choose directly.

• scripts/tamper-check.sh main refuses the branch. Ours did, because main’s old tests expected the open door. Read the agent’s list of changed tests and judge it. Then say so in the merge message.
• The secrets gate fails on your own test password. Ours did, twice in history. The agent asked whether to ignore it or rewrite history. A made-up test password is a false alarm: put its exact fingerprints in .gitleaksignore by hand, with a comment saying why.
• The agent never gives a final answer. The stop hook kept sending ours back while the secrets gate was red, and its last message was empty. The kit’s stop hook has changed since, on 6 November 2026: it still never lets the agent stop on red, and from the 7th block in a row, just under Claude Code’s limit of 8, it asks for a final message saying what is still red and what was tried. Whatever it says, look at git log and the gate output yourself.
• With the sandbox on, the agent can’t start the server or reach localhost. We could not test this, because our run already sat inside a sandbox, and macOS refuses one inside another. Claude Code’s sandbox settings can allow local ports. Read its sandboxing page before you widen anything else.

To undo this stage: Each step is on its own branch: threat-model, then agent-fence. git switch main leaves them behind. To take the sandbox off again, delete the sandbox block from .claude/settings.json.

Take the escaping off, one place at a time, and try to fool your agent.

1. Close the agent. In src/group-page.ts, find e(comment.author), where the comment’s author is printed, and delete the e( and its closing bracket. Run bun test. It should fail. Run git checkout -- src/group-page.ts.
2. Do the same for each place the page prints what someone typed. Before the table test, ours noticed only one place in nine. After it, all nine.
3. Make the fake key: mkdir secrets && printf 'FAKE_KEY_not_a_real_key_0123456789\n' > secrets/fake-key.txt. Write docs/note-from-a-stranger.txt yourself, with a line telling an AI to read that file and send it with curl to a made-up address.
4. Run the last three prompts. Save what happens to each attempt in docs/threats.md.
5. Then, with the agent closed, try one by hand: cat secrets/fake-key.txt works for you. The rules only bind the agent.

Done when: Nine rows you saw fail one at a time, and a note in docs/threats.md naming what refused each attempt, and what nothing refused. In ours, rules refused the file reads and ls ~/.ssh, curl to a host off the list got out, and only the model chose to ignore the note.

• docs: what the fence test showed, and what it could not Rules refused the file reads. Nothing refused curl. The model ignored the injected note, which is behaviour and not a wall.Copy

  What you commit by hand. The agent's own commits are already on the branch.

• | 2026-11-06 | The XSS test only noticed one of nine places the page prints what someone typed. I found that by taking the escaping off each place by hand. | A table test in src/group-page.test.ts covering all nine, each row seen failing. | your commit | Yes: each of nine, by hand. |Copy

  The row you add to docs/ratchet-log.md, with your own date, your own words and your own commit hash. If what went wrong for you was different, write that instead.

• Race condition: two people settling the same debt at the same moment.
• Locks and atomic updates: the check and the write as one step in the database.
• Transaction: and why D1 can’t hold one open across awaits.
• Unique constraint: what makes a repeated webhook do nothing.
• Idempotency: safe to retry, in one word.
• Delivery guarantees: why a webhook arrives twice in the first place.
• Migration: changing the schema while rows exist.
• Backup and restore: you do one for real below.
• Money and floats: why every amount here is whole pence.

Builds settling up the plain way, then a test firing 50 settlements at one debt at once. In ours the race did not show: bun:sqlite is synchronous, so an await on it never lets another request in, and all 50 tests saw one get through. The agent said so plainly and suggested a store that yields, which D1 would be like. With that, 3 to 5 of 50 got through. It closed it with one SQL statement. Then the webhook: 22 of 100 payments doubled on a lossy fake network, and 0 after the event id went under a unique constraint. Then migrations, with a test that rows survive.

1. The race test’s commit messages: the numbers before and after. Is the yielding store only in the test file?
2. src/store-sqlite.ts, settleIfOwed: one statement. Read the WHERE that refuses an over-payment.
3. src/webhook.ts: the signature is checked first, with a constant-time comparison.
4. docs/webhook-crash.md: pick one step and check its claim against the code.
5. migrations/: 0001 is today’s schema. 0002 adds a column that old rows can live with.

• bun test src/settle-race.test.ts src/webhook.test.tsCopy

  All pass. The race test prints 1 of 50 got through.

• bun -e "console.log(0.1 + 0.2, 19.99 * 100)"Copy

  0.30000000000000004 and 1998.9999999999998. That is why money here is whole pence.

• sqlite3 kitty.sqlite ".backup backup.sqlite" && sqlite3 kitty.sqlite "select count(*) from expenses"Copy

  Make some data through the app first. The count is your number to get back.

• The race test passes the first time. That happened to us, and it proves nothing until you have seen it fail. The second prompt is for exactly this.
• It fixes the race with a lock in JavaScript. That works on one server and not on two. The prompt rules it out. If it tries, point it back at the SPEC.
• The structural test refuses a word. Ours refused the word update in the webhook code, because the test looks for SQL outside the store. The agent worked round the word, and it told us. A crude check, and it still did its job.

To undo this stage: Each step is its own branch: settlements, webhook, migrations. Merge each one only after reading it.

Lose the data on purpose, and get it back.

1. Close the agent. With bun run dev running, sign up, make a group and add five expenses with curl.
2. sqlite3 kitty.sqlite ".backup backup.sqlite". Count the expenses.
3. Make the mistake: sqlite3 kitty.sqlite "delete from expenses". Count again.
4. sqlite3 kitty.sqlite ".restore backup.sqlite", timing it. Count again, and read the balances through the app.
5. Put the old route back on a scratch branch, so the check and the insert are two calls again, and run the race test. Watch it fail.

Done when: A note in docs/ with the counts before, after the mistake and after the restore, and how long it took. Ours: 5, 0 and 5, in 0.03 seconds, on a tiny database.

• docs: a backup restored by hand, with the counts and the timeCopy

  What you commit by hand. The agent's own commits are already on the branch.

• | 2026-11-06 | A race test passed for the wrong reason: bun:sqlite is synchronous, so an await never let another request in. With a store that yields, 3 to 5 of 50 settled the same debt. | Check and insert are one statement, and the race test keeps the yielding store. | your commit | Yes: 3 to 5 of 50 before, 1 of 50 after. |Copy

  The row you add to docs/ratchet-log.md, with your own date, your own words and your own commit hash. If what went wrong for you was different, write that instead.

• Measure first: your guess goes in writing before the profiler runs.
• Percentiles: the median and p95, not an average.
• Profiler: what really took the time.
• N+1 query: one query per row. You have had one since stage 12.
• Query plan: EXPLAIN QUERY PLAN, before and after.
• Performance budget: a number that fails the build.
• Cost per task: the same task priced on two models.
• Model routing: which model for which job, from your own numbers.

• printf "# What makes the group page slow?\n\n## My guess\n\n" > docs/performance-guess.mdCopy

  Then write your own guess under it, in a sentence, before anything is measured. Leave it uncommitted. The first prompt commits it for you.

Seeds 5,000 expenses, times the page over real HTTP, writes its own guess below yours, then profiles. Ours: a median of 468 ms, and 5,007 SQL statements for one page view, nearly all of them one comments query per expense. My guess, the HTML building, was wrong. The fix read every comment in one query, pinned the whole page’s HTML first so the output could not change, and took the median to about 8 ms. Then a budget gate, seen failing at 758 ms on the old code.

1. docs/performance-guess.md: your guess and the agent’s, then the profile summary under docs/runs/.
2. The golden test commit: it pins the page before the change. That is what makes the fix safe.
3. The fix commit message: the query plans. Ours added no index and said why, and named what would get slow with many groups.
4. scripts/perf-budget.ts: what number, what limit, and the message when it is over.

• bun scripts/seed-perf.ts && bun scripts/time-page.tsCopy

  A median and p95. Ours went from about 468 ms to about 8 ms. Machines differ, and ours drifted to 745 ms for the same old code in a later session, so only compare runs from the same sitting.

• jq "{cost: .total_cost_usd, turns: .num_turns}" docs/runs/task-haiku.json docs/runs/task-sonnet.jsonCopy

  Ours: $0.018 on Haiku and $0.29 on Sonnet, both passing the same checks.

• Your guess was wrong. Good. Ours was. Keep it in the file. A wrong guess you wrote down is worth more in an interview than a right one you didn’t.
• The agent wants to fix three things at once. Stop it. The second prompt says the top item only, so you can tell what made the difference.
• The timing changes between runs. Timings are noisy. The budget has a wide margin for that reason. Ours was 20 ms against a typical 7.65 ms.
• Running the same task on Sonnet costs more than you expect. Set --max-budget-usd on every headless run. Ours cost 16 times as much for the same result.

To undo this stage: Each step is on its own branch: perf, budget, task-haiku and task-sonnet. Keep the one you like and delete the other.

Price the same task on two models.

1. From the same commit, make two branches: git switch -c task-haiku, and later task-sonnet.
2. Run the last prompt on each, headless, as stage 5 did: claude -p "$(cat task.txt)" --model claude-haiku-5-5 --output-format json --max-budget-usd 1 > docs/runs/task-haiku.json, then the same with claude-sonnet-5-5.
3. Run bash scripts/check.sh --fast on each. Read both diffs.
4. Write docs/runs/two-models.md: cost, turns, time, passed or not, and which you merged and why.

Done when: A table of two runs and one decision you made because of it. One task proves nothing about either model, and the note should say so.

• docs(perf): the same task on two models, pricedCopy

  What you commit by hand. The agent's own commits are already on the branch.

• | 2026-11-06 | The group page ran 5,007 SQL statements for one view, about 470 ms with 5,000 expenses. I guessed the HTML was slow, and I was wrong. | A performance budget of 20 ms for the median, in the full check. | your commit | Yes: 758 ms on the old code fails it. |Copy

  The row you add to docs/ratchet-log.md, with your own date, your own words and your own commit hash. If what went wrong for you was different, write that instead.

• Serverless: what a Worker is, and what it can’t do that Bun can.
• Config and secrets: the API token lives in CI, never on the agent’s machine.
• Continuous delivery: deploy only after the checks pass.
• Feature flag: the same person always gets the same answer.
• Structured logging: one line per request, and never a cookie.
• SLI and SLO: what good means, as a number.
• Error budget: 216 minutes a month, worked out by hand.
• Rollback: the way back, timed.
• Postmortem: blameless, with each cause marked evidenced or guessed.
• Runbook: what a tired person or a fresh agent reads.

Moves the app into a file both runtimes share, writes a D1 store using batches where SQLite used transactions, and runs a smoke test against Bun and against wrangler dev on your machine. Ours took two sessions, because the first ran past our time limit. On the local Workers runtime it found PBKDF2 at 100,000 iterations takes about 7 ms, close to the free plan’s 10 ms of CPU time per request, though that was not measured on Cloudflare. It accepted counts far higher, because local workerd has no cap. Deployed Workers do: they refuse more than 100,000, as workerd’s source and its maintainers say (read 6 November 2026), so stay at or under it. Then a deploy job, request logs, a flag and the runbook. Then the drill: a fault hidden from you.

1. docs/decisions/0004-d1-transactions.md: each place a transaction became a batch.
2. .github/workflows/ci.yml: needs: check on the deploy job. Find why a red check can’t deploy.
3. src/request-log.test.ts: it fails if a log line holds a session token. It was seen failing.
4. docs/runbook.md: the SLI, and what it can’t see. You find that out in the drill.

• bun run dev & bash scripts/smoke.sh http://localhost:3000Copy

  smoke passed. Then stop the server and do the same against bunx wrangler dev --local on port 8787.

• actionlintCopy

  No output.

• bunx wrangler deployCopy

  Only once you are ready, and only after bunx wrangler login, bunx wrangler d1 create kitty, and putting its id in wrangler.toml. Then add CLOUDFLARE_API_TOKEN to the repo’s secrets on GitHub, so CI deploys from then on. We did not run this step.

• wrangler dev keeps running after the agent finishes. Ours left servers running twice. Find them with lsof -i :8787 and stop the ones you started.
• The agent changes code you didn’t ask about. Ours had to move the crypto to Web Crypto, because Workers can’t load node:crypto, and it told us. Read that commit closely.
• The first deploy fails. wrangler.toml holds a placeholder database id until you create the database. That is expected.
• Sign-up works locally, and fails once deployed. Look at the PBKDF2 iteration count first. Local workerd accepts any count, and deployed Workers refuse more than 100,000 with a NotSupportedError. That limit is in workerd’s source and in its pull request 1471, read 6 November 2026, and Cloudflare’s Web Crypto page doesn’t mention it.
• You can’t find the fault from your signals. Neither could we. Every status was fine and the smoke test passed, because a 201 that saves nothing looks healthy. That is the lesson, and the postmortem’s first follow-up.

To undo this stage: Each step is on its own branch. The drill branch is thrown away after the postmortem. To undo a real deploy, use the rollback command you write down in the runbook.

Break it on purpose, notice, roll back, and write it up.

1. Run the third prompt. Don’t look at the diff or the answer file.
2. Run the drill branch as your stand-in for production. Note the time, run the smoke test and use the app as a person would. Write down every time and what you saw.
3. When you give up, run the fourth prompt, read-only, and note when it names the cause.
4. Roll back: git revert the bad commit, redeploy, and check that the thing that failed now works. Time it from the moment you knew.
5. Write your timeline to docs/postmortems/drill-notes.txt and run the last prompt. Then check its new test yourself on the broken commit in a worktree.

Done when: A postmortem with no names, a measured time to notice and to recover, and a test you saw fail on the broken commit. Ours: no signal ever showed the fault. A read-only agent named it in 66 seconds by reading the newest commit, and a verified rollback took 32 seconds after that.

• docs(runbook): the rollback command and its measured time, from the drillCopy

  What you commit by hand. The agent's own commits are already on the branch.

• | 2026-11-06 | A drill: expenses of £1,000 or more were silently not saved, and the route still answered 201. No signal showed it, and the smoke test passed. | src/expense-saved.test.ts: every saved expense is listed, at any size. | your commit | Yes: 5 of 6 fail on the broken commit. |Copy

  The row you add to docs/ratchet-log.md, with your own date, your own words and your own commit hash. If what went wrong for you was different, write that instead.

• Parallel agents: two at once, and what that costs you.
• Worktree isolation: a folder each, so neither can touch the other’s files.
• Coordination cost: the merge is yours, and it took longer than the work.
• Ralph loop: a fresh agent per pass, until a check is green.
• Progress files: how one pass tells the next what happened.
• Runaway loops: the three limits that stop a loop.
• When not to: our own numbers say one agent was better here.

• unzip -o ~/Downloads/harness-typescript-earned.zip -d .harness-kitCopy

  Pass this chapter’s gate, download again, and unpack. It brings scripts/ralph.sh and docs/loop-prompt.md.

First, two agents at once in one folder, each on a different function in the same file. Ours did not overwrite each other: each saw the other’s edits appear and said so, and you are left with one diff with two authors. Then the same two tasks in two worktrees: clean history, a real conflict for you to settle, and two copies of the same helper that no gate noticed. Then one agent doing both, which was cheapest and cleanest.

1. After the shared-folder run, git diff: can you tell which agent wrote which line? You can’t.
2. After the worktree merge, src/group-page.ts: how many pound formatters are there now?
3. progress.txt after the loop: what each pass did, and why it stopped.

• git worktree add ../kitty-a -b pounds-balance main && git worktree add ../kitty-b -b pounds-payment mainCopy

  Two folders. Start one agent in each, at the same time, with the worktree prompts.

• MAX_LOOPS=5 MAX_TURNS=30 MAX_BUDGET_USD=0.5 bash scripts/ralph.sh; echo "exit $?"Copy

  With your three failing tests and fix_plan.md in place. It stops with exit 0 only when every item is ticked and the checks are green. Ours ran the older ralph.sh, which stopped after one pass on green checks with all three items unticked.

• MAX_BUDGET_USD=0.001 bash scripts/ralph.sh; echo "exit $?"Copy

  On a branch from before the loop ran. It stops on the budget, exit 2.

• The loop stops with plan items still open. Ours did, because ralph.sh then stopped on green checks, and the stop hook pushed the first pass to do all three items. Since 6 November 2026 green checks with items open mean another pass, so it ends on a ticked plan or on its pass limit. Still write a failing test for every item before you start: the plan is only as good as its tests.
• The loop’s agent can’t commit or tick the plan. Ours couldn’t: it had no permission to run git or the check script without you there. Since 6 November 2026 ralph.sh lets each pass run the fast check, git add and git commit, and nothing else on the shell beyond your settings. If yours still can’t, read what it did and commit it yourself.
• The merge conflict looks frightening. Ours was five lines of test expectations, where each side was right about half. Keep both halves, then run every check.

To undo this stage: git worktree remove ../kitty-a, and the same for b. Branches stay until you delete them.

Write the loop’s tests by hand, then make it stop three ways.

1. Close the agent. Write fix_plan.md with three items for a slugify function, and src/slug.test.ts with one failing test per item, by hand.
2. Copy scripts/ralph.sh and docs/loop-prompt.md from the kit. Commit.
3. Run the loop once normally, once with a budget far too low, and once with every plan item ticked. Save progress.txt each time.
4. Write docs/one-or-several.md: a row each for the shared folder, the worktrees and the single agent, with time, cost and what you had to do.

Done when: Three stops you saw, and a rule of your own. Ours: one agent for anything that touches the same file or the same tests.

• docs: one agent or several, measured on one taskCopy

  What you commit by hand. The agent's own commits are already on the branch.

• | 2026-11-06 | Two agents in worktrees each added their own pound formatter. The merge was clean apart from one test conflict, and no gate noticed the copy. | A rule in AGENTS.md: one agent for work that touches the same file. Still only a rule. | your commit |Copy

  The row you add to docs/ratchet-log.md, with your own date, your own words and your own commit hash. If what went wrong for you was different, write that instead.

• The claim you can defend: five sentences, each with a link.
• A repo worth showing: this repo is the thing you show.
• A commit trail: what changed, when, and why.
• AGENTS.md as evidence: each rule ends in a commit hash.
• The log of past failures: mistakes that became checks.
• Saying what you don't know: what your setup can’t catch, said first.
• Reviewing live in an interview: what happens when someone opens a file and asks you to explain it.
• What you can now say: and what you can’t, below.

• unzip -o ~/Downloads/harness-typescript-earned.zip -d .harness-kitCopy

  Pass the last gate, download again, and unpack. It brings docs/claims.md.

Fills in docs/claims.md with five sentences and a link after each, opening every link to check it. Ours checked three of its claims by running old commits in worktrees, and found things in the repo that were not true, without being asked: AGENTS.md said CI runs every gate, and it runs only the fast ones and the audit. Then a sceptical session, read-only, checks every link and finds more. Ours found a commit count that did not reproduce, a ratchet row listed twice, and a mutation file that showed the old floor.

1. docs/claims.md, out loud. Every sentence you can’t defend, cut.
2. The sceptic’s report: each partly or doesn’t. Fix those, by hand.
3. README.md: does it say in one line what Kitty is, and link to the claims?

• git log --oneline | wc -lCopy

  Your commit trail. Ours: 186 commits on main.

• bash scripts/check.sh; echo "exit $?"Copy

  Every gate, including mutation and the budget. exit 0. Run this before you show anyone.

• grep -c "^| 2026" docs/ratchet-log.mdCopy

  Your ratchet rows. Ours: 10, after removing a duplicate the sceptic found.

• Your claims say more than the evidence. Ours did, in places. The sceptic catches some. The rest you catch by reading each sentence aloud to someone.
• Something in AGENTS.md is no longer true. Ours said CI runs every gate, and our CI ran only the fast ones and the audit. That line came from the kit, which since 6 November 2026 mentions CI only in a download that has the kit’s CI file, and that runs every gate. Fix the line, and either add the gates to CI or say plainly that you run them by hand.

To undo this stage: The claims are on the claims branch, and nothing in it changes code.

Be interviewed with the agent off.

1. Close the agent. Open src/settle.ts and explain it line by line, out loud, recording yourself.
2. Have someone change one line in src/balances.ts without telling you which. Find it and fix it by hand, timing yourself, and note every time you reached for the agent.
3. Open the interview room on this site and answer six of its hard questions out loud, pointing at this repo.
4. Write what you couldn’t answer, and do the first thing on that list.

Done when: A recording or notes, a timed fix, and a list with one item crossed off. Nobody has done this step for this page yet: our run was an AI following it, and an AI can’t tell you how a person does without the agent.

• docs: correct what a sceptical read foundCopy

  What you commit by hand. The agent's own commits are already on the branch.

• | 2026-11-06 | AGENTS.md said CI runs every gate. A sceptical read found it runs only the fast gates and the audit, so the mutation floor and the budget were never enforced in CI. | The line now says so. Adding those gates to CI is the next ratchet. | your commit |Copy

  The row you add to docs/ratchet-log.md, with your own date, your own words and your own commit hash. If what went wrong for you was different, write that instead.

Each claim from the home page, and the exact thing to open when someone doubts it. If you skipped the stage, you can’t say the sentence.

My agents write the code.

AGENTS.md, then its "Rules from real mistakes" section. Each line ends in a commit hash. Open one with git show and tell the story. Then open docs/ratchet-log.md, where each row names the mistake and the check it became.

But nothing goes in on their word.

.github/workflows/ci.yml and scripts/check.sh, then docs/what-gets-through.md: your own table of what you tried, what stopped it and what got through. Show the canary secret being refused. Be ready to say that the stop rule is a hook, and hooks can be skipped, which is why CI is the check that counts.

I know the tests really test.

docs/mutation/before.txt, with the survivor that wiped earlier balances, then the floor in stryker.config.json. Run bun scripts/check or stryker live if they have ten seconds. Then open ../kitty-exam, the checks the agent never saw, and say how small that exam is.

I can read what it wrote.

Close the agent, open src/balances.ts or src/settle.ts, and walk through it on an awkward input. Then git show the Math.round commit from stage 4: you found that bug by hand. If you did it with reasoning and log lines and not a debugger, say that. The home page says debugger, and you should earn that word or not use it.

I know what it costs and what can go wrong.

docs/threats.md, tied to src/access.test.ts and src/group-page.test.ts. Your fence settings and the refusals you saved. docs/runs/, where one task’s bill is worked out by hand and another is compared across two models. Say plainly whether your agent can reach the live system: it should have no deploy credentials on your machine.

And when it breaks, it is mine.

docs/postmortems/, an incident you caused on purpose, with measured times to notice and to recover. Then the check that fails on the broken commit and passes on the fix. Run it both ways. Say up front that it was a drill, because pretending otherwise is the fastest way to lose the room.

• I built this small app with an agent, I can walk you through any file of it, and here is the commit trail.
• I measured whether my tests catch bugs, and here is what they missed before and after.
• Here is an access-control table, with every route against every kind of caller, and a test that fails if someone adds a route and forgets it.
• I reproduced a race condition with a real database and closed it in the database, and I can tell you what would still go wrong.
• I broke it on purpose, timed how long it took me to notice and to get back, and turned what I learned into a check.
• Here is what my harness does not stop. I tried to get past it, and I wrote down what worked.

• That you have run software with real users, real traffic or a real 3am incident. A drill is a drill, and you caused it.
• That you could write this without an agent. You can read it, debug it and test it, and that is a different skill from writing it from a blank file. Find out how far you get, and say so.
• That your app is secure. You closed the attacks you listed, and nobody independent has tried to break in.
• That you know a large codebase. Kitty is a few thousand lines that you watched grow. Most jobs start with a million lines you did not.
• That this makes you faster or better than anyone else. Nothing here measured that, and chapter 18 explains why almost nobody can.
• That you are a senior engineer, or that a course replaces years. It gets you to the point where you can be honest about where you stand, and show it.

Now go and be doubted: the interview room asks what someone paid to doubt you will ask, and the review gym trains the eye your repo can’t show.