@erclx/canon 5.38.0 → 5.40.0

package/src/markdown/structure.ts

@@ -1,6 +1,6 @@
 import { type BodyLine, visibleText } from '@/markdown/scan'
 
-const HEADING = /^#{1,6}\s/
+export const HEADING = /^#{1,6}\s/
 
 /**
  * A section marker holding its line alone, which is the signpost a document
@@ -65,10 +65,10 @@ const BOLD_LINE = /^\*\*([^*]+)\*\*\s*$/
 const SPAN_LABEL = /^`[^`]+`$/
 const MARKER_WIDTH = 20
 
-const LIST_ITEM = /^(\s*)([-*+]|\d+\.)\s+/
-const TABLE_ROW = /^\s*\|/
+export const LIST_ITEM = /^(\s*)([-*+]|\d+\.)\s+/
+export const TABLE_ROW = /^\s*\|/
 const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
-const BLOCKQUOTE = /^\s*>/
+export const BLOCKQUOTE = /^\s*>/
 
 /**
  * A sentence ends on terminal punctuation followed by the start of another
@@ -109,8 +109,8 @@ const SENTENCE_END = /[.!?]["'’”)\]]*(?=\s+(?:["'“([]*[A-Z]|`)|\s*$)/g
 export const CHECKPOINTS = {
   run: 40,
   peerBullet: 130,
-  bullet: 250,
-  paragraph: 700,
+  bullet: 200,
+  paragraph: 350,
   sentences: 4,
   renderWidth: 80,
   cadence: 3,
@@ -336,7 +336,7 @@ function isTableRun(run: readonly BodyLine[]): boolean {
  * what lets a linked path reach the span test at all, since the markup around
  * it would fail the pattern the destination is still attached.
  */
-function isSectionMarker(text: string): boolean {
+export function isSectionMarker(text: string): boolean {
   const marker = text.match(BOLD_LINE)
   if (!marker) return false
 
@@ -438,11 +438,7 @@ interface FoldedBullet extends BulletFinding {
   readonly text: string
 }
 
-/**
- * The walk `heavyBullets` reports from, keeping each past-checkpoint bullet's
- * text so `longBlocks` can ask whether a base copy of it exists. One walk
- * rather than two, for the reason `paragraphBlocks` is shared.
- */
+/** The walk `heavyBullets` reports from. */
 function foldBullets(
   lines: readonly BodyLine[],
   checkpoints: Checkpoints,
@@ -579,10 +575,7 @@ function paragraphText(block: readonly BodyLine[]): string {
  * paragraph rule whenever the bullet rule was changed, and an author reading
  * the sentence cap would find no weight rule to read at all.
  *
- * The two numbers coincide today because paragraph and bullet weight measure
- * one population, sharing a median near 170 characters with no gap behind
- * either candidate. They are separate checkpoints regardless, so either moves
- * without dragging the other.
+ * They are separate checkpoints, so either moves without dragging the other.
  */
 export function heavyParagraphs(
   lines: readonly BodyLine[],
@@ -606,49 +599,6 @@ export function heavyParagraphs(
   return findings
 }
 
-export interface LongBlock {
-  readonly kind: 'paragraph' | 'bullet'
-  readonly line: number
-  readonly characters: number
-  /** The block's source lines folded into one, as the paragraph and bullet folds read it. */
-  readonly text: string
-}
-
-/**
- * The paragraphs past the paragraph checkpoint and the top-level bullets past
- * the bullet checkpoint, each with its text.
- *
- * Weight alone, never the sentence cap, since the growth stage asks about the
- * two numbers the standard states in characters. The definitions are the
- * audit's own, so a block this names and a block the weight report names are
- * one set.
- */
-export function longBlocks(
-  lines: readonly BodyLine[],
-  checkpoints: Checkpoints,
-): LongBlock[] {
-  const blocks: LongBlock[] = []
-
-  for (const block of paragraphBlocks(lines)) {
-    const text = paragraphText(block)
-    const characters = visibleText(text).length
-    if (characters > checkpoints.paragraph) {
-      blocks.push({
-        kind: 'paragraph',
-        line: block[0].number,
-        characters,
-        text,
-      })
-    }
-  }
-
-  for (const bullet of foldBullets(lines, checkpoints)) {
-    blocks.push({ kind: 'bullet', ...bullet })
-  }
-
-  return blocks.sort((a, b) => a.line - b.line)
-}
-
 /** Punctuation either side of a word, so an opener is compared on its letters. */
 const WORD_EDGE = /^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu
 

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/shipped/references.ts

@@ -132,7 +132,7 @@ const SAME_REPOSITORY =
  * `canon/context/` carries no equivalent pattern. The same resolution test
  * cannot separate a path every scaffolded project holds, such as
  * `canon/context/index.md`, from this repository's own domain entry, such
- * as `canon/context/context-model/indexes.md`, since both resolve here and only the
+ * as `canon/context/context-model.md`, since both resolve here and only the
  * second is a defect. That is a semantic read no pattern makes, so it stays
  * with the rule and the review checklist rather than joining this reader.
  */

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:

package/tooling/astro/reference.md

@@ -22,7 +22,7 @@ The astro stack covers Astro + TypeScript projects: content sites, marketing sit
 - `playwright.config.ts`: all browsers, `webServer` runs `bun run build && bun run preview` on port `4321` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`. Astro's dev/prod gap is wide (MDX, island hydration, asset optimization), so E2E always tests the built `dist/`. `DIST_PREBUILT` set in the environment drops the `build` half, running `bun run preview` alone against a `dist/` a prior CI job already produced.
 - `tsconfig.json`: extends `astro/tsconfigs/strict`, adds `skipLibCheck`, `vitest/globals` and `@testing-library/jest-dom/vitest` in types, `@/` paths.
 - `card.config.mjs`, `card-src/pages/og-card.astro`, and `scripts/check-card-exclusion.sh`: the social card route, its structural build exclusion, and the check enforcing it. See `## Social card route` below.
-- `eslint.config.js`: this stack's own flat config, since the web layer lints with oxlint, which parses no `.astro` file. Adds `eslint-plugin-astro` (`.astro` parser via `astro-eslint-parser`). React-hooks scoped to `.jsx`/`.tsx` only (`.astro` is not React). The shared block's `files` selector includes `.astro`, so `check-file/filename-naming-convention` reaches `.ts`, `.tsx`, and `.astro` under `KEBAB_CASE`, overriding Astro's own PascalCase component convention deliberately, on the ground that a component's name in markup comes from the import binding rather than the filename. `.js` and `.jsx` stay out of the rule's own pattern, matching `web` and `nextjs`. `check-file/folder-naming-convention` reaches every `src/**` folder except `__tests__` and the whole `pages/` subtree, which carries its own off-block for the bracket-named dynamic routes and nested slug folders Astro's file-based routing produces. See `canon/context/tooling/stacks.md` for the measurement.
+- `eslint.config.js`: this stack's own flat config, since the web layer lints with oxlint, which parses no `.astro` file. Adds `eslint-plugin-astro` (`.astro` parser via `astro-eslint-parser`). React-hooks scoped to `.jsx`/`.tsx` only (`.astro` is not React). The shared block's `files` selector includes `.astro`, so `check-file/filename-naming-convention` reaches `.ts`, `.tsx`, and `.astro` under `KEBAB_CASE`, overriding Astro's own PascalCase component convention deliberately, on the ground that a component's name in markup comes from the import binding rather than the filename. `.js` and `.jsx` stay out of the rule's own pattern, matching `web` and `nextjs`. `check-file/folder-naming-convention` reaches every `src/**` folder except `__tests__` and the whole `pages/` subtree, which carries its own off-block for the bracket-named dynamic routes and nested slug folders Astro's file-based routing produces. See `canon/context/surfaces/tooling.md` for the measurement.
 
 ## Typecheck
 
@@ -60,7 +60,7 @@ Append to the `## Scripts` table:
 
 ## CI docs (extend)
 
-In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `astro check` passes ``. The Build row's assertion reads: `` `astro build` succeeds ``. <!-- audit-ignore-citations: canon/context/ci.md -->
+In `canon/context/development/ci.md`, the Typecheck row's assertion reads: `` `astro check` passes ``. The Build row's assertion reads: `` `astro build` succeeds ``. <!-- audit-ignore-citations: canon/context/development/ci.md -->
 
 ## Social card route