@erclx/canon 5.70.0 → 5.72.0

package/src/commands/feedback.ts

@@ -2,11 +2,20 @@ import { Option, type Command } from 'commander'
 import {
   deriveDomainLabels,
   deriveTitle,
+  followUpProblem,
   missingField,
   missingFieldMessage,
 } from '@/feedback/body'
-import { createGithubIssue } from '@/feedback/github'
-import { issueFailureMessage } from '@/feedback/github-format'
+import {
+  createGithubIssue,
+  postIssueComment,
+  readFeedbackIssue,
+} from '@/feedback/github'
+import {
+  commentFailureMessage,
+  issueFailureMessage,
+  issueReadFailureMessage,
+} from '@/feedback/github-format'
 import { frameError, frameSuccess } from '@/cli/ui'
 
 function readStdin(): Promise<string> {
@@ -20,6 +29,61 @@ function readStdin(): Promise<string> {
   })
 }
 
+/**
+ * Triage lists open `feedback` issues only, so a comment anywhere else is
+ * never read. Both checks run before the post, since a public comment cannot
+ * be taken back by a later refusal.
+ */
+async function postFollowUp(issue: number, body: string): Promise<void> {
+  const problem = followUpProblem(body)
+  if (problem) {
+    frameError(problem)
+    process.exitCode = 1
+    return
+  }
+
+  // An absent gh can post nothing, so the block goes out for a hand paste. A
+  // failed read is a refusal to repair, since the number may name no issue.
+  const read = await readFeedbackIssue(issue)
+  if (!read.ok && read.reason === 'missing-binary') {
+    frameError(commentFailureMessage(read, issue))
+    process.stdout.write(`${body}\n`)
+    process.exitCode = 1
+    return
+  }
+  if (!read.ok) {
+    frameError(issueReadFailureMessage(read, issue))
+    process.exitCode = 1
+    return
+  }
+  if (read.state !== 'OPEN') {
+    frameError(
+      `Issue #${issue} is ${read.state.toLowerCase()}, and triage reads open feedback issues only. File a new report instead.`,
+    )
+    process.exitCode = 1
+    return
+  }
+  if (!read.labels.includes('feedback')) {
+    frameError(
+      `Issue #${issue} carries no feedback label, so it is not a toolkit feedback report. Check the number and re-run.`,
+    )
+    process.exitCode = 1
+    return
+  }
+
+  const result = await postIssueComment(issue, body)
+  if (result.ok) {
+    frameSuccess('canon feedback', result.url)
+    process.stdout.write(`${result.url}\n`)
+    return
+  }
+  frameError(commentFailureMessage(result, issue))
+  process.stdout.write(`${body}\n`)
+  process.exitCode = 1
+}
+
+const ISSUE_NUMBER = /^[1-9]\d*$/
+
 export function register(program: Command): void {
   program
     .command('feedback')
@@ -27,10 +91,21 @@ export function register(program: Command): void {
     .description(
       'Open a GitHub issue on the toolkit repo from a feedback block on stdin',
     )
+    .option(
+      '--on <issue>',
+      'Post a follow-up block as a comment on an open feedback issue instead',
+    )
     // A cached plugin still pipes `--github`, and commander rejects an unknown
     // option, so the flag stays accepted and hidden for one release.
     .addOption(new Option('--github').hideHelp())
-    .action(async () => {
+    .action(async (opts: { on?: string }) => {
+      if (opts.on !== undefined && !ISSUE_NUMBER.test(opts.on)) {
+        frameError(
+          `--on takes an issue number, such as --on 2801, not "${opts.on}".`,
+        )
+        process.exitCode = 1
+        return
+      }
       if (process.stdin.isTTY) {
         frameError(
           'No feedback on stdin. Pipe a markdown block: pbpaste | canon feedback',
@@ -45,6 +120,11 @@ export function register(program: Command): void {
         return
       }
 
+      if (opts.on !== undefined) {
+        await postFollowUp(Number(opts.on), body)
+        return
+      }
+
       // A report missing its surface is no more useful in the tracker than
       // anywhere else, so validation runs before any `gh` call.
       const absent = missingField(body)

package/src/commands/markdown.ts

@@ -167,7 +167,9 @@ export function register(program: Command): void {
         '',
         'A mid-sentence colon and a heading with a capital after its first word',
         'report the same way. A proper noun is the one case the second cannot',
-        'tell from title case, and the first is sometimes right.',
+        'tell from title case, and the first is sometimes right. A list whose',
+        'every item opens on a lead and a colon reads each lead as a label, and so',
+        'does a lead made only of code spans, links, commas, and and, or, to.',
         '',
         'Length reports a whole document past the ceiling and never exits 2.',
         'The Document ceiling gate stage owns that verdict, since this audit also',
@@ -842,6 +844,9 @@ function reportColons(reports: readonly FileReport[]): void {
   logInfo(
     'A colon followed by more text in a prose line, outside a label, a code span, and a link.',
   )
+  logInfo(
+    'A list where every item opens on a lead and a colon reads each lead as a label.',
+  )
   logInfo(
     'A heading, a table row, a fenced block, and a line-final colon are excluded. This never fails a run.',
   )

package/src/commands/pr.ts

@@ -98,6 +98,7 @@ import {
 } from '@/git/status'
 import { machineListenerReader } from '@/listeners/machine'
 import { loadPaintedPatterns } from '@/pr/painted'
+import { readCarry } from '@/pr/carry'
 import { LOCAL_CONFIG_REL, readHealthPaths } from '@/pr/health'
 import {
   dropAddressLine,
@@ -228,6 +229,7 @@ type TickReason =
   | TickRefusal
   | 'count-mismatch'
   | 'stale-head'
+  | 'redrive-owed'
   | 'bad-boxes'
   | 'no-comment'
   | 'body-refused'
@@ -236,7 +238,9 @@ 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.',
+    'The head named is not the branch tip on the remote, and the tip does not descend from it or the gap could not be read, so a tick would claim a pass on a commit that is no longer the pull request. Re-drive the checklist at the tip.',
+  'redrive-owed':
+    'A push since the driven head changed a path a box can observe, so the pass does not carry to the tip. Nothing was written. Re-drive the checklist at the tip rather than retrying the tick there.',
   'bad-boxes':
     '--boxes takes box numbers as a comma-separated list of positive whole numbers, such as 1,3, and --head takes the commit that was driven.',
   'count-mismatch':
@@ -700,8 +704,9 @@ export function register(program: Command): void {
         '',
         '`ui` also carries the newest `## UI review` pass (`heading`, `state`,',
         '`commit`, `source`), `isBound`, which is whether the evidence comment',
-        'carries a checklist, and `carriedFrom` or `paintedPaths` when the lift',
-        'carried a close forward or refused to. An unbound family reads covered.',
+        'carries a checklist, and `carriedFrom` when the lift carried a close',
+        'forward, or `drivenPaths` and the painted subset `paintedPaths` when it',
+        'refused to. An unbound family reads covered.',
         '',
         'Both families post as pull request reviews, so this reads',
         '`pulls/<n>/reviews` alone, as the lift does. Issue comments are not',
@@ -944,11 +949,15 @@ export function register(program: Command): void {
         '  ui        the newest `## UI review` is closed at the head, bound only',
         '            where `canon pr evidence --check` carries a checklist. A close',
         '            on an earlier commit still holds when it is an ancestor of the',
-        '            head and no painted path changed since, and the record names',
-        '            it as `carriedFrom`. A painted change refuses `ui-behind` and',
-        '            lists the paths as `paintedPaths`. A close whose count line',
-        '            shows boxes not driven and none passed, failed, or needing',
-        '            eyes refuses `ui-undriven`, carried or not',
+        '            head and every path changed since is one no box can observe,',
+        '            being tests, stories, snapshots, markdown in the root and in',
+        '            `canon/`, `.claude/`, `.github/`, and `docs/`, evidence captures,',
+        '            and `canon/design/`, and the record names it as `carriedFrom`.',
+        '            Any other change refuses `ui-behind`, listing the paths as',
+        '            `drivenPaths` and the painted subset as `paintedPaths`, since',
+        '            a box drives behavior a `.ts` file holds too. A close whose',
+        '            count line shows boxes not driven and none passed, failed,',
+        '            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',
@@ -1295,14 +1304,23 @@ export function register(program: Command): void {
         'driver can run is ticked, counts taste boxes apart, and is the only',
         'body text this verb writes, so hand edits elsewhere survive.',
         '',
-        'Before writing it reads the newest UI verdict. One that covers the tip',
-        'and carries a count line must match the ticks this call leaves at the',
-        'tip, so a re-drive passes every box that passed, since a new head',
-        'clears the older ticks. Any other verdict leaves the check unrun.',
+        'A --head behind the remote tip carries to the tip when every path',
+        'changed since is one no box can observe, being tests, stories,',
+        'snapshots, markdown in the root and in `canon/`, `.claude/`,',
+        '`.github/`, and `docs/`, evidence captures, and `canon/design/`. The',
+        'boxes are then stamped at the tip and the record names `carriedFrom`.',
+        'Any other changed path, markdown elsewhere included, owes a re-drive.',
+        '',
+        'Before writing it reads the newest UI verdict. One that covers the tip,',
+        'or the driven head on a carry, and carries a count line must match the',
+        'ticks this call leaves at the tip, so a re-drive passes every box that',
+        'passed, since a new head clears the older ticks. Any other verdict',
+        'leaves the check unrun.',
         '',
         'Read `reason` on the JSON record:',
         '  ticked       the boxes were ticked and the body line written, with the',
-        '               tip in `head` and `countCheck` as matched or unchecked',
+        '               tip in `head`, `countCheck` as matched or unchecked, and',
+        '               `carriedFrom` when --head was carried to the tip',
         '  count-mismatch the verdict passed a different number of boxes than',
         '               this call leaves ticked at the tip, nothing written,',
         '               `passed` and `ticked` carry the two counts. Fewer ticks',
@@ -1310,7 +1328,10 @@ export function register(program: Command): void {
         '               operator an untick of a box that has since failed',
         '  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',
+        '  redrive-owed a push since --head changed a path a box can observe,',
+        '               nothing written, with `driven`, `head`, and `drivenPaths`',
+        '  stale-head   --head is behind the tip with no readable linear gap,',
+        '               as a force-push or a rebase leaves, nothing written',
         '  taste-box    a named box ends in (taste), nothing written',
         '  no-box       a named number is past the checklist, nothing written',
         '  no-checklist the evidence comment carries no checklist',
@@ -3475,9 +3496,9 @@ const POSITIVE_WHOLE = /^[1-9]\d*$/
 const MIN_TICK_HEAD_LENGTH = 7
 
 /**
- * Ticks the named boxes on the marked comment. It refuses a head that is not
- * the remote tip and a taste box before writing, so both rules hold as checks
- * rather than as prose a driver can talk itself out of.
+ * Ticks the named boxes on the marked comment. It refuses a head the tip moved
+ * past in a way a box can observe, and a taste box, before writing, so both
+ * rules hold as checks rather than as prose a driver can talk itself out of.
  */
 async function runTick(
   number: string | undefined,
@@ -3518,7 +3539,26 @@ async function runTick(
       root,
     )
   }
-  if (!reading.tip.startsWith(head)) return refuseTick('stale-head')
+  const carry = await readCarry(
+    (from, to) => readChangedPaths(gitRunner(root), from, to),
+    head,
+    reading.tip,
+  )
+  if (carry.kind === 'moved') {
+    return refuseWith(
+      'redrive-owed',
+      TICK_REFUSALS['redrive-owed'],
+      emitJson,
+      root,
+      { driven: head, head: reading.tip, drivenPaths: carry.drivenPaths },
+    )
+  }
+  // A gap that could not be read refuses as a rewrite does, which is what the
+  // verb answered for every moved tip before the carry.
+  if (carry.kind === 'not-ancestor' || carry.kind === 'failed') {
+    return refuseTick('stale-head')
+  }
+  const carriedFrom = carry.kind === 'carried' ? carry.carriedFrom : undefined
 
   const comments = await listComments(root, String(identity.number))
   if (comments === undefined) return refuseTick('gh-failed')
@@ -3534,8 +3574,9 @@ async function runTick(
   if (result.kind === 'refused') return refuseTick(result.reason)
 
   // Read ahead of the write so a short list refuses before it leaves the
-  // comment half ticked. A verdict that does not cover the tip, carries no
-  // count line, or cannot be read leaves the check unrun and says so.
+  // comment half ticked. A verdict that covers neither the tip nor the head a
+  // carry came from, carries no count line, or cannot be read leaves the check
+  // unrun and says so.
   const ticked = countTicksAtHead(
     readChecklistBoxes(findEvidenceChecklist([{ body: result.body }]) ?? ''),
     reading.tip,
@@ -3547,7 +3588,10 @@ async function runTick(
   const isCounted =
     verdict.counts !== undefined &&
     verdict.commit !== undefined &&
-    coversHead(verdict.commit, reading.tip)
+    (coversHead(verdict.commit, reading.tip) ||
+      (carriedFrom !== undefined &&
+        (coversHead(verdict.commit, carriedFrom) ||
+          coversHead(carriedFrom, verdict.commit))))
   if (isCounted && verdict.counts.passed !== ticked) {
     return refuseWith(
       'count-mismatch',
@@ -3622,6 +3666,7 @@ async function runTick(
         reason: 'ticked',
         countCheck,
         head: reading.tip,
+        ...(carriedFrom !== undefined && { carriedFrom }),
         boxes: numbers.map(Number),
         commentId,
       })}\n`,

package/src/commands/tasks.ts

@@ -57,7 +57,10 @@ import {
   type RecordRefused,
   type RecordSelector,
   recordPullRequest,
+  recordSession,
+  type SessionOutcome,
 } from '@/tasks/record'
+import { resolveSessions } from '@/sessions/resolve'
 import {
   type BoardGroup,
   type Finding,
@@ -142,6 +145,13 @@ interface PullRequestCommandOptions {
   readonly root?: string
 }
 
+interface SessionCommandOptions {
+  readonly json?: boolean
+  readonly plan?: string
+  readonly name?: string
+  readonly root?: string
+}
+
 interface PlanLinkCommandOptions {
   readonly add?: boolean
   readonly waiting?: string
@@ -617,6 +627,63 @@ export function register(program: Command): void {
       },
     )
 
+  tasks
+    .command('session')
+    .description('Record a session that worked a task on its Sessions: line')
+    .argument(
+      '<sessionId>',
+      'Full sessionId, as canon sessions list --json carries it',
+    )
+    .argument('[task]', 'Task filename stem, as in v28.1-trigger-escalation')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--plan <slug>', 'Select the task whose Plan line names this plan')
+    .option(
+      '--name <name>',
+      'Name to record, read off the live roster when omitted',
+    )
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Refusals, read off `reason`:',
+        '  no-board   the repository holds no `.canon/tasks/` board',
+        '  no-match   no task matches the selector',
+        '  ambiguous  more than one task matches the selector',
+        '  bad-input  an id that is not a full sessionId, or an empty name',
+        '  no-name    the roster lists no live session with the id, and no',
+        '             --name was passed',
+        '',
+        'Exit codes:',
+        '  0  the session was added, appended, or already listed',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'It writes Sessions: <name> (<sessionId>) below the origin, Pull',
+        'request:, and Pending branch: lines, and appends to the line when one',
+        'exists. The id is the key, so a session already listed is reported',
+        'unchanged under the name it was first recorded with. A cloud',
+        'session_ id is accepted, and takes --name since the roster never',
+        'lists it. Safe from a linked worktree, since it resolves the board',
+        'root in-process.',
+        '',
+        'Examples:',
+        '  canon tasks session 0b1c2d3e-4f50-6172-8394-a5b6c7d8e9f0 v28.1-trigger-escalation',
+        '  canon tasks session 0b1c2d3e-4f50-6172-8394-a5b6c7d8e9f0 --plan task-sessions-line --json',
+        '  canon tasks session session_01AbC v28.1-trigger-escalation --name cloud-canon-a',
+        '',
+      ].join('\n'),
+    )
+    .action(
+      async (
+        sessionId: string,
+        task: string | undefined,
+        opts: SessionCommandOptions,
+      ) => {
+        process.exitCode = await runSession(sessionId, task, opts)
+      },
+    )
+
   tasks
     .command('plan-link')
     .description("Write or correct a task's Plan: line to point at a plan")
@@ -1259,6 +1326,72 @@ async function runPullRequest(
   return reportPullRequest(outcome, emitJson, root)
 }
 
+async function runSession(
+  sessionId: string,
+  task: string | undefined,
+  opts: SessionCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const selector = selectorFor(task, opts.plan)
+
+  if ('ok' in selector) {
+    return reportRecord(
+      'canon tasks session',
+      selector,
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const name = opts.name ?? (await rosterName(sessionId))
+  const outcome = await recordSession(root, selector, sessionId, name)
+
+  return reportSession(outcome, emitJson, root)
+}
+
+/** The live roster's name for an id, or undefined once the session has exited. */
+async function rosterName(sessionId: string): Promise<string | undefined> {
+  const report = await resolveSessions()
+  if (report.kind === 'absent') return undefined
+
+  return report.sessions.find((session) => session.sessionId === sessionId)
+    ?.name
+}
+
+function reportSession(
+  outcome: SessionOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    return reportRecord('canon tasks session', outcome, emitJson, root)
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        task: outcome.stem,
+        path: relative(root, outcome.path),
+        sessionId: outcome.sessionId,
+        name: outcome.name,
+        action: outcome.action,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('canon tasks session')
+  logStep(outcome.action === 'unchanged' ? 'Already recorded' : 'Recorded')
+  logInfo(`${outcome.stem} names ${outcome.name} (${outcome.sessionId})`)
+  if (outcome.action !== 'unchanged') logAdd(relative(root, outcome.path))
+  outro()
+
+  return 0
+}
+
 const RENAME_PATTERN = /^Branch: renamed refs\/heads\/(.+) to refs\/heads\//
 
 /**

package/src/feedback/body.ts

@@ -94,6 +94,56 @@ export function missingFieldMessage(field: string): string {
   return `Feedback report is missing its "### ${field}" section. Every report needs ${REQUIRED_FIELDS.map((name) => `### ${name}`).join(', ')}.`
 }
 
+/**
+ * The fields a follow-up comment carries. A follow-up reports what happened
+ * after filing, so it names no surface and proposes no fix of its own. It says
+ * whether the body's fix still stands, since triage reads the body as the
+ * request and a silent overturn leaves it acting on the old one.
+ */
+export const FOLLOW_UP_FIELDS = [
+  'Observed',
+  'Changes the fix',
+  'Links',
+] as const
+
+const YES_OR_NO = /^(?:yes|no)\b/i
+
+/**
+ * A URL, or an issue reference such as `#2801`, `frameboard#156`, or
+ * `erclx/canon#2801`. A bare name is what the hand-written follow-up carried,
+ * and nothing a reader can open from it.
+ */
+const REFERENCE = /https?:\/\/\S+|(?:^|[\s(])(?:[\w.-]+\/)?[\w.-]*#\d+\b/
+
+export function missingFollowUpField(body: string): string | undefined {
+  const sections = parseSections(body)
+  for (const field of FOLLOW_UP_FIELDS) {
+    const value = sections.get(field.toLowerCase())
+    if (!value) return field
+  }
+  return undefined
+}
+
+/**
+ * The sentence a refused follow-up reads, or `undefined` when it carries every
+ * field in a checkable shape. One problem at a time, as `missingField` does.
+ */
+export function followUpProblem(body: string): string | undefined {
+  const absent = missingFollowUpField(body)
+  if (absent) {
+    return `Follow-up is missing its "### ${absent}" section. Every follow-up needs ${FOLLOW_UP_FIELDS.map((name) => `### ${name}`).join(', ')}.`
+  }
+  const changes = readField(body, 'Changes the fix') ?? ''
+  if (!YES_OR_NO.test(changes)) {
+    return 'Follow-up "### Changes the fix" must open with yes or no, so triage can tell whether the issue body still holds.'
+  }
+  const links = readField(body, 'Links') ?? ''
+  if (!REFERENCE.test(links)) {
+    return 'Follow-up "### Links" carries no URL or issue reference. Write each as a URL or as owner/repo#number.'
+  }
+  return undefined
+}
+
 function surfaceField(body: string): string | undefined {
   return readField(body, 'Surface')?.split('\n')[0]?.trim()
 }

package/src/feedback/github-format.ts

@@ -37,6 +37,61 @@ export function buildIssueArgs(opts: CreateIssueOptions): string[] {
   return args
 }
 
+export function buildCommentArgs(issue: number, body: string): string[] {
+  return ['issue', 'comment', String(issue), '--body', body, '--repo', REPO]
+}
+
+export function buildIssueReadArgs(issue: number): string[] {
+  return [
+    'issue',
+    'view',
+    String(issue),
+    '--json',
+    'state,labels',
+    '--repo',
+    REPO,
+  ]
+}
+
+export interface IssueRead {
+  readonly ok: true
+  readonly state: string
+  readonly labels: readonly string[]
+}
+
+/**
+ * Reads the `gh issue view --json state,labels` record. A record of any other
+ * shape is a failed read rather than an issue with no labels, since the caller
+ * refuses on a missing label and that refusal would then name the wrong cause.
+ */
+export function parseIssueRead(stdout: string): IssueRead | IssueFailure {
+  let record: unknown
+  try {
+    record = JSON.parse(stdout)
+  } catch {
+    return {
+      ok: false,
+      reason: 'command-failed',
+      detail: 'gh printed no JSON issue record',
+    }
+  }
+  const { state, labels } = (record ?? {}) as {
+    state?: unknown
+    labels?: unknown
+  }
+  if (typeof state !== 'string' || !Array.isArray(labels)) {
+    return {
+      ok: false,
+      reason: 'command-failed',
+      detail: 'gh printed an issue record with no state or labels',
+    }
+  }
+  const names = labels
+    .map((label: unknown) => (label as { name?: unknown } | null)?.name)
+    .filter((name): name is string => typeof name === 'string')
+  return { ok: true, state, labels: names }
+}
+
 /**
  * Collapses to one line. Both callers write the detail inside a framed error or
  * a colored warning, and a newline in the middle of either breaks the frame and
@@ -75,3 +130,25 @@ export function issueFailureMessage(failure: IssueFailure): string {
   }
   return `gh could not file the issue: ${failure.detail ?? 'no diagnostic on stderr'}. File it manually at ${ISSUE_URL} instead.`
 }
+
+export function commentFailureMessage(
+  failure: IssueFailure,
+  issue: number,
+): string {
+  const target = `https://github.com/${REPO}/issues/${issue}`
+  if (failure.reason === 'missing-binary') {
+    return `gh is not installed, so no follow-up was posted. Install gh, or comment at ${target}`
+  }
+  return `gh could not post the follow-up: ${failure.detail ?? 'no diagnostic on stderr'}. Comment manually at ${target} instead.`
+}
+
+/**
+ * A read that `gh` ran and failed is most often a number naming no issue, so
+ * the sentence asks for the number rather than pointing a paste at it.
+ */
+export function issueReadFailureMessage(
+  failure: IssueFailure,
+  issue: number,
+): string {
+  return `gh could not read issue #${issue}: ${failure.detail ?? 'no diagnostic on stderr'}. Check the number and re-run.`
+}