@vintasoftware/pr-review-canvas 0.1.0 → 0.3.0

package/README.md

@@ -43,8 +43,6 @@ Install the command globally once, for use in any project:
 npm install -g @vintasoftware/pr-review-canvas
 ```
 
-The npm installation command will be available after the first release.
-
 ## Set up a project
 
 ```bash
@@ -54,15 +52,19 @@ pr-review doctor --all-checks
 ```
 
 `install-skill` sets up **both Claude Code and Codex** in one command: `.claude/skills/pr-review-canvas`
-and `.agents/skills/pr-review-canvas`, respectively. It also adds `.pr-review/settings.yml` to the
+and `.agents/skills/pr-review-canvas`, respectively. These are portable copies you can commit to Git.
+Re-run `pr-review install-skill` after upgrading the CLI to refresh them. It also adds `.pr-review/settings.yml` to the
 project's `.gitignore`. Restart your coding agent if the skill
 does not appear. Repeat this setup for each project you want to review.
 
 `doctor` checks Git, your GitHub remote, the GitHub CLI and its login, write access to the local
-canvas directory, and whether the skill is installed. It prints a JSON report with a result for
+canvas directory, and whether installed skills match the current package. It prints a JSON report with a result for
 each check and suggested fixes for failures. `doctor --all-checks` also checks that `acpx` runs and
 reports its version. Exit code `0` means all checks passed.
 
+`serve` automatically runs the skill check and warns on stderr if a skill is missing, outdated,
+or modified. The warning includes the reinstall command and does not block startup.
+
 ### Optional: AI Chat install
 
 To ask questions about a PR inside the canvas, install `acpx` globally:
@@ -131,45 +133,34 @@ Canvas generation follows the [skill's model rules](skills/pr-review-canvas/SKIL
 
 ### Project prompt templates
 
-A global install reads `pr-review.config.yml` from the project root. Use its `prompts`
-map to replace individual templates with files you keep in the project's Git repository:
+Customize generation and AI Chat prompts with the `prompts` map in your project's
+`pr-review.config.yml`:
 
 ```yaml
 prompts:
-  generation-format.md: review-prompts/generation-format.md
-  generation-surfacing.md: review-prompts/generation-surfacing.md
-  chat-seed.md: review-prompts/chat-seed.md
+    generation-format.md: review-prompts/generation-format.md
+    generation-surfacing.md: review-prompts/generation-surfacing.md
+    chat-seed.md: review-prompts/chat-seed.md
 ```
 
-To start from the installed templates (for an npm global install):
+Copy the installed templates to start editing (for an npm global install):
 
 ```bash
 mkdir -p review-prompts
 cp "$(npm root -g)/@vintasoftware/pr-review-canvas/prompts/"*.md review-prompts/
 ```
 
-Edit the copies and add entries only for the templates you want to override. Commit
-`pr-review.config.yml` and the referenced files together. Paths resolve from the project
-root, including when running from a subdirectory or using `--repo`. Absolute paths also
-work for personal templates shared across projects. Omitted entries use the installed
-package's defaults; a configured file that cannot be read causes an error.
-
-The six supported keys are `generation-format.md` (schema and output rules),
-`generation-strict.md` and `generation-surfacing.md` (mode wrappers),
-`quality-standards.md` (bundled code standards), `layers-default.md` (taxonomy prose),
-and `chat-seed.md` (the opening AI Chat instructions). `generation.mode` still selects
-the wrapper. The rulebook still takes precedence over code standards, and configured
-layers and caps still supply the template data.
-
-Each file replaces a whole template. Preserve its `{{TOKENS}}`, including `{{FORMAT}}`
-in generation wrappers, to keep the generated context and output contract. Unknown
-generation tokens fail rendering. Chat leaves unknown tokens as written. Prompt edits
-do not change the output schema or validation rules enforced by the tool. Overrides
-remain yours across tool upgrades; compare them with new bundled templates when upgrading.
+Edit the copies and configure only the templates you want to replace. Paths are relative
+to the project root. Omitted entries use the bundled defaults. Keep each template's
+`{{TOKENS}}`, including `{{FORMAT}}` in generation wrappers. Commit the config and
+referenced files together.
 
 Run `prepare` again to apply generation edits (use `--force` for an existing canvas).
 Restart the server after changing the config; chat template edits apply to new threads.
 
+See the [prompt template reference](docs/reference.md#prompt-templates) for supported keys,
+path rules, validation, and upgrades.
+
 ## Contributing
 
 In a clone of this tool, use pnpm for the shared lockfile and development checks:
@@ -177,11 +168,22 @@ In a clone of this tool, use pnpm for the shared lockfile and development checks
 ```bash
 corepack pnpm --version
 corepack pnpm install --frozen-lockfile
+corepack pnpm hooks:install
 corepack pnpm exec playwright install --with-deps chromium
 corepack pnpm verify
 corepack pnpm start --repo /path/to/your-project
 ```
 
+The pre-commit hook runs `pnpm precommit`: lint, formatting, strict type checks, and tests.
+Any failure blocks the commit. Run `pnpm hooks:install`
+once per clone to enable it. Use `pnpm lint:fix` and `pnpm format` to apply automatic fixes.
+CI runs the same checks through `pnpm verify`, with coverage executing the unit tests once.
+
+Run the full `pnpm verify` before pushing. Keep branch coverage at least 96% when adding or
+changing behavior, leaving a margin above CI's 95% minimum. Cover meaningful failure and boundary
+cases rather than lowering thresholds. Each CI job uploads `coverage-node-<version>` with branch
+locations and a summary; locally, these reports are in `coverage/` after `pnpm coverage`.
+
 Run `pr-review --help` for CLI commands. Local data goes in the project's `.pr-review/`
 directory; keep it out of Git.
 

package/docs/reference.md

@@ -1,8 +1,7 @@
 # CLI and configuration reference
 
-For installation, the author/reviewer workflow, and basic settings, start with the
-[README](../README.md). This reference covers command options, configuration values, and behavior
-that matters when customizing or troubleshooting a review.
+This reference covers command options, configuration, and troubleshooting for local PR reviews.
+For setup and the basic review workflow, see the [README](../README.md).
 
 - [CLI options](#cli-options)
 - [Project config](#project-config)
@@ -16,14 +15,14 @@ that matters when customizing or troubleshooting a review.
 
 ### Repository and runtime options
 
-| Option | Applies to | Default and behavior |
-|---|---|---|
-| `--repo <dir>` | All commands | Uses the current directory when omitted; resolves the repository root from there |
-| `--data-dir <dir>` | All except `install-skill` | Overrides `PR_REVIEW_DATA_DIR`, then the default `<main checkout>/.pr-review` |
-| `--port <n>` | `serve` | Overrides `PR_REVIEW_PORT`, then `3010`; accepts 1–65535 |
-| `--agent claude\|codex` | `serve` | Overrides the saved chat agent for this run |
-| `--model <id>` | `serve` | Overrides the saved chat model for this run |
-| `--fixture-canvas <review.json>` | `serve` | Development preview: uses the supplied canvas for every requested PR, with its head replaced by the live PR head |
+| Option                           | Applies to                 | Default and behavior                                                                                             |
+| -------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `--repo <dir>`                   | All commands               | Uses the current directory when omitted; resolves the repository root from there                                 |
+| `--data-dir <dir>`               | All except `install-skill` | Overrides `PR_REVIEW_DATA_DIR`, then the default `<main checkout>/.pr-review`                                    |
+| `--port <n>`                     | `serve`                    | Overrides `PR_REVIEW_PORT`, then `3010`; accepts 1–65535                                                         |
+| `--agent claude\|codex`          | `serve`                    | Overrides the saved chat agent for this run                                                                      |
+| `--model <id>`                   | `serve`                    | Overrides the saved chat model for this run                                                                      |
+| `--fixture-canvas <review.json>` | `serve`                    | Development preview: uses the supplied canvas for every requested PR, with its head replaced by the live PR head |
 
 Repository operations require an `origin` remote on **github.com**. GitHub Enterprise Server
 hosts are not supported. Fetching a PR does not check out its branch.
@@ -75,6 +74,10 @@ pr-review import <zip> [--pr <n>] [--force]
   the archive; it does not select the commit.
 - `--out` defaults to the data directory's `exports/` folder. Supply an existing directory to
   keep the generated filename, or a full `.zip` file path to choose a name.
+- Generated names follow `pr-<number>-<YYYYMMDDTHHmmssZ>-<sha8>-<owner>-<repo>-canvas.zip`,
+  for example `pr-42-20260910T110000Z-aaaaaaaa-acme-widgets-canvas.zip`. The timestamp is the
+  canvas generation time in UTC, to seconds, so exports sort chronologically within each PR.
+  Before a PR exists, `ref-` replaces `pr-<number>-`. Re-exporting the same canvas keeps its name.
 - Export returns `status`, `path`, `name`, `headSha`, and `prNumber` when supplied or stored.
 - `import --pr` compares the imported canvas with that PR's current head. Without it, import does
   not check against a live PR.
@@ -101,8 +104,19 @@ Relative custom paths resolve from the command's working directory. For example:
 pr-review install-skill --codex-dir ~/.codex/skills
 ```
 
-Installation uses relative symlinks on Linux and macOS and copies on Windows. Re-running it
-refreshes its own installation. A customized directory requires `--force` to replace it.
+Installation copies the bundled skill on every platform. The copies and their `.pr-review-install`
+marker files can be committed to Git. Re-running the command refreshes managed copies and replaces
+legacy symlinks. An unmanaged directory requires `--force` to replace it.
+
+Each installed `SKILL.md` records `metadata.body-sha256` in its YAML frontmatter. The SHA-256 hash
+covers the body after the closing frontmatter delimiter, with CRLF normalized to LF. `doctor`
+compares the recorded hash and actual body against the skill bundled with the running CLI. Any
+outdated or modified copy in `.claude/skills` or `.agents/skills` fails the skill check, even if the
+other copy is current. Refresh copies with `pr-review install-skill` (repeat any custom directory
+flags used during installation). Automatic discovery checks the two default directories.
+
+`serve` runs this skill check automatically and prints failures with a repair hint to stderr.
+Warnings do not prevent the server from starting. Use `doctor --all-checks` for full diagnostics.
 The `.gitignore` update always applies to the selected repository root, even with custom skill
 directories.
 
@@ -115,13 +129,13 @@ JSON error. `serve` stays running and writes its startup message to stderr.
 Command failures use `{ "error": { "code", "message", "hint" } }`, with `hint` optional.
 Validation failures from `validate` use its report format instead.
 
-| Exit code | Meaning |
-|---|---|
-| `0` | Success |
-| `1` | Error, including a failed `doctor` check |
-| `2` | Command usage error, such as an unknown command or missing required flag |
-| `4` | GitHub CLI missing or unauthenticated |
-| `5` | Validation failed in `validate` or `publish` |
+| Exit code | Meaning                                                                  |
+| --------- | ------------------------------------------------------------------------ |
+| `0`       | Success                                                                  |
+| `1`       | Error, including a failed `doctor` check                                 |
+| `2`       | Command usage error, such as an unknown command or missing required flag |
+| `4`       | GitHub CLI missing or unauthenticated                                    |
+| `5`       | Validation failed in `validate` or `publish`                             |
 
 `doctor` reports failed checks with exit `1`, including authentication failures.
 
@@ -134,20 +148,20 @@ Lists you supply replace their defaults.
 Path patterns match repository-relative paths. `**` crosses directories; `*` and `?` match
 within one path segment.
 
-| Key | Default | Details |
-|---|---|---|
-| `version` | `1` | The only supported configuration version |
-| `rulebook` | Unset | Path to a Markdown file of project code standards, resolved from the repository root; these standards take precedence over bundled standards |
-| `layers` | Eight architecture groups | Suggested review groups; each entry has `id`, `title`, `description`, and optional `paths` patterns. The generator may split or reorder groups |
-| `highRisk` | `[]` | Entries with a `pattern` glob and `label`; matching changes receive risk labels and cannot go in the Other layer |
-| `generation.mode` | `strict` | See [generation modes](#generation-modes) |
-| `generation.maxRepairRounds` | `3` | Failed validation rounds allowed by the generation skill |
-| `generation.inlineDiffMaxLines` | `1500` | Maximum diff length to include directly in the generation prompt |
-| `generation.smallPrHunks` | `10` | At or below this hunk count, the prompt asks for one layer unless concerns differ |
-| `generation.caps` | See below | Overrides individual text limits |
-| `tests.patterns` | `['**/*.test.*', '**/*.spec.*', '**/__tests__/**']` | Paths treated as tests for review ordering and labels |
-| `chat.enabled` | `true` | Set to `false` to disable AI Chat |
-| `prompts` | Bundled templates | See [prompt customization](../README.md#project-prompt-templates) for supported keys and setup |
+| Key                             | Default                                             | Details                                                                                                                                                                                                                    |
+| ------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`                       | `1`                                                 | The only supported configuration version                                                                                                                                                                                   |
+| `rulebook`                      | Unset                                               | Path to a Markdown file of project code standards, resolved from the repository root; these standards take precedence over bundled standards                                                                               |
+| `layers`                        | `[]`                                                | Optional review guidance; each entry has `id`, `title`, `description`, and optional `paths` patterns. The agent may combine, split, or reorder groups. When omitted or empty, it chooses semantic sections from the change |
+| `highRisk`                      | `[]`                                                | Entries with a `pattern` glob and `label`; matching changes receive risk labels and cannot go in the Other layer                                                                                                           |
+| `generation.mode`               | `strict`                                            | See [generation modes](#generation-modes)                                                                                                                                                                                  |
+| `generation.maxRepairRounds`    | `3`                                                 | Failed validation rounds allowed by the generation skill                                                                                                                                                                   |
+| `generation.inlineDiffMaxLines` | `1500`                                              | Maximum diff length to include directly in the generation prompt                                                                                                                                                           |
+| `generation.smallPrHunks`       | `10`                                                | At or below this hunk count, the prompt asks for one layer unless concerns differ                                                                                                                                          |
+| `generation.caps`               | See below                                           | Overrides individual text limits                                                                                                                                                                                           |
+| `tests.patterns`                | `['**/*.test.*', '**/*.spec.*', '**/__tests__/**']` | Paths treated as tests for review ordering and labels                                                                                                                                                                      |
+| `chat.enabled`                  | `true`                                              | Set to `false` to disable AI Chat                                                                                                                                                                                          |
+| `prompts`                       | Bundled templates                                   | See [prompt templates](#prompt-templates) for supported keys and behavior                                                                                                                                                  |
 
 Generation's numeric options and text caps must be positive integers. An empty `layers` list
 provides no suggested groups; an empty `tests.patterns` list recognizes no files as tests.
@@ -164,23 +178,54 @@ not change an already prepared generation or an existing canvas.
 Both modes read the project rulebook and use the same validation and review controls. The mode
 affects canvas generation; chat answers the reviewer's selected question.
 
+### Prompt templates
+
+The `prompts` map in `pr-review.config.yml` accepts these keys:
+
+| Key                       | Purpose                               |
+| ------------------------- | ------------------------------------- |
+| `generation-format.md`    | Schema and output rules               |
+| `generation-strict.md`    | Instructions for strict mode          |
+| `generation-surfacing.md` | Instructions for surfacing mode       |
+| `quality-standards.md`    | Bundled code standards                |
+| `layering-guidance.md`    | Guidance for grouping related changes |
+| `chat-seed.md`            | Opening AI Chat instructions          |
+
+Each configured file replaces a whole template. Paths resolve from the project root,
+including when running from a subdirectory or using `--repo`. Absolute paths work for
+personal templates shared across projects. Omitted entries use the installed package's
+defaults. A configured file that cannot be read causes an error.
+
+`generation.mode` selects the generation wrapper. The project rulebook takes precedence
+over code standards. Configured layers and caps supply data to the templates.
+
+Preserve `{{TOKENS}}`, including `{{FORMAT}}` in generation wrappers, so generated prompts
+include the context and output requirements. Unknown generation tokens fail rendering;
+chat leaves unknown tokens as written. Prompt edits do not change the output schema or
+validation rules enforced by the tool.
+
+Run `prepare` again to apply generation edits (use `--force` for an existing canvas).
+Restart the server after changing the config; chat template edits apply to new threads.
+Custom templates persist across tool upgrades. Compare them with the new bundled templates
+when upgrading.
+
 ### Text limits
 
 Set any of these keys under `generation.caps`. Prose limits count visible characters, so Markdown
 link targets do not count. `diagram` counts raw Mermaid source characters.
 
-| Key | Default |
-|---|---|
-| `summary` | 1200 |
-| `layerTitle` | 60 |
-| `rationale` | 300 |
-| `decisions` | 600 |
-| `checkByHand` | 400 |
-| `annotation` | 240 |
-| `pointTitle` | 90 |
-| `pointBody` | 600 |
-| `testBehavior` | 120 |
-| `diagram` | 1500 |
+| Key            | Default |
+| -------------- | ------- |
+| `summary`      | 1200    |
+| `layerTitle`   | 60      |
+| `rationale`    | 300     |
+| `decisions`    | 600     |
+| `checkByHand`  | 400     |
+| `annotation`   | 240     |
+| `pointTitle`   | 90      |
+| `pointBody`    | 600     |
+| `testBehavior` | 120     |
+| `diagram`      | 1500    |
 
 The canvas has a separate limit of 12 attention points, including entries generated from missing
 tests. Increasing text caps does not increase that limit.
@@ -191,7 +236,7 @@ Custom patterns replace the JavaScript/TypeScript defaults. For example, a Pytho
 
 ```yaml
 tests:
-  patterns: ['**/test_*.py', '**/tests/**']
+    patterns: ['**/test_*.py', '**/tests/**']
 ```
 
 Test recognition controls ordering, but matching a test to its source file currently follows
@@ -200,18 +245,17 @@ placed in Other while its source is in a regular layer.
 
 ## Local settings and storage
 
-See the [README's settings overview](../README.md#user-local-preferences) for editing preferences
-through the UI. These are the file keys and accepted values:
+The data directory's `settings.yml` accepts these keys and values:
 
-| Key | Default | Accepted values |
-|---|---|---|
-| `version` | `1` | `1` |
-| `skin` | `terminal` | `terminal`, `github` |
-| `theme` | `auto` | `auto`, `light`, `dark` |
-| `agent` | `claude` | `claude`, `codex` |
-| `model` | `null` | A model ID, or `null` for the agent's default |
-| `chatTimeoutSec` | `600` | Integer seconds, 30–3600 |
-| `maxTurns` | `null` | Integer 1–100, or `null` for the agent's default |
+| Key              | Default    | Accepted values                                  |
+| ---------------- | ---------- | ------------------------------------------------ |
+| `version`        | `1`        | `1`                                              |
+| `skin`           | `terminal` | `terminal`, `github`                             |
+| `theme`          | `auto`     | `auto`, `light`, `dark`                          |
+| `agent`          | `claude`   | `claude`, `codex`                                |
+| `model`          | `null`     | A model ID, or `null` for the agent's default    |
+| `chatTimeoutSec` | `600`      | Integer seconds, 30–3600                         |
+| `maxTurns`       | `null`     | Integer 1–100, or `null` for the agent's default |
 
 Invalid settings fall back to defaults. URL parameters `?skin=github&theme=light` can override
 appearance for one page load without saving it.
@@ -230,13 +274,13 @@ Deleting the directory loses saved preferences, canvases, progress, and chat his
 
 Append a fragment to `/review/<pr-number>`:
 
-| Target | Fragment example |
-|---|---|
-| Layer | `#layer:data-access` |
-| File | `#file:src/store.ts` |
-| Hunk | `#hunk:src/store.ts#2` |
-| New-side line range | `#line:src/store.ts:40-52` |
-| Old-side line | `#line:src/store.ts:40:old` |
+| Target              | Fragment example            |
+| ------------------- | --------------------------- |
+| Layer               | `#layer:data-access`        |
+| File                | `#file:src/store.ts`        |
+| Hunk                | `#hunk:src/store.ts#2`      |
+| New-side line range | `#line:src/store.ts:40-52`  |
+| Old-side line       | `#line:src/store.ts:40:old` |
 
 Use the layer key and file path from the canvas. Links open the target file when needed; if a
 line is unavailable, navigation uses the nearest visible row. Recipients need their own running
@@ -300,41 +344,41 @@ sandbox for the agent. Its access also depends on the agent's own permissions. D
 
 ## Troubleshooting
 
-| Symptom or code | Next step |
-|---|---|
-| `NOT_A_REPO` | Run inside a Git clone or pass `--repo <dir>` |
-| `NO_ORIGIN` | Check that `origin` points to a repository on github.com |
-| `GH_MISSING` / `GH_UNAUTHENTICATED` | Follow the [GitHub CLI setup](../README.md#install); check authentication in the same environment that runs the server |
-| `GITHUB_API_ERROR` | Read the underlying error for permissions, rate limits, connectivity, or GitHub service problems |
-| `PR_NOT_FOUND` | Check the PR number, repository, and your access |
-| `CANVAS_NOT_FOUND` | Generate or import a canvas for the requested commit |
-| `CANVAS_INVALID` | Read the format errors; re-export or regenerate the canvas |
-| `CANVAS_REPO_MISMATCH` | Check which clone is open; use `import --force` only when importing from the other repository is intentional |
-| `CANVAS_TOO_LARGE` | The archive exceeds the 20 MiB import limit |
-| `CANVAS_STALE` | The PR head moved; prepare again for the current commit |
-| `MODEL_INVALID` | Fix the reported problems in `model.json`, validate, then publish again |
-| `SKILL_DIR_EXISTS` | The destination contains a customized directory; preserve it elsewhere before replacing it with `--force` |
-| `CHAT_BUSY` | Wait for the running reply or press **stop** |
-| `AGENT_AUTH_REQUIRED` | Sign in through the selected agent's CLI, then retry |
-| `AGENT_MISSING` or missing chat pane | Check the [chat setup](../README.md#optional-ai-chat-install), `chat.enabled`, and that the server can find the installed executables |
-| `AGENT_INCOMPLETE` | Retry the message or increase the chat timeout |
-| `COMMENT_FORBIDDEN` | Check the GitHub account's repository access and token permissions |
-| `COMMENT_LINE_NOT_IN_DIFF` | Choose a line shown in the current diff |
-| `SIGNOFF_INCOMPLETE` | Mark every layer except Other reviewed for this head |
-| `FORBIDDEN_HOST` / `CROSS_ORIGIN` | Open the local server using `localhost` or `127.0.0.1` and submit actions from that page |
+| Symptom or code                      | Next step                                                                                                                                |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `NOT_A_REPO`                         | Run inside a Git clone or pass `--repo <dir>`                                                                                            |
+| `NO_ORIGIN`                          | Check that `origin` points to a repository on github.com                                                                                 |
+| `GH_MISSING` / `GH_UNAUTHENTICATED`  | Install [GitHub CLI](https://cli.github.com), run `gh auth login`, and check authentication in the same environment that runs the server |
+| `GITHUB_API_ERROR`                   | Read the underlying error for permissions, rate limits, connectivity, or GitHub service problems                                         |
+| `PR_NOT_FOUND`                       | Check the PR number, repository, and your access                                                                                         |
+| `CANVAS_NOT_FOUND`                   | Generate or import a canvas for the requested commit                                                                                     |
+| `CANVAS_INVALID`                     | Read the format errors; re-export or regenerate the canvas                                                                               |
+| `CANVAS_REPO_MISMATCH`               | Check which clone is open; use `import --force` only when importing from the other repository is intentional                             |
+| `CANVAS_TOO_LARGE`                   | The archive exceeds the 20 MiB import limit                                                                                              |
+| `CANVAS_STALE`                       | The PR head moved; prepare again for the current commit                                                                                  |
+| `MODEL_INVALID`                      | Fix the reported problems in `model.json`, validate, then publish again                                                                  |
+| `SKILL_DIR_EXISTS`                   | The destination contains a customized directory; preserve it elsewhere before replacing it with `--force`                                |
+| `CHAT_BUSY`                          | Wait for the running reply or press **stop**                                                                                             |
+| `AGENT_AUTH_REQUIRED`                | Sign in through the selected agent's CLI, then retry                                                                                     |
+| `AGENT_MISSING` or missing chat pane | Check `chat.enabled` and confirm the server can find `acpx` and the selected agent; run `pr-review doctor --all-checks`                  |
+| `AGENT_INCOMPLETE`                   | Retry the message or increase the chat timeout                                                                                           |
+| `COMMENT_FORBIDDEN`                  | Check the GitHub account's repository access and token permissions                                                                       |
+| `COMMENT_LINE_NOT_IN_DIFF`           | Choose a line shown in the current diff                                                                                                  |
+| `SIGNOFF_INCOMPLETE`                 | Mark every layer except Other reviewed for this head                                                                                     |
+| `FORBIDDEN_HOST` / `CROSS_ORIGIN`    | Open the local server using `localhost` or `127.0.0.1` and submit actions from that page                                                 |
 
 ### Validation diagnostics
 
 Validation reports name the field, file, hunk, or line to fix. Common groups are:
 
-| Codes | What to check |
-|---|---|
-| `SCHEMA`, `TEXT_TOO_LONG` | Required fields, types, and text limits |
-| `HUNK_UNASSIGNED`, `HUNK_DUPLICATE`, `HUNK_UNKNOWN` | Each known hunk belongs to exactly one layer |
-| `PATH_UNKNOWN`, `TEST_PATH_UNKNOWN` | Referenced files exist in the relevant diff or PR head |
-| `LAYER_EMPTY`, `LAYER_KEY_DUPLICATE` | Layers contain hunks and have unique keys |
-| `OTHER_DUPLICATE`, `OTHER_NOT_LAST`, `RISK_IN_OTHER` | At most one Other layer, last, without risk-tagged changes |
-| `TEST_NOT_LAST`, `TEST_IN_OTHER` | Tests follow the code they cover and use the appropriate layer |
-| `ANNOTATION_OUTSIDE_HUNK`, `POINT_OUTSIDE_DIFF`, `FOLD_INVALID` | Locations and fold ranges fit the assigned diff |
-| `TOO_MANY_POINTS` | Count explicit points and missing-test entries together |
-| `LINK_UNRESOLVED`, `DIAGRAM_NODE_UNKNOWN`, `DIAGRAM_LIMIT` | Link targets, diagram node IDs, and diagram counts |
+| Codes                                                           | What to check                                                  |
+| --------------------------------------------------------------- | -------------------------------------------------------------- |
+| `SCHEMA`, `TEXT_TOO_LONG`                                       | Required fields, types, and text limits                        |
+| `HUNK_UNASSIGNED`, `HUNK_DUPLICATE`, `HUNK_UNKNOWN`             | Each known hunk belongs to exactly one layer                   |
+| `PATH_UNKNOWN`, `TEST_PATH_UNKNOWN`                             | Referenced files exist in the relevant diff or PR head         |
+| `LAYER_EMPTY`, `LAYER_KEY_DUPLICATE`                            | Layers contain hunks and have unique keys                      |
+| `OTHER_DUPLICATE`, `OTHER_NOT_LAST`, `RISK_IN_OTHER`            | At most one Other layer, last, without risk-tagged changes     |
+| `TEST_NOT_LAST`, `TEST_IN_OTHER`                                | Tests follow the code they cover and use the appropriate layer |
+| `ANNOTATION_OUTSIDE_HUNK`, `POINT_OUTSIDE_DIFF`, `FOLD_INVALID` | Locations and fold ranges fit the assigned diff                |
+| `TOO_MANY_POINTS`                                               | Count explicit points and missing-test entries together        |
+| `LINK_UNRESOLVED`, `DIAGRAM_NODE_UNKNOWN`, `DIAGRAM_LIMIT`      | Link targets, diagram node IDs, and diagram counts             |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vintasoftware/pr-review-canvas",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Localhost PR review canvas: layered diffs, attention points, and GitHub comments for one PR",
   "type": "module",
   "bin": {
@@ -10,13 +10,20 @@
     "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",
     "test:watch": "vitest",
     "test:browser": "playwright test",
     "coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
     "test:package": "node scripts/test-package.mjs",
-    "verify": "pnpm typecheck && pnpm coverage && pnpm test:browser --workers=2 && pnpm test:package",
-    "prepublishOnly": "pnpm verify"
+    "verify": "pnpm check && pnpm coverage && pnpm test:browser --workers=2 && pnpm test:package",
+    "prepublishOnly": "pnpm verify",
+    "lint": "oxlint --deny-warnings",
+    "lint:fix": "oxlint --fix --deny-warnings",
+    "format": "oxfmt --write",
+    "format:check": "oxfmt --check",
+    "check": "pnpm lint && pnpm format:check && pnpm typecheck",
+    "precommit": "pnpm check && pnpm test"
   },
   "dependencies": {
     "@highlightjs/cdn-assets": "^11.12.0",
@@ -36,6 +43,8 @@
     "@types/node": "^24.13.3",
     "@vitest/coverage-v8": "^4.1.10",
     "happy-dom": "20.11.2",
+    "oxfmt": "^0.68.0",
+    "oxlint": "^1.83.0",
     "typescript": "^5.9.3",
     "vite": "~8.0.16",
     "vitest": "^4.1.10"

package/pr-review.config.example.yml

@@ -11,35 +11,16 @@ version: 1
 #   generation-strict.md: review-prompts/generation-strict.md
 #   generation-surfacing.md: review-prompts/generation-surfacing.md
 #   quality-standards.md: review-prompts/quality-standards.md
-#   layers-default.md: review-prompts/layers-default.md
+#   layering-guidance.md: review-prompts/layering-guidance.md
 #   chat-seed.md: review-prompts/chat-seed.md
 
-# Default layer taxonomy, in review order. Ids are referenced by `defaultLayerId` in a canvas.
-layers:
-  - id: contracts
-    title: Contracts and schemas
-    description: Types, schemas, and the shapes two modules must agree on.
-  - id: data-access
-    title: Data access
-    description: Queries, repositories, migrations, storage.
-  - id: mappers
-    title: Mappers and DTOs
-    description: Code that turns records into view models and back.
-  - id: hooks-state
-    title: Hooks and state
-    description: Hooks, query definitions, stores, state machines.
-  - id: views
-    title: Views
-    description: Components, screens, styles, copy.
-  - id: routes-wiring
-    title: Routes and wiring
-    description: Route files, providers, shells, entry points.
-  - id: policy-config
-    title: Policy and config
-    description: Access policies, environment variables, feature flags, CI, deployment, docs.
-  - id: mechanical
-    title: Mechanical changes
-    description: Renames, lockfiles, generated files, formatting, moved code.
+# Optional layer guidance. Omit or leave empty for agent-chosen semantic sections.
+layers: []
+# layers:
+#   - id: checkout
+#     title: Checkout
+#     description: Cart totals, payment processing, and order creation.
+#     paths: ['src/checkout/**']
 
 # Blast radius tags. Glob patterns against changed paths; the label shows in the header and the rail.
 highRisk:
@@ -49,10 +30,10 @@ highRisk:
     label: auth
 
 generation:
-  mode: strict          # strict: quality review; surfacing: walkthrough that audits as it reads
-  maxRepairRounds: 3      # publish retries the skill may make after a failed validation
+  mode: strict # strict: quality review; surfacing: walkthrough that audits as it reads
+  maxRepairRounds: 3 # publish retries the skill may make after a failed validation
   inlineDiffMaxLines: 1500 # diffs longer than this are read per file instead of inlined in the prompt
-  smallPrHunks: 10         # at most this many hunks: one layer unless concerns differ, fewer annotations
+  smallPrHunks: 10 # at most this many hunks: one layer unless concerns differ, fewer annotations
   # caps:                  # override the text caps (characters)
   #   summary: 1800
   #   rationale: 300
@@ -65,4 +46,4 @@ tests:
   patterns: ['**/*.test.*', '**/*.spec.*', '**/__tests__/**']
 
 chat:
-  enabled: true            # false removes the chat pane and its routes
+  enabled: true # false removes the chat pane and its routes

package/prompts/generation-format.md

@@ -39,11 +39,11 @@ hunk in that file's patch.
 
 ## Layering rules
 
-The project's default layers, in review order, are the default taxonomy:
+Project-configured layers (optional guidance):
 
-{{DEFAULT_LAYERS}}
+{{CONFIGURED_LAYERS}}
 
-{{LAYERS_DEFAULT}}
+{{LAYERING_GUIDANCE}}
 
 - **Every hunk id must appear in exactly one layer.** The validator rejects an unassigned or
   duplicated hunk. A file's hunks may be spread over several layers.
@@ -55,7 +55,7 @@ The project's default layers, in review order, are the default taxonomy:
 - Test files go at the **end** of the layer whose code they cover, never in a layer of their own,
   and into Other only together with the code they cover. This project counts a file as a test when
   its path matches one of: {{TEST_PATTERNS}}.
-- No empty layers. Set `defaultLayerId` when a layer derives from a default; add, split, or reorder
+- No empty layers. Set `defaultLayerId` only when a layer derives from a configured layer; add, split, or reorder
   layers when the {{TARGET_WORD}} reads better that way. Two to eight layers is typical for a
   {{TARGET_WORD}} of any size; see the size note below for a small one.
 - Each layer's `key` is a short lowercase slug (`auth-session`); links use it.

package/prompts/layering-guidance.md

@@ -0,0 +1,18 @@
+Choose semantic sections from the actual change: group hunks that explain one behavior, concern,
+or decision, even when they span files or directories. Give each layer a specific title that tells
+the reviewer what to understand.
+
+When the project config lists layers, use their descriptions, path hints, and order as guidance.
+Adapt, combine, split, or reorder them to fit the change. When no layers are configured, choose
+sections yourself without assuming an architecture or a fixed list of categories.
+
+Order sections by reviewer value. Lead with the main behavior changes, algorithms, state
+transitions, or API changes. Follow with the integration and wiring that support them. Put
+mechanical or low-importance hunks in Other at the end, subject to the eligibility rules below.
+Bring a prerequisite earlier when it helps explain the main change. These priorities guide the
+reading order; choose the number and names of sections to suit this diff.
+
+Pair each test with its subject. A test file sits at the end of the layer whose code it covers,
+never in a layer of its own. Match by stem: `lab-mapper.test.ts` covers `lab-mapper.ts`, and a
+file under `__tests__/` covers the file with the same name one directory up. A test whose subject
+is in Other may sit in Other; a test whose subject is in a real layer must sit in that layer.

package/skills/pr-review-canvas/SKILL.md

@@ -39,7 +39,14 @@ pr-review prepare --base <ref> --head <ref> [--force]
 Progress goes to stderr. The last stdout line is JSON:
 
 ```json
-{ "canvasDir": "...", "headSha": "...", "mergeBaseSha": "...", "promptPath": "...", "contextPath": "...", "status": "prepared" }
+{
+    "canvasDir": "...",
+    "headSha": "...",
+    "mergeBaseSha": "...",
+    "promptPath": "...",
+    "contextPath": "...",
+    "status": "prepared"
+}
 ```
 
 - `status: "exists"` means a canvas already exists for this head. Stop and tell the user: