@erclx/canon 4.69.0 → 4.71.0

package/src/migrate/skill-names.ts

@@ -2,7 +2,8 @@ import { defineRenameRules, type RenameRules } from '@/migrate/rename'
 
 /**
  * The twenty-five shipped skills that carried a `claude-` prefix, and the
- * two-word name each takes instead.
+ * two-word name each takes instead, plus the four that carried a `canon-`
+ * prefix naming a subject other than the toolkit itself.
  *
  * The plugin namespace already resolves every one of them as `canon:<name>`,
  * so the prefix bought grouping rather than uniqueness, and the grouping it
@@ -11,9 +12,28 @@ import { defineRenameRules, type RenameRules } from '@/migrate/rename'
  * a listing groups the review triple, the three planning skills, and the three
  * session roles together.
  *
+ * The four `canon-` rows split the same way rather than sharing one
+ * replacement prefix. `canon-screencast` and `canon-slides-draft` draft a
+ * document, which is what the `draft-` family already means across its other
+ * members, so they join it as `draft-screencast` and `draft-slides`.
+ * `canon-record` and `canon-frames-read` are not drafting anything, so each
+ * takes a standalone verb-first name, `record-screencast` and `read-frames`,
+ * reading in sequence with `draft-screencast` as one three-step pipeline with
+ * no prefix forcing that reading.
+ *
  * Every name takes two words. Ten of these would have landed as a bare single
  * word under a plain strip, and a bare word such as `review` or `docs` is a
  * substring of ordinary prose with no token left for a later sweep to find.
+ *
+ * No bare single-word name may ever join this map, whatever prefix it would
+ * otherwise take. `wholeToken: true` below matches a standalone word rather
+ * than a namespaced compound, so a one-word key rewrites every unrelated use
+ * of that word too. `identity` proved it: a dry run against a fifth row
+ * reading `'identity': 'draft-identity'` reported 112 occurrences across 43
+ * files, most of them a variable, field, or type name spelling the bare word
+ * rather than the skill, including `readonly identity: SelfIdentity` at
+ * `src/sessions/resolve.ts:255`, which the rewrite would have turned into
+ * invalid TypeScript. The row was never added.
  */
 export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
   'claude-address-review': 'review-address',
@@ -41,6 +61,10 @@ export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
   'claude-ux-measure': 'ux-measure',
   'claude-worker': 'role-worker',
   'claude-worktree': 'session-worktree',
+  'canon-screencast': 'draft-screencast',
+  'canon-slides-draft': 'draft-slides',
+  'canon-record': 'record-screencast',
+  'canon-frames-read': 'read-frames',
 }
 
 /**

package/src/pr/review-scope.ts

@@ -0,0 +1,177 @@
+/**
+ * The last state a review pass covered, read off the pass's own marker rather
+ * than off the fields GitHub stamps when a review is submitted.
+ *
+ * `commit.oid` names whatever the pull request head was at the instant the
+ * review was submitted, not the commit the session read. A push landing between
+ * the read and the post moves that stamp onto a commit nobody reviewed, and the
+ * next pass then scopes its delta past work no reader has seen. `submittedAt`
+ * carries the same defect on the time axis. `review-pr` therefore writes the
+ * commit it read and the instant it read it into the body itself, and this
+ * module is the one place that marker is parsed.
+ */
+
+/** The two headings `review-pr` posts a pass under. */
+export const REVIEW_HEADINGS = ['## Review', '## Review closed'] as const
+
+export type ReviewHeading = (typeof REVIEW_HEADINGS)[number]
+
+/** Whether the thread's newest pass still owes work on it. */
+export type ReviewState = 'open' | 'closed' | 'none'
+
+/** Where the covered state came from. */
+export type ScopeSource =
+  /** The pass wrote its own read-time marker, which is the authority. */
+  | 'marker'
+  /** A pass posted before the marker shipped, read off GitHub's own stamps. */
+  | 'fallback'
+  /** The thread carries no pass at all, so this is a first pass. */
+  | 'none'
+
+export interface ReviewScope {
+  /** The heading of the newest pass, absent when the thread carries none. */
+  readonly heading?: ReviewHeading
+  /** The same fact as `heading`, collapsed for a caller that reads only state. */
+  readonly state: ReviewState
+  /** The commit the newest pass covered. */
+  readonly commit?: string
+  /** When that pass read the commit, present only under a marker. */
+  readonly readAt?: string
+  /** When GitHub recorded the pass, which trails `readAt` by the compose window. */
+  readonly submittedAt?: string
+  readonly source: ScopeSource
+}
+
+/** One row of `gh pr view --json reviews`. */
+export interface ReviewRow {
+  readonly body?: string
+  readonly commit?: { readonly oid?: string } | null
+  readonly submittedAt?: string | null
+}
+
+/**
+ * What this reads out of `gh pr view`.
+ *
+ * Only `reviews` is named, so a caller may hand over a wider payload it fetched
+ * for its own reasons without this module growing a field it never opens.
+ */
+export interface ReviewListing {
+  readonly reviews?: readonly ReviewRow[]
+}
+
+/**
+ * The marker `review-pr` appends as the last line of every body it posts.
+ *
+ * The sha is bounded at git's own abbreviation range rather than pinned to 40,
+ * since an abbreviated sha still names a commit and refusing one drops the pass
+ * back to the stamp this exists to replace.
+ *
+ * Anchoring to a whole line is not on its own what keeps a quoted marker out.
+ * It stops the inline form, where the surrounding backticks leave the trimmed
+ * line unmatchable, and a marker shown alone inside a fenced block trims to
+ * exactly this pattern. Position is what separates the two, which is why
+ * `markerOf` reads one line rather than searching.
+ */
+const MARKER =
+  /^<!--\s*review-pr:\s*commit=([0-9a-f]{7,40})\s+read-at=(\S+)\s*-->$/
+
+/**
+ * Loose enough to accept every stamp `date -u +%Y-%m-%dT%H:%M:%SZ` and
+ * `toISOString` produce, strict enough that a body carrying prose in the field
+ * falls back rather than handing a caller a value no date parser reads.
+ */
+const ISO_8601 =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:?\d{2})$/
+
+/**
+ * The heading a body opens with, or undefined when it opens with anything else.
+ *
+ * Matched for equality on the first line alone. A prefix test also reaches
+ * `## Review response`, which belongs to the reply family and would scope a
+ * pass to whatever commit a worker's answer carried. The `\r` trim covers a
+ * body composed in the GitHub web editor, which stores CRLF.
+ */
+function headingOf(body: string): ReviewHeading | undefined {
+  const first = (body.split('\n')[0] ?? '').replace(/\r$/, '')
+  return REVIEW_HEADINGS.find((heading) => heading === first)
+}
+
+/**
+ * The marker a body carries, or undefined when it carries none this reader
+ * trusts.
+ *
+ * The last non-empty line and no other. Searching the body for the last match
+ * instead reads a marker the body was displaying rather than claiming: a pass
+ * that shows the format on its own line inside a fenced block, and carries no
+ * marker of its own because it predates this shipping, would hand the next
+ * reader a covered commit taken from an illustration. That is the defect this
+ * module exists to close, arriving by another route and just as silently.
+ *
+ * Position costs nothing, since Step 4 of `review-pr` puts the marker on the
+ * last line of every body it writes, the `PUT` rewrite included. Trailing blank
+ * lines are skipped rather than read as an absent marker, which is the one
+ * thing the search was buying.
+ */
+function markerOf(
+  body: string,
+): { commit: string; readAt: string } | undefined {
+  const lines = body.split('\n')
+
+  let index = lines.length - 1
+  while (index >= 0 && (lines[index] ?? '').trim() === '') index -= 1
+  if (index < 0) return undefined
+
+  const match = MARKER.exec((lines[index] ?? '').trim())
+  if (match === null) return undefined
+
+  const [, commit, readAt] = match
+  if (commit === undefined || readAt === undefined) return undefined
+  if (!ISO_8601.test(readAt)) return undefined
+
+  return { commit, readAt }
+}
+
+/**
+ * Resolves what the newest review pass covered.
+ *
+ * The newest pass rather than the newest marker: a thread whose latest pass
+ * predates this mechanism reads through the fallback, and reaching back to an
+ * older marked pass would report a commit a later pass has already moved past.
+ */
+export function resolveReviewScope(listing: ReviewListing): ReviewScope {
+  let newest: { heading: ReviewHeading; row: ReviewRow } | undefined
+
+  for (const row of listing.reviews ?? []) {
+    const heading = headingOf(row.body ?? '')
+    if (heading === undefined) continue
+    newest = { heading, row }
+  }
+
+  if (newest === undefined) return { state: 'none', source: 'none' }
+
+  const { heading, row } = newest
+  const state: ReviewState = heading === '## Review' ? 'open' : 'closed'
+  const submittedAt = row.submittedAt ?? undefined
+  const stamped = submittedAt === undefined ? {} : { submittedAt }
+  const marker = markerOf(row.body ?? '')
+
+  if (marker !== undefined) {
+    return {
+      heading,
+      state,
+      commit: marker.commit,
+      readAt: marker.readAt,
+      ...stamped,
+      source: 'marker',
+    }
+  }
+
+  const oid = row.commit?.oid
+  return {
+    heading,
+    state,
+    ...(oid === undefined || oid === '' ? {} : { commit: oid }),
+    ...stamped,
+    source: 'fallback',
+  }
+}

package/src/tasks/archive.ts

@@ -8,6 +8,8 @@ import { recordDir, recordDirs } from '@/record-root'
 const TASKS = 'tasks'
 const PLANS = 'plans'
 const ARCHIVE = 'archive'
+const DECLINED = 'declined'
+const BACKLOG = 'backlog.md'
 
 /**
  * Siblings that sit on the board without being tasks: the generated index, the
@@ -48,6 +50,21 @@ export const ARCHIVE_REFUSALS = [
 
 export type ArchiveRefusal = (typeof ARCHIVE_REFUSALS)[number]
 
+/**
+ * Kept apart from `ARCHIVE_REFUSALS` on purpose. `archive` and `decline`
+ * answer different questions, shipped versus decided-against, and a shared
+ * refusal set would let one archive a task that cannot yet ship or decline
+ * one that already has.
+ */
+export const DECLINE_REFUSALS = [
+  'no-board',
+  'no-match',
+  'ambiguous',
+  'bad-input',
+] as const
+
+export type DeclineRefusal = (typeof DECLINE_REFUSALS)[number]
+
 export type TaskSelector =
   | { readonly kind: 'stem'; readonly stem: string }
   | { readonly kind: 'pull-request'; readonly number: number }
@@ -80,6 +97,27 @@ export interface ArchiveRefused {
 
 export type ArchiveOutcome = ArchiveSuccess | ArchiveRefused
 
+export interface DeclineSuccess {
+  readonly ok: true
+  readonly stem: string
+  readonly from: string
+  readonly to: string
+  readonly priorityRowRemoved: boolean
+  readonly backlogRowRemoved: boolean
+  readonly indexRegenerated: boolean
+  /** Undefined when the task cited no live plan, or when another task still holds it. */
+  readonly plan: PlanMove | undefined
+}
+
+export interface DeclineRefused {
+  readonly ok: false
+  readonly reason: DeclineRefusal
+  readonly message: string
+  readonly detail: readonly string[]
+}
+
+export type DeclineOutcome = DeclineSuccess | DeclineRefused
+
 export interface TaskOutcomes {
   readonly open: readonly string[]
   readonly closed: readonly string[]
@@ -94,6 +132,10 @@ export function archiveDir(root: string): string {
   return recordDir(root, TASKS, ARCHIVE)
 }
 
+export function declinedDir(root: string): string {
+  return recordDir(root, TASKS, DECLINED)
+}
+
 export const OUTCOME_PATTERN = /^- \[([ xX])\] ?(.*)$/
 
 /**
@@ -238,6 +280,62 @@ export function retargetPlanLine(text: string, target: string): string {
   return text.replace(PLAN_PATTERN, () => planLine(target))
 }
 
+/**
+ * Builds the `Declined:` line recording why a task was decided against and by
+ * whom. Free prose after the colon, since the line names no file to link,
+ * unlike `planLine`.
+ */
+export function declineLine(reason: string, by: string, date: string): string {
+  return `Declined: ${reason}, ${by} on ${date}`
+}
+
+/**
+ * Lines a `Declined:` line anchors after, mirroring `record.ts`'s
+ * `ORIGIN_PREFIXES` with `Pull request:` folded in, since a decline can follow
+ * a pull request that never merged.
+ */
+const DECLINE_ANCHOR_PREFIXES = [
+  'Plan:',
+  'Groundwork:',
+  'Intake:',
+  'Issue:',
+  'Pull request:',
+] as const
+
+function lastAnchorLine(lines: readonly string[]): number | undefined {
+  let found: number | undefined
+
+  for (const [index, line] of lines.entries()) {
+    if (DECLINE_ANCHOR_PREFIXES.some((prefix) => line.startsWith(prefix))) {
+      found = index
+    }
+  }
+
+  return found
+}
+
+/**
+ * Places the `Declined:` line after the origin lines a task carries, the same
+ * scan-and-anchor shape `writePullRequestLine` carries. A decline runs once
+ * per task, so there is no existing line to correct, unlike the
+ * add/correct/unchanged shape a write safe to run twice needs.
+ */
+function insertDeclinedLine(text: string, line: string): string {
+  const lines = text.split('\n')
+  const anchor = lastAnchorLine(lines)
+
+  if (anchor !== undefined) {
+    lines.splice(anchor + 1, 0, line)
+    return lines.join('\n')
+  }
+
+  const heading = lines.findIndex((entry) => entry.startsWith('# '))
+  if (heading === -1) return `${line}\n${text}`
+
+  lines.splice(heading + 1, 0, '', line)
+  return lines.join('\n')
+}
+
 /**
  * Drops the archived task's row from the ordering table. Rows are matched by
  * the link they carry rather than by a line pattern, because a row holds links
@@ -267,6 +365,27 @@ function isRowFor(line: string, target: string): boolean {
   return first !== undefined && first.includes(target)
 }
 
+/**
+ * Drops the declined task's bullet from the backlog. A backlog line is a
+ * bullet carrying a link rather than a table row, so the match is a bullet
+ * prefix and the link target rather than `isRowFor`'s pipe-delimited cell.
+ */
+export function removeBacklogRow(
+  text: string,
+  stem: string,
+): { readonly text: string; readonly removed: boolean } {
+  const target = `](${stem}.md)`
+  const lines = text.split('\n')
+  const kept = lines.filter((line) => !isBulletFor(line, target))
+
+  return { text: kept.join('\n'), removed: kept.length !== lines.length }
+}
+
+function isBulletFor(line: string, target: string): boolean {
+  const trimmed = line.trimStart()
+  return /^[-*]\s/.test(trimmed) && trimmed.includes(target)
+}
+
 /**
  * Resolves the `Plan:` target against the board and against the project root
  * both, which is how `docs-fold` reads the same line. It accepts `../plans/x.md`
@@ -481,11 +600,20 @@ async function matchByPullRequest(
   return read.filter((entry) => entry.number === number).map(({ stem }) => stem)
 }
 
-function refuse(
-  reason: ArchiveRefusal,
+/**
+ * Generic over the refusal vocabulary so `archiveTask` and `declineTask` share
+ * one builder despite answering with two disjoint reason sets.
+ */
+function refuse<Reason extends string>(
+  reason: Reason,
   message: string,
   detail: readonly string[] = [],
-): ArchiveRefused {
+): {
+  readonly ok: false
+  readonly reason: Reason
+  readonly message: string
+  readonly detail: readonly string[]
+} {
   return { ok: false, reason, message, detail }
 }
 
@@ -690,3 +818,78 @@ async function clearPriorityRow(dir: string, stem: string): Promise<boolean> {
 
   return removed
 }
+
+async function clearBacklogRow(dir: string, stem: string): Promise<boolean> {
+  const path = join(dir, BACKLOG)
+  if (!existsSync(path)) return false
+
+  const { text, removed } = removeBacklogRow(await readFile(path, 'utf8'), stem)
+  if (removed) await writeFile(path, text)
+
+  return removed
+}
+
+/**
+ * Declines one task as a single unit: the move, the ordering-or-backlog row
+ * removal, and the index regen. Unlike `archiveTask`, it carries no
+ * outcome-state gate, since a task decided against can sit at any outcome
+ * state, and the two never share a refusal set for the reason
+ * `DECLINE_REFUSALS` states.
+ */
+export async function declineTask(
+  root: string,
+  stem: string,
+  reason: string,
+  by: string,
+): Promise<DeclineOutcome> {
+  const dir = tasksDir(root)
+
+  if (!existsSync(dir)) {
+    return refuse('no-board', `No task board at ${relative(root, dir)}.`)
+  }
+
+  const stems = await listTaskStems(dir)
+  if (!stems.includes(stem)) {
+    const unmatched = describeUnmatchedStem(stems, stem)
+    return refuse(unmatched.reason, unmatched.message, unmatched.detail)
+  }
+
+  const from = join(dir, `${stem}.md`)
+  const text = await readFile(from, 'utf8')
+
+  const plan = await planToArchive(dir, root, stem, text)
+  const destination = declinedDir(root)
+  const to = join(destination, `${stem}.md`)
+
+  // The plan moves first, the same order archiveTask uses, so the retarget
+  // written below describes a file already at its new path.
+  if (plan) {
+    await mkdir(dirname(plan.to), { recursive: true })
+    await rename(plan.from, plan.to)
+  }
+
+  await mkdir(destination, { recursive: true })
+  await rename(from, to)
+
+  const date = new Date().toISOString().slice(0, 10)
+  const declined = insertDeclinedLine(text, declineLine(reason, by, date))
+  const final = plan
+    ? retargetPlanLine(declined, linkTo(destination, plan.to))
+    : declined
+  await writeFile(to, final)
+
+  const priorityRowRemoved = await clearPriorityRow(dir, stem)
+  const backlogRowRemoved = await clearBacklogRow(dir, stem)
+  const regen = await regenOne(dir, { dryRun: false })
+
+  return {
+    ok: true,
+    stem,
+    from,
+    to,
+    priorityRowRemoved,
+    backlogRowRemoved,
+    indexRegenerated: regen.action === 'written',
+    plan,
+  }
+}

package/src/tasks/label.ts

@@ -1,6 +1,11 @@
 import { existsSync } from 'node:fs'
 import { relative } from 'node:path'
-import { archiveDir, listTaskStems, tasksDir } from '@/tasks/archive'
+import {
+  archiveDir,
+  declinedDir,
+  listTaskStems,
+  tasksDir,
+} from '@/tasks/archive'
 
 /** Every label in the corpus today stops here before rolling to the next major. */
 const MINOR_ROLLOVER = 9
@@ -68,9 +73,10 @@ function next(label: Label): Label {
 
 /**
  * Reports the next unused phase label, read off the true maximum across
- * `.canon/tasks/` and its `archive/` sibling together. A scan confined to the
- * live board is blind to every label the archive already spent, which is what
- * let two sessions hand out the same label within minutes of each other.
+ * `.canon/tasks/` and its `archive/` and `declined/` siblings together. A scan
+ * confined to the live board is blind to every label a settled folder already
+ * spent, which is what let two sessions hand out the same label within
+ * minutes of each other.
  *
  * It reports and never writes. Two sessions calling it in the same second can
  * still take the same answer, since the board is gitignored files rather than
@@ -90,8 +96,10 @@ export async function nextLabel(root: string): Promise<LabelOutcome> {
     }
   }
 
-  const archive = archiveDir(root)
-  const dirs = existsSync(archive) ? [dir, archive] : [dir]
+  const settled = [archiveDir(root), declinedDir(root)].filter((candidate) =>
+    existsSync(candidate),
+  )
+  const dirs = [dir, ...settled]
   const stems = (await Promise.all(dirs.map((d) => listTaskStems(d)))).flat()
 
   const highest = stems

package/src/tasks/validate.ts

@@ -3,6 +3,7 @@ import { readdir, readFile } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
 import {
   archiveDir,
+  declinedDir,
   isReservedStem,
   readOutcomes,
   readPlanTarget,
@@ -47,6 +48,7 @@ export const FINDING_KINDS = [
   'touches-collided',
   'blocker-settled',
   'blocker-unresolved',
+  'blocker-declined',
 ] as const
 
 export type FindingKind = (typeof FINDING_KINDS)[number]
@@ -124,6 +126,7 @@ export interface ValidateReport {
   readonly rows: number
   readonly backlog: number
   readonly tasks: number
+  readonly declined: number
   readonly findings: readonly Finding[]
   readonly untested: readonly Untested[]
   readonly claims: readonly FolderClaim[]
@@ -970,6 +973,20 @@ async function checkCitedTask(
       return settled(group, subject, `waits on ${cited}, which is archived.`)
     }
 
+    if (existsSync(join(declinedDir(root), `${cited}.md`))) {
+      return {
+        findings: [
+          {
+            kind: 'blocker-declined',
+            group,
+            subject,
+            message: `waits on ${cited}, which was declined.`,
+          },
+        ],
+        untested: [],
+      }
+    }
+
     return {
       findings: [
         {
@@ -1158,6 +1175,10 @@ export async function validateBoard(
     : []
 
   const stems = await listTaskStems(dir)
+  const declinedPath = declinedDir(root)
+  const declined = existsSync(declinedPath)
+    ? await listTaskStems(declinedPath)
+    : []
   const parked = await checkParked(rows, root, trunk)
 
   const findings = [
@@ -1175,6 +1196,7 @@ export async function validateBoard(
     rows: rows.length,
     backlog: backlog.length,
     tasks: stems.length,
+    declined: declined.length,
     findings,
     untested: parked.untested,
     claims: checkFolderClaims(rows, root),