@erclx/canon 4.68.0 → 4.70.0

package/src/commands/tasks.ts

@@ -1,11 +1,15 @@
 import { relative } from 'node:path'
 import type { Command } from 'commander'
+import { execa } from 'execa'
+import { gitEnv } from '@/git-env'
 import { type AnswersOutcome, planAnswers } from '@/tasks/answers'
 import { type BranchOutcome, planBranch } from '@/tasks/branch'
 import {
   type ArchiveOutcome,
   archiveTask,
   type CitationOutcome,
+  type DeclineOutcome,
+  declineTask,
   type PlanCitations,
   planCitations,
 } from '@/tasks/archive'
@@ -44,12 +48,22 @@ import { mainWorktreeRoot } from '@/worktree'
 /** Returned when the board carries a finding, which is the gating result. */
 const EXIT_FINDINGS = 2
 
+/** Matches `trunk.ts`'s bound on a git subprocess this verb also shells out to. */
+const GIT_TIMEOUT_MS = 10_000
+
 interface ArchiveCommandOptions {
   readonly json?: boolean
   readonly pullRequest?: string
   readonly root?: string
 }
 
+interface DeclineCommandOptions {
+  readonly by?: string
+  readonly json?: boolean
+  readonly reason?: string
+  readonly root?: string
+}
+
 interface ValidateCommandOptions {
   readonly json?: boolean
   readonly root?: string
@@ -134,6 +148,39 @@ export function register(program: Command): void {
       process.exitCode = await runArchive(task, opts)
     })
 
+  tasks
+    .command('decline')
+    .description(
+      'Move a task decided against into .canon/tasks/declined/, recording why',
+    )
+    .argument('<task>', 'Task filename stem, as in v28.1-trigger-escalation')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--reason <text>', 'Why the task was decided against')
+    .option('--by <name>', 'Who decided, defaulting to git config user.name')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Unlike archive, decline carries no outcome-state gate: a task can be',
+        'decided against at any outcome state, and the two never share a',
+        'refusal set since they answer different questions.',
+        '',
+        'Exit codes:',
+        '  0  the task was declined',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  canon tasks decline v28.1-trigger-escalation --reason "superseded by v30.2" # canon-allow-reference: illustrates the stem-selection form, not a citation of a real task',
+        '  canon tasks decline v28.1-trigger-escalation --reason "no longer needed" --by Alex --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (task: string, opts: DeclineCommandOptions) => {
+      process.exitCode = await runDecline(task, opts)
+    })
+
   tasks
     .command('validate')
     .description(
@@ -938,7 +985,7 @@ function reportValidation(
     intro('canon tasks validate')
     logStep('Board')
     logInfo(
-      `${outcome.rows} row(s) across the readiness groups, ${outcome.backlog} backlog line(s), ${outcome.tasks} task file(s)`,
+      `${outcome.rows} row(s) across the readiness groups, ${outcome.backlog} backlog line(s), ${outcome.tasks} task file(s), ${outcome.declined} declined`,
     )
 
     logStep(outcome.findings.length === 0 ? 'Clean' : 'Findings')
@@ -994,6 +1041,7 @@ function reportValidation(
         rows: outcome.rows,
         backlog: outcome.backlog,
         tasks: outcome.tasks,
+        declined: outcome.declined,
         findings: outcome.findings,
         untested: outcome.untested,
         claims: outcome.claims,
@@ -1146,3 +1194,132 @@ function recordFor(
     cut: outcome.cut,
   }
 }
+
+/**
+ * Reads the local `git config user.name` when `--by` names nobody. `--root`
+ * scopes the read so it answers for the board's own repository rather than
+ * whatever the ambient environment points at, mirroring `trunk.ts`'s guard.
+ */
+async function resolveBy(
+  root: string,
+  by: string | undefined,
+): Promise<string | undefined> {
+  if (by) return by
+
+  const result = await execa('git', ['-C', root, 'config', 'user.name'], {
+    reject: false,
+    timeout: GIT_TIMEOUT_MS,
+    env: gitEnv(),
+    extendEnv: false,
+  })
+
+  const name = result.exitCode === 0 ? result.stdout.trim() : ''
+  return name.length > 0 ? name : undefined
+}
+
+async function runDecline(
+  task: string,
+  opts: DeclineCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  if (!opts.reason) {
+    return reportDecline(
+      {
+        ok: false,
+        reason: 'bad-input',
+        message: 'No reason named. Pass --reason <text>.',
+        detail: [],
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const by = await resolveBy(root, opts.by)
+
+  if (!by) {
+    return reportDecline(
+      {
+        ok: false,
+        reason: 'bad-input',
+        message:
+          'No decider named. Pass --by <name> or set git config user.name.',
+        detail: [],
+      },
+      emitJson,
+      root,
+    )
+  }
+
+  const outcome = await declineTask(root, task, opts.reason, by)
+
+  return reportDecline(outcome, emitJson, root)
+}
+
+function reportDecline(
+  outcome: DeclineOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify(declineRecordFor(outcome, root))}\n`)
+    return outcome.ok ? 0 : 1
+  }
+
+  intro('canon tasks decline')
+
+  if (!outcome.ok) {
+    logStep('Refused')
+    logError(outcome.message)
+    if (outcome.detail.length > 0) pipeOutput(outcome.detail.join('\n'))
+    outro()
+    return 1
+  }
+
+  logStep('Declined')
+  logRemove(relative(root, outcome.from))
+  logAdd(relative(root, outcome.to))
+  if (outcome.plan) {
+    logRemove(relative(root, outcome.plan.from))
+    logAdd(relative(root, outcome.plan.to))
+    logInfo('retargeted the Plan: line')
+  }
+  if (outcome.priorityRowRemoved) logInfo('cleared the ordering row')
+  if (outcome.backlogRowRemoved) logInfo('cleared the backlog row')
+  if (outcome.indexRegenerated) logInfo('regenerated index.md')
+  outro()
+
+  return 0
+}
+
+function declineRecordFor(
+  outcome: DeclineOutcome,
+  root: string,
+): Record<string, unknown> {
+  if (!outcome.ok) {
+    return {
+      ok: false,
+      reason: outcome.reason,
+      message: outcome.message,
+      detail: outcome.detail,
+    }
+  }
+
+  return {
+    ok: true,
+    task: outcome.stem,
+    from: relative(root, outcome.from),
+    to: relative(root, outcome.to),
+    priorityRowRemoved: outcome.priorityRowRemoved,
+    backlogRowRemoved: outcome.backlogRowRemoved,
+    indexRegenerated: outcome.indexRegenerated,
+    plan: outcome.plan
+      ? {
+          from: relative(root, outcome.plan.from),
+          to: relative(root, outcome.plan.to),
+        }
+      : null,
+  }
+}

package/src/demo/beats.ts

@@ -1,5 +1,5 @@
 /**
- * Reads the human-facing draft `canon-screencast` writes. Nothing here knows
+ * Reads the human-facing draft `draft-screencast` writes. Nothing here knows
  * about a browser: the draft is prose aimed at a person, and turning it into
  * something executable is `@/demo/compile`'s job.
  */

package/src/design/components.ts

@@ -998,6 +998,18 @@ h2 .count {
   line-height: 1.55;
 }
 
+.gloss-group {
+  margin: 1.1rem 0 0.4rem;
+  font-family: var(--teach-sans);
+  font-size: 0.8125rem;
+  font-weight: 600;
+  color: var(--color-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.02em;
+}
+
+.gloss-group:first-of-type { margin-top: 0; }
+
 .gterm b { font-weight: 700; }
 /* The markdown source separates a term from its definition with a colon,
    and the house standard bans an em dash outright, so the view mirrors

package/src/gate/measures.ts

@@ -110,6 +110,17 @@ export const GOV_EXPECTED_UNREFERENCED = ['260-shadcn', '320-tanstack-query']
  */
 export const SANDBOX_UNDECLARED_CEILING = 47
 
+/**
+ * Skills the sandbox skill census reports `asserted`, taken from `canon
+ * sandbox coverage --skills` against a clean tree. A dropped pairing lowers
+ * this directly, unlike the ceiling above, which a rename can starve without
+ * moving: fourteen arms drifted off their skill's name in one branch and the
+ * scenario-level ceiling stayed green throughout, since it counts scenarios
+ * declaring an expectation rather than skills a scenario reaches. Lowering
+ * this floor is a deliberate edit that says which skill lost its arm and why.
+ */
+export const SANDBOX_ASSERTED_FLOOR = 26
+
 /**
  * The retained counts the audit stage compares each run against. Spelled here
  * rather than derived, because this stage only ever names the file in a remedy
@@ -740,10 +751,45 @@ export const sandboxCoverage: Measure = async (ctx) => {
     }
   }
 
+  const scenarioEmission = info(
+    `${armed} of ${total} scenarios declare expectations, ${undeclared} undeclared against a ceiling of ${SANDBOX_UNDECLARED_CEILING}`,
+  )
+
+  const skillsRun = await ctx.cli(['sandbox', 'coverage', '--skills', '--json'])
+
+  if (skillsRun.exitCode !== 0) {
+    return {
+      emissions: [scenarioEmission],
+      unmeasured: `The skill census did not report (exit ${skillsRun.exitCode}). It ships in the checkout beside the scenario report, so a run that does not report is a broken command rather than an absent census.`,
+    }
+  }
+
+  const skillsRecord = parseJson(skillsRun.stdout) as
+    | { asserted?: unknown; totalSkills?: unknown }
+    | undefined
+  const asserted = skillsRecord?.asserted
+  const totalSkills = skillsRecord?.totalSkills
+
+  if (typeof asserted !== 'number' || typeof totalSkills !== 'number') {
+    return {
+      emissions: [scenarioEmission],
+      failure:
+        'The skill census carried no asserted total, so the stage measured nothing. Run bun src/cli.ts sandbox coverage --skills --json.',
+    }
+  }
+
+  if (asserted < SANDBOX_ASSERTED_FLOOR) {
+    return {
+      emissions: [scenarioEmission],
+      failure: `${asserted} of ${totalSkills} skills asserted, under the floor of ${SANDBOX_ASSERTED_FLOOR}. A rename or a moved arm likely dropped a skill's pairing; repair the arm's filename against its skill and say which skill lost its arm, or lower SANDBOX_ASSERTED_FLOOR in src/gate/measures.ts.`,
+    }
+  }
+
   return {
     emissions: [
+      scenarioEmission,
       info(
-        `${armed} of ${total} scenarios declare expectations, ${undeclared} undeclared against a ceiling of ${SANDBOX_UNDECLARED_CEILING}`,
+        `${asserted} of ${totalSkills} skills asserted, against a floor of ${SANDBOX_ASSERTED_FLOOR}`,
       ),
     ],
   }

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,6 +12,15 @@ 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.
@@ -41,6 +51,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/sandbox/expect.ts

@@ -78,6 +78,14 @@ export interface CheckInput {
    * nothing to watch, both of which produce the same empty `escapes` list.
    */
   readonly escapesWatched?: boolean
+  /**
+   * Names of sessions the client's own registry carried both before and after
+   * the run, so present rather than dispatched by it. Undefined when the
+   * caller supplied none, which is not the same as a run that had no witness:
+   * the registry carries no contract, so a client that stops writing a record
+   * per session makes this list empty regardless of who else was live.
+   */
+  readonly concurrentSessions?: readonly string[]
   readonly envelope?: RunEnvelope
 }
 
@@ -386,11 +394,19 @@ function checkWriteScope(
  * empty `escapes` list. `watched` is what tells them apart: a run that had
  * nothing to watch reports unmeasured rather than passing on a diff it never
  * had the target to take.
+ *
+ * A witnessed concurrent session never softens the verdict. `concurrentSessions`
+ * is evidence a reader can act on without a second lookup, appended to the
+ * message on an unbounded escape, never a reason to pass or skip one: a session
+ * merely alive throughout the run proves someone else was busy, not that a
+ * given file is theirs, and a real dispatch escape reads identically to an
+ * innocent sibling's write either way.
  */
 function checkEscapeScope(
   expectation: Expectation,
   escapes: readonly string[] | undefined,
   watched: boolean | undefined,
+  concurrentSessions: readonly string[] | undefined,
 ): KindOutcome {
   if (expectation.escapeScope === undefined) return { results: [], skipped: [] }
 
@@ -416,12 +432,20 @@ function checkEscapeScope(
   }
 
   const globs = expectation.escapeScope.map((glob) => new Bun.Glob(glob))
+  const witnessCount = concurrentSessions?.length ?? 0
+  const witnessSuffix =
+    witnessCount > 0
+      ? ` (${witnessCount} session${witnessCount === 1 ? '' : 's'} live throughout the run)`
+      : ''
 
   return {
     results: escapes.map((path) =>
       globs.some((glob) => glob.match(path))
         ? { ok: true, message: `declared escape: ${path}` }
-        : { ok: false, message: `unbounded escape: ${path}` },
+        : {
+            ok: false,
+            message: `unbounded escape: ${path}${witnessSuffix}`,
+          },
     ),
     skipped: [],
   }
@@ -514,6 +538,7 @@ export function checkExpectation(
     expectation,
     input.escapes,
     input.escapesWatched,
+    input.concurrentSessions,
   )
   const reply = checkReply(expectation, input.envelope)
   const envelope = checkEnvelope(expectation, input.envelope)