@erclx/canon 4.117.0 → 4.118.0

package/src/sync/engine.ts

@@ -8,8 +8,11 @@ import {
   type DomainHashes,
   hashFile,
   readStamp,
+  type Stamp,
+  type StampDomain,
   type StampSource,
   stampedHashes,
+  stampedVersion,
   toStampKey,
   writeStamp,
 } from '@/sync/stamp'
@@ -26,6 +29,8 @@ import {
   palette,
   select,
 } from '@/ui'
+import { compareVersions, parseVersion } from '@/version/compare'
+import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 
 /**
  * One installed file in three path flavours: absolute, relative to the
@@ -58,10 +63,12 @@ export type SyncChange =
  * who moved it. `stale` and `customized` need the stamp to tell apart, so
  * `drifted` stays the verdict for a difference no stamp covers.
  *
- * `orphaned` and `stranded` both mean the walk found no source, and they are
- * separate because they need opposite treatment. A project-authored file is
- * orphaned and stays that way forever. A stamped file the toolkit no longer
- * installs to is stranded, which is a relocation waiting on a decision.
+ * `orphaned`, `retired`, and `stranded` all mean the walk found no source, and
+ * they are separate because they need different treatment. A project-authored
+ * file is orphaned and stays that way forever. A file under a root the toolkit
+ * owns outright is retired, since only the toolkit ever wrote there, and a
+ * sync deletes it. A stamped file the toolkit no longer installs to is
+ * stranded, which is a relocation waiting on a decision.
  *
  * `missing` is the one state the walk cannot produce on its own, since the
  * walk only iterates files that exist. It comes from `collectMissing`
@@ -73,6 +80,7 @@ export type EntryState =
   | 'customized'
   | 'drifted'
   | 'orphaned'
+  | 'retired'
   | 'stranded'
   | 'missing'
 
@@ -152,6 +160,14 @@ export interface SyncAdapter {
    * inference orphans a file sitting anywhere else.
    */
   readonly projectSubdir?: string
+  /**
+   * Every file under `installedRoot` is the toolkit's, so a walked file with
+   * no source is a leftover of a rule the toolkit retired or renamed rather
+   * than something a project wrote. Setting it turns that file into a
+   * `retired` entry and queues its delete, edited or not, whatever the stamp
+   * holds. Unset, the file stays `orphaned` and untouched.
+   */
+  readonly ownsInstalledRoot?: boolean
   /** Defaults to applying. */
   readonly nonInteractive?: NonInteractivePolicy
   /** Runs on a completed sync, including one with no changes. */
@@ -195,15 +211,18 @@ export function listInstalled(
 
 /**
  * Classifies every installed file against its source without writing anything.
- * A file with no source is left alone rather than deleted, which is what keeps
- * project-authored rules alive across a sync.
+ * A file with no source is deleted only when the adapter owns its installed
+ * root outright, and left alone otherwise, which is what keeps a
+ * project-authored file alive across a sync of a root the project shares.
  */
 export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
   const entries: ScanEntry[] = []
   const changes: SyncChange[] = []
   const unattributed: UnattributedFile[] = []
 
-  const hashes = stampedHashes(readStamp(target), adapter.stamp?.domain)
+  const stamp = readStamp(target)
+  const hashes = stampedHashes(stamp, adapter.stamp?.domain)
+  const newerInstall = newerInstallingVersion(stamp, adapter.stamp?.domain)
   const walked = new Set<string>()
 
   for (const file of listInstalled(
@@ -222,7 +241,18 @@ export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
     const source = adapter.locateSource(file)
 
     if (source === undefined || !existsSync(source)) {
-      entries.push(misplacedOrphan(adapter, target, file))
+      if (adapter.ownsInstalledRoot !== true) {
+        entries.push(misplacedOrphan(adapter, target, file))
+      } else if (newerInstall !== undefined) {
+        entries.push(heldForNewerInstall(file, newerInstall))
+      } else {
+        entries.push({
+          state: 'retired',
+          rel: file.rel,
+          notice: `${file.rel} (no longer shipped by the toolkit, removing)`,
+        })
+        changes.push({ kind: 'delete', dest: file.path, rel: file.rel })
+      }
       continue
     }
 
@@ -438,6 +468,8 @@ function report(adapter: SyncAdapter, plan: SyncPlan): void {
       )
     else if (entry.state === 'customized')
       logWarn(`${entry.rel} (locally customized)`)
+    else if (entry.state === 'retired')
+      logWarn(entry.notice ?? `${entry.rel} (no longer shipped by the toolkit)`)
     else if (entry.state === 'stranded')
       logWarn(`${entry.rel} (installed here by an older toolkit, now moved)`)
     else if (entry.state === 'missing')
@@ -528,6 +560,10 @@ function isProjectAuthored(adapter: SyncAdapter, file: InstalledFile): boolean {
  * Naming the destination is all this does. Moving the file rewrites a path the
  * project's own rules, skills, and docs may cite, so the sync leaves it where
  * it is.
+ *
+ * An adapter declaring `ownsInstalledRoot` never reaches this, since owning
+ * the root answers the question neither the name nor the stamp can, and its
+ * sourceless file is retired instead.
  */
 function misplacedOrphan(
   adapter: SyncAdapter,
@@ -549,6 +585,49 @@ function misplacedOrphan(
   }
 }
 
+/**
+ * The release that last wrote this domain, when it is newer than the one
+ * running. A binary older than that release cannot tell a rule it retired
+ * from one added after it, so it holds every sourceless file rather than
+ * deleting rules the newer release installed. An unparseable side holds too,
+ * since deleting on a comparison that never ran is the failure this guards.
+ * A stamp with no version predates the field and is never newer.
+ */
+function newerInstallingVersion(
+  stamp: Stamp | undefined,
+  domain: StampDomain | undefined,
+): { readonly stamped: string; readonly running: string } | undefined {
+  if (domain === undefined) return undefined
+
+  const stamped = stampedVersion(stamp, domain)
+  if (stamped === undefined) return undefined
+
+  const running = readInstalled().version ?? UNKNOWN_LABEL
+  const parsedStamped = parseVersion(stamped)
+  const parsedRunning = parseVersion(running)
+
+  if (
+    parsedStamped !== undefined &&
+    parsedRunning !== undefined &&
+    compareVersions(parsedStamped, parsedRunning) <= 0
+  ) {
+    return undefined
+  }
+
+  return { stamped, running }
+}
+
+function heldForNewerInstall(
+  file: InstalledFile,
+  versions: { readonly stamped: string; readonly running: string },
+): ScanEntry {
+  return {
+    state: 'orphaned',
+    rel: file.rel,
+    notice: `${file.rel} (installed by canon ${versions.stamped}, newer than this ${versions.running}. Upgrade canon to sync it.)`,
+  }
+}
+
 function isInside(target: string, path: string): boolean {
   const rel = relative(target, path)
   return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel)
@@ -567,8 +646,9 @@ function hasUnattributedDrift(plan: SyncPlan): boolean {
 /**
  * Records what the toolkit placed, after the copies land, so a partial apply
  * that throws leaves the previous stamp rather than a claim the target does not
- * meet. A file with no source, or one orphaned by location, is
- * project-authored and stays out.
+ * meet. A file with no source stays out, whether it is project-authored or a
+ * retired leftover a declined sync did not delete, and so does one orphaned by
+ * location.
  *
  * Reads the installed tree rather than the caller's file list, so a partial
  * install still stamps the domain's whole installed set.

package/src/sync/stamp.ts

@@ -5,6 +5,8 @@ import { dirname, join, sep } from 'node:path'
 import { execa } from 'execa'
 import { resolveExisting } from '@/legacy-path'
 import { recordTarget } from '@/targets/registry'
+import { compareVersions, parseVersion } from '@/version/compare'
+import { readInstalled } from '@/version/installed'
 
 /**
  * Domains the stamp can record. Governance and design both attribute file by
@@ -38,6 +40,14 @@ export type DomainHashes = Readonly<Record<string, string>>
 export interface DomainStamp {
   /** Toolkit revision this domain last synced from. Absent outside a git clone. */
   readonly commit?: string
+  /**
+   * Newest canon release that has written this domain. A sync deletes an
+   * installed file its toolkit does not ship, and a binary older than the one
+   * that installed the file cannot tell a retired file from one added after
+   * its own release, so this is what it reads before deleting anything.
+   * Absent on a stamp written before the field existed.
+   */
+  readonly version?: string
   readonly syncedAt: string
   readonly files: DomainHashes
   /**
@@ -178,6 +188,14 @@ function readStampFile(path: string): Stamp | undefined {
   }
 }
 
+/** The newest canon release that has written this domain, when one was recorded. */
+export function stampedVersion(
+  stamp: Stamp | undefined,
+  domain: StampDomain,
+): string | undefined {
+  return stamp?.domains[domain]?.version
+}
+
 /** The revision this domain last synced from, which bounds its upstream range. */
 export function stampedCommit(
   stamp: Stamp | undefined,
@@ -245,9 +263,11 @@ async function putDomain(
   const previous = readStamp(target)
   const previousRecord = previous?.domains[source.domain]
   const commit = await toolkitCommit(source.toolkitRoot)
+  const version = newerVersion(readInstalled().version, previousRecord?.version)
 
   const record: DomainStamp = {
     ...(commit === undefined ? {} : { commit }),
+    ...(version === undefined ? {} : { version }),
     syncedAt: now.toISOString(),
     files: payload.files ?? previousRecord?.files ?? {},
     ...resolveChainField(payload.chain, previousRecord?.chain),
@@ -304,6 +324,27 @@ async function readCommit(root: string): Promise<string | undefined> {
     : undefined
 }
 
+/**
+ * Keeps the newer of the running release and the one already recorded, so an
+ * older binary syncing after a newer one cannot lower the mark and let a later
+ * run delete a rule the newer release installed. An unparseable side loses to
+ * a parseable one, and a recorded value survives an unreadable manifest.
+ */
+function newerVersion(
+  running: string | undefined,
+  recorded: string | undefined,
+): string | undefined {
+  if (running === undefined) return recorded
+  if (recorded === undefined) return running
+
+  const parsedRunning = parseVersion(running)
+  const parsedRecorded = parseVersion(recorded)
+  if (parsedRecorded === undefined) return running
+  if (parsedRunning === undefined) return recorded
+
+  return compareVersions(parsedRecorded, parsedRunning) > 0 ? recorded : running
+}
+
 /**
  * A write naming no chain keeps the domain's previous one rather than dropping
  * it, since `writeStamp` and `writeChainStamp` each touch one half of a
@@ -365,6 +406,9 @@ function isDomainStamp(value: unknown): value is DomainStamp {
   if (value.commit !== undefined && typeof value.commit !== 'string') {
     return false
   }
+  if (value.version !== undefined && typeof value.version !== 'string') {
+    return false
+  }
   if (value.chain !== undefined && !isStringArray(value.chain)) return false
 
   return Object.values(value.files).every((hash) => typeof hash === 'string')

package/standards/plan.md

@@ -31,6 +31,7 @@ A plan works when a session holding none of the conversation that produced it ca
 - Which decisions are already settled, and which are still open?
 - For each open decision, what happens when nobody answers it?
 - What is likely to go wrong, and where does the work collide with something already in flight?
+- How is each outcome proven, and which input would break it?
 
 A plan failing these is non-conforming even when it satisfies every shape rule below.
 
@@ -53,10 +54,12 @@ The document opens with `# Feature: <short title>` and one paragraph stating wha
 | `## Summary`          | three to five one-line bullets: the goal, the deliverables, the trade-off | Always        |
 | `**Constraints:**`    | durable rules the work must respect                                       | When supplied |
 | `**Files to touch:**` | each file with a one-line reason                                          | Always        |
+| `**Verification:**`   | the test or command that proves each outcome                              | Always        |
 | `**Risks:**`          | conflicts, coupling, and the tricky spots                                 | Always        |
+| `**Review focus:**`   | the inputs or states that would break the change, for the reviewer        | Always        |
 | `**Questions:**`      | numbered open decisions, each with a suggestion and an answer slot        | Always        |
 
-- Write each marker as the table gives it. `Summary` opens the prose a reader scans, so it takes an H2, and the four that follow are labels over lists rather than sections of prose.
+- Write each marker as the table gives it. `Summary` opens the prose a reader scans, so it takes an H2, and the six that follow are labels over lists rather than sections of prose.
 - A section written in the other spelling is still that section. `## Risks` and `**Risks:**` name one thing, and a plan carrying either has stated its risks, so neither reads as an omission. Write the table's form in a new plan and leave an existing plan's spelling alone.
 - Both spellings break a depth run, so `canon markdown audit` reads either as the seam it is and reports a plan for a section that genuinely runs long rather than for its whole body. The markdown standard states the rule.
 - Write `None identified.` under a required section with nothing to report rather than dropping the marker. A dropped section and an unconsidered one read identically.
@@ -87,11 +90,23 @@ A dead constraint fails silently in the expensive direction. A session honoring
 
 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.
 
+### Verification
+
+- Name, for each outcome, the test or the command that proves it, as one bullet leading with the outcome and ending on the command in backticks.
+- Write a command a later session can run as given, from the project root. A description of what would be checked leaves the executing session to invent the check.
+- Name the visual check where no test reaches, and say it is visual, so a reader can tell a proof from a look.
+
 ### Risks
 
 - Name the collision rather than the category. A risk a reader cannot act on is padding.
 - Where the work establishes a resource with more than one consumer, list the consumers and mark each one read or write. A policy stated over that resource has to hold for the writers and not only for the consumer that prompted it.
 
+### Review focus
+
+- Name each input or state that would break the change if the implementation got it wrong, one bullet each, with what the change must do there.
+- Write it for the reviewer rather than the builder. The session writing the plan understood the risk before any diff existed, and this section is where that understanding reaches the review pass.
+- Keep it apart from `**Risks:**`. A risk is something the work might collide with, and a focus item is something the finished diff must be shown to handle, so a reviewer confirms the second and the executing session plans around the first.
+
 ## The suggested-and-answer contract
 
 Every question carries a `- Suggested:` line and an empty `- Answer:` slot below it.
@@ -165,10 +180,18 @@ This contract inverts the one an intake folder keeps, where an empty slot means
 
 - `<path/to/file>`: <reason>
 
+**Verification:**
+
+- <outcome>: `<test or command that proves it>`
+
 **Risks:**
 
 - <conflict, coupling, or tricky spot>
 
+**Review focus:**
+
+- <input or state that would break the change>: <what the change must do there>
+
 **Questions:**
 
 1. <question>

package/src/context/narration.ts

@@ -1,99 +0,0 @@
-import { existsSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
-import { resolve } from 'node:path'
-
-/**
- * The headings a rule carries to publish the two sets.
- *
- * Discovery is anchored on these rather than on a filename for the reason
- * `src/comments/vocabulary.ts` anchors its own: governance rules are numbered,
- * and a renumber would empty the sets while the check kept reporting clean.
- * Both open with `Narration` so neither loader can read the other's list.
- */
-export const PRONOUN_HEADING = '## Narration pronouns'
-export const VERB_HEADING = '## Narration verbs'
-
-/**
- * Roots searched in order. The installed copy wins over the toolkit source, so
- * a target project measures against the rule it actually has rather than one
- * only the toolkit carries.
- */
-const RULE_ROOTS = ['.claude/rules', 'governance/rules']
-
-export interface NarrationTerms {
-  /** Back-reference openings, matched at the start of a bullet and cased. */
-  readonly pronouns: readonly string[]
-  /** Past-tense verbs, matched anywhere in the bullet and uncased. */
-  readonly verbs: readonly string[]
-}
-
-/**
- * Absent is a distinct state from empty, the split the comment vocabulary
- * draws for the same reason: a scan with no terms finds nothing, and reporting
- * that as zero findings claims the corpus is clean when nothing was looked for.
- */
-export type Narration =
-  | ({ readonly kind: 'loaded'; readonly source: string } & NarrationTerms)
-  | { readonly kind: 'absent' }
-
-/** Pulls the backticked terms out of the bullets under one heading. */
-export function parseTerms(
-  markdown: string,
-  heading: string,
-): string[] | undefined {
-  const lines = markdown.split('\n')
-  const start = lines.findIndex((line) => line.trim() === heading)
-  if (start === -1) return undefined
-
-  const terms: string[] = []
-
-  for (const line of lines.slice(start + 1)) {
-    if (line.startsWith('## ')) break
-    for (const match of line.matchAll(/`([^`]+)`/g)) {
-      const term = match[1].trim()
-      if (term && !terms.includes(term)) terms.push(term)
-    }
-  }
-
-  return terms
-}
-
-/**
- * Finds the rule publishing both sets under `root`.
- *
- * Both come from one file rather than from whichever rule carries each. A
- * pronoun set and a verb set are halves of one signal, and pairing them across
- * files would let a renumber recombine them into a signal nobody wrote.
- */
-export async function loadNarration(root: string): Promise<Narration> {
-  for (const ruleRoot of RULE_ROOTS) {
-    const dir = resolve(root, ruleRoot)
-    if (!existsSync(dir)) continue
-
-    const paths: string[] = []
-    for await (const rel of new Bun.Glob('**/*.md').scan({
-      cwd: dir,
-      onlyFiles: true,
-    })) {
-      paths.push(rel)
-    }
-    paths.sort()
-
-    for (const rel of paths) {
-      const source = await readFile(resolve(dir, rel), 'utf8')
-      const pronouns = parseTerms(source, PRONOUN_HEADING)
-      const verbs = parseTerms(source, VERB_HEADING)
-
-      if (pronouns && verbs && pronouns.length > 0 && verbs.length > 0) {
-        return {
-          kind: 'loaded',
-          source: `${ruleRoot}/${rel}`,
-          pronouns,
-          verbs,
-        }
-      }
-    }
-  }
-
-  return { kind: 'absent' }
-}