jackherd 1.12.7 → 1.14.0

package/kit/hooks/hooks/plain-question/code-cache.ts

@@ -0,0 +1,70 @@
+import { isRecord } from '../shared/json'
+
+/** A plan file as `stat` sees it: its absolute path, modification time and size, the cache's key. */
+export type PlanFileStat = { path: string; mtimeMs: number; size: number }
+
+/** The codes of each plan file the last dialog read, by absolute path, with the time and size they were read at. */
+export type CodeCache = Record<string, { mtimeMs: number; size: number; codes: string[] }>
+
+/** The codes the files define together (null when none could be read), the cache to keep, and whether it changed. */
+export type CodeLookup = { codes: Set<string> | null; cache: CodeCache; changed: boolean }
+
+const CACHE_VERSION = 1
+
+const isEntry = (value: unknown): value is CodeCache[string] =>
+  isRecord(value) &&
+  typeof value.mtimeMs === 'number' &&
+  typeof value.size === 'number' &&
+  Array.isArray(value.codes) &&
+  value.codes.every((code) => typeof code === 'string')
+
+/** The cache file's text as a cache; a missing, broken or foreign file, and each entry of the wrong shape, read as empty. */
+export const parseCodeCache = (text: string | null): CodeCache => {
+  try {
+    const parsed: unknown = text === null ? null : JSON.parse(text)
+    if (!isRecord(parsed) || parsed.version !== CACHE_VERSION || !isRecord(parsed.entries)) return {}
+    return Object.fromEntries(
+      Object.entries(parsed.entries).flatMap(([path, entry]): [string, CodeCache[string]][] =>
+        isEntry(entry) ? [[path, entry]] : [],
+      ),
+    )
+  } catch {
+    return {}
+  }
+}
+
+export const serializeCodeCache = (cache: CodeCache): string =>
+  `${JSON.stringify({ version: CACHE_VERSION, entries: cache })}\n`
+
+const isFresh = (entry: CodeCache[string] | undefined, { mtimeMs, size }: PlanFileStat): entry is CodeCache[string] =>
+  entry !== undefined && entry.mtimeMs === mtimeMs && entry.size === size
+
+/**
+ * The codes of the plan files: a file whose time and size match its cache entry is not read, the others are read and
+ * parsed, copies with the same text once. The cache keeps exactly the files read or reused now, so an unlinked plan
+ * leaves it.
+ */
+export const lookUpCodes = (
+  stats: readonly PlanFileStat[],
+  cache: CodeCache,
+  readText: (path: string) => string | null,
+  codesOf: (text: string) => string[],
+): CodeLookup => {
+  const parsed = new Map<string, string[]>()
+  const parse = (text: string): string[] => parsed.get(text) ?? parsed.set(text, codesOf(text)).get(text) ?? []
+  let missed = false
+  const entries = stats.flatMap((stat): [string, CodeCache[string]][] => {
+    const entry = cache[stat.path]
+    if (isFresh(entry, stat)) return [[stat.path, entry]]
+    missed = true
+    const text = readText(stat.path)
+    return text === null ? [] : [[stat.path, { mtimeMs: stat.mtimeMs, size: stat.size, codes: parse(text) }]]
+  })
+  const next = Object.fromEntries(entries)
+  const dropped = Object.keys(cache).some((path) => !(path in next))
+  return {
+    codes: entries.length === 0 ? null : new Set(entries.flatMap(([, entry]) => entry.codes)),
+    cache: next,
+    changed: missed || dropped,
+  }
+}

package/kit/hooks/hooks/plain-question/index.ts

@@ -0,0 +1,80 @@
+// PreToolUse hook of Claude Code for AskUserQuestion, shipped by jackherd: the client adapter of the plain-question
+// guard. A dialog that shows a plan code bare (`F9` instead of "the release check (F9)") is denied with one line of
+// reason, so the question is asked again in the user's words. The codes are the ones the plans linked from the boards
+// of the main checkout define, in the main checkout and in the worktrees of the lanes the boards name, else a fallback
+// pattern; a cache keyed by each file's time and size spares reading the unchanged ones. Anything else, and any
+// failure, answers nothing, so the dialog opens.
+import { statSync } from 'node:fs'
+import { join } from 'node:path'
+import { boardLocationOf, boardsIn } from '../shared/boards'
+import { mainCheckoutOf } from '../shared/checkout'
+import { readConfig } from '../shared/config'
+import { readTextOrNull } from '../shared/files'
+import { isRecord } from '../shared/json'
+import { planCodesOf } from '../shared/plan-codes'
+import { ensurePrivateDirectory, writePrivateFile } from '../shared/private-directory'
+import { type CodeCache, lookUpCodes, type PlanFileStat, parseCodeCache, serializeCodeCache } from './code-cache'
+import { denyReasonOf, dialogTextsOf, planPathsOfBoards, planRootsOfBoards } from './run'
+
+const HOOK_EVENT = 'PreToolUse'
+
+/** Where the cache lies: in the main checkout beside `.jackherd/approvals`, ignored by git. */
+const cacheDirectory = (main: string): string => join(main, '.jackherd', 'plan-codes')
+const CACHE_FILE = 'codes.json'
+
+const statOf = (path: string): PlanFileStat | null => {
+  const stat = statSync(path, { throwIfNoEntry: false })
+  return stat?.isFile() ? { path, mtimeMs: stat.mtimeMs, size: stat.size } : null
+}
+
+/** Keeps the cache for the next dialog; a cache that cannot be written only costs that dialog a full read. */
+const saveCache = (main: string, cache: CodeCache): void => {
+  try {
+    ensurePrivateDirectory(cacheDirectory(main))
+    writePrivateFile(join(cacheDirectory(main), CACHE_FILE), serializeCodeCache(cache))
+  } catch {
+    // the next dialog reads the plans again
+  }
+}
+
+/**
+ * The codes of the plans the main checkout's boards link, in the main checkout and in the worktrees of the lanes the
+ * boards name; null outside a repository, without a board location or a readable plan.
+ */
+const planCodesFor = (cwd: string): Set<string> | null => {
+  try {
+    const main = mainCheckoutOf(cwd)
+    const location = boardLocationOf(readConfig([main]))
+    if (location === null) return null
+    const { planLanguage: language, worktreeDirectory } = location
+    const boards = boardsIn(main, location)
+    const roots = planRootsOfBoards(main, worktreeDirectory, boards, language)
+    const stats = planPathsOfBoards(boards, language).flatMap((path) => roots.flatMap((root) => statOf(join(root, path)) ?? []))
+    const cache = parseCodeCache(readTextOrNull(join(cacheDirectory(main), CACHE_FILE)))
+    const lookup = lookUpCodes(stats, cache, readTextOrNull, (text) => [...planCodesOf(text, language)])
+    if (lookup.changed) saveCache(main, lookup.cache)
+    return lookup.codes
+  } catch {
+    return null
+  }
+}
+
+const decide = async (): Promise<string | null> => {
+  try {
+    const input: unknown = JSON.parse(await Bun.stdin.text())
+    if (!isRecord(input) || typeof input.cwd !== 'string') return null
+    const texts = dialogTextsOf(input.tool_input)
+    return texts.length === 0 ? null : denyReasonOf(texts, planCodesFor(input.cwd))
+  } catch {
+    return null
+  }
+}
+
+const reason = await decide()
+if (reason !== null)
+  console.log(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName: HOOK_EVENT, permissionDecision: 'deny', permissionDecisionReason: reason },
+    }),
+  )
+process.exit(0)

package/kit/hooks/hooks/plain-question/run.ts

@@ -0,0 +1,50 @@
+import { join } from 'node:path'
+import { type BoardLanguage, boardPlansOf, isInsideRepository, openLaneNamesOf } from '../shared/board-lanes'
+import type { Board } from '../shared/boards'
+import { isRecord } from '../shared/json'
+import { bareCodesOf } from '../shared/plan-codes'
+
+/** A lane name that is one plain directory name, never `.`, `..` or a path. */
+const LANE_DIRECTORY = /^(?!\.{1,2}$)[A-Za-z0-9._-]+$/
+
+const strings = (values: unknown[]): string[] => values.filter((value): value is string => typeof value === 'string')
+
+const optionTexts = (options: unknown): string[] =>
+  Array.isArray(options) ? options.filter(isRecord).flatMap((option) => strings([option.label, option.description])) : []
+
+/** The texts a dialog shows the user: each question, its header chip, and every option's label and description. */
+export const dialogTextsOf = (toolInput: unknown): string[] => {
+  if (!isRecord(toolInput) || !Array.isArray(toolInput.questions)) return []
+  return toolInput.questions
+    .filter(isRecord)
+    .flatMap((question) => [...strings([question.question, question.header]), ...optionTexts(question.options)])
+}
+
+/** Every plan the boards link, relative to the repository, once; a path that leaves the repository is dropped. */
+export const planPathsOfBoards = (boards: readonly Board[], language: BoardLanguage): string[] => [
+  ...new Set(boards.flatMap(({ text, directory }) => boardPlansOf(text, directory, language)).filter(isInsideRepository)),
+]
+
+/**
+ * Where a plan the boards link may lie: the main checkout, and the worktree of each open lane a board names, where a
+ * lane's new plan may exist before it reaches the main checkout. Other worktrees are not read.
+ */
+export const planRootsOfBoards = (
+  main: string,
+  worktreeDirectory: string,
+  boards: readonly Board[],
+  language: BoardLanguage,
+): string[] => {
+  const lanes = new Set(
+    boards.flatMap(({ text }) => openLaneNamesOf(text, language)).filter((lane) => LANE_DIRECTORY.test(lane)),
+  )
+  return [main, ...[...lanes].map((lane) => join(main, worktreeDirectory, lane))]
+}
+
+/** The reason to send a dialog back: it names the first code it shows bare; null when it shows none. */
+export const denyReasonOf = (texts: readonly string[], codes: ReadonlySet<string> | null): string | null => {
+  const [code] = texts.flatMap((text) => bareCodesOf(text, codes))
+  return code === undefined
+    ? null
+    : `Plan code ${code} without its words: say in everyday words what it is, the code at most in brackets after them, as in "the architecture docs (${code})".`
+}

package/kit/hooks/hooks/shared/board-lanes.ts

@@ -89,6 +89,25 @@ export const laneNamesOf = (markdown: string, language: BoardLanguage): string[]
   ...new Set(laneRows(markdown, language).map(({ lane }) => lane)),
 ]
 
+/** Whether a plan path as `planPathOf` normalises it stays inside the repository: relative, no step out of it. */
+export const isInsideRepository = (path: string): boolean =>
+  !path.startsWith('/') && path !== '..' && !path.startsWith('../')
+
+/** Every plan the lanes table links, cleaned-up lanes included, relative to the repository, in table order. */
+export const boardPlansOf = (markdown: string, boardDirectory: string, language: BoardLanguage): string[] => [
+  ...new Set(laneRows(markdown, language).flatMap(({ cells }) => planPathOf(boardDirectory, cells[PLAN_COLUMN] ?? ''))),
+]
+
+/** Every lane the lanes table names whose current rows do not say it was cleaned up, in table order, read in one pass. */
+export const openLaneNamesOf = (markdown: string, language: BoardLanguage): string[] => {
+  const { laneClosed } = BOARD_WORDS[language]
+  const rowsByLane = new Map<string, Row[]>()
+  for (const row of laneRows(markdown, language)) rowsByLane.set(row.lane, [...(rowsByLane.get(row.lane) ?? []), row])
+  return [...rowsByLane].flatMap(([lane, rows]) =>
+    currentRows(rows, laneClosed).some(({ cells }) => (cells[0] ?? '').includes(laneClosed)) ? [] : [lane],
+  )
+}
+
 /** The rows of `lane` in the board's lanes table; undefined when the table has no row for it. */
 export const lanePlansOf = (
   markdown: string,

package/kit/hooks/hooks/shared/boards.ts

@@ -0,0 +1,96 @@
+/**
+ * Where a project keeps its boards, read from its config, and the boards themselves as the main checkout holds them
+ * (the coordinator keeps its board there, committed or not). Shared by the merge guard and the plain-question guard.
+ */
+import { readdirSync } from 'node:fs'
+import { join, posix } from 'node:path'
+import { BOARD_WORDS, type BoardLanguage } from './board-lanes'
+import { readTextOrNull } from './files'
+import { isRecord } from './json'
+import { isRepositoryDirectory } from './repository-directory'
+
+/** A board's directory relative to the repository, and its text. */
+export type Board = { directory: string; text: string }
+
+/** The plan language, the plan directory and the board pattern and file below it, and where the lane worktrees live. */
+export type BoardLocation = {
+  planLanguage: BoardLanguage
+  planDirectory: string
+  board: { pattern: string; file: string }
+  worktreeDirectory: string
+}
+
+const BOARD_PATTERN = /^(?![-.])[A-Za-z0-9._*?-]+$/
+const BOARD_FILE = /^(?![-.])[A-Za-z0-9._-]+\.md$/
+
+/** The value at `key`, its default when absent, `undefined` when present but invalid. */
+const valueOr = <T>(
+  section: Record<string, unknown>,
+  key: string,
+  isValid: (value: unknown) => value is T,
+  fallback: T,
+) => (!(key in section) ? fallback : isValid(section[key]) ? section[key] : undefined)
+
+const matches =
+  (pattern: RegExp) =>
+  (value: unknown): value is string =>
+    typeof value === 'string' && pattern.test(value)
+
+const isPlanLanguage = (value: unknown): value is BoardLanguage => typeof value === 'string' && Object.hasOwn(BOARD_WORDS, value)
+
+/**
+ * The board location's values of a config, each with its default where absent and `undefined` where present but
+ * invalid; `board` is the config's `board` section.
+ */
+export const boardLocationValues = (config: Record<string, unknown>, board: Record<string, unknown>) => ({
+  planLanguage: valueOr(config, 'planLanguage', isPlanLanguage, 'en'),
+  planDirectory: valueOr(config, 'planDirectory', isRepositoryDirectory, 'docs/plans'),
+  pattern: valueOr(board, 'pattern', matches(BOARD_PATTERN), 'board-*'),
+  file: valueOr(board, 'file', matches(BOARD_FILE), 'board.md'),
+  worktreeDirectory: valueOr(config, 'worktreeDirectory', isRepositoryDirectory, '.claude/worktrees'),
+})
+
+/** The board location of a config; `null` when its `board` section is no object or a value it reads is invalid. */
+export const boardLocationOf = (config: Record<string, unknown>): BoardLocation | null => {
+  const board = config.board ?? {}
+  if (!isRecord(board)) return null
+  const { planLanguage, planDirectory, pattern, file, worktreeDirectory } = boardLocationValues(config, board)
+  if (planLanguage === undefined || planDirectory === undefined || worktreeDirectory === undefined) return null
+  if (pattern === undefined || file === undefined) return null
+  return { planLanguage, planDirectory, board: { pattern, file }, worktreeDirectory }
+}
+
+/** The boards under the plan directory of the main checkout whose directory name matches the board pattern. */
+export const boardsIn = (main: string, location: Pick<BoardLocation, 'planDirectory' | 'board'>): Board[] => {
+  const pattern = new Bun.Glob(location.board.pattern)
+  try {
+    return readdirSync(join(main, location.planDirectory), { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && pattern.match(entry.name))
+      .flatMap((entry) => {
+        const directory = posix.join(location.planDirectory, entry.name)
+        const text = readTextOrNull(join(main, directory, location.board.file))
+        return text === null ? [] : [{ directory, text }]
+      })
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Where a plan the boards link can lie: the main checkout, and every directory below its worktree directory, since a
+ * lane's plan may exist only in the lane's worktree, at the same path relative to it.
+ */
+export const planRootsIn = (main: string, worktreeDirectory: string): string[] => {
+  try {
+    const worktrees = readdirSync(join(main, worktreeDirectory), { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => join(main, worktreeDirectory, entry.name))
+    return [main, ...worktrees]
+  } catch {
+    return [main]
+  }
+}
+
+/** The texts of a plan, `path` relative to the repository, in every root that holds a readable copy. */
+export const planCopiesIn = (roots: readonly string[], path: string): string[] =>
+  roots.flatMap((root) => readTextOrNull(join(root, path)) ?? [])

package/kit/hooks/hooks/shared/plan-codes.ts

@@ -0,0 +1,68 @@
+/**
+ * The codes plans give their phases, decisions and questions (`P7`, `D16`, `F1`, `L3`), read the way a plan defines
+ * them, and the ones a text names bare, outside brackets. The phase headings are read the way `phaseHeadings` in the
+ * package reads them, which a hook cannot import; a test compares both on the repository's real plans.
+ */
+import type { BoardLanguage } from './board-lanes'
+
+/** The plan vocabulary's word for a phase heading, per plan language. */
+export const PHASE_WORDS: Record<BoardLanguage, string> = { de: 'Phase', en: 'Phase' }
+
+/** The prefix a phase id carries outside its heading (`PHASE_ID_PREFIX` in the package). */
+export const PHASE_CODE_PREFIX = 'P'
+
+const CODE = '[A-Z]{1,2}\\d{1,3}[a-z]?'
+const NUMBERED_SECTION = new RegExp(`^##\\s+${PHASE_CODE_PREFIX}?(\\d+[a-z]?)\\s*[—–:-]\\s*(.*)$`)
+const DEFINITIONS = [
+  new RegExp(`^\\|\\s*(?:\\*\\*)?(${CODE})(?:\\*\\*)?\\s*\\|`),
+  new RegExp(`^#{2,6}\\s+(?:\\*\\*)?(${CODE})\\b`),
+  new RegExp(`^\\s*[-*]\\s+\\*\\*(${CODE})\\b`),
+]
+/** A code standing as a word of its own: not after a word character, `-`, `/` or `.`, not before a word character. */
+const STANDALONE = new RegExp(`(?<![\\w/.-])(${CODE})(?!\\w)`, 'g')
+/** Without a plan to read: phase, follow-up, decision and question codes, as the plans of this kit write them. */
+const FALLBACK = /^[FPDE]\d{1,3}[a-z]?$/
+const BRACKETED = /\([^()]*\)/g
+
+const phaseHeadingOf = (language: BoardLanguage): RegExp =>
+  new RegExp(`^###\\s+${PHASE_WORDS[language]}\\s+(\\d+[a-z]?)\\b`, 'i')
+
+/** The phase ids of a plan's headings, `### Phase <id>` and `## <id> — title` alike, lower case as the package reads them. */
+export const phaseIdsOf = (markdown: string, language: BoardLanguage): string[] => {
+  const heading = phaseHeadingOf(language)
+  return markdown.split('\n').flatMap((line) => {
+    const id = (line.match(heading) ?? line.match(NUMBERED_SECTION))?.[1]
+    return id === undefined ? [] : [id.toLowerCase()]
+  })
+}
+
+/**
+ * Every code a plan defines: its phases as `P<id>`, and each code that opens a table row, a heading or a bold list
+ * item (one or two capitals, a number, at most one lower-case letter).
+ */
+export const planCodesOf = (markdown: string, language: BoardLanguage): Set<string> => {
+  const defined = markdown.split('\n').flatMap((line) => {
+    const code = DEFINITIONS.map((definition) => line.match(definition)?.[1]).find((match) => match !== undefined)
+    return code === undefined ? [] : [code]
+  })
+  return new Set([...phaseIdsOf(markdown, language).map((id) => `${PHASE_CODE_PREFIX}${id}`), ...defined])
+}
+
+/** The codes the plans define together; null when there is no plan text, so the fallback pattern decides. */
+export const codesOfPlans = (plans: readonly string[], language: BoardLanguage): Set<string> | null =>
+  plans.length === 0 ? null : new Set(plans.flatMap((plan) => [...planCodesOf(plan, language)]))
+
+/** The text with every bracketed span blanked, innermost first, so a code in brackets is never read as bare. */
+const withoutBrackets = (text: string): string => {
+  const blanked = text.replace(BRACKETED, ' ')
+  return blanked === text ? text : withoutBrackets(blanked)
+}
+
+/**
+ * The codes `text` names bare, outside brackets, in order of appearance: those of `codes`, or, when no plan could be
+ * read (`null`), those of the fallback pattern.
+ */
+export const bareCodesOf = (text: string, codes: ReadonlySet<string> | null): string[] =>
+  [...withoutBrackets(text).matchAll(STANDALONE)]
+    .map((match) => match[1] ?? '')
+    .filter((code) => (codes === null ? FALLBACK.test(code) : codes.has(code)))

package/kit/hooks/hooks.json

@@ -69,6 +69,15 @@
       "timeout": 10
     }
   },
+  "plain-question": {
+    "event": "PreToolUse",
+    "matcher": "AskUserQuestion",
+    "handler": {
+      "type": "command",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/plain-question/index.ts",
+      "timeout": 10
+    }
+  },
   "sent-file": {
     "event": "PostToolUse",
     "matcher": "SendUserFile|Artifact",

package/kit/review/skills/diagnose/SKILL.md

@@ -30,7 +30,7 @@ If the redacted output is not enough to diagnose the bug, say so and ask the use
 
 Spend disproportionate effort here. Be aggressive, be creative, refuse to give up.
 
-**The loop recipes live in [`references/feedback-loops.md`](references/feedback-loops.md)** — Bun tests, a real browser via Playwright, HTTP via curl, message subjects, differential runs. Read it before you build a loop; it also carries the two Bun invocation traps that make a healthy suite look broken.
+**The loop recipes live in [`references/feedback-loops.md`](references/feedback-loops.md)** — the test runner, a real browser via Playwright, HTTP via curl, message subjects, differential runs. Read it before you build a loop; it also names the invocation traps that make a healthy suite look broken.
 
 ### Tighten the loop
 
@@ -111,7 +111,7 @@ A correct seam exercises the **real bug pattern as it occurs at the call site**.
 
 Where a seam exists, follow the decision tree in `.claude/rules/kit/testing.md` (a bug fix always earns a regression test) and:
 
-1. Turn the minimised repro into a failing `*.test.ts` next to the source.
+1. Turn the minimised repro into a failing test, named and placed as `.claude/rules/kit/testing.md` → Runner & File Placement says.
 2. Watch it fail.
 3. Apply the fix — the smallest change that turns it green, no opportunistic refactoring.
 4. Watch it pass.

package/kit/review/skills/diagnose/references/feedback-loops.md

@@ -2,22 +2,13 @@
 
 Recipes for Phase 1 of `/diagnose`. Pick the one that reaches the bug's code path, then tighten it. The project supplement in `.claude/project/diagnose.md` adds the recipes only this project has.
 
-Ordered by how tight the loop tends to be. Reach for the first one that can actually go red on the bug — a Bun test that cannot see the bug is worse than a slower loop that can.
+Ordered by how tight the loop tends to be. Reach for the first one that can actually go red on the bug — a test that cannot see the bug is worse than a slower loop that can.
 
-## 1. Bun test — the default
+## 1. The project's test runner — the default
 
-The tightest loop available. Milliseconds, deterministic, unattended.
+The tightest loop available. Milliseconds, deterministic, unattended: `{{kit.command.test}}`, narrowed to the one test file or module directory that reaches the bug.
 
-```bash
-cd packages/<package> && bun test src/<module>/<file>.test.ts
-```
-
-Two invocation traps make a healthy suite look broken:
-
-- **`EMFILE` / `ProcessFdQuotaExceeded` while dev servers run.** From the workspace root Bun walks the whole monorepo and can exhaust the kernel's descriptor table while watchers hold it. It reports `0 pass / 1 error`, not an assertion failure. Fix: `cd` into the package or module directory first; leave the user's dev servers running.
-- **Run from the package root, not below it.** Bun reads `tsconfig.json` — and with it `jsxImportSource` — from the **working directory**. One level too deep and every `.tsx` a test touches compiles against React's runtime: `Cannot find module 'react/jsx-dev-runtime'`. It reads like a missing dependency in untouched code. Re-run from the package root before concluding anything.
-
-Both failures are environmental. Neither is evidence about the bug.
+Invocation traps make a healthy suite look broken: a runner started from the wrong directory fails on a watcher exhausting file descriptors, or on a config file it resolved from the working directory. Such a failure is environmental, not an assertion, and says nothing about the bug. Re-run from the directory the project's config lives in before concluding anything; the project supplement in `.claude/project/diagnose.md` names the traps of this project's runner.
 
 ## 2. The rendered app — Playwright
 

package/kit/rules/rules/kit/code-style.md

@@ -4,12 +4,9 @@ The kit's core. Project-specific conventions (UI framework, shared component lib
 
 ## Formatting
 
-The formatter and linter config is the authority; these are the conventions it encodes:
+The formatter and linter config is the authority; where it is silent, match the surrounding code.
 
-- Single quotes, no semicolons, 2-space indent, trailing commas.
-- Sorted imports; no unused imports.
-- Arrow functions over `function` declarations.
-- Template literals over string concatenation.
+- No unused imports.
 - Blank lines separate logical sections; decorative separator comments (`// ─────────`) stay out.
 
 ## Language
@@ -29,9 +26,9 @@ The formatter and linter config is the authority; these are the conventions it e
 - Self-documenting code over comments: clear naming, pure functions, obvious control flow.
 - **No section-label comments** (`// Types`, `// Pure functions`, `// Imports`). The code order speaks for itself.
 
-### When to add JSDoc
+### When to add a doc comment
 
-Add JSDoc to an exported item when **any** of these is true:
+Add a doc comment (JSDoc, PHPDoc …) to an exported item when **any** of these is true:
 
 - Parameters aren't self-evident from their types (a `duration` param: what unit? what happens at 0?)
 - The function has non-obvious constraints or behaviour (serialization limits, a required context, a side-effect contract)
@@ -65,11 +62,11 @@ export const processFile = async (path: string): Promise<void> => {
 
 The UI framework is a **replaceable adapter layer**, not where domain logic lives. Keep business logic framework-free so the framework stays swappable and the logic stays unit-testable without a component harness.
 
-- **Domain logic lives in framework-free `.ts` modules** — calculations, validation, state machines, mapping, formatting. These modules import nothing from the UI framework.
+- **Domain logic lives in framework-free modules** — calculations, validation, state machines, mapping, formatting. These modules import nothing from the UI framework.
 - **Components consume logic, they don't contain it.** A component body wires state to pure functions; a derived value that grows past trivial derivation becomes a pure function the component calls.
 - **Backend logic never touches the frontend framework.**
 
-**Litmus test:** if swapping the framework would force you to rewrite a `.ts` file that has no UI in it, that file has leaked framework coupling — extract the logic.
+**Litmus test:** if swapping the framework would force you to rewrite a source file that has no UI in it, that file has leaked framework coupling — extract the logic.
 
 ## Code Reuse
 
@@ -101,24 +98,24 @@ Apply these checks to **your own output** before presenting it, and fix violatio
 
 Before editing a file that might be generated:
 
-1. **Check `package.json` scripts** for `gen`, `generate`, `codegen`.
+1. **Check the project's scripts** (`package.json`, `composer.json`, `Makefile`) for `gen`, `generate`, `codegen`.
 2. **Run the generator** instead of editing by hand; a generated file is overwritten on the next run.
 
 ## Validation & Types
 
-- Zod for schemas, with types inferred via `z.infer`.
+- The project's schema library for schemas, with types derived from the schema.
 - Validation lives once, at the boundary, not again in every layer.
-- Strict typing; `unknown` and a parse over `any`.
-- Zod v4 top-level API: `z.uuid()`, `z.email()`, `z.url()`, `z.iso.datetime()`, `.loose()` — not the deprecated v3 chains (`z.string().uuid()`, `.passthrough()`).
+- Strict typing; an unknown value is parsed at the boundary, never typed as "anything".
+- Read the installed version of the schema library before writing against it.
 
 ### A fixed vocabulary is a typed constant
 
-Roles, modes, statuses, channels: every closed set of values has **one** `as const` object next to its type, and every comparison, option id and schema literal reads from it.
+Roles, modes, statuses, channels: every closed set of values has **one** constant next to its type (an `as const` object, an enum, a class constant), and every comparison, option id and schema literal reads from it.
 
-TypeScript already checks a literal against a union inside the core. The constant earns its place at the **seams where a `string` arrives**: a query parameter, a form option id, a row read from the database. There a literal comparison is unchecked, and its usual companion — `mode === 'per_km' ? 'per_km' : 'tiers'` — maps every unknown value to a default in silence.
+A type checker already checks a literal against the closed set inside the core. The constant earns its place at the **seams where a `string` arrives**: a query parameter, a form option id, a row read from the database. There a literal comparison is unchecked, and its usual companion — `mode === 'per_km' ? 'per_km' : 'tiers'` — maps every unknown value to a default in silence.
 
 ```ts
-// ✅ the constant is the vocabulary; a guard narrows the string, an unknown value is refused
+// ✅ (TypeScript shown) the constant is the vocabulary; a guard narrows the string, an unknown value is refused
 export const FEE_MODE = { tiers: 'tiers', perKm: 'per_km' } as const
 export type FeeMode = (typeof FEE_MODE)[keyof typeof FEE_MODE]
 export const isFeeMode = (value: string): value is FeeMode =>
@@ -130,7 +127,7 @@ if (isFeeMode(id)) handleChange(switchMode(form, id))
 mode: id === 'per_km' ? 'per_km' : 'tiers'
 ```
 
-Derive the schema from the constant (`z.literal(FEE_MODE.perKm)`), never the other way round, so the constant, the type and the parser cannot disagree. Test fixtures may spell the literal.
+Derive the schema from the constant (a literal built from `FEE_MODE.perKm`), never the other way round, so the constant, the type and the parser cannot disagree. Test fixtures may spell the literal.
 
 ## Database Writes
 
@@ -151,7 +148,7 @@ The lesson behind this rule: order numbers drawn from a truncated clock collided
 
 ### Generated identifiers carry entropy, never a clock
 
-A value drawn from the clock is a bucket, not an identifier, and truncating it widens the bucket. Draw from `crypto.getRandomValues`, keep the drawing in a **pure function** that takes the random values as an argument, and unit-test it. A generator whose only seam is a server function with a database call in it is a generator no test reaches.
+A value drawn from the clock is a bucket, not an identifier, and truncating it widens the bucket. Draw from the platform's CSPRNG (`crypto.getRandomValues`, `random_bytes`), keep the drawing in a **pure function** that takes the random values as an argument, and unit-test it. A generator whose only seam is a server function with a database call in it is a generator no test reaches.
 
 ## External Measurements
 

package/kit/rules/rules/kit/testing.md

@@ -9,24 +9,12 @@ All new or changed code **must** have tests.
 | Setting      | Value                                          |
 | ------------ | ---------------------------------------------- |
 | Runner       | `{{kit.command.test}}`                         |
-| File naming  | `*.test.ts` co-located next to the source file |
-| E2E runner   | Playwright                                     |
+| File naming  | the name and place the runner finds; follow where the project's existing tests live |
+| E2E runner   | Playwright, or the project's own               |
 
-### `EMFILE` / `ProcessFdQuotaExceeded` while dev servers run
+### Run the tests where the runner can see the project's config
 
-With watch processes active, `bun test` from the **workspace root** can fail before running a single test with `EMFILE` / `ProcessFdQuotaExceeded` (`Cannot read file ".../tsconfig.json": EMFILE`). The watchers exhaust the kernel's global descriptor table, so Bun cannot open its config. **This is an environment condition, not a test failure** — the run reports `0 pass / 1 error`. Raising `ulimit -n` does not help; the exhaustion is system-wide.
-
-**Workaround: `cd` into the package or module directory and run the tests there.** From a narrow directory Bun scans only that subtree. Leave the user's dev servers running; for a full-suite run that genuinely needs the root, stop them with the user's consent.
-
-### Run from the package root, not below it
-
-Bun resolves `tsconfig.json` from the **working directory**, and that is where it reads `jsxImportSource`. Descend below a package root and any `.tsx` a test pulls in compiles against React's JSX runtime. The failure does not name JSX:
-
-```
-error: Cannot find module 'react/jsx-dev-runtime' from '.../components/area-chart/index.tsx'
-```
-
-**Read the failure before calling it a broken test.** It arrives as an "unhandled error between tests" with a module-resolution message, so it reads like a missing dependency in code nobody touched. Re-run from the package root first. Re-running the same wrong invocation with the changes stashed reproduces it identically and proves nothing.
+A runner started from the wrong directory can fail before it runs a test: a watcher exhausting file descriptors, a config file or compiler setting resolved from the working directory and not found. **Read the failure before calling it a broken test** — an environment error reads like a missing dependency in code nobody touched, and re-running the same wrong invocation with the changes stashed proves nothing. Run from the package or module directory the config lives in, and leave the user's dev servers running. Where the project has its own testing rule, it names the failures its runner shows.
 
 ## What to Test (decision tree)
 
@@ -65,20 +53,11 @@ Write tests in this order — stop when coverage expectations are met:
 
 1. **Unit tests** — pure functions, validators, mappers
 2. **Integration tests** — service interactions, database operations
-3. **E2E tests** — user flows via Playwright (only when requested)
-
-## `mock.module()` replaces a module for the whole file
+3. **E2E tests** — user flows via the E2E runner (only when requested)
 
-`mock.module()` replaces the module **globally for the entire test file** — every import, including transitive ones.
+## Mock only the lowest-level dependency
 
-**Mock only the lowest-level dependency** (adapters, repositories). The use-case logic still runs; only I/O is stubbed. Mocking an intermediate module (a use-case in a handler test) breaks every other test in that file that imports it.
-
-```typescript
-// ✅ Mock only the adapter
-mock.module('../adapters', () => ({
-  auditRepo: { insert: mock(() => Promise.resolve()) },
-}))
-```
+**Mock only the lowest-level dependency** (adapters, repositories). The use-case logic still runs; only I/O is stubbed. Where the runner's mock replaces a whole module, it does so for the entire file, so mocking an intermediate module (a use-case in a handler test) breaks every other test there. Where the project has its own testing rule, it names the mocking call of its runner.
 
 ## Before every commit
 

package/kit/workflow/skills/implement/SKILL.md

@@ -44,7 +44,7 @@ Before you write a single line:
 
 0. A phase not yet in the plan gets its skeleton there first (heading, origin, tasks, review gate), before any research, so the herd never shows it as missing.
 1. Search with `Grep` / `Glob` / `Read` for existing utilities, components and domain types that cover 80%+ of the need. For deeper research dispatch an `explore` subagent.
-2. Check `package.json` for `gen` / `generate` / `codegen` scripts and run the generator for a generated file instead of editing it.
+2. Run the generator for a generated file instead of editing it (`.claude/rules/kit/code-style.md` → Generators).
 
 ## Step 2: Implement
 
@@ -65,11 +65,11 @@ After each changed file:
 
 ## Step 4: Write Tests
 
-Follow the decision tree in `.claude/rules/kit/testing.md`. Test files sit next to the source; run them with `{{kit.command.test}}`. For changes in a shared package, also run the tests of the packages that consume it.
+Follow the decision tree in `.claude/rules/kit/testing.md`. Name and place test files as `.claude/rules/kit/testing.md` → Runner & File Placement says; run them with `{{kit.command.test}}`. For changes in a shared package, also run the tests of the packages that consume it.
 
 ## Step 4b: Look at It
 
-A change a user sees — a page, a route, a redirect, a printed document — is looked at in the running app before `/pre-commit`. Unit tests prove the pieces; only the running app proves they meet. Use a temporary end-to-end spec (Playwright) or the browser, take a screenshot per state, and report what each shows. Delete the temporary spec before the commit unless the plan asks for an end-to-end test.
+A change a user sees — a page, a route, a redirect, a printed document — is looked at in the running app before `/pre-commit`. Unit tests prove the pieces; only the running app proves they meet. Use a temporary end-to-end spec (Playwright or the project's E2E runner) or the browser, take a screenshot per state, and report what each shows. Delete the temporary spec before the commit unless the plan asks for an end-to-end test.
 
 No visible change (a domain package, a migration, a service) → skip, and say so in the report.