@erclx/canon 5.27.0 → 5.28.0

package/claude/skills/role-orchestrator/scripts/poll.ts

@@ -40,19 +40,33 @@ export interface Row {
   passAt: number
   prior: string
   replyAt: number
+  /** What the pull request writes, null when its diff could not be read. */
+  paths: null | string[]
   resp: number
+  stale: Staleness
+  staleFiles: string[]
   ui: string
   unmatchedCount: number
   unmatchedHeading: string
 }
 
+/**
+ * Whether the base moved under a path the pull request writes since the commit
+ * it branched from. `unknown` is a written set this run could not read, which
+ * must never pass for `fresh`.
+ */
+export type Staleness = 'fresh' | 'stale' | 'unknown'
+
 /** One baseline line, kept as the strings it was written with. */
 export interface Baseline {
   head: string
   merges: string
   number: string
+  /** Open pull requests this one conflicts with, comma-separated, or `none`. */
+  overlaps: string
   prior: string
   resp: string
+  stale: string
   state: string
   ui: string
   unmatched: string
@@ -211,7 +225,7 @@ export const uiState = (payload: Payload, head: string): string => {
   return `${heading}-${covered ? 'head' : 'behind'}-${commit.slice(0, 7)}`
 }
 
-/** Takes the first eight fields and ignores the rest, so a short or padded line still reads. */
+/** Takes the first ten fields and ignores the rest, so a short or padded line still reads. */
 export const parseBaseline = (line: string): Baseline => {
   const fields = line.split(' ')
 
@@ -219,14 +233,21 @@ export const parseBaseline = (line: string): Baseline => {
     head: fields[1] ?? '',
     merges: fields[4] ?? '',
     number: fields[0] ?? '',
+    overlaps: fields[9] ?? '',
     prior: fields[2] ?? '',
     resp: fields[3] ?? '',
+    stale: fields[8] ?? '',
     state: fields[5] ?? '',
     ui: fields[7] ?? '',
     unmatched: fields[6] ?? '',
   }
 }
 
+/**
+ * New fields append at the end, so every positional read of an older line still
+ * lands. A field an older line never carried stays empty and is not written
+ * back as a trailing space.
+ */
 export const formatBaseline = (entry: Baseline): string =>
   [
     entry.number,
@@ -237,10 +258,30 @@ export const formatBaseline = (entry: Baseline): string =>
     entry.state,
     entry.unmatched,
     entry.ui,
-  ].join(' ')
+    entry.stale,
+    entry.overlaps,
+  ]
+    .join(' ')
+    .trimEnd()
 
 const short = (head: string): string => head.slice(0, 7)
 
+const listFiles = (files: string[]): string =>
+  files.length > 3
+    ? `${files.slice(0, 3).join(', ')}, +${files.length - 3} more`
+    : files.join(', ')
+
+/**
+ * A conflict already sends the branch to its owner for a rebase, so a pull
+ * request reading both reports the conflict alone and earns one handback.
+ */
+const staleLine = (row: Row, base: string): string[] =>
+  row.stale === 'stale' && row.merges !== 'conflict'
+    ? [
+        `STALE     #${row.number} ${base} changed ${row.staleFiles.length} file(s) it writes since its base: ${listFiles(row.staleFiles)}`,
+      ]
+    : []
+
 export interface Classification {
   baseline: Baseline
   isChanged: boolean
@@ -266,8 +307,10 @@ const classifyFirstSighting = (
     head: row.head,
     merges: row.merges,
     number: row.number,
+    overlaps: 'none',
     prior: row.prior,
     resp: String(row.resp),
+    stale: row.stale,
     state: row.heading,
     ui: row.ui,
     unmatched: String(row.unmatchedCount),
@@ -280,7 +323,11 @@ const classifyFirstSighting = (
     line = `OPENED    #${row.number} at ${at}`
   }
 
-  return { baseline, isChanged: true, lines: [line] }
+  return {
+    baseline,
+    isChanged: true,
+    lines: [line, ...staleLine(row, context.base)],
+  }
 }
 
 const classifyUi = (row: Row, old: Baseline): string[] => {
@@ -312,11 +359,23 @@ export const classify = (
   let state = row.heading
 
   // A conflict arrives from the base moving, not from the branch, so it is
-  // reported on the transition rather than only when the head changes.
-  if (row.merges === 'conflict' && old.merges !== 'conflict') {
+  // reported on the transition rather than only when the head changes. A push
+  // that leaves it conflicting reports it again, for the same reason STALE does.
+  if (
+    row.merges === 'conflict' &&
+    (old.merges !== 'conflict' || row.head !== old.head)
+  ) {
     lines.push(`CONFLICT  #${row.number} no longer merges into ${context.base}`)
   }
 
+  // Staleness arrives the same way, and reports on its transition so a branch
+  // left behind across several runs earns one handback rather than one a run.
+  // A push that leaves it behind reports it again, since the draft lift reads a
+  // MOVED with no STALE beside it as the rebase having landed.
+  if (old.stale !== 'stale' || row.head !== old.head) {
+    lines.push(...staleLine(row, context.base))
+  }
+
   // A rising count is what is new here. It fires on a tracked pull request
   // only: a first sighting takes whatever already sits on the thread as its
   // baseline rather than flagging history retroactively.
@@ -386,8 +445,10 @@ export const classify = (
     head: row.head,
     merges: row.merges,
     number: row.number,
+    overlaps: old.overlaps,
     prior: row.prior,
     resp: String(row.resp),
+    stale: row.stale,
     state,
     ui: row.ui === '' ? old.ui : row.ui,
     unmatched: String(row.unmatchedCount),
@@ -396,6 +457,29 @@ export const classify = (
   return { baseline, isChanged: lines.length > 0, lines }
 }
 
+/**
+ * One pull request's base movement as a single line. STALE and CONFLICT print
+ * in the poll only on a transition or a push, so a reader deciding a draft
+ * lift reads this instead. A reading that could not be taken is unknown, never
+ * clear.
+ */
+export const standingLine = (
+  entry: Pick<Baseline, 'head' | 'merges' | 'number' | 'stale'>,
+): string => {
+  const at = short(entry.head)
+  if (entry.merges === 'conflict') {
+    return `CONFLICT  #${entry.number} standing at ${at}`
+  }
+  if (entry.stale === 'stale') {
+    return `STALE     #${entry.number} standing at ${at}`
+  }
+  if (entry.merges === 'clean' && entry.stale === 'fresh') {
+    return `CLEAR     #${entry.number} at ${at}`
+  }
+
+  return `UNKNOWN   #${entry.number} at ${at}, whether it merges or is current could not be read`
+}
+
 /**
  * A pull request this run could not read keeps the line it had, so the GONE
  * sweep does not read the gap as a merge. Its heading is blanked to a value no
@@ -532,6 +616,152 @@ const readMerges = (number: string, head: string, ref: string): string => {
     : 'conflict'
 }
 
+interface Written {
+  forkPoint: string
+  paths: string[]
+}
+
+const nonEmptyLines = (output: string): string[] =>
+  output.split('\n').filter((line) => line !== '')
+
+/**
+ * The paths a pull request writes, read from its own diff against the commit it
+ * branched from. `--no-renames` lists both sides of a rename, since a change on
+ * the base to either one is a change under the branch. A head or base that does
+ * not resolve, which a fork or a deleted head leaves, reads as null.
+ */
+const readWritten = (head: string, ref: string): null | Written => {
+  const forkPoint = run('git', ['merge-base', ref, head])
+  if (!forkPoint.isOk) return null
+  const point = forkPoint.stdout.trim()
+  const diff = run('git', ['diff', '--name-only', '--no-renames', point, head])
+  if (!diff.isOk) return null
+
+  return { forkPoint: point, paths: nonEmptyLines(diff.stdout) }
+}
+
+/**
+ * Re-testing after every merge to the base is a merge queue's cost without its
+ * batching, so only a change to a path the branch writes makes it stale. The
+ * net diff rather than the log is read, so a change the base made and then
+ * reverted moves nothing.
+ */
+const readStale = (
+  written: null | Written,
+  ref: string,
+): { files: string[]; stale: Staleness } => {
+  if (written === null) return { files: [], stale: 'unknown' }
+  if (written.paths.length === 0) return { files: [], stale: 'fresh' }
+
+  const moved = run('git', [
+    '--literal-pathspecs',
+    'diff',
+    '--name-only',
+    '--no-renames',
+    written.forkPoint,
+    ref,
+    '--',
+    ...written.paths,
+  ])
+  if (!moved.isOk) return { files: [], stale: 'unknown' }
+
+  const files = nonEmptyLines(moved.stdout)
+
+  return { files, stale: files.length > 0 ? 'stale' : 'fresh' }
+}
+
+export interface Overlap {
+  files: string[]
+  pair: readonly [string, string]
+}
+
+/**
+ * Pairwise merge-tree grows with the square of open pull requests, so only a
+ * pair sharing a written path is tested. Each pair comes lower number first,
+ * which fixes the order its line and its baseline entry are read in.
+ */
+export const sharedPairs = (rows: Row[]): [Row, Row][] => {
+  const readable = rows
+    .filter((row) => row.paths !== null && row.paths.length > 0)
+    .toSorted((a, b) => Number(a.number) - Number(b.number))
+  const pairs: [Row, Row][] = []
+  for (const [index, first] of readable.entries()) {
+    const written = new Set(first.paths)
+    for (const second of readable.slice(index + 1)) {
+      if ((second.paths ?? []).some((path) => written.has(path))) {
+        pairs.push([first, second])
+      }
+    }
+  }
+
+  return pairs
+}
+
+const partnersOf = (entry: Baseline | undefined): string[] =>
+  entry === undefined || entry.overlaps === '' || entry.overlaps === 'none'
+    ? []
+    : entry.overlaps.split(',')
+
+/**
+ * A partner this run could not read keeps its place, so a pull request that
+ * drops out of one run and returns does not report the same pair twice.
+ */
+export const overlapPartners = (
+  number: string,
+  overlaps: Overlap[],
+  old: Baseline | undefined,
+  carried: Set<string>,
+): string => {
+  const partners = new Set(
+    overlaps.flatMap(({ pair: [first, second] }) =>
+      first === number ? [second] : second === number ? [first] : [],
+    ),
+  )
+  for (const partner of partnersOf(old)) {
+    if (carried.has(partner)) partners.add(partner)
+  }
+  const sorted = [...partners].toSorted((a, b) => Number(a) - Number(b))
+
+  return sorted.length === 0 ? 'none' : sorted.join(',')
+}
+
+/** A pair reports once, read off the lower-numbered side's baseline entry. */
+export const overlapLines = (
+  overlaps: Overlap[],
+  known: Map<string, Baseline>,
+): string[] =>
+  overlaps
+    .filter(
+      ({ pair: [first, second] }) =>
+        !partnersOf(known.get(first)).includes(second),
+    )
+    .map(
+      ({ files, pair: [first, second] }) =>
+        `OVERLAP   #${first} #${second} conflict on ${listFiles(files)}`,
+    )
+
+/**
+ * Two pull request heads merged against each other, which is the merge the
+ * second to land will have to make. merge-tree exits 1 on a conflict and
+ * prints the tree then one conflicted path a line. Any other failure prints no
+ * tree, and reads as null beside a clean merge, since neither names a file.
+ */
+const readOverlap = (first: string, second: string): null | string[] => {
+  const merged = run('git', [
+    'merge-tree',
+    '--write-tree',
+    '--name-only',
+    '--no-messages',
+    first,
+    second,
+  ])
+  if (merged.isOk) return null
+  const lines = nonEmptyLines(merged.stdout)
+  if (lines.length < 2) return null
+
+  return [...new Set(lines.slice(1))]
+}
+
 const buildRow = (
   number: string,
   payload: Payload,
@@ -545,17 +775,23 @@ const buildRow = (
     run('canon', ['pr', 'review-state', number, '--json']).stdout,
   )
   const scope = scopeFromVerb(record, now) ?? scopeFallback(payload, now)
+  const merges = readMerges(number, head, ref)
+  const written = merges === 'unknown' ? null : readWritten(head, ref)
+  const stale = readStale(written, ref)
 
   return {
     age: scope.age,
     head,
     heading: scope.state,
-    merges: readMerges(number, head, ref),
+    merges,
     number,
     passAt: scope.readAt,
+    paths: written?.paths ?? null,
     prior: scope.commit,
     replyAt: replies.newestAt,
     resp: replies.count,
+    stale: stale.stale,
+    staleFiles: stale.files,
     ui: uiState(payload, head),
     unmatchedCount: unmatched.count,
     unmatchedHeading: unmatched.heading,
@@ -573,7 +809,37 @@ const countSince =
     return log.isOk ? log.stdout.split('\n').filter((l) => l !== '').length : 0
   }
 
-const main = (): number => {
+/**
+ * `--check <number>` reads the base and the head at call time and writes
+ * nothing. The baseline is as old as the last full run, and a sibling merging
+ * after it would leave a stored reading claiming clear.
+ */
+const check = (number: string): number => {
+  const ref = baseRef()
+  run('git', ['fetch', '-q', 'origin', baseBranch(ref)])
+  const head = readHead(number)
+  if (head === '') {
+    console.error(
+      `poll: #${number} returned no head, so nothing is known about it`,
+    )
+
+    return 1
+  }
+  const merges = readMerges(number, head, ref)
+  const written = merges === 'unknown' ? null : readWritten(head, ref)
+  console.log(
+    standingLine({
+      head,
+      merges,
+      number,
+      stale: readStale(written, ref).stale,
+    }),
+  )
+
+  return 0
+}
+
+const main = (args: string[]): number => {
   const root = mainRoot()
   if (root === null) {
     console.error('poll: not a git repository, so nothing is classified')
@@ -583,6 +849,7 @@ const main = (): number => {
 
   // The baseline is per-machine mutable state, so it stays in gitignored
   // scratch even though the script is tracked.
+  if (args[0] === '--check') return check(args[1] ?? '')
   const stateDir = join(root, '.canon', 'tmp', 'pr', 'poll')
   mkdirSync(stateDir, { recursive: true })
   const statePath = join(stateDir, 'baseline.txt')
@@ -655,6 +922,22 @@ const main = (): number => {
     snapshots.push({ row: buildRow(number, payload, head, ref) })
   }
 
+  const rows = snapshots.flatMap((snapshot) =>
+    'row' in snapshot ? [snapshot.row] : [],
+  )
+  const carried = new Set(
+    snapshots.flatMap((snapshot) =>
+      'baseline' in snapshot ? [snapshot.baseline.number] : [],
+    ),
+  )
+  const overlaps = sharedPairs(rows).flatMap(([first, second]) => {
+    const files = readOverlap(first.head, second.head)
+
+    return files === null
+      ? []
+      : [{ files, pair: [first.number, second.number] as const }]
+  })
+
   let isChanged = false
   const final: string[] = []
   const seen = new Set<string>()
@@ -667,13 +950,24 @@ const main = (): number => {
 
     const { row } = snapshot
     seen.add(row.number)
-    const result = classify(row, known.get(row.number), {
+    const old = known.get(row.number)
+    const result = classify(row, old, {
       base,
       countSince: countSince(row.number),
     })
     for (const line of result.lines) console.log(line)
     if (result.isChanged) isChanged = true
-    final.push(formatBaseline(result.baseline))
+    final.push(
+      formatBaseline({
+        ...result.baseline,
+        overlaps: overlapPartners(row.number, overlaps, old, carried),
+      }),
+    )
+  }
+
+  for (const line of overlapLines(overlaps, known)) {
+    console.log(line)
+    isChanged = true
   }
 
   for (const entry of previous) {
@@ -688,4 +982,4 @@ const main = (): number => {
   return 0
 }
 
-if (import.meta.main) process.exitCode = main()
+if (import.meta.main) process.exitCode = main(process.argv.slice(2))

package/claude/skills/role-planner/REQUIREMENT.md

@@ -89,4 +89,4 @@ four carried at least one, caught only because the planner ran
 - The mechanical addressee resolution, which `session-relay` owns for every session with or without a role
 - The branch, the build, and the pull request, which `role-worker` and `auto-ship` own
 - Deciding which rows run and in what order, which is the controlling session's call and stated in `role-orchestrator`
-- The dispatch itself, its collision check, and its disjointness gate, which `orchestrator-dispatch.md` holds
+- The dispatch itself, its collision check, and its conflict check, which `orchestrator-dispatch.md` holds

package/claude/skills/role-planner/SKILL.md

@@ -42,7 +42,7 @@ Each item below is something a record needed and a launch string did not carry.
 - The task file, and its `## Findings` before deciding anything. A row can carry its own disproof under a title that still states the original claim, which is how one trial nearly planned against a premise the file had already recorded as dead.
 - The source files themselves, opened rather than summarized. Never a count quoted from the task file, which was wrong or stale in ten places across four plans.
 - `CLAUDE.md` and `canon/ARCHITECTURE.md`, for the decision and the alternative it was taken against rather than for the decision alone.
-- `.canon/tasks/priority.md` for the row's Touches column and its stated blocker. That column is the file set the dispatch disjointness gate already reads.
+- `.canon/tasks/priority.md` for the row's Touches column and its stated blocker. That column is the file set the dispatch conflict check already reads. Read it for the shared-path lines and the holds of the constraint block, never as a gate a plan must clear.
 
 Two reads belong to the `plan-feature` path alone, since neither a groundwork
 track nor an intake pass is sequenced behind another row or validated as a plan:
@@ -60,7 +60,7 @@ it.
 - Run `canon sessions list --json`, take the `branch` field of every session whose `repository` matches this one and whose branch is neither null nor the trunk branch, union that with every `headRefName` from `gh pr list --json number,headRefName`, dedupe by branch name, then diff each with `git diff --name-only main...<branch>` for its file set. That resolves locally whether or not a pull request exists, since every track in this repository shares one git directory across its worktrees.
 - A bare branch or worktree with neither a live session nor a pull request behind it is still not evidence, since this repository squash-merges and leaves both behind. The roster read is already filtered to live sessions, so what changed is the second source composed with it rather than a raw count. It still misses a live session that reached its worktree through the direct-path fallback rather than `EnterWorktree`, since that session's registered branch never moves off the trunk.
 - Run the read once per row rather than once per batch. A session working several rows ages its picture of the tree while it goes, and this read is what dates it.
-- Name each in-flight set as a constraint, say which act it forbids, and stamp the block with the commit the tree was read at. A bare path list leaves the reader guessing. The plan standard fixes that block for a feature plan, and a groundwork or intake record carries the same three parts in whatever shape its own standard states.
+- Name each in-flight set as a constraint, being a hold that says which act it forbids or a shared path that says which branch rebases, and stamp the block with the commit the tree was read at. A bare path list leaves the reader guessing. The plan standard fixes that block for a feature plan, and a groundwork or intake record carries the same three parts in whatever shape its own standard states.
 
 ## The board is read-only
 

package/claude/skills/role-reviewer/SKILL.md

@@ -25,7 +25,7 @@ from here.
 
 ## Where the session stands
 
-- Write the review comment through `review-pr` and the body file it names under `.canon/tmp/pr/review/`, and nothing else. A UI reviewer writes the comment `review-ui` posts, its body file, and the browser's snapshots and frames, all under `.canon/tmp/pr/review-ui/`. A tracked file, a branch, a worktree, a board file, and a commit all sit outside what this session may touch.
+- Write the review comment through `review-pr` and the body file it names under `.canon/tmp/pr/review/`, and nothing else. A UI reviewer writes the comment `review-ui` posts, its body file, and the browser's snapshots and frames, all under `.canon/tmp/pr/review-ui/`, and ticks the boxes it passed on the evidence comment through `canon pr tick`. A tracked file, a branch, a worktree, a board file, and a commit all sit outside what this session may touch.
 - Never enter a worktree and never check the branch out. The pass reads a change, and a checkout is the first step toward editing it.
 - Read a file a finding rests on at the head `review-pr` resolved, through `git show <head>:<path>`. The main worktree holds the trunk, so a finding read off its copy is about a tree the pull request never changed, and it reads as confidently as one that is right.
 - Resolve `.canon/plans/`, `.canon/tasks/`, and `.canon/tmp/` at the main worktree root, and send the body file as a heredoc, the main-root route `session-worktree` states. Report a plan or task that fails to resolve there as unreadable, naming the path, rather than reviewing as though the branch had none.

package/claude/skills/role-worker/SKILL.md

@@ -49,7 +49,7 @@ The controlling session cannot watch this one build, so the messages below are
 owed and nothing else.
 
 - Announce the pull request as the ship chain's pull request step returns, carrying the number, the branch, and the task it closes. That transition is the one moment only this session knows, and the controller's review poll no longer starts on a dispatch because of it.
-- Carry the reach in that same message: the paths this branch wrote that another live plan or `## Run now` row holds, and who holds each, which `canon tasks plan-reach` reports as `claimed`. The gate cleared this branch against a prediction it has since outgrown, so the controller holds a disjointness reading that stopped being true hours ago and nothing else tells it. Say the reach was unread rather than clear when the installed binary carries no such subcommand, and leave the undeclared list to the pull request.
+- Carry the reach in that same message: the paths this branch wrote that another live plan or `## Run now` row holds, and who holds each, which `canon tasks plan-reach` reports as `claimed`. Report each as a rebase the controller should order, never as a breach, since sharing a path is not a hold. The gate cleared this branch against a prediction it has since outgrown, so the controller holds a reading of what this branch shares that stopped being true hours ago and nothing else tells it. Say the reach was unread rather than clear when the installed binary carries no such subcommand, and leave the undeclared list to the pull request.
 - Carry a row this build turned up in that same message, with its title, its origin, and the surface it would take. Send it as its own message only when the session will end before a pull request opens, since the row has no other way to reach the controller.
 - Announce when an address-review pass finishes, as `review-address` Step 8 returns, carrying what was addressed and the PR's new CI state. That transition is the other moment only this session knows, and it is what tells the controller to re-review rather than leaving it to poll for an answer nothing marks as landed.
 - Send a block out as a message before it becomes an interactive prompt.
@@ -84,7 +84,8 @@ feature branch and a controller does not.
 - Refuse an instruction the tree contradicts, and carry the evidence with it. Name the commands read and the consequences of complying, rather than reporting reluctance.
 - Halt on a plan question written as needing the operator's call. The plan standard defines that as a stop for an executing session, so the dispatch that sent it unattended is the defect and the halt is not.
 - Halting is cheap and guessing is not. Four measured halts each cost the dispatcher one reply, and the correction that mattered most reached the right place because a worker argued back rather than complying.
-- Read a file named as held, whether by a plan's Constraints block or by a controller's message sent mid-build, at the hunk against the branch or pull request holding it before conceding it.
+- Write a file a constraint names as shared, and keep both sides on the rebase. A shared path forbids nothing, so the hunk comparison below does not apply to it.
+- Read a file named as held, whether by a plan's Constraints block or by a controller's message sent mid-build, at the hunk against the branch or pull request holding it before conceding it. A hold is a dependency, a contract, a relocation, or a sweep.
 - Report that reading to the controller as the hunks or line ranges on each side, and take its reply as the call on whether the file is kept or given up, not a decision this session makes alone.
 - When the holding track carries no commits yet, there is nothing to diff. Compare against the file set its plan declares instead, and report that the hunk comparison could not be taken, rather than conceding on the name or proceeding as if the sets never collided.
 - A dispatcher once named three files a branch was writing. The worker diffed that branch, found its hunks at two lines against its own at three others, and reported the comparison, and the dispatcher reversed the instruction and returned every file.

package/claude/skills/ui-checklist/SKILL.md

@@ -41,7 +41,7 @@ Write each box so a session driving the running app can run it without guessing:
 - **Taste.** End the line with `(taste)` when the result is a judgment of look or feel rather than a fact a driver can observe. A driver reports such a box as needing a person's eyes instead of passing it.
 - **Setup.** A box needing a state the page does not open in states the setup inline. When a hosted preview cannot reach that state, such as a stopped service or a seeded record, end the line with `(local only)` instead.
 
-The checkbox stays `- [ ]` followed by the action and the result, since the evidence comment carries ticked boxes forward by that shape.
+The checkbox stays `- [ ]` followed by the action and the result, since the evidence comment reads boxes by that shape. Only the UI reviewer ticks a box, stamping it with the commit it passed at, and the comment carries that tick forward only while the head it names is current.
 
 ## The missing-test list
 

package/docs/agents/canvas.md

@@ -39,23 +39,23 @@ A pick is refused as `address-mismatch` when the browser builds elements the fil
 
 ## Edit
 
-`canvas edit <page>/<frame> --element <index> --set <property>=<value>` sets one property of the element at that index, the same index `canvas selection` reports. The properties are `text`, `color`, `background-color`, `font-size`, `font-weight`, `width`, `height`, `padding`, `gap`, `display`, `flex-direction`, `justify-content`, `align-items`, `flex-wrap`, `opacity`, `border-radius`, `border-top-left-radius`, `border-top-right-radius`, `border-bottom-right-radius`, and `border-bottom-left-radius`. A style property is written into the element's inline `style`, replacing that property and leaving the others as they were, and an empty value drops it. Writing `border-radius` or `padding` also drops that shorthand's longhands from the same `style`, so no corner or side left over overrides the new value. Writing a longhand leaves its shorthand in place, since the longhand comes later and wins.
+`canvas edit <page>/<frame> --element <index> --set <property>=<value>` sets one property of the element at that index, the same index `canvas selection` reports. The properties are `text`, `color`, `background-color`, `font-size`, `font-weight`, `font-family`, `line-height`, `letter-spacing`, `text-align`, `width`, `height`, `padding`, `gap`, `display`, `flex-direction`, `justify-content`, `align-items`, `flex-wrap`, `opacity`, `border-radius`, `border-top-left-radius`, `border-top-right-radius`, `border-bottom-right-radius`, and `border-bottom-left-radius`. A style property is written into the element's inline `style`, replacing that property and leaving the others as they were, and an empty value drops it. Writing `border-radius` or `padding` also drops that shorthand's longhands from the same `style`, so no corner or side left over overrides the new value. Writing a longhand leaves its shorthand in place, since the longhand comes later and wins.
 
 `text` replaces the text of an element holding text alone and refuses one holding other elements as `not-text-only`. Every byte outside the element stays as it was. `--json` emits the page, frame, file, path, and the file's new `hash`.
 
 The operator edits the same set from the inspector, which posts to the same writer with the hash the frame was served with. Dragging a selected element's corner handle writes `width` and then `height` in pixels through that writer, the second edit carrying the hash the first answered. An edit made against a version of the file Claude has since rewritten is refused as `stale-address` and the shell reloads the frame, so nothing lands on a shifted element. Both writers take the frame file's lock, and an edit that keeps the selected element where it was keeps the selection fresh.
 
-Size, padding, opacity, and radius show in the inspector for every element. The flex fields show only on a flex container, a grid container gets none, and the inspector sets `display` only to `flex`, so any other `display` change goes through the verb.
+Size, padding, opacity, radius, and the type properties show in the inspector for every element. Family and font size list the sheet's `font-family` and `font-size` token groups first and write a pick as `var(--<name>)`, the same as a color. The flex fields show only on a flex container, a grid container gets none, and the inspector sets `display` only to `flex`, so any other `display` change goes through the verb.
 
 A color picked from the project's tokens is written as `var(--<name>)`, and below full opacity as a `color-mix()` of that `var()` with `transparent` at the opacity percent, so it keeps following the theme. A browser older than 2023 drops a `color-mix()` value, which leaves the property unset there. A hex is written as six digits, or eight below full opacity. The inspector's full color picker writes a hex for any color it sets, so the field marks the value raw, and only its alpha keeps a token through the `color-mix()` form.
 
-Inline style beats a class, so an operator's edit masks a class change Claude makes later. Read a frame's inline styles before restyling it, and remove one the change should replace. The inspector marks a color or background set inline with the word `raw` when its value names no `var()` and is not `currentColor` or a CSS-wide keyword, since that value stays fixed when the theme changes. A property outside the set, or a value carrying `;`, `{`, `}`, `<`, `>`, or a line break, is refused as `invalid-edit`.
+Inline style beats a class, so an operator's edit masks a class change Claude makes later. Read a frame's inline styles before restyling it, and remove one the change should replace. The inspector marks a color, a background, or a family or font size the sheet has tokens for, set inline, with the word `raw` when its value names no `var()` and is not `currentColor` or a CSS-wide keyword, since that value stays fixed when the theme changes. A property outside the set, or a value carrying `;`, `{`, `}`, `<`, `>`, or a line break, is refused as `invalid-edit`.
 
 The Theme tab in the shell lists what the token stylesheet defines, grouped as color, spacing, radius, font family, font size, and other. The page record at `/api/pages` carries the same list as `tokens.groups`.
 
 ## Mark a frame being edited
 
-`canvas editing <page>/<frame>` marks a frame as being edited, so an open canvas can show who is working on it before the write lands. Run it before writing a frame and again with `--done` once the edits are written. A bare `canvas editing` lists the live marks, and `--json` emits `{ ok, editing }` after each of the three, with each mark carrying `page`, `frame`, `by`, `since`, and `until`.
+`canvas editing <page>/<frame>` marks a frame as being edited, so an open canvas shows who is working on it before the write lands. The shell draws the mark as `<by> editing` on that frame's label with a dashed outline around it, and drops it on the reread after `--done` or at the mark's `until` with no reread. Run it before writing a frame and again with `--done` once the edits are written. A bare `canvas editing` lists the live marks, and `--json` emits `{ ok, editing }` after each of the three, with each mark carrying `page`, `frame`, `by`, `since`, and `until`.
 
 The label is `--by <name>` when given. Without it, the verb reads the caller's name off the session roster, and falls back to `a session` when the environment names no session or the roster holds none matching it.
 

package/docs/agents/gate.md

@@ -86,4 +86,6 @@ One code for a failure, which is what a `bun run` caller and a git hook both rea
 
 A failing stage carries its remedy in `failure`, and the same line goes to stderr so a caller reading neither the record nor the frame is still told what to fix.
 
-`ms` carries the wall time each stage's checks took, including every process spawn, and the top-level `ms` sums them. Neither reading changes what a stage measures. Both exist so a slow run is attributable to a stage rather than read off a stopwatch held against the whole thing.
+`ms` carries the wall time each stage took, including every process spawn, and the top-level `ms` sums them. Neither reading changes what a stage measures. Both exist so a slow run is attributable to a stage rather than read off a stopwatch held against the whole thing.
+
+The Tests stage holds a machine lock so one box runs one suite at a time, and its `ms` includes any time it queued behind another worktree's suite. A stage that queued carries `queuedMs`, the part of `ms` spent waiting, which is how to separate a queue from a slow suite. The field is absent on a stage that never waited. The wait is also announced on stderr when it starts, naming the holder's pid and worktree, in every mode.

package/docs/agents/index.md

@@ -40,6 +40,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [The pull request local preview](pr-local.md): How canon pr local finds the server a worktree is running, why a server in another worktree is never reported, the refusal reasons it names, and how a close workflow drops the address line with --remove
 - [The pull request preview deploy](pr-preview.md): How canon pr preview finds a fenced Cloudflare Pages deploy, refuses a branch its push filter does not serve, dispatches it on a pull request's branch, reads the alias the run prints, the refusal reasons it names, and why an unfenced deploy is refused before anything runs
 - [Head-sensitive pull request reads](pr-reads.md): Resolving a branch tip from the remote rather than from the pull request object, reading what a review pass covered off its own marker rather than off GitHub's submission stamps, why an empty run list is not a pass, the refusal reasons each verb names, and what the remote read costs
+- [The pull request checklist tick](pr-tick.md): How canon pr tick marks the checklist boxes a UI pass drove, the stamp that names the commit each passed at, why a render at a newer head clears a tick, the refusal reasons it names, and why a taste box is never ticked
 - [Records push](records-push.md): Backing the record folders to a private remote and restoring them, which folders the payload carries, the one-time setup, the refusal reasons, and the hook that runs the push
 - [Records stale](records-stale.md): Reading the memory pen as a review queue, what makes an entry due, how a cited path is read and resolved, the order entries come back in, counting the releases since the requirements and architecture records were last reviewed, and the exit codes and refusals
 - [Records validate](records-validate.md): Validating the session records and the standards corpus, the per-kind checks, which root each kind defaults to, the exit codes, and the refusal reasons
@@ -61,7 +62,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Targets](targets.md): The projects this toolkit installed into, the record the install writes against the sweep that backs it, what bounds each answer, and the cross-target pull request read
 - [Tasks archive](tasks-archive.md): Archiving a shipped task by stem or pull request, declining one decided against, the refusal reasons each carries, and how the plan and ready folder move with the task
 - [Tasks plans](tasks-plans.md): The five verbs that read or write a task's plan, being where it sits and who cites it, whether it waits on the operator, the branch it derives, what a branch reached against what it declared, and writing its Plan line
-- [Tasks validate](tasks-validate.md): Validating the board against the tree, the seven checks, the untested, claims, wide, and unplaced arrays, the exit codes, and the refusal reasons
+- [Tasks validate](tasks-validate.md): Validating the board against the tree, the seven checks, the five report arrays, the exit codes, and the refusal reasons
 - [Tasks](tasks.md): Claiming the next phase label, recording a pull request number and closing an outcome, listing each task's readiness, and where archiving, the plan verbs, and board validation are described
 - [Teach authoring](teach-authoring.md): Resolving what the next lesson needs before it is written, rendering a lesson body's blocks to HTML, and rewriting the root listing, a contents page, and each lesson's chrome and quiz stepper from its marker regions
 - [Teach](teach.md): Listing learning workspaces with what their records schedule next, opening one with its required files, recording sources and glossary terms, viewing one with its chrome refreshed, where the lesson authoring verbs are described, the refusal reasons, and why every write here runs through a verb

package/docs/agents/pr-evidence.md

@@ -33,16 +33,16 @@ its filename carries an image extension (`png`, `jpg`, `jpeg`, `gif`, `webp`,
 folder holds whatever else a project keeps beside its captures. This
 repository's own tree carries eight `.md` files, two `.sh` scripts, a `.tsv`,
 a `.json`, and an `.html` file against a single `.png`, and every one of them
-would render as a broken `![]()` embed without the extension filter.
+would render as a broken image embed without the extension filter.
 
 ## What the record carries
 
 The record groups every evidence path by state, the remainder of its
 directory under the `evidence/` segment, and within a state by filename stem,
 so a `before/hero.png` and an `after/hero.png` naming the same case group as
-one entry rather than two unrelated files. Each entry carries whether it
-existed at the base commit, which decides whether the comment shows a base
-image or marks the case new.
+one entry, not two files. Each entry carries whether it existed at the base
+commit, so the comment shows a base image or marks it new. All-new states drop
+the Base column and each image is an `<img width="1000">`.
 
 `reason` on the record is what a caller branches on, not the exit code:
 
@@ -73,6 +73,7 @@ shows a reviewer, each field present only when that comment holds it:
 | `preview`   | The hosted `**Preview:**` address on the comment's address line.  |
 | `local`     | The `**Local preview:**` address beside it.                       |
 | `checklist` | The checklist between its delimiters, with any ticked boxes kept. |
+| `boxes`     | Each box's `number`, `text`, tick, `stamp`, and `isTaste`.        |
 
 These come from the comment already posted, never from the flags the call
 passed, so a skill driving a review reads which address and which checklist a
@@ -102,7 +103,7 @@ The trade is that the verb no longer sees evidence that is uncommitted or
 unpushed, which the comment's head-pinned image links could not show anyway.
 A path the pull request renamed or copied counts as added, since the new path
 has no counterpart at the merge base, so a rename loses its before image and
-renders `*(new)*`. A path the pull request removed is dropped, since it has no
+reads as new. A path the pull request removed is dropped, since it has no
 head image to show. A failed files read refuses as `unreadable-changes` rather
 than rendering a short set, and a missing merge base refuses as `no-base`.
 
@@ -181,9 +182,9 @@ screenshots, and what a reviewer has to look at. The file is what
 
 A run without the option carries forward whatever checklist the marked comment
 already holds, the same way the preview address is carried. That is what keeps
-`git-followup`'s re-render after a push from wiping boxes a reviewer has
-already ticked, since `git-pr` deletes the handoff once the first post reports
-success and no later call has a file to pass.
+`git-followup`'s re-render after a push from dropping the checklist, since
+`git-pr` deletes the handoff once the first post reports success and no later
+call has a file to pass. `canon docs pr-tick` covers what a tick carries.
 
 The option decides `no-evidence` on its own. A branch with a checklist and no
 changed evidence image renders `ok` with a marked body holding the checklist,