@vintasoftware/pr-review-canvas 0.1.0 → 0.3.0

package/src/github/comments.ts

@@ -110,9 +110,12 @@ export async function fetchComments(
     fetchAllPages(gh, `${base}/issues/${number}/comments`),
   ])
   const reviews = (await fetchAllPages(gh, `${base}/pulls/${number}/reviews`)).flatMap(raw => {
-    const review = GhIssueCommentSchema.omit({ created_at: true }).extend({
-      submitted_at: z.string().nullable().optional(), state: z.string(),
-    }).parse(raw)
+    const review = GhIssueCommentSchema.omit({ created_at: true })
+      .extend({
+        submitted_at: z.string().nullable().optional(),
+        state: z.string(),
+      })
+      .parse(raw)
     if (!review.submitted_at || review.state === 'PENDING') return []
     return [{ ...mapIssueComment({ ...review, created_at: review.submitted_at }), state: review.state }]
   })

package/src/github/gh.ts

@@ -140,14 +140,24 @@ export function createGitHubClient(exec: GhExec = execGh): GitHubClient {
       }
       const r = await exec(args)
       if (r.code !== 0) {
-        throw new GitHubApiError(path, r.missingBinary ? 'gh: command not found' : r.stderr, r.code, r.missingBinary)
+        throw new GitHubApiError(
+          path,
+          r.missingBinary ? 'gh: command not found' : r.stderr,
+          r.code,
+          r.missingBinary
+        )
       }
       return JSON.parse(r.stdout) as unknown
     },
     apiWithHeaders: async path => {
       const r = await exec(['api', '-i', '--method', 'GET', path])
       if (r.code !== 0) {
-        throw new GitHubApiError(path, r.missingBinary ? 'gh: command not found' : r.stderr, r.code, r.missingBinary)
+        throw new GitHubApiError(
+          path,
+          r.missingBinary ? 'gh: command not found' : r.stderr,
+          r.code,
+          r.missingBinary
+        )
       }
       return parseIncludedResponse(r.stdout)
     },
@@ -155,7 +165,12 @@ export function createGitHubClient(exec: GhExec = execGh): GitHubClient {
       // The payload goes over stdin, so no comment text ever appears in an argument list.
       const r = await exec(['api', '--method', 'POST', path, '--input', '-'], { input: JSON.stringify(body) })
       if (r.code !== 0) {
-        throw new GitHubApiError(path, r.missingBinary ? 'gh: command not found' : r.stderr, r.code, r.missingBinary)
+        throw new GitHubApiError(
+          path,
+          r.missingBinary ? 'gh: command not found' : r.stderr,
+          r.code,
+          r.missingBinary
+        )
       }
       return JSON.parse(r.stdout) as unknown
     },

package/src/github/post-comment.ts

@@ -81,7 +81,10 @@ export function commentRequest(
       return { path: `${base}/pulls/${number}/comments`, body }
     }
     case 'reply':
-      return { path: `${base}/pulls/${number}/comments/${input.inReplyToId}/replies`, body: { body: input.body } }
+      return {
+        path: `${base}/pulls/${number}/comments/${input.inReplyToId}/replies`,
+        body: { body: input.body },
+      }
     case 'issue':
       return { path: `${base}/issues/${number}/comments`, body: { body: input.body } }
   }

package/src/github/pr.ts

@@ -100,7 +100,10 @@ export function prBaseRef(number: number): string {
  * it is local once the base was fetched). Today's base tip would contain the PR and give an
  * empty diff.
  */
-export async function fetchPrRefs(git: Git, meta: PrMeta): Promise<{ headSha: string; mergeBaseSha: string }> {
+export async function fetchPrRefs(
+  git: Git,
+  meta: PrMeta
+): Promise<{ headSha: string; mergeBaseSha: string }> {
   await git.fetch('origin', [
     `+pull/${meta.number}/head:${prHeadRef(meta.number)}`,
     `+refs/heads/${meta.baseRef}:${prBaseRef(meta.number)}`,

package/src/github/threads.ts

@@ -33,7 +33,11 @@ export const THREADS_QUERY = `query($owner: String!, $name: String!, $number: In
  * The ids of every review comment that sits in a resolved thread. REST has no resolved flag,
  * so this one GraphQL query is joined to the REST comments by id.
  */
-export async function fetchResolvedCommentIds(gh: GitHubClient, repo: Repo, number: number): Promise<Set<number>> {
+export async function fetchResolvedCommentIds(
+  gh: GitHubClient,
+  repo: Repo,
+  number: number
+): Promise<Set<number>> {
   const resolved = new Set<number>()
   let after: string | null = null
   for (;;) {

package/src/project-config.ts

@@ -36,14 +36,16 @@ const capsShape = {
   diagram: cap(),
 } satisfies Record<keyof TextCaps, z.ZodOptional<z.ZodNumber>>
 
-export const PromptOverridesSchema = z.object({
-  'generation-format.md': z.string().min(1).optional(),
-  '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(),
-  'chat-seed.md': z.string().min(1).optional(),
-}).strict()
+export const PromptOverridesSchema = z
+  .object({
+    'generation-format.md': z.string().min(1).optional(),
+    'generation-strict.md': z.string().min(1).optional(),
+    'generation-surfacing.md': z.string().min(1).optional(),
+    'quality-standards.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>
 
 export const ProjectConfigSchema = z.object({
@@ -86,49 +88,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] },
@@ -159,7 +121,8 @@ export function mergeProjectConfig(raw: unknown): { config: ProjectConfig; warni
   const generation: ProjectConfig['generation'] = {
     mode: user.generation?.mode ?? DEFAULT_PROJECT_CONFIG.generation.mode,
     maxRepairRounds: user.generation?.maxRepairRounds ?? DEFAULT_PROJECT_CONFIG.generation.maxRepairRounds,
-    inlineDiffMaxLines: user.generation?.inlineDiffMaxLines ?? DEFAULT_PROJECT_CONFIG.generation.inlineDiffMaxLines,
+    inlineDiffMaxLines:
+      user.generation?.inlineDiffMaxLines ?? DEFAULT_PROJECT_CONFIG.generation.inlineDiffMaxLines,
     smallPrHunks: user.generation?.smallPrHunks ?? DEFAULT_PROJECT_CONFIG.generation.smallPrHunks,
   }
   if (user.generation?.caps !== undefined) {
@@ -167,7 +130,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 +143,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/prompt-files.ts

@@ -15,9 +15,10 @@ export async function loadPromptFile(
   project?: ProjectPrompts
 ): Promise<string> {
   const override = project?.overrides?.[name]
-  const file = project !== undefined && override !== undefined
-    ? path.resolve(project.repoRoot, override)
-    : path.join(dir, name)
+  const file =
+    project !== undefined && override !== undefined
+      ? path.resolve(project.repoRoot, override)
+      : path.join(dir, name)
   try {
     return await readFile(file, 'utf8')
   } catch (cause) {

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,17 +56,42 @@ 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) {
@@ -92,7 +117,10 @@ async function checkAcpx(deps: DoctorDeps): Promise<DoctorCheck> {
 }
 
 /** Runs core checks and, with allChecks, checks acpx for AI Chat. */
-export async function runDoctorChecks(deps: DoctorDeps, options: { allChecks?: boolean } = {}): Promise<DoctorReport> {
+export async function runDoctorChecks(
+  deps: DoctorDeps,
+  options: { allChecks?: boolean } = {}
+): Promise<DoctorReport> {
   let repoRoot: string | null = null
   let git: DoctorCheck
   try {
@@ -130,7 +158,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/normalize.ts

@@ -195,7 +195,9 @@ export function artifactToModelOutput(artifact: ReviewArtifact): ModelOutput {
     summary: artifact.summary,
     layers: artifact.layers.map(layer => {
       const { id: _id, risk, files, ...rest } = layer
-      const modelRisk = risk.filter(r => r.source === 'model').map(r => ({ label: r.label, reason: r.reason ?? '' }))
+      const modelRisk = risk
+        .filter(r => r.source === 'model')
+        .map(r => ({ label: r.label, reason: r.reason ?? '' }))
       const out: ModelLayer = { ...rest, files: files.map(({ isTest: _isTest, ...f }) => f) }
       if (modelRisk.length > 0) {
         out.risk = modelRisk

package/src/review/prepare.ts

@@ -37,7 +37,12 @@ async function resolvePr(ctx: AppContext, number: number, log: PrepareOptions['l
 }
 
 /** A change set before a PR exists: the refs must already be in the clone. */
-async function resolveRefs(ctx: AppContext, base: string, head: string, log: PrepareOptions['log']): Promise<Pr> {
+async function resolveRefs(
+  ctx: AppContext,
+  base: string,
+  head: string,
+  log: PrepareOptions['log']
+): Promise<Pr> {
   log('fetch-refs')
   const headSha = await ctx.git.revParse(head)
   const mergeBaseSha = await ctx.git.mergeBase(base, headSha)
@@ -93,7 +98,11 @@ async function clearCanvasDir(canvasDir: string): Promise<void> {
   }
 }
 
-export async function prepare(ctx: AppContext, target: PrepareTarget, opts: PrepareOptions): Promise<PrepareResult> {
+export async function prepare(
+  ctx: AppContext,
+  target: PrepareTarget,
+  opts: PrepareOptions
+): Promise<PrepareResult> {
   const pr =
     target.kind === 'pr'
       ? await resolvePr(ctx, target.number, opts.log)
@@ -116,7 +125,8 @@ export async function prepare(ctx: AppContext, target: PrepareTarget, opts: Prep
   const derived = await ctx.derived.ensure(pr.headSha, pr.mergeBaseSha)
   const additions = derived.files.reduce((n, f) => n + f.additions, 0)
   const deletions = derived.files.reduce((n, f) => n + f.deletions, 0)
-  const fullPr: Pr = target.kind === 'pr' ? pr : { ...pr, additions, deletions, changedFiles: derived.files.length }
+  const fullPr: Pr =
+    target.kind === 'pr' ? pr : { ...pr, additions, deletions, changedFiles: derived.files.length }
   const derivedDir = ctx.derived.derivedDir(pr.headSha)
   const config = ctx.projectConfig.config
 
@@ -152,14 +162,20 @@ export async function prepare(ctx: AppContext, target: PrepareTarget, opts: Prep
     largePr: isLargePr({ files: derived.files.length, additions, deletions }),
     preparedAt: ctx.now().toISOString(),
   }
-  const sources = opts.promptSources ?? (await loadPromptSources(undefined, {
-    repoRoot: ctx.config.repoRoot,
-    overrides: ctx.projectConfig.config.prompts,
-  }))
+  const sources =
+    opts.promptSources ??
+    (await loadPromptSources(undefined, {
+      repoRoot: ctx.config.repoRoot,
+      overrides: ctx.projectConfig.config.prompts,
+    }))
   await clearCanvasDir(canvasDir)
   await writeTextAtomic(promptPath, renderPrompt(context, derived.patches, sources))
   await writeJsonAtomic(contextPath, context)
   // The log keeps the whole history; publish counts attempts from this line on.
-  await appendFile(path.join(canvasDir, 'publish.log'), `${context.preparedAt} prepared ${pr.headSha}\n`, 'utf8')
+  await appendFile(
+    path.join(canvasDir, 'publish.log'),
+    `${context.preparedAt} prepared ${pr.headSha}\n`,
+    'utf8'
+  )
   return { ...result, status: 'prepared' }
 }

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,14 +64,16 @@ 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) => {
       const paths =
-        l.paths === undefined || l.paths.length === 0 ? '' : ` Path hints: ${l.paths.map(p => `\`${p}\``).join(', ')}.`
+        l.paths === undefined || l.paths.length === 0
+          ? ''
+          : ` Path hints: ${l.paths.map(p => `\`${p}\``).join(', ')}.`
       return `${i + 1}. \`${l.id}\` **${l.title}** — ${l.description}${paths}`
     })
     .join('\n')
@@ -164,7 +166,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.'
   )
@@ -196,7 +198,11 @@ export function schemaMarkdown(ctx: GenerationContext): string {
 }
 
 /** Selects one task and fills its data and format placeholders before the generator sees it. */
-export function renderPrompt(ctx: GenerationContext, patches: Record<string, string>, sources: PromptSources): string {
+export function renderPrompt(
+  ctx: GenerationContext,
+  patches: Record<string, string>,
+  sources: PromptSources
+): string {
   const tokens: Record<string, string> = {
     TARGET_WORD: ctx.target.kind === 'pr' ? 'pull request' : 'change set',
     META: metaMarkdown(ctx),
@@ -207,8 +213,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/publish.ts

@@ -75,7 +75,11 @@ async function readModel(canvasDir: string): Promise<{ raw: unknown } | { error:
   const file = path.join(canvasDir, 'model.json')
   const text = await readText(file)
   if (text === null) {
-    throw new PublishError('NOT_FOUND', `${file} does not exist`, 'write the model output there and publish again')
+    throw new PublishError(
+      'NOT_FOUND',
+      `${file} does not exist`,
+      'write the model output there and publish again'
+    )
   }
   return parseModelText(text, 'model.json')
 }
@@ -141,7 +145,11 @@ export async function validationInput(
   }
 }
 
-export function buildManifest(context: GenerationContext, artifact: ReviewArtifact, version: string): CanvasManifest {
+export function buildManifest(
+  context: GenerationContext,
+  artifact: ReviewArtifact,
+  version: string
+): CanvasManifest {
   const manifest: CanvasManifest = {
     formatVersion: 1,
     tool: { name: 'pr-review', version },
@@ -159,7 +167,11 @@ export function buildManifest(context: GenerationContext, artifact: ReviewArtifa
   return manifest
 }
 
-export async function publish(ctx: AppContext, canvasDir: string, opts: PublishOptions): Promise<PublishResult> {
+export async function publish(
+  ctx: AppContext,
+  canvasDir: string,
+  opts: PublishOptions
+): Promise<PublishResult> {
   const context = await readContext(canvasDir)
   if (!opts.allowStale) {
     const head = await currentHead(ctx, context)

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}`
+}