@erclx/canon 4.85.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,11 +65,15 @@ export const RECORD_ENTRIES: readonly string[] = [
   SCRATCH,
   'README.md',
   'diagrams',
+  'evidence',
+  'feedback',
   'groundwork',
   'intake',
   'memory',
+  'picks',
   'plans',
   'proposals',
+  'ready',
   'review',
   'tasks',
   'teach',

package/standards/index.md

@@ -27,6 +27,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Pull request reference](pr.md): Pull request title and body conventions
 - [Publish reference](publish.md): Scan an author runs against finished text, the cross-reference form each destination takes, and the response to an unreadable source
 - [Readme reference](readme.md): Readme voice, structure, and content conventions
+- [Ready reference](ready.md): Folder layout, ordinal naming, the overview frontmatter, the thin-plan contract, and the archive lifecycle for a finished-file handoff
 - [Requirements reference](requirements.md): Shape and content rules for canon/REQUIREMENTS.md
 - [Governance rule reference](rule.md): Rule frontmatter, body shape, and voice for .claude/rules files
 - [Session map reference](session.md): Filename and location, the sections a handoff carries, the write and read procedures, and how a role extends it

package/standards/memory.md

@@ -88,7 +88,7 @@ Capture the pattern rather than the recovery. What was tried, what failed, and w
 
 ## Links
 
-Link a related entry as `[[name]]`, where `name` is the target's filename stem without the extension. Link freely: the folder is flat and the links are the only structure it has.
+Link a related entry as `[[name]]`, where `name` is the target's filename stem without the extension. Link freely: an entry sits flat at the top level and the links are the only structure among them. `review/` and `archive/` hold receipts and retirements rather than entries, so neither takes a link.
 
 - Place links inside the body part they support, not in a list of their own at the end.
 - A link naming an entry nobody has written yet is legal, and it marks a rule worth writing rather than a defect.

package/standards/plan.md

@@ -85,6 +85,8 @@ A constraint measured against work in flight expires when that work merges, and
 
 A dead constraint fails silently in the expensive direction. A session honoring one ships the dangling citation the change created and reports success, where a session crossing a live constraint collides visibly and is caught.
 
+A constraint naming a `.canon/ready/` folder is a third shape beside the two above. It makes that folder's files the verbatim source for the paths this plan's `**Files to touch:**` lists, per `ready.md`, so the executing session copies those paths rather than authoring them.
+
 ### Risks
 
 - Name the collision rather than the category. A risk a reader cannot act on is padding.

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/ready.md

@@ -0,0 +1,105 @@
+---
+title: Ready reference
+description: Folder layout, ordinal naming, the overview frontmatter, the thin-plan contract, and the archive lifecycle for a finished-file handoff
+---
+
+# Ready reference
+
+Applies to a ready folder at `.canon/ready/<nn>-<slug>/`. A warm session that has already written a skill, a rule, or another finished file uses it to hand the exact text to the worker that ships it, since a plan only describes a change and a cold worker reading a description writes the file again from scratch. The folder holds the finished files themselves, laid out at their destination paths, so the worker's job is to copy rather than to author.
+
+The folder is gitignored, and backed wherever a records remote is configured: `canon records push` and `canon records pull` protect it against the machine being lost there, refuse with `no-remote` where it is not, and protect nothing against a folder deleted before anyone has pushed. That is why the archive step below is a move rather than a cleanup.
+
+## Scope
+
+Governs a ready folder under `.canon/ready/<nn>-<slug>/`: folder layout, ordinal naming, the overview's frontmatter, what the mirrored tree holds, the thin-plan contract that ships it, and the lifecycle from the live folder to the archive.
+
+Does not govern:
+
+- The thin plan itself, its filename, its sections, and its suggested-and-answer contract: `plan.md`
+- The task file that reaches a ready folder through a plan, and the origin line pointing back at it: `tasks.md`
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Headings, punctuation, word choice, and file references: `markdown.md`
+- Whether a change earns a ready folder over a plan a worker builds from scratch, which belongs to the warm session deciding how to hand off its own work
+
+## What a working ready folder looks like
+
+A ready folder works when a worker that has never seen the warm session's conversation can copy from it alone:
+
+- Which destination path does each file land at, and does the folder hold nothing else?
+- What is the worker still responsible for that the files themselves do not carry, such as a docs sync, a sandbox scenario, or a test?
+- What branch type does the change take?
+- Is every path the folder mirrors also declared in the thin plan's `**Files to touch:**`?
+
+A ready folder failing these is non-conforming even when it satisfies every shape rule below.
+
+## Folder name
+
+- Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal followed by a kebab-case slug matching the plan's own slug.
+- The ordinal marks a folder per handoff, opened once by the warm session that writes it. It runs on its own sequence, separate from groundwork and intake's shared one, since a ready folder is not a measurement track.
+- With no folder holding an entry yet, the first one opened takes `01`. Read the highest existing `.canon/ready/<nn>-*/` folder, including the archive, and take the next integer.
+- Never renumber an existing folder. The ordinal is the order it opened, and the pull request that shipped it cites the folder by that name.
+
+## 00-overview.md
+
+Every ready folder carries `00-overview.md` at its root, beside the mirrored tree. It orients the worker and states what the files themselves cannot.
+
+- `title` (required): the change in sentence case
+- `description` (required): one line naming what the handoff carries
+- `type` (required): the branch type the plan should take, one of the types `branch.md` fixes
+- `destinations` (required): the list of destination paths the folder mirrors, matching the thin plan's `**Files to touch:**` exactly
+
+```yaml
+---
+title: <Change in sentence case>
+description: <one line naming what the handoff carries>
+type: <feat | fix | chore | ...>
+destinations:
+  - <path/to/file>
+---
+```
+
+Below the frontmatter, state in prose what the worker still owns beyond copying the files: a docs sync, a sandbox scenario update, a test the files do not include, or "nothing further" where the files are the whole of the change.
+
+## The mirrored tree
+
+- Every other file in the folder sits at the same relative path its destination has in the project, so `standards/ready.md` inside the destination tree sits at `<nn>-<slug>/standards/ready.md` inside the ready folder.
+- Carry no file the destination tree would not carry. A ready folder is a source for `git mv`-shaped copies, not a scratch pad for the warm session's own notes. Anything else belongs in the plan or in the pull request body.
+- Write each file exactly as it should land. The worker copies verbatim and edits only what the gate or the overview's own list requires, so a placeholder or a half-finished passage ships as written.
+
+## The thin-plan contract
+
+- A ready folder ships through an ordinary task row and a plan at `.canon/plans/feature-<slug>.md`, per `plan.md`. No new plan shape exists for it.
+- Name the ready folder in the plan's `**Constraints:**`, stating that the folder's files are the verbatim source for the paths the plan's `**Files to touch:**` lists.
+- List every destination path in `**Files to touch:**`, matching `00-overview.md`'s `destinations` field. A path the plan omits is invisible to `plan-reach`'s collision check, so a mismatch between the two lists is a defect in the plan rather than a variant the standard permits.
+- Keep the plan itself thin. Its `**Files to touch:**` entries may point at the ready folder's own copy for the reason behind each file rather than restating it, since the overview and the files already carry the detail a plan would otherwise duplicate.
+
+## Lifecycle
+
+- Write the ready folder in the same session that writes the files it carries. A folder assembled later from memory is a plan with extra steps, not a handoff.
+- Move the folder to `.canon/ready/archive/<nn>-<slug>/` by hand when the task that shipped it archives. No board verb currently automates this move. `canon tasks archive` moves the task and its plan and leaves the ready folder where it is.
+- Never delete a ready folder. The archived copy sits beside the merged pull request as the exact text that shipped, the way an archived plan sits beside the reasoning that produced it.
+
+## Anti-patterns
+
+- **The folder with an undeclared destination.** A file the plan's `**Files to touch:**` does not list passes the collision check unseen, and a second track can write the same path without either side finding out.
+- **The rewritten copy.** A worker that reads the folder's files as inspiration and writes its own version loses the exact text the handoff exists to carry.
+- **The folder as scratch.** Notes, alternates, or draft passages left in the folder beside the real files leave the worker guessing which is the source.
+- **The folder left live after shipping.** A ready folder nobody moves to the archive reads as unshipped work to the next session that lists the live folder.
+
+## Template
+
+```markdown
+.canon/ready/<nn>-<slug>/
+├── 00-overview.md
+└── <path/to/file> # mirrors the destination tree, one entry per file
+```
+
+```yaml
+---
+title: <Change in sentence case>
+description: <one line naming what the handoff carries>
+type: <feat | fix | chore | ...>
+destinations:
+  - <path/to/file>
+---
+```

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/`, 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.

package/tooling/claude/seeds/.claude/hooks/memory-index.sh

@@ -33,6 +33,16 @@ case "$file_path" in
 *) exit 0 ;;
 esac
 
+# A shell `case` `*` crosses `/`, so the match above also catches a receipt
+# under memory/review/ or a retired entry under memory/archive/. Neither is
+# a pen entry the index renders, so both exit here before the regen call.
+case "$file_path" in
+*/.claude/memory/review/* | */.canon/memory/review/* | \
+  */.claude/memory/archive/* | */.canon/memory/archive/*)
+  exit 0
+  ;;
+esac
+
 case "$file_path" in
 */.claude/memory/index.md | */.canon/memory/index.md) exit 0 ;;
 esac