@erclx/canon 5.39.0 → 5.40.0

package/src/design/document.ts

@@ -95,7 +95,7 @@ function borderRows(tokens: readonly BorderToken[]): string[][] {
  */
 const LEAD = [
   'Authoring guidance: `claude/skills/canvas-board/references/design.md`. Rendered from `src/design/tokens.ts` by `canon design regen`, so edit the module and never this file.',
-  'Why each value was chosen lives in `canon/context/design.md`.',
+  'Why each value was chosen lives in `canon/context/features/design.md`.',
 ].join(' ')
 
 function bullets(rules: readonly string[]): string {

package/src/design/tokens.ts

@@ -59,7 +59,7 @@ export interface BorderToken {
 /**
  * Every prose slot is a list of one-line rules rather than a string, so a
  * bullet is the unit the renderer emits and the prose budget counts, and a
- * value needing a paragraph of why goes to `canon/context/design.md`.
+ * value needing a paragraph of why goes to `canon/context/features/design.md`.
  */
 export interface DesignTokens {
   readonly personality: string

package/src/gate/boundaries.ts

@@ -211,7 +211,7 @@ function collectCommands(value: unknown, into: string[] = []): string[] {
 /**
  * A hook, a workflow, or a husky script reaching one side of the seed or config
  * boundary and not the other is a capability withheld with no recorded reason,
- * per the criterion in `canon/context/tooling/seeds.md`.
+ * per the criterion in `canon/context/surfaces/tooling.md`.
  *
  * Presence on either side clears a name, and a `canon-no-seed:` comment in the
  * file is the recorded reason. The same marker on a destination clears a
@@ -434,6 +434,9 @@ function grepLines(
  * seed itself installs, so every other spelling reports. No seed root, or roots
  * carrying no markdown, is unmeasured rather than a pass, which agrees with
  * `seedStandards` on the no-root case.
+ *
+ * The token matches as a substring, so `canonical` reports as `canon` does. The
+ * walk covers the seed roots alone, so a shipped rule citing the CLI passes.
  */
 export const seedIndependence: Measure = async (ctx) => {
   if (!isDirectory(join(ctx.root, 'tooling'))) {

package/src/gate/measures.ts

@@ -1401,7 +1401,7 @@ export const pluginManifests: Measure = async (ctx) => {
     return {
       emissions: [],
       unmeasured:
-        'claude is on PATH and claude --version fails, so the install brought down no platform-native binary and no manifest was read. Raise or lower the pinned version at the Install Plugin CLI step in .github/workflows/verify.yml, and record the move in canon/context/ci/checks.md.',
+        'claude is on PATH and claude --version fails, so the install brought down no platform-native binary and no manifest was read. Raise or lower the pinned version at the Install Plugin CLI step in .github/workflows/verify.yml, then test the raised pin as `canon/context/development/ci.md` states.',
     }
   }
 

package/src/gate/stages.ts

@@ -92,12 +92,12 @@ export interface Stage {
 }
 
 /**
- * Corpora a `src/` test asserts over from outside `src/`, censused in
- * `canon/context/development/tests.md`. This list and that census are
- * two copies of one set with nothing comparing them, so a corpus joining the
- * census joins this list in the same change. The first four are directory
- * prefixes because their tests walk the tree whole, which is what reaches a
- * rule or a skill a branch adds rather than edits.
+ * Corpora a `src/` test asserts over from outside `src/`. Nothing compares
+ * this list to the tests reading those paths, so a test that starts reading a
+ * new corpus joins it here in the same change, or a branch touching only that
+ * corpus skips the Tests stage. The first four are directory prefixes because
+ * their tests walk the tree whole, which is what reaches a rule or a skill a
+ * branch adds rather than edits.
  */
 export const TEST_CORPORA_PATTERNS = [
   '^claude/skills/',
@@ -302,7 +302,7 @@ export const STAGES: readonly Stage[] = [
   {
     // A hook, a workflow, or a husky script reaching one side of the seed or
     // config boundary and not the other is a capability withheld with no
-    // recorded reason, per the criterion in canon/context/tooling/seeds.md.
+    // recorded reason, per the criterion in canon/context/surfaces/tooling.md.
     id: 'capability-seeding',
     label: 'Capability seeding',
     checks: [{ kind: 'measure', measure: capabilitySeeding }],

package/src/git/env.ts

@@ -26,6 +26,12 @@ const RESOLUTION_VARS = [
  * Read per call rather than captured at module load. A long-lived process can
  * have these set after import, and a snapshot would then hand git the very
  * variables this exists to strip.
+ *
+ * Hooks export `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, and `GIT_PREFIX`,
+ * which beat `-C`. Under pre-push an inherited `GIT_DIR` made a `-C src` read
+ * resolve against the whole repository, and in a fixture it let a config write
+ * overwrite the real repository's committer identity, so route every shelled
+ * call through this, fixtures included.
  */
 export function gitEnv(): Record<string, string> {
   return Object.fromEntries(

package/src/markdown/scope.ts

@@ -35,16 +35,11 @@ const DENSITY_SCOPE = [
  * corpus, which is why the audit reads it only inside a canon checkout.
  */
 export const GATED_PATHS: readonly string[] = [
-  'canon/context/claude-plugin/',
-  'canon/context/claude-internal/',
+  'canon/context/surfaces/',
+  'canon/context/workflow/',
+  'canon/context/development/',
   'canon/context/features/',
-  'canon/context/cli/',
-  'canon/context/sandbox/',
-  'canon/context/governance/',
-  'canon/context/tooling/',
-  'canon/context/web.md',
   'canon/context/context-model.md',
-  'canon/context/design.md',
   'canon/context/index.md',
   'claude/skills/api-design/SKILL.md',
   'claude/skills/auto-ship/SKILL.md',
@@ -76,6 +71,7 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/draft-screencast/SKILL.md',
   'claude/skills/draft-screencast/references/beats-template.md',
   'claude/skills/draft-slides/SKILL.md',
+  'claude/skills/draft-slides/references/deck.md',
   'claude/skills/git-branch/SKILL.md',
   'claude/skills/git-commit/SKILL.md',
   'claude/skills/git-followup/SKILL.md',
@@ -130,16 +126,8 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/video-craft/SKILL.md',
   'claude/skills/write-human/SKILL.md',
   'claude/skills/youtube-transcripts/SKILL.md',
-  'docs/agents/indexes.md',
-  'docs/agents/install-and-sync.md',
-  'docs/agents/migrate.md',
-  'docs/agents/output-shape.md',
-  'docs/agents/overview.md',
-  'docs/agents/targets.md',
-  'canon/context/development/',
-  'canon/context/ci/',
-  'canon/context/scripts/',
   '.claude/skills/internal-',
+  'docs/',
 ]
 
 /**

package/src/pr/lift.ts

@@ -5,6 +5,7 @@ import {
   resolveReviewScope,
   resolveUiScope,
 } from '@/pr/review-scope'
+import { DEFAULT_PAINTED, isPainted, type PaintedPatterns } from '@/pr/painted'
 
 /** How long `--wait` holds for a pending CI run, in seconds, when none is named. */
 export const DEFAULT_WAIT_SECONDS = 1200
@@ -42,6 +43,17 @@ export interface GateResult {
   readonly isOk: boolean
   /** Absent when the gate passed. */
   readonly reason?: LiftRefusal
+  /** The commit a UI close was carried forward from, when it covered an earlier head. */
+  readonly carriedFrom?: string
+  /** The painted paths that kept a UI close from carrying forward. */
+  readonly paintedPaths?: readonly string[]
+}
+
+/** How an earlier commit sits against the head, and what changed since. */
+export interface ChangedRead {
+  /** False when the commit is rewritten away or does not resolve. */
+  readonly isAncestor: boolean
+  readonly paths: readonly string[]
 }
 
 /** How the head sits against the base the pull request targets. */
@@ -85,6 +97,10 @@ export interface LiftApi {
   readChecks(tip: string): Promise<ChecksGate | undefined>
   /** The one GraphQL call the verb makes. */
   markReady(nodeId: string): Promise<boolean>
+  /** The paths changed from an earlier commit to the head, undefined when the read failed. */
+  readChanged(from: string, to: string): Promise<ChangedRead | undefined>
+  /** The one GraphQL call that returns a ready pull request to draft. */
+  markDraft(nodeId: string): Promise<boolean>
   sleep(ms: number): Promise<void>
   now(): number
 }
@@ -93,10 +109,20 @@ export interface LiftOptions {
   readonly isCheck: boolean
   readonly waitSeconds: number
   readonly pollMs?: number
+  readonly painted?: PaintedPatterns
 }
 
 export interface LiftRecord {
-  readonly reason: 'lifted' | 'already-ready' | 'clear' | LiftRefusal
+  readonly reason:
+    | 'lifted'
+    | 'already-ready'
+    | 'redrafted'
+    | 'clear'
+    | LiftRefusal
+  /** The gate that read not clear when a ready pull request went back to draft. */
+  readonly failed?: LiftRefusal
+  readonly carriedFrom?: string
+  readonly paintedPaths?: readonly string[]
   readonly isLifted: boolean
   /** Whether the caller can treat the pull request as ready afterwards. */
   readonly isOk: boolean
@@ -129,22 +155,51 @@ function reviewGate(reviews: readonly ReviewRow[], head: string): GateResult {
   return pass('review')
 }
 
-/** Binds only where the evidence record carries a checklist to drive. */
-function uiGate(
+/** What the UI gate says about a close carried across commits, for a record. */
+function carried(gates: readonly GateResult[]): {
+  carriedFrom?: string
+  paintedPaths?: readonly string[]
+} {
+  const ui = gates.find((gate) => gate.gate === 'ui')
+  return {
+    ...(ui?.carriedFrom !== undefined && { carriedFrom: ui.carriedFrom }),
+    ...(ui?.paintedPaths !== undefined && { paintedPaths: ui.paintedPaths }),
+  }
+}
+
+/**
+ * Binds only where the evidence record carries a checklist to drive.
+ *
+ * A close behind the head still holds when it is an ancestor of the head and
+ * no painted path changed since, since a push that paints nothing leaves the
+ * checklist the reviewer drove as true as it was. A close that is not an
+ * ancestor, which a force-push or a rebase leaves, never carries.
+ */
+async function uiGate(
+  api: LiftApi,
+  painted: PaintedPatterns,
   reviews: readonly ReviewRow[],
   head: string,
   hasChecklist: boolean,
-): GateResult {
+): Promise<GateResult> {
   if (!hasChecklist) return pass('ui')
 
   const scope = resolveUiScope({ reviews })
   if (scope.state === 'none') return fail('ui', 'ui-missing')
   if (scope.state === 'open') return fail('ui', 'ui-open')
   if (scope.source !== 'marker') return fail('ui', 'ui-unmarked')
-  if (scope.commit === undefined || !coversHead(scope.commit, head)) {
-    return fail('ui', 'ui-behind')
+  if (scope.commit === undefined) return fail('ui', 'ui-behind')
+  if (coversHead(scope.commit, head)) return pass('ui')
+
+  const changed = await api.readChanged(scope.commit, head)
+  if (changed === undefined) return fail('ui', 'gh-failed')
+  if (!changed.isAncestor) return fail('ui', 'ui-behind')
+
+  const paintedPaths = changed.paths.filter((path) => isPainted(path, painted))
+  if (paintedPaths.length > 0) {
+    return { ...fail('ui', 'ui-behind'), paintedPaths }
   }
-  return pass('ui')
+  return { ...pass('ui'), carriedFrom: scope.commit }
 }
 
 function standingGate(standing: Standing): GateResult {
@@ -207,6 +262,56 @@ function refused(
     ...(head !== undefined && { head }),
     gates,
     waitedSeconds,
+    ...carried(gates),
+  }
+}
+
+/** The gates whose failure sends a ready pull request back to draft. */
+const REDRAFT_GATES: readonly GateName[] = ['review', 'ui', 'evidence']
+
+/**
+ * Reads a ready pull request against the gates a person's ready mark vouched
+ * for. A failing review, UI, or evidence gate returns it to draft, since the
+ * mark no longer holds. Standing and CI are reported and never written on, as
+ * either would flap a merge-ready pull request on a run still going.
+ */
+async function settleReady(
+  api: LiftApi,
+  opts: LiftOptions,
+  pull: PullState,
+  tip: string,
+  gates: readonly GateResult[],
+): Promise<LiftRecord> {
+  const blocked = gates.find(
+    (gate) => REDRAFT_GATES.includes(gate.gate) && !gate.isOk,
+  )
+  if (blocked?.reason === undefined) {
+    return {
+      reason: 'already-ready',
+      isLifted: false,
+      isOk: true,
+      head: tip,
+      gates,
+      waitedSeconds: 0,
+      ...carried(gates),
+    }
+  }
+  if (opts.isCheck || blocked.reason === 'gh-failed') {
+    return refused(blocked.reason, gates, tip)
+  }
+
+  const isDrafted = await api.markDraft(pull.nodeId)
+  if (!isDrafted) return refused('gh-failed', gates, tip)
+
+  return {
+    reason: 'redrafted',
+    failed: blocked.reason,
+    isLifted: false,
+    isOk: false,
+    head: tip,
+    gates,
+    waitedSeconds: 0,
+    ...carried(gates),
   }
 }
 
@@ -224,20 +329,11 @@ export async function lift(
   opts: LiftOptions,
 ): Promise<LiftRecord> {
   const pollMs = opts.pollMs ?? CHECKS_POLL_MS
+  const painted = opts.painted ?? DEFAULT_PAINTED
 
   const pull = await api.readPull()
   if (pull === undefined) return refused('gh-failed', [], undefined)
   if (!pull.isOpen) return refused('pull-closed', [], pull.head)
-  if (!pull.isDraft) {
-    return {
-      reason: 'already-ready',
-      isLifted: false,
-      isOk: true,
-      head: pull.head,
-      gates: [],
-      waitedSeconds: 0,
-    }
-  }
 
   // The tip, not the object's head, since the object lags the ref by up to a
   // minute after a push and a review marker names the commit it read.
@@ -255,10 +351,12 @@ export async function lift(
 
   const gates: GateResult[] = [
     reviewGate(reviews, tip),
-    uiGate(reviews, tip, evidence.hasChecklist),
+    await uiGate(api, painted, reviews, tip, evidence.hasChecklist),
     evidence.isSettled ? pass('evidence') : fail('evidence', 'evidence-owed'),
     standingGate(standing),
   ]
+  if (!pull.isDraft) return settleReady(api, opts, pull, tip, gates)
+
   const blocked = gates.find((gate) => !gate.isOk)
 
   if (opts.isCheck) {
@@ -284,6 +382,7 @@ export async function lift(
       head: tip,
       gates: all,
       waitedSeconds: 0,
+      ...carried(all),
     }
   }
 
@@ -316,13 +415,14 @@ export async function lift(
       head: nowTip,
       gates: cleared,
       waitedSeconds: ci.waited,
+      ...carried(cleared),
     }
   }
   if (nowTip !== tip) return refused('head-moved', cleared, nowTip, ci.waited)
 
   const reread = [
     reviewGate(nowReviews, nowTip),
-    uiGate(nowReviews, nowTip, evidence.hasChecklist),
+    await uiGate(api, painted, nowReviews, nowTip, evidence.hasChecklist),
   ].find((gate) => !gate.isOk)
   if (reread?.reason !== undefined) {
     return refused(reread.reason, cleared, nowTip, ci.waited)
@@ -345,6 +445,7 @@ export async function lift(
     head: nowTip,
     gates: cleared,
     waitedSeconds: ci.waited,
+    ...carried(cleared),
   }
 }
 
@@ -416,3 +517,36 @@ export async function readBaseStanding(
 
   return nonEmptyLines(moved).length > 0 ? 'stale' : 'fresh'
 }
+
+/**
+ * Reads what changed between a close commit and the head. A commit that does
+ * not resolve, or that the head does not descend from, reads as not an
+ * ancestor and carries nothing. A head that does not resolve, or a diff that
+ * fails, is a read that failed, so the gate refuses rather than passes.
+ *
+ * The abbreviated marker resolves first, so the ancestry test runs on the full
+ * sha. Renames are split into both sides so a move out of a painted path
+ * still reads as painted.
+ */
+export async function readChangedPaths(
+  git: GitRunner,
+  from: string,
+  to: string,
+): Promise<ChangedRead | undefined> {
+  if ((await git(['cat-file', '-e', `${to}^{commit}`])) === undefined) {
+    return undefined
+  }
+
+  const full = (
+    await git(['rev-parse', '--verify', '-q', `${from}^{commit}`])
+  )?.trim()
+  if (full === undefined || full === '') return { isAncestor: false, paths: [] }
+
+  const base = (await git(['merge-base', full, to]))?.trim()
+  if (base !== full) return { isAncestor: false, paths: [] }
+
+  const diff = await git(['diff', '--name-only', '--no-renames', full, to])
+  if (diff === undefined) return undefined
+
+  return { isAncestor: true, paths: nonEmptyLines(diff) }
+}

package/src/pr/painted.ts

@@ -0,0 +1,87 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Where a project adds to or trims the default list of painted paths. */
+export const PAINTED_CONFIG_REL = join('canon', 'config', 'painted.json')
+
+export interface PaintedPatterns {
+  /** A path matching any of these is painted unless `unpainted` also matches. */
+  readonly painted: readonly string[]
+  readonly unpainted: readonly string[]
+}
+
+const RENDERED_EXTENSIONS = [
+  'tsx',
+  'jsx',
+  'vue',
+  'svelte',
+  'astro',
+  'html',
+  'css',
+  'scss',
+  'svg',
+  'png',
+  'jpg',
+  'jpeg',
+  'gif',
+  'webp',
+  'avif',
+  'ico',
+  'woff',
+  'woff2',
+  'ttf',
+  'otf',
+]
+
+/**
+ * What a browser renders, minus the tests and stories beside it. A test-only
+ * push touches nothing a reviewer drove, which is the case the carry-forward
+ * exists for.
+ */
+export const DEFAULT_PAINTED: PaintedPatterns = {
+  painted: [`**/*.{${RENDERED_EXTENSIONS.join(',')}}`],
+  unpainted: [
+    '**/*.{test,spec,stories}.*',
+    '**/__tests__/**',
+    '**/__snapshots__/**',
+  ],
+}
+
+function strings(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === 'string')
+    : []
+}
+
+/**
+ * The default list plus the project's own, read from `canon/config/painted.json`
+ * as `{ "painted": [...], "unpainted": [...] }`. A file that is absent or does
+ * not parse leaves the default, since a typo there must not make every push
+ * read as unpainted.
+ */
+export function loadPaintedPatterns(root: string): PaintedPatterns {
+  const path = join(root, PAINTED_CONFIG_REL)
+  if (!existsSync(path)) return DEFAULT_PAINTED
+
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
+    if (typeof parsed !== 'object' || parsed === null) return DEFAULT_PAINTED
+    const { painted, unpainted } = parsed as Record<string, unknown>
+    return {
+      painted: [...DEFAULT_PAINTED.painted, ...strings(painted)],
+      unpainted: [...DEFAULT_PAINTED.unpainted, ...strings(unpainted)],
+    }
+  } catch {
+    return DEFAULT_PAINTED
+  }
+}
+
+function matchesAny(path: string, globs: readonly string[]): boolean {
+  return globs.some((glob) => new Bun.Glob(glob).match(path))
+}
+
+export function isPainted(path: string, patterns: PaintedPatterns): boolean {
+  return (
+    matchesAny(path, patterns.painted) && !matchesAny(path, patterns.unpainted)
+  )
+}

package/src/roots/record.ts

@@ -177,6 +177,16 @@ export function creationRel(
   return join(at, spell(at, folder), ...rest)
 }
 
+/** Whether a root holds the backup history or a record folder, at its spelling. */
+function holdsRecords(root: string, candidate: RecordRoot): boolean {
+  return RECORD_ENTRIES.some(
+    (entry) =>
+      entry !== 'README.md' &&
+      entry !== SCRATCH &&
+      existsSync(join(root, candidate, spell(candidate, entry))),
+  )
+}
+
 /**
  * The record root itself, for a caller whose subject is the root rather than a
  * folder inside it.
@@ -186,11 +196,18 @@ export function creationRel(
  * one answer. Splitting them would let a push resolve a history at one root and
  * stage a work tree at the other, which stages the deletion of every folder the
  * move relocated.
+ *
+ * A root counts when it holds a `.records.git` or a record folder. The bare
+ * directory does not, because `.claude/` exists in every installed project for
+ * its hooks and rules, so testing it pinned a fresh clone to the retired root.
+ * `README.md` and the scratch folder are left out: a records pull writes the
+ * first back and the second is deletable, so a root holding only them has
+ * nothing to protect.
  */
 export function recordRoot(root: string): string {
   return join(
     root,
-    RECORD_ROOTS.find((candidate) => existsSync(join(root, candidate))) ??
+    RECORD_ROOTS.find((candidate) => holdsRecords(root, candidate)) ??
       CREATION_ROOT,
   )
 }

package/src/sandbox/census.ts

@@ -69,7 +69,7 @@ export function listSkills(root: string): string[] {
 /**
  * Maps a scenario to the skill it drives, trying two spellings in order.
  *
- * `<category>-<command>` is the rule `canon/context/sandbox/coverage/census.md` states, and it
+ * `<category>-<command>` is the rule `canon/context/development/sandbox.md` states, and it
  * alone pairs 29 of 54 skills. The bare `<command>` fallback is what reaches the
  * rest: `claude/target-setup.ts` drives the `target-setup` skill, not a `claude-target-setup` that
  * does not exist. Stating one spelling and shipping two is what let the audit

package/src/sandbox/headless/run.ts

@@ -417,8 +417,9 @@ async function drive(
 
   // Taken after provisioning, so a scenario that stages a live session record
   // of its own is already in the before snapshot rather than reported as a
-  // dispatch this run made. `canon/context/sandbox/isolation.md` carries why
-  // such a scenario writes to the real registry at all.
+  // dispatch this run made. A scenario that fakes a live session
+  // writes to the real registry, since provisioning and the driven run share
+  // no environment to repoint it.
   const registry = sessionsDir()
   const sessionsBefore = snapshotSessions(registry)
 

package/src/sandbox/headless/watch.ts

@@ -65,8 +65,8 @@ export function writesBetween(before: Manifest, after: Manifest): string[] {
  *
  * It makes an escape visible rather than impossible. A session can write to a
  * home directory, to a sibling worktree, or to any path outside these roots, and
- * none of that is watched. The standing limits in
- * `canon/context/sandbox/overview.md` carry what stays invisible.
+ * none of that is watched. `canon/context/development/sandbox.md` names the four
+ * directories the watch reads.
  *
  * A linked worktree is the normal place to develop this repository, and the
  * rule an escaping session follows sends scratch to the main root rather than to
@@ -108,8 +108,7 @@ export function escapeRoots(projectRoot: string): string[] {
  * `dispatch.ts`, so the key defined against this file-write watch keeps one
  * meaning. An arm whose skill is meant to reach past the sandbox tree declares
  * `escape_scope` in its `expect.toml`, which bounds a legitimate write rather
- * than the run. Read `canon/context/sandbox/isolation.md` and
- * `canon/context/sandbox/coverage/workflow-arms.md` before writing a claim past
+ * than the run. Read `canon/context/development/sandbox.md` before writing a claim past
  * that.
  */
 export const ESCAPE_SCRATCH_DIRS = [

package/src/slides/convert/master.ts

@@ -157,6 +157,9 @@ export function slideNumberProps(theme: DeckTheme): PptxGenJS.SlideNumberProps {
   }
 }
 
+// An SVG mark keeps the broken PNG fallback pptxgenjs writes, because the
+// screenshot patch in export.ts reaches slides and never layouts, so the mark
+// is a raster file.
 function markImage(path: string, size: MarkSize): PptxGenJS.ImageProps {
   const scale = Math.min(MARK_BOX.w / size.width, MARK_BOX.h / size.height)
   const w = Math.round(size.width * scale * 1000) / 1000

package/src/sync/format.ts

@@ -0,0 +1,46 @@
+import { existsSync } from 'node:fs'
+import { extname, join, resolve } from 'node:path'
+import { execa } from 'execa'
+
+/**
+ * Resolved in order, so a project carrying both formats with the repo's own.
+ * Prettier prints to stdout unless told to write, where oxfmt rewrites in place.
+ */
+const FORMATTERS = [
+  { name: 'oxfmt', flags: [] },
+  { name: 'prettier', flags: ['--write'] },
+] as const
+
+/** What a formatter reads. A shell script or a binary seed is left to its own tool. */
+const FORMATTABLE = new Set(['.json', '.jsonc', '.md', '.yml', '.yaml'])
+
+/**
+ * Runs the project's installed formatter over the files a sync wrote, so a
+ * write the formatter would reshape does not leave a whitespace diff on a file
+ * nobody edited. Only the named paths are passed, never the project, which
+ * keeps a dirty tree unformatted. A path is absolute or relative to `target`.
+ *
+ * Best effort: no installed formatter, or one that fails, leaves the output as
+ * written and the sync unaffected. Never pass a file the sync hashes against
+ * its source, since the bytes on disk would stop matching the record.
+ */
+export async function formatWritten(
+  target: string,
+  paths: readonly string[],
+): Promise<void> {
+  const files = paths
+    .filter((path) => FORMATTABLE.has(extname(path)))
+    .map((path) => resolve(target, path))
+  if (files.length === 0) return
+
+  const formatter = FORMATTERS.map((candidate) => ({
+    ...candidate,
+    path: join(target, 'node_modules', '.bin', candidate.name),
+  })).find((candidate) => existsSync(candidate.path))
+  if (formatter === undefined) return
+
+  await execa(formatter.path, [...formatter.flags, ...files], {
+    cwd: target,
+    reject: false,
+  })
+}

package/src/sync/stamp.ts

@@ -4,6 +4,7 @@ import { mkdir, writeFile } from 'node:fs/promises'
 import { dirname, join, sep } from 'node:path'
 import { execa } from 'execa'
 import { resolveExisting } from '@/roots/legacy'
+import { formatWritten } from '@/sync/format'
 import { recordTarget } from '@/targets/registry'
 import { compareVersions, parseVersion } from '@/version/compare'
 import { readInstalled } from '@/version/installed'
@@ -287,6 +288,11 @@ async function putDomain(
   await mkdir(dirname(path), { recursive: true })
   await writeFile(path, `${JSON.stringify(stamp, null, 2)}\n`)
 
+  // The stamp hashes every file but itself, so reshaping it cannot read as
+  // drift. Seeds and goldens stay as copied for the opposite reason: their
+  // hashes are taken against the source bytes.
+  await formatWritten(target, [path])
+
   // Every install and sync that stamps a target passes through here, which is
   // what makes this the one place the machine-level index can be kept without
   // each command remembering to. Its outcome is dropped rather than reported: