@erclx/canon 5.47.0 → 5.49.0

package/src/commands/records.ts

@@ -31,6 +31,7 @@ import {
   RECORD_KINDS,
   type RecordKind,
   type ValidateOutcome,
+  type StructureFinding,
   validateRecords,
 } from '@/records/validate'
 import {
@@ -89,6 +90,10 @@ export function register(program: Command): void {
     .command('validate')
     .description('Report where a file and the standard governing it disagree')
     .argument('<kind>', `Record folder: ${RECORD_KINDS.join(', ')}`)
+    .argument(
+      '[record]',
+      'One plan stem or folder slug, narrowing both findings and structure to it',
+    )
     .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')
@@ -101,12 +106,18 @@ export function register(program: Command): void {
         '  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',
         '',
+        'Structure, under `structure` and never in the exit:',
+        "  S1 to S5 from the plan standard, read on plans, a track's README and",
+        '  numbered files, and intake clusters, plus intake-spill for content under',
+        '  a field. A record written before the criteria misses S1, so it reports alone.',
+        '',
         'Refusals, read off `reason`:',
         "  no-folder     none of the kind's directories exist at either record root",
+        '  no-record     the folder holds no record by the name given',
         '  unknown-kind  the argument names no published kind',
         '',
         'Exit codes:',
-        '  0  every check passed',
+        '  0  no record carries a finding, whatever structure reports',
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  at least one record carries a finding',
         '',
@@ -115,14 +126,21 @@ export function register(program: Command): void {
         '',
         'Examples:',
         '  canon records validate plans',
+        '  canon records validate plans feature-records-by-heading',
         '  canon records validate teach',
         '  canon records validate intake --json',
         '',
       ].join('\n'),
     )
-    .action(async (kind: string, opts: ValidateCommandOptions) => {
-      process.exitCode = await runValidate(kind, opts)
-    })
+    .action(
+      async (
+        kind: string,
+        record: string | undefined,
+        opts: ValidateCommandOptions,
+      ) => {
+        process.exitCode = await runValidate(kind, record, opts)
+      },
+    )
 
   records
     .command('ordinal')
@@ -721,6 +739,7 @@ function reportRefusal(
 
 async function runValidate(
   kind: string,
+  record: string | undefined,
   opts: ValidateCommandOptions,
 ): Promise<number> {
   const emitJson = opts.json ?? false
@@ -739,7 +758,11 @@ async function runValidate(
 
   const root = opts.root ?? (await mainWorktreeRoot())
 
-  return report(await validateWithStacks(root, kind), emitJson, root)
+  // A plan named with its extension and without it is one record, so the walk
+  // and the cross-plan filter below both read the bare stem.
+  const stem = record?.replace(/\.md$/, '')
+
+  return report(await validateWithStacks(root, kind, stem), emitJson, root)
 }
 
 /**
@@ -749,18 +772,21 @@ async function runValidate(
 async function validateWithStacks(
   root: string,
   kind: RecordKind,
+  record: string | undefined,
 ): Promise<ValidateOutcome> {
-  const outcome = await validateRecords(root, kind)
+  const outcome = await validateRecords(root, kind, record)
   if (!outcome.ok || kind !== 'plans') return outcome
 
   const live = await readLivePlans(root)
+  const across = [...stackFindings(live), ...fanInFindings(live)]
 
   return {
     ...outcome,
     findings: [
       ...outcome.findings,
-      ...stackFindings(live),
-      ...fanInFindings(live),
+      ...(record === undefined
+        ? across
+        : across.filter((found) => found.record === `${record}.md`)),
     ],
   }
 }
@@ -801,6 +827,7 @@ function report(
         kind: outcome.kind,
         records: outcome.records,
         findings: outcome.findings,
+        structure: outcome.structure,
       })}\n`,
     )
   } else {
@@ -814,6 +841,11 @@ function report(
     } else {
       for (const found of outcome.findings) logWarn(describe(found))
     }
+
+    if (outcome.structure.length > 0) {
+      logStep('Structure, reported and never in the exit')
+      for (const entry of outcome.structure) logInfo(describeStructure(entry))
+    }
     outro()
   }
 
@@ -825,6 +857,11 @@ function describe(found: Finding): string {
   return `${scope}${found.subject} ${found.message}`
 }
 
+function describeStructure(entry: StructureFinding): string {
+  const scope = entry.record === entry.subject ? '' : `${entry.record}/`
+  return `${entry.criterion} ${scope}${entry.subject}:${entry.line} ${entry.message}`
+}
+
 async function runOrdinal(
   kind: string,
   slug: string,

package/src/commands/tasks.ts

@@ -222,6 +222,11 @@ export function register(program: Command): void {
         'listed, and pending-branch while a Pending branch: line names a branch',
         'whose own pull request is not recorded yet. A stem skips both.',
         '',
+        'On an earlier-slice or open-outcomes refusal from --pull-request, the',
+        'slice plan whose derived branch is the pull request head, read through',
+        'gh, moves to the plans archive and the task stays open. The record',
+        'names it under `slice`.',
+        '',
         'Refusals, read off `reason`:',
         '  no-board        the repository holds no `.canon/tasks/` board',
         '  no-match        no task matches the selector',
@@ -680,7 +685,9 @@ export function register(program: Command): void {
         '                  the last listed, so a later number closes the issue',
         '  lookup-failed   the pull request lookup failed while the task already',
         '                  lists a pull request, so an earlier slice cannot be ruled out',
-        '  open-outcomes   an outcome is still open, so a later slice closes it',
+        '  open-outcomes   an outcome is still open, so a later slice closes it.',
+        '                  A `- [ ] Operator check: <outcome>` line holds nothing open and',
+        '                  is listed under `operatorChecks`',
         '  pending-branch  another branch is on `Pending branch:`',
         '  no-outcomes     the task carries no outcomes',
         '',
@@ -1544,6 +1551,7 @@ function reportCloses(
         issues: outcome.issues,
         closing: outcome.closing,
         reason: outcome.reason,
+        operatorChecks: outcome.operatorChecks ?? [],
       })}\n`,
     )
     return 0
@@ -1556,6 +1564,9 @@ function reportCloses(
       ? `${outcome.stem} names ${outcome.issues.map((n) => `#${n}`).join(', ')}, ${outcome.reason}`
       : `${outcome.stem} names no issue`,
   )
+  for (const check of outcome.operatorChecks ?? []) {
+    logInfo(`operator check: ${check}`)
+  }
   outro()
 
   return 0
@@ -2181,6 +2192,10 @@ function report(
     logStep('Refused')
     logError(outcome.message)
     if (outcome.detail.length > 0) pipeOutput(outcome.detail.join('\n'))
+    if (outcome.slice) {
+      logStep('Slice plan archived')
+      logPlanMoves([outcome.slice], root)
+    }
     outro()
     return 1
   }
@@ -2199,6 +2214,7 @@ function report(
   logRelinked(outcome.relinked, outcome.relinkFailed, root)
   if (outcome.indexRegenerated) logInfo('regenerated index.md')
   if (outcome.cut > 0) logInfo(`${outcome.cut} outcome(s) cut`)
+  for (const check of outcome.operatorChecks) logInfo(check)
   outro()
 
   return 0
@@ -2269,6 +2285,9 @@ function recordFor(
       reason: outcome.reason,
       message: outcome.message,
       detail: outcome.detail,
+      ...(outcome.slice
+        ? { slice: planMovesFor([outcome.slice], root)[0] }
+        : {}),
     }
   }
 
@@ -2289,6 +2308,7 @@ function recordFor(
       : null,
     closed: outcome.closed,
     cut: outcome.cut,
+    operatorChecks: outcome.operatorChecks,
     relinked: relinkedFor(outcome.relinked, root),
     relinkFailed: relinkFailedFor(outcome.relinkFailed, root),
   }

package/src/hooks/post-merge.ts

@@ -161,8 +161,19 @@ function archiveLines(
   if (reason === undefined || reason === 'no-match' || reason === 'no-board') {
     return undefined
   }
+  // A merged slice moves its own plan while the task stays open, so the line
+  // names the plan that dropped off the board row.
+  const slice =
+    fields.slice !== null && typeof fields.slice === 'object'
+      ? text(fields.slice as Fields, 'from')
+      : undefined
+  const moved =
+    slice === undefined
+      ? ''
+      : `🗂️  Archived the slice plan ${slice}, and the task stays open.\n`
   return (
     `\n📋 Task not archived for #${number}: ${text(fields, 'message') ?? reason}\n` +
+    moved +
     `Run /task-complete archive #${number} to resolve it by hand.\n\n`
   )
 }

package/src/migrate/session-defaults.ts

@@ -1,6 +1,7 @@
 /**
  * Adds the session defaults the seeded `.claude/settings.json` carries to a
- * target that was seeded before them.
+ * target that was seeded before them: the subagent deny, the memory default, and
+ * the merge deny entries.
  *
  * `canon claude init` copies a seed only when the file is absent, so a target
  * holding its own settings never sees a later seed change. This verb adds each
@@ -21,6 +22,12 @@ import {
 /** Both names, since `Task` is the tool's name before Claude Code renamed it. */
 export const DENIED_TOOLS: readonly string[] = ['Agent', 'Task']
 
+/** The merge entries the seeded deny list carries, so a session cannot merge. */
+export const MERGE_DENIED: readonly string[] = [
+  'Bash(canon pr merge:*)',
+  'Bash(gh pr merge:*)',
+]
+
 export interface SessionDefaultsPlan {
   readonly keys: readonly SettingsKey[]
   readonly next: SettingsRecord
@@ -31,6 +38,8 @@ export interface SessionDefaultsPlan {
    * on purpose, which is how an operator opts back into subagents.
    */
   readonly predates: boolean
+  /** True when the deny list lacks any merge entry, whatever else it holds. */
+  readonly lacksMergeDeny: boolean
 }
 
 export type SessionDefaultsRead =
@@ -52,8 +61,8 @@ function isRecord(value: unknown): value is SettingsRecord {
 }
 
 /**
- * Appends the denied tools a list lacks, keeping the list's own order, so the
- * diff a person reads is the added entries alone.
+ * Appends the denied tools and merge entries a list lacks, keeping the list's
+ * own order, so the diff a person reads is the added entries alone.
  */
 export function planSessionDefaults(
   current: SettingsRecord,
@@ -62,7 +71,9 @@ export function planSessionDefaults(
   const permissions = isRecord(current.permissions) ? current.permissions : {}
   const deny = Array.isArray(permissions.deny) ? permissions.deny : []
 
-  const missing = DENIED_TOOLS.filter((tool) => !deny.includes(tool))
+  const subagentsMissing = DENIED_TOOLS.filter((tool) => !deny.includes(tool))
+  const mergeMissing = MERGE_DENIED.filter((entry) => !deny.includes(entry))
+  const missing = [...subagentsMissing, ...mergeMissing]
   if (missing.length > 0) {
     next.permissions = { ...permissions, deny: [...deny, ...missing] }
   }
@@ -78,7 +89,11 @@ export function planSessionDefaults(
     keys,
     next,
     changed: keys.some((key) => key.changed),
-    predates: memoryAbsent && missing.length === DENIED_TOOLS.length,
+    predates:
+      memoryAbsent &&
+      subagentsMissing.length === DENIED_TOOLS.length &&
+      mergeMissing.length === MERGE_DENIED.length,
+    lacksMergeDeny: mergeMissing.length > 0,
   }
 }
 

package/src/pr/drive-copy.ts

@@ -0,0 +1,218 @@
+import { createHash } from 'node:crypto'
+import { cpSync, existsSync, readFileSync, rmSync, statSync } from 'node:fs'
+import { isAbsolute, join } from 'node:path'
+import { $ } from 'bun'
+import { gitEnv } from '@/git/env'
+
+/** Where a project names the folders its running preview saves into. */
+export const PREVIEW_CONFIG_REL = join('canon', 'config', 'preview.json')
+
+/** The variable a preview server reads for the copy root when the project names none. */
+export const DEFAULT_PREVIEW_ENV = 'CANON_PREVIEW_ROOT'
+
+/** The type vocabulary of `git-branch`'s branch standard, which the slug transform drops. */
+const BRANCH_TYPES = new Set([
+  'feat',
+  'fix',
+  'refactor',
+  'docs',
+  'chore',
+  'perf',
+  'test',
+  'style',
+  'build',
+  'ci',
+  'revert',
+])
+
+export interface PreviewConfig {
+  readonly writes: readonly string[]
+  readonly env: string
+}
+
+export type PreviewConfigRead =
+  | { readonly kind: 'absent' }
+  | { readonly kind: 'read'; readonly config: PreviewConfig }
+  | {
+      readonly kind: 'refused'
+      readonly reason: 'bad-config' | 'unsafe-path'
+      readonly detail: string
+    }
+
+export interface StatusEntry {
+  readonly path: string
+  readonly status: string
+  /** The content digest, or null where no regular file stands at the path. */
+  readonly digest: string | null
+}
+
+/**
+ * The branch-to-slug transform every branch-derived name shares: a leading
+ * type segment comes off when a further segment follows it, and each
+ * remaining `/` becomes `-`. The worker reads its branch off the worktree and
+ * the reviewer off the pull request's head ref, so this one function is what
+ * lands both on the same folder.
+ */
+export function branchSlug(branch: string): string {
+  const segments = branch.split('/')
+  const rest =
+    segments.length > 1 && BRANCH_TYPES.has(segments[0] ?? '')
+      ? segments.slice(1)
+      : segments
+  return rest.join('-')
+}
+
+function isContained(path: string): boolean {
+  return (
+    path.length > 0 && !isAbsolute(path) && !path.split(/[\\/]/).includes('..')
+  )
+}
+
+/**
+ * Reads `canon/config/preview.json` as `{ "writes": [...], "env": "<NAME>" }`.
+ * A file that does not parse refuses rather than reading as absent, since a
+ * typo there would otherwise drive the real folders while the pass reports a
+ * copy. A `writes` path that is absolute or climbs with `..` refuses, so the
+ * copy never reads or writes outside its two roots.
+ */
+export function loadPreviewConfig(worktree: string): PreviewConfigRead {
+  const path = join(worktree, PREVIEW_CONFIG_REL)
+  if (!existsSync(path)) return { kind: 'absent' }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    return {
+      kind: 'refused',
+      reason: 'bad-config',
+      detail: `${PREVIEW_CONFIG_REL} does not parse as JSON.`,
+    }
+  }
+  if (typeof parsed !== 'object' || parsed === null) {
+    return {
+      kind: 'refused',
+      reason: 'bad-config',
+      detail: `${PREVIEW_CONFIG_REL} is not an object.`,
+    }
+  }
+
+  const { writes, env } = parsed as Record<string, unknown>
+  if (
+    !Array.isArray(writes) ||
+    !writes.every((item): item is string => typeof item === 'string')
+  ) {
+    return {
+      kind: 'refused',
+      reason: 'bad-config',
+      detail: `${PREVIEW_CONFIG_REL} carries no "writes" list of paths.`,
+    }
+  }
+  if (env !== undefined && (typeof env !== 'string' || env === '')) {
+    return {
+      kind: 'refused',
+      reason: 'bad-config',
+      detail: `${PREVIEW_CONFIG_REL} names an "env" that is not a variable name.`,
+    }
+  }
+
+  const unsafe = writes.find((item) => !isContained(item))
+  if (unsafe !== undefined) {
+    return {
+      kind: 'refused',
+      reason: 'unsafe-path',
+      detail: `${PREVIEW_CONFIG_REL} names "${unsafe}", which leaves the worktree.`,
+    }
+  }
+
+  return {
+    kind: 'read',
+    config: { writes, env: env ?? DEFAULT_PREVIEW_ENV },
+  }
+}
+
+/**
+ * Replaces the copy root with a fresh copy of each declared path, so the last
+ * pass's drives never reach the next one. A path the worktree does not hold
+ * is named rather than failing the copy.
+ */
+export function buildDriveCopy(
+  worktree: string,
+  copyRoot: string,
+  writes: readonly string[],
+): { readonly copied: readonly string[]; readonly missing: readonly string[] } {
+  rmSync(copyRoot, { recursive: true, force: true })
+  const copied: string[] = []
+  const missing: string[] = []
+  for (const path of writes) {
+    const source = join(worktree, path)
+    if (!existsSync(source)) {
+      missing.push(path)
+      continue
+    }
+    cpSync(source, join(copyRoot, path), { recursive: true })
+    copied.push(path)
+  }
+  return { copied, missing }
+}
+
+function digestOf(path: string): string | null {
+  try {
+    if (!statSync(path).isFile()) return null
+    return createHash('sha1').update(readFileSync(path)).digest('hex')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Every entry `git status` reports, untracked files listed one by one so a
+ * file a drive adds inside a tracked folder names itself, each with a content
+ * digest so a file already dirty at the baseline still reads as changed when
+ * a drive writes it again. Undefined when git cannot read the tree.
+ */
+export async function readWorktreeStatus(
+  worktree: string,
+): Promise<readonly StatusEntry[] | undefined> {
+  const result =
+    await $`git -C ${worktree} status --porcelain=v1 -z --untracked-files=all`
+      .env(gitEnv())
+      .quiet()
+      .nothrow()
+  if (result.exitCode !== 0) return undefined
+
+  const tokens = result.stdout.toString().split('\0')
+  const entries: StatusEntry[] = []
+  for (let index = 0; index < tokens.length; index++) {
+    const token = tokens[index] ?? ''
+    if (token.length < 4) continue
+    const status = token.slice(0, 2)
+    const path = token.slice(3)
+    // A rename or copy carries its source as the next token.
+    if (status.includes('R') || status.includes('C')) index++
+    entries.push({ path, status, digest: digestOf(join(worktree, path)) })
+  }
+  return entries
+}
+
+/**
+ * The paths whose status or content differs from the baseline, in the order
+ * git reports them. An entry gone since the baseline is not reported, since a
+ * worker committing its own edit mid-pass clears it the same way.
+ */
+export function changedSince(
+  baseline: readonly StatusEntry[],
+  current: readonly StatusEntry[],
+): readonly string[] {
+  const before = new Map(baseline.map((entry) => [entry.path, entry]))
+  return current
+    .filter((entry) => {
+      const prior = before.get(entry.path)
+      return (
+        prior === undefined ||
+        prior.status !== entry.status ||
+        prior.digest !== entry.digest
+      )
+    })
+    .map((entry) => entry.path)
+}

package/src/pr/lift.ts

@@ -4,6 +4,7 @@ import {
   type ReviewRow,
   resolveReviewScope,
   resolveUiScope,
+  type UiCounts,
 } from '@/pr/review-scope'
 import { DEFAULT_PAINTED, isPainted, type PaintedPatterns } from '@/pr/painted'
 
@@ -24,6 +25,7 @@ export type LiftRefusal =
   | 'ui-open'
   | 'ui-unmarked'
   | 'ui-behind'
+  | 'ui-undriven'
   | 'evidence-owed'
   | 'standing-stale'
   | 'standing-conflict'
@@ -170,6 +172,20 @@ function carried(gates: readonly GateResult[]): {
   }
 }
 
+/**
+ * Whether a verdict's counts show boxes left undriven and none driven. An empty
+ * pass, with nothing not driven either, looked at no box because none was owed.
+ */
+function droveNothing(counts: UiCounts | undefined): boolean {
+  return (
+    counts !== undefined &&
+    counts.failed === 0 &&
+    counts.eyes === 0 &&
+    counts.passed === 0 &&
+    counts.notDriven > 0
+  )
+}
+
 /**
  * Binds only where the evidence record carries a checklist to drive.
  *
@@ -192,6 +208,9 @@ export async function uiGate(
   if (scope.state === 'open') return fail('ui', 'ui-open')
   if (scope.source !== 'marker') return fail('ui', 'ui-unmarked')
   if (scope.commit === undefined) return fail('ui', 'ui-behind')
+  // Ahead of the head test so a close carried across commits is refused too.
+  // A verdict whose count line did not parse reads as unchecked and goes on.
+  if (droveNothing(scope.counts)) return fail('ui', 'ui-undriven')
   if (coversHead(scope.commit, head)) return pass('ui')
 
   const changed = await api.readChanged(scope.commit, head)

package/src/pr/local.ts

@@ -64,3 +64,29 @@ export function dropAddressLine(body: string): string | undefined {
   if (isGapAbove && (lines[first] ?? '').trim() === '') lines.splice(first, 1)
   return lines.join('\n')
 }
+
+/**
+ * A loopback URL with any port and path, and the backticks or angle brackets a
+ * pass may have wrapped it in. These hosts resolve on one machine for one
+ * session, so no later reader of the thread can open them.
+ */
+const LOOPBACK_URL =
+  /[`<]?https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(?::\d+)?(?:\/[^\s`>,]*)?[`>]?/g
+
+/**
+ * Rewrites the loopback address on a UI review's `Driven at` line to "a local
+ * preview", keeping the head and the renderer. Only that line is read, so a
+ * loopback URL a box reason quotes from the page stays as content. Undefined
+ * when no line changes, which is also what a second mask of the same body
+ * returns.
+ */
+export function maskLocalAddress(body: string): string | undefined {
+  let changed = false
+  const lines = body.split('\n').map((line) => {
+    if (!line.startsWith('Driven at ')) return line
+    const masked = line.replace(LOOPBACK_URL, 'a local preview')
+    if (masked !== line) changed = true
+    return masked
+  })
+  return changed ? lines.join('\n') : undefined
+}