@erclx/canon 4.113.0 → 4.115.0

package/src/tooling/subfolder.ts

@@ -0,0 +1,110 @@
+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'
+
+/**
+ * The path the generated subfolder spell config is written to. Written
+ * copy-once, since a project that already configured cspell here owns it.
+ */
+export const SUBFOLDER_SPELL_CONFIG = 'cspell.json'
+
+const WITHHELD_PREFIX = '.github/'
+
+const SPELL_CONFIG_NAMES = ['cspell.json', '.cspell.json']
+
+/**
+ * Whether the target sits below the root of the git repository holding it. A
+ * target outside any repository, or one git cannot read, counts as a root, so
+ * a scratch folder with no repository keeps the behavior a root sync has.
+ *
+ * Synchronous because `scan` and `buildToolingReport` are, which is why this
+ * does not reuse the async worktree reader.
+ */
+export function isSubfolderTarget(target: string): boolean {
+  return subfolderPath(target) !== undefined
+}
+
+/**
+ * The target's path relative to its git toplevel, which is what a root CI
+ * job names as its `working-directory`. Undefined wherever
+ * `isSubfolderTarget` reads a root.
+ */
+export function subfolderPath(target: string): string | undefined {
+  const result = Bun.spawnSync(
+    ['git', '-C', target, 'rev-parse', '--show-toplevel'],
+    { env: gitEnv(), stdout: 'pipe', stderr: 'ignore' },
+  )
+  if (result.exitCode !== 0) return undefined
+
+  const toplevel = result.stdout.toString().trim()
+  if (toplevel === '') return undefined
+
+  try {
+    const path = relative(realpathSync(toplevel), realpathSync(target))
+    return path === '' ? undefined : path
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * GitHub reads workflows only at the repository root, so a `.github/` copied
+ * into a subfolder is a file nothing runs. `scan` and `injectConfigs` both
+ * read this, so the set the diff withholds and the set the sync skips cannot
+ * disagree.
+ */
+export function isWithheldInSubfolder(rel: string): boolean {
+  return rel.startsWith(WITHHELD_PREFIX)
+}
+
+/**
+ * Whether the target already carries a cspell config of its own, in any of
+ * the file names cspell searches for.
+ */
+export function hasSpellConfig(target: string): boolean {
+  if (SPELL_CONFIG_NAMES.some((name) => existsSync(join(target, name)))) {
+    return true
+  }
+  if (!existsSync(target)) return false
+  return readdirSync(target).some((name) => name.startsWith('cspell.config.'))
+}
+
+/**
+ * Builds the nested cspell config that registers a subfolder's seeded word
+ * lists. A root `cspell '**'` merges it with the root config for files under
+ * the subfolder. Each dictionary takes a `local-` name, since reusing a root
+ * dictionary's name shadows it inside the subfolder and a root word then fails
+ * there.
+ *
+ * Returns nothing when the chain carries `base`, whose own seed already writes
+ * a config, or when no stack seeds a word list.
+ */
+export function subfolderSpellConfig(
+  chain: readonly Manifest[],
+): string | undefined {
+  if (chain.some((manifest) => manifest.name === 'base')) return undefined
+
+  const lists = new Set<string>()
+  for (const manifest of chain) {
+    for (const rel of listFiles(manifest.seedsDir)) {
+      if (rel.startsWith('.cspell/') && rel.endsWith('.txt')) lists.add(rel)
+    }
+  }
+  if (lists.size === 0) return undefined
+
+  const definitions = [...lists].sort().map((path) => ({
+    name: `local-${basename(path, '.txt')}`,
+    path,
+    addWords: true,
+  }))
+
+  const config = {
+    version: '0.2',
+    dictionaryDefinitions: definitions,
+    dictionaries: definitions.map((definition) => definition.name),
+    ignorePaths: ['.cspell/**'],
+  }
+
+  return `${JSON.stringify(config, null, 2)}\n`
+}

package/standards/teach.md

@@ -44,18 +44,19 @@ A workspace failing these is non-conforming even when it satisfies every shape r
 
 ## Layout
 
-| Path                  | Holds                                                  | Required |
-| --------------------- | ------------------------------------------------------ | -------- |
-| `MISSION.md`          | The subject, the learner's starting point, and success | Always   |
-| `RESOURCES.md`        | Sources read and sources found but not opened          | Always   |
-| `GLOSSARY.md`         | Terms the subject defines, one entry each              | Always   |
-| `NOTES.md`            | Session scratch that belongs to no other file          | Optional |
-| `reference/<slug>.md` | Durable reference pages, the promotable half           | Optional |
-| `learning-records/`   | Numbered records of what the learner was taken through | Optional |
-| `lessons/`            | Numbered lessons, generated and disposable             | Optional |
-| `assets/`             | Files several lessons share, including the stylesheet  | Optional |
-
-Only the markdown half answers to a conformance check: `MISSION.md`, `RESOURCES.md`, `GLOSSARY.md`, `NOTES.md`, `reference/`, and `learning-records/`. A lesson is generated markup that nothing downstream cites, so this standard fixes its filename and its location and says nothing about what it contains.
+| Path                    | Holds                                                                   | Required |
+| ----------------------- | ----------------------------------------------------------------------- | -------- |
+| `MISSION.md`            | The subject, the learner's starting point, and success                  | Always   |
+| `RESOURCES.md`          | Sources read and sources found but not opened                           | Always   |
+| `GLOSSARY.md`           | Terms the subject defines, one entry each                               | Always   |
+| `NOTES.md`              | Session scratch that belongs to no other file                           | Optional |
+| `reference/<slug>.md`   | Durable reference pages, the promotable half                            | Optional |
+| `reference/<slug>.html` | Each reference page rendered by `canon teach nav`, never edited by hand | Optional |
+| `learning-records/`     | Numbered records of what the learner was taken through                  | Optional |
+| `lessons/`              | Numbered lessons, generated and disposable                              | Optional |
+| `assets/`               | Files several lessons share, including the stylesheet                   | Optional |
+
+Only the markdown half answers to a conformance check: `MISSION.md`, `RESOURCES.md`, `GLOSSARY.md`, `NOTES.md`, the markdown under `reference/`, and `learning-records/`. A lesson is generated markup that nothing downstream cites, so this standard fixes its filename and its location and says nothing about what it contains. A rendered reference page is the same kind of output, rewritten from its markdown on every `nav` run.
 
 ## Frontmatter
 

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

@@ -82,7 +82,11 @@ if command -v canon >/dev/null 2>&1; then
     # ran the one-time setup. Nothing to report.
     if [ "$reason" != "no-repository" ]; then
       printf '\n🗄️  Records not backed up: %s\n' "${reason:-unknown}"
-      printf 'Run canon records push when the remote is reachable.\n\n'
+      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
 fi

package/tooling/go/configs/.golangci.yml

@@ -0,0 +1,25 @@
+version: '2'
+
+linters:
+  default: standard
+  enable:
+    - bodyclose
+    - errorlint
+    - gosec
+    - misspell
+    - noctx
+    - revive
+    - sqlclosecheck
+    - rowserrcheck
+    - unconvert
+  exclusions:
+    paths:
+      - node_modules
+
+formatters:
+  enable:
+    - gofmt
+    - goimports
+  exclusions:
+    paths:
+      - node_modules

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

@@ -0,0 +1,95 @@
+#!/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}"; }
+log_skip() { echo -e "${GREY}│ - $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"
+  command -v go >/dev/null 2>&1 || log_error "go is not installed"
+  command -v golangci-lint >/dev/null 2>&1 || log_error "golangci-lint is not installed. Run 'go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest'"
+}
+
+check_package() {
+  [ -f package.json ] || log_error "No package.json here. Run 'bun init', then sync the stack again"
+}
+
+has_script() {
+  bun -e 'process.exit(require(process.cwd() + "/package.json").scripts?.[process.argv[1]] ? 0 : 1)' "$1"
+}
+
+# A subfolder synced with --skip base declares none of base's scripts, since
+# the repository root owns them. Each base phase runs only where its script is
+# declared, so this script passes on its own in that subfolder.
+run_base_phase() {
+  local title=$1
+  local script=$2
+  local err_msg=$3
+  local pass_msg=$4
+
+  log_step "$title"
+  if ! has_script "$script"; then
+    log_skip "Skipped: $script is not declared here, so the repository root runs it"
+    return
+  fi
+  run_check "bun run $script" "$err_msg"
+  log_info "$pass_msg"
+}
+
+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
+  check_package
+
+  if [ "$NESTED" = false ]; then echo -e "${GREY}┌${NC}"; fi
+
+  echo -e "${GREY}├${NC} ${WHITE}Typecheck${NC}"
+  run_check "bun run typecheck" "Typecheck failed"
+  log_info "Typecheck passed"
+
+  log_step "Lint"
+  run_check "bun run lint" "Lint failed"
+  log_info "Lint passed"
+
+  run_base_phase "Formatting" "format" "Format failed" "Format applied"
+  run_base_phase "Format check" "check:format" "Format check failed" "Format check passed"
+  run_base_phase "Spelling" "check:spell" "Spell check failed" "Spell check passed"
+  run_base_phase "Shell" "check:shell" "Shell check failed" "Shell check passed"
+
+  log_step "Unit tests"
+  run_check "bun run test:run" "Unit tests failed"
+  log_info "Unit tests passed"
+
+  if [ "$NESTED" = false ]; then
+    echo -e "${GREY}└${NC}\n"
+    echo -e "${GREEN}✓ Verification passed${NC}"
+  fi
+}
+
+main "$@"

package/tooling/go/manifest.toml

@@ -0,0 +1,13 @@
+[stack]
+name = "go"
+extends = "base"
+runtime = "go"
+scaffold = "mkdir {{name}} && cd {{name}} && go mod init example.com/{{name}} && go mod edit -ignore=./node_modules"
+
+[scripts]
+"lint" = "golangci-lint run ./..."
+"lint:fix" = "golangci-lint fmt ./... && golangci-lint run --fix ./..."
+"typecheck" = "go vet ./..."
+"test" = "go test ./..."
+"test:run" = "go test -v ./..."
+"build" = "go build ./..."

package/tooling/go/reference.md

@@ -0,0 +1,60 @@
+# Tooling Go reference
+
+> Extends: `base`. Apply base stack first.
+
+## 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.
+
+## Scaffold checklist
+
+1. Scaffold with `go mod init <module-path>`. The module path is the project's own identity, so this stack never ships a `go.mod`.
+2. Keep `./...` out of `node_modules`: `go mod edit -ignore=./node_modules`. At a root sync the base layer installs `node_modules/` inside the module, and a package there can ship a `.go` file that `go vet`, `go test`, and `golangci-lint` would otherwise walk. The directive needs Go 1.25 or later.
+3. Seed `package.json` so the base layer's bun-side tools (husky, prettier, cspell, commitlint) have a target to install into: `bun init -y`.
+4. Install base tooling: `canon tooling sync base . --write`
+5. Install go tooling: `canon tooling sync go . --write`
+6. Install the linter: `go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest`. The manifest declares no `[dependencies.dev]`, because manifest injection runs `bun add -D`, which cannot install a Go tool. This step stays manual.
+7. Run `bun run lint:fix` then `bun run check`.
+
+The go stack also ships `smoke_test.go` at the module root as a copy-once seed. A module with no `.go` file fails `golangci-lint run`, `go vet`, and `go test` on an empty package list, so the seed is what lets `bun run check` pass on a fresh scaffold. It declares `package main`, so delete or rename it once the root package takes another name, or the build reports two packages in one folder.
+
+## golangci-lint
+
+- Use config `version: '2'`.
+- Start from `default: standard`.
+- Enable `bodyclose`, `errorlint`, `gosec`, `misspell`, `noctx`, `revive`, `sqlclosecheck`, `rowserrcheck`, and `unconvert`. The two SQL linters report only on `database/sql` call sites, so they cost nothing in a module without a database.
+- 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
+
+- 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.
+- 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.
+- 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
+
+- Install Go with `actions/setup-go`, reading the version from `go.mod` through `go-version-file`.
+- Install the linter with the same `go install` line as the scaffold checklist.
+- Run `go test -race ./...` in CI.
+
+## Anti-patterns
+
+- Do not ship `go.mod` or `go.sum` from tooling. Both belong to the project, and a golden copy would overwrite its module path on every sync.
+- Do not pin the linter through a `tools.go` file or a `tool` directive in `go.mod`. The module is project-owned, so the install stays in the checklist.
+- Do not ship a `Dockerfile`, `.dockerignore`, or `compose.yaml` under tooling. Those are deployment choices and belong in the project itself.
+
+## Development docs (extend)
+
+Append to the `## Scripts` table:
+
+| `bun run lint` | Run `golangci-lint run`. |
+| `bun run lint:fix` | Format with `golangci-lint fmt`, then auto-fix with `golangci-lint run --fix`. |
+| `bun run typecheck` | Run `go vet`. |
+| `bun run test` | Run `go test`. |
+| `bun run test:run` | Run `go test -v` (used by `verify`). |
+| `bun run build` | Run `go build`. |
+
+## CI docs (extend)
+
+In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `go vet ./...` passes ``. Add a Lint row whose assertion reads: `` `golangci-lint run` passes ``. Add a Tests row whose assertion reads: `` `go test -race ./...` exits 0 ``.

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

@@ -0,0 +1,16 @@
+bodyclose
+Errorf
+errorlint
+Fatalf
+gofmt
+goimports
+golangci
+goroutine
+goroutines
+gosec
+httptest
+noctx
+nolint
+rowserrcheck
+sqlclosecheck
+unconvert

package/tooling/go/seeds/smoke_test.go

@@ -0,0 +1,9 @@
+package main
+
+import "testing"
+
+func TestSmoke(t *testing.T) {
+	if 1+1 != 2 {
+		t.Fatal("arithmetic is broken")
+	}
+}

package/tooling/php/configs/.php-cs-fixer.dist.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+$finder = (new PhpCsFixer\Finder())
+    ->in([__DIR__ . '/src', __DIR__ . '/tests']);
+
+return (new PhpCsFixer\Config())
+    ->setRiskyAllowed(true)
+    ->setRules([
+        '@PER-CS' => true,
+        'declare_strict_types' => true,
+        'strict_comparison' => true,
+        'no_unused_imports' => true,
+        'ordered_imports' => true,
+    ])
+    ->setFinder($finder)
+    ->setCacheFile(__DIR__ . '/.php-cs-fixer.cache');

package/tooling/php/configs/phpstan.neon

@@ -0,0 +1,5 @@
+parameters:
+    level: max
+    paths:
+        - src
+        - tests

package/tooling/php/configs/phpunit.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+         failOnWarning="true"
+         failOnRisky="true">
+    <testsuites>
+        <testsuite name="unit">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+    <source>
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
+</phpunit>

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

@@ -0,0 +1,100 @@
+#!/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}"; }
+log_skip() { echo -e "${GREY}│ - $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"
+  command -v php >/dev/null 2>&1 || log_error "php is not installed"
+  command -v composer >/dev/null 2>&1 || log_error "composer is not installed"
+}
+
+check_package() {
+  [ -f package.json ] || log_error "No package.json here. Run 'bun init', then sync the stack again"
+}
+
+check_vendor() {
+  [ -x vendor/bin/phpunit ] || log_error "No vendor/bin/phpunit here. Run 'composer install'"
+}
+
+has_script() {
+  bun -e 'process.exit(require(process.cwd() + "/package.json").scripts?.[process.argv[1]] ? 0 : 1)' "$1"
+}
+
+# A subfolder synced with --skip base declares none of base's scripts, since
+# the repository root owns them. Each base phase runs only where its script is
+# declared, so this script passes on its own in that subfolder.
+run_base_phase() {
+  local title=$1
+  local script=$2
+  local err_msg=$3
+  local pass_msg=$4
+
+  log_step "$title"
+  if ! has_script "$script"; then
+    log_skip "Skipped: $script is not declared here, so the repository root runs it"
+    return
+  fi
+  run_check "bun run $script" "$err_msg"
+  log_info "$pass_msg"
+}
+
+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
+  check_package
+  check_vendor
+
+  if [ "$NESTED" = false ]; then echo -e "${GREY}┌${NC}"; fi
+
+  echo -e "${GREY}├${NC} ${WHITE}Typecheck${NC}"
+  run_check "bun run typecheck" "Typecheck failed"
+  log_info "Typecheck passed"
+
+  log_step "Lint"
+  run_check "bun run lint" "Lint failed"
+  log_info "Lint passed"
+
+  run_base_phase "Formatting" "format" "Format failed" "Format applied"
+  run_base_phase "Format check" "check:format" "Format check failed" "Format check passed"
+  run_base_phase "Spelling" "check:spell" "Spell check failed" "Spell check passed"
+  run_base_phase "Shell" "check:shell" "Shell check failed" "Shell check passed"
+
+  log_step "Unit tests"
+  run_check "bun run test:run" "Unit tests failed"
+  log_info "Unit tests passed"
+
+  if [ "$NESTED" = false ]; then
+    echo -e "${GREY}└${NC}\n"
+    echo -e "${GREEN}✓ Verification passed${NC}"
+  fi
+}
+
+main "$@"

package/tooling/php/manifest.toml

@@ -0,0 +1,15 @@
+[stack]
+name = "php"
+extends = "base"
+runtime = "composer"
+scaffold = "mkdir {{name}} && cd {{name}} && composer init -n --name example/{{name}} --autoload src/"
+
+[scripts]
+"lint" = "vendor/bin/php-cs-fixer check --diff"
+"lint:fix" = "vendor/bin/php-cs-fixer fix"
+"typecheck" = "vendor/bin/phpstan analyse --no-progress"
+"test" = "vendor/bin/phpunit"
+"test:run" = "vendor/bin/phpunit --testdox"
+
+[gitignore]
+"# PHP" = ["vendor/", ".php-cs-fixer.cache", ".phpunit.cache/", ".phpunit.result.cache"]

package/tooling/php/reference.md

@@ -0,0 +1,74 @@
+# Tooling PHP reference
+
+> Extends: `base`. Apply base stack first.
+
+## 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.
+
+## Scaffold checklist
+
+1. Scaffold with `composer init -n --name <vendor>/<name> --autoload src/`. The package name and namespace are the project's own identity, so this stack never ships a `composer.json`.
+2. Seed `package.json` so the base layer's bun-side tools (husky, prettier, cspell, commitlint) have a target to install into: `bun init -y`.
+3. Install base tooling: `canon tooling sync base . --write`
+4. Install php tooling: `canon tooling sync php . --write`
+5. Install the dev tools: `composer require --dev friendsofphp/php-cs-fixer phpstan/phpstan phpunit/phpunit`. The manifest declares no `[dependencies.dev]`, because manifest injection runs `bun add -D`, which cannot install a Composer package. This step stays manual.
+6. Run `bun run lint:fix` then `bun run check`.
+
+Use PHP 8.3 or later, since PHPUnit 12 requires it.
+
+Keep both `src/` and `tests/` in place. All three tools read both paths and fail when either is missing. The scaffold creates `src/`, but git does not commit an empty folder, so a fresh clone with no source yet fails `lint` and `typecheck` until the first class lands there.
+
+The php stack also ships `tests/SmokeTest.php` as a copy-once seed, so `bun run check` passes on a fresh scaffold. Delete or replace it with real tests.
+
+## PHP CS Fixer
+
+- Scan `src` and `tests`.
+- Allow risky rules.
+- Apply `@PER-CS`, plus `declare_strict_types`, `strict_comparison`, `no_unused_imports`, and `ordered_imports`.
+- Write the cache to `.php-cs-fixer.cache` beside the config.
+
+## PHPStan
+
+- Set `level: max`.
+- Analyse `src` and `tests`.
+
+## PHPUnit
+
+- Bootstrap from `vendor/autoload.php` and validate against the vendored schema.
+- Set `colors`, `failOnWarning`, and `failOnRisky`.
+- Run one `unit` suite over `tests`, with `src` as the source.
+
+## verify.sh
+
+- 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.
+
+## Gitignore
+
+- `# PHP`: `vendor/`, `.php-cs-fixer.cache`, `.phpunit.cache/`, `.phpunit.result.cache`
+
+## CI
+
+- Install PHP with `shivammathur/setup-php` and `tools: composer`.
+- Run `composer install`, then `bun run typecheck`, `bun run lint`, and `bun run test:run`.
+
+## Anti-patterns
+
+- Do not ship `composer.json` or `composer.lock` from tooling. Both belong to the project, and a golden copy would overwrite its package name on every sync.
+- Do not add a `phpstan-baseline.neon` to reach `level: max`. Fix the finding or lower the level in the project.
+- Do not ship a `Dockerfile`, `.dockerignore`, or `compose.yaml` under tooling. Those are deployment choices and belong in the project itself.
+
+## Development docs (extend)
+
+Append to the `## Scripts` table:
+
+| `bun run lint` | Run `php-cs-fixer check --diff`. |
+| `bun run lint:fix` | Auto-fix with `php-cs-fixer fix`. |
+| `bun run typecheck` | Run `phpstan analyse`. |
+| `bun run test` | Run `phpunit`. |
+| `bun run test:run` | Run `phpunit --testdox` (used by `verify`). |
+
+## CI docs (extend)
+
+In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `phpstan analyse` passes ``. Add a Lint row whose assertion reads: `` `php-cs-fixer check` passes ``. Add a Tests row whose assertion reads: `` `phpunit` exits 0 ``.

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

@@ -0,0 +1,5 @@
+analyse
+friendsofphp
+phpstan
+phpunit
+testdox

package/tooling/php/seeds/tests/SmokeTest.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+use PHPUnit\Framework\TestCase;
+
+final class SmokeTest extends TestCase
+{
+    public function testSmoke(): void
+    {
+        $this->assertSame(2, 1 + 1);
+    }
+}