diff --git a/.gitignore b/.gitignore index 76bf89e6..090b6f62 100644 --- a/.gitignore +++ b/.gitignore @@ -108,7 +108,7 @@ !docs/*.md !presentation/ !presentation/README.md -!presentation/build-pdf.sh +!presentation/build-pdf.py !presentation/index.html !presentation/render-pdf.js !principles/ diff --git a/presentation/README.md b/presentation/README.md index 4a612958..afcb3a00 100644 --- a/presentation/README.md +++ b/presentation/README.md @@ -5,12 +5,12 @@ ## Rebuild the PDF ```sh -presentation/build-pdf.sh +presentation/build-pdf.py ``` -It writes `presentation/loop-claude-explained.pdf`, which stays out of git. It needs Docker and the `playwright-for-claude` image, which `~/code/playwright-for-agents/pw about:blank` builds once. +It writes `presentation/loop-claude-explained.pdf`, which stays out of git. It needs Docker and the `playwright-for-claude` image. Build the image once with `~/.claude/bin/run-heavy docker build -t playwright-for-claude ~/code/playwright-for-agents`. -`index.html` is an artifact body: it has no doctype, head or body of its own. `build-pdf.sh` wraps it the way the artifact host does. To publish an edited page, publish `index.html` to the same artifact. +`index.html` is an artifact body: it has no doctype, head or body of its own. `build-pdf.py` wraps it the way the artifact host does. To publish an edited page, publish `index.html` to the same artifact. ## Who it is for diff --git a/presentation/build-pdf.py b/presentation/build-pdf.py new file mode 100755 index 00000000..c013ba39 --- /dev/null +++ b/presentation/build-pdf.py @@ -0,0 +1,28 @@ +#!/usr/bin/env python3 +"""Print index.html to loop-claude-explained.pdf beside it, in the playwright-for-claude image.""" +import pathlib, shutil, subprocess, sys, tempfile + +HERE = pathlib.Path(__file__).resolve().parent +IMAGE = "playwright-for-claude" +# index.html is an artifact body, without a doctype, head or body of its own, so wrap it as the artifact host does. +HEAD = '
\n' + + +def main() -> int: + if subprocess.run(["docker", "image", "inspect", IMAGE], capture_output=True).returncode != 0: + print(f"No {IMAGE} image. Build it once with: ~/.claude/bin/run-heavy docker build -t {IMAGE} ~/code/playwright-for-agents", file=sys.stderr) + return 1 + with tempfile.TemporaryDirectory() as folder: + work = pathlib.Path(folder) + (work / "page.html").write_text(HEAD + (HERE / "index.html").read_text(encoding="utf-8") + "\n", encoding="utf-8") + shutil.copy(HERE / "render-pdf.js", work) + printed = subprocess.run(["docker", "run", "--rm", "--init", "--memory", "2g", "--memory-swap", "2g", "-v", f"{work}:/work", "-w", "/work", "--entrypoint", "node", IMAGE, "render-pdf.js"]) + if printed.returncode != 0: + return printed.returncode + shutil.copy(work / "out.pdf", HERE / "loop-claude-explained.pdf") + print(f"Wrote {HERE / 'loop-claude-explained.pdf'}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/presentation/build-pdf.sh b/presentation/build-pdf.sh deleted file mode 100755 index a5997b67..00000000 --- a/presentation/build-pdf.sh +++ /dev/null @@ -1,25 +0,0 @@ -#!/bin/sh -# Print index.html to loop-claude-explained.pdf beside it, in the playwright-for-claude image. -# The image comes from ~/code/playwright-for-agents: its ./pw builds it on first use. -set -eu - -here=$(cd "$(dirname "$0")" && pwd) -work=$(mktemp -d) -trap 'rm -rf "$work"' EXIT - -if ! docker image inspect playwright-for-claude >/dev/null 2>&1; then - echo "No playwright-for-claude image. Build it once with: ~/code/playwright-for-agents/pw about:blank" >&2 - exit 1 -fi - -# index.html is an artifact body, without a doctype, head or body of its own, so wrap it as the artifact host does. -{ - printf '\n' - cat "$here/index.html" - printf '\n' -} > "$work/page.html" -cp "$here/render-pdf.js" "$work/" - -docker run --rm --init --memory 2g --memory-swap 2g -v "$work:/work" -w /work --entrypoint node playwright-for-claude render-pdf.js -cp "$work/out.pdf" "$here/loop-claude-explained.pdf" -echo "Wrote $here/loop-claude-explained.pdf" diff --git a/presentation/index.html b/presentation/index.html index 2871c787..f157cb29 100644 --- a/presentation/index.html +++ b/presentation/index.html @@ -231,9 +231,9 @@ dl.gloss dt { font-weight: 700; } dl.gloss dd { margin: 0; color: var(--muted);For developers and teams who build with AI agents and want a software factory: work that keeps flowing without someone watching it, at a quality they would sign off on.
| 14 | Narrow, separate reviewers | Experience Early on, a reviewer with too broad a responsibility found fewer issues. Own measurement On 2026-11-09, merged reviewers were replayed on archived rounds. Stability, product owner and prose as one reviewer cost half as much, but found 15 of 34 prose findings again, against 22–23 for the prose reviewer. Architect and principles auditor as one found 5 of 17 principles findings, against 10, and lost both red ones. Even stability and product owner alone, as one, found 4–5 of 16 product-owner findings, against 7–10. In every merge, one absorbed pass lost findings, at a third to half the cost. Method and figures: reviewer-merge-trials/ in the setup's repo. Merging reviewers that check the same kind of thing did hold up: one principles auditor found as much as several. |
| 15 | At most two rounds per reviewer | Own measurement Since 2026-10-21, across all projects: round 1 ran 357 times and found 59 red findings. Round 2 ran about 200 times and found 12, mostly in round 1's fixes. Rounds 3 and later ran about 110 times and found none, for about $125. Asks for more rounds were 24 of 59 interrupts. |
| 16 | Reviewers report only real problems | Vendor docs Anthropic's Claude Code best practices: "A reviewer prompted to find gaps will usually report some, even when the work is sound." Own measurement 320 of this repo's 876 commits answered a review round. So stability and product owner report only defects, broken requirements or broken principles. |
| 16 | Reviewers report only real problems | Vendor docs Anthropic's Claude Code best practices: "A reviewer prompted to find gaps will usually report some, even when the work is sound." Own measurement 320 of the setup repo's first 876 commits, by 2026-10-13, answered a review round. So stability and product owner report only defects, broken requirements or broken principles. |
| 17 | Architect and principles only in the release review | Own measurement The principles audit was the costliest reviewer after the worker, and filed findings unrelated to the chunk. Once a release, over the whole project, catches the same drift. |
| 18 | Security: /security-review, not a hand-written reviewer | Reasoning Its tuned exclusion list and confidence floor would be reproduced worse by hand. Own measurement Run beside the deep scan, it returned a near-identical report, so the deep scan replaces it when both would run. |
| 19 | Mutation testing instead of coverage | Research Coverage barely predicts fault detection: Inozemtseva & Holmes, ICSE 2014. Surviving mutants do predict real faults: Just et al., FSE 2014. Google runs mutation testing in code review: Petrović et al., arXiv:2102.11378. |