@erclx/canon 4.84.0 → 4.86.0

package/src/records/backup.ts

@@ -1,27 +1,25 @@
-import { existsSync } from 'node:fs'
+import { existsSync, readdirSync } from 'node:fs'
 import { basename, join, relative, resolve } from 'node:path'
 import { $ } from 'bun'
 import { gitEnv } from '@/git-env'
 import { RECORD_ROOTS, recordRoot } from '@/record-root'
 
 /**
- * The folders a backup carries, relative to the record root `workTree` resolves
- * rather than to either root specifically, since the same eleven names sit
- * under whichever one a tree holds.
+ * The legacy `.claude`-root allowlist, read only when a project has not moved
+ * to `.canon/` yet.
  *
- * Nothing bounds this list any more, and the move is what took the bound away.
- * The claude manifest used to ship a folder apiece, so the `# Claude` group
- * named a superset this could be read against; it ships one `.canon/` root
- * entry now and names no folder at all. Spelling the list out is therefore the
- * whole of the protection rather than half of it, since a record folder added
- * under `.canon/` is ignored the moment it exists and enters no payload until
- * a name is written here.
+ * That root still tracks `skills/`, `rules/`, and `hooks/` a backup must never
+ * carry, so it cannot take the exclusion-based reading `foldersAt` applies at
+ * `.canon/`: every top-level entry there is fair game and an allowlist is the
+ * only thing separating a record folder from the vendor's own. A `.canon/` root
+ * carries no such mix, since nothing else lives there, which is what let the
+ * bound move from this list to `EXCLUDED_ENTRIES`.
  *
- * Three counts describe this surface and each is right about a different
- * question, so they are stated apart rather than reconciled. Eleven is what a
- * disk loss would take, which is this list. Twelve is what sat under `.claude/`
- * as an ignored folder before the move, which adds the scratch folder that is
- * deletable without loss and `worktrees/`, whose contents belong to the
+ * Three counts describe what this list once bounded and each is right about a
+ * different question, so they are stated apart rather than reconciled. Eleven
+ * is what a disk loss would take, which is this list. Twelve is what sat under
+ * `.claude/` as an ignored folder before the move, which adds the scratch folder
+ * that is deletable without loss and `worktrees/`, whose contents belong to the
  * enclosing repository already. Thirteen is what the move relocated, which counts
  * ignore entries rather than folders: the twelve less `worktrees/`, which stayed,
  * plus `.records.git/` and the `README.md` a records pull writes back.
@@ -73,6 +71,53 @@ const RETIRED_FOLDERS = [
 /** The history directory's own name, which keeps its dot at either record root. */
 const RECORDS_GIT_NAME = '.records.git'
 
+/**
+ * Top-level `.canon/` entries a backup never carries, named rather than
+ * matched by pattern so a reader can see the whole exemption in one place.
+ *
+ * `tmp` is deletable without loss, per the scratch standard. `ordinal-locks`
+ * is transient per claim, and pushing one races the claim it guards.
+ * `.records.git` is the history itself, and reading directories rather than
+ * every entry already keeps a pull's `README.md` out, so this is the one name
+ * that still has to be said: without it a listing would stage the history
+ * into itself.
+ */
+export const EXCLUDED_ENTRIES = [
+  'tmp',
+  'ordinal-locks',
+  RECORDS_GIT_NAME,
+] as const
+
+/**
+ * The record folders sitting at `dir` right now, at either root spelling.
+ *
+ * A `.claude`-spelled directory reads the fixed allowlist, filtered to what
+ * exists, since that root also holds `skills/`, `rules/`, and `hooks/` no
+ * exclusion set names. A `.canon`-spelled directory reads its own top-level
+ * directories less `EXCLUDED_ENTRIES` instead, since nothing else shares that
+ * root and a folder added there is a record folder by construction.
+ *
+ * Takes a directory rather than a project root so `strandedFolders` can ask it
+ * about a candidate root other than the one `workTree` resolved.
+ */
+function foldersAt(dir: string): string[] {
+  if (basename(dir) === '.claude') {
+    return BACKED_FOLDERS.filter((folder) => existsSync(join(dir, folder)))
+  }
+
+  const entries = existsSync(dir)
+    ? readdirSync(dir, { withFileTypes: true })
+    : []
+
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter(
+      (name) =>
+        !EXCLUDED_ENTRIES.includes(name as (typeof EXCLUDED_ENTRIES)[number]),
+    )
+}
+
 /**
  * The tree a backup stages, which is the record root itself.
  *
@@ -167,6 +212,8 @@ export interface PushReport {
   readonly ok: true
   readonly root: string
   readonly folders: readonly string[]
+  /** A folder in scope this push found on disk but the records index had never tracked. */
+  readonly firstSeen: readonly string[]
   readonly changed: number
   readonly commit?: string
   readonly pushed: boolean
@@ -372,9 +419,10 @@ async function resolveRemote(
  * work tree hard and leaves the stranded copy beside it, which is not a loss but
  * is a tree where two roots disagree and neither is wrong.
  *
- * Only `BACKED_FOLDERS` is read. The scratch folder is deletable by definition
- * and `worktrees/` belongs to the enclosing repository, so neither stranded
- * anywhere costs a record.
+ * Reads `foldersAt` on each candidate, so a `.canon` candidate is checked
+ * against its own exclusion set rather than the `.claude` allowlist. The
+ * scratch folder is deletable by definition and `worktrees/` belongs to the
+ * enclosing repository, so neither stranded anywhere costs a record.
  */
 function strandedFolders(root: string): string[] {
   const resolved = resolve(workTree(root))
@@ -383,9 +431,7 @@ function strandedFolders(root: string): string[] {
     const dir = join(root, candidate)
     if (resolve(dir) === resolved) return []
 
-    return BACKED_FOLDERS.filter((folder) => existsSync(join(dir, folder))).map(
-      (folder) => join(candidate, folder),
-    )
+    return foldersAt(dir).map((folder) => join(candidate, folder))
   })
 }
 
@@ -404,9 +450,15 @@ function refuseSplitRoots(root: string): BackupRefused | undefined {
   )
 }
 
+/** A pathspec-safe subset, plus which of it never entered the records index before. */
+interface FolderScope {
+  readonly scope: readonly string[]
+  readonly firstSeen: readonly string[]
+}
+
 /**
- * The subset of the backed and retired names a pathspec can name: on disk, or
- * already in the records index.
+ * The subset of the present, retired, and previously-tracked names a pathspec
+ * can name.
  *
  * A pathspec matching neither fails the whole `add`, which is why the subset
  * exists. The index half is what covers a folder deleted in full. Reading disk
@@ -415,29 +467,64 @@ function refuseSplitRoots(root: string): BackupRefused | undefined {
  * every other unpushed deletion.
  *
  * The retired names are the same case one level up, where the folder left the
- * backed list rather than the disk, and the index is the only side that still
- * knows it existed.
+ * disk before the index caught up, and the index is the only side that still
+ * knows it existed. At a `.canon` root a folder can leave the same way under a
+ * name `RETIRED_FOLDERS` never anticipated, which is what folding the index
+ * into the candidate set (rather than only using it as a filter) covers.
+ *
+ * `firstSeen` is a folder in scope that disk carries but the index has never
+ * tracked, which is the read a caller reports rather than acts on: a folder
+ * `.canon` picked up that should have been excluded is visible in the push
+ * report instead of entering the payload silently.
  */
-async function scopedFolders(root: string): Promise<string[]> {
+async function scopedFolders(root: string): Promise<FolderScope> {
   const tracked = await records(root, ['ls-files'])
   const indexed = new Set(
     tracked.ok ? tracked.text.split('\n').filter(Boolean).map(topSegment) : [],
   )
 
-  return [...BACKED_FOLDERS, ...RETIRED_FOLDERS].filter(
+  const present = new Set(foldersAt(workTree(root)))
+  const retired = RETIRED_FOLDERS.filter(
     (folder) => existsSync(join(workTree(root), folder)) || indexed.has(folder),
   )
+  const scope = [...new Set([...present, ...retired, ...indexed])].sort()
+  const firstSeen = scope.filter(
+    (folder) => present.has(folder) && !indexed.has(folder),
+  )
+
+  return { scope, firstSeen }
 }
 
 function topSegment(path: string): string {
   return path.split('/')[0]
 }
 
-/** What a report names, which is the folders a reader can go and open. */
-function presentFolders(root: string): string[] {
-  return BACKED_FOLDERS.filter((folder) =>
-    existsSync(join(workTree(root), folder)),
-  )
+/**
+ * What a report names, which is the folders a reader can go and open.
+ *
+ * Exported so the scratch-evidence walk and the push and pull help text read
+ * the same resolved set rather than each re-deriving it against
+ * `BACKED_FOLDERS`, which is silently wrong at a `.canon` root.
+ */
+export function presentFolders(root: string): string[] {
+  return foldersAt(workTree(root))
+}
+
+/**
+ * The record folder names a project could ever carry, without regard to
+ * whether each currently exists: `BACKED_FOLDERS` at the legacy `.claude`
+ * root, since nothing else names a folder there, and the live directory
+ * listing at `.canon`, since nothing bounds that root's names from outside
+ * any more and a name nobody has created yet cannot be listed.
+ *
+ * Exported for `canon records size`, whose own contract reports every folder
+ * whether or not it exists so a caller reading the record gets a stable set
+ * of keys. `presentFolders` filters by existence instead, which is right for
+ * a push report naming what a reader can go and open and wrong here.
+ */
+export function candidateFolders(root: string): string[] {
+  const tree = workTree(root)
+  return basename(tree) === '.claude' ? [...BACKED_FOLDERS] : foldersAt(tree)
 }
 
 function countLines(text: string): number {
@@ -459,7 +546,7 @@ export async function pushRecords(root: string): Promise<PushOutcome> {
   const remote = await resolveRemote(root, enclosing)
   if (typeof remote !== 'string') return remote
 
-  const scope = await scopedFolders(root)
+  const { scope, firstSeen } = await scopedFolders(root)
 
   if (scope.length > 0) {
     // `-f` is what carries the payload: every backed folder is ignored by the
@@ -495,7 +582,7 @@ export async function pushRecords(root: string): Promise<PushOutcome> {
   const folders = presentFolders(root)
   const head = await records(root, ['rev-parse', '--short', 'HEAD'])
   if (!head.ok) {
-    return { ok: true, root, folders, changed, pushed: false }
+    return { ok: true, root, folders, firstSeen, changed, pushed: false }
   }
 
   const branch = await projectBranch(root, enclosing)
@@ -506,7 +593,15 @@ export async function pushRecords(root: string): Promise<PushOutcome> {
   ])
   if (!pushed.ok) return failed('push', pushed)
 
-  return { ok: true, root, folders, changed, commit: head.text, pushed: true }
+  return {
+    ok: true,
+    root,
+    folders,
+    firstSeen,
+    changed,
+    commit: head.text,
+    pushed: true,
+  }
 }
 
 /**
@@ -557,7 +652,7 @@ export async function pullRecords(root: string): Promise<PullOutcome> {
   const target = await records(root, ['rev-parse', 'FETCH_HEAD'])
   if (!target.ok) return failed('rev-parse', target)
 
-  const scope = await scopedFolders(root)
+  const { scope } = await scopedFolders(root)
 
   if (scope.length > 0) {
     const dirty = await records(root, ['status', '--porcelain', '--', ...scope])

package/src/records/size.ts

@@ -2,20 +2,24 @@ import { existsSync, type Stats } from 'node:fs'
 import { readdir, stat } from 'node:fs/promises'
 import { join } from 'node:path'
 import { RECORD_ROOTS, recordDir, SCRATCH } from '@/record-root'
-import { BACKED_FOLDERS } from '@/records/backup'
+import { candidateFolders } from '@/records/backup'
 
 /**
- * The folders a size reading covers, named at the record root they sit under.
+ * The folders a size reading covers at `root`, resolved the same way a push
+ * resolves its scope rather than pinned to `BACKED_FOLDERS`, which is silently
+ * wrong at a `.canon` root.
  *
- * It is the backed set plus the scratch folder, which a backup skips because it is
- * deletable without loss and a reading covers because deletable is not the same
- * as empty: the routing handoffs and the memory archive both sit there and both
- * accumulate. `.records.git` stays out because it is the backup history rather
- * than a record, and `worktrees/` stays out because each entry there is a
- * checkout of the enclosing repository with its own removal verb, and one of
- * them outweighs every record folder combined.
+ * It is the present backed set plus the scratch folder, which a backup skips
+ * because it is deletable without loss and a reading covers because deletable
+ * is not the same as empty: the routing handoffs and the memory archive both
+ * sit there and both accumulate. `.records.git` stays out because it is the
+ * backup history rather than a record, and `worktrees/` stays out because each
+ * entry there is a checkout of the enclosing repository with its own removal
+ * verb, and one of them outweighs every record folder combined.
  */
-export const SIZED_FOLDERS = [...BACKED_FOLDERS, SCRATCH] as const
+export function sizedFolders(root: string): string[] {
+  return [...candidateFolders(root), SCRATCH]
+}
 
 /**
  * The windows a reading reports, in days.
@@ -227,9 +231,9 @@ export async function sizeRecords(
 
   // Each folder is walked independently, and the report is ordered by the
   // caller rather than by arrival, so `Promise.all` keeps the input order while
-  // the ten walks overlap.
+  // the walks overlap.
   const folders = await Promise.all(
-    SIZED_FOLDERS.map((folder) => measure(root, folder, now)),
+    sizedFolders(root).map((folder) => measure(root, folder, now)),
   )
 
   return {

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