human-review

Assemble .human-review/review.html — a tabbed reviewer's guide for a change set — from the review-points.md the coding agent committed with its fixes (what it fixed, declined and assumed), plus diagra

SKILL.md

GitHub

/human-review — assemble a review.html for a human

This skill does not review the code. It writes up a review that already happened.

The review happened in the coding agent's own conversation, and it left a record: /record-review, run in the conversation that implemented the change, reviews it adversarially (/code-review in Claude Code, reviewer subagents elsewhere) and writes review-points.md at the repository root — what it fixed because the review was right, what it read and declined, and what it assumed where the ticket was ambiguous — committed with the fixes, so the record arrives in the pull request's own file list. This skill reads that file. It does not run a review, and it does not write one.

That is the whole division. The judgement is produced once, by the agent that made the decisions, while it still has them; the page is assembled by programs from the branch. What is left for you is two model-written artifacts — the cheap model's check of the sentence↔test pairing behind the Tests tab (test-mapping.json: every scripted link confirmed or rejected, the rest paired), and +1 LLM script, the Demo film's — plus the page's layout and its ledes. Everything else on these five steps is a script. Do not commit or push.

A branch with no review-points.md is not an error and not a gate: the page says so, in a band, and the piles read not recorded. Do not write the piles by hand to fill the gap — a pile you compose at the end of a review is exactly the artifact this flow replaced, and it reads on the page identically to one the agent actually recorded.

Resolve the skill's own directory once — a plugin install, an env override, a project symlink, a gitignored CI clone and a ~/.copilot/skills/ symlink (VS Code Copilot Chat) are all real layouts:

for candidate in "${CLAUDE_PLUGIN_ROOT:-/nonexistent}/skills/human-review" \
    "${HUMAN_REVIEW_HOME:-/nonexistent}" \
    "$(readlink -f .claude/skills/human-review 2>/dev/null)" ".claude/skills/human-review" \
    "$(readlink -f ~/.copilot/skills/human-review 2>/dev/null)"; do
  [ -x "$candidate/scripts/run-steps.py" ] && { SKILL="$candidate"; break; }
done
[ -n "${SKILL:-}" ] || { echo "cannot locate the human-review skill"; exit 1; }

Run everything from the repository root. Project-specific commands live in human-review.json there, not in this file — human-review.example.json is the template.

Step 1 — What does the branch record about its own review?

${SKILL}/scripts/review-points.py --check

It prints what it understood: how many items in each pile, which reviewer raised each one, and what each is anchored to. Read that output — it is the review. Nothing below this line produces findings, and nothing below this line may add one.

Four answers, and none of them is a refusal:

  • 0 — the record is there and parses. Step 3 turns it into .human-review/review-points.json and the page's three piles are filled from it.
  • 3 — no review-points.md on this branch. Say so to the human in one line and carry on: the page renders a band reading nothing records what was reviewed or declined, the assumptions pile says the coder could not be asked, and that is the honest page for this branch. If they want the record, the thing to run is /record-review, in the conversation that wrote the code — not a review pass here, whose findings would be nobody's decisions.
  • 4 — the file is there and will not parse. Print the problems; they name lines. This one does stop Step 3, loudly, because a pile the parser skipped reads on the page exactly like a pile nobody wrote.
  • 5 — every item is unanchored. The file exists and says nothing checkable, which is not the same thing as a clean review.

⚠️ Never run /code-review or /simplify from here. Not to fill a gap, not to corroborate the file, not to "check" it. A pass run now is a second opinion formed after the fact by an agent that did not write the code, and its findings carry no accept/decline decision at all — which is the one thing the Review tab exists to show. review-passes.py still runs, and is still worth reading, as a cost source: it finds the passes that ran in the coding session and prices them. It is not a gate any more.

Step 2 — Resolve the change set, then gate and wipe

From $ARGUMENTS: empty → uncommitted work, BASE=HEAD — unless the working tree is clean, which is the normal state right after /record-review: then the branch against origin/main. A ref / range / SHA → BASE=<the older ref>. A PR (#123, a github URL) → gh pr checkout <n>, and BASE=$(gh pr view <n> --json baseRefName -q .baseRefName). Default origin/main. Print a one-line scope banner; an empty change set is "Nothing to review." and stop.

${SKILL}/scripts/preflight.py --base "$BASE"

It pushes, waits for CI on the pushed commit, and only then wipes assets/ and earlier builds' *.out logs, clears the model state that is not HEAD's (.model-prev/ and .model-runs.json/.film-runs.json rows from another branch or from before the fork — the last run's branch is kept in .branch), resets the ledger and writes the run's start markers. Exit 1 means the branch is not proven and nothing was destroyed — report which workflow failed and stop. Whatever it prints on its last line about the gate goes in the guide verbatim; "no build proved this" must never read as a pass. Only the authoritative workflows count — "ci": {"workflows": ["ci.yml"]} in human-review.json or --workflow ci.yml (repeatable, all must be green); unset, the one workflow named like ci/build, else every run on the SHA. A green Pages deploy never opens the gate. Cancelled, never-picked-up (runner outage) and GitHub-unreachable are reported as such, not as a red build; the verdict (workflow, run id, SHA) is in .human-review/.gate.json, with sonar (steps' verdict, quality gate, dashboard URL) when that run has Sonar steps — preflight.py --ci-only re-reads it off the recorded run, and adds head (CI on the branch's pushed head when it is not the reviewed commit), with no push and no wipe.

If .human-review/review.html already exists, ask what changed first — see Iterating.

Step 3 — Produce the evidence

First, the film's script — the one producer input that is yours. If none of .human-review/feature-script.js, human-review-feature.js at the repo root, or $HUMAN_REVIEW_FEATURE_SCRIPT exists, write .human-review/feature-script.js now, before the producers run, following reference/feature-script.md: derive the screens from the diff, drive the app through every one the change touched, say() what is new on each. Fork it to a model: sonnet subagent, like the matrix. Without it the video step exits 2, "no feature script", and the Demo tab says nothing was filmed — the reference run had a film because a model wrote this file; the Copilot run of 2 Oct had none because nothing asked it to. Outside a session the same step is a program, scripts/rerun-film.py (claude -p --model sonnet over reference/film-prompt.md), which is what the Demo tab's 🤖 runs.

${SKILL}/scripts/run-steps.py --base "$BASE"

Never end your turn while it runs. It takes 5–15 minutes. Background it if you like and write content.json meanwhile, but then wait for it in the same turn — again and again if a wait times out — until it exits, then build. Under claude -p / copilot -p the session ends with your turn and takes every background child with it: eval run 16 ended on "you'll get the page once that step finishes", and the film died half-rendered. Never start it a second time while one is running.

One command runs every deterministic producer — the branch's own review record, what landed after it, diagram deltas, sequence diagrams, the container view projected from them, Code City, the feature film, complexity, the REST contract and its two second opinions, the logging scan, the design-system audit, code owners, the test manifest, the Playwright recordings — each gated on its own prerequisite, each ledger-wrapped, none of them able to skip its end. When review-points.md records an audited-base on this branch past the fork point, every producer — and the page build after them — measures from it rather than from $BASE's merge-base: a page never mixes two bases.

The first two steps are the Review tab, and neither of them is yours to write:

  • reviewpoints parses review-points.md into .human-review/review-points.json and resolves the two commits by trailer (Review-Points:, Implements:) into .human-review/review-commits.json. Skipped, with a reason, when the file is absent; failed, loudly, when it is there and will not parse. See Step 1.
  • aftermath measures <review commit>..HEAD and splits it by human-review.json's "generated" globs. Anything a human wrote after the agent stopped opens the Review tab as a red band, each commit with a revert button that stages an inverse and stops. This is the one fact on the page no diff can carry, and the one you must not narrate around: if the band is red, say in the guide what those commits were and why, because everything else on the page describes the branch as the agent left it.

Read the status table it prints. Three things in it are yours:

  • skipped — a missing optional binary, an unconfigured step, or a stack that is not up (the design-system audit needs both builds served — it starts them itself from steps.dsaudit.app, and without that block it skips naming the URL that did not answer). Its tab is dropped and named under the strip. That is honest; do not work around it. Unless another step feeds the same tab — tests, traces and testcov all feed Tests — in which case the tab stays and only that step's part of it is missing: say that, not that the tab was dropped. Without testcov the Tests tab's right-hand column is the AI's pairing and says coverage was not measured; with it, the column lists the tests that execute the change, measured per test, and the pairing is a 🤖 chip on the rows AI named.

  • failed — say so in the guide. A failed producer is a fact about the run.

  • note — things only the run knows: an amber PARTIAL LIST seal that is correct, a suite that could not start, and above all video exit 3 — filmed, and the feature did not hold. Lead the whole review with that one. You no longer have to notice it to keep it: the step writes assets/feature.run.log every time and assets/feature.verdict.json on any non-zero exit, and the page draws that verdict as a red band over the player. Say it in the prose as well — the band is the floor, not the review.

    The film is recorded against the instance steps.video.app starts, not against whatever happens to answer on :4200. The design-system audit reads the same block (steps.dsaudit.app, usually "video" to borrow it) and starts two: this branch and the merge-base, which is the only way one step can compare two running builds. Until 19 Sep 2026 it named two fixed ports instead, nothing started them, and the UX tab had been empty on every review since. A project without that block gets the old behaviour plus one guard: the recorder asks the application which commit it is (/actuator/info, or $HUMAN_REVIEW_APP_COMMIT_URL) and refuses to film a different one. An application that cannot say only warns — but if you see that warning, check by hand which tree is up before you believe a frame of it.

  • UNLISTED SCREEN (a dsaudit note) — the branch changed a routed component that no entry in steps.dsaudit.screens reaches, so the design-system audit never looked at the one screen the change was about. That is a hole in the evidence, not a finding to narrate around: add the screen to human-review.json (the list is the app's whole catalogue; only the screens whose DOM changed are drawn) and re-run --only dsaudit before writing the guide. The page prints the same warning in red at the top of UX.

Step 4 — Write the layout, the ledes, and the matrix

This is the only step that is yours, and it is much smaller than it was. The three piles are not in it. content.json names them and nothing more:

"findings":    {"auto": "review-points"},
"autofixes":   {"auto": "review-points"},
"assumptions": {"auto": "review-points"}

and the build fills them from the branch's own record, with the same item shapes the renderers already read. Do not type an item into any of the three. Do not "improve" one the parser produced — the file is committed, and the page disagreeing with it is worse than the page being terse.

${SKILL}/scripts/steps-ledger.py start guide --label "assemble content.json and build the page" \
  > .human-review/.step-guide

The matrix, and the model that checks its pairings

The Tests tab's matrix is drawn by a script, scripts/semcov.py, every build: the ticket (gh issue view, cached in ticket-body.json) rendered on the left and split into sentences with stable ids — followed, when the branch implements an OpenSpec change (openspec/changes/<name>/, matched by branch name or by the issue number its proposal cites), by that change's requirements as a numbered list, paired like the issue's own sentences; on the right the tests whose per-test coverage (assets/test-coverage.json, from the testcov step) runs a line this PR changed, the ones about the change first, each saying on hover which changed lines brought it there; and the colouring and hover/click association between them. The script proposes links — shared words of the test's name and assertions, a synonym table, literals, the changed lines its coverage ran — and every scripted link carries its evidence. A proposed link is a candidate, not proof: run 5 painted "sortable by any column" green over a test that checks the page size.

So a model reads them. Always run it, every review, after run-steps.py and before the build — from the repository root:

${SKILL}/scripts/rerun-model.py           # Sonnet by default, one call for the whole ticket

In one call it confirms or rejects every scripted link with a one-line reason, pairs the sentences the script could not, and marks a sentence narrowed when a scope decision the branch recorded (an assumption or a declined finding in review-points.md, a scope cut in the OpenSpec proposal) delivers less than it says. Until it has run, no scripted link is drawn as covering anything — the sentence reads unconfirmed. It writes .human-review/test-mapping.json (schema: reference/test-mapping.schema.json; prompt: reference/matrix-prompt.md), refuses an answer that fails the schema, names a sentence, test or decision it was not given, or leaves a scripted link without a verdict; it asks nothing only when no sentence makes a claim. Two passes then check the answer and can only lower it, each recording what it took away in the sentence's downgrades: a free script rule drops a link whose test shares nothing specific with its sentence — never an asserted link whose quoted assertion line is in the body, and never the last links of a sentence (those it lowers to exercised: a word filter alone does not turn a sentence red) — and a second cheap call (reference/matrix-check-prompt.md) re-reads every kept link against the test body, must copy the assertion line that proves the claim (looked up in the real body), and turns covered into partial/exercised/missing where it cannot (--no-check, or "mappingCheck": false, turns it off; it runs by default only on haiku, which it was built for). The model is Sonnet unless "mappingModel" in human-review.json (or --model) says otherwise — measured on eval run 8, one Sonnet call beat haiku plus its second read on accuracy and time at about the same price; the press's cost — both calls — is one row of .model-runs.json and shows on the cost tab. Under GitHub Copilot, pick the cheap model (Auto, or gpt-5-mini) yourself: rerun-model.py --prompt-only prints the prompt with its input, you answer it as JSON, and rerun-model.py --answer reply.json checks and installs the answer; --check-prompt and --check-answer check.json do the same for the second read. Never write the matrix HTML yourself — the build draws it. A pairing older than the coverage (test-mapping.json older than assets/test-coverage.json, or a candidate test it was never shown — rerun-model.py records what it showed in offered) makes the build and refresh-report.py warn on stderr and the Tests tab say so over the ticket, with the command. Nothing re-runs it for you: run rerun-model.py again.

The prose that is left

Everything else in the content file is prose: title, subtitle, pr, verdict, an optional note, and the Review tab's block titles and ledes. No summary: the Review tab opens on the grade's computed reasons, and a summary is dropped there. verdict is {"score": n} plus at most two bullets for what only you know — CI, the open piles, a breaking API change, tabs without evidence and commits outside the review are computed, and they cap your score.

Every tab after Review is the scripts', not yours — write nothing on it. Demo, API, Data, Tests, Sequence, Structure, Code City, UX, Complexity, Logging and CODEOWNERS show what a step produced. List them in tabs with the blocks in the reference strip (reference/content-schema.md, The tab strip) and stop: no section of your own, no intro, no snippet, no html block, no re-pointing of swaggerdiff, video, conceptual, requirements-map, ds-audit or complexity-delta at another fragment. The build owns those (scripts/hrbuild/shared/layout.py): it drops anything else on a script-owned tab, rebuilds those sections from its own table, puts back a Demo tab declared empty, and prints each drop on stderr. A run that wrote an API note, a Data section with two hand-picked snippets and a gate green chip produced a different page from the reference one — that is what this rule ends. scope is computed chips only ({"auto": "diffstat"}, {"auto": "tests"}, {"auto": "autofixed"}): a chip you type is dropped, and a gate/CI chip says nothing — a red gate means there is no page.

The writing rule: show the code, do not narrate it. A finding is not a story about a defect, it is the defect, quoted. It still applies, to the tab ledes and the sections:

  • Two or three sentences of prose, hard ceiling. Past that, the reviewer is reading your reasoning instead of their code.
  • Then the code, and most of it is code. Prefer several short captioned snippets over one long one; a caption names the one thing in the lines ("the null branch that never runs"), not the block.
  • Never retype code — extract-snippet.py path:from-to cuts it verbatim at build time.
  • Never type a number the page computes (the diffstat, the cost tab and its label, the auto-fixed count, the test balance, tab costs, the pile counts). A hand-typed number goes stale with nothing noticing — unit tests · 125 green (20 new) was true until somebody wrote the next test, lines +1198 / −863 sat on a page for six days matching no range in the repository at all, and "10 buildings lit" over the Code City shot was a count of a city nobody had recounted. That last one is gone for good: the codecity block takes no lede at all now, and the picture starts under the tab strip. files and lines come from {"auto": "diffstat"}, which measures the change set and leaves generated files out.
  • Never say a test's state yourself. Name the test under the requirement it pins; test-changes.py reads the code for whether it is new, edited, deleted, commented out or sitting under an @Disabled. It is the one thing on the page you would have had to check by hand, and the one a reviewer is least able to check behind you.
  • Never name a specific artefact's absence. "add-visit.genseq.puml does not exist" stopped being true while it was being written. Describe the case; let the renderer say which instances hit it.
  • Never write a paragraph the reader can see. "Twelve items came back. They are one list: the nine that need your judgement first, then the three I applied, greyed out and numbered straight on." — every clause of that is on screen underneath it. The reader is an experienced developer who came for the finding, not for a description of the list the finding is in. Say only what looking cannot tell them, in a line, and let the page do the rest. Where the counts are the whole content, they are computed and you write nothing.
  • A tooltip is a few words. It is read standing up, in one glance, with a hand on the mouse. Numbers the face could not fit, or where a click goes — then stop. Rationale is not tooltip material even when it is true: it goes in the code comment beside the thing, where whoever needs it is already reading.

Write .human-review/content.json against reference/content-schema.md — every shape, every block type, the tab vocabulary, and everything the renderer already enforces so you do not restate it.

Change no code in this step. Not a fix, not a comment, not a rename. The page used to apply the non-disputable half of its own findings and leave them uncommitted for the human to inspect; it no longer triages anything, because the triage happened in the coding session and is recorded. An edit made here would land after the review commit, which is precisely what the aftermath band exists to report — so it would show up on the page, in red, attributed to a human.

Step 5 — Close, check, refresh

${SKILL}/scripts/steps-ledger.py end "$(cat .human-review/.step-guide)"
${SKILL}/scripts/steps-ledger.py check          # exits non-zero on a renamed tab
${SKILL}/scripts/report-cost.py                 # outside Claude Code: --harness copilot-cli
URL=$(${SKILL}/scripts/refresh-report.py | tail -1)

report-cost.py is this run measuring itself — the $ tab's fourth row, this guide: your session's model work since .started (a Claude transcript, or the Copilot CLI / VS Code session that ran /human-review here), the paid model steps you shelled out to, and how long the run took and how much of it the model was working. It writes .human-review/report-cost.json once per run; a refresh adds its own time there, never money. The other three rows were measured by /record-review (review-cost.json).

end before check, so the guide record is closed when the check reads it. check before the refresh, so a DRIFT: line is still actionable — once the page is written, a renamed tab is a column of blanks nobody can tell from a step never instrumented.

refresh-report.py is the build and the server, in that order and for a reason: the build writes .human-review/.actions.json beside the page, and that file is the only thing that lets the served copy run the commands its buttons describe — the environment, the drive-to-cue, the diagram rerun. A page read off disk, or out of the zip, has no manifest next to it and copies them to the clipboard as it always did.

It is also the whole of the machine half of this skill, which is why it is one command and not three to retype. It pins the build to the session that did the work, it builds --no-model so a refresh cannot quietly buy a privacy verdict nobody asked for, and it refuses to build in two cases. One is a missing model-written part — content.json, the model's half of the test pairing (test-mapping.json) — which it cannot re-run. The other is a commit carrying a Review-Points: trailer whose file is not on disk: the branch says it recorded its own review and the record is gone, so the band reading nothing records what was reviewed would be true of the disk and false about the run. Restore the file, or drop the trailer if the claim was never true.

The page opens itself. The first time refresh-report.py starts the server it shows the page — in the VS Code window's own browser, beside the code, when the run is in a VS Code terminal and the Human Review VS Code extension (vscode-extension/ in this repository, victorrentea.human-review) is installed; in the default browser otherwise. Later rebuilds open nothing: the tab already open catches up by itself — it swaps in place only the tabs the rebuild changed (the build writes them beside the page, tabs/<id>.html), and reloads whole when a shared part moved. Do not open it again by hand, and never open review.html.

Print $URL as the last line of the run. Then make sure the app runs from this checkout, open the screen the change affects, and start /relay so they can dictate tweaks — only when a human is there: never in a headless run (claude -p, copilot -p, $CLAUDE_CODE_ENTRYPOINT = sdk-cli, CI). Headless, stop at the URL. An eval run that started the relay sat 20 of its 40 minutes waiting for dictation nobody was going to give.

Iterating on a review that already exists

Most invocations after the first are not reviews — the page is on disk and what is wanted is a change to the page. Has the code changed since the page was built? New commits, a force-push, a finding fixed → re-review, start at Step 1. You will usually not have to ask: a commit that landed since the review commit is already on the page, in the aftermath band, in red. Otherwise it is an iteration, and an iteration is one command:

${SKILL}/scripts/refresh-report.py                  # the page changed: rebuild, re-serve
${SKILL}/scripts/refresh-report.py --steps static   # …and the producers that need nothing up
${SKILL}/scripts/refresh-report.py --steps cheap    # the branch changed: re-derive the fast evidence too
${SKILL}/scripts/refresh-report.py --steps all      # …including the film, the city and the traced suites
${SKILL}/scripts/refresh-report.py --steps static --force   # …ignoring the cache: re-run every producer
${SKILL}/scripts/refresh-report.py --steps static --timing  # …and print what each one cost

A refresh only re-runs the producers whose inputs moved. Each step declares what it reads — git pathspecs in the repository, the producer scripts themselves, and any artifact an earlier step wrote (STEP_INPUTS in run-steps.py) — and a step whose fingerprint matches the one beside its last successful run prints unchanged, N s saved and is skipped. Edit one test body and the test manifest, the complexity bars, the logging scan and the owners check re-run while the diagram deltas and the container view do not. Nothing has to be remembered: the default is incremental, --force is how you ask for all of it, and the cache is keyed on inputs and never on a timestamp, so a hit means nothing this answer depends on has moved rather than somebody said it was fine.

On petclinic that is 1m32s → 5s for a refresh that changes nothing, and about 6s for one that changes a single test. Two thirds of the saving is not the producers at all: a step that runs stamps .steps.json, which the build's cost ledger is cached on, so a single needless step used to cost the build another forty-five seconds re-reading a conversation that had not gained a turn. A refresh therefore no longer stamps the ledger — its step windows would name a stretch of a later session in which none of the reviewed conversation happened. The review's own run (Step 2) still does, which is what the cost attribution is built from.

On the served page, the reader can do the middle one themselves. The masthead carries a Rerun beside the served badge — refresh-report.py --steps static, which is the producers that need nothing up: the diagram deltas, the container view, the complexity increment, the REST contract and its second opinions, the logging scan, code owners and the test manifest. It rebuilds and the tab catches up on the same tab, keeping its place. It is deliberately not --steps cheap: that one keeps traces, whose configured commands are the project's own e2e suite. And it is deliberately not the film — the button says so on its hover, because that is the one a reader is right to worry about.

Beside it, Rerun + AI is the same thing with this skill's own model step in front of it. It is the button form of the matrix instruction above: rerun-model.py asks a cheap model (Sonnet by default) to confirm or reject the script's pairings and pair the rest, rewrites test-mapping.json, and then the static refresh runs with --allow-model and redraws the matrix from it.

Spelt as a program rather than as a fork because a reader is the one pressing it: the page is read outside any Claude session, and someone with the report open in front of them and a branch that has moved cannot fork a subagent. From inside a run, Step 4 is still the way — the fork has the conversation's context and this does not.

It costs cents, and its hover says what the last runs really cost; it asks in the page's own confirmation panel before it spends anything, and the answer it replaces is copied to .human-review/.model-prev/ first: this replaces a judgement rather than refreshing one. content.json is not in it — the layout and the ledes are yours, and no button regenerates them.

The Demo tab has its own 🤖, beside its ↺: the film-only equivalent. rerun-film.py hands reference/film-prompt.md to claude -p --model sonnet, which rewrites .human-review/feature-script.js (the old one goes to .model-prev/ first, and a result that is missing, empty, fails node --check or exports no function is refused), then refresh-report.py --steps video films it again. Same confirmation, its price on the hover out of its own ledger (.human-review/.film-runs.json), and the tab reloads when it is done.

Both buttons exist only where the page is served; read off disk or out of the zip there is nothing behind them, so there is nothing there, and the paid one is also absent where rerun-model.py is not beside the server. A rerun that fails puts the program's last lines in a red band under the header rather than leaving the reader guessing, and only one runs at a time across both — a second click joins the run in flight, and a click that asked for the free half never starts the paid one.

The free rerun is offered a second time, in the aftermath band. A red band says a human moved the code after the review was written, and there are two honest answers to that, as two buttons: Revert it and Regenerate the report. The second is this same Rerun, offered from the place the reader is actually looking at the problem — so when the commits were legitimate (the infrastructure cherry-pick that had to land here), catching the page up does not mean scrolling back to the header. Nothing for you to write: the band renders both.

That is the loop for "the branch moved, catch the page up", and it is the reason to prefer it over a terminal: the three commands are one command here, and the one it runs is the one that cannot cost anything.

Never hand-run the build, the server or run-steps.py to satisfy a request. Edit content.json if the request is about its words, then run the program. That is the point of it: the machine half of this skill is reproducible and free, the model half is neither, and typing the commands by hand is how the two ended up being run together every time somebody wanted a page refreshed. --steps exists so "refresh the page" never silently means "record the feature film again".

Every command the page offers, it offers the same way

Anywhere the page offers an action that is a shell command underneath, the offer wears a copy glyph and — served — a play glyph. The command itself is not printed on the page; it is in the copy glyph's hover. A click on the offer runs it where there is a server and copies it where there is not, so a reader with a terminal open beside the page always has the line and a reader with a server always has the button, and neither has to know which copy of the report they are on.

This matters to you only as things not to do. Do not write "run this in a terminal" into a lede. Do not retype a command into content.json — declare it (runtime, a diagram's rerun) and let the renderer wear it. Do not describe what the glyphs do: the hovers say it, and a sentence repeating them is the page reading itself out loud.

The refresh pins the build to the session that did the work (.human-review/.session), because a build run in a later session cannot recompute what the first one spent and a page that drops the number silently is a page claiming the review was free. If that id is gone, publish no number rather than a measured-looking one: delete .human-review/.steps.json. With no session to ask, the cost tab reports what it still can — what the conversation that wrote the code spent — and says in words why the run's own half is missing. If neither half is measurable the tab drops itself: a pill reading $0 is a claim that this change was free, which is not what an absence means.

Do not re-run the coding session's review passes, do not steps-ledger.py reset, do not rewrite .started, do not wipe assets/, and do not open ledger records for the iteration's own edits. They belong to the run they timed.

The server is sticky, so the URL does not change — and a tab already open on it reloads itself once the build stops writing, so an iteration lands in front of the reader without anybody pressing F5.

What the model half is, so the program half can never be asked to fake it

Written by a model, once, when the human asks — and restored, never regenerated, if it goes missing: test-mapping.json (the cheap model's verdict on the script's pairings, and its pairing of the sentences the script could not decide) and content.json. refresh-report.py exits 3 rather than build a page without them. The matrix itself is no longer on this list: semcov.py draws it on every build from the ticket, the per-test coverage and that JSON. A model-written assets/requirements-map.html from an older run stands in for the JSON (it is rendered as it is, with a note on stderr) until rerun-model.py has run once.

+1 LLM script: .human-review/feature-script.js, the Demo film's script, is model-written too and owned the same way — refresh-report.py never writes or regenerates it, and only a model run (Step 3's fork, or rerun-film.py behind the Demo tab's 🤖) does. Its absence is not a refusal: no script means no film, which the Demo tab already says.

content.json is on that list and no longer for the reason it used to be. It was the judgement — which findings were raised, which were fixed, which were left, what the coder assumed — written by a model at the end of a review and corroborated by nothing outside itself. That record belongs to the branch now: the coding agent writes review-points.md, commits it with the fixes, and the content file asks for the three piles with {"auto": "review-points"}. What is left in it is the layout and the ledes. Still a model's work, still not reproducible, still not something a program will invent for you; a much smaller claim.

Everything else under .human-review/ is the output of a program and may be re-run at any time. The one model call that hides inside a build — the Logging tab's privacy verdicts — is cached by a hash of what was sent, and a refresh runs --no-model: cached verdicts render, uncached statements say not evaluated, and nothing is bought.

Wrap-up

.human-review/ is a throwaway artifact — remind the human to delete it rather than commit it (serve-review.py --stop first). Print the path and the URL. Do not list what you fixed, because you fixed nothing: what was fixed and what was declined is in review-points.md, which is committed, and the page renders it. What is worth saying in the last lines is what the run could not do — a step that skipped, a tab named under the strip, a red aftermath band — and nothing else. Do not commit or push.