@vintasoftware/pr-review-canvas 0.4.0 → 0.5.0

package/src/review/carry-marks.ts

@@ -0,0 +1,131 @@
+// Review marks following an incremental canvas forward. Each canvas names the one it was generated
+// from, and that line of descent decides which of the reviewer's marks may follow — worked out here,
+// on the reviewer's own machine, from the two canvases and the two diffs it can read itself. The
+// published canvas is a pointer along that line and never a statement about what anyone reviewed.
+import { reviewedId } from '../contract/keys.js'
+import type { ReviewArtifact } from '../contract/review-artifact.js'
+import type { PrState } from '../contract/state.js'
+import type { AppContext } from '../server/context.js'
+import { fileDelta } from './incremental.js'
+
+function samePaths(a: readonly string[], b: readonly string[]): boolean {
+  const set = new Set(b)
+  return a.length === b.length && a.every(p => set.has(p))
+}
+
+/**
+ * The marks that still describe code the reviewer has seen. `marked` is the canvas they made the
+ * marks on. A file mark follows when that file is in both canvases under the same layer key and
+ * its patch is byte-identical; a layer mark follows only when the layer holds exactly the same
+ * files and none of them changed, since a layer mark claims the whole layer was read. Marks on
+ * anything else are left behind.
+ */
+export function carriedMarks(
+  marked: ReviewArtifact,
+  next: ReviewArtifact,
+  unchangedPaths: ReadonlySet<string>,
+  reviewed: Readonly<Record<string, true>>
+): Record<string, true> {
+  const carried: Record<string, true> = {}
+  for (const layer of next.layers) {
+    const before = marked.layers.find(l => l.key === layer.key)
+    if (before === undefined) {
+      continue
+    }
+    const paths = layer.files.map(f => f.path)
+    const beforePaths = before.files.map(f => f.path)
+    for (const path of paths) {
+      const id = reviewedId(layer.key, path)
+      if (unchangedPaths.has(path) && beforePaths.includes(path) && reviewed[id] === true) {
+        carried[id] = true
+      }
+    }
+    const id = reviewedId(layer.key)
+    if (reviewed[id] === true && samePaths(paths, beforePaths) && paths.every(p => unchangedPaths.has(p))) {
+      carried[id] = true
+    }
+  }
+  return carried
+}
+
+export interface MarksForCanvas {
+  /** The stored state as it applies to this canvas: only the marks that count for it. */
+  state: PrState
+  /** The canvas the marks were made on, when any of them followed. The page says so. */
+  carriedFrom?: string
+}
+
+/**
+ * Whether the line of descent that starts at `basisSha` reaches `ancestorSha`. The canvas on screen
+ * states its own basis, so the walk starts from the artifact's own pointer; the canvases further
+ * back are read from the index, which one read already holds, so following the line costs no extra
+ * canvas reads on the page's hot path.
+ *
+ * The line matters because the reviewer's marks only move to a canvas generated from the one they
+ * were made on. It has to be a line rather than a single step: the stored commit advances only when
+ * the reviewer marks something (`setReviewed` is its only writer), so a reviewer who opens a canvas,
+ * finds it already ticked, and clicks nothing leaves their marks keyed to a canvas two or more
+ * generations back.
+ */
+async function descendsFrom(
+  ctx: AppContext,
+  basisSha: string | undefined,
+  ancestorSha: string
+): Promise<boolean> {
+  const index = await ctx.canvases.readIndex()
+  const seen = new Set<string>()
+  let at = basisSha
+  while (at !== undefined && !seen.has(at)) {
+    if (at === ancestorSha) {
+      return true
+    }
+    seen.add(at)
+    at = index.canvases[at]?.basisCanvasSha
+  }
+  return false
+}
+
+/**
+ * The marks to show for one canvas. Marks made on it stand. Marks made on a canvas it descends
+ * from follow it for the parts of the diff those two canvases share, whatever the canvases in
+ * between did: a mark says the reviewer read one patch, so the patch they read and the patch on
+ * screen are compared directly, and a file the intervening canvases changed and changed back reads
+ * as untouched because it is. Anything else describes other code and counts for nothing, which is
+ * also what happens when this machine cannot read the older canvas or rebuild either diff.
+ */
+export async function marksForCanvas(
+  ctx: AppContext,
+  artifact: ReviewArtifact,
+  canvasSha: string,
+  stored: PrState
+): Promise<MarksForCanvas> {
+  if (stored.reviewedCanvasSha === canvasSha) {
+    return { state: stored }
+  }
+  const dropped: MarksForCanvas = { state: { ...stored, reviewed: {} } }
+  const markedOn = stored.reviewedCanvasSha
+  if (markedOn === undefined || !(await descendsFrom(ctx, artifact.basisCanvasSha, markedOn))) {
+    return dropped
+  }
+  const [markedArtifact, markedManifest, manifest] = await Promise.all([
+    ctx.canvases.readArtifact(markedOn),
+    ctx.canvases.readManifest(markedOn),
+    ctx.canvases.readManifest(canvasSha),
+  ])
+  if (markedArtifact === null || markedManifest === null || manifest === null) {
+    return dropped
+  }
+  const [markedDiff, diff] = await Promise.all([
+    ctx.derived.readOrBuild(markedOn, markedManifest.mergeBaseSha),
+    ctx.derived.readOrBuild(canvasSha, manifest.mergeBaseSha),
+  ])
+  if (markedDiff === null || diff === null) {
+    return dropped
+  }
+  const unchanged = new Set(fileDelta(markedDiff, diff).unchanged)
+  const reviewed = carriedMarks(markedArtifact, artifact, unchanged, stored.reviewed)
+  if (Object.keys(reviewed).length === 0) {
+    return dropped
+  }
+  return { state: { ...stored, reviewed, reviewedCanvasSha: canvasSha }, carriedFrom: markedOn }
+}

package/src/review/doctor.ts

@@ -37,7 +37,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
-  readSkill?: (file: string) => Promise<string | null>
+  readSkill?: ReadSkill
 }
 
 function message(err: unknown): string {
@@ -60,57 +60,91 @@ async function checkDataDir(dir: string): Promise<DoctorCheck> {
   }
 }
 
+export type ReadSkill = (file: string) => Promise<string | null>
+
+const readSkillFile: ReadSkill = file => readFile(file, 'utf8')
+
+/** One copy of the skill in the repository, next to how it compares with the bundled one. */
+export interface SkillCopy {
+  kind: 'claude' | 'codex'
+  /** The skills directory the copy sits in, absolute. */
+  dir: string
+  /** `<dir>/pr-review-canvas`, relative to the repository. */
+  path: string
+  /** True when the copy's body or recorded hash differs from the bundled skill, or it cannot be read. */
+  stale: boolean
+  /** Why the copy could not be read, when it could not. */
+  error?: string
+}
+
+/**
+ * The copies of the skill in `.claude/skills` and `.agents/skills`. A directory without one is
+ * left out. Throws when the bundled skill itself cannot be read.
+ */
+export async function findSkillCopies(
+  repoRoot: string,
+  readSkill: ReadSkill = readSkillFile
+): Promise<SkillCopy[]> {
+  const expected = skillContent(await readFile(path.join(SKILL_SOURCE_DIR, 'SKILL.md'), 'utf8')).hash
+  const copies: SkillCopy[] = []
+  for (const [kind, skillsDir] of [
+    ['claude', CLAUDE_SKILLS_DIR],
+    ['codex', CODEX_SKILLS_DIR],
+  ] as const) {
+    const dir = path.join(repoRoot, skillsDir)
+    const target = path.join(dir, SKILL_NAME)
+    const rel = path.relative(repoRoot, target)
+    try {
+      const text = await readSkill(path.join(target, 'SKILL.md'))
+      if (text === null) continue
+      const { hash, frontmatter } = skillContent(text)
+      const matches = hash === expected && frontmatter.getIn(['metadata', 'body-sha256']) === expected
+      copies.push({ kind, dir, path: rel, stale: !matches })
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+        copies.push({ kind, dir, path: rel, stale: true, error: message(err) })
+      }
+    }
+  }
+  return copies
+}
+
 /** The skill the generation flow needs, in either harness's directory. */
 export async function checkSkill(
   repoRoot: string | null,
-  readSkill: NonNullable<DoctorDeps['readSkill']> = file => readFile(file, 'utf8')
+  readSkill: ReadSkill = readSkillFile
 ): 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
+  let copies: SkillCopy[]
   try {
-    expected = skillContent(await readFile(path.join(SKILL_SOURCE_DIR, 'SKILL.md'), 'utf8')).hash
+    copies = await findSkillCopies(repoRoot, readSkill)
   } catch (err) {
     return { ok: false, detail: message(err), hint: 'reinstall the pr-review package' }
   }
-  for (const target of targets) {
-    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)}`)
-      }
-    }
-  }
+  const stale = copies.flatMap(copy =>
+    copy.stale ? [copy.error === undefined ? copy.path : `${copy.path}: ${copy.error}`] : []
+  )
   if (stale.length > 0) {
     return {
       ok: false,
       detail: `outdated or modified skill: ${stale.join(', ')}`,
-      hint: 'run `pr-review install-skill`',
+      hint: 'run `pr-review upgrade` or `pr-review install-skill`',
     }
   }
-  if (found.length === 0) {
+  if (copies.length === 0) {
     return {
       ok: false,
       detail: `${SKILL_NAME} is in neither ${CLAUDE_SKILLS_DIR} nor ${CODEX_SKILLS_DIR}`,
       hint: 'run `pr-review install-skill`',
     }
   }
-  return { ok: true, detail: found.join(', ') }
+  return { ok: true, detail: copies.map(copy => copy.path).join(', ') }
 }
 
 async function checkAcpx(deps: DoctorDeps): Promise<DoctorCheck> {
-  const hint = 'install with `npm install -g acpx` and check `acpx --version`'
+  const hint = 'install with `npm install -g acpx@latest` and check `acpx --version`'
   try {
     const version = (await deps.acpxVersion())?.trim()
     return version

package/src/review/incremental.ts

@@ -0,0 +1,107 @@
+// Incremental generation: the basis canvas an update starts from, the per-file delta between that
+// canvas's diff and the head's, and the split of the basis into content the head leaves untouched
+// and content the generator has to decide anew. Everything here is a function of two diffs and one
+// stored canvas, so `prepare` states the split instead of asking the generator to work it out.
+import type {
+  BasisSplit,
+  BasisSplitLayer,
+  BasisSplitPoint,
+  FileDelta,
+} from '../contract/generation-context.js'
+import type { ReviewArtifact } from '../contract/review-artifact.js'
+import type { Git } from '../git/git.js'
+import type { CanvasStore } from '../store/canvas-store.js'
+import type { Derived } from '../store/derived-store.js'
+
+/**
+ * Which files the head changes relative to the basis canvas's diff. A file is unchanged only when
+ * its whole patch is byte-identical: line numbers, context, and all. Anything less would let a
+ * fold or an annotation of the basis land on a line it was never written for. Renames arrive as a
+ * removal and an addition, since a file's key follows its path.
+ *
+ * The two sides are matched by path, and each side's patch is read through its own key. A key is
+ * the sanitized path, and two paths can sanitize to the same key (`a-b.ts` and `a_b.ts`), which
+ * `uniqueKey` then separates by the order the files appear in that one diff. The same key can
+ * therefore name different files in two diffs; the path cannot.
+ */
+export function fileDelta(basis: Derived, head: Derived): FileDelta {
+  const keysByPath = (d: Derived): Map<string, string> => new Map(d.files.map(f => [f.path, f.key]))
+  const basisKeys = keysByPath(basis)
+  const headKeys = keysByPath(head)
+  const delta: FileDelta = { unchanged: [], changed: [], added: [], removed: [] }
+  for (const [path, headKey] of headKeys) {
+    const basisKey = basisKeys.get(path)
+    if (basisKey === undefined) {
+      delta.added.push(path)
+    } else if (basis.patches[basisKey] === head.patches[headKey]) {
+      delta.unchanged.push(path)
+    } else {
+      delta.changed.push(path)
+    }
+  }
+  for (const path of basisKeys.keys()) {
+    if (!headKeys.has(path)) {
+      delta.removed.push(path)
+    }
+  }
+  for (const list of Object.values(delta)) {
+    list.sort()
+  }
+  return delta
+}
+
+/**
+ * The basis canvas divided in two. A layer is carried whole when the head touches none of its
+ * files; otherwise the layer is re-judged, and only the files the head leaves alone keep their
+ * note, folds, and annotations. A point is carried when the file it sits in is untouched, which
+ * keeps its title and so its fingerprint, and with it any dismissal the reviewer made.
+ */
+export function splitBasis(
+  artifact: ReviewArtifact,
+  delta: FileDelta
+): Omit<BasisSplit, 'canvasSha' | 'reviewJsonPath' | 'files'> {
+  const unchanged = new Set(delta.unchanged)
+  const layers: BasisSplitLayer[] = artifact.layers.map(layer => {
+    const carriedFiles = layer.files.filter(f => unchanged.has(f.path)).map(f => f.path)
+    const reJudgedFiles = layer.files.filter(f => !unchanged.has(f.path)).map(f => f.path)
+    return {
+      key: layer.key,
+      title: layer.title,
+      status: reJudgedFiles.length === 0 ? 'carried' : 're-judged',
+      carriedFiles,
+      reJudgedFiles,
+    }
+  })
+  const points: BasisSplitPoint[] = artifact.points.map(point => ({
+    kind: point.kind,
+    path: point.path,
+    title: point.title,
+    status: unchanged.has(point.path) ? 'carried' : 're-judged',
+  }))
+  return { layers, points }
+}
+
+/**
+ * The canvas an incremental run builds on: the newest one generated for a commit this head was
+ * built on. A canvas of a line of work the head no longer contains describes code that was
+ * abandoned, so it is never a basis, however recent it is.
+ */
+export async function findBasisCanvas(
+  canvases: CanvasStore,
+  git: Git,
+  prNumber: number | undefined,
+  headSha: string
+): Promise<string | null> {
+  const index = await canvases.readIndex()
+  const candidates = Object.entries(index.canvases)
+    .filter(
+      ([sha, entry]) => sha !== headSha && (entry.prNumber === undefined || entry.prNumber === prNumber)
+    )
+    .sort(([, a], [, b]) => (a.generatedAt < b.generatedAt ? 1 : a.generatedAt > b.generatedAt ? -1 : 0))
+  for (const [sha] of candidates) {
+    if (await git.isAncestor(sha, headSha)) {
+      return sha
+    }
+  }
+  return null
+}

package/src/review/normalize.ts

@@ -29,6 +29,8 @@ export interface NormalizeInput {
   caps: TextCaps
   generatedAt: string
   generator: Generator
+  /** The canvas this one was generated from, when the run was incremental. */
+  basisCanvasSha?: string | undefined
   /** The globs that make a file a test; the project config's list, or the built-in one. */
   testPatterns?: readonly string[] | undefined
 }
@@ -76,16 +78,20 @@ function unionRisk(layers: readonly Layer[]): RiskTag[] {
   return out
 }
 
+/**
+ * A layer's id is its own key, which the validator has already checked is unique here. A reviewed
+ * mark is keyed by it, so a regenerated canvas that reorders or renames its layers keeps the
+ * reviewer's progress pointing at the same concern; a position could not.
+ */
 function toLayer(
   layer: ModelLayer,
-  index: number,
   highRisk: readonly HighRiskRule[],
   testPatterns: readonly string[]
 ): Layer {
   const { risk: _modelRisk, files, ...rest } = layer
   return {
     ...rest,
-    id: `layer-${index + 1}`,
+    id: layer.key,
     risk: layerRisk(layer, highRisk),
     files: files.map(f => ({ ...f, isTest: isTestPath(f.path, testPatterns) })),
   }
@@ -167,12 +173,12 @@ function sortPoints(points: Unassigned[]): Point[] {
 
 export function normalize(output: ModelOutput, input: NormalizeInput): ReviewArtifact {
   const testPatterns = input.testPatterns ?? DEFAULT_TEST_PATTERNS
-  const layers = output.layers.map((l, i) => toLayer(l, i, input.highRisk, testPatterns))
+  const layers = output.layers.map(l => toLayer(l, input.highRisk, testPatterns))
   const points = [
     ...output.points.map(p => modelPoint(p, layers, input.files)),
     ...layers.flatMap(l => testPoints(l, input.files, input.caps.pointTitle)),
   ]
-  return {
+  const artifact: ReviewArtifact = {
     version: 1,
     pr: input.pr,
     files: [...input.files],
@@ -184,6 +190,10 @@ export function normalize(output: ModelOutput, input: NormalizeInput): ReviewArt
     generator: input.generator,
     source: 'local',
   }
+  if (input.basisCanvasSha !== undefined) {
+    artifact.basisCanvasSha = input.basisCanvasSha
+  }
+  return artifact
 }
 
 /**

package/src/review/prepare.ts

@@ -3,6 +3,7 @@
 import { appendFile, readdir, rm } from 'node:fs/promises'
 import path from 'node:path'
 import {
+  type BasisSplit,
   type GenerationContext,
   isLargePr,
   type PrepareTarget,
@@ -16,6 +17,8 @@ import { fetchPrRefs } from '../git/pr-refs.js'
 import { toPr } from '../host/pr.js'
 import type { AppContext } from '../server/context.js'
 import { readText, writeJsonAtomic, writeTextAtomic } from '../store/atomic-json.js'
+import type { Derived } from '../store/derived-store.js'
+import { fileDelta, findBasisCanvas, splitBasis } from './incremental.js'
 import { loadPromptSources, type PromptSources, renderPrompt } from './prompt.js'
 
 export interface PrepareOptions {
@@ -131,6 +134,45 @@ async function clearCanvasDir(canvasDir: string): Promise<void> {
   }
 }
 
+/**
+ * The basis canvas of this run, split into what carries and what is re-judged, or null when the
+ * canvas is generated from a blank page: `--force`, `canvas.incremental: false`, no canvas of an
+ * ancestor commit, or a basis whose canvas or diff this machine can no longer read.
+ *
+ * Only a pull request's canvases are owned by a number; a refs or local run considers the canvases
+ * that carry no number, the same ownership rule the store's own lookup uses.
+ */
+async function resolveBasis(
+  ctx: AppContext,
+  target: PrepareTarget,
+  pr: Pr,
+  head: Derived
+): Promise<BasisSplit | null> {
+  const prNumber = target.kind === 'pr' ? target.number : undefined
+  const sha = await findBasisCanvas(ctx.canvases, ctx.git, prNumber, pr.headSha)
+  if (sha === null) {
+    return null
+  }
+  const [artifact, manifest] = await Promise.all([
+    ctx.canvases.readArtifact(sha),
+    ctx.canvases.readManifest(sha),
+  ])
+  if (artifact === null || manifest === null) {
+    return null
+  }
+  const basis = await ctx.derived.readOrBuild(sha, manifest.mergeBaseSha)
+  if (basis === null) {
+    return null
+  }
+  const files = fileDelta(basis, head)
+  return {
+    canvasSha: sha,
+    reviewJsonPath: path.join(ctx.canvases.canvasDir(sha), 'review.json'),
+    files,
+    ...splitBasis(artifact, files),
+  }
+}
+
 /** The target with its base resolved, which is the form `context.json` records. */
 async function resolveTarget(ctx: AppContext, input: PrepareTargetInput): Promise<PrepareTarget> {
   if (input.kind !== 'local') {
@@ -216,6 +258,11 @@ export async function prepare(
     largePr: isLargePr({ files: derived.files.length, additions, deletions }),
     preparedAt: ctx.now().toISOString(),
   }
+  // `--force` means start over, so it never reads a basis, whatever the project config says.
+  const basis = opts.force || !config.canvas.incremental ? null : await resolveBasis(ctx, target, pr, derived)
+  if (basis !== null) {
+    context.basis = basis
+  }
   const sources =
     opts.promptSources ??
     (await loadPromptSources(undefined, {

package/src/review/prompt.ts

@@ -1,7 +1,7 @@
 // Renders prompt.md from the selected generation template and the prepared context. The template carries
 // the prose; this module fills the `{{TOKENS}}` with data so a wording change never touches code.
 import { z } from 'zod'
-import { type GenerationContext, LARGE_PR } from '../contract/generation-context.js'
+import { type BasisSplit, type GenerationContext, LARGE_PR } from '../contract/generation-context.js'
 import { type FileEntry, modelOutputSchema } from '../contract/review-artifact.js'
 import { labelPatch } from '../git/patch-lines.js'
 import { loadPromptFile, type ProjectPrompts } from '../prompt-files.js'
@@ -12,20 +12,48 @@ export { PROMPTS_DIR }
 
 export interface PromptSources {
   generation: Record<GenerationMode, string>
+  /** The same two modes, worded as an update of a basis canvas. Used when `ctx.basis` is set. */
+  incremental: Record<GenerationMode, string>
+  /**
+   * The judging rules of each mode: the half of the task that does not change between writing a
+   * canvas and updating one. Both task files of a mode end with it, so its wording has one home.
+   */
+  judging: Record<GenerationMode, string>
   format: string
   layeringGuidance: string
   qualityStandards: string
 }
 
 export async function loadPromptSources(dir = PROMPTS_DIR, project?: ProjectPrompts): Promise<PromptSources> {
-  const [format, layeringGuidance, qualityStandards, strict, surfacing] = await Promise.all([
+  const [
+    format,
+    layeringGuidance,
+    qualityStandards,
+    strict,
+    surfacing,
+    strictInc,
+    surfacingInc,
+    judgingStrict,
+    judgingSurfacing,
+  ] = await Promise.all([
     loadPromptFile('generation-format.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),
+    loadPromptFile('generation-strict-incremental.md', dir, project),
+    loadPromptFile('generation-surfacing-incremental.md', dir, project),
+    loadPromptFile('judging-strict.md', dir, project),
+    loadPromptFile('judging-surfacing.md', dir, project),
   ])
-  return { format, layeringGuidance, qualityStandards, generation: { strict, surfacing } }
+  return {
+    format,
+    layeringGuidance,
+    qualityStandards,
+    generation: { strict, surfacing },
+    incremental: { strict: strictInc, surfacing: surfacingInc },
+    judging: { strict: judgingStrict, surfacing: judgingSurfacing },
+  }
 }
 
 /** The line ranges of a hunk header; the trailing function context can hold backticks. */
@@ -197,6 +225,74 @@ export function schemaMarkdown(ctx: GenerationContext): string {
   return `\`\`\`json\n${JSON.stringify(schema, null, 2)}\n\`\`\``
 }
 
+function list(items: readonly string[], empty: string): string {
+  return items.length === 0 ? `_${empty}_` : items.map(i => `- \`${i}\``).join('\n')
+}
+
+function basisMarkdown(basis: BasisSplit | undefined): string {
+  if (basis === undefined) {
+    return ''
+  }
+  return [
+    `- Basis canvas: \`${basis.canvasSha}\``,
+    `- Its canvas file: \`${basis.reviewJsonPath}\` — read it for the wording you carry`,
+  ].join('\n')
+}
+
+function fileDeltaMarkdown(basis: BasisSplit | undefined): string {
+  if (basis === undefined) {
+    return ''
+  }
+  const f = basis.files
+  return [
+    `**Untouched** — the patch is byte-identical to the basis canvas's:\n\n${list(f.unchanged, 'none')}`,
+    `**Changed** — the patch differs, so every line number in it may have moved:\n\n${list(f.changed, 'none')}`,
+    `**New** — not in the basis canvas at all:\n\n${list(f.added, 'none')}`,
+    `**Gone** — in the basis canvas, not in this diff:\n\n${list(f.removed, 'none')}`,
+  ].join('\n\n')
+}
+
+/** The two lists the generator works from: what to copy across, and what to decide anew. */
+function carriedMarkdown(basis: BasisSplit | undefined): string {
+  if (basis === undefined) {
+    return ''
+  }
+  const layers = basis.layers
+    .filter(l => l.status === 'carried')
+    .map(l => `- layer \`${l.key}\` — **${l.title}** (${l.carriedFiles.length} files, all untouched)`)
+  const files = basis.layers
+    .filter(l => l.status === 're-judged')
+    .flatMap(l => l.carriedFiles.map(p => `- \`${p}\`, from layer \`${l.key}\``))
+  const points = basis.points
+    .filter(p => p.status === 'carried')
+    .map(p => `- ${p.kind} on \`${p.path}\` — "${p.title}"`)
+  return [
+    `**Whole layers** — copy the layer with its title, rationale, decisions, checkByHand, tests, files, notes, folds, and annotations:\n\n${layers.length === 0 ? '_none_' : layers.join('\n')}`,
+    `**Single files of a re-judged layer** — the file is untouched, so its note, folds, and annotations still fit wherever you put the file:\n\n${files.length === 0 ? '_none_' : files.join('\n')}`,
+    `**Attention points** — repeat the kind, path, and title exactly, so the point keeps its identity and any dismissal the reviewer made:\n\n${points.length === 0 ? '_none_' : points.join('\n')}`,
+  ].join('\n\n')
+}
+
+function reJudgedMarkdown(basis: BasisSplit | undefined): string {
+  if (basis === undefined) {
+    return ''
+  }
+  const layers = basis.layers
+    .filter(l => l.status === 're-judged')
+    .map(
+      l =>
+        `- layer \`${l.key}\` — **${l.title}**; touched: ${l.reJudgedFiles.map(p => `\`${p}\``).join(', ')}`
+    )
+  const points = basis.points
+    .filter(p => p.status === 're-judged')
+    .map(p => `- ${p.kind} on \`${p.path}\` — "${p.title}"`)
+  return [
+    `**Layers** — the head touched at least one of their files, so decide the grouping, the prose, and the anchors again:\n\n${layers.length === 0 ? '_none_' : layers.join('\n')}`,
+    `**Attention points** — the code under them moved; keep one only if you read the new code and it still holds:\n\n${points.length === 0 ? '_none_' : points.join('\n')}`,
+    '**The summary and the pull-request-wide risk** are always written again: they describe the whole change set, which the new commits changed.',
+  ].join('\n\n')
+}
+
 /** Selects one task and fills its data and format placeholders before the generator sees it. */
 export function renderPrompt(
   ctx: GenerationContext,
@@ -227,12 +323,23 @@ export function renderPrompt(
     TEST_PATTERNS: testPatternsMarkdown(ctx),
     SMALL_PR: smallPrMarkdown(ctx),
     MAX_REPAIR_ROUNDS: String(ctx.generation.maxRepairRounds),
+    BASIS: basisMarkdown(ctx.basis),
+    FILE_DELTA: fileDeltaMarkdown(ctx.basis),
+    CARRIED: carriedMarkdown(ctx.basis),
+    RE_JUDGED: reJudgedMarkdown(ctx.basis),
   }
-  const template = sources.generation[ctx.generation.mode].replace('{{FORMAT}}', () => sources.format)
+  // A prepared basis picks the incremental wording: one prompt states one job, with no conditions.
+  // Both wordings end with the mode's judging rules, which are assembled first so the tokens inside
+  // them are filled by the one pass below.
+  const task = ctx.basis === undefined ? sources.generation : sources.incremental
+  const template = task[ctx.generation.mode]
+    .replace('{{JUDGING}}', () => sources.judging[ctx.generation.mode])
+    .replace('{{FORMAT}}', () => sources.format)
   return template.replace(/\{\{([A-Z_]+)\}\}/g, (_m, name: string) => {
     const value = tokens[name]
     if (value === undefined) {
-      throw new Error(`generation-${ctx.generation.mode}.md uses an unknown token {{${name}}}`)
+      const suffix = ctx.basis === undefined ? '' : '-incremental'
+      throw new Error(`generation-${ctx.generation.mode}${suffix}.md uses an unknown token {{${name}}}`)
     }
     return value
   })

package/src/review/publish.ts

@@ -232,6 +232,7 @@ export async function publish(
     generatedAt: now,
     generator,
     testPatterns: context.tests.patterns,
+    basisCanvasSha: context.basis?.canvasSha,
   })
   const manifest = buildManifest(context, artifact, ctx.version)
   // A snapshot commit is on no branch, so it must never be offered as a pull request's canvas.