@erclx/canon 5.75.0 → 5.77.0

package/claude/skills/role-orchestrator/scripts/poll.ts

@@ -2,10 +2,10 @@
 //
 // Run as `bun poll.ts`. The pure pieces are exported so a test drives the code
 // a loop runs, and `main` runs only when this file is the entry point.
-import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
-import { baseBranch, baseRef, mainRoot, run } from './repo'
+import { baseBranch, baseRef, mainRoot, mapPool, run, runAsync } from './repo'
 
 interface Comment {
   body?: null | string
@@ -499,11 +499,11 @@ const parseJson = (text: string): unknown => {
  * line that does not parse both return null, so neither reads as a thread with
  * nothing on it.
  */
-const readRows = (
+const readRows = async (
   path: string,
   fields: string,
-): null | Record<string, unknown>[] => {
-  const read = run('gh', [
+): Promise<null | Record<string, unknown>[]> => {
+  const read = await runAsync('gh', [
     'api',
     '--paginate',
     `repos/{owner}/{repo}/${path}`,
@@ -546,15 +546,14 @@ export const toComment = (row: Record<string, unknown>): Comment => ({
  * Two reads feed one payload, so either failing makes the pull request
  * unreadable rather than a thread missing half its rows.
  */
-const readPayload = (number: string): null | Payload => {
-  const reviews = readRows(
-    `pulls/${number}/reviews?per_page=100`,
-    'body, commit_id, submitted_at',
-  )
-  const comments = readRows(
-    `issues/${number}/comments?per_page=100`,
-    'body, created_at',
-  )
+const readPayload = async (number: string): Promise<null | Payload> => {
+  const [reviews, comments] = await Promise.all([
+    readRows(
+      `pulls/${number}/reviews?per_page=100`,
+      'body, commit_id, submitted_at',
+    ),
+    readRows(`issues/${number}/comments?per_page=100`, 'body, created_at'),
+  ])
   if (reviews === null || comments === null) return null
 
   return { comments: comments.map(toComment), reviews: reviews.map(toReview) }
@@ -562,14 +561,17 @@ const readPayload = (number: string): null | Payload => {
 
 type Snapshot = { baseline: Baseline } | { row: Row }
 
+/** What one pull request's reads produced, before the baseline is consulted. */
+type Collected = { number: string; reason: string } | { row: Row }
+
 const nowSeconds = (): number => Math.floor(Date.now() / 1000)
 
-const readHead = (number: string): string => {
+const readHead = async (number: string): Promise<string> => {
   // The tip is the authority for the head, not the pull request object, which
   // lags the ref by up to a minute after a push. The object's head is the
   // fallback for a target on an older binary with no `pr head` verb.
   const record = parseJson(
-    run('canon', ['pr', 'head', number, '--json']).stdout,
+    (await runAsync('canon', ['pr', 'head', number, '--json'])).stdout,
   )
   const tip =
     typeof record === 'object' && record !== null
@@ -578,7 +580,7 @@ const readHead = (number: string): string => {
 
   if (typeof tip === 'string' && tip !== '') return tip
 
-  const pull = run('gh', [
+  const pull = await runAsync('gh', [
     'api',
     `repos/{owner}/{repo}/pulls/${number}`,
     '--jq',
@@ -594,16 +596,26 @@ const readHead = (number: string): string => {
  * against the base this machine has. It exits non-zero on a ref it cannot
  * resolve as well as on a real conflict, so both sides are checked first.
  */
-const readMerges = (number: string, head: string, ref: string): string => {
-  run('git', ['fetch', '-q', 'origin', `pull/${number}/head`])
-  if (
-    !run('git', ['cat-file', '-e', `${head}^{commit}`]).isOk ||
-    !run('git', ['rev-parse', '--verify', '-q', ref]).isOk
-  ) {
-    return 'unknown'
-  }
+const readMerges = async (
+  number: string,
+  head: string,
+  ref: string,
+): Promise<string> => {
+  // Concurrent fetches would each rewrite FETCH_HEAD, which nothing here reads.
+  await runAsync('git', [
+    'fetch',
+    '-q',
+    '--no-write-fetch-head',
+    'origin',
+    `pull/${number}/head`,
+  ])
+  const [commit, base] = await Promise.all([
+    runAsync('git', ['cat-file', '-e', `${head}^{commit}`]),
+    runAsync('git', ['rev-parse', '--verify', '-q', ref]),
+  ])
+  if (!commit.isOk || !base.isOk) return 'unknown'
 
-  return run('git', ['merge-tree', '--write-tree', ref, head]).isOk
+  return (await runAsync('git', ['merge-tree', '--write-tree', ref, head])).isOk
     ? 'clean'
     : 'conflict'
 }
@@ -622,11 +634,20 @@ const nonEmptyLines = (output: string): string[] =>
  * the base to either one is a change under the branch. A head or base that does
  * not resolve, which a fork or a deleted head leaves, reads as null.
  */
-const readWritten = (head: string, ref: string): null | Written => {
-  const forkPoint = run('git', ['merge-base', ref, head])
+const readWritten = async (
+  head: string,
+  ref: string,
+): Promise<null | Written> => {
+  const forkPoint = await runAsync('git', ['merge-base', ref, head])
   if (!forkPoint.isOk) return null
   const point = forkPoint.stdout.trim()
-  const diff = run('git', ['diff', '--name-only', '--no-renames', point, head])
+  const diff = await runAsync('git', [
+    'diff',
+    '--name-only',
+    '--no-renames',
+    point,
+    head,
+  ])
   if (!diff.isOk) return null
 
   return { forkPoint: point, paths: nonEmptyLines(diff.stdout) }
@@ -638,14 +659,14 @@ const readWritten = (head: string, ref: string): null | Written => {
  * net diff rather than the log is read, so a change the base made and then
  * reverted moves nothing.
  */
-const readStale = (
+const readStale = async (
   written: null | Written,
   ref: string,
-): { files: string[]; stale: Staleness } => {
+): Promise<{ files: string[]; stale: Staleness }> => {
   if (written === null) return { files: [], stale: 'unknown' }
   if (written.paths.length === 0) return { files: [], stale: 'fresh' }
 
-  const moved = run('git', [
+  const moved = await runAsync('git', [
     '--literal-pathspecs',
     'diff',
     '--name-only',
@@ -754,22 +775,23 @@ const readOverlap = (first: string, second: string): null | string[] => {
   return [...new Set(lines.slice(1))]
 }
 
-const buildRow = (
+const buildRow = async (
   number: string,
   payload: Payload,
   head: string,
   ref: string,
-): Row => {
+): Promise<Row> => {
   const now = nowSeconds()
   const replies = replyState(payload.comments ?? [])
   const unmatched = unmatchedState(payload.comments ?? [])
-  const record = parseJson(
-    run('canon', ['pr', 'review-state', number, '--json']).stdout,
-  )
+  const [state, merges] = await Promise.all([
+    runAsync('canon', ['pr', 'review-state', number, '--json']),
+    readMerges(number, head, ref),
+  ])
+  const record = parseJson(state.stdout)
   const scope = scopeFromVerb(record, now) ?? scopeFallback(payload, now)
-  const merges = readMerges(number, head, ref)
-  const written = merges === 'unknown' ? null : readWritten(head, ref)
-  const stale = readStale(written, ref)
+  const written = merges === 'unknown' ? null : await readWritten(head, ref)
+  const stale = await readStale(written, ref)
 
   return {
     age: scope.age,
@@ -845,7 +867,7 @@ export const standingFromLift = (
  * after it would leave a stored reading claiming clear. The lift verb's reading
  * comes first, and the read below stays as the fallback for an older binary.
  */
-const check = (number: string): number => {
+const check = async (number: string): Promise<number> => {
   // The verb exits 1 on any refused gate and still prints its record, so the
   // exit says nothing about whether the standing was read.
   const lifted = standingFromLift(
@@ -858,7 +880,7 @@ const check = (number: string): number => {
   }
   const ref = baseRef()
   run('git', ['fetch', '-q', 'origin', baseBranch(ref)])
-  const head = readHead(number)
+  const head = await readHead(number)
   if (head === '') {
     console.error(
       `poll: #${number} returned no head, so nothing is known about it`,
@@ -866,43 +888,57 @@ const check = (number: string): number => {
 
     return 1
   }
-  const merges = readMerges(number, head, ref)
-  const written = merges === 'unknown' ? null : readWritten(head, ref)
+  const merges = await readMerges(number, head, ref)
+  const written = merges === 'unknown' ? null : await readWritten(head, ref)
   console.log(
     standingLine({
       head,
       merges,
       number,
-      stale: readStale(written, ref).stale,
+      stale: (await readStale(written, ref)).stale,
     }),
   )
 
   return 0
 }
 
-const main = (args: string[]): number => {
-  const root = mainRoot()
-  if (root === null) {
-    console.error('poll: not a git repository, so nothing is classified')
+/** Pull requests read at once, which keeps a wave under GitHub's burst limit. */
+const READ_POOL = 4
 
-    return 1
-  }
+interface PollRun {
+  /** Lines for stdout, the state lines and the closing `No movement.` */
+  readonly out: string[]
+  /** `poll:` lines for stderr, each a read that failed. */
+  readonly err: string[]
+  readonly isChanged: boolean
+  readonly status: number
+}
+
+/**
+ * One classification pass. It writes the baseline only when `record` holds,
+ * so a run made to time or inspect the board leaves the next run's view intact.
+ */
+const pollOnce = async (
+  root: string,
+  { record }: { record: boolean },
+): Promise<PollRun> => {
+  const out: string[] = []
+  const err: string[] = []
 
   // The baseline is per-machine mutable state, so it stays in gitignored
   // scratch even though the script is tracked.
-  if (args[0] === '--check') return check(args[1] ?? '')
   const stateDir = join(root, '.canon', 'tmp', 'pr', 'poll')
-  mkdirSync(stateDir, { recursive: true })
   const statePath = join(stateDir, 'baseline.txt')
-  appendFileSync(statePath, '')
+  const previous = (
+    existsSync(statePath) ? readFileSync(statePath, 'utf8') : ''
+  )
+    .split('\n')
+    .filter((line) => line !== '')
+    .map(parseBaseline)
 
   const ref = baseRef()
   const base = baseBranch(ref)
   const known = new Map<string, Baseline>()
-  const previous = readFileSync(statePath, 'utf8')
-    .split('\n')
-    .filter((line) => line !== '')
-    .map(parseBaseline)
   for (const entry of previous) {
     if (!known.has(entry.number)) known.set(entry.number, entry)
   }
@@ -920,47 +956,50 @@ const main = (args: string[]): number => {
     '.[].number',
   ])
   if (!listed.isOk) {
-    console.error('poll: the open pull request list could not be read')
-    console.error(
+    err.push(
+      'poll: the open pull request list could not be read',
       'poll: nothing is classified this run and the baseline is unchanged',
     )
 
-    return 1
+    return { err, isChanged: false, out, status: 1 }
   }
 
-  const snapshots: Snapshot[] = []
-  for (const number of listed.stdout.split(/\s+/).filter((n) => n !== '')) {
-    // A read that failed and a pull request with no reviews both arrive as an
-    // empty result, so each read returns null on failure and the payload gives
-    // the failure a single place to surface.
-    const payload = readPayload(number)
-    const old = known.get(number)
-    const unreadable = (reason: string): void => {
-      if (old === undefined) {
-        console.error(
-          `poll: #${number} ${reason}, and it has no last known state, so it goes unclassified`,
-        )
-
-        return
-      }
-      console.error(
-        `poll: #${number} ${reason}, so it keeps its last known state and goes unclassified`,
-      )
-      snapshots.push({ baseline: carryForward(old) })
-    }
+  const numbers = listed.stdout.split(/\s+/).filter((n) => n !== '')
+  const collected = await mapPool(
+    numbers,
+    READ_POOL,
+    async (number): Promise<Collected> => {
+      // A read that failed and a pull request with no reviews both arrive as an
+      // empty result, so each read returns null on failure and the payload gives
+      // the failure a single place to surface.
+      const [payload, head] = await Promise.all([
+        readPayload(number),
+        readHead(number),
+      ])
+      if (payload === null) return { number, reason: 'could not be read' }
+      if (head === '') return { number, reason: 'returned no head' }
+
+      return { row: await buildRow(number, payload, head, ref) }
+    },
+  )
 
-    if (payload === null) {
-      unreadable('could not be read')
+  const snapshots: Snapshot[] = []
+  for (const item of collected) {
+    if ('row' in item) {
+      snapshots.push({ row: item.row })
       continue
     }
-
-    const head = readHead(number)
-    if (head === '') {
-      unreadable('returned no head')
+    const old = known.get(item.number)
+    if (old === undefined) {
+      err.push(
+        `poll: #${item.number} ${item.reason}, and it has no last known state, so it goes unclassified`,
+      )
       continue
     }
-
-    snapshots.push({ row: buildRow(number, payload, head, ref) })
+    err.push(
+      `poll: #${item.number} ${item.reason}, so it keeps its last known state and goes unclassified`,
+    )
+    snapshots.push({ baseline: carryForward(old) })
   }
 
   const rows = snapshots.flatMap((snapshot) =>
@@ -996,7 +1035,7 @@ const main = (args: string[]): number => {
       base,
       countSince: countSince(row.number),
     })
-    for (const line of result.lines) console.log(line)
+    out.push(...result.lines)
     if (result.isChanged) isChanged = true
     final.push(
       formatBaseline({
@@ -1007,20 +1046,96 @@ const main = (args: string[]): number => {
   }
 
   for (const line of overlapLines(overlaps, known)) {
-    console.log(line)
+    out.push(line)
     isChanged = true
   }
 
   for (const entry of previous) {
     if (seen.has(entry.number)) continue
-    console.log(`GONE      #${entry.number} merged or closed`)
+    out.push(`GONE      #${entry.number} merged or closed`)
     isChanged = true
   }
 
-  if (!isChanged) console.log('No movement.')
-  writeFileSync(statePath, final.map((line) => `${line}\n`).join(''))
+  if (record) {
+    mkdirSync(stateDir, { recursive: true })
+    writeFileSync(statePath, final.map((line) => `${line}\n`).join(''))
+  }
 
-  return 0
+  return { err, isChanged, out, status: 0 }
+}
+
+/** The gap between reads in a wait, the interval the scheduled prompt used. */
+const DEFAULT_EVERY_S = 180
+
+/** A flag's value in seconds, null when absent and NaN when not positive. */
+const seconds = (args: string[], flag: string): null | number => {
+  const at = args.indexOf(flag)
+  if (at === -1) return null
+  const value = Number(args[at + 1])
+
+  return Number.isFinite(value) && value > 0 ? value : Number.NaN
+}
+
+const print = (result: PollRun): void => {
+  for (const line of result.err) console.error(line)
+  for (const line of result.out) console.log(line)
+}
+
+const main = async (args: string[]): Promise<number> => {
+  const root = mainRoot()
+  if (root === null) {
+    console.error('poll: not a git repository, so nothing is classified')
+
+    return 1
+  }
+
+  if (args[0] === '--check') return check(args[1] ?? '')
+
+  const record = !args.includes('--no-record')
+  const wait = seconds(args, '--wait')
+  const every = seconds(args, '--every') ?? DEFAULT_EVERY_S
+  if (Number.isNaN(wait) || Number.isNaN(every)) {
+    console.error('poll: --wait and --every take a positive number of seconds')
+
+    return 1
+  }
+
+  if (wait === null) {
+    const result = await pollOnce(root, { record })
+    print(result)
+    if (result.status === 0 && !result.isChanged) console.log('No movement.')
+
+    return result.status
+  }
+
+  // Only movement ends the wait early. A failed read, of one pull request or of
+  // the whole open list, holds to the cap, since one failing every run would end
+  // each wait at once and the re-arm would spin. Its lines ride with the exit,
+  // and a list still unreadable at the cap exits 1.
+  const deadline = Date.now() + wait * 1000
+  const failed = new Set<string>()
+  for (;;) {
+    const result = await pollOnce(root, { record })
+    for (const line of result.err) failed.add(line)
+    if (result.status === 0 && result.isChanged) {
+      print({ ...result, err: [...failed] })
+
+      return 0
+    }
+    // A quiet wait never ends before its cap, whatever `--every` says, since an
+    // early exit is a re-arm the orchestrator spends a turn on.
+    const left = deadline - Date.now()
+    if (left <= 0) {
+      for (const line of failed) console.error(line)
+      if (result.status !== 0) return result.status
+      console.log('No movement.')
+
+      return 0
+    }
+    await new Promise((resolve) =>
+      setTimeout(resolve, Math.min(every * 1000, left)),
+    )
+  }
 }
 
-if (import.meta.main) process.exitCode = main(process.argv.slice(2))
+if (import.meta.main) process.exitCode = await main(process.argv.slice(2))

package/claude/skills/role-orchestrator/scripts/repo.ts

@@ -1,23 +1,75 @@
 // Shared by the poll and the watch. Imports are `node:` builtins only, since
 // the plugin ships `claude/` alone and a cached plugin root carries no
 // `node_modules`.
-import { spawnSync } from 'node:child_process'
+import { spawn, spawnSync } from 'node:child_process'
 
 export interface RunResult {
   isOk: boolean
   stdout: string
 }
 
+/**
+ * How long one command may run before it is killed and read as failed. A
+ * background wait has no caller to cut a hung `git fetch` or `gh api` off, so
+ * without this bound one stalled read would hold the wait past its cap.
+ */
+export const RUN_TIMEOUT_MS = 60_000
+
 /** Runs a command to completion. A command that cannot start reads as failed. */
 export const run = (command: string, args: string[]): RunResult => {
   const result = spawnSync(command, args, {
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: RUN_TIMEOUT_MS,
   })
 
   return { isOk: result.status === 0, stdout: result.stdout ?? '' }
 }
 
+/** `run` without blocking, so reads for several pull requests overlap. */
+export const runAsync = (
+  command: string,
+  args: string[],
+  timeoutMs = RUN_TIMEOUT_MS,
+): Promise<RunResult> =>
+  new Promise((resolve) => {
+    const child = spawn(command, args, {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: timeoutMs,
+    })
+    let stdout = ''
+    child.stdout.setEncoding('utf8')
+    child.stdout.on('data', (chunk: string) => {
+      stdout += chunk
+    })
+    child.on('error', () => resolve({ isOk: false, stdout: '' }))
+    child.on('close', (status) => resolve({ isOk: status === 0, stdout }))
+  })
+
+/**
+ * Maps every item with at most `limit` in flight, keeping results in input
+ * order, so output stays stable however the reads finish.
+ */
+export const mapPool = async <T, R>(
+  items: readonly T[],
+  limit: number,
+  map: (item: T) => Promise<R>,
+): Promise<R[]> => {
+  const results: R[] = Array.from({ length: items.length })
+  let next = 0
+  const worker = async (): Promise<void> => {
+    while (next < items.length) {
+      const index = next++
+      results[index] = await map(items[index] as T)
+    }
+  }
+  await Promise.all(
+    Array.from({ length: Math.min(limit, items.length) }, worker),
+  )
+
+  return results
+}
+
 /**
  * The main worktree root rather than the current one, so a script started from
  * a linked worktree reads the same repository and state as one started from

package/docs/agents/migrate.md

@@ -21,7 +21,7 @@ kind: reference
 | `record-layout`    | Review receipts, memory archives, feedback, renders, picks, evidence, and the design board into their current folders |
 | `session-defaults` | The seeded session defaults into an existing `.claude/settings.json`, listed below the table                          |
 
-`record-tree` follows citations in `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`. `session-defaults` denies `Agent`, `Task`, and both merge commands, turns auto memory off, and wires an installed `plan-guard.sh` into the PreToolUse hooks. The bullets below add detail per verb.
+`record-tree` follows citations in `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`. `session-defaults` denies subagents and both merge commands, allows the two lease push forms workers run, turns auto memory off, and wires an installed `plan-guard.sh`. The bullets below add detail per verb.
 
 - `skill-names` takes no `--scope`, and skips the changelog, eval transcripts, replay fixtures, and the pointer each renamed `draft-` skill leaves at its old name
 - `surface-roots` moves `context/`, `wireframes/`, `ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`, and the stamp folder, and leaves `rules/`, `skills/`, `hooks/`, and `settings.json` in place
@@ -56,15 +56,15 @@ Three markers keep an old spelling on a line. Each also covers the nearest non-b
 
 ## Refusals
 
-| Verb               | Refuses when                                                                                              |
-| ------------------ | --------------------------------------------------------------------------------------------------------- |
-| `records`          | The project does not ignore `.canon/`. Run `canon tooling sync --write` first.                            |
-| `records`          | A record folder already exists at the destination                                                         |
-| `surface-roots`    | Any destination already exists under `canon/`, refusing the whole plan                                    |
-| `scratch-evidence` | A destination is occupied                                                                                 |
-| `record-layout`    | A destination already exists, each move refused on its own                                                |
-| `rule-layout`      | A destination holds different bytes. Neither file is touched and other moves apply.                       |
-| `session-defaults` | The settings file is not valid JSON, or `permissions`, `deny`, `hooks`, or `PreToolUse` has another shape |
+| Verb               | Refuses when                                                                                                       |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| `records`          | The project does not ignore `.canon/`. Run `canon tooling sync --write` first.                                     |
+| `records`          | A record folder already exists at the destination                                                                  |
+| `surface-roots`    | Any destination already exists under `canon/`, refusing the whole plan                                             |
+| `scratch-evidence` | A destination is occupied                                                                                          |
+| `record-layout`    | A destination already exists, each move refused on its own                                                         |
+| `rule-layout`      | A destination holds different bytes. Neither file is touched and other moves apply.                                |
+| `session-defaults` | The settings file is not valid JSON, or `permissions`, `deny`, `allow`, `hooks`, or `PreToolUse` has another shape |
 
 A `rule-layout` destination holding the same bytes marks a duplicate, which `--write` deletes.
 

package/docs/agents/targets.md

@@ -9,7 +9,9 @@ kind: reference
 `canon targets list` reports the projects this toolkit installed into. `canon targets pulls [paths…]` reports each target's open pull requests, or every target's when none is named. Both take `--json`. Read the record's fields, since a wrapping shell function can flatten the exit.
 
 - `list` takes `--sweep <path…>`, `--depth <n>` (default 4), and `--record`, which seeds the index from swept stamps and needs `--sweep`
-- Each stamping sync records its target in `$XDG_STATE_HOME/canon/targets.json`, and no row is removed
+- Each stamping sync records its target in `$XDG_STATE_HOME/canon/targets.json`, except a folder under the OS temp folder, the state folder, `~/.claude/jobs/`, or any `.canon/tmp/`
+- Every write drops a row whose folder is gone or sits under one of those, and `list` leaves the same rows out. A target on an unmounted drive drops until its next sync records it again.
+- `--record` counts a swept checkout under one of those folders as skipped, not failed
 - A sweep finds installs the index never held
 
 `canon changelog` prints the releases a target has not seen, from the `CHANGELOG.md` the installed package ships. It reads no registry and needs no `gh`.

package/docs/migrations/by-verb.md

@@ -75,8 +75,8 @@ Replace a citation of a skill with no successor by hand, or delete the sentence.
 
 - `canvas` is now `canvas-board`. The sweep rewrites only `canon:canvas` and `skills/canvas`, so replace a bare mention by hand. <!-- canon-keep-retired -->
 - `draft-ready` is rewritten only as `canon:draft-ready` and `skills/draft-ready`, since bare it also describes a pull request, so replace a bare mention by hand. <!-- canon-keep-retired -->
-- `design-extract` and `sketch-design` are replaced by `canon:canvas-board`. <!-- canon-keep-retired -->
-- `review-branch`, `seed-sync`, `restate-plainly`, `bash-cli-script`, `canon-operator`, `canon-rollout`, and `canon-feedback-triage` have no successor <!-- canon-keep-retired -->
+- `design-extract` and `sketch-design` are replaced by `canon:canvas-board`, and `canon-feedback-triage` by `canon:issue-triage`. <!-- canon-keep-retired -->
+- `review-branch`, `seed-sync`, `restate-plainly`, `bash-cli-script`, `canon-operator`, and `canon-rollout` have no successor <!-- canon-keep-retired -->
 - `create-standard`, `markdown-propose`, `memory-review`, `project-commands`, `repo-metadata`, `ux-walkthrough`, and `plan-ready` have no successor <!-- canon-keep-retired -->
 
 The `memory` record kind left `canon records`, so `canon records validate memory` refuses as an unknown kind and `canon records migrate` is gone.
@@ -115,6 +115,10 @@ canon migrate session-defaults --json
 canon migrate session-defaults --write --json
 ```
 
-The verb only adds a key that is absent. A person who wants auto memory back sets it in their own `.claude/settings.local.json`.
+The verb only adds a key or entry that is absent, so a project migrated before an entry runs `--write` once more.
 
-The verb adds `Bash(canon pr merge:*)` and `Bash(gh pr merge:*)` so a session cannot merge. A project migrated before them runs `--write` once more, which also restores `Agent` and `Task` for a person who removed them to allow subagents, so remove them again after.
+- A person who wants auto memory back sets it in their own `.claude/settings.local.json`
+- `Bash(canon pr merge:*)` and `Bash(gh pr merge:*)` stop a session merging
+- A rerun restores `Agent` and `Task` for a person who removed them to allow subagents, so remove them again after
+- `git push --force-with-lease` and its `origin HEAD` form are allowed exactly, so a worker pushes after a rebase without waiting
+- Any other lease push still goes through auto mode's review, and `canon claude sync` warns while either entry is missing

package/docs/workflow/ai-workflow.md

@@ -41,7 +41,7 @@ See [target projects](../target/projects.md).
 
 Plan and build in session 1, then review and ship in a fresh session 2 when you want a cold reviewer on the diff.
 
-- For a pile of findings, invoke `canon:plan-intake`, and for a grown backlog `canon:backlog-triage`
+- For a pile of findings, invoke `canon:plan-intake`, for a grown backlog `canon:backlog-triage`, and for open GitHub issues `canon:issue-triage`
 - For an unmeasured state with live approaches, invoke `canon:plan-groundwork`
 - Invoke `canon:plan-feature`, implement, and run the `CLAUDE.md` commands until they pass
 - For UI changes, invoke `canon:ui-checklist`

package/docs/workflow/skill-map.md

@@ -22,6 +22,7 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 | `canon:plan-intake`        | The input is a pile of findings                    |
 | `canon:plan-intake-answer` | An intake folder holds unread slots                |
 | `canon:backlog-triage`     | The backlog needs pruning                          |
+| `canon:issue-triage`       | Open GitHub issues need measuring before planning  |
 | `canon:plan-groundwork`    | The state is unmeasured and approaches compete     |
 | `canon:decision-escalate`  | Open decisions turn on your preference             |
 | `canon:proposal-critique`  | A proposal needs questioning before it is built    |

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.75.0",
+  "version": "5.77.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
-    "canon": "./src/cli.ts"
+    "canon": "src/cli.ts"
   },
   "files": [
     "src",