@erclx/canon 5.11.0 → 5.13.0

package/docs/workflow/parallel-features.md

@@ -70,8 +70,8 @@ Past that shape, it checks what a surviving row claims against what the tree hol
 
 Archiving a task carries its plan with it, in the same act. The merge is what settles a plan, and the hook below reaches the archive with nobody watching, so a second call after it would be a second failure point leaving the task archived and the plan live. A task whose plan a sibling still cites archives on its own and leaves the plan live, since moving it on the first task to close strands every other pointer at a path that has gone.
 
-Nothing chained that archive until the `post-merge` git hook landed. Every earlier step fires from `canon:auto-ship` or `canon:git-ship`, both of which finish while the pull request is still open, so a task archived there would close for work that may be abandoned. The board is gitignored, which rules out reading it from anywhere but the machine that pulled. The hook names the board's archive candidates and stays silent otherwise, including on a project with no board.
+Nothing chained that archive until the `post-merge` git hook landed. Every earlier step fires from `canon:auto-ship` or `canon:git-ship`, both of which finish while the pull request is still open, so a task archived there would close for work that may be abandoned. The board is gitignored, which rules out reading it from anywhere but the machine that pulled. The hook archives the task a merged pull request closed, through the same verb the base stack ships to every target, and does nothing on a project with no board.
 
-Candidates rather than closed tasks, because outcomes are marked on the branch. A task can read all `[x]` while its pull request is still open, so `canon:task-board` confirms the work reached `main` before it moves anything, and the hook's own output says that check is still owed. A companion `post-rewrite` hook carries the same announcement for anyone pulling with rebase, which fires that event instead of `post-merge`.
+The archive gates on a pull request number the merge carried and a closed task, because outcomes are marked on the branch and a task can read all `[x]` while its pull request is still open, so `canon:task-board` still confirms the work reached `main` when a person archives by hand. A companion `post-rewrite` hook carries the same steps for anyone pulling with rebase, which fires that event instead of `post-merge`.
 
-It announces and moves nothing, so `canon:task-board` stays the only writer. A shell-side archive would change a gitignored board with no diff to review and no session watching, and `index.md` regenerates from a session hook that a shell `mv` never fires. Both hooks ship with the `base` tooling stack, so a target project running this workflow gets the same trigger.
+The hook archives through `canon tasks archive`, which carries the refusals above, so a task whose pull request has not merged stays where it is. Both hooks ship with the `base` tooling stack, so a target project running this workflow gets the same trigger, and `CANON_SKIP_RECLAIM`, `CANON_SKIP_UPGRADE`, and `CANON_SKIP_PLUGIN_UPDATE` turn off the three steps that act on the machine.

package/docs/workflow/skill-map.md

@@ -45,7 +45,9 @@ This page is the corpus the coverage claim is measured against: every name `cano
 | `canon:project-commands`     | When the project's own command needs running                                                               |
 | `canon:test-first`           | Before implementing a planned change, to run its test red, green, then refactor                            |
 | `canon:test-craft`           | When writing or changing any test, to pick its layer and filter what it asserts                            |
+| `canon:build-in-slices`      | While building a plan, to commit each tested slice and note out-of-scope defects rather than fix them      |
 | `canon:api-design`           | When changing what a caller sees, being an export, a flag, an output shape, or a retried write             |
+| `canon:code-craft`           | Before writing a function, class, or module, to pick the shape the next change needs                       |
 | `canon:review-craft`         | When reviewing a change, for what to look for and how much evidence a finding needs                        |
 | `canon:systematic-debugging` | When a test fails or a bug surfaces, to force root cause first                                             |
 | `canon:design-taste`         | When drafting or judging an interface, or when output reads generic, to settle which decision comes first  |

package/governance/rules/code/000-code.md

@@ -1,5 +1,5 @@
 ---
-description: Code placement, dependency, error, and naming choices a model does not make by default
+description: Code placement, shape, dependency, error, and naming choices a model does not make by default
 ---
 
 # Code standards
@@ -10,6 +10,10 @@ description: Code placement, dependency, error, and naming choices a model does
 - Prioritize native platform capabilities over third-party libraries.
 - Ensure data and configuration reside in designated Single Source of Truth locations.
 
+## Shape
+
+- Load the `canon:code-craft` skill before deciding the shape of a new function, class, or module, and report it rather than proceeding silently when it does not resolve.
+
 ## Errors
 
 - Return structured error types for recoverable failures.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.11.0",
+  "version": "5.13.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -36,9 +36,8 @@
     "prepare": "husky",
     "check": "bun src/cli.ts gate run",
     "check:ci": "bun src/cli.ts gate run --all --no-write",
-    "update": "./scripts/core/update.sh",
-    "clean": "./scripts/core/clean.sh",
-    "snapshot": "./scripts/core/snapshot.sh",
+    "update": "bun update --interactive && bun run check",
+    "clean": "rm -rf node_modules && bun pm cache rm && bun install",
     "bootstrap": "./scripts/core/bootstrap.sh",
     "canon:sandbox": "canon sandbox",
     "canon:sandbox:reset": "canon sandbox reset",

package/scripts/lib/sandbox-path.sh

@@ -7,7 +7,7 @@
 # both carry the rule sending shared session scratch to the main worktree root,
 # and nothing decides which root wins. A session picking the toolkit writes its
 # output where no manifest reads it, so the run reports success while the verdict
-# reports no writes at all. `scripts/eval/run.sh` keeps its fixture outside the
+# reports no writes at all. The retired eval runner kept its fixture outside the
 # repository for the same reason.
 #
 # Mints a short random per-run identifier the first time it is asked for, then

package/src/claude/cases/misc.ts

@@ -74,6 +74,16 @@ export const MISC_CASES: readonly SkillCase[] = [
       "I'm adding a field to the JSON this command prints and renaming one flag, anything to watch?",
     expect: 'api-design',
   },
+  {
+    prompt:
+      'The same discount rule sits in two files and I need a third variant. Should I extract it, or add a strategy class for the two cases?',
+    expect: 'code-craft',
+  },
+  {
+    prompt:
+      "I've got the plan approved and it touches the parser, the command, and the docs. How should I build it so I don't end up with one giant diff?",
+    expect: 'build-in-slices',
+  },
   {
     prompt: 'Does our github about text still match what the readme says?',
     expect: 'repo-metadata',

package/src/claude/skills-audit.ts

@@ -37,6 +37,8 @@ export const PRACTICE_SKILLS: readonly string[] = [
   join(SHIPPED_CORPUS, 'review-craft'),
   join(SHIPPED_CORPUS, 'systematic-debugging'),
   join(SHIPPED_CORPUS, 'api-design'),
+  join(SHIPPED_CORPUS, 'code-craft'),
+  join(SHIPPED_CORPUS, 'build-in-slices'),
 ]
 
 /** The closing H2s a practice skill carries, matched exactly outside fences. */

package/src/commands/pr.ts

@@ -50,6 +50,8 @@ import { KEY_CHANGES } from '@/pr/paths'
 import {
   findDeployWorkflow,
   mintPreview,
+  type PreviewHeadReason,
+  readPreviewHead,
   type PreviewRefusal,
   type PreviewRunner,
   type RunRow,
@@ -116,6 +118,7 @@ const LOCAL_REFUSALS: Record<LocalRefusal | 'gh-failed', string> = {
 
 interface PreviewOptions extends ReadOptions {
   readonly timeout?: string
+  readonly check?: boolean
 }
 
 /** How long `canon pr preview` waits on the deploy run by default, in minutes. */
@@ -124,8 +127,13 @@ const PREVIEW_TIMEOUT_MINUTES = 15
 /** How often the deploy run is re-read while waiting on it. */
 const PREVIEW_POLL_MS = 15_000
 
-const PREVIEW_REFUSALS: Record<PreviewRefusal | 'bad-timeout', string> = {
+const PREVIEW_REFUSALS: Record<
+  PreviewRefusal | 'bad-timeout' | 'check-timeout',
+  string
+> = {
   'bad-timeout': '--timeout takes a positive number of minutes.',
+  'check-timeout':
+    '--check only reads the deploy runs and waits on nothing, so it takes no --timeout.',
   'no-deploy':
     'No workflow under .github/workflows/ runs pages deploy and carries a workflow_dispatch trigger, so there is nothing to dispatch.',
   // biome-ignore lint/suspicious/noTemplateCurlyInString: a workflow expression, not a template
@@ -141,6 +149,17 @@ const PREVIEW_REFUSALS: Record<PreviewRefusal | 'bad-timeout', string> = {
     'The deploy run did not finish inside the bound. The preview may still land. Re-run with a longer --timeout or read the run.',
 }
 
+/** What a reader does about each way `canon pr preview --check` answers. */
+const PREVIEW_HEAD_NOTES: Record<PreviewHeadReason, string> = {
+  fresh: 'The newest successful deploy built the branch tip.',
+  stale:
+    'The newest successful deploy built an earlier head than the branch tip. Mint again with canon pr preview before driving the preview.',
+  building:
+    'A deploy of the branch tip is still running. Wait for it rather than minting again.',
+  'no-build':
+    'No successful deploy exists for this branch. Mint one with canon pr preview.',
+}
+
 /** Why a head-sensitive read produced no answer about a commit. */
 type PullRefusal =
   | 'gh-missing'
@@ -466,17 +485,17 @@ export function register(program: Command): void {
         '--checklist closes the body with a visual checklist, below the',
         'comparison it annotates. A checklist the marked comment already',
         'carries is read back and carried forward the same way the preview',
-        'address is, which keeps a re-render from wiping ticked boxes. It does',
-        'not decide no-evidence: a branch with a checklist and no evidence',
-        'image still reports no-evidence, and the caller posts the checklist',
-        'on its own.',
+        'address is, which keeps a re-render from wiping ticked boxes. It',
+        'turns no-evidence into ok: a branch with a checklist and no evidence',
+        'image renders a marked body holding the checklist, so a later call',
+        'finds and edits that comment.',
         '',
         '--local adds a **Local preview:** line under the hosted preview line,',
         'or opens the body with it when there is none, and is carried forward',
         'the same way. It does not by itself turn no-evidence into ok, so a',
         'branch with a server running and nothing to show posts no link-only',
-        'comment. Together with --checklist it does, so the checklist and the',
-        'link land in one comment.',
+        'comment. Together with --checklist the link and the checklist land in',
+        'one comment.',
         '',
         'Both reasons carry what the marked comment already posted, each field',
         'present only when that comment holds it:',
@@ -484,9 +503,10 @@ export function register(program: Command): void {
         '  local      the **Local preview:** address under it',
         '  checklist  the checklist between its delimiters, ticks included',
         'These come from the comment already posted, never from the flags this',
-        'call passed. A checklist posted on its own carries no marker, so the',
-        'record reports none of the three for it. An unread thread refuses as',
-        'gh-failed on both reasons rather than reporting the fields absent.',
+        'call passed. A checklist the caller posted raw after a refused render',
+        'carries no marker, so the record reports none of the three for it. An',
+        'unread thread refuses as gh-failed on both reasons rather than',
+        'reporting the fields absent.',
         '',
         '--check reads the same changed set and thread, renders no body, and',
         'reports what the ship chain still owes the pull request:',
@@ -527,8 +547,11 @@ export function register(program: Command): void {
     .option('--json', 'Add a machine-readable record on stdout')
     .option(
       '--timeout <minutes>',
-      'How long to wait on the deploy run',
-      String(PREVIEW_TIMEOUT_MINUTES),
+      `How long to wait on the deploy run (default ${PREVIEW_TIMEOUT_MINUTES})`,
+    )
+    .option(
+      '--check',
+      'Read whether the newest successful deploy built the branch tip, dispatching nothing',
     )
     .addHelpText(
       'after',
@@ -553,13 +576,22 @@ export function register(program: Command): void {
         '  run-failed  the deploy run finished without succeeding',
         '  timeout     the run did not finish inside --timeout minutes',
         '',
+        'With --check nothing is dispatched or waited on. The newest successful',
+        'workflow_dispatch run is compared with the branch tip read from the remote.',
+        'Read `reason` on the JSON record, with `built`, `tip`, and `runId`:',
+        '  fresh       the newest successful deploy built the tip',
+        '  stale       the newest successful deploy built an earlier head',
+        '  building    a deploy of the tip is still running, so wait',
+        '  no-build    no deploy of this branch has succeeded',
+        '',
         'Exit codes:',
-        '  0  a preview was published',
-        '  1  refused, with the reason on stderr or in the JSON record',
+        '  0  a preview was published, or --check read fresh',
+        '  1  refused, or --check read anything but fresh',
         '',
         'Examples:',
         '  canon pr preview --json',
         '  canon pr preview 1341 --json --timeout 20',
+        '  canon pr preview 1341 --check --json',
         '',
       ].join('\n'),
     )
@@ -1605,14 +1637,15 @@ async function runEvidence(
     return refuseWith('no-base', EVIDENCE_REFUSALS['no-base'], emitJson, root)
   }
 
-  // A local address rides on a checklist or a hosted preview and never opens
-  // a comment alone, so a docs-only branch with a server up posts nothing.
-  const hasChecklistAndLocal =
-    suppliedChecklist !== undefined && opts.local !== undefined
+  // A checklist opens a comment on its own, so it always lands in the marked
+  // comment a later call edits. A local address rides on a checklist or a
+  // hosted preview and never opens one alone, so a docs-only branch with a
+  // server up posts nothing.
+  const hasChecklist = suppliedChecklist !== undefined
   if (
     grouped.kind === 'refused' &&
     opts.preview === undefined &&
-    !hasChecklistAndLocal
+    !hasChecklist
   ) {
     logStep('Skipped')
     logInfo(
@@ -1771,7 +1804,7 @@ function ghPreviewRunner(root: string): PreviewRunner {
         '--limit',
         '20',
         '--json',
-        'databaseId,status,conclusion',
+        'databaseId,status,conclusion,headSha,createdAt',
       ])
       if (out === null) return undefined
       try {
@@ -1787,7 +1820,7 @@ function ghPreviewRunner(root: string): PreviewRunner {
           'view',
           String(id),
           '--json',
-          'databaseId,status,conclusion',
+          'databaseId,status,conclusion,headSha,createdAt',
         ]),
       )
     },
@@ -1808,6 +1841,15 @@ async function runPreview(
 
   intro('canon pr preview')
 
+  if (opts.check === true && opts.timeout !== undefined) {
+    return refuseWith(
+      'check-timeout',
+      PREVIEW_REFUSALS['check-timeout'],
+      emitJson,
+      root,
+    )
+  }
+
   const minutes = Number(opts.timeout ?? PREVIEW_TIMEOUT_MINUTES)
   if (!Number.isFinite(minutes) || minutes <= 0) {
     return refuseWith(
@@ -1836,6 +1878,10 @@ async function runPreview(
   }
   const { identity } = read
 
+  if (opts.check === true) {
+    return runPreviewCheck(root, emitJson, pick.path, identity)
+  }
+
   logStep('Deploy')
   logInfo(`${pick.path} on ${identity.branch}`)
 
@@ -1885,6 +1931,62 @@ async function runPreview(
   return 0
 }
 
+/**
+ * Reads the built head against the tip. The tip comes from the remote rather
+ * than `headRefOid`, which lags a push, so a build of the last head reads stale
+ * the moment a newer commit lands.
+ */
+async function runPreviewCheck(
+  root: string,
+  emitJson: boolean,
+  workflow: string,
+  identity: { readonly branch: string; readonly number?: number },
+): Promise<number> {
+  const resolved = await resolveTip(identity.branch, refReader(root))
+  if (resolved.kind === 'refused') {
+    return refuseWith(
+      resolved.reason,
+      PULL_REFUSALS[resolved.reason],
+      emitJson,
+      root,
+    )
+  }
+
+  const reading = await readPreviewHead(ghPreviewRunner(root), {
+    workflow,
+    branch: identity.branch,
+    tip: resolved.tip,
+  })
+  if (reading.reason === 'gh-failed') {
+    return refuseWith(
+      'gh-failed',
+      PREVIEW_REFUSALS['gh-failed'],
+      emitJson,
+      root,
+    )
+  }
+
+  logStep('Preview head')
+  logInfo(PREVIEW_HEAD_NOTES[reading.reason])
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        ...(identity.number !== undefined && { number: identity.number }),
+        reason: reading.reason,
+        message: PREVIEW_HEAD_NOTES[reading.reason],
+        workflow,
+        tip: reading.tip,
+        ...(reading.built !== undefined && { built: reading.built }),
+        ...(reading.runId !== undefined && { runId: reading.runId }),
+      })}\n`,
+    )
+  }
+  return reading.reason === 'fresh' ? 0 : 1
+}
+
 async function readText(path: string): Promise<string | undefined> {
   return readFile(path, 'utf8').catch(() => undefined)
 }

package/src/commands/tooling.ts

@@ -1,6 +1,5 @@
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
-import { execScript } from '@/exec'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import {
   injectConfigs,
@@ -21,6 +20,7 @@ import { readReference, resolveReference } from '@/tooling/read'
 import { scan, type ScanResult } from '@/tooling/scan'
 import { recordedStacks, recordToolingChain } from '@/tooling/stamp'
 import { subfolderPath } from '@/tooling/subfolder'
+import { verifyStack } from '@/tooling/verify-stack'
 import {
   intro,
   isNonInteractive,
@@ -34,8 +34,6 @@ import {
   select,
 } from '@/ui'
 
-const PASS_THROUGH_VERBS = ['verify'] as const
-
 interface SyncOptions {
   readonly skip?: string
   readonly check?: boolean
@@ -60,6 +58,10 @@ interface PruneOptions {
   readonly nested?: boolean
 }
 
+interface VerifyOptions {
+  readonly keep?: boolean
+}
+
 interface ListOptions {
   readonly json?: boolean
 }
@@ -207,18 +209,39 @@ export function register(program: Command): void {
       process.exitCode = printReference(stack)
     })
 
-  for (const verb of PASS_THROUGH_VERBS) {
-    tooling
-      .command(verb)
-      .description(`Run the tooling ${verb} command`)
-      .allowUnknownOption()
-      .allowExcessArguments(true)
-      .passThroughOptions()
-      .helpOption(false)
-      .action(async (_opts: unknown, cmd: Command) => {
-        await execScript(`tooling/${verb}.sh`, cmd.args)
+  tooling
+    .command('verify')
+    .description('Scaffold a stack fresh, sync it, and run its checks')
+    .argument('<stack>', 'Tooling stack name (e.g. vite-react, astro)')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--keep', 'Keep the tmp dir after a clean run for inspection')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Scaffolds <stack> into .canon/tmp/runs/verify-<stack>/, runs the',
+        "manifest's [verify] prepare, syncs the chain from this checkout, then",
+        'runs lint:fix, check, test:e2e, and screenshot where the scaffold',
+        'declares them. A scaffold with no package.json after Sync fails.',
+        '',
+        'Exit codes:',
+        '  0  every phase passed',
+        '  1  a phase failed, or the stack cannot be verified',
+        '',
+        'Examples:',
+        '  canon tooling verify vite-react',
+        '  canon tooling verify astro --keep',
+        '',
+      ].join('\n'),
+    )
+    .action(async (stack: string, opts: VerifyOptions) => {
+      const outcome = await verifyStack({
+        root: PROJECT_ROOT,
+        stack,
+        keep: opts.keep === true,
       })
-  }
+      process.exitCode = outcome.exitCode
+    })
 }
 
 /**
@@ -227,8 +250,8 @@ export function register(program: Command): void {
  * quote emitted output a consuming skill could not parse.
  *
  * The frame opens after the `--json` return. The bash emitted a closing `└`
- * from its EXIT trap with no `┌` above it, because the hand-rolled
- * pass-through loop below opens no frame before it runs the script.
+ * from its EXIT trap with no `┌` above it, because the pass-through loop that
+ * ran it opened no frame first.
  */
 function runList(opts: ListOptions): number {
   // The warning is a frame-interior line, so it goes out after `intro` on the

package/src/gate/stages.ts

@@ -163,7 +163,11 @@ export const STAGES: readonly Stage[] = [
     id: 'indexes',
     label: 'Indexes',
     checks: [
-      script('regen-indexes.sh', 'Index regen failed'),
+      {
+        kind: 'cli',
+        argv: ['indexes', 'regen'],
+        failure: 'Index regen failed',
+      },
       {
         kind: 'drift',
         pathspec: '*index.md',
@@ -177,7 +181,11 @@ export const STAGES: readonly Stage[] = [
     id: 'consumed-copies',
     label: 'Consumed copies',
     checks: [
-      script('regen-claude-copies.sh', 'Consumed-copy regen failed'),
+      {
+        kind: 'cli',
+        argv: ['gov', 'regen'],
+        failure: 'Consumed-copy regen failed',
+      },
       {
         kind: 'drift',
         pathspec: '.claude/rules',

package/src/pr/preview.ts

@@ -95,6 +95,8 @@ export interface RunRow {
   readonly databaseId: number
   readonly status: string
   readonly conclusion: string
+  readonly headSha: string
+  readonly createdAt: string
 }
 
 /** The `gh` calls a preview makes, injected so the wait can be driven without a network. */
@@ -176,3 +178,67 @@ export async function mintPreview(
 
   return { kind: 'minted', runId, url }
 }
+
+export type PreviewHeadReason = 'fresh' | 'stale' | 'building' | 'no-build'
+
+export type PreviewHeadReading =
+  | {
+      readonly reason: PreviewHeadReason
+      readonly tip: string
+      readonly built?: string
+      readonly runId?: number
+    }
+  | { readonly reason: 'gh-failed' }
+
+/**
+ * Compares the head the newest successful dispatch built with the branch tip.
+ *
+ * The run listing is the only record of the built head, since the alias serves
+ * the newest successful deployment per branch and names no sha. Runs are
+ * ordered by creation rather than list position, so the verdict follows the
+ * most recent deploy. A run still going at the tip reads `building` rather
+ * than `stale`, so a mint already under way is not reported as a failure.
+ */
+export async function readPreviewHead(
+  runner: PreviewRunner,
+  target: {
+    readonly workflow: string
+    readonly branch: string
+    readonly tip: string
+  },
+): Promise<PreviewHeadReading> {
+  const rows = await runner.listRuns(target.workflow, target.branch)
+  if (rows === undefined) return { reason: 'gh-failed' }
+
+  const { tip } = target
+  const newest = [...rows].sort((a, b) =>
+    b.createdAt.localeCompare(a.createdAt),
+  )
+  const built = newest.find(
+    (row) => row.status === 'completed' && row.conclusion === 'success',
+  )
+
+  if (built?.headSha === tip) {
+    return {
+      reason: 'fresh',
+      built: built.headSha,
+      tip,
+      runId: built.databaseId,
+    }
+  }
+
+  const pending = newest.find(
+    (row) => row.status !== 'completed' && row.headSha === tip,
+  )
+  if (pending !== undefined) {
+    return {
+      reason: 'building',
+      tip,
+      runId: pending.databaseId,
+      ...(built !== undefined && { built: built.headSha }),
+    }
+  }
+
+  if (built === undefined) return { reason: 'no-build', tip }
+  return { reason: 'stale', built: built.headSha, tip, runId: built.databaseId }
+}