@vintasoftware/pr-review-canvas 0.1.0 → 0.2.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,8 +133,8 @@ 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:
@@ -141,35 +143,24 @@ prompts:
   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:
@@ -182,6 +173,11 @@ corepack pnpm verify
 corepack pnpm start --repo /path/to/your-project
 ```
 
+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)
@@ -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.
 
@@ -138,7 +152,7 @@ within one path segment.
 |---|---|---|
 | `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 |
+| `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 |
@@ -147,7 +161,7 @@ within one path segment.
 | `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 |
+| `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,6 +178,37 @@ 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
@@ -200,8 +245,7 @@ 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 |
 |---|---|---|
@@ -304,7 +348,7 @@ sandbox for the agent. Its access also depends on the agent's own permissions. D
 |---|---|
 | `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 |
+| `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 |
@@ -316,7 +360,7 @@ sandbox for the agent. Its access also depends on the agent's own permissions. D
 | `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_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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vintasoftware/pr-review-canvas",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Localhost PR review canvas: layered diffs, attention points, and GitHub comments for one PR",
   "type": "module",
   "bin": {

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:

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/src/canvas/export.ts

@@ -37,7 +37,7 @@ export async function buildCanvasZipFor(
   const number = prNumber ?? stored.prNumber
   const manifest: CanvasManifest = number === undefined ? stored : { ...stored, prNumber: number }
   const zip: CanvasZip = {
-    name: buildCanvasZipName({ repo: manifest.repo, headSha, prNumber: number }),
+    name: buildCanvasZipName({ repo: manifest.repo, headSha, prNumber: number, generatedAt: manifest.generatedAt }),
     bytes: buildCanvasZip(manifest, artifact),
     headSha,
   }

package/src/canvas/name.ts

@@ -4,11 +4,9 @@ import type { Repo } from '../contract/review-artifact.js'
 
 export interface ParsedCanvasName {
   prNumber?: number
-  sha7: string
+  shaPrefix: string
 }
 
-export const CANVAS_NAME_PREFIX = 'pr-review-canvas'
-
 /** Owner and repo names may hold characters a file name should not; runs of them become one dash. */
 function slugPart(value: string): string {
   return value
@@ -24,32 +22,34 @@ export function repoSlug(repo: Repo): string {
 export interface BuildNameOptions {
   repo: Repo
   headSha: string
+  generatedAt: string
   prNumber?: number | undefined
 }
 
-/** `pr-review-canvas-<owner>-<repo>-pr<n>-<sha7>.zip`, without `-pr<n>` before the PR exists. */
+/** PR or ref, UTC generation time to seconds, commit prefix, repository, and canvas marker. */
 export function buildCanvasZipName(opts: BuildNameOptions): string {
-  const pr = opts.prNumber === undefined ? '' : `-pr${opts.prNumber}`
-  return `${CANVAS_NAME_PREFIX}-${repoSlug(opts.repo)}${pr}-${opts.headSha.slice(0, 7)}.zip`
+  const target = opts.prNumber === undefined ? 'ref' : `pr-${opts.prNumber}`
+  const timestamp = new Date(opts.generatedAt).toISOString().slice(0, 19).replace(/[-:]/g, '') + 'Z'
+  return `${target}-${timestamp}-${opts.headSha.slice(0, 8)}-${repoSlug(opts.repo)}-canvas.zip`
 }
 
-const TAIL_RE = /^(?:pr(\d+)-)?([0-9a-f]{7})\.zip$/
+const NAME_RE = /^(?:pr-([1-9]\d*)|ref)-\d{8}t\d{6}z-([0-9a-f]{8})$/
 
 /**
  * Reads a file name as a canvas zip for `repo`. A name for another repository, or one that does
  * not follow the grammar, returns null: discovery uses this to skip attachments that are not ours.
  */
 export function parseCanvasZipName(filename: string, repo: Repo): ParsedCanvasName | null {
-  const prefix = `${CANVAS_NAME_PREFIX}-${repoSlug(repo)}-`
+  const suffix = `-${repoSlug(repo)}-canvas.zip`
   const lower = filename.toLowerCase()
-  if (!lower.startsWith(prefix)) {
+  if (!lower.endsWith(suffix)) {
     return null
   }
-  const m = TAIL_RE.exec(lower.slice(prefix.length))
-  const sha7 = m?.[2]
-  if (sha7 === undefined) {
+  const m = NAME_RE.exec(lower.slice(0, -suffix.length))
+  const shaPrefix = m?.[2]
+  if (shaPrefix === undefined) {
     return null
   }
   const pr = m?.[1]
-  return pr === undefined ? { sha7 } : { prNumber: Number(pr), sha7 }
+  return pr === undefined ? { shaPrefix } : { prNumber: Number(pr), shaPrefix }
 }

package/src/cli.ts

@@ -1,4 +1,3 @@
-import { readFile } from 'node:fs/promises'
 import path from 'node:path'
 import { parseArgs } from 'node:util'
 import { createAgentRunner } from './acpx/acpx.js'
@@ -21,6 +20,7 @@ import { type ReviewArtifact, ReviewArtifactSchema } from './contract/review-art
 import { createGit } from './git/git.js'
 import { createGitHubClient } from './github/gh.js'
 import { loadProjectConfig } from './project-config.js'
+import { checkSkill } from './review/doctor.js'
 import { type AppContext, createAppContext, readPackageVersion } from './server/context.js'
 import { startServer } from './server/node-server.js'
 import { readJson } from './store/atomic-json.js'
@@ -109,6 +109,8 @@ async function serve(argv: string[]): Promise<number> {
     agent: values.agent,
     model: values.model,
   })
+  const skill = await checkSkill(ctx.config.repoRoot)
+  if (!skill.ok) io.stderr(`pr-review doctor: ${skill.detail}. ${skill.hint ?? ''}`)
   startServer(ctx, line => process.stderr.write(`${line}\n`))
   return EXIT.ok
 }
@@ -125,15 +127,6 @@ async function doctorCommand(argv: string[]): Promise<number> {
       version: readPackageVersion(),
       acpxVersion: () => createAgentRunner().acpxVersion(),
       dataDirOverride: dataDir ?? readEnv(process.env, 'PR_REVIEW_DATA_DIR'),
-      exists: async file => {
-        try {
-          // A read, so a dangling symlink and a directory both answer no.
-          await readFile(file)
-          return true
-        } catch {
-          return false
-        }
-      },
     },
     rest,
     io
@@ -144,7 +137,7 @@ async function installSkillCommand(argv: string[]): Promise<number> {
   const { repo, rest } = splitCommonFlags(argv)
   const cwd = process.cwd()
   const repoRoot = await resolveRepoRoot(createGit(repo === undefined ? cwd : path.resolve(cwd, repo)))
-  return runInstallSkill({ repoRoot, cwd, platform: process.platform }, rest, io)
+  return runInstallSkill({ repoRoot, cwd }, rest, io)
 }
 
 export async function main(argv: string[]): Promise<number> {

package/src/commands.ts

@@ -306,7 +306,6 @@ export async function runDoctor(deps: DoctorDeps, argv: string[], io: CliIo): Pr
 export interface InstallSkillEnv {
   repoRoot: string
   cwd: string
-  platform: NodeJS.Platform
 }
 
 /** `install-skill [--claude-dir <dir>] [--codex-dir <dir>] [--force]`, both dirs under the repo root by default. */
@@ -319,7 +318,6 @@ export async function runInstallSkill(env: InstallSkillEnv, argv: string[], io:
   const resolve = (flag: string | undefined, fallback: string): string =>
     flag === undefined ? path.join(env.repoRoot, fallback) : path.resolve(env.cwd, flag)
   const result = await installSkill({
-    platform: env.platform,
     force: values.force === true,
     targets: [
       { kind: 'claude', dir: resolve(values['claude-dir'], CLAUDE_SKILLS_DIR) },

package/src/github/attachments.ts

@@ -94,9 +94,9 @@ export function rankCandidates(
   candidates: AttachmentCandidate[],
   target: { headSha: string; prNumber: number }
 ): AttachmentCandidate[] {
-  const sha7 = target.headSha.slice(0, 7)
+  const shaPrefix = target.headSha.slice(0, 8)
   const score = (c: AttachmentCandidate): number =>
-    (c.parsed.sha7 === sha7 ? 2 : 0) + (c.parsed.prNumber === target.prNumber ? 1 : 0)
+    (c.parsed.shaPrefix === shaPrefix ? 2 : 0) + (c.parsed.prNumber === target.prNumber ? 1 : 0)
   return [...candidates].sort(
     (a, b) => score(b) - score(a) || b.postedAt.localeCompare(a.postedAt) || b.order - a.order
   )
@@ -261,7 +261,7 @@ async function tryCandidate(
   const shared = {
     url: candidate.url,
     name: candidate.name,
-    matchesHead: candidate.parsed.sha7 === pr.headSha.slice(0, 7),
+    matchesHead: candidate.parsed.shaPrefix === pr.headSha.slice(0, 8),
   }
   const download = await downloadAttachment(ctx, candidate.url)
   if (!download.ok) {

package/src/project-config.ts

@@ -41,7 +41,7 @@ export const PromptOverridesSchema = z.object({
   'generation-strict.md': z.string().min(1).optional(),
   'generation-surfacing.md': z.string().min(1).optional(),
   'quality-standards.md': z.string().min(1).optional(),
-  'layers-default.md': z.string().min(1).optional(),
+  'layering-guidance.md': z.string().min(1).optional(),
   'chat-seed.md': z.string().min(1).optional(),
 }).strict()
 export type PromptOverrides = z.infer<typeof PromptOverridesSchema>
@@ -86,49 +86,9 @@ const PartialProjectConfigSchema = z.object({
   chat: z.object({ enabled: z.boolean().optional() }).optional(),
 })
 
-/** The 8 architecture groups, in review order. A project file replaces the list. */
-export const DEFAULT_LAYERS: DefaultLayer[] = [
-  {
-    id: 'contracts',
-    title: 'Contracts and schemas',
-    description: 'Types, Zod schemas, FHIR profiles, and the shapes two packages must agree on.',
-  },
-  {
-    id: 'data-access',
-    title: 'Data access',
-    description: 'Server functions, FHIR client calls, repositories, migrations, and storage.',
-  },
-  {
-    id: 'mappers',
-    title: 'Mappers and DTOs',
-    description: 'Code that turns resources or rows into view models and back.',
-  },
-  {
-    id: 'hooks-state',
-    title: 'Hooks and state',
-    description: 'React hooks, query definitions, stores, and client-side state machines.',
-  },
-  { id: 'views', title: 'Views', description: 'Components, screens, styles, and copy.' },
-  {
-    id: 'routes-wiring',
-    title: 'Routes and wiring',
-    description: 'Route files, providers, app shells, dependency wiring, and entry points.',
-  },
-  {
-    id: 'policy-config',
-    title: 'Policy and config',
-    description: 'Access policies, environment variables, feature flags, CI, and deployment config.',
-  },
-  {
-    id: 'mechanical',
-    title: 'Mechanical changes',
-    description: 'Renames, lockfiles, generated files, formatting, and moved code.',
-  },
-]
-
 export const DEFAULT_PROJECT_CONFIG: ProjectConfig = {
   version: 1,
-  layers: DEFAULT_LAYERS,
+  layers: [],
   highRisk: [],
   generation: { mode: 'strict', maxRepairRounds: 3, inlineDiffMaxLines: 1500, smallPrHunks: 10 },
   tests: { patterns: [...DEFAULT_TEST_PATTERNS] },
@@ -167,7 +127,7 @@ export function mergeProjectConfig(raw: unknown): { config: ProjectConfig; warni
   }
   const config: ProjectConfig = {
     version: 1,
-    layers: user.layers ?? DEFAULT_LAYERS,
+    layers: user.layers ?? [],
     highRisk: user.highRisk ?? [],
     generation,
     tests: { patterns: user.tests?.patterns ?? [...DEFAULT_TEST_PATTERNS] },
@@ -180,9 +140,6 @@ export function mergeProjectConfig(raw: unknown): { config: ProjectConfig; warni
     config.prompts = user.prompts
   }
   const warnings: string[] = []
-  if (config.layers.length === 0) {
-    warnings.push(`${PROJECT_CONFIG_FILE}: "layers" is empty, the model gets no default taxonomy`)
-  }
   if (config.tests.patterns.length === 0) {
     warnings.push(`${PROJECT_CONFIG_FILE}: "tests.patterns" is empty, so no file counts as a test`)
   }

package/src/review/doctor.ts

@@ -1,13 +1,14 @@
 // `pr-review doctor`: one pass over everything the tool needs before it can serve a review, as
 // one JSON line. It reports instead of throwing, so a broken setup still answers.
 import { randomBytes } from 'node:crypto'
-import { rm, writeFile } from 'node:fs/promises'
+import { readFile, rm, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import { parseGithubRemote } from '../config.js'
 import type { Git } from '../git/git.js'
 import type { GitHubClient } from '../github/gh.js'
 import { ensureDataDir, resolveDataDir } from '../store/data-dir.js'
-import { CLAUDE_SKILLS_DIR, CODEX_SKILLS_DIR, SKILL_NAME } from './install-skill.js'
+import { CLAUDE_SKILLS_DIR, CODEX_SKILLS_DIR, SKILL_NAME, SKILL_SOURCE_DIR } from './install-skill.js'
+import { skillContent } from './skill-content.js'
 
 export const DOCTOR_CHECKS = ['git', 'origin', 'gh', 'ghAuth', 'dataDir', 'skill'] as const
 export type DoctorCheckName = (typeof DOCTOR_CHECKS)[number]
@@ -31,8 +32,7 @@ export interface DoctorDeps {
   acpxVersion: () => Promise<string | null>
   /** `--data-dir` or `PR_REVIEW_DATA_DIR`; without it the dir sits next to the git common dir. */
   dataDirOverride?: string | undefined
-  /** Answers whether a file can be read; the skill check asks for the SKILL.md inside. */
-  exists: (file: string) => Promise<boolean>
+  readSkill?: (file: string) => Promise<string | null>
 }
 
 function message(err: unknown): string {
@@ -56,19 +56,40 @@ async function checkDataDir(dir: string): Promise<DoctorCheck> {
 }
 
 /** The skill the generation flow needs, in either harness's directory. */
-async function checkSkill(repoRoot: string | null, exists: DoctorDeps['exists']): Promise<DoctorCheck> {
+export async function checkSkill(
+  repoRoot: string | null,
+  readSkill: NonNullable<DoctorDeps['readSkill']> = file => readFile(file, 'utf8')
+): Promise<DoctorCheck> {
   if (repoRoot === null) {
     return { ok: false, detail: 'no repository, so no skill directory to look in', hint: 'run from a clone' }
   }
   const targets = [CLAUDE_SKILLS_DIR, CODEX_SKILLS_DIR].map(dir => path.join(repoRoot, dir, SKILL_NAME))
   const found: string[] = []
+  const stale: string[] = []
+  let expected: string
+  try {
+    expected = skillContent(await readFile(path.join(SKILL_SOURCE_DIR, 'SKILL.md'), 'utf8')).hash
+  } catch (err) {
+    return { ok: false, detail: message(err), hint: 'reinstall the pr-review package' }
+  }
   for (const target of targets) {
-    // The file the harness reads, not the directory: an empty directory, a dangling link, and
-    // an unreadable file all install nothing.
-    if (await exists(path.join(target, 'SKILL.md'))) {
+    try {
+      const text = await readSkill(path.join(target, 'SKILL.md'))
+      if (text === null) continue
       found.push(path.relative(repoRoot, target))
+      const { hash, frontmatter } = skillContent(text)
+      if (hash !== expected || frontmatter.getIn(['metadata', 'body-sha256']) !== expected) {
+        stale.push(path.relative(repoRoot, target))
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+        stale.push(`${path.relative(repoRoot, target)}: ${message(err)}`)
+      }
     }
   }
+  if (stale.length > 0) {
+    return { ok: false, detail: `outdated or modified skill: ${stale.join(', ')}`, hint: 'run `pr-review install-skill`' }
+  }
   if (found.length === 0) {
     return {
       ok: false,
@@ -130,7 +151,7 @@ export async function runDoctorChecks(deps: DoctorDeps, options: { allChecks?: b
     dataDir = { ok: false, detail: message(err), hint: 'pass --data-dir <dir>' }
   }
 
-  const skill = await checkSkill(repoRoot, deps.exists)
+  const skill = await checkSkill(repoRoot, deps.readSkill)
   const checks: DoctorReport['checks'] = { git, origin, gh, ghAuth, dataDir, skill }
   if (options.allChecks) {
     checks.acpx = await checkAcpx(deps)

package/src/review/install-skill.ts

@@ -1,9 +1,10 @@
-// `pr-review install-skill`: link the bundled skill into the host repo's skill directories, so
+// `pr-review install-skill`: copy the bundled skill into the host repo's skill directories, so
 // Claude Code (`.claude/skills`) and Codex (`.agents/skills`) both see `/pr-review-canvas`.
-import { appendFile, cp, lstat, mkdir, readlink, realpath, rm, symlink, writeFile } from 'node:fs/promises'
+import { appendFile, cp, lstat, mkdir, readFile, realpath, rm, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import { PACKAGE_ROOT } from '../server/context.js'
 import { readText } from '../store/atomic-json.js'
+import { stampSkill } from './skill-content.js'
 
 export const SKILL_NAME = 'pr-review-canvas'
 export const SKILL_SOURCE_DIR = path.join(PACKAGE_ROOT, 'skills', SKILL_NAME)
@@ -27,39 +28,38 @@ export interface InstallSkillOptions {
   /** Absolute skills directories to install into; each gets `<dir>/pr-review-canvas`. */
   targets: Array<{ kind: 'claude' | 'codex'; dir: string }>
   source?: string
-  /** Windows copies; everything else links. */
-  platform?: NodeJS.Platform
   /** Replace a real directory that already sits at the target. */
   force?: boolean
 }
 
-/** A real directory (a customized copy of the skill) sits where the link would go. */
+/** Preserve directories that were not created by the installer unless forced. */
 export class SkillDirExistsError extends Error {
   readonly path: string
 
   constructor(target: string) {
-    super(`${target} is a directory, not a link to the bundled skill`)
+    super(`${target} is a directory, not a managed copy of the bundled skill`)
     this.name = 'SkillDirExistsError'
     this.path = target
   }
 }
 
-export type InstallStatus = 'linked' | 'copied' | 'exists' | 'replaced'
+export type InstallStatus = 'copied'
 
 export interface InstallSkillResult {
   skill: string
   targets: Array<{ kind: 'claude' | 'codex'; path: string; status: InstallStatus }>
 }
 
-/** What sits at the target now: nothing, a symlink (with its target), or something else. */
-async function inspect(target: string): Promise<{ kind: 'none' } | { kind: 'link'; to: string } | { kind: 'other' }> {
+/** Inspect the entry without following a possibly dangling symlink. */
+async function inspect(target: string): Promise<{ kind: 'none' } | { kind: 'link' } | { kind: 'other' }> {
   let stats: Awaited<ReturnType<typeof lstat>>
   try {
     stats = await lstat(target)
-  } catch {
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
     return { kind: 'none' }
   }
-  return stats.isSymbolicLink() ? { kind: 'link', to: await readlink(target) } : { kind: 'other' }
+  return stats.isSymbolicLink() ? { kind: 'link' } : { kind: 'other' }
 }
 
 /** A copy carries a marker file, so a later run can tell it from a hand-made directory. */
@@ -68,7 +68,7 @@ export const COPY_MARKER = '.pr-review-install'
 async function installOne(
   source: string,
   dir: string,
-  copy: boolean,
+  content: string,
   force: boolean
 ): Promise<{ path: string; status: InstallStatus }> {
   await mkdir(dir, { recursive: true })
@@ -78,29 +78,25 @@ async function installOne(
   if (current.kind === 'other' && !force && (await inspect(path.join(target, COPY_MARKER))).kind === 'none') {
     throw new SkillDirExistsError(target)
   }
-  if (copy) {
-    await rm(target, { recursive: true, force: true })
-    await cp(source, target, { recursive: true })
-    await writeFile(path.join(target, COPY_MARKER), `copied from ${source}\n`, 'utf8')
-    return { path: target, status: 'copied' }
+  if (current.kind === 'other') {
+    const realTarget = await realpath(target)
+    if (source === realTarget || source.startsWith(`${realTarget}${path.sep}`)) {
+      throw new Error('Cannot install a skill over its source directory')
+    }
   }
-  const relative = path.relative(realDir, source)
-  if (current.kind === 'link' && current.to === relative) {
-    return { path: target, status: 'exists' }
-  }
-  if (current.kind !== 'none') {
-    await rm(target, { recursive: true, force: true })
-  }
-  await symlink(relative, target, 'dir')
-  return { path: target, status: current.kind === 'none' ? 'linked' : 'replaced' }
+  await rm(target, { recursive: true, force: true })
+  await cp(source, target, { recursive: true, dereference: true })
+  await writeFile(path.join(target, 'SKILL.md'), content, 'utf8')
+  await writeFile(path.join(target, COPY_MARKER), 'pr-review managed skill copy\n', 'utf8')
+  return { path: target, status: 'copied' }
 }
 
 export async function installSkill(opts: InstallSkillOptions): Promise<InstallSkillResult> {
   const source = await realpath(opts.source ?? SKILL_SOURCE_DIR)
-  const copy = (opts.platform ?? process.platform) === 'win32'
+  const content = stampSkill(await readFile(path.join(source, 'SKILL.md'), 'utf8'))
   const targets: InstallSkillResult['targets'] = []
   for (const t of opts.targets) {
-    const done = await installOne(source, t.dir, copy, opts.force === true)
+    const done = await installOne(source, t.dir, content, opts.force === true)
     targets.push({ kind: t.kind, ...done })
   }
   return { skill: SKILL_NAME, targets }

package/src/review/prompt.ts

@@ -13,19 +13,19 @@ export { PROMPTS_DIR }
 export interface PromptSources {
   generation: Record<GenerationMode, string>
   format: string
-  layersDefault: string
+  layeringGuidance: string
   qualityStandards: string
 }
 
 export async function loadPromptSources(dir = PROMPTS_DIR, project?: ProjectPrompts): Promise<PromptSources> {
-  const [format, layersDefault, qualityStandards, strict, surfacing] = await Promise.all([
+  const [format, layeringGuidance, qualityStandards, strict, surfacing] = await Promise.all([
     loadPromptFile('generation-format.md', dir, project),
-    loadPromptFile('layers-default.md', dir, project),
+    loadPromptFile('layering-guidance.md', dir, project),
     loadPromptFile('quality-standards.md', dir, project),
     loadPromptFile('generation-strict.md', dir, project),
     loadPromptFile('generation-surfacing.md', dir, project),
   ])
-  return { format, layersDefault, qualityStandards, generation: { strict, surfacing } }
+  return { format, layeringGuidance, qualityStandards, generation: { strict, surfacing } }
 }
 
 /** The line ranges of a hunk header; the trailing function context can hold backticks. */
@@ -64,9 +64,9 @@ function inlineDiffs(files: readonly FileEntry[], patches: Record<string, string
     .join('\n\n')
 }
 
-function defaultLayersMarkdown(ctx: GenerationContext): string {
+function configuredLayersMarkdown(ctx: GenerationContext): string {
   if (ctx.defaultLayers.length === 0) {
-    return '_The project config lists no default layers; choose the layers yourself._'
+    return '_No layers are configured; divide the change into semantic sections based on its behavior and concerns._'
   }
   return ctx.defaultLayers
     .map((l, i) => {
@@ -164,7 +164,7 @@ function smallPrMarkdown(ctx: GenerationContext): string {
   }
   return (
     `**Small change set.** This ${ctx.target.kind === 'pr' ? 'pull request' : 'change set'} has ${hunks} hunks, at most ${limit}, so:\n\n` +
-    '- Use one layer unless the concerns truly differ; do not split for the sake of the taxonomy.\n' +
+    '- Use one layer unless the concerns truly differ; do not split merely to fill suggested groups.\n' +
     '- Annotate only where the diff does not speak for itself; zero annotations is a fine answer.\n' +
     '- Keep the summary self-contained: state the behavior change and the one relationship or decision worth understanding.'
   )
@@ -207,8 +207,8 @@ export function renderPrompt(ctx: GenerationContext, patches: Record<string, str
     MODEL_PATH: ctx.paths.model,
     MANIFEST: manifestMarkdown(ctx.files),
     DIFFS: diffsMarkdown(ctx, patches),
-    DEFAULT_LAYERS: defaultLayersMarkdown(ctx),
-    LAYERS_DEFAULT: sources.layersDefault.trim(),
+    CONFIGURED_LAYERS: configuredLayersMarkdown(ctx),
+    LAYERING_GUIDANCE: sources.layeringGuidance.trim(),
     CAPS: capsMarkdown(ctx),
     MAX_POINTS: String(ctx.limits.maxPoints),
     MAX_DIAGRAMS: String(ctx.limits.maxDiagramsPerLayer),

package/src/review/skill-content.ts

@@ -0,0 +1,20 @@
+import { createHash } from 'node:crypto'
+import { parseDocument } from 'yaml'
+
+/** Normalize checkout line endings so Git's CRLF conversion does not stale a copy. */
+export function skillContent(text: string) {
+  const normalized = text.replace(/\r\n/g, '\n')
+  const match = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(normalized)
+  if (!match) throw new Error('SKILL.md is missing YAML frontmatter')
+  const frontmatter = parseDocument(match[1]!)
+  if (frontmatter.errors.length) throw new Error('SKILL.md has invalid YAML frontmatter')
+  const body = normalized.slice(match[0].length)
+  const hash = createHash('sha256').update(body).digest('hex')
+  return { frontmatter, body, hash }
+}
+
+export function stampSkill(text: string): string {
+  const { frontmatter, body, hash } = skillContent(text)
+  frontmatter.setIn(['metadata', 'body-sha256'], hash)
+  return `---\n${frontmatter.toString()}---\n${body}`
+}

package/static/js/empty-state.js

@@ -50,7 +50,7 @@ export function validateCanvasFilename(filename) {
   if (!filename.toLowerCase().endsWith('.zip')) {
     return 'that is not a zip file'
   }
-  return filename.toLowerCase().startsWith('pr-review-canvas-') ? null : 'that zip is not a review canvas export'
+  return /^(?:pr-[1-9]\d*|ref)-.+-canvas\.zip$/i.test(filename) ? null : 'that zip is not a review canvas export'
 }
 
 /**

package/static/js/settings.js

@@ -66,7 +66,7 @@ export function settingsDialogHtml(data, agents) {
     '<div class="panel-ro"><h3>Project config (read-only)</h3>' +
     `<ul class="plain"><li>chat enabled: ${project.chatEnabled ? 'yes' : 'no'}</li>` +
     `<li>rulebook: ${esc(project.rulebook ?? 'none')}</li>` +
-    `<li>layers in the taxonomy: ${project.layers}</li>` +
+    `<li>configured layer suggestions: ${project.layers}</li>` +
     `<li>high-risk patterns: ${project.highRisk}</li>` +
     `<li>max repair rounds: ${project.maxRepairRounds}</li>` +
     `<li>inline diff max lines: ${project.inlineDiffMaxLines}</li>` +

package/prompts/layers-default.md

@@ -1,13 +0,0 @@
-Order the layers so each one depends only on the layers above it. A wrong shape in a contract
-invalidates every judgment about the code that consumes it, so contracts and schemas come first;
-policy and config come late because you can only judge an access policy or an env var after you
-know what the code reads. The configured default layers already follow this order. Keep it unless
-the pull request reads better another way, and say why in the rationale when you reorder.
-
-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.
-
-Group by feature only when the pull request is wide. One feature area means the flat order above.
-Two or more areas mean one layer per area and stage, still in dependency order.