@erclx/canon 4.86.0 → 4.87.0

package/src/migrate/scratch-evidence.ts

@@ -1,6 +1,6 @@
 /**
  * The promotion of nine cited measurement folders out of `.canon/tmp/` into
- * `.canon/review/evidence/`, which `canon records push` already backs.
+ * `.canon/evidence/<nn>-<folder>/`, which `canon records push` already backs.
  *
  * The scratch root is the one record root a disk loss takes with it, and a
  * durable record naming a folder under it as its evidence is a citation into
@@ -26,6 +26,13 @@
 import { existsSync } from 'node:fs'
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
+import {
+  byFirstAppearance,
+  folderNames,
+  nextOrdinal,
+  numberedName,
+  slugOf,
+} from '@/migrate/evidence-ordinal'
 import { presentFolders } from '@/records/backup'
 import { recordDir, SCRATCH } from '@/record-root'
 
@@ -59,16 +66,14 @@ export const PROMOTED_FOLDERS: readonly string[] = [
   'target-survey',
 ]
 
-const EVIDENCE_ROOT = ['review', 'evidence'] as const
-
 /** Where a promoted folder sits before the move. */
 export function sourcePath(root: string, folder: string): string {
   return recordDir(root, SCRATCH, folder)
 }
 
-/** Where it lands after, always under whichever root `review/` resolves at. */
-export function destinationPath(root: string, folder: string): string {
-  return recordDir(root, ...EVIDENCE_ROOT, folder)
+/** The folder a promoted one lands inside, under whichever root carries it. */
+function evidenceDir(root: string): string {
+  return recordDir(root, 'evidence')
 }
 
 function escape(value: string): string {
@@ -100,14 +105,14 @@ function citationPattern(folder: string): RegExp {
 
 interface Rewrite {
   readonly pattern: RegExp
-  readonly folder: string
+  readonly name: string
 }
 
-/** One rewrite per folder, paired with its citation pattern. */
-function buildRewrites(folders: readonly string[]): readonly Rewrite[] {
-  return folders.map((folder) => ({
+/** One rewrite per folder, from its scratch name to its numbered one. */
+function buildRewrites(names: ReadonlyMap<string, string>): readonly Rewrite[] {
+  return [...names].map(([folder, name]) => ({
     pattern: citationPattern(folder),
-    folder,
+    name,
   }))
 }
 
@@ -131,8 +136,8 @@ function isKept(lines: readonly string[], index: number): boolean {
 
 function rewriteLine(line: string, rewrites: readonly Rewrite[]): string {
   return rewrites.reduce(
-    (current, { pattern, folder }) =>
-      current.replace(pattern, `.canon/review/evidence/${folder}`),
+    (current, { pattern, name }) =>
+      current.replace(pattern, `.canon/evidence/${name}`),
     line,
   )
 }
@@ -144,7 +149,7 @@ interface RewriteOutcome {
 
 /**
  * Rewrites every unmarked citation of a folder `rewrites` covers into its
- * destination under `.canon/review/evidence/`, absolute regardless of how the
+ * destination under `.canon/evidence/`, absolute regardless of how the
  * source citation was spelled, counting each as it goes. A file naming no
  * such folder returns byte-identical with a count of zero, and a marked line
  * is returned unchanged and uncounted.
@@ -232,30 +237,55 @@ export interface ScratchEvidencePlan {
 }
 
 /**
- * Every promoted folder found on disk, with its destination, refusing a
- * folder whose destination is already occupied rather than merging into it.
+ * Every promoted folder found on disk, with its numbered destination, and the
+ * name each promoted folder's citations rewrite to.
+ *
+ * Folders on disk take ordinals in order of first appearance, continuing past
+ * the highest ordinal `evidence/` already holds. One whose slug `evidence/`
+ * already carries refuses rather than taking a second number, and its
+ * citations stay as they are. One already moved is not on disk under scratch,
+ * so its citations rewrite to the numbered name it landed at.
  */
 export function planFolderMoves(root: string): {
   moves: FolderMove[]
   collisions: string[]
+  names: Map<string, string>
 } {
+  const dir = evidenceDir(root)
+  const existing = folderNames(dir)
   const moves: FolderMove[] = []
   const collisions: string[] = []
+  const names = new Map<string, string>()
+  let next = nextOrdinal(existing)
+
+  const present = byFirstAppearance(
+    PROMOTED_FOLDERS.map((folder) => ({
+      name: folder,
+      dir: sourcePath(root, folder),
+    })).filter((folder) => existsSync(folder.dir)),
+  )
 
-  for (const folder of PROMOTED_FOLDERS) {
-    const from = sourcePath(root, folder)
-    if (!existsSync(from)) continue
-
-    const to = destinationPath(root, folder)
-    if (existsSync(to)) {
-      collisions.push(to)
+  for (const { name: folder, dir: from } of present) {
+    const landed = existing.find((entry) => slugOf(entry) === folder)
+    if (landed !== undefined) {
+      collisions.push(join(dir, landed))
       continue
     }
 
-    moves.push({ folder, from, to })
+    const name = numberedName(next, folder)
+    next += 1
+    names.set(folder, name)
+    moves.push({ folder, from, to: join(dir, name) })
   }
 
-  return { moves, collisions }
+  for (const folder of PROMOTED_FOLDERS) {
+    if (existsSync(sourcePath(root, folder))) continue
+
+    const landed = existing.find((entry) => slugOf(entry) === folder)
+    if (landed !== undefined) names.set(folder, landed)
+  }
+
+  return { moves, collisions, names }
 }
 
 /**
@@ -267,11 +297,8 @@ export function planScratchEvidence(
   root: string,
   sources: readonly ScratchEvidenceSource[],
 ): ScratchEvidencePlan {
-  const { moves, collisions } = planFolderMoves(root)
-  const folders = PROMOTED_FOLDERS.filter(
-    (folder) => !collisions.includes(destinationPath(root, folder)),
-  )
-  const rewrites = buildRewrites(folders)
+  const { moves, collisions, names } = planFolderMoves(root)
+  const rewrites = buildRewrites(names)
   const entries: CitationEntry[] = []
 
   for (const source of sources) {

package/src/record-root.ts

@@ -65,9 +65,12 @@ export const RECORD_ENTRIES: readonly string[] = [
   SCRATCH,
   'README.md',
   'diagrams',
+  'evidence',
+  'feedback',
   'groundwork',
   'intake',
   'memory',
+  'picks',
   'plans',
   'proposals',
   'ready',

package/standards/publish.md

@@ -40,7 +40,7 @@ This check is one of the two the destination rule above scopes. The reader insid
 
 A phase label is one way text names the board, and a path under a record root is the other. Both resolve for a reader holding this checkout and neither resolves for anyone else, so this check is the second one the destination rule scopes.
 
-Two shapes get past a reader scanning for a bare label. A code span quoting a label is still the label, so read a span whose whole content is one as a hit and leave a longer token inside a span alone, which is a fixture name rather than a reference. The second shape is a path under a record root, gitignored and therefore absent from every clone, so `.canon/review/feedback/` names a folder the remote's reader cannot open.
+Two shapes get past a reader scanning for a bare label. A code span quoting a label is still the label, so read a span whose whole content is one as a hit and leave a longer token inside a span alone, which is a fixture name rather than a reference. The second shape is a path under a record root, gitignored and therefore absent from every clone, so `.canon/feedback/` names a folder the remote's reader cannot open.
 
 Under the tracked `canon/` and `.claude/` folders there is no hit, since `canon/context/governance/rules.md` resolves everywhere. `.canon/` carries no such carve-out: one ignore line covers the root whole, so every path beneath it is a hit regardless of which folder names it.
 

package/standards/skill.md

@@ -210,7 +210,7 @@ Without this skill, a session <observed failure>, <observed failure>.
 ### Output and tuning
 
 - Skill success lines emit the full relative path from the project root (`<dir>/<file>`) for any file written, updated, or deleted. A bare filename names a file the reader cannot open. The `## Output` section of the project's instruction file sets the form that path takes, so a skill body states which path is emitted and leaves the form to that section.
-- Before a skill writes anything, decide whether the output is a deliverable the project keeps or a toolkit session record. A deliverable lands among the project's own tracked files. A session record lands under `.canon/`, in the named subfolder for its kind (`tasks/`, `plans/`, `review/`, `memory/`, `groundwork/`, `intake/`, `proposals/`, `diagrams/`, `teach/`, `ready/`, or `walkthroughs/`, with `tmp/` for scratch nothing else claims), never in a folder the body invents. `canon/ARCHITECTURE.md`'s per-folder decisions are the precedent for which kind takes which folder.
+- Before a skill writes anything, decide whether the output is a deliverable the project keeps or a toolkit session record. A deliverable lands among the project's own tracked files. A session record lands under `.canon/`, in the named subfolder for its kind (`tasks/`, `plans/`, `review/`, `memory/`, `groundwork/`, `intake/`, `proposals/`, `diagrams/`, `teach/`, `ready/`, `feedback/`, `picks/`, `evidence/`, `transcripts/`, or `walkthroughs/`, with `tmp/` for scratch nothing else claims), never in a folder the body invents. A `review/` writer names its file `<kind>-<slug>.md` and writes it flat, and an `evidence/` folder takes the next two-digit ordinal as `<nn>-<slug>/`, numbered in the order the folders first appeared. `canon/ARCHITECTURE.md`'s per-folder decisions are the precedent for which kind takes which folder.
 - Codify a skill's posted or generated output as a fenced template, and keep the body consistent with every capability the frontmatter description names.
 - When a skill gathers user input or pre-seeds a template, attach a concrete proposed default to every question, derived from project context. Accept "use defaults" as a bulk-confirm.
 - Separate correctness axes (routing, sourcing, escalation, decline) from shape axes (line count, formatting, variant sprawl) when tuning a skill. Tighten only on correctness regressions. Do not convert soft caps to hard caps for aesthetic drift when correctness passes.