@erclx/canon 5.73.0 → 5.75.0

package/src/commands/migrate.ts

@@ -1489,9 +1489,13 @@ export function register(program: Command): void {
         'false only when the key is absent. A deny entry is never removed and',
         'an existing autoMemoryEnabled is never changed.',
         '',
+        'Where .claude/hooks/plan-guard.sh exists, also wires it into',
+        'hooks.PreToolUse for Bash and Write|Edit, skipping a tool whose',
+        'matcher already runs it, so a hand wiring is never doubled.',
+        '',
         'A missing settings file is nothing to do. A file that is not valid',
-        'JSON, or whose permissions or deny has an unexpected shape, is',
-        'refused by name and never partly written.',
+        'JSON, or whose permissions, deny, hooks, or PreToolUse has an',
+        'unexpected shape, is refused by name and never partly written.',
         '',
         'Exit codes:',
         '  0  nothing to add, or --write applied the plan',

package/src/commands/pr.ts

@@ -23,6 +23,8 @@ import {
 import {
   type CheckRunListing,
   collapseChecks,
+  type RawStatus,
+  requiredChecks,
   withMergeState,
 } from '@/pr/checks'
 import {
@@ -33,6 +35,7 @@ import {
   findEvidenceLocal,
   findEvidencePreview,
   findEvidenceReel,
+  findEvidenceSkips,
   type EvidenceItem,
   type EvidenceReading,
   groupEvidence,
@@ -171,6 +174,8 @@ interface EvidenceOptions extends ReadOptions {
   readonly checklist?: string
   readonly local?: string
   readonly reel?: string
+  readonly localSkip?: string
+  readonly reelSkip?: string
   readonly check?: boolean
 }
 
@@ -433,7 +438,7 @@ type EvidenceRefusal =
 
 const EVIDENCE_REFUSALS: Record<EvidenceRefusal, string> = {
   'check-writes':
-    '--check is a read and renders no body, so it takes none of --preview, --local, --checklist, or --reel. Run the check and the render as two calls.',
+    '--check is a read and renders no body, so it takes none of --preview, --local, --checklist, --reel, --local-skip, or --reel-skip. 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':
@@ -775,6 +780,14 @@ export function register(program: Command): void {
       '--reel <link>',
       'Embed this reel under the address line, filmed at the head, from canon pr frames --reel',
     )
+    .option(
+      '--local-skip <reason>',
+      'Name why no local address is posted, from the reason pr-evidence holds for canon pr local',
+    )
+    .option(
+      '--reel-skip <reason>',
+      'Name why no reel is embedded, from the reason pr-evidence holds for canon pr frames --reel',
+    )
     .option(
       '--check',
       'Report which post-pull-request steps the thread is still owed, rendering nothing',
@@ -854,6 +867,17 @@ export function register(program: Command): void {
         'current, and a passed one replaces it. Like --local it rides on a',
         'checklist or a comparison and never opens a comment alone.',
         '',
+        '--local-skip and --reel-skip each put one line under the addresses,',
+        '**No local preview:** or **No reel:** followed by the text passed, a',
+        'reason code and any one-line message joined to it, folded onto one',
+        'line. Without the flag, a skip line the marked comment already carries',
+        'is carried forward. A skip line is dropped whenever its address or',
+        'reel renders, passed or carried, so a later run that posts the link or',
+        'films the reel replaces it. A passed --local-skip drops a carried',
+        'local address, since that line names no head and would read as live,',
+        'while a carried reel names its head and stays beside --reel-skip. Like',
+        '--local, neither opens a comment alone.',
+        '',
         "A render at a new head also resets the pull request body's UI pass",
         'line, the one `canon pr tick` writes under ## Testing, to unchecked',
         'naming that head. It touches no other body text, leaves a line already',
@@ -893,7 +917,8 @@ export function register(program: Command): void {
         'request changed, and the marked comment carries no **Preview:**',
         'address. A failed deploy reads the same as a skipped one.',
         'The record carries `owed` and the same marked fields. --check refuses',
-        'with --preview, --local, --checklist, or --reel as check-writes.',
+        'with --preview, --local, --checklist, --reel, --local-skip, or',
+        '--reel-skip as check-writes.',
         '',
         'Refusals, read off `reason`:',
         '  unreadable-checklist  --checklist named a path that could not be read,',
@@ -917,6 +942,7 @@ export function register(program: Command): void {
         '  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 --reel <link from canon pr frames --reel> --json',
+        "  canon pr evidence 1341 --reel-skip 'no-server: <message>' --json",
         '  canon pr evidence 1341 --check --json',
         '',
       ].join('\n'),
@@ -960,7 +986,12 @@ export function register(program: Command): void {
         '            or needing eyes refuses `ui-undriven`, carried or not',
         '  evidence  the evidence check reads settled',
         '  standing  the head is fresh against the base, not stale or conflicted',
-        '  ci        every check run on the tip passed, waited on up to --wait',
+        '  ci        every required check run on the tip passed, waited on up to --wait',
+        '',
+        "The required checks are the ones the base branch's rules list. A",
+        'check outside them is waited on by nobody, and one that failed is',
+        'named in the record as `advisory` without blocking. Rules that do not',
+        'read, or that list no check, gate by every check run on the tip.',
         '',
         'Review state, UI state, evidence, and standing are read before the CI',
         'wait, so a reviewer whose partner is still driving refuses at once. The',
@@ -1039,6 +1070,10 @@ export function register(program: Command): void {
         'request already passed `canon pr lift`. It does not wait on checks or',
         'delete the branch.',
         '',
+        "The checks gate by the ones the base branch's rules require, the way",
+        '`canon pr lift` reads them. A failing check outside that set is named',
+        'in the record as `advisory` and does not refuse the merge.',
+        '',
         'Reasons:',
         '  merged, dry-run (--dry-run)',
         '  pull-closed, pull-draft, missing-summary, missing-key-changes,',
@@ -2658,7 +2693,9 @@ async function runEvidence(
     (opts.preview !== undefined ||
       opts.local !== undefined ||
       opts.checklist !== undefined ||
-      opts.reel !== undefined)
+      opts.reel !== undefined ||
+      opts.localSkip !== undefined ||
+      opts.reelSkip !== undefined)
   ) {
     return refuseWith(
       'check-writes',
@@ -2868,8 +2905,17 @@ async function runEvidence(
   }
 
   const preview = opts.preview ?? (isUnserved ? undefined : carriedPreview)
-  const local = opts.local ?? carriedLocal
+  // A carried local line names no head and reads as live, so a passed skip
+  // drops it the way a passed address replaces it. A carried reel names the
+  // head it was filmed at, so it stays beside a passed skip.
+  const local =
+    opts.local ?? (opts.localSkip === undefined ? carriedLocal : undefined)
   const reel = nextEvidenceReel(opts.reel, identity.head, comments)
+  const carriedSkips = findEvidenceSkips(comments)
+  const skips = {
+    local: opts.localSkip ?? carriedSkips.local,
+    reel: opts.reelSkip ?? carriedSkips.reel,
+  }
   const unsettled = suppliedChecklist ?? carriedChecklist
   const checklist =
     unsettled === undefined
@@ -2886,6 +2932,7 @@ async function runEvidence(
     checklist,
     local,
     reel,
+    skips,
   )
 
   const caseCount = states.reduce((n, s) => n + s.items.length, 0)
@@ -4209,24 +4256,64 @@ async function readChecksGate(
   number: string,
   tip: string,
 ): Promise<ChecksGate | undefined> {
-  const [listed, pulled] = await Promise.all([
+  // A status read that fails leaves a required status context unseen, which
+  // reads pending rather than passing, so it needs no refusal of its own.
+  const [listed, pulled, combined] = await Promise.all([
     gh(root, [
       'api',
       `repos/{owner}/{repo}/commits/${tip}/check-runs?per_page=100`,
     ]),
     gh(root, ['api', `repos/{owner}/{repo}/pulls/${number}`]),
+    gh(root, [
+      'api',
+      `repos/{owner}/{repo}/commits/${tip}/status?per_page=100`,
+    ]),
   ])
   if (listed === null) return undefined
   try {
-    const mergeState =
-      pulled === null
-        ? undefined
-        : mergeStateOf((JSON.parse(pulled) as RestPull).mergeable_state)
+    const row = pulled === null ? undefined : (JSON.parse(pulled) as RestPull)
+    const required = await readRequiredChecks(root, row?.base?.ref)
+    const statuses =
+      combined === null
+        ? []
+        : ((JSON.parse(combined) as { statuses?: readonly RawStatus[] })
+            .statuses ?? [])
     const reading = withMergeState(
-      mergeState,
-      collapseChecks(tip, JSON.parse(listed) as CheckRunListing),
+      mergeStateOf(row?.mergeable_state),
+      collapseChecks(
+        tip,
+        JSON.parse(listed) as CheckRunListing,
+        required,
+        statuses,
+      ),
     )
-    return { state: reading.state, isConflicted: reading.conflicted }
+    return {
+      state: reading.state,
+      isConflicted: reading.conflicted,
+      ...(reading.advisory !== undefined && { advisory: reading.advisory }),
+    }
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The checks the base branch's rules require, so a check they leave out runs
+ * without holding the gate. Undefined on any read that fails, which gates by
+ * every check as the verbs did before the rules were read.
+ */
+async function readRequiredChecks(
+  root: string,
+  base: string | undefined,
+): Promise<ReadonlySet<string> | undefined> {
+  if (base === undefined || base === '') return undefined
+  const rules = await gh(root, [
+    'api',
+    `repos/{owner}/{repo}/rules/branches/${base}`,
+  ])
+  if (rules === null) return undefined
+  try {
+    return requiredChecks(JSON.parse(rules))
   } catch {
     return undefined
   }
@@ -4360,6 +4447,7 @@ async function runLift(
   for (const gate of record.gates) {
     if (!gate.isOk) logWarn(`${gate.gate}: ${gate.reason ?? 'not clear'}`)
   }
+  warnAdvisory(record.advisory)
   outro()
 
   if (emitJson) {
@@ -4371,6 +4459,14 @@ async function runLift(
   return record.isOk ? 0 : 1
 }
 
+function warnAdvisory(advisory: readonly string[] | undefined): void {
+  for (const name of advisory ?? []) {
+    logWarn(
+      `advisory: ${name} failed, which the base's rules do not require, so it did not block`,
+    )
+  }
+}
+
 const MERGE_REFUSALS: Record<MergeRefusal | 'gh-missing', string> = {
   'gh-missing': PULL_REFUSALS['gh-missing'],
   'pull-closed': 'The pull request is closed, so there is nothing to merge.',
@@ -4516,6 +4612,7 @@ async function runMerge(
         ? `#${record.number} would merge with the message below`
         : MERGE_REFUSALS[record.reason],
   )
+  warnAdvisory(record.advisory)
   outro()
 
   if (emitJson) {

package/src/commands/take.ts

@@ -28,6 +28,7 @@ type Take = typeof import('@/take/film')
 interface RunOptions {
   readonly out?: string
   readonly reel?: string
+  readonly maxSeconds?: string
   readonly json?: boolean
 }
 
@@ -58,6 +59,10 @@ const TAKE_REFUSALS: Record<TakeRefusal, string> = {
   'browser-missing': 'The headless shell is not installed in this project.',
   'server-unreachable': 'Nothing answered at the URL, so no beat was filmed.',
   'target-missing': 'A step names a target the page does not carry.',
+  'target-offscreen':
+    'A step names a target outside the window, so a setup step must bring it into view first.',
+  'over-cap':
+    'The filmed beats ran past --max-seconds, so the take stopped at the beat that crossed it.',
   'take-failed': 'The take failed against a reachable page.',
 }
 
@@ -80,6 +85,10 @@ export function register(program: Command): void {
       '--reel <file>',
       'Also join the beats into one animated WebP with the pointer drawn',
     )
+    .option(
+      '--max-seconds <n>',
+      'Refuse once the filmed beats run past n seconds in total',
+    )
     .option('--json', 'Add a machine-readable record on stdout')
     .addHelpText(
       'after',
@@ -153,6 +162,7 @@ export function register(program: Command): void {
         `  ${INSTALL_BROWSER}`,
         '',
         'Reasons:',
+        '  bad-max-seconds     --max-seconds is not a positive number',
         '  no-plan-file        nothing readable at the plan path',
         '  unreadable-plan     the plan file is not valid JSON',
         '  no-beats            the plan names no beat',
@@ -166,15 +176,18 @@ export function register(program: Command): void {
         '  browser-missing     the headless shell or browser binary is not installed',
         '  server-unreachable  nothing answered at the URL',
         '  target-missing      a step names a target the page does not carry',
+        '  target-offscreen    a step names a target outside the window, so a setup step must bring it into view first',
+        '  over-cap            the filmed beats ran past --max-seconds, naming the',
+        '                      beat that crossed it',
         '  take-failed         the take failed against a reachable page',
         '  reel-failed         every beat was filmed and the reel did not encode',
         '',
-        'A refusal in a beat carries beat. target-missing carries still when the',
-        "page answered a capture, the beat folder's still.jpg as the step met it. A",
-        'beat that fell back to the screencast before refusing carries fallback,',
-        'the reason it fell back. The screencast opens the address a second time,',
-        'so a single-use link is spent by then: check the access before the',
-        'selector.',
+        'A refusal in a beat carries beat. target-missing and target-offscreen',
+        "carry still when the page answered a capture, the beat folder's",
+        'still.jpg as the step met it. A beat that fell back to the screencast',
+        'before refusing carries fallback, the reason it fell back. The',
+        'screencast opens the address a second time, so a single-use link is',
+        'spent by then: check the access before the selector.',
         '',
         'Exit codes:',
         '  0  every beat was filmed, and the reel written when asked for',
@@ -300,6 +313,17 @@ async function runTake(
 
   intro(`canon take ${url}`)
 
+  const maxSeconds =
+    opts.maxSeconds === undefined ? undefined : readRate(opts.maxSeconds)
+  if (opts.maxSeconds !== undefined && maxSeconds === undefined) {
+    return refuse(
+      emitJson,
+      url,
+      'bad-max-seconds',
+      `--max-seconds ${opts.maxSeconds} is not a positive number, such as 12 or 7.5.`,
+    )
+  }
+
   let source: string
   try {
     source = readFileSync(path, 'utf8')
@@ -344,7 +368,12 @@ async function runTake(
   }
 
   logStep('Filming')
-  const result = await taker.take({ url, plan, out: opts.out })
+  const result = await taker.take({
+    url,
+    plan,
+    out: opts.out,
+    ...(maxSeconds === undefined ? {} : { maxSeconds }),
+  })
 
   if (result.status === 'failed') {
     logStep('Refused')

package/src/counts/catalogs.ts

@@ -24,12 +24,10 @@ const REGISTER_IMPORT = /^import \{ register as /gm
 /**
  * Every top-level `canon` command, read off the CLI entry point rather than a
  * catalog verb, because a command carries no `--json` listing of its own
- * siblings. `regen-hero.ts` imports this reader for its `COMMAND_COUNT`
- * rather than a second regex on `src/cli.ts`, so this is the one place that
- * pattern is written.
+ * siblings. Callers import this reader rather than a second regex on
+ * `src/cli.ts`, so this is the one place that pattern is written.
  *
- * This is the one catalog with no meaning outside this repository, the way
- * `regen-hero.ts` documents itself as clone-only for the same reason.
+ * This is the one catalog with no meaning outside this repository.
  */
 export function countCommands(root: string): number | undefined {
   const cli = join(root, 'src', 'cli.ts')

package/src/gate/measures.ts

@@ -1,5 +1,4 @@
-import { createHash } from 'node:crypto'
-import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import {
   CLIENT_COMMAND_MARKER,
@@ -144,9 +143,6 @@ export function auditsBaselineRel(root: string): string {
   return relative(root, surfaceDir(root, 'canon', 'baseline.json'))
 }
 
-export const CAPTURE_STAMP_FAILURE =
-  'A capture set disagrees with the stamp written when its image was captured. Run canon capture assets/captures --selector .window --out assets/frames and commit each frame with its image and its stamp.'
-
 function parseJson(payload: string): unknown {
   try {
     return JSON.parse(payload)
@@ -1111,7 +1107,7 @@ const VISUAL_ONLY_GLOBS: readonly string[] = ['tooling/web/configs/e2e/**']
 
 /**
  * `deploy-site.yml` and `pr-visual-checks.yml` each carry their own literal
- * copy of the eight path globs a landing-page change should trigger on, plus
+ * copy of the five path globs a landing-page change should trigger on, plus
  * the `VISUAL_ONLY_GLOBS` the visual workflow adds for itself, per
  * Question 2 in `.canon/plans/archive/feature-render-visibility.md`. A YAML
  * anchor cannot cross files here, so the two copies are read live and compared
@@ -1478,142 +1474,3 @@ async function collectPluginManifests(ctx: MeasureContext): Promise<string[]> {
   )
   return [...seen].sort()
 }
-
-/**
- * A capture set spans two folders. The markup and the template beside it are
- * the authored half and sit under `assets/captures/`, while the image a
- * document points at and the stamp answering for it sit under
- * `assets/frames/`, which is where `--out assets/frames` sends them. They sit
- * outside `assets/evidence/` so a changed marketing image is not read as dev
- * evidence.
- */
-const CAPTURE_MARKUP_DIR = 'assets/captures'
-const CAPTURE_OUTPUT_DIR = 'assets/frames'
-
-/**
- * Every capture under `assets/captures/`, named by the base its three files
- * share.
- *
- * Read off the folder rather than listed, and off the markup specifically,
- * because that is how `resolveCaptureSources` decides what `canon capture
- * assets/captures` renders. A list would fail open on the frame somebody adds
- * next, which is the one nobody thinks to add here, and driving off the PNGs
- * instead would report a missing set for any image in `assets/` that is not a
- * capture.
- */
-function captureBases(root: string): string[] {
-  const dir = join(root, CAPTURE_MARKUP_DIR)
-  if (!existsSync(dir)) return []
-
-  return readdirSync(dir)
-    .filter((name) => name.endsWith('.html'))
-    .map((name) => name.slice(0, -'.html'.length))
-    .sort()
-}
-
-/**
- * The drift assert on the Hero stage covers the markup because the image beside
- * it is a chromium render whose bytes move with the browser. That leaves the
- * artifact a visitor actually sees asserted nowhere, so a branch regenerating
- * the markup and never running the capture would pass every stage while
- * shipping an image with the old counts.
- *
- * `canon capture` records a digest of the markup it rendered and one of the image
- * it wrote, so this reads provenance rather than timing. Comparing the commit
- * that last touched each file passes any pair that moved together whatever the
- * two files hold, which is what a binary conflict resolved by taking either
- * side produces.
- *
- * Both digests are checked because either file can move alone. The markup side
- * catches an edit committed with no capture, and the image side catches an
- * image replaced under markup that never changed. A tree carrying no markup
- * under `assets/captures/` has no set to read and passes, which is correct.
- */
-export const captureStamps: Measure = async (ctx) => {
-  const lines = captureBases(ctx.root).flatMap((base) =>
-    readCaptureSet(ctx.root, base),
-  )
-  if (lines.length === 0) return { emissions: [] }
-
-  return {
-    emissions: [output(lines.join('\n'))],
-    failure: CAPTURE_STAMP_FAILURE,
-  }
-}
-
-/**
- * One capture set, as the lines it has to report and none where it agrees.
- *
- * The markup resolves against the source folder and the two files a render
- * writes resolve against the output folder, so the set spans both rather than
- * hanging off one base directory. Sending any of the three to the wrong folder
- * reports it as missing rather than failing loudly, since a missing file reads
- * the same way whether the path is wrong or the file is.
- */
-function readCaptureSet(root: string, base: string): string[] {
-  const set = [
-    `${CAPTURE_MARKUP_DIR}/${base}.html`,
-    `${CAPTURE_OUTPUT_DIR}/${base}.png`,
-    `${CAPTURE_OUTPUT_DIR}/${base}.stamp`,
-  ]
-
-  const missing = set.filter((rel) => !existsSync(join(root, rel)))
-  if (missing.length > 0) {
-    return [`Missing from the ${base} set: ${missing.join(' ')}`]
-  }
-
-  const [html, png, stamp] = set.map((rel) => join(root, rel))
-  return [
-    ...assertStampField(root, stamp, 'source-sha256', html),
-    ...assertStampField(root, stamp, 'image-sha256', png),
-  ]
-}
-
-/**
- * One digest the stamp recorded against the file it was taken over, returning
- * the lines to report and nothing when the two agree.
- *
- * An absent field reports itself rather than comparing against an empty string,
- * so a stamp predating the current format is distinguishable from a file that
- * moved. Both names in the message come off the paths rather than from
- * arguments, which is what keeps a name from disagreeing with the file it
- * labels once a second capture source calls this.
- */
-export function assertStampField(
-  root: string,
-  stamp: string,
-  field: string,
-  file: string,
-): string[] {
-  const stampLabel = relativeTo(root, stamp)
-  const fileLabel = relativeTo(root, file)
-
-  const recorded = readStampField(stamp, field)
-  if (recorded === undefined) {
-    return [
-      `${stampLabel} carries no ${field} line, so it predates the capture that writes one.`,
-    ]
-  }
-
-  const actual = createHash('sha256').update(readFileSync(file)).digest('hex')
-  if (recorded !== actual) {
-    return [
-      `${stampLabel} records ${field} ${recorded}`,
-      `${fileLabel} hashes to ${actual}`,
-    ]
-  }
-
-  return []
-}
-
-function readStampField(stamp: string, field: string): string | undefined {
-  for (const line of readFileSync(stamp, 'utf8').split('\n')) {
-    const [key, value] = line.trim().split(/\s+/)
-    if (key === `${field}:` && value !== undefined) return value
-  }
-  return undefined
-}
-
-function relativeTo(root: string, path: string): string {
-  return path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path
-}

package/src/gate/sequencer.ts

@@ -386,7 +386,13 @@ async function runCheck(
   }
 
   const run = check.kind === 'cli' ? ctx.cli : ctx.run
-  const result = await run(check.argv, env)
+  const argv =
+    check.kind === 'command' &&
+    check.changedArgv !== undefined &&
+    ctx.changed !== undefined
+      ? check.changedArgv(ctx.changed)
+      : check.argv
+  const result = await run(argv, env)
   return {
     emissions: [{ kind: 'output', text: result.all }],
     failure: result.exitCode === 0 ? undefined : check.failure,