@erclx/canon 5.46.0 → 5.47.0

package/docs/workflow/zshrc-aliases.md

@@ -17,6 +17,7 @@ A hand-written block without markers is detected through its `alias clp=` line,
 ```zsh
 # >>> canon aliases >>>
 TOOLKIT="/path/to/toolkit"
+export CLAUDE_CODE_ENABLE_TODO_TOOLS=1
 
 alias cl='claude'
 alias clr='cl -r'
@@ -32,6 +33,8 @@ alias clpac='clpa --cwd .'
 # <<< canon aliases <<<
 ```
 
+The export gives a session started from your terminal the task tools, which Claude Code reads before it starts, so workers and reviewers can show their checklist on `Ctrl+T`. A background session has them without it.
+
 To opt out, delete the block and run `bun install` and `bun link` yourself. Bash takes the block unchanged in `~/.bashrc`, pasted by hand. Bootstrap writes `~/.zshrc` alone.
 
 ## What each one does

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.46.0",
+  "version": "5.47.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/scripts/core/bootstrap.sh

@@ -26,6 +26,7 @@ alias_block() {
   cat <<EOF
 $MARKER_OPEN
 TOOLKIT="$PROJECT_ROOT"
+export CLAUDE_CODE_ENABLE_TODO_TOOLS=1
 
 alias cl='claude'
 alias clr='cl -r'

package/src/commands/labels.ts

@@ -6,6 +6,12 @@ import { gitEnv } from '@/git/env'
 import { diffLabels } from '@/labels/apply'
 import { type LabelAuditRefusal, auditLabels } from '@/labels/audit'
 import { checkClosing } from '@/labels/closing'
+import {
+  bodyDensity,
+  isPost,
+  POST_HEADINGS,
+  postDensity,
+} from '@/labels/density'
 import { resolveScanInput } from '@/labels/event'
 import { checkTitleFormat, type TitleFormatIssue } from '@/labels/format'
 import { MAP_REL } from '@/labels/map'
@@ -241,7 +247,27 @@ export function register(program: Command): void {
         'It grades the body of an ordinary pull request against the closed',
         'section list: a level-two heading outside it, or a missing',
         '## Summary or ## Key changes, fails. A review, a release-please body,',
-        'and a scan carrying no title skip this check. It also fails a banned',
+        'and a scan carrying no title skip this check.',
+        '',
+        'It reports the density of that same body per section under `density`,',
+        'without failing on it: a bullet past 200 characters, more than 5 plain',
+        'bullets or 2 paragraphs in a row, a paragraph past 350 characters, any',
+        'H3 or deeper heading, and Technical context mixing bullets with',
+        'paragraphs. A bold label alone on a line splits a Key changes run, a',
+        'bold-led paragraph starts a new Technical context run, and Testing',
+        'takes the heading limit alone. Each finding carries its section, kind,',
+        'line in the whole body, value, and limit.',
+        '',
+        'A body the section check skips is graded as a post under the same',
+        '`density` key when its first level-two heading is one of',
+        `${POST_HEADINGS.map((heading) => `## ${heading}`).join(', ')}.`,
+        'A post takes the same length and run limits, allows an H3, and',
+        'measures a nested item as a bullet of its own. The footer, the',
+        'marker, and a table never report, a block inside <details> takes the',
+        'length limits alone, and a checklist box under ## What to look at',
+        'takes no length limit. Post density never fails the scan.',
+        '',
+        'It also fails a banned',
         'character, an em dash or a semicolon, in the title or body of a pull',
         'request or a review, outside a code span or a link.',
         '',
@@ -692,6 +718,44 @@ async function runScan(opts: ScanOptions): Promise<number> {
     }
   }
 
+  // Reported and never gated yet. New bodies come back clean under the
+  // shape in pr.md first, so an older open pull request fails no edit event.
+  // A post is never gated, since CI reads one only after it is published.
+  const post = !sectionsChecked && isPost(resolved.body)
+  const density = sectionsChecked
+    ? bodyDensity(resolved.body)
+    : post
+      ? postDensity(resolved.body)
+      : []
+
+  logStep(
+    !sectionsChecked && !post
+      ? 'Density not checked'
+      : density.length === 0
+        ? 'Clean'
+        : 'Density finding found',
+  )
+  if (!sectionsChecked && !post) {
+    logInfo(
+      'only an ordinary pull request body or a post opening on a post heading is graded for density',
+    )
+  } else if (density.length === 0) {
+    logInfo('every section is within its length, run, and heading limits')
+  } else {
+    logWarn(
+      `${plural(density.length, 'density finding')} in the ${post ? 'post' : 'body'}. Regroup the section under bold labels or split the long item rather than cutting a path.`,
+    )
+    for (const finding of density) {
+      const measured =
+        finding.value === null
+          ? ''
+          : ` (${finding.value} over ${finding.limit})`
+      logWarn(
+        `line ${finding.line} in ${finding.section ?? 'the opening'}: ${finding.kind}${measured}`,
+      )
+    }
+  }
+
   const banFindings = [
     ...scanBans(
       [{ number: 1, text: resolved.title, fenced: false }],
@@ -781,6 +845,7 @@ async function runScan(opts: ScanOptions): Promise<number> {
         sessionLinks: result.sessionLinks,
         titleFormatIssues,
         sections: { checked: sectionsChecked, ...sections },
+        density,
         bannedCharacters,
         missingClosures: closing.missing,
         strayClosures: closing.stray,

package/src/commands/pr.ts

@@ -93,7 +93,13 @@ import {
   servesChange,
   type WorkflowFile,
 } from '@/pr/preview'
-import { type TickRefusal, tickBoxes } from '@/pr/tick'
+import {
+  readUiPassHead,
+  type TickRefusal,
+  tickBoxes,
+  type UiPassSummary,
+  writeUiPassLine,
+} from '@/pr/tick'
 import {
   commentRowOf,
   identityOf,
@@ -157,9 +163,16 @@ interface TickOptions extends ReadOptions {
   readonly head?: string
 }
 
-type TickReason = TickRefusal | 'stale-head' | 'bad-boxes' | 'no-comment'
+type TickReason =
+  | TickRefusal
+  | 'stale-head'
+  | 'bad-boxes'
+  | 'no-comment'
+  | 'body-refused'
 
 const TICK_REFUSALS: Record<TickReason | 'gh-failed', string> = {
+  'body-refused':
+    'The boxes are ticked on the evidence comment, but gh could not edit the pull request body, so its UI pass line still shows the earlier result. Re-run the tick to retry the body.',
   'stale-head':
     'The head named is not the branch tip on the remote, so a tick would claim a pass on a commit that is no longer the pull request. Re-drive the checklist at the tip.',
   'bad-boxes':
@@ -736,6 +749,11 @@ export function register(program: Command): void {
         'comment. Together with --checklist the link and the checklist land in',
         'one comment.',
         '',
+        "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',
+        'naming this head alone, and reports `uiPass` as reset or reset-refused.',
+        '',
         'Both reasons carry what the marked comment already posted, each field',
         'present only when that comment holds it:',
         '  preview    the hosted **Preview:** address the comment carries',
@@ -1024,8 +1042,17 @@ export function register(program: Command): void {
         'it. A later render at another head clears a tick whose stamp names',
         'a different commit.',
         '',
+        "It also keeps one marked line in the pull request body's ## Testing,",
+        'such as `- [x] UI pass, 17 of 17 boxes passed at <short sha>, 1 taste',
+        'box left to the operator`. The line is ticked only when every box a',
+        'driver can run is ticked, counts taste boxes apart, and is the only',
+        'body text this verb writes, so hand edits elsewhere survive.',
+        '',
         'Read `reason` on the JSON record:',
-        '  ticked       the boxes were ticked, with the tip in `head`',
+        '  ticked       the boxes were ticked and the body line written, with the',
+        '               tip in `head`',
+        '  body-refused the comment is ticked but gh could not edit the body,',
+        '               exit 1 with `commentTicked`. Re-run to retry the body.',
         '  stale-head   --head is not the remote branch tip, nothing written',
         '  taste-box    a named box ends in (taste), nothing written',
         '  no-box       a named number is past the checklist, nothing written',
@@ -2437,10 +2464,30 @@ async function runEvidence(
     return 1
   }
 
+  // A UI pass line stamped at an earlier head describes a tree that is gone,
+  // so a render at a new head puts it back to unchecked. A line already
+  // naming this head is left alone, since each body edit reruns the label gate.
+  const priorBody = identity.body ?? ''
+  const stampedHead = readUiPassHead(priorBody)
+  let uiPass: 'reset' | 'reset-refused' | undefined
+  if (stampedHead !== undefined && !identity.head.startsWith(stampedHead)) {
+    const reset = writeUiPassLine(priorBody, {
+      kind: 'reset',
+      head: identity.head,
+    })
+    uiPass = (await patchPullBody(root, identity.number, reset))
+      ? 'reset'
+      : 'reset-refused'
+  }
+
   logStep('Scope')
   logInfo(
     `${plural(caseCount, 'case')} across ${plural(states.length, 'state')}`,
   )
+  if (uiPass === 'reset') logInfo('UI pass line reset to the new head')
+  if (uiPass === 'reset-refused') {
+    logWarn('gh could not edit the body, so its UI pass line names an old head')
+  }
   if (sized.unread.length > 0) {
     logWarn(
       `width unread for ${plural(sized.unread.length, 'image')}, rendered at 1000: ${sized.unread.join(', ')}`,
@@ -2469,6 +2516,7 @@ async function runEvidence(
         body,
         states,
         ...(sized.unread.length > 0 && { widthUnread: sized.unread }),
+        ...(uiPass !== undefined && { uiPass }),
         ...(commentId !== undefined && { commentId }),
         ...carried,
       })}\n`,
@@ -2941,9 +2989,53 @@ async function runTick(
     if (patched === null) return refuseTick('gh-failed')
   }
 
+  const boxes = readChecklistBoxes(
+    findEvidenceChecklist([{ body: result.body }]) ?? '',
+  )
+  const driven = boxes.filter((box) => !box.isTaste)
+  const summary: UiPassSummary = {
+    kind: 'passed',
+    // A tick counts as this pass's only when stamped at the tip, since an
+    // unstamped one is the author's claim and an older stamp names another head.
+    passed: driven.filter(
+      (box) =>
+        box.isTicked &&
+        box.stamp !== undefined &&
+        reading.tip.startsWith(box.stamp),
+    ).length,
+    total: driven.length,
+    taste: boxes.length - driven.length,
+    head: reading.tip,
+  }
+  const priorBody = identity.body ?? ''
+  const nextBody = writeUiPassLine(priorBody, summary)
+  if (
+    nextBody !== priorBody &&
+    !(await patchPullBody(root, identity.number, nextBody))
+  ) {
+    logStep('Partly ticked')
+    logWarn(TICK_REFUSALS['body-refused'])
+    outro()
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          number: identity.number,
+          reason: 'body-refused',
+          message: TICK_REFUSALS['body-refused'],
+          commentTicked: true,
+          head: reading.tip,
+          boxes: numbers.map(Number),
+          commentId,
+        })}\n`,
+      )
+    }
+    return 1
+  }
+
   logStep('Ticked')
   logInfo(
-    `${plural(numbers.length, 'box')} at ${reading.tip.slice(0, 7)} on comment ${commentId}`,
+    `${plural(numbers.length, 'box')} at ${reading.tip.slice(0, 7)} on comment ${commentId}, UI pass line on the body`,
   )
   outro()
   if (emitJson) {
@@ -2961,6 +3053,23 @@ async function runTick(
   return 0
 }
 
+/** Replaces a pull request's body, which `gh` takes through the REST pulls endpoint a cloud proxy serves. */
+async function patchPullBody(
+  root: string,
+  number: number,
+  body: string,
+): Promise<boolean> {
+  const patched = await gh(root, [
+    'api',
+    '-X',
+    'PATCH',
+    `repos/{owner}/{repo}/pulls/${number}`,
+    '-f',
+    `body=${body}`,
+  ])
+  return patched !== null
+}
+
 /** One `gh api` call, keeping the HTTP status of a failure so a refused write can be told from a missing ref. */
 type ApiCall =
   | { readonly ok: true; readonly data: unknown }

package/src/commands/sessions.ts

@@ -3,6 +3,7 @@ import type { Command } from 'commander'
 import { checkClaim, type ClaimReport } from '@/sessions/claim'
 import {
   callerIdentity,
+  confidenceOf,
   repositoryOf,
   type ResolvedSession,
   resolveSessions,
@@ -134,15 +135,21 @@ export function register(program: Command): void {
         '',
         'The confidence field says how the liveness of a row was decided.',
         '"confirmed" matched the running process against the start time the',
-        'record stamped. "unverified" means only that the pid answers, which',
-        'cannot rule out a pid handed to an unrelated process, so a roster',
-        'reported that way is a candidate list rather than an identity.',
+        'record stamped, and reads "via": "pid". "unverified" means only that the',
+        'pid answers, which cannot rule out a pid handed to an unrelated',
+        'process, so a roster reported that way is a candidate list rather than',
+        'an identity. Where the start time cannot be read, a row whose messaging',
+        'socket accepts a connection is confirmed instead and reads "via":',
+        '"listener". The probe connects and closes without writing. Each row',
+        'carries its own "confidence", and the top-level field is the weakest of',
+        'the rows listed, so --branch is not weakened by a row it dropped.',
         '',
         'A reader in another pid namespace, such as a sandboxed shell, cannot',
         'see the pid of a record stamped elsewhere. That row is judged on its',
         'messaging socket instead: it stays on the roster as "unverified" with',
         '"via": "socket", since a crashed session leaves its socket behind. A',
-        'foreign record whose socket is gone is left off the roster and',
+        'foreign record whose socket accepts a connection is confirmed as',
+        '"listener". One whose socket is gone is left off the roster and',
         'counted in "foreignDead", so an empty roster beside a count above zero',
         'is one this reader could not check, not one whose sessions ended.',
         '',
@@ -471,7 +478,7 @@ async function runList(opts: ListCommandOptions): Promise<number> {
     : null
 
   intro('canon sessions list')
-  reportConfidence(report)
+  reportConfidence(shown, report)
   reportSessions(
     shown,
     opts.branch,
@@ -486,7 +493,8 @@ async function runList(opts: ListCommandOptions): Promise<number> {
     process.stdout.write(
       `${JSON.stringify({
         dir: report.dir,
-        confidence: report.confidence,
+        // Over the rows shown, so an unrelated row --branch dropped cannot weaken it.
+        confidence: confidenceOf(shown),
         foreignDead: report.foreignDead,
         branch: opts.branch ?? null,
         repository,
@@ -528,6 +536,7 @@ function selfRefusal(own: Extract<SelfReport, { kind: 'unresolved' }>): string {
  * addresses a session directly and the second opens by asking to be corrected.
  */
 function reportConfidence(
+  shown: readonly ResolvedSession[],
   report: Extract<SessionReport, { kind: 'resolved' }>,
 ): void {
   logStep('Liveness')
@@ -535,23 +544,28 @@ function reportConfidence(
   // A roster of none decided nothing, so the confirmed line would claim a check
   // over rows that do not exist. The registry is never pruned and holds a record
   // per session ever run, which is what makes the empty result worth stating.
-  if (report.sessions.length === 0) {
+  if (shown.length === 0) {
     logInfo(
-      report.foreignDead > 0
+      report.foreignDead > 0 || report.sessions.length > 0
         ? 'No row to decide.'
         : 'No row to decide. Every record belongs to a session that has ended.',
     )
     return
   }
 
-  if (report.confidence === 'confirmed') {
+  if (confidenceOf(shown) === 'confirmed') {
+    const listened = shown.filter(
+      (session) => session.via === 'listener',
+    ).length
     logInfo(
-      'Every row matched a running process against the start time its record stamped.',
+      listened === 0
+        ? 'Every row matched a running process against the start time its record stamped.'
+        : `Every row is confirmed, ${listened} of them because their messaging socket accepted a connection and the rest by start time.`,
     )
     return
   }
 
-  if (report.sessions.some((session) => session.via === 'socket')) {
+  if (shown.some((session) => session.via === 'socket')) {
     logWarn(
       'This reader sits in another pid namespace than some records, so those rows rest on a messaging socket existing alone. A crashed session leaves its socket behind, so treat the mapping as inferred and open by asking to be corrected.',
     )

package/src/commands/tasks.ts

@@ -2195,6 +2195,7 @@ function report(
     logInfo('retargeted the Ready: line')
   }
   if (outcome.priorityRowRemoved) logInfo('cleared the ordering row')
+  if (outcome.backlogRowRemoved) logInfo('cleared the backlog row')
   logRelinked(outcome.relinked, outcome.relinkFailed, root)
   if (outcome.indexRegenerated) logInfo('regenerated index.md')
   if (outcome.cut > 0) logInfo(`${outcome.cut} outcome(s) cut`)
@@ -2277,6 +2278,7 @@ function recordFor(
     from: relative(root, outcome.from),
     to: relative(root, outcome.to),
     priorityRowRemoved: outcome.priorityRowRemoved,
+    backlogRowRemoved: outcome.backlogRowRemoved,
     indexRegenerated: outcome.indexRegenerated,
     plans: planMovesFor(outcome.plans, root),
     ready: outcome.ready