@erclx/canon 5.33.0 → 5.35.0

package/src/commands/pr.ts

@@ -48,15 +48,27 @@ import {
   FRAMES_BRANCH,
   type FramesApi,
   type FramesRefusal,
+  type FrameTheme,
   frameLink,
   isFrameHead,
   isFramePass,
+  isFrameTheme,
   pruneFrames,
   pushFrame,
   readFrame,
   type TreeEntry,
 } from '@/pr/frames'
 import { type HeadRefusal, resolveHead, resolveTip } from '@/pr/head'
+import {
+  DEFAULT_WAIT_SECONDS,
+  type EvidenceGate,
+  type GitRunner,
+  lift,
+  type LiftApi,
+  type LiftRefusal,
+  type PullState,
+  readBaseStanding,
+} from '@/pr/lift'
 import {
   dropAddressLine,
   findLocalServer,
@@ -82,6 +94,7 @@ import { type TickRefusal, tickBoxes } from '@/pr/tick'
 import {
   commentRowOf,
   identityOf,
+  mergeStateOf,
   type PullIdentity,
   parseJsonLines,
   type RestComment,
@@ -91,6 +104,7 @@ import {
   selectBranchPull,
 } from '@/pr/rest'
 import { resolveReviewScope } from '@/pr/review-scope'
+import { PROJECT_ROOT } from '@/roots/project'
 import { intro, logInfo, logStep, logWarn, outro, plural } from '@/cli/ui'
 
 const GH_TIMEOUT_MS = 30_000
@@ -117,6 +131,11 @@ interface EvidenceOptions extends ReadOptions {
   readonly check?: boolean
 }
 
+interface LiftCommandOptions extends ReadOptions {
+  readonly check?: boolean
+  readonly wait?: string
+}
+
 interface LocalOptions extends ReadOptions {
   readonly remove?: boolean
 }
@@ -164,6 +183,7 @@ interface FramesOptions extends ReadOptions {
   readonly box?: string
   readonly head?: string
   readonly pass?: string
+  readonly theme?: string
   readonly drop?: boolean
   readonly prune?: string
 }
@@ -175,6 +195,7 @@ type FramesCommandRefusal =
   | 'bad-box'
   | 'bad-head'
   | 'bad-pass'
+  | 'bad-theme'
   | 'bad-days'
   | 'unreadable-frame'
   | 'read-only'
@@ -193,6 +214,8 @@ const FRAMES_REFUSALS: Record<FramesCommandRefusal, string> = {
     '--head takes a commit sha, 7 to 40 lowercase hex characters. A branch name or a path would file the frame under a folder that names no commit.',
   'bad-pass':
     '--add takes --pass <stamp>, the instant the pass started in compact UTC such as 20261002T154450Z, so a second pass never replaces an earlier one.',
+  'bad-theme':
+    '--theme takes dark or light and goes with --add, so a second shot of one box never replaces the first.',
   'bad-days': '--prune takes a positive whole number of days.',
   'unreadable-frame':
     'The file named by --add is missing, empty, or not a PNG, so it would embed as a broken image. Nothing is pushed.',
@@ -650,6 +673,62 @@ export function register(program: Command): void {
       process.exitCode = await runEvidence(number, opts)
     })
 
+  pr.command('lift')
+    .description(
+      "Lift a pull request's draft mark once its reviews, evidence, standing, and CI all read clear at the head",
+    )
+    .argument('[number]', 'Pull request to lift, defaulting to this branch')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--check', 'Report every gate and write nothing')
+    .option(
+      '--wait <seconds>',
+      `Hold for a pending CI run up to this long, default ${DEFAULT_WAIT_SECONDS}`,
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'The verb reads the gate itself, so any session that closes a review can',
+        'run it and nobody has to vouch for who is asking. Gates, in the order',
+        'they are read:',
+        '  review    the newest `## Review` is closed at the head, off its marker',
+        '  ui        the newest `## UI review` is closed at the head, bound only',
+        '            where `canon pr evidence --check` carries a checklist',
+        '  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',
+        '',
+        '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',
+        'head and the reviews are read again before the mutation.',
+        '',
+        'Reasons:',
+        '  lifted, already-ready, clear (--check)',
+        '  pull-closed, review-missing, review-open, review-unmarked,',
+        '  review-behind, ui-missing, ui-open, ui-unmarked, ui-behind,',
+        '  evidence-owed, standing-stale, standing-conflict, standing-unknown,',
+        '  ci-pending (--check), ci-failing, ci-conflicted, ci-timeout,',
+        '  head-moved, gh-failed',
+        '',
+        'Every read is REST. The mutation is the one GraphQL call.',
+        '',
+        'Exit codes:',
+        '  0  lifted, already-ready, or every gate clear under --check',
+        '  1  refused, with the reason in the JSON record',
+        '',
+        'Examples:',
+        '  canon pr lift 1341 --json',
+        '  canon pr lift 1341 --check --json',
+        '  canon pr lift --wait 600',
+        '',
+      ].join('\n'),
+    )
+    .action(async (number: string | undefined, opts: LiftCommandOptions) => {
+      process.exitCode = await runLift(number, opts)
+    })
+
   pr.command('preview')
     .description(
       "Deploy the pull request's branch to a Cloudflare Pages preview and report its address",
@@ -841,6 +920,10 @@ export function register(program: Command): void {
       '--pass <stamp>',
       'The instant the pass started, in compact UTC such as 20261002T154450Z, with --add',
     )
+    .option(
+      '--theme <theme>',
+      'The theme the frame was shot at, dark or light, with --add, keeping two shots of one box apart',
+    )
     .option('--drop', "Rewrite the branch without this pull request's frames")
     .option(
       '--prune <days>',
@@ -852,7 +935,8 @@ export function register(program: Command): void {
         '',
         `Writes only refs/heads/${FRAMES_BRANCH}, through the GitHub git data API,`,
         'so nothing is checked out and no other branch is touched. A frame lands',
-        'at pr-<number>/<short-head>/<pass>/box-<n>.png, and `link` names that',
+        'at pr-<number>/<short-head>/<pass>/box-<n>.png, or box-<n>-<theme>.png',
+        'with --theme, and `link` names that',
         `path on ${FRAMES_BRANCH}, so it survives a rewrite that drops other pull`,
         'requests and resolves until its own pull request is dropped. The pass',
         'segment keeps a second pass at one head and box from replacing an image',
@@ -871,6 +955,7 @@ export function register(program: Command): void {
         '  bad-box           --add without a positive --box',
         '  bad-head          --head is not 7 to 40 lowercase hex characters',
         '  bad-pass          --add without a compact UTC --pass stamp',
+        '  bad-theme         --theme is not dark or light, or no --add',
         '  bad-days          --prune without a positive number of days',
         '  unreadable-frame  the --add file is missing, empty, or not a PNG',
         '  read-only         GitHub refused the write, as on a fork token',
@@ -2906,6 +2991,12 @@ function framesArgumentRefusal(
   ) {
     return 'bad-pass'
   }
+  if (
+    opts.theme !== undefined &&
+    (opts.add === undefined || !isFrameTheme(opts.theme))
+  ) {
+    return 'bad-theme'
+  }
   return undefined
 }
 
@@ -3005,11 +3096,13 @@ async function runFrames(
 
   const box = Number(opts.box)
   const pass = opts.pass ?? ''
+  const theme = opts.theme as FrameTheme | undefined
   const result = await pushFrame(api, {
     number: pull,
     head,
     pass,
     box,
+    theme,
     bytes: bytes ?? new Uint8Array(),
   })
   if (result.kind === 'refused') return refuseWrite(result.reason)
@@ -3018,6 +3111,7 @@ async function runFrames(
     {
       number: pull,
       box,
+      ...(theme === undefined ? {} : { theme }),
       head,
       pass,
       path: result.path,
@@ -3029,6 +3123,287 @@ async function runFrames(
   )
 }
 
+const LIFT_REFUSALS: Record<LiftRefusal | 'bad-wait' | 'gh-missing', string> = {
+  'bad-wait': '--wait takes a whole number of seconds, zero or more.',
+  'gh-missing': PULL_REFUSALS['gh-missing'],
+  'pull-closed': 'The pull request is closed, so there is no mark to lift.',
+  'review-missing': 'The thread carries no code review, so none has closed.',
+  'review-open':
+    'The newest code review is open, so a finding still owes a fix.',
+  'review-unmarked':
+    'The newest code review carries no read-time marker, so the commit it covers is a GitHub stamp this gate does not trust.',
+  'review-behind':
+    'The newest code review closed on an earlier commit than the head.',
+  'ui-missing':
+    'The evidence comment carries a checklist and no UI review has been posted.',
+  'ui-open': 'The newest UI review is open, so a box still owes a fix.',
+  'ui-unmarked':
+    'The newest UI review carries no head marker, so the commit it covers is a GitHub stamp this gate does not trust.',
+  'ui-behind':
+    'The newest UI review closed on an earlier commit than the head.',
+  'evidence-owed':
+    'The evidence check reads owed, so the ship chain left a step undone.',
+  'standing-stale':
+    'The base moved under a path this branch writes since it branched, so CI measured a tree that is gone.',
+  'standing-conflict': 'The head does not merge cleanly into the base.',
+  'standing-unknown':
+    'The head or the base did not resolve, which a fork or a deleted head leaves, so its standing is unread and waits on a person.',
+  'ci-pending': 'A check run on the tip has yet to conclude.',
+  'ci-failing': 'A check run on the tip failed.',
+  'ci-conflicted':
+    'The branch conflicts with its base, so no run will start for the tip.',
+  'ci-timeout': 'A check run was still pending when --wait ran out.',
+  'head-moved':
+    'A push landed during the wait, so the gates cleared a commit that is no longer the head.',
+  'gh-failed':
+    'A read or the mutation was refused, so nothing is reported as lifted.',
+}
+
+const READY_MUTATION =
+  'mutation($id: ID!) { markPullRequestReadyForReview(input: {pullRequestId: $id}) { pullRequest { isDraft } } }'
+
+function gitRunner(root: string): GitRunner {
+  return async (args) => {
+    const result = await execa('git', ['-C', root, ...args], {
+      reject: false,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    })
+    return result.exitCode === 0 ? String(result.stdout) : undefined
+  }
+}
+
+/**
+ * Reads the evidence check through this checkout's own CLI rather than a
+ * second copy of its logic, so the lift and a caller running
+ * `canon pr evidence --check` read one answer.
+ */
+async function readEvidenceGate(
+  root: string,
+  number: string,
+): Promise<EvidenceGate | undefined> {
+  const result = await execa(
+    process.execPath,
+    [
+      join(PROJECT_ROOT, 'src', 'cli.ts'),
+      'pr',
+      'evidence',
+      number,
+      '--check',
+      '--json',
+      '--root',
+      root,
+    ],
+    {
+      cwd: root,
+      reject: false,
+      timeout: GH_TIMEOUT_MS * 2,
+      env: { ...gitEnv(), CANON_NON_INTERACTIVE: '1' },
+      extendEnv: false,
+    },
+  )
+  const last = String(result.stdout)
+    .split('\n')
+    .filter((line) => line.trim() !== '')
+    .at(-1)
+  if (last === undefined) return undefined
+
+  let record: { reason?: unknown; owed?: unknown; checklist?: unknown }
+  try {
+    record = JSON.parse(last)
+  } catch {
+    return undefined
+  }
+  if (record.reason !== 'settled' && record.reason !== 'owed') return undefined
+
+  return {
+    isSettled: record.reason === 'settled',
+    owed: Array.isArray(record.owed) ? record.owed.map(String) : [],
+    hasChecklist:
+      typeof record.checklist === 'string' && record.checklist !== '',
+  }
+}
+
+function liftApi(root: string, number: string, baseRef: string): LiftApi {
+  const git = gitRunner(root)
+
+  return {
+    readPull: async (): Promise<PullState | undefined> => {
+      const stdout = await gh(root, [
+        'api',
+        `repos/{owner}/{repo}/pulls/${number}`,
+      ])
+      if (stdout === null) return undefined
+      try {
+        const row = JSON.parse(stdout) as RestPull
+        if (row.node_id === undefined || row.head?.ref === undefined) {
+          return undefined
+        }
+        return {
+          isDraft: row.draft === true,
+          isOpen: row.state === 'open',
+          nodeId: row.node_id,
+          branch: row.head.ref,
+          head: row.head.sha ?? '',
+        }
+      } catch {
+        return undefined
+      }
+    },
+    readTip: async (branch) => {
+      const resolved = await resolveTip(branch, refReader(root))
+      return resolved.kind === 'read' ? resolved.tip : undefined
+    },
+    readReviews: async () => {
+      const reviews = await listReviews(root, number)
+      return reviews.kind === 'read' ? reviews.rows.map(reviewRowOf) : undefined
+    },
+    readEvidence: () => readEvidenceGate(root, number),
+    readStanding: (head) =>
+      readBaseStanding(git, Number(number), head, baseRef),
+    readChecks: async (tip) => {
+      const [listed, pulled] = await Promise.all([
+        gh(root, [
+          'api',
+          `repos/{owner}/{repo}/commits/${tip}/check-runs?per_page=100`,
+        ]),
+        gh(root, ['api', `repos/{owner}/{repo}/pulls/${number}`]),
+      ])
+      if (listed === null) return undefined
+      try {
+        const mergeState =
+          pulled === null
+            ? undefined
+            : mergeStateOf((JSON.parse(pulled) as RestPull).mergeable_state)
+        const reading = withMergeState(
+          mergeState,
+          collapseChecks(tip, JSON.parse(listed) as CheckRunListing),
+        )
+        return { state: reading.state, isConflicted: reading.conflicted }
+      } catch {
+        return undefined
+      }
+    },
+    markReady: async (nodeId) => {
+      const result = await execa(
+        'gh',
+        [
+          'api',
+          'graphql',
+          '-f',
+          `query=${READY_MUTATION}`,
+          '-f',
+          `id=${nodeId}`,
+        ],
+        {
+          cwd: root,
+          reject: false,
+          timeout: GH_TIMEOUT_MS,
+          env: gitEnv(),
+          extendEnv: false,
+        },
+      )
+      if (result.exitCode !== 0) return false
+      // The flag is read back rather than the exit trusted, since the
+      // mutation can answer 200 with an errors array and no change.
+      try {
+        const body = JSON.parse(String(result.stdout)) as {
+          data?: {
+            markPullRequestReadyForReview?: {
+              pullRequest?: { isDraft?: boolean }
+            }
+          }
+        }
+        return (
+          body.data?.markPullRequestReadyForReview?.pullRequest?.isDraft ===
+          false
+        )
+      } catch {
+        return false
+      }
+    },
+    sleep: (ms) => new Promise((done) => setTimeout(done, ms)),
+    now: () => Date.now(),
+  }
+}
+
+async function runLift(
+  number: string | undefined,
+  opts: LiftCommandOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('canon pr lift')
+
+  let waitSeconds = DEFAULT_WAIT_SECONDS
+  if (opts.wait !== undefined) {
+    if (!/^\d+$/.test(opts.wait)) {
+      return refuseWith('bad-wait', LIFT_REFUSALS['bad-wait'], emitJson, root)
+    }
+    waitSeconds = Number(opts.wait)
+  }
+
+  if (Bun.which('gh') === null) {
+    return refuseWith('gh-missing', LIFT_REFUSALS['gh-missing'], emitJson, root)
+  }
+
+  const resolved = await resolvePullNumber(root, number)
+  if (resolved.kind === 'refused') {
+    return refuseWith(
+      resolved.reason,
+      PULL_REFUSALS[resolved.reason],
+      emitJson,
+      root,
+    )
+  }
+
+  // Read once up front for the base the standing is measured against. The
+  // injected `readPull` re-reads the object on every gate that needs it.
+  const initial = await readPull(root, resolved.number)
+  if (initial.kind === 'refused') {
+    return refuseWith(
+      initial.reason,
+      PULL_REFUSALS[initial.reason],
+      emitJson,
+      root,
+    )
+  }
+  const base = initial.row.base?.ref
+  if (base === undefined || base === '') {
+    return refuseWith('gh-failed', LIFT_REFUSALS['gh-failed'], emitJson, root)
+  }
+
+  const record = await lift(liftApi(root, resolved.number, `origin/${base}`), {
+    isCheck: opts.check ?? false,
+    waitSeconds,
+  })
+
+  logStep(record.reason)
+  logInfo(
+    record.reason === 'lifted'
+      ? `#${resolved.number} is ready for review at ${record.head?.slice(0, 8)}`
+      : record.reason === 'already-ready'
+        ? `#${resolved.number} is already ready for review`
+        : record.reason === 'clear'
+          ? `every gate reads clear for #${resolved.number}`
+          : LIFT_REFUSALS[record.reason],
+  )
+  for (const gate of record.gates) {
+    if (!gate.isOk) logWarn(`${gate.gate}: ${gate.reason ?? 'not clear'}`)
+  }
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ root, number: Number(resolved.number), ...record })}\n`,
+    )
+  }
+
+  return record.isOk ? 0 : 1
+}
+
 /**
  * Frames a refusal on stderr in both modes and puts the record on stdout alone,
  * so an operator reading the terminal sees the reason rather than a command

package/src/commands/records.ts

@@ -29,7 +29,6 @@ import {
 import {
   type Finding,
   isRecordKind,
-  isSharedScratch,
   RECORD_KINDS,
   type RecordKind,
   type ValidateOutcome,
@@ -92,10 +91,7 @@ export function register(program: Command): void {
     .argument('<kind>', `Record folder: ${RECORD_KINDS.join(', ')}`)
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Add a machine-readable record on stdout')
-    .option(
-      '--root <path>',
-      'Project root, defaulting to the main worktree except on standards',
-    )
+    .option('--root <path>', 'Project root, defaulting to the main worktree')
     .addHelpText(
       'after',
       [
@@ -104,8 +100,6 @@ export function register(program: Command): void {
         '  plans       filename, required sections, and the suggested-and-answer contract',
         '  groundwork  README and current-state files, numbering, dating, and a half-closed track',
         '  intake      overview file, numbering, dating, and the four bullets every item carries',
-        '  standards   frontmatter, the scope section and its handoff list, and a filename',
-        '              derived from the governed path',
         '',
         'Exit codes:',
         '  0  every check passed',
@@ -113,12 +107,11 @@ export function register(program: Command): void {
         '  2  at least one record carries a finding',
         '',
         'It reports and never writes, so a session fixes what the report names. A',
-        'session record has no history to undo a wrong repair from, and a standard',
-        'is installed and cited everywhere, so a rename is larger than a file move.',
+        'session record has no history to undo a wrong repair from.',
         '',
         'Examples:',
         '  canon records validate plans',
-        '  canon records validate standards',
+        '  canon records validate teach',
         '  canon records validate intake --json',
         '',
       ].join('\n'),
@@ -718,15 +711,6 @@ function reportRefusal(
   return 1
 }
 
-/**
- * A shared-scratch kind reads the main worktree root, so a linked worktree
- * validates the records every other session reads. A tracked corpus reads the
- * checkout the caller stands in, which is the copy that session has edited.
- */
-function defaultRoot(kind: RecordKind): Promise<string> {
-  return isSharedScratch(kind) ? mainWorktreeRoot() : currentWorktreeRoot()
-}
-
 async function runValidate(
   kind: string,
   opts: ValidateCommandOptions,
@@ -745,7 +729,7 @@ async function runValidate(
     )
   }
 
-  const root = opts.root ?? (await defaultRoot(kind))
+  const root = opts.root ?? (await mainWorktreeRoot())
 
   return report(await validateWithStacks(root, kind), emitJson, root)
 }

package/src/commands/tooling.ts

@@ -99,8 +99,7 @@ export function register(program: Command): void {
         '  canon tooling sync vite-react web --skip base',
         '',
         'A target below its git root syncs as a subfolder. It withholds',
-        '.github/, which GitHub reads only at the root, and writes a nested',
-        'cspell.json registering the stack word lists.',
+        '.github/, which GitHub reads only at the root.',
         '',
         'To gate CI on tooling drift, run headlessly with neither flag. That',
         'exits 1 when a file would be replaced and 0 when none would, which is',
@@ -276,8 +275,7 @@ function runList(opts: ListOptions): number {
 
 /**
  * Writes the reference to stdout and every frame line to stderr, so a caller
- * capturing the output with `$(...)` receives the document alone. Mirrors
- * `print` in `src/commands/standards.ts`.
+ * capturing the output with `$(...)` receives the document alone.
  */
 function printReference(stack: string): number {
   intro('canon tooling reference')

package/src/counts/catalogs.ts

@@ -3,7 +3,6 @@ import { join } from 'node:path'
 import { AUDITS } from '@/audits/catalog'
 import { listSkills } from '@/claude/skills-list'
 import { buildGovCatalog } from '@/gov/list'
-import { listStandards } from '@/standards/read'
 
 export interface Catalog {
   readonly id: string
@@ -59,11 +58,6 @@ export const CATALOGS: readonly Catalog[] = [
     nouns: ['rule', 'rules'],
     count: (root) => buildGovCatalog(root).rules.length,
   },
-  {
-    id: 'standards',
-    nouns: ['standard', 'standards'],
-    count: (root) => listStandards(root).length,
-  },
   {
     id: 'commands',
     nouns: ['command', 'commands'],

package/src/feedback/body.ts

@@ -18,13 +18,18 @@ export const REQUIRED_FIELDS = ['Surface', 'Observed', 'Proposed fix'] as const
  * retire, and the validator would then enforce nothing.
  */
 const FIELD_HEADING = /^###\s+(.+?)\s*$/
-const FENCE = /^\s*(```|~~~)/
+const FENCE = /^\s*(`{3,}|~{3,})(.*)$/
+
+interface OpenFence {
+  readonly marker: string
+  readonly length: number
+}
 
 export function parseSections(body: string): Map<string, string> {
   const sections = new Map<string, string>()
   let heading: string | undefined
   let lines: string[] = []
-  let fenced = false
+  let fence: OpenFence | undefined
 
   const flush = (): void => {
     if (heading === undefined) return
@@ -34,9 +39,25 @@ export function parseSections(body: string): Map<string, string> {
   for (const line of body.split('\n')) {
     // A Repro field routinely carries a fenced block, and a `###` comment
     // inside one is shell rather than the next field. Reading it as a heading
-    // splits the section and drops everything under it.
-    if (FENCE.test(line)) fenced = !fenced
-    const match = fenced ? null : line.match(FIELD_HEADING)
+    // splits the section and drops everything under it. A Suggested shape
+    // wraps a template that holds its own fence in a longer one, so a fence
+    // closes only on the same marker at least as long, per CommonMark.
+    const fenceMatch = line.match(FENCE)
+    const run = fenceMatch?.[1]
+    if (run !== undefined) {
+      const marker = run.charAt(0)
+      const isBare = (fenceMatch?.[2] ?? '').trim() === ''
+      if (fence === undefined) {
+        fence = { marker, length: run.length }
+      } else if (
+        isBare &&
+        marker === fence.marker &&
+        run.length >= fence.length
+      ) {
+        fence = undefined
+      }
+    }
+    const match = fence ? null : line.match(FIELD_HEADING)
     if (match?.[1] === undefined) {
       lines.push(line)
       continue

package/src/gate/boundaries.ts

@@ -337,8 +337,8 @@ export const capabilitySeeding: Measure = async (ctx) => {
  * Every file under `claude/` resolved through its symlinks and rejected when it
  * lands under `internal/`.
  *
- * The plugin reaches `standards/` through a symlink, which an installer
- * dereferences with no code in the path to filter. Walking with symlinks
+ * An installer dereferences any symlink under the plugin root with no code in
+ * the path to filter, so a link added there ships whatever it points at. Walking with symlinks
  * followed is what an install copies, so this is the only place the boundary
  * can be measured. The walk tracks the real directories on its current descent
  * and does not enter one a second time, the way `find -L` stops on a loop.