@erclx/canon 5.10.0 → 5.12.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.10.0",
+  "version": "5.12.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -36,9 +36,8 @@
     "prepare": "husky",
     "check": "bun src/cli.ts gate run",
     "check:ci": "bun src/cli.ts gate run --all --no-write",
-    "update": "./scripts/core/update.sh",
-    "clean": "./scripts/core/clean.sh",
-    "snapshot": "./scripts/core/snapshot.sh",
+    "update": "bun update --interactive && bun run check",
+    "clean": "rm -rf node_modules && bun pm cache rm && bun install",
     "bootstrap": "./scripts/core/bootstrap.sh",
     "canon:sandbox": "canon sandbox",
     "canon:sandbox:reset": "canon sandbox reset",

package/scripts/lib/sandbox-path.sh

@@ -7,7 +7,7 @@
 # both carry the rule sending shared session scratch to the main worktree root,
 # and nothing decides which root wins. A session picking the toolkit writes its
 # output where no manifest reads it, so the run reports success while the verdict
-# reports no writes at all. `scripts/eval/run.sh` keeps its fixture outside the
+# reports no writes at all. The retired eval runner kept its fixture outside the
 # repository for the same reason.
 #
 # Mints a short random per-run identifier the first time it is asked for, then

package/src/commands/gate.ts

@@ -5,7 +5,6 @@ import {
   commandRunner,
   exitCodeFor,
   type GateContext,
-  repairBareFlag,
   type StageResult,
   type Summary,
   runStages,
@@ -24,6 +23,7 @@ import {
   pipeOutput,
   plural,
 } from '@/ui'
+import { repairBareFlag } from '@/worktrees/bare-flag'
 
 interface RunCommandOptions {
   readonly all?: boolean
@@ -97,7 +97,8 @@ async function runGate(opts: RunCommandOptions): Promise<number> {
 
   if (!emitJson && !nested) intro('canon gate run')
 
-  await repairBareFlag(root)
+  const repair = await repairBareFlag(root)
+  if (repair.message !== null) logWarn(repair.message)
 
   const changed = opts.all
     ? { scoped: false, files: [] }

package/src/commands/pr.ts

@@ -32,6 +32,8 @@ import {
   findEvidenceLocal,
   findEvidencePreview,
   groupEvidence,
+  hasMarkedEvidenceComment,
+  readOwed,
   renderEvidenceBody,
 } from '@/pr/evidence'
 import { type HeadRefusal, resolveHead, resolveTip } from '@/pr/head'
@@ -88,6 +90,7 @@ interface EvidenceOptions extends ReadOptions {
   readonly preview?: string
   readonly checklist?: string
   readonly local?: string
+  readonly check?: boolean
 }
 
 interface LocalOptions extends ReadOptions {
@@ -172,6 +175,7 @@ const PULL_REFUSALS: Record<PullRefusal | HeadRefusal, string> = {
  * one `identity.head` owns (`no-object-head`).
  */
 type EvidenceRefusal =
+  | 'check-writes'
   | 'gh-failed'
   | 'no-base'
   | 'unreadable-changes'
@@ -179,6 +183,8 @@ type EvidenceRefusal =
   | 'would-empty'
 
 const EVIDENCE_REFUSALS: Record<EvidenceRefusal, string> = {
+  'check-writes':
+    '--check is a read and renders no body, so it takes none of --preview, --local, or --checklist. Run the check and the render as two calls.',
   'gh-failed':
     'gh could not answer for this repository. Name the pull request number.',
   'unreadable-checklist':
@@ -425,6 +431,10 @@ export function register(program: Command): void {
       '--local <url>',
       "Add this worktree's running server under any preview line, from canon pr local",
     )
+    .option(
+      '--check',
+      'Report which post-pull-request steps the thread is still owed, rendering nothing',
+    )
     .addHelpText(
       'after',
       [
@@ -456,17 +466,17 @@ export function register(program: Command): void {
         '--checklist closes the body with a visual checklist, below the',
         'comparison it annotates. A checklist the marked comment already',
         'carries is read back and carried forward the same way the preview',
-        'address is, which keeps a re-render from wiping ticked boxes. It does',
-        'not decide no-evidence: a branch with a checklist and no evidence',
-        'image still reports no-evidence, and the caller posts the checklist',
-        'on its own.',
+        'address is, which keeps a re-render from wiping ticked boxes. It',
+        'turns no-evidence into ok: a branch with a checklist and no evidence',
+        'image renders a marked body holding the checklist, so a later call',
+        'finds and edits that comment.',
         '',
         '--local adds a **Local preview:** line under the hosted preview line,',
         'or opens the body with it when there is none, and is carried forward',
         'the same way. It does not by itself turn no-evidence into ok, so a',
         'branch with a server running and nothing to show posts no link-only',
-        'comment. Together with --checklist it does, so the checklist and the',
-        'link land in one comment.',
+        'comment. Together with --checklist the link and the checklist land in',
+        'one comment.',
         '',
         'Both reasons carry what the marked comment already posted, each field',
         'present only when that comment holds it:',
@@ -474,12 +484,24 @@ export function register(program: Command): void {
         '  local      the **Local preview:** address under it',
         '  checklist  the checklist between its delimiters, ticks included',
         'These come from the comment already posted, never from the flags this',
-        'call passed. A checklist posted on its own carries no marker, so the',
-        'record reports none of the three for it. An unread thread refuses as',
-        'gh-failed on both reasons rather than reporting the fields absent.',
+        'call passed. A checklist the caller posted raw after a refused render',
+        'carries no marker, so the record reports none of the three for it. An',
+        'unread thread refuses as gh-failed on both reasons rather than',
+        'reporting the fields absent.',
+        '',
+        '--check reads the same changed set and thread, renders no body, and',
+        'reports what the ship chain still owes the pull request:',
+        '  settled  nothing is owed',
+        '  owed     `owed` lists evidence, preview, or both, in that order',
+        'evidence is owed when an evidence image changed and no comment carries',
+        'the marker. preview is owed when either holds, a deploy workflow in',
+        "this checkout resolves, and the marked comment's first line is no",
+        '**Preview:** line. A failed deploy reads the same as a skipped one.',
+        'The record carries `owed` and the same marked fields. --check refuses',
+        'with --preview, --local, or --checklist as check-writes.',
         '',
         'Exit codes:',
-        '  0  read, whether it produced a body or reported no-evidence',
+        '  0  read, whether it produced a body, reported no-evidence, or checked',
         '  1  refused, with the reason on stderr or in the JSON record',
         '',
         'Examples:',
@@ -488,6 +510,7 @@ export function register(program: Command): void {
         '  canon pr evidence 1341 --preview https://feat-x.site.pages.dev --json',
         '  canon pr evidence 1341 --checklist .canon/tmp/handoff/ui-checklist/x.md --json',
         '  canon pr evidence 1341 --local http://localhost:5173 --json',
+        '  canon pr evidence 1341 --check --json',
         '',
       ].join('\n'),
     )
@@ -1417,9 +1440,24 @@ async function runEvidence(
 ): Promise<number> {
   const root = resolve(opts.root ?? process.cwd())
   const emitJson = opts.json ?? false
+  const isCheck = opts.check ?? false
 
   intro('canon pr evidence')
 
+  if (
+    isCheck &&
+    (opts.preview !== undefined ||
+      opts.local !== undefined ||
+      opts.checklist !== undefined)
+  ) {
+    return refuseWith(
+      'check-writes',
+      EVIDENCE_REFUSALS['check-writes'],
+      emitJson,
+      root,
+    )
+  }
+
   // Read ahead of anything else, so a bad path refuses before a `gh` round
   // trip rather than after one.
   let suppliedChecklist: string | undefined
@@ -1461,9 +1499,13 @@ async function runEvidence(
     )
   }
 
+  // The check never reads the merge base, so it skips the compare call and
+  // a failed one cannot hold a draft lift for a reason the check never had.
   const [pullFiles, base] = await Promise.all([
     listPullFiles(root, identity.number),
-    readPullMergeBase(root, identity.number, identity.head),
+    isCheck
+      ? undefined
+      : readPullMergeBase(root, identity.number, identity.head),
   ])
   if (pullFiles === undefined) {
     return refuseWith(
@@ -1473,9 +1515,6 @@ async function runEvidence(
       root,
     )
   }
-  if (base === undefined) {
-    return refuseWith('no-base', EVIDENCE_REFUSALS['no-base'], emitJson, root)
-  }
 
   const grouped = await groupEvidence(
     [...pullFiles.keys()],
@@ -1533,14 +1572,49 @@ async function runEvidence(
     ...(carriedChecklist !== undefined && { checklist: carriedChecklist }),
   }
 
-  // A local address rides on a checklist or a hosted preview and never opens
-  // a comment alone, so a docs-only branch with a server up posts nothing.
-  const hasChecklistAndLocal =
-    suppliedChecklist !== undefined && opts.local !== undefined
+  if (isCheck) {
+    const owed = readOwed({
+      hasEvidenceChange: grouped.kind === 'read',
+      hasMarkedComment: hasMarkedEvidenceComment(comments),
+      carriedPreview: carriedPreview !== undefined,
+      deployWorkflowFound:
+        findDeployWorkflow(await readWorkflows(root)).kind === 'found',
+    })
+    logStep(owed.length === 0 ? 'Settled' : 'Owed')
+    logInfo(
+      owed.length === 0
+        ? 'Nothing the ship chain posts after the pull request is missing.'
+        : `missing ${owed.join(', ')}`,
+    )
+    outro()
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          number: identity.number,
+          reason: owed.length === 0 ? 'settled' : 'owed',
+          owed,
+          ...(commentId !== undefined && { commentId }),
+          ...carried,
+        })}\n`,
+      )
+    }
+    return 0
+  }
+
+  if (base === undefined) {
+    return refuseWith('no-base', EVIDENCE_REFUSALS['no-base'], emitJson, root)
+  }
+
+  // A checklist opens a comment on its own, so it always lands in the marked
+  // comment a later call edits. A local address rides on a checklist or a
+  // hosted preview and never opens one alone, so a docs-only branch with a
+  // server up posts nothing.
+  const hasChecklist = suppliedChecklist !== undefined
   if (
     grouped.kind === 'refused' &&
     opts.preview === undefined &&
-    !hasChecklistAndLocal
+    !hasChecklist
   ) {
     logStep('Skipped')
     logInfo(

package/src/commands/worktrees.ts

@@ -17,6 +17,7 @@ import {
   type WorktreeVerdict,
 } from '@/worktrees/reclaim'
 import { mainWorktreeRoot } from '@/worktree'
+import { repairBareFlag } from '@/worktrees/bare-flag'
 import {
   removeReclaimable,
   type RemovalOutcome,
@@ -27,6 +28,11 @@ interface ListCommandOptions {
   readonly json?: boolean
 }
 
+interface RepairBareFlagOptions {
+  readonly root?: string
+  readonly json?: boolean
+}
+
 interface ReclaimCommandOptions {
   readonly dryRun?: boolean
   readonly json?: boolean
@@ -208,6 +214,37 @@ export function register(program: Command): void {
     .action(async (opts: ReclaimCommandOptions) => {
       process.exitCode = await runReclaim(opts)
     })
+
+  worktrees
+    .command('repair-bare-flag', { hidden: true })
+    .description('Clear a core.bare flag that worktree entry left set')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to repair', '.')
+    .option('--json', 'Print the record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  always, since the caller is a hook that must never fail a tool call',
+        '',
+        'Called by .claude/hooks/bare-flag-repair.sh, the one caller that is not',
+        'a person, so no help listing shows it. A repository whose common dir is',
+        'not named .git keeps its flag, since that is a genuinely bare one.',
+        '',
+        'Examples:',
+        '  canon worktrees repair-bare-flag --root . --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RepairBareFlagOptions) => {
+      const record = await repairBareFlag(opts.root ?? '.')
+      if (opts.json === true) {
+        process.stdout.write(`${JSON.stringify(record)}\n`)
+      } else if (record.message !== null) {
+        logWarn(record.message)
+      }
+    })
 }
 
 /**

package/src/gate/sequencer.ts

@@ -377,23 +377,3 @@ async function spawn(
     spawnError: code === 'ENOENT' ? `${file} is not on PATH` : undefined,
   }
 }
-
-/**
- * Repairs `core.bare`, which Claude Code's worktree entry leaves set in the
- * shared config and nothing restores.
- *
- * It runs ahead of every stage rather than as one of them, because the flag
- * breaks the git reads that scope the run. The rule itself stays in
- * `scripts/lib/worktree.sh`, which is the one bash function under test, so this
- * calls it rather than restating the guard that spares a genuinely bare
- * repository.
- */
-export async function repairBareFlag(root: string): Promise<void> {
-  await execa('bash', [join(root, 'scripts/core/repair-bare-flag.sh')], {
-    cwd: root,
-    reject: false,
-    stdio: 'inherit',
-    env: { ...gitEnv(), PROJECT_ROOT: root },
-    extendEnv: false,
-  })
-}

package/src/gate/stages.ts

@@ -99,7 +99,6 @@ export const TEST_CORPORA_PATTERNS = [
   '^standards/markdown\\.md$',
   '^tooling/base/reference\\.md$',
   '^tooling/web/configs/scripts/worktree-port\\.sh$',
-  '^scripts/lib/worktree\\.sh$',
   '^scripts/core/check-ignore-parity\\.sh$',
 ]
 
@@ -164,7 +163,11 @@ export const STAGES: readonly Stage[] = [
     id: 'indexes',
     label: 'Indexes',
     checks: [
-      script('regen-indexes.sh', 'Index regen failed'),
+      {
+        kind: 'cli',
+        argv: ['indexes', 'regen'],
+        failure: 'Index regen failed',
+      },
       {
         kind: 'drift',
         pathspec: '*index.md',
@@ -178,7 +181,11 @@ export const STAGES: readonly Stage[] = [
     id: 'consumed-copies',
     label: 'Consumed copies',
     checks: [
-      script('regen-claude-copies.sh', 'Consumed-copy regen failed'),
+      {
+        kind: 'cli',
+        argv: ['gov', 'regen'],
+        failure: 'Consumed-copy regen failed',
+      },
       {
         kind: 'drift',
         pathspec: '.claude/rules',

package/src/pr/evidence.ts

@@ -215,6 +215,41 @@ function hasEvidenceMarker(body: string): boolean {
   return (lines[index] ?? '').trim().startsWith(MARKER_PREFIX)
 }
 
+/** Whether any comment carries the evidence marker, url or not. */
+export function hasMarkedEvidenceComment(
+  comments: readonly EvidenceComment[],
+): boolean {
+  return comments.some((comment) => hasEvidenceMarker(comment.body))
+}
+
+/** A post-pull-request step of the ship chain that never landed on the thread. */
+export type OwedStep = 'evidence' | 'preview'
+
+export interface OwedInput {
+  readonly hasEvidenceChange: boolean
+  readonly hasMarkedComment: boolean
+  readonly carriedPreview: boolean
+  readonly deployWorkflowFound: boolean
+}
+
+/**
+ * The steps a pull request is still owed, read off the pull request rather
+ * than off any session's account of what it ran. The thread cannot tell a
+ * skipped preview from one whose deploy failed, so both read as owed.
+ */
+export function readOwed(input: OwedInput): OwedStep[] {
+  const owed: OwedStep[] = []
+  if (input.hasEvidenceChange && !input.hasMarkedComment) owed.push('evidence')
+  if (
+    (input.hasMarkedComment || input.hasEvidenceChange) &&
+    input.deployWorkflowFound &&
+    !input.carriedPreview
+  ) {
+    owed.push('preview')
+  }
+  return owed
+}
+
 /**
  * The REST id of the comment this module already posted, read off its `url`
  * field, since `gh pr view --json comments` reports only a GraphQL id there

package/src/tasks/validate.ts

@@ -6,7 +6,6 @@ import {
   declinedDir,
   isReservedStem,
   readOutcomes,
-  readPlanTarget,
   readPlanTargets,
   readPullRequest,
   resolveLivePlan,
@@ -731,11 +730,8 @@ async function planDisagreement(
   if (!existsSync(file)) return undefined
 
   const text = await readFile(file, 'utf8')
-  const target = readPlanTarget(text)
-  if (!target) {
-    const several = severalPlans(text, 'Run now', subject)
-    if (several) return several
-
+  const targets = readPlanTargets(text)
+  if (targets.length === 0) {
     return {
       kind: 'plan-uncited',
       group: 'Run now',
@@ -744,15 +740,22 @@ async function planDisagreement(
     }
   }
 
+  const twice = duplicatePlans(targets, 'Run now', subject, dir, root)
+  if (twice) return twice
+
   const rowed = planPath(row.plan, dir, root)
-  const cited = planPath(target, dir, root)
-  if (rowed === cited) return undefined
+  if (targets.some((target) => planPath(target, dir, root) === rowed)) {
+    return undefined
+  }
 
   return {
     kind: 'plan-mismatched',
     group: 'Run now',
     subject,
-    message: `is rowed against ${row.plan} and cites ${target} in its own Plan: line. One task names one plan.`,
+    message:
+      targets.length === 1
+        ? `is rowed against ${row.plan} and cites ${targets[0]} in its own Plan: line. One task names one plan.`
+        : `is rowed against ${row.plan}, which is none of the links on its own Plan: line (${targets.join(', ')}).`,
   }
 }
 
@@ -794,14 +797,15 @@ async function groupClaimFinding(
   if (!existsSync(file)) return undefined
 
   const text = await readFile(file, 'utf8')
-  const target = readPlanTarget(text)
-  if (!target) {
-    const several = severalPlans(text, row.group, row.stem)
-    if (several) return several
-  }
+  const targets = readPlanTargets(text)
+  const twice = duplicatePlans(targets, row.group, row.stem, dir, root)
+  if (twice) return twice
 
-  const live = target ? resolveLivePlan(target, dir, root) : undefined
-  const hasLivePlan = live !== undefined && existsSync(live)
+  const target = targets.find((link) => {
+    const live = resolveLivePlan(link, dir, root)
+    return live !== undefined && existsSync(live)
+  })
+  const hasLivePlan = target !== undefined
 
   if (row.group === 'Needs a plan' && hasLivePlan) {
     return {
@@ -817,9 +821,12 @@ async function groupClaimFinding(
       kind: 'plan-absent',
       group: row.group,
       subject: row.stem,
-      message: target
-        ? `sits under ${row.group}, which claims a written plan, and its task cites ${target}, which is not a live plan.`
-        : `sits under ${row.group}, which claims a written plan, and its task carries no Plan: line.`,
+      message:
+        targets.length > 1
+          ? `sits under ${row.group}, which claims a written plan, and its task cites ${targets.join(', ')}, none of which is a live plan.`
+          : targets.length === 1
+            ? `sits under ${row.group}, which claims a written plan, and its task cites ${targets[0]}, which is not a live plan.`
+            : `sits under ${row.group}, which claims a written plan, and its task carries no Plan: line.`,
     }
   }
 
@@ -827,23 +834,26 @@ async function groupClaimFinding(
 }
 
 /**
- * Reports a `Plan:` line linking more than one plan. `readPlanTarget` reads
- * such a line as naming nothing, so without this a caller would report the
- * line as absent when it is there and breaks the one-plan rule instead.
+ * Reports a `Plan:` line linking one plan more than once. Links to distinct
+ * plans are the shape a sliced task carries, so only a repeat is a finding.
+ * Links compare by the file they resolve to, so `../plans/x.md` beside
+ * `.canon/plans/x.md` is one plan listed twice.
  */
-function severalPlans(
-  text: string,
+function duplicatePlans(
+  targets: readonly string[],
   group: Finding['group'],
   subject: string,
+  dir: string,
+  root: string,
 ): Finding | undefined {
-  const targets = readPlanTargets(text)
-  if (targets.length < 2) return undefined
+  const paths = targets.map((target) => planPath(target, dir, root))
+  if (new Set(paths).size === paths.length) return undefined
 
   return {
     kind: 'plan-several',
     group,
     subject,
-    message: `cites ${targets.length} plans on its Plan: line (${targets.join(', ')}). One task names one plan, so split the task or drop the extra links.`,
+    message: `lists the same plan twice on its Plan: line (${targets.join(', ')}). Drop the repeat, or link a distinct plan per slice.`,
   }
 }
 

package/src/worktrees/bare-flag.ts

@@ -0,0 +1,83 @@
+import { basename } from 'node:path'
+import { execa } from 'execa'
+import { gitEnv } from '@/git-env'
+
+/** Why a run wrote nothing. The three are different states a caller can tell apart. */
+export type BareFlagSkip =
+  | 'flag-unset'
+  | 'common-dir-unreadable'
+  | 'genuinely-bare'
+  | 'write-failed'
+
+/**
+ * What the repair did, or the reason it left the configuration alone.
+ *
+ * `message` is non-null whenever the flag is still set and a caller should say
+ * so, which is a repair and a failed write. The three quiet skips carry none.
+ */
+export type BareFlagRecord =
+  | { readonly repaired: true; readonly reason: null; readonly message: string }
+  | {
+      readonly repaired: false
+      readonly reason: BareFlagSkip
+      readonly message: string | null
+    }
+
+export const REPAIRED_MESSAGE =
+  "Repaired core.bare, which worktree entry left set. Recovery is 'git config core.bare false'."
+
+export const WRITE_FAILED_MESSAGE =
+  "core.bare is set and the repair could not write the config, which a lock file or a read-only config causes. Recovery is 'git config core.bare false'."
+
+const skipped = (reason: BareFlagSkip): BareFlagRecord => ({
+  repaired: false,
+  reason,
+  message: null,
+})
+
+/**
+ * Repairs `core.bare`, which Claude Code's worktree entry leaves set in the
+ * shared config and nothing restores.
+ *
+ * The flag strands the main worktree and breaks the git reads that scope a
+ * verification run, so the gate runs this ahead of every stage. Every git call
+ * drops the repository-resolution variables a git hook exports, so the root
+ * the caller names is the repository that gets read and written.
+ *
+ * A genuinely bare repository keeps its objects at the root and has no `.git`
+ * directory, so its common dir fails the basename test and keeps its flag. That
+ * test is the one case where an unguarded repair does damage.
+ */
+export async function repairBareFlag(root: string): Promise<BareFlagRecord> {
+  const git = (...args: string[]) =>
+    execa('git', ['-C', root, ...args], {
+      env: gitEnv(),
+      extendEnv: false,
+      reject: false,
+    })
+
+  const flag = await git('config', '--get', 'core.bare')
+  if (flag.exitCode !== 0 || flag.stdout.trim() !== 'true') {
+    return skipped('flag-unset')
+  }
+
+  const common = await git(
+    'rev-parse',
+    '--path-format=absolute',
+    '--git-common-dir',
+  )
+  if (common.exitCode !== 0) return skipped('common-dir-unreadable')
+  if (basename(common.stdout.trim()) !== '.git')
+    return skipped('genuinely-bare')
+
+  const write = await git('config', 'core.bare', 'false')
+  if (write.exitCode !== 0) {
+    return {
+      repaired: false,
+      reason: 'write-failed',
+      message: WRITE_FAILED_MESSAGE,
+    }
+  }
+
+  return { repaired: true, reason: null, message: REPAIRED_MESSAGE }
+}

package/standards/tasks.md

@@ -124,7 +124,7 @@ An intake folder answers that direction at folder scope rather than item scope.
 
 A project that archived plans before the folder nested under `.canon/plans/` holds closed tasks pointing at `../plans-archive/` or `../.tmp/plans-archive/`. Leave those pointers where they are, since each resolves against the files it names and a task retargeted without its plan moving leads nowhere.
 
-One plan per task, or one per slice on a sliced task. A plan cited by two tasks is a misfile rather than a shape to design for.
+One plan per task, or one per slice, which the board check reads as distinct plans on one line. A plan cited by two tasks is a misfile.
 
 `canon tasks plan-link <task> <plan>` writes or corrects the `Plan:` line, and `--add` appends a slice's plan, so the line is never hand-edited.