@erclx/canon 4.114.0 → 4.116.0

package/src/teach/render.ts

@@ -1,6 +1,7 @@
 import { Heading } from '@/teach/components/heading'
 import { List } from '@/teach/components/list'
 import { Paragraph } from '@/teach/components/paragraph'
+import { type Reference, Refs } from '@/teach/components/refs'
 import { render } from '@/teach/html/jsx-runtime'
 import type { TeachRefused } from '@/teach/workspace'
 
@@ -10,12 +11,14 @@ export type LessonBlock =
       readonly type: 'paragraph'
       readonly text: string
       readonly lede?: boolean
+      readonly cites?: readonly number[]
     }
   | {
       readonly type: 'list'
       readonly items: readonly string[]
       readonly ordered?: boolean
     }
+  | { readonly type: 'refs'; readonly items: readonly Reference[] }
   | { readonly type: 'raw'; readonly html: string }
 
 export interface RenderRendered {
@@ -25,7 +28,9 @@ export interface RenderRendered {
 
 export type RenderOutcome = RenderRendered | TeachRefused
 
-const BLOCK_TYPES = ['heading', 'paragraph', 'list', 'raw'] as const
+const BLOCK_TYPES = ['heading', 'paragraph', 'list', 'refs', 'raw'] as const
+
+const LINK_PROTOCOLS = new Set(['http:', 'https:'])
 
 function isBlockType(value: unknown): value is LessonBlock['type'] {
   return (BLOCK_TYPES as readonly string[]).includes(value as string)
@@ -48,10 +53,46 @@ function isStringArray(value: unknown): value is readonly string[] {
   return Array.isArray(value) && value.every(isString)
 }
 
+function isCiteArray(value: unknown): value is readonly number[] {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.every((cite) => Number.isInteger(cite) && cite > 0)
+  )
+}
+
+function isLinkUrl(value: string): boolean {
+  if (!URL.canParse(value)) return false
+  return LINK_PROTOCOLS.has(new URL(value).protocol)
+}
+
+function readReference(item: unknown, position: number): Reference | string {
+  if (typeof item !== 'object' || item === null) {
+    return `reference ${position} is not an object`
+  }
+  const { title, url, note } = item as Record<string, unknown>
+  if (!isString(title) || title === '') {
+    return `reference ${position} needs a non-empty string title`
+  }
+  if (note !== undefined && !isString(note)) {
+    return `reference ${position} note must be a string`
+  }
+  if (url !== undefined && !(isString(url) && isLinkUrl(url))) {
+    return `reference ${position} url must be an http or https URL`
+  }
+  return { title, url, note }
+}
+
+interface RenderedBlock {
+  readonly html: string
+  readonly cites?: readonly number[]
+  readonly referenceCount?: number
+}
+
 function renderBlock(
   block: unknown,
   index: number,
-): { readonly html: string } | TeachRefused {
+): RenderedBlock | TeachRefused {
   if (typeof block !== 'object' || block === null || !('type' in block)) {
     return badBlock(index, 'not an object carrying a type')
   }
@@ -83,8 +124,24 @@ function renderBlock(
       if (fields.lede !== undefined && typeof fields.lede !== 'boolean') {
         return badBlock(index, 'paragraph lede must be a boolean')
       }
+      if (fields.cites !== undefined && !isCiteArray(fields.cites)) {
+        return badBlock(
+          index,
+          'paragraph cites must be a non-empty array of positive integers',
+        )
+      }
+      if (fields.lede === true && fields.cites !== undefined) {
+        return badBlock(index, 'a lede paragraph cannot carry cites')
+      }
       return {
-        html: render(Paragraph({ lede: fields.lede, children: fields.text })),
+        html: render(
+          Paragraph({
+            lede: fields.lede,
+            cites: fields.cites,
+            children: fields.text,
+          }),
+        ),
+        cites: fields.cites,
       }
     }
     case 'list': {
@@ -98,6 +155,21 @@ function renderBlock(
         html: render(List({ ordered: fields.ordered, items: fields.items })),
       }
     }
+    case 'refs': {
+      if (!Array.isArray(fields.items) || fields.items.length === 0) {
+        return badBlock(index, 'refs needs a non-empty items array')
+      }
+      const items: Reference[] = []
+      for (const [position, item] of fields.items.entries()) {
+        const reference = readReference(item, position + 1)
+        if (isString(reference)) return badBlock(index, reference)
+        items.push(reference)
+      }
+      return {
+        html: render(Refs({ items })),
+        referenceCount: items.length,
+      }
+    }
     case 'raw': {
       if (!isString(fields.html)) {
         return badBlock(index, 'raw needs a string html')
@@ -112,15 +184,31 @@ function renderBlock(
  * `lesson.test.tsx` composes as JSX, so a real lesson and the component test
  * share one rendering mechanism. Every block past the first refusal
  * goes unread, matching how a malformed JSON parse refuses the whole call.
+ * Citations resolve across blocks once every block has rendered, so a marker
+ * with no reference refuses rather than leaving a dead anchor.
  */
 export function renderLessonBody(blocks: readonly unknown[]): RenderOutcome {
-  const rendered: string[] = []
+  const rendered: RenderedBlock[] = []
+  let referenceCount = 0
 
   for (const [index, block] of blocks.entries()) {
     const result = renderBlock(block, index)
     if ('ok' in result) return result
-    rendered.push(result.html)
+    if (result.referenceCount !== undefined) {
+      if (referenceCount > 0) {
+        return badBlock(index, 'a lesson carries one refs block')
+      }
+      referenceCount = result.referenceCount
+    }
+    rendered.push(result)
+  }
+
+  for (const [index, block] of rendered.entries()) {
+    const dangling = block.cites?.find((cite) => cite > referenceCount)
+    if (dangling !== undefined) {
+      return badBlock(index, `cite ${dangling} resolves to no reference`)
+    }
   }
 
-  return { ok: true, html: rendered.join('\n') }
+  return { ok: true, html: rendered.map((block) => block.html).join('\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/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