@erclx/canon 5.8.0 → 5.10.0

package/src/tooling/stamp.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { writeChainStamp } from '@/sync/stamp'
-import type { Manifest } from '@/tooling/manifest'
+import { isWholeStack, type Manifest } from '@/tooling/manifest'
 import { readPackage } from '@/tooling/package'
 
 /**
@@ -33,12 +33,21 @@ export async function recordToolingChain(
   await writeChainStamp(
     target,
     { domain: 'tooling', toolkitRoot },
-    chain.map((manifest) => manifest.name),
+    recordedStacks(chain),
     now,
   )
   return true
 }
 
+/**
+ * The stack names a chain stamp records. A skipped stack kept for its
+ * per-root configs stays out, since the report re-resolves each recorded name
+ * as a whole manifest and would then measure every config the skip withheld.
+ */
+export function recordedStacks(chain: readonly Manifest[]): string[] {
+  return chain.filter(isWholeStack).map((manifest) => manifest.name)
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }

package/src/tooling/subfolder.ts

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync, realpathSync } from 'node:fs'
 import { basename, join, relative } from 'node:path'
 import { gitEnv } from '@/git-env'
-import { listFiles, type Manifest } from '@/tooling/manifest'
+import { isWholeStack, type Manifest, seedFiles } from '@/tooling/manifest'
 
 /**
  * The path the generated subfolder spell config is written to. Written
@@ -83,11 +83,15 @@ export function hasSpellConfig(target: string): boolean {
 export function subfolderSpellConfig(
   chain: readonly Manifest[],
 ): string | undefined {
-  if (chain.some((manifest) => manifest.name === 'base')) return undefined
+  if (
+    chain.some((manifest) => manifest.name === 'base' && isWholeStack(manifest))
+  ) {
+    return undefined
+  }
 
   const lists = new Set<string>()
   for (const manifest of chain) {
-    for (const rel of listFiles(manifest.seedsDir)) {
+    for (const rel of seedFiles(manifest)) {
       if (rel.startsWith('.cspell/') && rel.endsWith('.txt')) lists.add(rel)
     }
   }

package/standards/tasks.md

@@ -124,9 +124,9 @@ 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. A plan cited by two tasks is a misfile rather than a shape to design for.
+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.
 
-`canon tasks plan-link <task> <plan>` writes or corrects the `Plan:` line, so the line is a mechanical write rather than hand-edited markdown.
+`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.
 
 `Groundwork:` points at `../groundwork/<slug>/`, the folder `plan-groundwork` fills. It names the surface it points at the way `Plan:` does. Use this key alone. `Research record` and `Decision record` are earlier spellings of the same thing and both convert to it.
 

package/tooling/astro/reference.md

@@ -69,7 +69,7 @@ The social card is a route the project keeps rather than a page a render writes
 - `card.config.mjs`: a second Astro config whose `srcDir` points at `./card-src`, which the main config's page router never reads. That is what excludes the card from the published build structurally rather than by a filename convention, the same mechanism `scenarios.astro` reaches for with `import.meta.env.DEV`. Its base port is `4421` plus `WORKTREE_PORT_OFFSET`, outside the band `astro.config.mjs` serves from, so a card server and a dev server of one worktree never contend.
 - `card-src/pages/og-card.astro`: the route, shipped as a working placeholder so it serves before any pick has been taken. It imports the project's own global stylesheet, which is what lets the composition read real tokens and real fonts instead of typed copies. It reads `--color-background` and `--color-text`, the names `canon design css` emits, and sets no `font-family` at all so the card inherits the project's body font rather than reading a font token the design system does not emit.
 - `scripts/check-card-exclusion.sh`: fails when the route's `<meta name="og-card-marker">` tag reaches `dist/`, and fails when the route dropped that tag, since the marker is what the leak test reads for.
-- `bun run card:dev` serves the route. `bun run card:check` runs the exclusion check, which the web layer's `scripts/verify.sh` also runs after its build stage whenever the script is installed.
+- `bun run card:dev` serves the route. `bun run card:check` runs the exclusion check, which base's verify runner, `scripts/verify.ts`, also runs after its build stage whenever the script is installed.
 
 ### Why each piece is shaped that way
 

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

@@ -0,0 +1,3 @@
+{
+  "require": ["format", "check:format", "check:spell", "check:shell"]
+}

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'" }
+  ]
+}