@erclx/canon 5.12.0 → 5.13.0

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

@@ -21,6 +21,7 @@ rather than inside it, so the two passes finish on their own clocks.
 - No address resolves under Step 3: stop and post nothing, `❌ No address to drive. PR #<number> carries no preview and no local preview, and the launch named none.`
 - The wrapper refuses to open the browser because its revision is absent: stop and post nothing, passing its install command to whoever launched the pass. Never install mid-pass.
 - The newest UI verdict is `## UI review closed` at the current head: stop, `The UI review already covers <short-sha>.` An open verdict at the head stops the same way only when nothing has arrived since it: drive again when a `## Review response` or `## Post-review findings` comment is newer than the verdict, or the launch names an address.
+- The hosted preview was not built from the head: stop and post nothing, naming `built`, `tip`, and `canon pr preview <number> --json` for the dispatcher. A verdict posted against an older build carries a marker naming a head nobody drove.
 - Post and stop. Never merge, never tick a box on the evidence comment, and never lift the draft mark.
 
 ## Step 1: resolve the pull request
@@ -55,6 +56,16 @@ Take the first rung that answers, testing each with `curl -s -o /dev/null -w '%{
 2. The `local` address off the record.
 3. An address the launch names.
 
+When the hosted rung answers, check that it was built from the head before driving it:
+
+```bash
+canon pr preview <number> --check --json
+```
+
+Branch on the record's `reason`. Only `fresh` continues. Any other stops with nothing posted, naming `built`, `tip`, and the next act: `stale` and `no-build` ask the dispatcher to run `canon pr preview <number> --json`, and `building` asks it to wait, since a mint is already running for the tip. This pass never mints. A `canon` that rejects `--check` predates the verb. Report that this pass needs a `canon` whose `pr preview` takes `--check`, naming the installed `canon --version`, and stop rather than reading the missing flag as `fresh`, the way Step 2 does for its own older binaries. A `reason` of `no-deploy`, `unfenced`, or `no-alias` means the project has no fenced deploy to read, so the hosted build cannot be verified. Stop on the hosted address then too, and say so.
+
+The check covers the hosted address only. The local rung and an address the launch names have no deploy run to read, so say in the comment that they were driven unverified rather than implying the same coverage.
+
 An address that exists and does not answer is a different outcome from no address at all. When every rung that exists fails to answer, skip the drive, record each box as not driven with the addresses tried and what each returned, and go to Step 7. A local address on another machine is the usual cause, and it says nothing about the change.
 
 ## Step 4: open the browser

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

@@ -52,5 +52,6 @@ The draft mark fails from both ends. On 2026-08-31 four sessions re-drafted a pu
 
 - Entering the worktree, which `session-worktree` owns
 - The chain from implement through pull request, which `auto-ship` owns
+- How the build moves through the plan, slice by slice with a commit each, which `build-in-slices` owns
 - Answering a posted review, which `review-address` owns
 - The controlling session's half of the channel, the review poll, and the watch beside it, which `role-orchestrator` and its runbooks hold

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

@@ -20,6 +20,10 @@ from the skill that owns it and invoke none of the three from here. The ordinary
 path arrives through `auto-ship` Step 0, which means that chain is already
 running and re-invoking it would restart the build.
 
+This body holds what the session may write. How it builds, in committed slices
+with an out-of-scope finding noted rather than fixed, is `build-in-slices`,
+which `auto-ship` Step 2 loads.
+
 ## Where the session stands
 
 - Resolve `.canon/plans/`, `.canon/tasks/`, `.canon/review/`, `.canon/memory/`, and `.canon/ready/` at the main worktree root, never against the linked worktree this session builds in. Those folders are gitignored, so `git worktree add` never creates them and the copy beside the build is absent rather than empty.

package/claude/skills/test-first/REQUIREMENT.md

@@ -14,6 +14,7 @@ Without this skill, a session implementing a planned change writes the test afte
 - Write or extend the test before the implementation it covers, for any behavior whose shape is already known
 - Run the test before implementing and confirm it fails for the missing behavior, not for an unrelated mistake in the test itself
 - Implement the minimum the current test demands, and start a new test before extending past it
+- Load `canon:code-craft` before writing the implementation when its shape is still open and the session has not loaded the skill, so the shape of the code is settled before the body rather than during refactor
 - Re-run the test after implementing and confirm the pass is the one the test was written to prove
 - Refactor the implementation and the test once the suite is green, re-running it after each change, since the smallest change that passes leaves duplication and shortcuts the loop exists to remove before they reach history
 
@@ -33,4 +34,6 @@ Without this skill, a session implementing a planned change writes the test afte
 - Choosing the layer a test belongs at and judging whether it is a good test: `canon:test-craft`, loaded at step 1 rather than restated here
 - Finding the cause of an unexplained failure: `canon:systematic-debugging`
 - Confirming visual output after a change lands: `567-planning.md` states the order and `ui-checklist` writes the list to confirm against
+- Shaping the function, class, or module the implementation writes: `canon:code-craft`, loaded at step 4 rather than restated here
+- Committing the behavior as a slice and ordering the slices of a larger build: `canon:build-in-slices`
 - The mechanical audit of whether an implementation reached history ahead of its test: `canon gov test-order`, invoked from `auto-ship`

package/claude/skills/test-first/SKILL.md

@@ -10,7 +10,7 @@ description: Write the failing test for a behavior before writing the code that
 1. Load `canon:test-craft` and pick the layer the test belongs at before writing it. Then find or write the test at that layer before touching the code it covers. Follow the pairing convention the project already uses, which is commonly a test sitting beside its subject under one name, so that `foo.ts` takes `foo.test.ts` beside it. Report it rather than proceeding silently when `canon:test-craft` does not resolve, and write the test at the smallest layer that can observe the behavior.
 2. Write the test against the behavior as it should exist once the change lands, naming the case for what it proves rather than for the function it calls.
 3. Run only that test and read the failure. Confirm it fails because the behavior is missing, not because of a typo, a missing import, or a signature the test itself got wrong. A test failing for the wrong reason still reads green the moment any code exists to satisfy that wrong reason, so treat any other failure as a defect in the test and fix the test before moving on.
-4. Implement the smallest change that turns the failure into a pass. Do not add behavior the test does not ask for. A second behavior wants its own test written first, not a shortcut folded into the change already open.
+4. Load `canon:code-craft` and settle the shape of the code before writing it, unless the shape is already fixed or this session already loaded the skill. Report it rather than proceeding silently when `canon:code-craft` does not resolve, and write the plainest code the test asks for. Then implement the smallest change that turns the failure into a pass. Do not add behavior the test does not ask for. A second behavior wants its own test written first, not a shortcut folded into the change already open.
 5. Run the test again and confirm it passes for the reason it was written for, not by accident. Then run the surrounding suite so a change made to satisfy this test has not broken another.
 6. Refactor with the suite green. Remove the duplication and the shortcuts step 4 left, in the implementation and in the test, without changing what either does. Run the suite after each change, and undo a change that turns anything red rather than fixing forward.
 
@@ -23,4 +23,5 @@ description: Write the failing test for a behavior before writing the code that
 
 - Which layer a test belongs at and what makes it a good one. `canon:test-craft` owns that judgment, and step 1 loads it.
 - A failure with no known cause. Route through `canon:systematic-debugging` first, whose own fix phase already writes the reproducing test as part of finding the cause. This skill starts once the shape of the fix or the feature is already decided.
+- Committing the green, refactored behavior as one slice of a larger build. `canon:build-in-slices` owns the commit and the order slices land in.
 - Confirming a change looks right once it has landed, which is a separate concern from whether the test passed and runs after implementation rather than before it.

package/docs/agents/pr-preview.md

@@ -14,6 +14,7 @@ rather than screenshots and a checklist alone.
 ```bash
 canon pr preview --json
 canon pr preview 1341 --json --timeout 20
+canon pr preview 1341 --check --json
 ```
 
 ## Which workflow it dispatches
@@ -61,22 +62,49 @@ keeps the match independent of the local clock.
 
 `reason` on the record is what a caller branches on, not the exit code:
 
-| Reason        | What it means                                                              |
-| ------------- | -------------------------------------------------------------------------- |
-| `ok`          | The preview was published. `url` carries the address and `runId` the run.  |
-| `no-deploy`   | No dispatchable workflow runs `pages deploy`.                              |
-| `unfenced`    | The deploy passes no `--branch`, so nothing was dispatched.                |
-| `no-alias`    | The workflow prints no alias line, or the finished run's log carried none. |
-| `run-failed`  | The deploy run finished without succeeding. `runId` names it.              |
-| `timeout`     | The run did not finish inside `--timeout` minutes, 15 by default.          |
-| `bad-timeout` | `--timeout` was not a positive number.                                     |
-| `gh-missing`  | `gh` is not on the path.                                                   |
-| `gh-failed`   | `gh` could not read the pull request, or list or dispatch the workflow.    |
-| `no-branch`   | The pull request carries no head branch name.                              |
+| Reason          | What it means                                                              |
+| --------------- | -------------------------------------------------------------------------- |
+| `ok`            | The preview was published. `url` carries the address and `runId` the run.  |
+| `no-deploy`     | No dispatchable workflow runs `pages deploy`.                              |
+| `unfenced`      | The deploy passes no `--branch`, so nothing was dispatched.                |
+| `no-alias`      | The workflow prints no alias line, or the finished run's log carried none. |
+| `run-failed`    | The deploy run finished without succeeding. `runId` names it.              |
+| `timeout`       | The run did not finish inside `--timeout` minutes, 15 by default.          |
+| `bad-timeout`   | `--timeout` was not a positive number.                                     |
+| `gh-missing`    | `gh` is not on the path.                                                   |
+| `gh-failed`     | `gh` could not read the pull request, or list or dispatch the workflow.    |
+| `no-branch`     | The pull request carries no head branch name.                              |
+| `check-timeout` | `--check` was combined with `--timeout`.                                   |
 
 The exit is 0 on `ok` and 1 on every refusal. A `timeout` leaves the run
 going, so the preview may still land after the verb has given up on it.
 
+## Checking which head a preview was built from
+
+`--check` dispatches nothing and waits on nothing. It lists the branch's
+`workflow_dispatch` runs, takes the newest successful one by creation time, and
+compares the head it ran at with the branch tip read from the remote. The tip
+comes from the remote rather than the pull request object's `headRefOid`, which
+lags a push. `--check` takes no `--timeout` and refuses one as `check-timeout`.
+
+The alias serves the newest successful deployment for the branch and names no
+sha, so the run listing is the only record of the built head. The
+`workflow_dispatch` filter also drops the cleanup run a closed pull request
+fires, which concludes `success` with its deploy skipped. A project that deploys
+on `push` to a feature branch would need that filter widened.
+
+| Reason     | What it means                                                         |
+| ---------- | --------------------------------------------------------------------- |
+| `fresh`    | The newest successful deploy built the tip. Exit 0.                   |
+| `stale`    | It built an earlier head. `built` and `tip` name both. Mint again.    |
+| `building` | A deploy of the tip is still running. Wait rather than minting again. |
+| `no-build` | No deploy of the branch has succeeded.                                |
+
+The record also carries `runId` for the deploy it read. The check covers the
+hosted address only, so a local address has no run to read and stays unverified.
+`review-ui` runs it before driving a hosted preview and posts nothing on any
+reason but `fresh`.
+
 ## How the address reaches the pull request
 
 `canon pr evidence --preview <url>` puts `**Preview:** <url>` on the first line

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.12.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": {

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'
@@ -528,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',
@@ -554,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'),
     )
@@ -1773,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 {
@@ -1789,7 +1820,7 @@ function ghPreviewRunner(root: string): PreviewRunner {
           'view',
           String(id),
           '--json',
-          'databaseId,status,conclusion',
+          'databaseId,status,conclusion,headSha,createdAt',
         ]),
       )
     },
@@ -1810,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(
@@ -1838,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}`)
 
@@ -1887,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/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 }
+}

package/src/tooling/manifest.ts

@@ -30,6 +30,14 @@ export interface Manifest {
    * gitignore entries.
    */
   readonly onlyConfigs?: readonly string[]
+  /**
+   * The command that creates a fresh project for this stack, from `[stack]
+   * scaffold`, with `{{name}}` standing for the project folder. Unset on a
+   * layer stack, which scaffolds nothing of its own.
+   */
+  readonly scaffold?: string
+  /** Post-scaffold setup `canon tooling verify` runs ahead of Sync. */
+  readonly prepare?: string
 }
 
 export interface ChainOptions {
@@ -134,6 +142,8 @@ export function loadManifest(
     typeof stackTable.extends === 'string' ? stackTable.extends : ''
   const scriptsTable = asTable(parsed.scripts)
   const perRoot = readStrings(asTable(parsed.sync).per_root)
+  const scaffold = readString(stackTable.scaffold)
+  const prepare = readString(asTable(parsed.verify).prepare)
   const dir = join(toolingDir(root), stack)
 
   return {
@@ -147,6 +157,8 @@ export function loadManifest(
     gitignore: readGitignoreSections(asTable(parsed.gitignore)),
     devPackages: readDevPackages(parsed.dependencies),
     ...(perRoot.length > 0 ? { perRoot } : {}),
+    ...(scaffold !== undefined ? { scaffold } : {}),
+    ...(prepare !== undefined ? { prepare } : {}),
   }
 }
 
@@ -231,6 +243,10 @@ function readDevPackages(dependencies: unknown): string[] {
   return readStrings(asTable(asTable(dependencies).dev).packages)
 }
 
+function readString(value: unknown): string | undefined {
+  return typeof value === 'string' && value !== '' ? value : undefined
+}
+
 function readStrings(value: unknown): string[] {
   if (!Array.isArray(value)) return []
   return value.filter(