@vintasoftware/pr-review-canvas 0.3.0 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vintasoftware/pr-review-canvas",
-  "version": "0.3.0",
-  "description": "Localhost PR review canvas: layered diffs, attention points, and GitHub comments for one PR",
+  "version": "0.5.0",
+  "description": "Localhost PR review canvas: layered diffs, attention points, and GitHub or GitLab comments for one PR",
   "type": "module",
   "bin": {
     "pr-review": "./bin/pr-review.mjs"
@@ -10,7 +10,7 @@
     "dev": "tsx watch --clear-screen=false --ignore '**/.pr-review/**' src/cli.ts serve",
     "start": "tsx src/cli.ts serve",
     "test": "vitest run",
-    "hooks:install": "git config core.hooksPath .githooks",
+    "hooks:install": "git config core.hooksPath \"$(git rev-parse --show-toplevel)/.githooks\"",
     "test:watch": "vitest",
     "test:browser": "playwright test",
     "coverage": "vitest run --coverage",
@@ -23,7 +23,12 @@
     "format": "oxfmt --write",
     "format:check": "oxfmt --check",
     "check": "pnpm lint && pnpm format:check && pnpm typecheck",
-    "precommit": "pnpm check && pnpm test"
+    "precommit": "pnpm check && pnpm test",
+    "site:dev": "vite --config site/vite.config.js",
+    "site:image": "node scripts/render-social-preview.mjs",
+    "site:build": "vite build --config site/vite.config.js",
+    "site:preview": "vite preview --config site/vite.config.js",
+    "site:test": "playwright test --config site/playwright.config.js"
   },
   "dependencies": {
     "@highlightjs/cdn-assets": "^11.12.0",

package/pr-review.config.example.yml

@@ -39,11 +39,51 @@ generation:
   #   rationale: 300
   #   diagram: 1500       # mermaid source, counted raw
 
-# Which paths count as tests, for the layering rules and the `test` pill on a file card.
-# Defaults to the JavaScript and TypeScript conventions below; name your own for other languages
-# (Python: '**/test_*.py', '**/tests/**'; Go: '**/*_test.go').
+# Which paths count as tests, for the layering rules, the `test` pill on a file card, and the
+# light reading level, which keeps test titles on screen. The defaults below match test
+# directories and file-name shapes across stacks (JS/TS, Python, Go, Ruby, Java, Kotlin, PHP,
+# C#, Swift, Elixir, Dart, Rust). A list here replaces them; add `'**/spec/**'` when that
+# directory holds tests in your repository. Snapshots and fixtures inside test paths may still
+# hide at light, since they are generated.
 tests:
-  patterns: ['**/*.test.*', '**/*.spec.*', '**/__tests__/**']
+  patterns:
+    - '**/__tests__/**'
+    - '**/tests/**'
+    - '**/test/**'
+    - '**/*.test.*'
+    - '**/*.spec.*'
+    - '**/*_test.*'
+    - '**/*_spec.*'
+    - '**/test_*.py'
+    - '**/conftest.py'
+    - '**/*Test.java'
+    - '**/*Tests.java'
+    - '**/*Test.kt'
+    - '**/*Tests.kt'
+    - '**/*Test.scala'
+    - '**/*Tests.scala'
+    - '**/*Test.groovy'
+    - '**/*Tests.groovy'
+    - '**/*Test.cs'
+    - '**/*Tests.cs'
+    - '**/*Test.fs'
+    - '**/*Tests.fs'
+    - '**/*Test.vb'
+    - '**/*Tests.vb'
+    - '**/*Test.swift'
+    - '**/*Tests.swift'
+    - '**/*Test.php'
+    - '**/*Tests.php'
 
 chat:
   enabled: true # false removes the chat pane and its routes
+
+canvas:
+  # A canvas stays current for a later head whose diff is identical to the one it was generated
+  # from, as after merging the base branch in. Set false to mark the canvas outdated on every new
+  # commit.
+  keepForIdenticalDiff: true
+  # Regenerating a canvas for a new head starts from the newest canvas of a commit the head was
+  # built on, keeping the layers, folds, notes and attention points its diff leaves untouched.
+  # Set false to generate every canvas from a blank page, as `--force` always does.
+  incremental: true

package/prompts/chat-seed.md

@@ -11,6 +11,9 @@ At most six sentences. No headings unless the reader asks for more. Markdown is
 short lists, `path:line` references. Do not restate the question. Do not summarize the whole PR
 when the reader asked about one file.
 
+Call diff sections **chunks** in answers and proposed comments. Keep code identifiers and
+`#hunk:` link targets unchanged.
+
 ## Answer protocol
 
 For any "is this fine / covered / needed / safe?" question, the verdict comes first, in one of

package/prompts/generation-format.md

@@ -39,6 +39,9 @@ hunk in that file's patch.
 
 ## Layering rules
 
+In reader-facing prose, call diff sections **chunks**. Keep the schema field `hunks` and
+`#hunk:` link targets exactly as specified.
+
 Project-configured layers (optional guidance):
 
 {{CONFIGURED_LAYERS}}
@@ -71,35 +74,129 @@ Project-configured layers (optional guidance):
 
 ## Selective expansion
 
-Keep the reading path focused by collapsing code that is already well understood and supported
-by evidence you read. This changes its initial presentation only: every hunk stays assigned and
-the reviewer can expand the full diff. Collapsing never marks code as reviewed.
-
-- For a test case with meaningful assertions that cover its behavior, show the test title and
-  collapse its body. Keep weak assertions, important omissions, and tests that explain a decision open.
-- Collapse straightforward, well-tested helpers, adapters, and conventional boilerplate when
-  there is no unresolved design choice, performance concern, or other non-functional requirement
-  to examine. A familiar pattern or a passing test name alone is insufficient evidence.
-- Repeated mappings, wiring, fixtures, and generated sections can collapse when their behavior
-  and relevant checks are understood. Keep the representative example open if it teaches the
-  pattern; collapse repetitions that add no new decision.
-- Keep security boundaries, destructive operations, ordering and concurrency rules, performance
-  assumptions, and other consequential behavior visible when they need the reviewer's attention.
-  Keep annotations, attention points, unresolved test gaps, and discussion visible.
-- For an entire routine file, set its `collapsed` field to `true`. Its file header remains visible.
-  Keep tests with the feature they cover even when their bodies are collapsed; confidence is not
-  a reason to move meaningful behavior into Other.
-- Within a file, use `folds`: `{ "title": "test or function/class title", "side": "new",
-  "startLine": 12, "endLine": 28 }`. Each range is inclusive and inside one assigned hunk.
-  The page shows only the title until expanded. Use `old` for a deletion; use one coordinate side
-  for all folds in a hunk, and keep ranges separate. Rows between the two anchors, including
-  interleaved deletions, are part of the fold. Pick boundaries that keep the whole change together.
-  Leave partial or ambiguous ranges open. A function spanning several hunks can use a separate
-  titled range in each hunk, or the whole file can start collapsed when appropriate.
+The reader chooses how much of the diff is on screen, with one control over the whole page. This
+changes the initial presentation only: every hunk stays assigned and the reviewer can expand
+anything. Hiding code never marks it reviewed.
+
+Give every fold and every collapsed file the lowest of the three levels at which it should hide.
+The levels nest, so a `light` fold is also hidden at `moderate` and `aggressive`; write each one
+once, at its own level. The three levels answer three different questions, and each one hides
+much more than the one below it:
+
+- **light — the diff as a reviewer has always seen it.** Nothing hand-written hides. The page
+  already folds imports, whitespace-only rewrites, and moved blocks by itself; `light` adds only
+  wholly generated content — lock files, snapshots, migrations, generated clients and fixtures —
+  as `collapsed: "light"` or a `light` fold over the generated block. Snapshots and fixtures
+  count as generated even inside a test directory. Tests are untouched at `light`: no fold and no
+  collapse in any other test file carries this level.
+- **moderate — what would a reviewer skip once they trust the layer's rationale?** Each test
+  body, folded under its own title so the list of titles reads as the spec of the change: one
+  fold per test, starting on the line after its title; a range that spans several tests hides the
+  titles and is not what this level means. Then everything whose contract its signature, its
+  name, or the layer rationale already states: helpers and adapters, data-transfer and
+  serialization types, request handlers and views that follow the project's pattern, templates
+  and markup, dependency wiring and registration, repeated mappings, configuration. Keep the one
+  representative example open if it teaches a pattern the rest repeats.
+- **aggressive — what must the reviewer judge to decide on this change?** Only that stays open:
+  the code an attention point or annotation names, and the few lines that carry the layer's core
+  mechanism. Everything else in the layer hides behind a title. The reader follows the change as
+  pseudo-code and expands what they want to see. This is the only level that may hide an
+  annotation. Such a fold covers one whole annotation and no other, and the page then shows the
+  annotation's text in place of the fold title.
+
+Aggressive is a strong instruction, not a slight increase over moderate. On a typical layer it
+leaves a small fraction of the changed lines on screen. Check your output before you finish: a
+layer where `moderate` and `aggressive` hide about the same amount has not applied `aggressive`.
+
+Decide first what the layer's **core** is, because the core never collapses at any level. The
+core is the file or two the reviewer must read to own the change: the file your rationale sends
+them to first, the file that defines the layer's new concepts (a schema, a type, a contract, a
+state machine), and every file you annotated. An annotation marks code worth reading; collapsing
+its file would hide the code and the explanation together, with only a path left to say so. Not
+having an attention point does not make a file routine: a new schema with no open question is
+still what everything else in the layer is built on.
+
+Then the two mechanisms split the work:
+
+- `folds` are for the core. The file stays open, and folds hide its routine parts behind titles.
+  At `aggressive` the core file shows its defining lines and its annotations, and nothing else:
+  expect more than half of it to sit inside folds. In a data type the field or column
+  declarations and the constraints stay; the framework's ceremony folds, whatever the stack calls
+  it — string conversion and equality, accessors and builders, type-checker-only blocks, query
+  helpers and repositories, derived-property boilerplate. In a function the signature and the
+  annotated lines stay; argument parsing, presenters, formatting, and error-to-response mapping
+  fold. Inside a core file, folds are `aggressive` by default: at `moderate` the reviewer still
+  reads the core in full and trusts only the other files to the rationale, so the two levels
+  differ by exactly this. Give a core-file range `moderate` only when it is pure ceremony — a
+  repeated import pattern, generated accessors, a type-checker-only block, string conversion.
+  Check the core files before you finish: mostly open at `moderate`, mostly folded at
+  `aggressive`. One fold per contiguous routine block; several small folds are better than one
+  wide title that overstates what it covers.
+- `collapsed` is for everything that is not the core. It hides a file's whole body behind its
+  header. At `moderate` and `aggressive` that is most files of a layer.
+
+A file that carries more than about twenty changed lines and no attention point should hide
+something at `aggressive`: the whole file when it is not the core, its routine ranges when it is.
+
+The validator enforces the shape of this: `collapsed` must name a level (`true` is refused); no
+fold or collapse in a test file may be `light`; a `light` fold covers at most forty lines; a file
+with more than twenty changed lines outside its annotations, no attention point, and neither
+`collapsed` nor a fold fails with `FOLD_MISSING`; a file of more than sixty changed lines that
+stays open must fold at least half of the lines outside its attention points, annotated lines
+included, or fails the same way; and a layer of more than a hundred changed lines that leaves more
+than twenty lines open at `moderate` outside its attention points and hides nothing more at
+`aggressive` fails the same way. A smaller layer reads whole, and only the file rules apply to it.
+An annotation is not a way past these: it marks the lines to read, and the rows around it still
+fold.
+
+Keep visible at every level: security boundaries, destructive operations, ordering and
+concurrency rules, performance assumptions, and other consequential behavior that needs the
+reviewer's attention. Attention points, unresolved test gaps, and discussion are never folded.
+Leaving such a file fully open at every level is the failure this control exists to prevent.
+
+An example of the two together, for a file whose new `settle()` matters and whose rest does not:
+
+```json
+{
+  "path": "domain/billing/actions.py",
+  "hunks": ["domain_billing_actions_py#1"],
+  "annotations": [{ "side": "new", "startLine": 61, "endLine": 66, "text": "Refunds settle before the ledger write, so a failed write leaves no money moved." }],
+  "folds": [
+    { "title": "the retry helper, unchanged in behavior", "side": "new", "startLine": 12, "endLine": 28, "level": "moderate" },
+    { "title": "settle() moves the money, then writes the ledger", "side": "new", "startLine": 55, "endLine": 80, "level": "aggressive" }
+  ]
+}
+```
+
+At `light` the file reads in full. At `moderate` the helper hides. At `aggressive` `settle()`
+hides too, behind the annotation's text.
+
+- A fold is `{ "title": "what the block does", "side": "new", "startLine": 12, "endLine": 28,
+  "level": "light" }`. Each range is inclusive and inside one assigned hunk. The page shows only
+  the title until expanded. Use `old` for a deletion; use one coordinate side for all folds in a
+  hunk. Rows between the two anchors, including interleaved deletions, are part of the fold. Pick
+  boundaries that keep the whole change together. Leave a range open when you cannot place both
+  of its ends. A function spanning several hunks can use a separate titled range in each hunk,
+  or the whole file can collapse instead.
+- Two folds are either separate, or one sits wholly inside the other with the lower level inside.
+  A test body at `moderate` inside its whole test class at `aggressive` is valid; two ranges that
+  cross each other are not.
+- When the declaration line is in the diff, start the fold on the line after it, so the reader
+  keeps the signature and can still find where the symbol is defined. The title then states what
+  the body does rather than repeating the name. When the declaration is outside the diff, the
+  title names the symbol.
+- Set a file's `collapsed` field to the level at which its whole body hides; its header stays
+  visible. `light` is for wholly generated files, such as lock files, snapshots, and migrations,
+  never for a test file, a template, or anything hand-written.
+  At `moderate`, collapse every file the layer rationale already accounts for. At `aggressive`,
+  collapse every file outside the layer's core, which is most of them. A file with an annotation
+  or an attention point never collapses, at any level: it is core, and it uses folds. Keep tests
+  with the feature they cover even when their bodies are collapsed; confidence is not a reason to
+  move meaningful behavior into Other.
 - Generate no explanation or confidence score for a fold. The title is plain text. Use the actual test title or symbol
   name when it fits. For a longer name, use a faithful excerpt with an ellipsis within the fold-title
   cap, preserving the behavior and distinguishing condition. The full name remains in the expanded
-  code. Omit `collapsed` and `folds` where the code should start open.
+  code. Omit `collapsed` and `folds` where the code should start open at every level.
 
 ## Length rules
 

package/prompts/generation-strict-incremental.md

@@ -0,0 +1,53 @@
+# Update the review canvas for a {{TARGET_WORD}}
+
+This {{TARGET_WORD}} already has a canvas, generated for a commit this head was built on. Your task
+is to bring that canvas to the current head: keep what the new commits leave untouched, decide anew
+what they changed, and write the result as one JSON file.
+
+A canvas earns a reviewer's trust by being stable. A layer they already read should come back with
+the same key, the same title, and the same words; a fold they opened should still be there; a
+concern they dismissed should not reappear under a new name. Rewriting a paragraph that describes
+code nobody touched costs the reviewer a second reading for nothing.
+
+## The basis canvas
+
+{{BASIS}}
+
+Read the basis canvas file for the exact wording of anything you carry. Its hunk ids belong to its
+own diff and mean nothing here: use the hunk ids of the manifest below.
+
+### What the head changed
+
+{{FILE_DELTA}}
+
+### Carry these as they stand
+
+{{CARRIED}}
+
+### Decide these again
+
+{{RE_JUDGED}}
+
+## How to update
+
+- Start from the carried content and change it only where this list says to. Where you do depart
+  from the basis canvas on an untouched file, you must have read the new code and have a reason.
+- A carried layer keeps its `key`. The key is how a reviewer's progress finds the layer again, so
+  never rename a key to tidy it up, and never reuse a key for a different concern.
+- A new or changed file belongs wherever it fits best, which may be a carried layer. Adding a file
+  to a layer is a change to that layer: its rationale must still describe what it now holds.
+- A re-judged concern may come back with the same kind, path, and title, but only if you read the
+  new code and it still holds. A concern the change fixed is gone, not softened.
+- Write the summary and the risk tags again, from the whole change set as it is now.
+- Everything below applies as it would to a canvas written from nothing: the layering rules, the
+  caps, the hunk coverage, and the validator.
+
+## Judging the change
+
+Produce a code-quality review that a human can navigate. Read the changed behavior, its tests,
+and the surrounding boundaries. Apply the project rulebook and bundled quality standards to
+identify consequential structural problems, risks, and decisions that need the reviewer's judgment.
+The basis canvas is the record of the structural review already done; extend it rather than
+repeating it.
+
+{{JUDGING}}

package/prompts/generation-strict.md

@@ -5,30 +5,4 @@ and the surrounding boundaries. Apply the project rulebook and bundled quality s
 identify consequential structural problems, risks, and decisions that need the reviewer's judgment.
 Assume no prior structural review unless evidence of one is supplied.
 
-Explain how the change works before asking the reviewer to assess it. Prioritize a small number
-of well-supported concerns; an empty attention-point list is valid. Tie each concern to concrete
-code, its consequence, and the condition under which the design is acceptable. Keep proposed
-changes within the PR's scope. Do not repeat automated lint findings or turn style preferences
-into merge requirements.
-
-Use `decide` for a choice requiring agreement or a substantiated structural concern that needs
-resolution, `check` for a concrete verification, and `fyi` for useful context. Read relevant test
-assertions before classifying behavior as covered or missing. The canvas itself runs no tests and
-provides no approval on the reviewer's behalf.
-
-Write one JSON file grouping the diff into semantic layers, linked explanations, and attention
-points. A deterministic validator checks the file; a web page renders it. Write no prose outside
-the JSON file.
-
-## Project rulebook
-
-Use these code standards to assess consequential drift and debt. Read them as reference material;
-follow this prompt's workflow and output format.
-
-{{RULEBOOK}}
-
-### Bundled standards
-
-{{QUALITY_STANDARDS}}
-
-{{FORMAT}}
+{{JUDGING}}

package/prompts/generation-surfacing-incremental.md

@@ -0,0 +1,56 @@
+# Update the review canvas for a {{TARGET_WORD}}
+
+This {{TARGET_WORD}} already has a canvas, generated for a commit this head was built on. Your task
+is to bring that walkthrough to the current head: keep the reading path the new commits leave
+untouched, rebuild the parts they changed, and write the result as one JSON file.
+
+A walkthrough earns a reviewer's trust by being stable. A layer they already read should come back
+with the same key, the same title, and the same words; a fold they opened should still be there; a
+concern they dismissed should not reappear under a new name. Rewriting an explanation of code
+nobody touched costs the reviewer a second reading for nothing.
+
+## The basis canvas
+
+{{BASIS}}
+
+Read the basis canvas file for the exact wording of anything you carry. Its hunk ids belong to its
+own diff and mean nothing here: use the hunk ids of the manifest below.
+
+### What the head changed
+
+{{FILE_DELTA}}
+
+### Carry these as they stand
+
+{{CARRIED}}
+
+### Decide these again
+
+{{RE_JUDGED}}
+
+## How to update
+
+- Start from the carried content and change it only where this list says to. Where you do depart
+  from the basis canvas on an untouched file, you must have read the new code and have a reason.
+- A carried layer keeps its `key`. The key is how a reviewer's progress finds the layer again, so
+  never rename a key to tidy it up, and never reuse a key for a different concern.
+- A new or changed file belongs wherever it fits best, which may be a carried layer. Adding a file
+  to a layer is a change to that layer: its rationale must still describe what it now holds.
+- Ask what the new commits do to the reading path, not only to the files: a change that answers a
+  question the basis canvas raised should stop being an open question.
+- A re-judged concern may come back with the same kind, path, and title, but only if you read the
+  new code and it still holds. A concern the change fixed is gone, not softened.
+- Write the summary and the risk tags again, from the whole change set as it is now.
+- Everything below applies as it would to a canvas written from nothing: the layering rules, the
+  caps, the hunk coverage, and the validator.
+
+## Build the reading path
+
+Build a visual walkthrough that reads like a peer explaining the PR, and review the code while you
+build it. Help the reviewer understand the code well enough to own it: what changed, how the parts
+cooperate, why the design takes this shape, what they will need to know when maintaining it, and
+what does not hold up.
+
+Use these questions for the parts you rebuild, and only the fields that help for this PR:
+
+{{JUDGING}}

package/prompts/generation-surfacing.md

@@ -7,61 +7,4 @@ what does not hold up.
 
 Build the reading path around these questions, using only the fields that help for this PR:
 
-- What changes for a user or a caller? Start with a concrete before/after example when useful.
-- How does one important request or state transition move through the changed parts? Link the
-  entry point, the owning module, and the resulting effect. A diagram or short pseudocode can
-  explain a long implementation; keep the real diff available through links.
-- Which decisions should the reviewer understand or agree with? Describe the chosen approach,
-  its benefit, its cost, and when the trade-off would need to be revisited. Distinguish a rationale
-  documented by the author from an inference you make from code. Mention alternatives only when
-  they clarify a real choice; do not invent rejected designs or author intent.
-- What gives confidence in the behavior? Point to the relevant test assertions, checks in the
-  code, and explicit limits. Map evidence you actually read rather than conducting an exhaustive
-  coverage audit. An uninspected behavior is not a missing test or a `not-needed` test.
-- What does the next maintainer need to remember? Surface ownership boundaries, ordering rules,
-  failure behavior, operational assumptions, and the places to change when requirements evolve.
-
-## Audit the change as you read it
-
-Explaining the change is half the task. The other half is judging it. Work through the diff with
-the bundled standards below and the project rulebook, and report a small number of well-supported
-problems. Tie each one to concrete code, its consequence, and the condition under which the design
-is acceptable. An empty list is a valid result; a padded list is not.
-
-Give particular weight to these, because a walkthrough reads past them easily:
-
-- **Claims against implementation.** A README sentence, a comment, a constant's name, and the PR
-  description each state a guarantee. The constants, configuration files, schedules, limits,
-  timeouts, and error paths in the diff either deliver it or they do not. Read the value next to
-  the claim. A guarantee that holds only under conditions the deployment does not promise is a
-  defect: name the claim, the value that breaks it, and the consequence.
-- **Values that must relate to each other.** A period, a window, a timeout, a retention, a batch
-  size, and a schedule are chosen against one another. Two values that meet exactly, or in the
-  wrong order, make the behavior depend on timing the system does not control.
-- **Structure.** Consequential drift, debt, and complexity the change adds rather than deletes.
-
-Use `decide` for a choice requiring agreement or a substantiated problem that needs resolution,
-`check` for a concrete verification, and `fyi` for useful context. Use layer rationales and file
-notes to explain the reading path and code flow. Put every decision, trade-off, and specific human
-verification in an attention point, including sound choices the reviewer should understand.
-A trade-off is not automatically a defect. Do not repeat automated lint
-findings, turn style preferences into merge requirements, manufacture concerns, or give a merge
-verdict. Avoid copying the same observation into several fields.
-
-Write one JSON file grouping the diff into semantic layers, linked explanations, and attention
-points. A deterministic validator checks the file; a web page renders it. Write no prose outside
-the JSON file.
-
-## Project rulebook
-
-Use these code standards to assess consequential drift and debt, and to explain project choices and
-boundaries as they arise in the reading path. Read them as reference material; follow this prompt's
-workflow and output format.
-
-{{RULEBOOK}}
-
-### Bundled standards
-
-{{QUALITY_STANDARDS}}
-
-{{FORMAT}}
+{{JUDGING}}

package/prompts/judging-strict.md

@@ -0,0 +1,27 @@
+Explain how the change works before asking the reviewer to assess it. Prioritize a small number
+of well-supported concerns; an empty attention-point list is valid. Tie each concern to concrete
+code, its consequence, and the condition under which the design is acceptable. Keep proposed
+changes within the PR's scope. Do not repeat automated lint findings or turn style preferences
+into merge requirements.
+
+Use `decide` for a choice requiring agreement or a substantiated structural concern that needs
+resolution, `check` for a concrete verification, and `fyi` for useful context. Read relevant test
+assertions before classifying behavior as covered or missing. The canvas itself runs no tests and
+provides no approval on the reviewer's behalf.
+
+Write one JSON file grouping the diff into semantic layers, linked explanations, and attention
+points. A deterministic validator checks the file; a web page renders it. Write no prose outside
+the JSON file.
+
+## Project rulebook
+
+Use these code standards to assess consequential drift and debt. Read them as reference material;
+follow this prompt's workflow and output format.
+
+{{RULEBOOK}}
+
+### Bundled standards
+
+{{QUALITY_STANDARDS}}
+
+{{FORMAT}}

package/prompts/judging-surfacing.md

@@ -0,0 +1,58 @@
+- What changes for a user or a caller? Start with a concrete before/after example when useful.
+- How does one important request or state transition move through the changed parts? Link the
+  entry point, the owning module, and the resulting effect. A diagram or short pseudocode can
+  explain a long implementation; keep the real diff available through links.
+- Which decisions should the reviewer understand or agree with? Describe the chosen approach,
+  its benefit, its cost, and when the trade-off would need to be revisited. Distinguish a rationale
+  documented by the author from an inference you make from code. Mention alternatives only when
+  they clarify a real choice; do not invent rejected designs or author intent.
+- What gives confidence in the behavior? Point to the relevant test assertions, checks in the
+  code, and explicit limits. Map evidence you actually read rather than conducting an exhaustive
+  coverage audit. An uninspected behavior is not a missing test or a `not-needed` test.
+- What does the next maintainer need to remember? Surface ownership boundaries, ordering rules,
+  failure behavior, operational assumptions, and the places to change when requirements evolve.
+
+## Audit the change as you read it
+
+Explaining the change is half the task. The other half is judging it. Work through the diff with
+the bundled standards below and the project rulebook, and report a small number of well-supported
+problems. Tie each one to concrete code, its consequence, and the condition under which the design
+is acceptable. An empty list is a valid result; a padded list is not.
+
+Give particular weight to these, because a walkthrough reads past them easily:
+
+- **Claims against implementation.** A README sentence, a comment, a constant's name, and the PR
+  description each state a guarantee. The constants, configuration files, schedules, limits,
+  timeouts, and error paths in the diff either deliver it or they do not. Read the value next to
+  the claim. A guarantee that holds only under conditions the deployment does not promise is a
+  defect: name the claim, the value that breaks it, and the consequence.
+- **Values that must relate to each other.** A period, a window, a timeout, a retention, a batch
+  size, and a schedule are chosen against one another. Two values that meet exactly, or in the
+  wrong order, make the behavior depend on timing the system does not control.
+- **Structure.** Consequential drift, debt, and complexity the change adds rather than deletes.
+
+Use `decide` for a choice requiring agreement or a substantiated problem that needs resolution,
+`check` for a concrete verification, and `fyi` for useful context. Use layer rationales and file
+notes to explain the reading path and code flow. Put every decision, trade-off, and specific human
+verification in an attention point, including sound choices the reviewer should understand.
+A trade-off is not automatically a defect. Do not repeat automated lint
+findings, turn style preferences into merge requirements, manufacture concerns, or give a merge
+verdict. Avoid copying the same observation into several fields.
+
+Write one JSON file grouping the diff into semantic layers, linked explanations, and attention
+points. A deterministic validator checks the file; a web page renders it. Write no prose outside
+the JSON file.
+
+## Project rulebook
+
+Use these code standards to assess consequential drift and debt, and to explain project choices and
+boundaries as they arise in the reading path. Read them as reference material; follow this prompt's
+workflow and output format.
+
+{{RULEBOOK}}
+
+### Bundled standards
+
+{{QUALITY_STANDARDS}}
+
+{{FORMAT}}