@erclx/canon 4.118.0 → 4.120.0

package/src/sync/check.ts

@@ -4,6 +4,7 @@ import { execa } from 'execa'
 import { gitEnv } from '@/git-env'
 import { createDesignAdapter, DESIGN_INSTALL_DIR } from '@/design/adapter'
 import { createGovAdapter, rulesSourceDir } from '@/gov/adapter'
+import { successorResolver } from '@/gov/renames'
 import { loadGovStack, resolveMissingRules, resolveRules } from '@/gov/stacks'
 import { planSync, type ScanEntry, type SyncAdapter } from '@/sync/engine'
 import {
@@ -80,6 +81,7 @@ export interface StateCounts {
   readonly stranded: number
   readonly missing: number
   readonly retired: number
+  readonly renamed: number
 }
 
 export interface DomainReport {
@@ -316,6 +318,7 @@ export function countStates(entries: readonly ScanEntry[]): StateCounts {
     stranded: count(entries, 'stranded'),
     missing: count(entries, 'missing'),
     retired: count(entries, 'retired'),
+    renamed: count(entries, 'renamed'),
   }
 }
 
@@ -347,6 +350,8 @@ export function countStates(entries: readonly ScanEntry[]): StateCounts {
  *
  * `retired` counts, since a sync deletes it mechanically. A target's CI goes
  * red the day a release retires a rule it holds, and one sync clears it.
+ * `renamed` counts on the same grounds, since the sync that moves it is
+ * equally mechanical.
  */
 export function hasDrift(report: CheckReport): boolean {
   if (report.unmigrated.length > 0) return true
@@ -357,7 +362,8 @@ export function hasDrift(report: CheckReport): boolean {
         domain.counts.customized +
         domain.counts.drifted +
         domain.counts.stranded +
-        domain.counts.retired >
+        domain.counts.retired +
+        domain.counts.renamed >
       0,
   )
 }
@@ -488,8 +494,14 @@ export function parseNewSkills(paths: string): string[] {
  * chain a target consumed survives nowhere else. `installRules` copies each
  * rule into the subdirectory it was authored in, which is what makes the band
  * folders legible as evidence.
+ *
+ * `successorOf` adds the name a held rule was renamed to, which the next sync
+ * installs, so the fallback does not report it as new.
  */
-export function readInstalledRules(target: string): {
+export function readInstalledRules(
+  target: string,
+  successorOf?: (name: string) => string | undefined,
+): {
   held: Set<string>
   bands: Set<string>
 } {
@@ -506,7 +518,10 @@ export function readInstalledRules(target: string): {
     const posix = rel.split(sep).join('/')
     const boundary = posix.indexOf('/')
 
-    held.add(basename(posix, '.md'))
+    const name = basename(posix, '.md')
+    held.add(name)
+    const successor = successorOf?.(name)
+    if (successor !== undefined) held.add(successor)
     if (boundary > 0) bands.add(posix.slice(0, boundary))
   }
 
@@ -640,7 +655,7 @@ export async function readNewRules(
     'governance/rules/',
   ])
 
-  const { held, bands } = readInstalledRules(target)
+  const { held, bands } = readInstalledRules(target, successorResolver(root))
   return selectNewRules(paths, held, bands.union(baseBands(root)))
 }
 

package/src/sync/engine.ts

@@ -70,6 +70,11 @@ export type SyncChange =
  * sync deletes it. A stamped file the toolkit no longer installs to is
  * stranded, which is a relocation waiting on a decision.
  *
+ * `renamed` is the fourth sourceless state and the only one that installs.
+ * It is a retired file whose rule the adapter declares still ships under a
+ * new name, so the sync deletes the old file and copies the rule to the new
+ * one.
+ *
  * `missing` is the one state the walk cannot produce on its own, since the
  * walk only iterates files that exist. It comes from `collectMissing`
  * instead, an adapter naming an entitled file the target does not hold.
@@ -81,6 +86,7 @@ export type EntryState =
   | 'drifted'
   | 'orphaned'
   | 'retired'
+  | 'renamed'
   | 'stranded'
   | 'missing'
 
@@ -165,9 +171,20 @@ export interface SyncAdapter {
    * 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.
+   * holds, or a `renamed` one when `locateSuccessor` names where it ships
+   * now. Unset, the file stays `orphaned` and untouched.
    */
   readonly ownsInstalledRoot?: boolean
+  /**
+   * Where a sourceless file's rule ships now, when the toolkit declares it
+   * renamed rather than retired. Reached only on a root the adapter owns and
+   * never past the newer-install guard. Unset, or returning nothing, leaves
+   * the file `retired`.
+   */
+  locateSuccessor?(
+    file: InstalledFile,
+    target: string,
+  ): { readonly source: string; readonly dest: string } | undefined
   /** Defaults to applying. */
   readonly nonInteractive?: NonInteractivePolicy
   /** Runs on a completed sync, including one with no changes. */
@@ -224,6 +241,7 @@ export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
   const hashes = stampedHashes(stamp, adapter.stamp?.domain)
   const newerInstall = newerInstallingVersion(stamp, adapter.stamp?.domain)
   const walked = new Set<string>()
+  const pendingCopies = new Set<string>()
 
   for (const file of listInstalled(
     adapter.installedRoot(target),
@@ -243,16 +261,44 @@ export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
     if (source === undefined || !existsSync(source)) {
       if (adapter.ownsInstalledRoot !== true) {
         entries.push(misplacedOrphan(adapter, target, file))
-      } else if (newerInstall !== undefined) {
+        continue
+      }
+
+      if (newerInstall !== undefined) {
         entries.push(heldForNewerInstall(file, newerInstall))
-      } else {
+        continue
+      }
+
+      const successor = adapter.locateSuccessor?.(file, target)
+      if (successor === undefined) {
         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
       }
+
+      const destRel = relative(target, successor.dest)
+      entries.push({
+        state: 'renamed',
+        rel: file.rel,
+        notice: renamedNotice(file, destRel, attribute(hashes, file)),
+      })
+
+      // A second predecessor of one successor, or a successor the target
+      // already holds, still loses its old file but must not overwrite.
+      if (!existsSync(successor.dest) && !pendingCopies.has(successor.dest)) {
+        pendingCopies.add(successor.dest)
+        changes.push({
+          kind: 'copy',
+          source: successor.source,
+          dest: successor.dest,
+          rel: destRel,
+        })
+      }
+      changes.push({ kind: 'delete', dest: file.path, rel: file.rel })
       continue
     }
 
@@ -470,6 +516,8 @@ function report(adapter: SyncAdapter, plan: SyncPlan): void {
       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 === 'renamed')
+      logWarn(entry.notice ?? `${entry.rel} (renamed by the toolkit)`)
     else if (entry.state === 'stranded')
       logWarn(`${entry.rel} (installed here by an older toolkit, now moved)`)
     else if (entry.state === 'missing')
@@ -617,6 +665,22 @@ function newerInstallingVersion(
   return { stamped, running }
 }
 
+/**
+ * The new name gets the toolkit's source rather than the old file's content,
+ * so a local edit is dropped the way a retire drops one. With no stamp the
+ * edit cannot be proven either way, so the line hedges rather than asserts.
+ */
+function renamedNotice(
+  file: InstalledFile,
+  destRel: string,
+  state: EntryState,
+): string {
+  const base = `${file.rel} (renamed to ${destRel} by the toolkit, moving`
+  if (state === 'customized') return `${base}. Local edits were not carried.)`
+  if (state === 'drifted') return `${base}. Any local edits were not carried.)`
+  return `${base})`
+}
+
 function heldForNewerInstall(
   file: InstalledFile,
   versions: { readonly stamped: string; readonly running: string },

package/src/tasks/archive.ts

@@ -46,6 +46,7 @@ export const ARCHIVE_REFUSALS = [
   'ambiguous',
   'no-outcomes',
   'open-outcomes',
+  'earlier-slice',
   'bad-input',
 ] as const
 
@@ -235,12 +236,19 @@ export function readOutcomes(text: string): TaskOutcomes {
 
 /**
  * Reads the `Pull request:` line `git-pr` writes when a pull request opens.
- * The number is a bare `#NNN` the way `Issue:` is, since neither is a path and
- * a full URL would write the remote into a gitignored file.
+ * Each number is a bare `#NNN` the way `Issue:` is, since neither is a path and
+ * a full URL would write the remote into a gitignored file. A task shipped in
+ * slices lists one per slice, oldest first, so the line reads as a list. A line
+ * carrying anything besides that list reads as naming none, rather than as the
+ * numbers that happened to parse.
  */
-export function readPullRequest(text: string): number | undefined {
-  const match = /^Pull request:\s*#(\d+)\s*$/m.exec(text)
-  return match ? Number(match[1]) : undefined
+export function readPullRequest(text: string): readonly number[] {
+  const match = /^Pull request:[ \t]*(#\d+(?:[ \t]*,[ \t]*#\d+)*)[ \t]*$/m.exec(
+    text,
+  )
+  if (!match) return []
+
+  return match[1].split(',').map((entry) => Number(entry.trim().slice(1)))
 }
 
 /**
@@ -628,11 +636,13 @@ async function matchByPullRequest(
   const read = await Promise.all(
     stems.map(async (stem) => ({
       stem,
-      number: readPullRequest(await readFile(join(dir, `${stem}.md`), 'utf8')),
+      numbers: readPullRequest(await readFile(join(dir, `${stem}.md`), 'utf8')),
     })),
   )
 
-  return read.filter((entry) => entry.number === number).map(({ stem }) => stem)
+  return read
+    .filter((entry) => entry.numbers.includes(number))
+    .map(({ stem }) => stem)
 }
 
 /**
@@ -748,6 +758,17 @@ export async function archiveTask(
   const from = join(dir, `${stem}.md`)
   const text = await readFile(from, 'utf8')
 
+  // `docs-fold` ticks outcomes at ship time, before the merge, so an earlier
+  // slice merging after the last slice shipped would find every box ticked
+  // while the last slice is still open. Only the last number closes the task.
+  const last = readPullRequest(text).at(-1)
+  if (selector.kind === 'pull-request' && last !== selector.number) {
+    return refuse(
+      'earlier-slice',
+      `${stem} lists #${last} after #${selector.number}, so the task closes when #${last} merges.`,
+    )
+  }
+
   const { open, closed, cut } = readOutcomes(text)
 
   if (open.length > 0) {

package/src/tasks/record.ts

@@ -10,6 +10,7 @@ import {
   OUTCOME_PATTERN,
   planLine,
   readPlanTarget,
+  readPullRequest,
   tasksDir,
 } from '@/tasks/archive'
 
@@ -49,7 +50,7 @@ export type RecordSelector =
   | { readonly kind: 'stem'; readonly stem: string }
   | { readonly kind: 'plan'; readonly plan: string }
 
-export type LineAction = 'added' | 'corrected' | 'unchanged'
+export type LineAction = 'added' | 'appended' | 'corrected' | 'unchanged'
 
 export interface PullRequestRecorded {
   readonly ok: true
@@ -101,9 +102,10 @@ function planKey(reference: string): string {
 
 /**
  * Places the `Pull request:` line under the origin lines the task already
- * carries, and corrects the number in place when the line exists. A task with
- * no origin line takes it under the H1, which is the only other anchor the
- * board format guarantees.
+ * carries. A task shipped in slices lists every pull request, so a new number
+ * appends to an existing line rather than replacing it, and a line that does
+ * not read as a list is replaced whole. A task with no origin line takes it
+ * under the H1, which is the only other anchor the board format guarantees.
  */
 export function writePullRequestLine(
   text: string,
@@ -114,9 +116,14 @@ export function writePullRequestLine(
   const existing = lines.findIndex((entry) => entry.startsWith('Pull request:'))
 
   if (existing !== -1) {
-    if (lines[existing] === line) return { text, action: 'unchanged' }
-    lines[existing] = line
-    return { text: lines.join('\n'), action: 'corrected' }
+    const listed = readPullRequest(lines[existing])
+    if (listed.includes(number)) return { text, action: 'unchanged' }
+    if (listed.length === 0) {
+      lines[existing] = line
+      return { text: lines.join('\n'), action: 'corrected' }
+    }
+    lines[existing] = `${lines[existing].trimEnd()}, #${number}`
+    return { text: lines.join('\n'), action: 'appended' }
   }
 
   const origin = lastOriginLine(lines)
@@ -143,8 +150,8 @@ function lastOriginLine(lines: readonly string[]): number | undefined {
 }
 
 /**
- * Places the `Plan:` line right after the H1, mirroring
- * `writePullRequestLine`'s add/correct/unchanged shape. `Plan:` is the first
+ * Places the `Plan:` line right after the H1, and corrects the target in place
+ * when the line exists, since a task runs under one plan. `Plan:` is the first
  * origin line a task carries, so it anchors on the heading itself rather than
  * on the last origin line above it.
  */

package/src/tasks/validate.ts

@@ -1071,7 +1071,9 @@ async function checkCitedTask(
   const { open, closed } = readOutcomes(text)
   if (open.length > 0 || closed.length === 0) return nothing()
 
-  const pullRequest = readPullRequest(text)
+  // The last number is the newest slice, and an earlier one closed without
+  // merging never lands, so only the last says whether the work reached trunk.
+  const pullRequest = readPullRequest(text).at(-1)
   if (pullRequest === undefined) {
     return untestedRow(
       group,

package/standards/index.md

@@ -30,6 +30,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [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
+- [Skill requirement reference](skill-requirement.md): Shape and content rules for the REQUIREMENT.md beside a skill
 - [Claude skill reference](skill.md): Claude skill structure and authoring rules
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result
 - [Snippet reference](snippets.md): Snippet reference and authoring conventions

package/standards/skill-requirement.md

@@ -0,0 +1,72 @@
+---
+title: Skill requirement reference
+description: Shape and content rules for the REQUIREMENT.md beside a skill
+---
+
+# Skill requirement reference
+
+Applies to the `REQUIREMENT.md` beside each `SKILL.md`. It states what the skill is for, so a proposed change can be argued against something and the corpus can be read to decide whether a skill should exist at all.
+
+## Scope
+
+Governs `skills/<name>/REQUIREMENT.md`: why it exists, what it must answer, and its sections.
+
+Does not govern:
+
+- The skill folder, `SKILL.md`, and the rule that every skill carries a requirement: `skill.md`
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Punctuation, formatting, and word choice: `markdown.md`
+
+## What a working requirement looks like
+
+A requirement works when a proposed change to the skill can be settled by reading it alone, without re-deriving what the skill is for:
+
+- Does this change close a gap the file states?
+- Does a line already in the body trace to one of those gaps?
+- Does this behavior belong to this skill or to a sibling the file names?
+
+A requirement that leaves any of the three open is non-conforming regardless of whether it satisfies every shape rule below. The third question is what makes a requirement worth more than a restated description, because a boundary stated only in prose is never checked against the skill on the other side of it.
+
+## Purpose
+
+- Treat the file as the compressed statement of what the skill is for. A skill body is procedural by design, so its purpose sits spread across its steps, and a reader gets this file before opening the body whether or not the skill's scope is contested.
+- Read it before editing the skill. When a change closes no gap the requirement states, change the requirement first or drop the change.
+- Write the gaps from what the skill is for, then compare the body against them. A requirement derived from the body records the body's accidents as the requirement, and misinforms a reader who reads it in place of the body.
+
+## Content
+
+- State each gap as an observed failure, not an intent. "Without this skill a session invents its own filename" can be shown wrong. "This skill helps manage tasks" cannot fail, so it constrains nothing.
+- Trace everything under `## Must` to a stated gap. A `Must` with no gap behind it is the padding the file exists to prevent.
+- Keep it high level. A requirement that outgrows one file has stopped being a requirement, and `references/` already holds detail.
+- Use `name` and `description` frontmatter, matching `SKILL.md` so the pair is consistent.
+
+## Template
+
+```markdown
+---
+name: <skill-name>
+description: <one line, distinct from the SKILL.md description>
+---
+
+# <Skill name> requirement
+
+## Gap
+
+Without this skill, a session <observed failure>, <observed failure>.
+
+## Must
+
+- <behavior that closes a named gap>
+
+## Must not
+
+- <behavior that would be wrong even though it closes a gap>
+
+## Guards
+
+- <the refusal condition and its message>
+
+## Out of scope
+
+- <the adjacent thing this deliberately does not cover, and what covers it>
+```