@erclx/canon 5.49.0 → 5.51.0

package/src/commands/worktrees.ts

@@ -17,6 +17,14 @@ import {
   type WorktreeVerdict,
 } from '@/worktrees/reclaim'
 import { mainWorktreeRoot } from '@/git/worktree'
+import {
+  type Half,
+  type MemberOutcome,
+  type MemberRefusal,
+  type MembersRefusal,
+  type MembersReport,
+  retireMembers,
+} from '@/worktrees/members'
 import { machineListenerReader } from '@/listeners/machine'
 import { repairBareFlag } from '@/worktrees/bare-flag'
 import { type StopReport, stopListeners } from '@/worktrees/stop'
@@ -40,6 +48,31 @@ interface ReclaimCommandOptions {
   readonly json?: boolean
 }
 
+interface RetireMembersCommandOptions {
+  readonly pullRequest: string
+  readonly dryRun?: boolean
+  readonly json?: boolean
+}
+
+/**
+ * What the post-merge hook reads after an integrator merges. Every field it
+ * branches on is a number or a fixed word, and `members` sits last, for the
+ * reason `ReclaimRecord` states.
+ */
+export interface RetireMembersRecord {
+  readonly pullRequest: number
+  readonly reason: MembersRefusal | null
+  readonly detail: string | null
+  readonly dryRun: boolean
+  /** Members with a half deleted, or that a dry run would delete, and none kept or failed. */
+  readonly retired: number
+  /** Members with a half kept and none failed. */
+  readonly kept: number
+  /** Members with a half whose deletion failed. */
+  readonly failed: number
+  readonly members: readonly MemberOutcome[]
+}
+
 /**
  * What a caller reads instead of the frame.
  *
@@ -145,6 +178,59 @@ const CONDITIONS = [
   'keeps a directory rather than removing one.',
 ]
 
+const MEMBERS_REFUSALS: Record<MembersRefusal, string> = {
+  'gh-missing': 'gh is not on the path, so the pull request could not be read',
+  'gh-failed': 'the pull request read failed',
+  'sessions-unreadable': 'the session roster could not be read',
+  'sessions-unchecked':
+    'some session records come from another pid namespace and no socket answers for them',
+  'not-merged': 'the pull request has not merged',
+  'no-members': 'the body carries no "Fan-in members:" line',
+  'trunk-named': 'the line names the branch the pull request merged into',
+  'head-named': "the line names the integrator's own branch",
+  'open-pull-request': 'a named branch has an open pull request of its own',
+  'head-unreadable':
+    'refs/pull/<n>/head could not be fetched, or names another commit than the merged head',
+}
+
+const MEMBER_REFUSALS: Record<MemberRefusal, string> = {
+  'not-in-merged-head':
+    "its tip is not an ancestor of the integrator's merged head, so it holds work the merge did not carry",
+  'remote-unreadable': 'origin could not be read for this branch',
+  'worktree-kept':
+    'its worktree was kept, and git refuses to delete a branch a worktree holds',
+  'main-worktree': 'it is checked out in the main worktree',
+  'current-worktree': 'its worktree is the one this command runs in',
+  'detached-head': 'its worktree has a detached HEAD',
+  'uncommitted-changes': 'its worktree holds uncommitted work',
+  'unreadable-worktree': 'its worktree could not be read',
+  'held-by-session': 'a live session holds its worktree',
+}
+
+const RETIRE_CONDITIONS = [
+  'Reads the "Fan-in members:" line of a merged integrator pull request,',
+  "whose backticked branches are the members, and deletes each one's",
+  'origin branch, worktree, and local branch. Nothing outside that line',
+  'is read.',
+  '',
+  "A member half is merged when its tip is an ancestor of the integrator's",
+  'merged head, fetched from refs/pull/<n>/head, rather than of the trunk,',
+  'which a squash merge never makes it. Origin and local are judged apart,',
+  'so an unpushed commit keeps the local branch and a commit pushed after',
+  'the merge keeps the origin branch. The worktree takes the same reading',
+  '`canon worktrees list` gives, with the members counted as merged.',
+  '',
+  'These refuse the whole run, and nothing is deleted:',
+  ...Object.entries(MEMBERS_REFUSALS).map(
+    ([reason, meaning]) => `  ${reason.padEnd(22)}${meaning}`,
+  ),
+  '',
+  'These keep one half of one member, named in its "reasons":',
+  ...Object.entries(MEMBER_REFUSALS).map(
+    ([reason, meaning]) => `  ${reason.padEnd(22)}${meaning}`,
+  ),
+]
+
 export function register(program: Command): void {
   const worktrees = program
     .command('worktrees')
@@ -240,6 +326,42 @@ export function register(program: Command): void {
       process.exitCode = await runReclaim(opts)
     })
 
+  worktrees
+    .command('retire-members')
+    .description(
+      'Delete the fan-in members a merged integrator pull request names, unless --dry-run',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .requiredOption(
+      '--pull-request <number>',
+      'The merged integrator pull request',
+    )
+    .option('--dry-run', 'Report what would be deleted without deleting it')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  every member was retired or kept, or the body names none',
+        '  1  refused, or a deletion failed, with the reason on stderr',
+        '',
+        ...RETIRE_CONDITIONS,
+        '',
+        'The post-merge hook runs this once per merged pull request number,',
+        'and CANON_SKIP_RECLAIM turns it off there. Run it by hand for a',
+        'merge the hook missed.',
+        '',
+        'Examples:',
+        '  canon worktrees retire-members --pull-request 2570 --dry-run',
+        '  canon worktrees retire-members --pull-request 2570 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RetireMembersCommandOptions) => {
+      process.exitCode = await runRetireMembers(opts)
+    })
+
   worktrees
     .command('repair-bare-flag', { hidden: true })
     .description('Clear a core.bare flag that worktree entry left set')
@@ -563,3 +685,154 @@ export function describe(verdict: WorktreeVerdict): string {
     `  Reclaimable. Pull request #${verdict.pullRequest} merged it, ${tree}, and no session holds it.`,
   ].join('\n')
 }
+
+function halves(member: MemberOutcome): readonly Half[] {
+  return member.worktree === null
+    ? [member.origin, member.local]
+    : [member.origin, member.worktree, member.local]
+}
+
+/**
+ * Builds the record from the report, separate from the run so the counts are
+ * testable without a repository. A member already gone everywhere counts
+ * nowhere, so a run repeated by hand does not report a retirement it did not
+ * make.
+ */
+export function retireMembersRecord(
+  pullRequest: number,
+  dryRun: boolean,
+  report: MembersReport,
+): RetireMembersRecord {
+  if (report.kind === 'refused') {
+    return {
+      pullRequest,
+      reason: report.reason,
+      detail: report.detail,
+      dryRun,
+      retired: 0,
+      kept: 0,
+      failed: 0,
+      members: [],
+    }
+  }
+
+  const states = report.members.map((member) =>
+    halves(member).map((half) => half.state),
+  )
+  const failed = states.filter((each) => each.includes('failed')).length
+  const kept = states.filter(
+    (each) => !each.includes('failed') && each.includes('kept'),
+  ).length
+  const retired = states.filter(
+    (each) =>
+      !each.includes('failed') &&
+      !each.includes('kept') &&
+      each.some((state) => state === 'deleted' || state === 'would-delete'),
+  ).length
+
+  return {
+    pullRequest,
+    reason: null,
+    detail: null,
+    dryRun,
+    retired,
+    kept,
+    failed,
+    members: report.members,
+  }
+}
+
+/**
+ * A kept half is a refusal doing its job and a body naming no members is the
+ * ordinary merge, so neither fails the run.
+ */
+export function retireMembersExit(record: RetireMembersRecord): number {
+  if (record.reason !== null && record.reason !== 'no-members') return 1
+  return record.failed > 0 ? 1 : 0
+}
+
+function describeHalf(name: string, half: Half): string {
+  if (half.state === 'kept') {
+    const reasons = half.reasons.map((reason) => MEMBER_REFUSALS[reason])
+    return `  ${name}: kept, since ${reasons.join('; ')}.`
+  }
+  const state = half.state.replace('-', ' ')
+  return half.detail === null
+    ? `  ${name}: ${state}.`
+    : `  ${name}: ${state}. ${half.detail}`
+}
+
+async function runRetireMembers(
+  opts: RetireMembersCommandOptions,
+): Promise<number> {
+  const dryRun = opts.dryRun ?? false
+  const pullRequest = Number(opts.pullRequest)
+
+  intro(
+    dryRun
+      ? 'canon worktrees retire-members (dry-run)'
+      : 'canon worktrees retire-members',
+  )
+
+  if (!Number.isInteger(pullRequest) || pullRequest <= 0) {
+    logStep('Refused')
+    logWarn(
+      `--pull-request takes a pull request number, and "${opts.pullRequest}" is not one.`,
+    )
+    outro()
+    return 1
+  }
+
+  // The reading stays on the caller's directory, which is what refuses the
+  // worktree it stands in, and every write runs from the main root.
+  const report = await retireMembers(pullRequest, {
+    cwd: process.cwd(),
+    root: await mainWorktreeRoot(),
+    dryRun,
+  })
+  const record = retireMembersRecord(pullRequest, dryRun, report)
+
+  if (report.kind === 'refused') {
+    logStep(report.reason === 'no-members' ? 'Members' : 'Refused')
+    if (report.reason === 'no-members') logInfo(report.detail)
+    else {
+      logWarn(`Nothing was deleted: ${MEMBERS_REFUSALS[report.reason]}.`)
+      logInfo(report.detail)
+    }
+  } else {
+    logStep('Members')
+    pipeOutput(
+      report.members
+        .map((member) =>
+          [
+            member.branch,
+            describeHalf('origin', member.origin),
+            ...(member.worktree === null
+              ? []
+              : [
+                  describeHalf(
+                    `worktree ${member.worktree.path}`,
+                    member.worktree,
+                  ),
+                ]),
+            describeHalf('local', member.local),
+          ].join('\n'),
+        )
+        .join('\n'),
+    )
+    if (record.failed > 0) {
+      logWarn(
+        `${plural(record.failed, 'member')} could not be fully deleted. Read the reason above and clear it by hand.`,
+      )
+    }
+    if (dryRun) {
+      logWarn(
+        'Nothing was deleted. Run this again without --dry-run to delete.',
+      )
+    }
+  }
+
+  outro()
+  if (opts.json === true) process.stdout.write(`${JSON.stringify(record)}\n`)
+  return retireMembersExit(record)
+}

package/src/context/audit.ts

@@ -108,13 +108,14 @@ export const OTHER_FOLDERS = 'Other folders'
 export const SCRIPTS_HEADING = 'Scripts'
 
 /**
- * Whether an entry path is the development entry, being the flat entry, the
- * overview of a split one a target may still carry, or this repository's
- * `local-loop` entry. The standard exempts the
- * `Scripts` H3 for that entry alone, so the path is what tells.
+ * Whether an entry path is the development entry, being the flat entry or any
+ * entry directly under a `development/` folder, since a split folder names its
+ * scripts entry by project, as `local-loop` here and `local` in another. The
+ * standard exempts the `Scripts` H3 for that entry alone, so the path is what
+ * tells.
  */
 function isDevelopmentEntry(rel: string): boolean {
-  return /(?:^|\/)development(?:\/(?:overview|local-loop))?\.md$/.test(rel)
+  return /(?:^|\/)development(?:\/[^/]+)?\.md$/.test(rel)
 }
 
 /**

package/src/design/budget.ts

@@ -1,7 +1,7 @@
 import { canonicalHeading } from '@/design/parse'
 
 /**
- * The prose budget `claude/skills/canvas-board/references/design.md` sets for a design record, and the
+ * The prose budget `claude/skills/design-record/references/design.md` sets for a design record, and the
  * counter the `design` gate stage reads it through.
  *
  * The limits live here and in the standard, never in the stage, so the stage

package/src/design/components.ts

@@ -15,7 +15,7 @@
  * `buildDesignCss`'s `components` option, which is what widening that option
  * from a boolean to `boolean | readonly Component[]` bought.
  *
- * It does not live in `canon/DESIGN.md`. `claude/skills/canvas-board/references/design.md` keeps CSS class
+ * It does not live in `canon/DESIGN.md`. `claude/skills/design-record/references/design.md` keeps CSS class
  * names out of that record and says they live in code, which is here.
  */
 

package/src/design/document.ts

@@ -94,7 +94,7 @@ function borderRows(tokens: readonly BorderToken[]): string[][] {
  * and every reason behind them lives in the entry.
  */
 const LEAD = [
-  'Authoring guidance: `claude/skills/canvas-board/references/design.md`. Rendered from `src/design/tokens.ts` by `canon design regen`, so edit the module and never this file.',
+  'Authoring guidance: `claude/skills/design-record/references/design.md`. Rendered from `src/design/tokens.ts` by `canon design regen`, so edit the module and never this file.',
   'Why each value was chosen lives in `canon/context/features/design.md`.',
 ].join(' ')
 

package/src/design/regen.ts

@@ -16,7 +16,7 @@ import { NEUTRAL_TOKENS } from '@/design/neutral'
  * gate stage is what keeps silently out of it.
  */
 
-/** The rendered record, at the path `claude/skills/canvas-board/references/design.md` fixes for it. */
+/** The rendered record, at the path `claude/skills/design-record/references/design.md` fixes for it. */
 export const DESIGN_DOCUMENT = join('canon', 'DESIGN.md')
 
 /**

package/src/design/render.ts

@@ -105,7 +105,7 @@ interface Confidence {
 }
 
 /**
- * The columns the confidence ratio reads, fixed by `claude/skills/canvas-board/references/design.md`. The
+ * The columns the confidence ratio reads, fixed by `claude/skills/design-record/references/design.md`. The
  * first column of each table names its row, and `Multiplier` and `When used`
  * restate what the row already carries, so none of them is something a source
  * could anchor and none belongs in the denominator.

package/src/gate/hand-suite.ts

@@ -0,0 +1,52 @@
+/**
+ * Names the machine lock a gate holds while a stage's commands run, so the
+ * suite it spawns knows not to wait on its own parent.
+ */
+export const HELD_LOCK_VARIABLE = 'CANON_HELD_LOCK'
+
+/**
+ * The vitest invocation a hand-run lock decision reads.
+ */
+export interface VitestRun {
+  /** The CLI arguments after the vitest entry, as `process.argv.slice(2)`. */
+  readonly args: readonly string[]
+  readonly ci: boolean
+  readonly watch: boolean
+  /**
+   * The lock a parent gate already holds for this run, from `HELD_LOCK_VARIABLE`.
+   * A gate's own suite waiting on that lock would wait on its parent forever.
+   */
+  readonly heldLock: string | undefined
+}
+
+const SUBCOMMANDS = new Set(['run'])
+
+/** `-t` and its long forms filter by test name, which scopes the run. */
+function isNameFilter(arg: string): boolean {
+  return (
+    arg === '-t' ||
+    arg.startsWith('-t=') ||
+    arg === '--testNamePattern' ||
+    arg.startsWith('--testNamePattern=') ||
+    arg === '--test-name-pattern' ||
+    arg.startsWith('--test-name-pattern=')
+  )
+}
+
+/**
+ * Whether a hand-run vitest invocation runs the whole suite and so queues on
+ * the machine lock the gate's Tests stage holds.
+ *
+ * A scoped run is seconds of work, and queueing it behind a full suite costs
+ * more than any collision it causes. Vitest exposes no setup-time API naming
+ * the CLI filters, so any bare argument other than the subcommand reads as a
+ * file filter. That includes the value of a flag spelled `--flag value`, which
+ * misreads such a run as scoped. The misread skips a lock rather than queueing
+ * a scoped run, which is the side to err on.
+ */
+export function locksHandSuite(run: VitestRun): boolean {
+  if (run.ci || run.watch || run.heldLock !== undefined) return false
+
+  const args = SUBCOMMANDS.has(run.args[0] ?? '') ? run.args.slice(1) : run.args
+  return !args.some((arg) => isNameFilter(arg) || !arg.startsWith('-'))
+}

package/src/gate/measures.ts

@@ -56,7 +56,14 @@ export interface CommandResult {
   readonly spawnError?: string
 }
 
-export type RunCommand = (argv: readonly string[]) => Promise<CommandResult>
+/**
+ * Spawns one command. `env` adds variables to the child's environment, which a
+ * locked stage uses to tell its child which lock the gate already holds.
+ */
+export type RunCommand = (
+  argv: readonly string[],
+  env?: Readonly<Record<string, string>>,
+) => Promise<CommandResult>
 
 export interface MeasureContext {
   readonly root: string
@@ -331,7 +338,7 @@ export const designProse: Measure = async (ctx) => {
   if (failures.length > 0) {
     return {
       emissions: [],
-      failure: `${failures.join(' ')} Cut to the budget in claude/skills/canvas-board/references/design.md, moving the why to the context entry.`,
+      failure: `${failures.join(' ')} Cut to the budget in claude/skills/design-record/references/design.md, moving the why to the context entry.`,
     }
   }
   if (emissions.length === 0)

package/src/gate/sequencer.ts

@@ -8,6 +8,7 @@ import type {
   MeasureContext,
   RunCommand,
 } from '@/gate/measures'
+import { HELD_LOCK_VARIABLE } from '@/gate/hand-suite'
 import type { Check, Stage } from '@/gate/stages'
 import {
   acquireSuiteLock,
@@ -248,7 +249,7 @@ async function executeStage(
   }
 
   // CI runs one suite per runner, so a lock there queues behind nothing.
-  if (stage.lock === undefined || ctx.ci) return runChecks(stage, ctx, [])
+  if (stage.lock === undefined || ctx.ci) return runChecks(stage, ctx, [], {})
 
   const held = await acquireSuiteLock({
     path: machineLockPath(stage.lock),
@@ -266,8 +267,10 @@ async function executeStage(
         ]
 
   try {
+    // The suite's own global setup takes this lock for a hand run, so the
+    // child is told its parent holds it rather than waiting on the parent.
     const outcome = withLoadLine(
-      await runChecks(stage, ctx, queued),
+      await runChecks(stage, ctx, queued, { [HELD_LOCK_VARIABLE]: stage.lock }),
       stage,
       ctx,
     )
@@ -310,11 +313,12 @@ async function runChecks(
   stage: Stage,
   ctx: GateContext,
   leading: readonly Emission[],
+  env: Readonly<Record<string, string>>,
 ): Promise<StageOutcome> {
   const emissions: Emission[] = [...leading]
 
   for (const check of stage.checks) {
-    const outcome = await runCheck(check, ctx)
+    const outcome = await runCheck(check, ctx, env)
     emissions.push(...outcome.emissions)
 
     if (outcome.failure !== undefined) {
@@ -363,7 +367,11 @@ interface CheckOutcome {
   readonly unmeasured?: string
 }
 
-async function runCheck(check: Check, ctx: GateContext): Promise<CheckOutcome> {
+async function runCheck(
+  check: Check,
+  ctx: GateContext,
+  env: Readonly<Record<string, string>>,
+): Promise<CheckOutcome> {
   if (check.kind === 'measure') {
     const report = await check.measure(ctx)
     return {
@@ -378,7 +386,7 @@ async function runCheck(check: Check, ctx: GateContext): Promise<CheckOutcome> {
   }
 
   const run = check.kind === 'cli' ? ctx.cli : ctx.run
-  const result = await run(check.argv)
+  const result = await run(check.argv, env)
   return {
     emissions: [{ kind: 'output', text: result.all }],
     failure: result.exitCode === 0 ? undefined : check.failure,
@@ -492,7 +500,7 @@ export function exitCodeFor(results: readonly StageResult[]): number {
  * repository the hook points at rather than the tree being verified.
  */
 export function commandRunner(root: string): RunCommand {
-  return async (argv) => spawn(argv[0], argv.slice(1), root)
+  return async (argv, env) => spawn(argv[0], argv.slice(1), root, env)
 }
 
 /**
@@ -504,19 +512,20 @@ export function commandRunner(root: string): RunCommand {
  */
 export function cliRunner(root: string): RunCommand {
   const cli = join(PROJECT_ROOT, 'src', 'cli.ts')
-  return async (argv) => spawn(process.execPath, [cli, ...argv], root)
+  return async (argv, env) => spawn(process.execPath, [cli, ...argv], root, env)
 }
 
 async function spawn(
   file: string,
   args: readonly string[],
   cwd: string,
+  env: Readonly<Record<string, string>> = {},
 ): Promise<CommandResult> {
   const result = await execa(file, [...args], {
     cwd,
     reject: false,
     all: true,
-    env: { ...gitEnv(), CANON_NON_INTERACTIVE: '1' },
+    env: { ...gitEnv(), CANON_NON_INTERACTIVE: '1', ...env },
     extendEnv: false,
   })
 

package/src/gov/detect.ts

@@ -99,25 +99,35 @@ function walkFiles(target: string): string[] {
   return files.sort()
 }
 
+interface Candidates {
+  readonly paths: readonly string[]
+  readonly folders: readonly string[]
+}
+
 /**
  * The paths a file glob is matched against: every file to depth two, plus
  * every folder on the way to any listed file, so an evidence folder such as
- * `.github/workflows` matches without naming the file inside it.
+ * `.github/workflows` matches without naming the file inside it. `folders`
+ * holds the folders alone, which a pattern ending in `/` is matched against.
  */
-async function candidatePaths(target: string): Promise<string[]> {
+async function candidatePaths(target: string): Promise<Candidates> {
   const listed = (await listRepositoryFiles(target)) ?? walkFiles(target)
   const paths = new Set<string>()
+  const folders = new Set<string>()
 
   for (const file of listed) {
     let dir = dirname(file)
     while (dir !== '.') {
-      if (depth(dir) <= MAX_DIRS) paths.add(dir)
+      if (depth(dir) <= MAX_DIRS) {
+        paths.add(dir)
+        folders.add(dir)
+      }
       dir = dirname(dir)
     }
     if (depth(file) <= MAX_DIRS) paths.add(file)
   }
 
-  return [...paths].sort()
+  return { paths: [...paths].sort(), folders: [...folders].sort() }
 }
 
 /** A PEP 508 requirement's distribution name, normalized per PEP 503. */
@@ -231,6 +241,11 @@ function readDependencies(
   return deps
 }
 
+/** A pattern ending in `/` matches folders only, so a file at that depth misses. */
+function isFolderPattern(pattern: string): boolean {
+  return pattern.endsWith('/')
+}
+
 /** A glob carrying no wildcard names one path rather than a pattern. */
 function isLiteral(pattern: string): boolean {
   return !/[*?[\]{}]/.test(pattern)
@@ -245,7 +260,7 @@ function matchEntry(
   entry: DetectEntry,
   target: string,
   deps: ReadonlyMap<string, readonly string[]>,
-  paths: readonly string[],
+  candidates: Candidates,
 ): Evidence[] {
   const evidence: Evidence[] = []
 
@@ -255,9 +270,12 @@ function matchEntry(
   }
 
   for (const pattern of entry.files) {
-    const glob = new Bun.Glob(pattern)
+    const folderOnly = isFolderPattern(pattern)
+    const glob = new Bun.Glob(folderOnly ? pattern.slice(0, -1) : pattern)
     const hit =
-      paths.find((path) => glob.match(path)) ??
+      (folderOnly ? candidates.folders : candidates.paths).find((path) =>
+        glob.match(path),
+      ) ??
       (isLiteral(pattern) && existsSync(join(target, pattern))
         ? pattern
         : undefined)
@@ -287,13 +305,13 @@ export async function detectRules(
   }
 
   const live = indexRuleSources(root)
-  const paths = await candidatePaths(target)
-  const deps = readDependencies(target, paths)
+  const candidates = await candidatePaths(target)
+  const deps = readDependencies(target, candidates.paths)
 
   const proposals = loadDetectEntries(root)
     .filter((entry) => live.has(entry.rule) && !covered.has(entry.rule))
     .flatMap((entry) => {
-      const evidence = matchEntry(entry, target, deps, paths)
+      const evidence = matchEntry(entry, target, deps, candidates)
       return evidence.length === 0 ? [] : [{ rule: entry.rule, evidence }]
     })