@erclx/canon 5.11.0 → 5.13.0

package/src/tasks/validate.ts

@@ -6,7 +6,6 @@ import {
   declinedDir,
   isReservedStem,
   readOutcomes,
-  readPlanTarget,
   readPlanTargets,
   readPullRequest,
   resolveLivePlan,
@@ -731,11 +730,8 @@ async function planDisagreement(
   if (!existsSync(file)) return undefined
 
   const text = await readFile(file, 'utf8')
-  const target = readPlanTarget(text)
-  if (!target) {
-    const several = severalPlans(text, 'Run now', subject)
-    if (several) return several
-
+  const targets = readPlanTargets(text)
+  if (targets.length === 0) {
     return {
       kind: 'plan-uncited',
       group: 'Run now',
@@ -744,15 +740,22 @@ async function planDisagreement(
     }
   }
 
+  const twice = duplicatePlans(targets, 'Run now', subject, dir, root)
+  if (twice) return twice
+
   const rowed = planPath(row.plan, dir, root)
-  const cited = planPath(target, dir, root)
-  if (rowed === cited) return undefined
+  if (targets.some((target) => planPath(target, dir, root) === rowed)) {
+    return undefined
+  }
 
   return {
     kind: 'plan-mismatched',
     group: 'Run now',
     subject,
-    message: `is rowed against ${row.plan} and cites ${target} in its own Plan: line. One task names one plan.`,
+    message:
+      targets.length === 1
+        ? `is rowed against ${row.plan} and cites ${targets[0]} in its own Plan: line. One task names one plan.`
+        : `is rowed against ${row.plan}, which is none of the links on its own Plan: line (${targets.join(', ')}).`,
   }
 }
 
@@ -794,14 +797,15 @@ async function groupClaimFinding(
   if (!existsSync(file)) return undefined
 
   const text = await readFile(file, 'utf8')
-  const target = readPlanTarget(text)
-  if (!target) {
-    const several = severalPlans(text, row.group, row.stem)
-    if (several) return several
-  }
+  const targets = readPlanTargets(text)
+  const twice = duplicatePlans(targets, row.group, row.stem, dir, root)
+  if (twice) return twice
 
-  const live = target ? resolveLivePlan(target, dir, root) : undefined
-  const hasLivePlan = live !== undefined && existsSync(live)
+  const target = targets.find((link) => {
+    const live = resolveLivePlan(link, dir, root)
+    return live !== undefined && existsSync(live)
+  })
+  const hasLivePlan = target !== undefined
 
   if (row.group === 'Needs a plan' && hasLivePlan) {
     return {
@@ -817,9 +821,12 @@ async function groupClaimFinding(
       kind: 'plan-absent',
       group: row.group,
       subject: row.stem,
-      message: target
-        ? `sits under ${row.group}, which claims a written plan, and its task cites ${target}, which is not a live plan.`
-        : `sits under ${row.group}, which claims a written plan, and its task carries no Plan: line.`,
+      message:
+        targets.length > 1
+          ? `sits under ${row.group}, which claims a written plan, and its task cites ${targets.join(', ')}, none of which is a live plan.`
+          : targets.length === 1
+            ? `sits under ${row.group}, which claims a written plan, and its task cites ${targets[0]}, which is not a live plan.`
+            : `sits under ${row.group}, which claims a written plan, and its task carries no Plan: line.`,
     }
   }
 
@@ -827,23 +834,26 @@ async function groupClaimFinding(
 }
 
 /**
- * Reports a `Plan:` line linking more than one plan. `readPlanTarget` reads
- * such a line as naming nothing, so without this a caller would report the
- * line as absent when it is there and breaks the one-plan rule instead.
+ * Reports a `Plan:` line linking one plan more than once. Links to distinct
+ * plans are the shape a sliced task carries, so only a repeat is a finding.
+ * Links compare by the file they resolve to, so `../plans/x.md` beside
+ * `.canon/plans/x.md` is one plan listed twice.
  */
-function severalPlans(
-  text: string,
+function duplicatePlans(
+  targets: readonly string[],
   group: Finding['group'],
   subject: string,
+  dir: string,
+  root: string,
 ): Finding | undefined {
-  const targets = readPlanTargets(text)
-  if (targets.length < 2) return undefined
+  const paths = targets.map((target) => planPath(target, dir, root))
+  if (new Set(paths).size === paths.length) return undefined
 
   return {
     kind: 'plan-several',
     group,
     subject,
-    message: `cites ${targets.length} plans on its Plan: line (${targets.join(', ')}). One task names one plan, so split the task or drop the extra links.`,
+    message: `lists the same plan twice on its Plan: line (${targets.join(', ')}). Drop the repeat, or link a distinct plan per slice.`,
   }
 }
 

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(

package/src/tooling/verify-stack.ts

@@ -0,0 +1,249 @@
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { execa, type Options } from 'execa'
+import { isStackExcluded, loadManifest } from '@/tooling/manifest'
+import { intro, logError, logInfo, logStep, logWarn, outro } from '@/ui'
+
+const SCREENSHOT_TIMEOUT_MS = 60_000
+const TAIL_LINES = 20
+
+export interface VerifyOptions {
+  readonly root: string
+  readonly stack: string
+  readonly keep?: boolean
+}
+
+export interface PhaseResult {
+  readonly name: string
+  readonly passed: boolean
+}
+
+export interface VerifyOutcome {
+  readonly results: readonly PhaseResult[]
+  readonly exitCode: number
+}
+
+interface Run {
+  readonly dir: string
+  readonly results: PhaseResult[]
+  isFailed: boolean
+}
+
+/**
+ * Scaffolds a stack into `.canon/tmp/runs/verify-<stack>/`, syncs its chain
+ * from the checkout at `root`, and runs the scaffold's own `lint:fix`,
+ * `check`, `test:e2e`, and `screenshot` scripts. Every line goes to stderr.
+ *
+ * A failed phase is recorded and the run carries on, so the Results block
+ * reports every phase rather than the first failure. The tmp dir is removed
+ * only on a clean run without `keep`.
+ */
+export async function verifyStack(opts: VerifyOptions): Promise<VerifyOutcome> {
+  intro(`canon tooling verify ${opts.stack}`)
+  // A signal skips the `finally` below, so the handler closes the frame on
+  // that path and leaves the tmp dir in place for inspection.
+  let isOpen = true
+  const close = (): void => {
+    if (isOpen) outro()
+    isOpen = false
+  }
+  const handleSignal = (): void => {
+    close()
+    process.exit(130)
+  }
+  process.once('SIGINT', handleSignal)
+  process.once('SIGTERM', handleSignal)
+
+  try {
+    return await run(opts)
+  } finally {
+    process.off('SIGINT', handleSignal)
+    process.off('SIGTERM', handleSignal)
+    close()
+  }
+}
+
+async function run({
+  root,
+  stack,
+  keep = false,
+}: VerifyOptions): Promise<VerifyOutcome> {
+  const refuse = (message: string): VerifyOutcome => {
+    logError(message)
+    return { results: [], exitCode: 1 }
+  }
+
+  if (isStackExcluded(stack)) {
+    return refuse(`Stack '${stack}' is excluded from tooling.`)
+  }
+  const manifest = loadManifest(root, stack)
+  if (manifest === undefined) {
+    return refuse(`No manifest at tooling/${stack}/manifest.toml`)
+  }
+  if (manifest.scaffold === undefined) {
+    return refuse(`Stack '${stack}' has no scaffold command in manifest.`)
+  }
+
+  const runsDir = join(root, '.canon/tmp/runs')
+  const name = `verify-${stack}`
+  const state: Run = { dir: join(runsDir, name), results: [], isFailed: false }
+
+  mkdirSync(runsDir, { recursive: true })
+  rmSync(state.dir, { recursive: true, force: true })
+
+  logStep(`Scaffolding ${stack}`)
+  // Manifests carry shell syntax (`&&`, `cd`, quoted globs), so the command
+  // runs under a shell rather than as a split argv.
+  const scaffold = await shell(
+    manifest.scaffold.replaceAll('{{name}}', name),
+    runsDir,
+  )
+  if (scaffold.failed) {
+    logWarn('Scaffold failed')
+    writeTail(scaffold.all)
+    state.isFailed = true
+  }
+
+  if (!existsSync(state.dir)) {
+    return refuse(`Scaffold did not produce ${state.dir}`)
+  }
+
+  await shell(
+    'git init -q && git add . && git commit -m "chore: verify scaffold" -q --no-verify --allow-empty',
+    state.dir,
+  )
+
+  const { prepare } = manifest
+  if (prepare !== undefined) {
+    await phase(state, 'Prepare', () => shell(prepare, state.dir))
+  }
+
+  const cli = join(root, 'src/cli.ts')
+  logInfo(`Sync resolves via bun ${cli}, not PATH canon`)
+  await phase(state, 'Sync', () =>
+    execa('bun', [cli, 'tooling', 'sync', stack, '.', '--write'], {
+      ...captured(state.dir),
+      env: { CI: '1', CANON_NON_INTERACTIVE: '1' },
+    }),
+  )
+
+  const packagePath = join(state.dir, 'package.json')
+  if (existsSync(packagePath)) {
+    await runScripts(state, readScriptKeys(packagePath))
+  } else {
+    logError(
+      `No package.json after Sync for ${stack}, so no phase past Sync can run.`,
+    )
+    state.isFailed = true
+  }
+
+  logStep('Results')
+  for (const result of state.results) {
+    if (result.passed) logInfo(result.name)
+    else logWarn(result.name)
+  }
+
+  if (!keep && !state.isFailed) {
+    rmSync(state.dir, { recursive: true, force: true })
+  } else {
+    logInfo(`Kept ${state.dir}`)
+  }
+
+  return { results: state.results, exitCode: state.isFailed ? 1 : 0 }
+}
+
+/**
+ * `lint:fix` runs first and reformats the scaffold, so `check` reads the
+ * reformatted tree.
+ */
+async function runScripts(state: Run, scripts: Set<string>): Promise<void> {
+  await phase(state, 'lint:fix', () => bunRun('lint:fix', state.dir))
+  await phase(state, 'check', () => bunRun('check', state.dir))
+
+  if (scripts.has('test:e2e')) {
+    await phase(state, 'test:e2e', () => bunRun('test:e2e', state.dir))
+  }
+
+  if (!scripts.has('screenshot')) return
+  const isShot = await phase(state, 'screenshot', () =>
+    bunRun('screenshot', state.dir, SCREENSHOT_TIMEOUT_MS),
+  )
+  // A killed or failed screenshot run is already a failure, and its partial
+  // output says nothing about the artifacts.
+  if (!isShot) return
+
+  const shots = countScreenshots(join(state.dir, 'screenshots'))
+  if (shots === 0) logWarn('screenshot produced no png files')
+  record(state, 'screenshot-artifacts', shots > 0)
+}
+
+type Spawned = Awaited<ReturnType<typeof execa>>
+
+async function phase(
+  state: Run,
+  name: string,
+  spawn: () => Promise<Spawned>,
+): Promise<boolean> {
+  logStep(name)
+  const result = await spawn()
+  if (!result.failed) {
+    logInfo(`${name} passed`)
+    record(state, name, true)
+    return true
+  }
+  logWarn(result.timedOut ? `${name} timed out` : `${name} failed`)
+  writeTail(result.all)
+  record(state, name, false)
+  return false
+}
+
+function record(state: Run, name: string, passed: boolean): void {
+  state.results.push({ name, passed })
+  if (!passed) state.isFailed = true
+}
+
+function captured(cwd: string): Options {
+  return { cwd, all: true, reject: false, stdin: 'ignore' }
+}
+
+function shell(command: string, cwd: string): Promise<Spawned> {
+  return execa(command, {
+    ...captured(cwd),
+    shell: 'bash',
+    env: { CI: '1' },
+  })
+}
+
+function bunRun(
+  script: string,
+  cwd: string,
+  timeout?: number,
+): Promise<Spawned> {
+  return execa('bun', ['run', script], {
+    ...captured(cwd),
+    env: { CI: '1' },
+    ...(timeout !== undefined ? { timeout } : {}),
+  })
+}
+
+function writeTail(output: unknown): void {
+  if (typeof output !== 'string' || output === '') return
+  const lines = output.replace(/\n$/, '').split('\n').slice(-TAIL_LINES)
+  process.stderr.write(`${lines.join('\n')}\n`)
+}
+
+function readScriptKeys(packagePath: string): Set<string> {
+  try {
+    const parsed = JSON.parse(readFileSync(packagePath, 'utf8')) as {
+      scripts?: Record<string, unknown>
+    }
+    return new Set(Object.keys(parsed.scripts ?? {}))
+  } catch {
+    return new Set()
+  }
+}
+
+function countScreenshots(dir: string): number {
+  if (!existsSync(dir)) return 0
+  return [...new Bun.Glob('**/*.png').scanSync({ cwd: dir, dot: true })].length
+}

package/standards/tasks.md

@@ -124,7 +124,7 @@ An intake folder answers that direction at folder scope rather than item scope.
 
 A project that archived plans before the folder nested under `.canon/plans/` holds closed tasks pointing at `../plans-archive/` or `../.tmp/plans-archive/`. Leave those pointers where they are, since each resolves against the files it names and a task retargeted without its plan moving leads nowhere.
 
-One plan per task, or one per slice on a sliced task. A plan cited by two tasks is a misfile rather than a shape to design for.
+One plan per task, or one per slice, which the board check reads as distinct plans on one line. A plan cited by two tasks is a misfile.
 
 `canon tasks plan-link <task> <plan>` writes or corrects the `Plan:` line, and `--add` appends a slice's plan, so the line is never hand-edited.
 

package/tooling/base/configs/.husky/post-merge

@@ -1,92 +1,45 @@
 #!/usr/bin/env sh
 
-# Names archive candidates after a pull merges work in.
+# Runs the post-merge steps through `canon hooks post-merge`: archive the task a
+# merged pull request closed, push the records, reclaim merged worktrees,
+# reinstall the CLI, and update the plugin cache. The verb owns the order and
+# each line it prints.
 #
-# Every step before the merge fires from a chain and the archive fires when a
-# person remembers, so shipped tasks accumulate on a board that reads as ready
-# to hand a worker. This is the only event that lands after a merge.
+# CANON_SKIP_RECLAIM=1 turns off the worktree reclaim.
+# CANON_SKIP_UPGRADE=1 turns off the CLI reinstall.
+# CANON_SKIP_PLUGIN_UPDATE=1 turns off the plugin cache update.
 #
-# Candidates rather than closed tasks, because an all-`[x]` board entry does not
-# mean the work merged. `context-fold` marks outcomes on the branch as step 1 of
-# the ship chain, so a task can read closed while its pull request is still open
-# or already abandoned. The board is gitignored and an archived task has nothing
-# to recover it, so `task-board` confirms the work is on `main` before moving
-# anything and this output says so rather than implying the check is done.
+# The reclaim reads merge state through `gh`, so a machine without it on PATH
+# reclaims nothing and says nothing. Install `gh` to turn it on.
 #
-# It announces and never moves a file. The board is gitignored, so a shell-side
-# archive leaves no diff to review with nobody watching, and `index.md` is
-# regenerated by a session-scoped hook that a `mv` from a shell never fires.
-#
-# Husky runs this as `sh -e`, so the shebang is advisory and any bare command
-# returning non-zero aborts the hook and prints a husky failure. Keep every
-# test inside an `if` condition, which errexit exempts.
+# Husky runs this as `sh -e`, and `post-rewrite` sources it on a rebase, so
+# every test sits inside an `if` or an `||` and nothing here exits non-zero.
 
 root=$(git worktree list --porcelain 2>/dev/null | grep -m 1 '^worktree ' | cut -d' ' -f2-) || root=''
 [ -n "$root" ] || exit 0
 
 # The board is shared scratch at the main worktree root, and `git worktree
-# list` puts that root first. A pull inside a linked worktree fires this same
-# hook, so trusting the working directory would read a board that is not there.
-board="$root/.canon/tasks"
-[ -d "$board" ] || exit 0
-
-closed=""
-count=0
-
-for file in "$board"/*.md; do
-  [ -f "$file" ] || continue
+# list` puts that root first. A checkout with no board runs none of the steps.
+[ -d "$root/.canon/tasks" ] || exit 0
 
-  case "$file" in
-  */index.md | */priority.md) continue ;;
-  esac
-
-  # Gate on the same condition both archive verbs gate on: at least one closed
-  # outcome and none open. A file carrying no outcomes at all falls out here,
-  # which is what keeps notes on the board from being announced as tasks.
-  if grep -q '^- \[ \]' "$file"; then
-    continue
-  fi
+if ! command -v canon >/dev/null 2>&1; then
+  exit 0
+fi
 
-  if grep -q '^- \[x\]' "$file"; then
-    closed="$closed  $(basename "$file" .md)
-"
-    count=$((count + 1))
+# A global binary older than the verb cannot run it, and the verb carries the
+# only step that would update it, so reinstall here and probe again. The probe
+# reads the verb's own usage line rather than the exit, since an older binary
+# answers an unknown command's `--help` with its root help and exits zero.
+has_verb() {
+  canon hooks post-merge --help 2>/dev/null | grep -q '^Usage: canon hooks post-merge'
+}
+
+if ! has_verb; then
+  if [ -z "$CANON_SKIP_UPGRADE" ]; then
+    CANON_NON_INTERACTIVE=1 canon upgrade >/dev/null 2>&1 || true
   fi
-done
-
-[ "$count" -gt 0 ] || exit 0
-
-printf '\n📋 %s archive candidate(s) on the board:\n%s\n' "$count" "$closed"
-printf 'Outcomes are marked on the branch, so each still needs its work confirmed\n'
-printf 'on main. Run /task-board, which checks that and sweeps the plan first.\n\n'
-
-# The gitignored record folders live on one disk and nowhere else, and a merge
-# is the event that changes them most. This runs on every merge rather than
-# only on one that closes a task, since a review report and a memory entry
-# both land on runs that archive nothing.
-#
-# Sits last so a slow or unreachable remote delays no candidate announcement,
-# and inside an `if` so a push failing offline, or a machine that never ran
-# the one-time setup, still leaves this hook exiting zero. Guarded by its own
-# `command -v canon` check, since this file carries none above it.
-if command -v canon >/dev/null 2>&1; then
-  if backup=$(canon records push --root "$root" --json 2>/dev/null); then
-    changed=$(printf '%s' "$backup" | sed -n 's/.*"changed":\([0-9][0-9]*\).*/\1/p')
-    if [ -n "$changed" ] && [ "$changed" != "0" ]; then
-      printf '\n🗄️  Backed up %s record path(s).\n\n' "$changed"
-    fi
-  else
-    reason=$(printf '%s' "$backup" | sed -n 's/.*"reason":"\([^"]*\)".*/\1/p')
+fi
 
-    # No records history on this machine, which is every checkout that never
-    # ran the one-time setup. Nothing to report.
-    if [ "$reason" != "no-repository" ]; then
-      printf '\n🗄️  Records not backed up: %s\n' "${reason:-unknown}"
-      if [ "$reason" = "unsafe-payload" ]; then
-        printf 'Run canon records push to see the blocked paths.\n\n'
-      else
-        printf 'Run canon records push when the remote is reachable.\n\n'
-      fi
-    fi
-  fi
+if has_verb; then
+  canon hooks post-merge --root "$root" || true
 fi

package/tooling/base/configs/.husky/post-rewrite

@@ -1,6 +1,6 @@
 #!/usr/bin/env sh
 
-# Runs the `post-merge` board check for anyone pulling with rebase.
+# Runs the `post-merge` steps for anyone pulling with rebase.
 #
 # `git pull` under `pull.rebase=true` runs `git rebase`, which fires this event
 # and never `post-merge`. Without this the trigger is a silent no-op on that
@@ -9,8 +9,8 @@
 # target, where the pull style is not something this repository controls.
 #
 # Only the `rebase` argument delegates. `post-rewrite` also fires on
-# `commit --amend`, which rewrites nothing on the board and would print the
-# candidate list on an ordinary amend.
+# `commit --amend`, which rewrites nothing on the board and would run the
+# archive, reclaim, and upgrade steps on an ordinary amend.
 
 [ "$1" = "rebase" ] || exit 0
 

package/tooling/base/reference.md

@@ -52,7 +52,7 @@ Seeds live in `tooling/base/seeds/`. Sync drops each once on first install and n
 - `pre-commit` runs `bunx lint-staged`.
 - `commit-msg` runs `bunx commitlint --edit "$1"`.
 - `pre-push` runs `bun run check`.
-- `post-merge` names `.canon/tasks/` archive candidates, staying silent otherwise and when the board is absent.
+- `post-merge` runs `canon hooks post-merge`: archive the task a merged pull request closed, push the records, reclaim merged worktrees, reinstall the CLI, and update the plugin. It does nothing when the board is absent. `CANON_SKIP_RECLAIM`, `CANON_SKIP_UPGRADE`, and `CANON_SKIP_PLUGIN_UPDATE` turn off the three steps that act on the machine. Read `canon docs hooks` for the contract.
 - `post-rewrite` delegates to `post-merge` on `rebase`, so a `pull.rebase=true` machine still gets the check.
 
 ## lint-staged

package/tooling/base/seeds/.cspell/tech-stack.txt

@@ -3,11 +3,13 @@ bradlc
 bunx
 commitlint
 dbaeumer
+dotenv
 dotfolders
 erclx
 errexit
 esac
 esbenp
+eslintcache
 frontmatter
 lintstagedrc
 mkhl

package/tooling/go/manifest.toml

@@ -11,3 +11,6 @@ scaffold = "mkdir {{name}} && cd {{name}} && go mod init example.com/{{name}} &&
 "test" = "go test ./..."
 "test:run" = "go test -v ./..."
 "build" = "go build ./..."
+
+[verify]
+prepare = "bun init -y && (command -v golangci-lint >/dev/null || go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest)"

package/tooling/go/reference.md

@@ -32,6 +32,7 @@ The go stack also ships `smoke_test.go` at the module root as a copy-once seed.
 - Probe `go` and `golangci-lint` first, and name the `go install` command when `golangci-lint` is missing.
 - Keep `build` out of `verify.json`, even though the stack declares the script. `go build ./...` exits 1 with `no packages to build` on a module holding only a test file, and a seeded `main.go` would assume every module is a binary rather than a library.
 - Keep `-race` out of `test:run`. The race detector needs cgo and a C toolchain, so it belongs in CI rather than in a local `bun run check`.
+- The manifest's `[verify] prepare` runs checklist steps 3 and 6 for `canon tooling verify go`: `bun init -y`, then the `golangci-lint` `go install` when the binary is not already on PATH. The scaffold writes no `package.json`, and a verify that reaches its end with none fails.
 
 ## CI
 

package/tooling/php/manifest.toml

@@ -13,3 +13,6 @@ scaffold = "mkdir {{name}} && cd {{name}} && composer init -n --name example/{{n
 
 [gitignore]
 "# PHP" = ["vendor/", ".php-cs-fixer.cache", ".phpunit.cache/", ".phpunit.result.cache"]
+
+[verify]
+prepare = "bun init -y && composer require --dev friendsofphp/php-cs-fixer phpstan/phpstan phpunit/phpunit"

package/tooling/php/reference.md

@@ -44,6 +44,7 @@ The php stack also ships `tests/SmokeTest.php` as a copy-once seed, so `bun run
 - Probe `php` and `composer` first.
 - Hold a precondition on `vendor/bin/phpunit`, so the run stops and names `composer install` when it is missing.
 - Require Typecheck (`phpstan analyse`), Lint (`php-cs-fixer check`), and Unit tests (`phpunit --testdox`). Base's runner adds the four base phases wherever the folder declares their scripts, then the markdown bans stage.
+- The manifest's `[verify] prepare` runs checklist steps 2 and 5 for `canon tooling verify php`: `bun init -y`, then the `composer require --dev` line. The scaffold writes no `package.json`, and a verify that reaches its end with none fails.
 
 ## Gitignore
 

package/tooling/python/manifest.toml

@@ -14,3 +14,6 @@ scaffold = "uv init --package {{name}}"
 
 [gitignore]
 "# Python" = [".pytest_cache/", ".mypy_cache/", ".ruff_cache/", ".coverage_cache/"]
+
+[verify]
+prepare = "bun init -y && uv add --dev ruff mypy pytest pytest-cov && uv sync"

package/tooling/python/reference.md

@@ -39,7 +39,7 @@ The manifest declares no `[dependencies.dev]`. Manifest injection currently call
 
 ## Verify command
 
-`canon tooling verify <stack>` currently runs `bun run lint:fix` and `bun run check` against any stack with a `package.json`. Since base ships a `package.json`, those run for python too. Python's `verify.json` requires the package.json `lint`/`typecheck`/`test:run` scripts that delegate to `uv run`, so the verify path works end-to-end as long as `uv` is installed in the verify environment. The end-to-end test and screenshot phases are gated on `package.json` script keys that python does not declare, so they cleanly skip.
+`canon tooling verify python` runs the manifest's `[verify] prepare` before Sync, which is checklist steps 2, 5, and 6: `bun init -y`, `uv add --dev ruff mypy pytest pytest-cov`, and `uv sync`. `uv init` writes no `package.json`, and a verify that reaches its end with none fails, so the prepare is what lets `bun run lint:fix` and `bun run check` run at all. Python's `verify.json` requires the `lint`, `typecheck`, and `test:run` scripts that delegate to `uv run`, so the run needs `uv` on the machine and a network for the installs. The end-to-end test and screenshot phases are gated on `package.json` script keys that python does not declare, so they skip.
 
 ## Anti-patterns
 

package/tooling/python/seeds/.cspell/tech-stack.txt

@@ -2,7 +2,6 @@ addopts
 appuser
 asyncio
 coveragerc
-dotenv
 fastapi
 flake8
 htmlcov