@erclx/canon 5.8.0 → 5.9.0

package/tooling/base/configs/scripts/verify.sh

@@ -1,111 +1,2 @@
 #!/bin/bash
-set -e
-set -o pipefail
-
-GREEN='\033[0;32m'
-RED='\033[0;31m'
-WHITE='\033[1;37m'
-GREY='\033[0;90m'
-NC='\033[0m'
-
-NESTED="${VERIFY_NESTED:-false}"
-
-log_info() { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1"; }
-log_error() {
-  echo -e "${GREY}│${NC} ${RED}✗${NC} $1"
-  exit 1
-}
-log_step() { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}"; }
-
-pipe_output() { while IFS= read -r line; do echo -e "${GREY}│${NC}  $line"; done; }
-
-check_dependencies() {
-  command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
-}
-
-check_markdown_bans() {
-  if ! command -v canon >/dev/null 2>&1; then
-    log_info "Skipped: no canon binary on PATH. Install with \`bun install --global @erclx/canon\`."
-    return 0
-  fi
-
-  local files=()
-  while IFS= read -r file; do
-    files+=("$file")
-  done < <(git ls-files --cached --others --exclude-standard -- '*.md' ':(exclude)CHANGELOG.md' ':(exclude)**/CHANGELOG.md')
-
-  if [ ${#files[@]} -eq 0 ]; then
-    log_info "No markdown file to check outside the exclusion set."
-    return 0
-  fi
-
-  local output code
-  if output=$(canon markdown audit "${files[@]}" 2>&1); then
-    code=0
-  else
-    code=$?
-  fi
-
-  case "$code" in
-  0)
-    log_info "No banned character"
-    ;;
-  1)
-    log_info "Skipped: canon markdown audit refused and measured nothing."
-    ;;
-  2)
-    echo "$output" | pipe_output
-    log_error "Markdown prose carries a banned character, or a relative link resolves to nothing on disk"
-    ;;
-  3)
-    echo "$output" | pipe_output
-    log_error "The markdown audit shipped an empty ban set, so the corpus was walked and nothing was looked for"
-    ;;
-  *)
-    log_error "canon markdown audit exited $code, which is neither a pass nor a finding"
-    ;;
-  esac
-}
-
-run_check() {
-  local cmd=$1
-  local err_msg=$2
-  local output
-  if ! output=$(eval "$cmd" 2>&1); then
-    echo "$output" | pipe_output
-    log_error "$err_msg"
-  fi
-  echo "$output" | pipe_output
-}
-
-main() {
-  check_dependencies
-
-  if [ "$NESTED" = false ]; then echo -e "${GREY}┌${NC}"; fi
-
-  echo -e "${GREY}├${NC} ${WHITE}Formatting${NC}"
-  run_check "bun run format" "Format failed"
-  log_info "Format applied"
-
-  log_step "Format check"
-  run_check "bun run check:format" "Format check failed"
-  log_info "Format check passed"
-
-  log_step "Spelling"
-  run_check "bun run check:spell" "Spell check failed"
-  log_info "Spell check passed"
-
-  log_step "Shell"
-  run_check "bun run check:shell" "Shell check failed"
-  log_info "Shell check passed"
-
-  log_step "Markdown bans"
-  check_markdown_bans
-
-  if [ "$NESTED" = false ]; then
-    echo -e "${GREY}└${NC}\n"
-    echo -e "${GREEN}✓ Verification passed${NC}"
-  fi
-}
-
-main "$@"
+exec bun "$(dirname "$0")/verify.ts" "$@"

package/tooling/base/configs/scripts/verify.ts

@@ -0,0 +1,378 @@
+// Runs this folder's verify phases in a fixed order. The phases a stack
+// requires come from scripts/verify.json, which each stack ships and the
+// nearest one wins. Only node: modules, since a target's own eslint and
+// tsc --noEmit read this file with no Bun types.
+import { spawnSync } from 'node:child_process'
+import { accessSync, constants, existsSync, readFileSync } from 'node:fs'
+import { delimiter, join } from 'node:path'
+
+interface Tool {
+  readonly name: string
+  readonly hint?: string
+}
+
+interface Precondition {
+  readonly path: string
+  readonly hint: string
+}
+
+interface PhaseList {
+  readonly require: readonly string[]
+  readonly tools: readonly Tool[]
+  readonly preconditions: readonly Precondition[]
+}
+
+interface Phase {
+  readonly script: string
+  readonly title: string
+  readonly failed: string
+  readonly passed: string
+}
+
+const PHASES: readonly Phase[] = [
+  {
+    script: 'typecheck',
+    title: 'Typecheck',
+    failed: 'Typecheck failed',
+    passed: 'Typecheck passed',
+  },
+  {
+    script: 'lint',
+    title: 'Lint',
+    failed: 'Lint failed',
+    passed: 'Lint passed',
+  },
+  {
+    script: 'format',
+    title: 'Formatting',
+    failed: 'Format failed',
+    passed: 'Format applied',
+  },
+  {
+    script: 'check:format',
+    title: 'Format check',
+    failed: 'Format check failed',
+    passed: 'Format check passed',
+  },
+  {
+    script: 'check:spell',
+    title: 'Spelling',
+    failed: 'Spell check failed',
+    passed: 'Spell check passed',
+  },
+  {
+    script: 'check:shell',
+    title: 'Shell',
+    failed: 'Shell check failed',
+    passed: 'Shell check passed',
+  },
+  {
+    script: 'test:run',
+    title: 'Unit tests',
+    failed: 'Unit tests failed',
+    passed: 'Unit tests passed',
+  },
+  {
+    script: 'build',
+    title: 'Build',
+    failed: 'Build failed',
+    passed: 'Build passed',
+  },
+]
+
+// A subfolder synced with --skip base declares none of these, since the
+// repository root owns them, so a list that does not require one runs it only
+// where the folder declares it.
+const BASE_PHASES = new Set([
+  'format',
+  'check:format',
+  'check:spell',
+  'check:shell',
+])
+
+const PHASE_LIST = 'scripts/verify.json'
+const CARD_EXCLUSION = 'scripts/check-card-exclusion.sh'
+
+const GREEN = '\x1b[0;32m'
+const RED = '\x1b[0;31m'
+const WHITE = '\x1b[1;37m'
+const GREY = '\x1b[0;90m'
+const NC = '\x1b[0m'
+
+const isNested = (process.env.VERIFY_NESTED || 'false') !== 'false'
+let hasStepped = false
+
+class VerifyFailure extends Error {}
+
+function print(line: string): void {
+  process.stdout.write(`${line}\n`)
+}
+
+function logInfo(message: string): void {
+  print(`${GREY}│${NC} ${GREEN}✓${NC} ${message}`)
+}
+
+function logSkip(message: string): void {
+  print(`${GREY}│ - ${message}${NC}`)
+}
+
+function fail(message: string): never {
+  print(`${GREY}│${NC} ${RED}✗${NC} ${message}`)
+  throw new VerifyFailure(message)
+}
+
+function logStep(title: string): void {
+  if (hasStepped) print(`${GREY}│${NC}`)
+  print(`${GREY}├${NC} ${WHITE}${title}${NC}`)
+  hasStepped = true
+}
+
+function pipeOutput(output: string): void {
+  for (const line of output.replace(/\n+$/, '').split('\n')) {
+    print(`${GREY}│${NC}  ${line}`)
+  }
+}
+
+function isExecutable(path: string): boolean {
+  try {
+    accessSync(path, constants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function onPath(name: string): boolean {
+  return (process.env.PATH ?? '')
+    .split(delimiter)
+    .some((dir) => dir !== '' && isExecutable(join(dir, name)))
+}
+
+// Runs through sh so stderr interleaves with stdout the way 2>&1 does.
+function capture(
+  command: string,
+  args: readonly string[] = [],
+): {
+  readonly code: number
+  readonly output: string
+} {
+  const result = spawnSync(
+    '/bin/sh',
+    ['-c', `${command} 2>&1`, 'sh', ...args],
+    {
+      encoding: 'utf8',
+      maxBuffer: 256 * 1024 * 1024,
+    },
+  )
+  return { code: result.status ?? 1, output: result.stdout ?? '' }
+}
+
+function runCheck(command: string, failed: string): void {
+  const { code, output } = capture(command)
+  pipeOutput(output)
+  if (code !== 0) fail(failed)
+}
+
+function readJson(path: string): unknown {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    return undefined
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {}
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : []
+}
+
+function readPhaseList(): PhaseList {
+  if (!existsSync(PHASE_LIST)) {
+    fail(
+      `No ${PHASE_LIST} here. Run 'canon tooling sync <stack>' so the stack ships its phase list`,
+    )
+  }
+  const parsed = readJson(PHASE_LIST)
+  if (parsed === undefined) fail(`${PHASE_LIST} is not valid JSON`)
+
+  const table = asRecord(parsed)
+  return {
+    require: asArray(table.require).filter(
+      (entry): entry is string => typeof entry === 'string',
+    ),
+    tools: asArray(table.tools).flatMap((entry) => {
+      const tool = asRecord(entry)
+      if (typeof tool.name !== 'string') return []
+      return [
+        {
+          name: tool.name,
+          hint: typeof tool.hint === 'string' ? tool.hint : undefined,
+        },
+      ]
+    }),
+    preconditions: asArray(table.preconditions).flatMap((entry) => {
+      const precondition = asRecord(entry)
+      if (typeof precondition.path !== 'string') return []
+      return [
+        {
+          path: precondition.path,
+          hint: typeof precondition.hint === 'string' ? precondition.hint : '',
+        },
+      ]
+    }),
+  }
+}
+
+function readDeclaredScripts(): Set<string> {
+  if (!existsSync('package.json')) {
+    fail("No package.json here. Run 'bun init', then sync the stack again")
+  }
+  return new Set(
+    Object.keys(asRecord(asRecord(readJson('package.json')).scripts)),
+  )
+}
+
+function checkTools(list: PhaseList): void {
+  for (const tool of list.tools) {
+    if (onPath(tool.name)) continue
+    fail(
+      tool.hint === undefined
+        ? `${tool.name} is not installed`
+        : `${tool.name} is not installed. ${tool.hint}`,
+    )
+  }
+}
+
+function checkPreconditions(list: PhaseList): void {
+  for (const precondition of list.preconditions) {
+    if (isExecutable(precondition.path)) continue
+    fail(`No ${precondition.path} here. ${precondition.hint}`.trimEnd())
+  }
+}
+
+function runPhase(
+  phase: Phase,
+  required: boolean,
+  declared: Set<string>,
+): void {
+  const isBase = BASE_PHASES.has(phase.script)
+  if (!required && !isBase) return
+
+  logStep(phase.title)
+  if (!declared.has(phase.script)) {
+    if (required) {
+      fail(
+        `${phase.script} is required by ${PHASE_LIST}, but package.json declares no such script`,
+      )
+    }
+    logSkip(
+      `Skipped: ${phase.script} is not declared here, so the repository root runs it`,
+    )
+    return
+  }
+  runCheck(`bun run ${phase.script}`, phase.failed)
+  logInfo(phase.passed)
+}
+
+function listMarkdown(): string[] {
+  const result = spawnSync(
+    'git',
+    [
+      'ls-files',
+      '--cached',
+      '--others',
+      '--exclude-standard',
+      '--',
+      '*.md',
+      ':(exclude)CHANGELOG.md',
+      ':(exclude)**/CHANGELOG.md',
+    ],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit'] },
+  )
+  return (result.stdout ?? '').split('\n').filter((line) => line !== '')
+}
+
+// canon markdown audit exits 0 on a pass, 1 on a refusal that measured
+// nothing, 2 on a finding, and 3 when it shipped an empty ban set.
+function checkMarkdownBans(): void {
+  if (!onPath('canon')) {
+    logInfo(
+      'Skipped: no canon binary on PATH. Install with `bun install --global @erclx/canon`.',
+    )
+    return
+  }
+
+  const files = listMarkdown()
+  if (files.length === 0) {
+    logInfo('No markdown file to check outside the exclusion set.')
+    return
+  }
+
+  const { code, output } = capture('canon markdown audit "$@"', files)
+  switch (code) {
+    case 0:
+      logInfo('No banned character')
+      return
+    case 1:
+      logInfo('Skipped: canon markdown audit refused and measured nothing.')
+      return
+    case 2:
+      pipeOutput(output)
+      fail(
+        'Markdown prose carries a banned character, or a relative link resolves to nothing on disk',
+      )
+      break
+    case 3:
+      pipeOutput(output)
+      fail(
+        'The markdown audit shipped an empty ban set, so the corpus was walked and nothing was looked for',
+      )
+      break
+    default:
+      fail(
+        `canon markdown audit exited ${code}, which is neither a pass nor a finding`,
+      )
+  }
+}
+
+function main(): void {
+  const declared = readDeclaredScripts()
+  const list = readPhaseList()
+  checkTools(list)
+  checkPreconditions(list)
+
+  if (!isNested) print(`${GREY}┌${NC}`)
+
+  const required = new Set(list.require)
+  for (const phase of PHASES) {
+    runPhase(phase, required.has(phase.script), declared)
+  }
+
+  logStep('Markdown bans')
+  checkMarkdownBans()
+
+  // The card exclusion check reads the build, so it runs last, and only where
+  // the stack that owns the card route shipped it.
+  if (existsSync(CARD_EXCLUSION)) {
+    logStep('Card exclusion')
+    runCheck(`bash ${CARD_EXCLUSION}`, 'Card exclusion check failed')
+    logInfo('Card exclusion passed')
+  }
+
+  if (!isNested) {
+    print(`${GREY}└${NC}\n`)
+    print(`${GREEN}✓ Verification passed${NC}`)
+  }
+}
+
+try {
+  main()
+} catch (error) {
+  if (!(error instanceof VerifyFailure)) throw error
+  process.exitCode = 1
+}

package/tooling/base/manifest.toml

@@ -6,6 +6,7 @@ scaffold = ""
 
 [sync]
 source = "configs"
+per_root = ["scripts/verify.sh", "scripts/verify.ts", "scripts/verify.json"]
 
 [dependencies.dev]
 packages = [

package/tooling/base/reference.md

@@ -16,7 +16,9 @@ Golden config files live in `tooling/base/configs/` and are copied into the targ
 - `commitlint.config.js`: ESM default export extending `@commitlint/config-conventional`. Rules are `header-max-length: 72`, `scope-case: lower-case`, `subject-full-stop: never`, `subject-case` disabled, and a local `no-claude-co-author` rule refusing a `Co-authored-by` trailer that names Claude or Anthropic.
 - `.husky/`: `pre-commit`, `commit-msg`, `pre-push`, `post-merge`, `post-rewrite`.
 - `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for Prettier, cspell, shfmt, and shellcheck.
-- `scripts/verify.sh`: the maintenance entry point behind `check`.
+- `scripts/verify.sh`: the maintenance entry point behind `check`, a wrapper that hands off to `scripts/verify.ts`.
+- `scripts/verify.ts`: the one verify runner every stack shares. It runs typecheck, lint, format, format check, spelling, shell, unit tests, build, markdown bans, then card exclusion, always in that order, and skips any phase the folder's `scripts/verify.json` leaves out. Node modules only, since a target's own lint and typecheck read it.
+- `scripts/verify.json`: the phases a stack requires, plus any tools and preconditions it probes first. The nearest stack's copy wins. A required phase whose script `package.json` lacks fails the run. A base phase the list leaves out runs only where the folder declares its script. Base requires its four phases, so a base-only target still fails on a missing one. These three files are base's `[sync] per_root` set, which a `--skip base` subfolder still receives.
 
 ## What ships as user-owned seeds
 
@@ -88,7 +90,7 @@ Sticky negative knowledge. Do not relearn.
 
 | Script                 | What it does                                                                                                                          |
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `bun run check`        | Repairs a checkout via `scripts/verify.sh`. Honors `VERIFY_NESTED=true` to suppress timeline boundaries when another script calls it. |
+| `bun run check`        | Repairs a checkout via `scripts/verify.ts`. Honors `VERIFY_NESTED=true` to suppress timeline boundaries when another script calls it. |
 | `bun run check:format` | Asserts prettier and shfmt formatting without writing                                                                                 |
 | `bun run check:spell`  | Runs cspell across every file, with context on failures                                                                               |
 | `bun run check:shell`  | Runs shellcheck at warning severity                                                                                                   |
@@ -97,4 +99,4 @@ Sticky negative knowledge. Do not relearn.
 
 `bun run check` repairs a checkout rather than gating one. It runs `format` first to auto-fix drifted code, then asserts only what the formatters could not fix. The pull request workflow calls `check:format`, `check:spell`, and `check:shell` directly, and those three are the gate.
 
-`scripts/verify.sh`'s `Markdown bans` stage is the exception: it gates rather than repairs. It runs `canon markdown audit` over every tracked markdown file except `CHANGELOG.md`, since a generated changelog carries commit subjects nobody wrote against the ban set, and exits `2` on a finding or `3` on a shipped-empty ban set, failing `bun run check` and the `pre-push` hook that calls it. A refusal to measure exits `1` and is logged as a skip rather than a failure, as does a corpus with no file left to check once `CHANGELOG.md` is set aside. The stage needs `canon` on PATH. `canon docs projects` names the install command. Without it, the stage is skipped and logged, and coverage falls back to the three checks above.
+`scripts/verify.ts`'s `Markdown bans` stage is the exception: it gates rather than repairs. It runs `canon markdown audit` over every tracked markdown file except `CHANGELOG.md`, since a generated changelog carries commit subjects nobody wrote against the ban set, and exits `2` on a finding or `3` on a shipped-empty ban set, failing `bun run check` and the `pre-push` hook that calls it. A refusal to measure exits `1` and is logged as a skip rather than a failure, as does a corpus with no file left to check once `CHANGELOG.md` is set aside. The stage needs `canon` on PATH. `canon docs projects` names the install command. Without it, the stage is skipped and logged, and coverage falls back to the three checks above.

package/tooling/go/configs/scripts/verify.json

@@ -0,0 +1,10 @@
+{
+  "require": ["typecheck", "lint", "test:run"],
+  "tools": [
+    { "name": "go" },
+    {
+      "name": "golangci-lint",
+      "hint": "Run 'go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest'"
+    }
+  ]
+}

package/tooling/go/reference.md

@@ -4,7 +4,7 @@
 
 ## Overview
 
-The go stack covers Go modules linted and formatted by `golangci-lint` v2, type-checked by `go vet`, and tested by `go test`. It ships a golden `.golangci.yml`, a Go-aware `verify.sh`, and a copy-once smoke test.
+The go stack covers Go modules linted and formatted by `golangci-lint` v2, type-checked by `go vet`, and tested by `go test`. It ships a golden `.golangci.yml`, a go phase list for base's verify runner, and a copy-once smoke test.
 
 ## Scaffold checklist
 
@@ -26,10 +26,11 @@ The go stack also ships `smoke_test.go` at the module root as a copy-once seed.
 - Enable formatters `gofmt` and `goimports`. `lint:fix` runs `golangci-lint fmt` ahead of `golangci-lint run --fix`.
 - Exclude `node_modules` from both linters and formatters. The `go.mod` `ignore` directive in the checklist covers every Go tool, but `go.mod` belongs to the project and sync cannot write it, so the config keeps `golangci-lint run` from reporting and `golangci-lint fmt` from rewriting a vendored `.go` file in a module that never added the directive.
 
-## verify.sh
+## verify.json
 
-- Run Typecheck (`go vet`), Lint (`golangci-lint run`), and Unit tests (`go test -v`), plus the four base phases wherever the folder declares their scripts, then the markdown bans stage base ships.
-- Keep `build` out of `verify.sh`. `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.
+- Require Typecheck (`go vet`), Lint (`golangci-lint run`), and Unit tests (`go test -v`). Base's runner adds the four base phases wherever the folder declares their scripts, then the markdown bans stage.
+- 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`.
 
 ## CI

package/tooling/php/configs/scripts/verify.json

@@ -0,0 +1,7 @@
+{
+  "require": ["typecheck", "lint", "test:run"],
+  "tools": [{ "name": "php" }, { "name": "composer" }],
+  "preconditions": [
+    { "path": "vendor/bin/phpunit", "hint": "Run 'composer install'" }
+  ]
+}

package/tooling/php/reference.md

@@ -4,7 +4,7 @@
 
 ## Overview
 
-The php stack covers Composer projects on PHP 8.3 or later, formatted by PHP CS Fixer, analysed by PHPStan, and tested by PHPUnit. It ships the three tools' configs, a PHP-aware `verify.sh`, and a copy-once smoke test.
+The php stack covers Composer projects on PHP 8.3 or later, formatted by PHP CS Fixer, analysed by PHPStan, and tested by PHPUnit. It ships the three tools' configs, a php phase list for base's verify runner, and a copy-once smoke test.
 
 ## Scaffold checklist
 
@@ -39,10 +39,11 @@ The php stack also ships `tests/SmokeTest.php` as a copy-once seed, so `bun run
 - Set `colors`, `failOnWarning`, and `failOnRisky`.
 - Run one `unit` suite over `tests`, with `src` as the source.
 
-## verify.sh
+## verify.json
 
-- Stop and name `composer install` when `vendor/bin/phpunit` is missing.
-- Run Typecheck (`phpstan analyse`), Lint (`php-cs-fixer check`), and Unit tests (`phpunit --testdox`), plus the four base phases wherever the folder declares their scripts, then the markdown bans stage base ships.
+- 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.
 
 ## Gitignore
 

package/tooling/python/configs/scripts/verify.json

@@ -0,0 +1,4 @@
+{
+  "require": ["typecheck", "lint", "test:run"],
+  "tools": [{ "name": "uv" }]
+}

package/tooling/python/reference.md

@@ -4,7 +4,7 @@
 
 ## Overview
 
-The python stack covers Python 3.13+ projects managed with `uv`. It ships golden sidecar configs for `ruff`, `mypy`, `pytest`, and `coverage`, plus a `.python-version` pin and a python-aware `verify.sh`. Framework adapters layer on top with their own deps and configs.
+The python stack covers Python 3.13+ projects managed with `uv`. It ships golden sidecar configs for `ruff`, `mypy`, `pytest`, and `coverage`, plus a `.python-version` pin and a python phase list for base's verify runner. Framework adapters layer on top with their own deps and configs.
 
 Configs ship as sidecar files (`ruff.toml`, `mypy.ini`, `pytest.ini`, `.coveragerc`) rather than `[tool.*]` sections in `pyproject.toml`. Sync overwrites configs on every run, so keeping them sidecar avoids stomping the user-owned `[project]` block in `pyproject.toml`.
 
@@ -27,7 +27,7 @@ The python stack also ships `tests/test_smoke.py` as a copy-once seed. `pytest`
 - `pytest.ini`: tests live under `tests/`, source under `src/`.
 - `.coveragerc`: branch coverage on `src/`, html report under `.coverage_cache/html`.
 - `.python-version`: pinned to `3.14` to match `uv init` defaults.
-- `scripts/verify.sh`: overrides base verify to add Typecheck (`mypy`), Lint (`ruff check && ruff format --check`), and Tests (`pytest -v`) phases, then the same markdown bans phase base ships.
+- `scripts/verify.json`: requires Typecheck (`mypy`), Lint (`ruff check && ruff format --check`), and Tests (`pytest -v`) on top of base's runner, and stops naming `uv` when it is not on PATH. The markdown bans phase runs as it does everywhere.
 
 ## Hybrid project shape
 
@@ -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.sh wraps 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 <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.
 
 ## Anti-patterns
 

package/tooling/web/configs/scripts/verify.json

@@ -0,0 +1,3 @@
+{
+  "require": ["typecheck", "lint", "test:run", "build"]
+}

package/tooling/web/reference.md

@@ -19,7 +19,7 @@ Golden config files live in `tooling/web/configs/` and are copied into the targe
 - `.github/workflows/readme-screenshot.yml`: refreshes that frame on a pull request and commits it back to the branch. The path list ships as `REPLACE_WITH_PROJECT_PATHS`, and the job's first step after checkout exits 1 while it stays, since a job that never fires leaves no run and no diff to notice. The workflow's own path is in the list so the installing pull request reaches that step. When a commit-back is right and when a report is, `governance/rules/tooling/700-ci-workflow.md` states the test.
 - `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for ESLint, Tailwind, Playwright, Vitest.
 - `.github/workflows/verify.yml`: `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests` jobs.
-- `scripts/verify.sh`: extends base verify with typecheck, lint, unit tests, and build in the full order. Its last stage runs `scripts/check-card-exclusion.sh` whenever that file is installed, which puts the social card route's build exclusion on the default path rather than behind a flag nobody passes. The stage tests for the script rather than for a framework, so this layer owns when the check runs and the stack shipping a card route owns what it reads. The astro reference carries the route itself.
+- `scripts/verify.json`: the phases base's verify runner requires here, being typecheck, lint, unit tests, and build. `## Verify script` covers the order and the card exclusion stage.
 - `scripts/worktree-port.sh`: prints a base port plus this working directory's offset. Called with no argument it prints the offset alone. It refuses a folder left under the worktrees directory after its worktree was removed, rather than printing a port for it.
 
 ## What stays in per-stack adapters
@@ -128,6 +128,6 @@ The sweep under `screenshots/` is ignored again, and only a flagged case's `evid
 
 ## Verify script
 
-The web layer's `scripts/verify.sh` replaces the base version. Order: typecheck, lint, format, spelling, shell, unit tests, build, markdown bans, then the card exclusion check where one is installed. Stack adapters may override if their typecheck or build differs.
+The web layer's `scripts/verify.json` requires `typecheck`, `lint`, `test:run`, and `build`, and base's `scripts/verify.ts` runs them in its fixed order: typecheck, lint, format, spelling, shell, unit tests, build, markdown bans, then the card exclusion check where one is installed. astro, vite-react, and nextjs inherit the list, since the nearest stack's copy wins. An adapter whose phases differ ships its own `verify.json` rather than a script.
 
-The card stage is conditional on `scripts/check-card-exclusion.sh` existing rather than on the stack, so a project with no card route runs one less stage and needs no override to skip it. A stack that ships a card route ships that script, and the check reads the build the stage before it produced.
+The card stage runs `scripts/check-card-exclusion.sh` whenever that file is installed, which keeps the social card route's build exclusion on the default path rather than behind a flag. It tests for the script rather than the stack, so a project with no card route runs one less stage with no override, and the stack shipping a card route owns what the check reads, being the build the stage before it produced. The astro reference carries the route itself.