jackherd 1.16.0 → 1.18.0

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

@@ -9,16 +9,23 @@ const LANE_DIRECTORY = /^(?!\.{1,2}$)[A-Za-z0-9._-]+$/
 
 const strings = (values: unknown[]): string[] => values.filter((value): value is string => typeof value === 'string')
 
+/** The objects of a list, or none when it is no list: the questions of a dialog, the options of a question. */
+export const recordsOf = (values: unknown): Record<string, unknown>[] =>
+  Array.isArray(values) ? values.filter(isRecord) : []
+
+/** The questions of an `AskUserQuestion` input; none when it is no object or has no list of them. */
+export const questionsOf = (toolInput: unknown): Record<string, unknown>[] =>
+  isRecord(toolInput) ? recordsOf(toolInput.questions) : []
+
 const optionTexts = (options: unknown): string[] =>
-  Array.isArray(options) ? options.filter(isRecord).flatMap((option) => strings([option.label, option.description])) : []
+  recordsOf(options).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)])
-}
+export const dialogTextsOf = (toolInput: unknown): string[] =>
+  questionsOf(toolInput).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[] => [

package/kit/hooks/hooks/shared/standing-mark.ts

@@ -0,0 +1,104 @@
+/**
+ * A standing approval: the user's answer to a dialog whose question carries ``<Key> `<subject>` <until> <YYYY-MM-DD HH:MM>``
+ * lifts a question about that subject until that moment, at most 24 hours after the answer. The key names what is
+ * approved (`Plan` for the merges of a plan's lanes, `Environment` for the calls against an environment), so two kinds
+ * never read each other's questions. The newest answer to a question naming the subject decides; any other label ends
+ * the approval, also on a question without an end: in doubt it ends.
+ */
+import type { DialogAnswer } from './dialog-answer'
+import { MS_PER_MINUTE } from './fresh'
+import { newestVerdict } from './newest-verdict'
+
+/** The exact option label that approves, and the word before the end in the question, both per response language. */
+export type StandingLabels = { approve: string; until: string }
+
+/** What a kind of standing approval is about: the word before the subject, and which subjects it accepts. */
+export type StandingKind = { key: string; isSubject: (subject: string) => boolean }
+
+/** A subject approved until `until`, in milliseconds. */
+export type StandingMark = { subject: string; until: number }
+
+export const MAX_STANDING_MINUTES = 24 * 60
+
+const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/** A local moment from its parts; undefined for one the calendar or the clock does not have (Feb 30, 24:00, a DST gap). */
+const localMoment = ([year, month, day, hour, minute]: number[]): number | undefined => {
+  const date = new Date(year, month - 1, day, hour, minute)
+  const exact =
+    date.getFullYear() === year &&
+    date.getMonth() === month - 1 &&
+    date.getDate() === day &&
+    date.getHours() === hour &&
+    date.getMinutes() === minute
+  return exact ? date.getTime() : undefined
+}
+
+/** The subject and the end a question names as ``<Key> `<subject>` <until> YYYY-MM-DD HH:MM``; none for none or several. */
+export const standingMarkOf = (question: string, kind: StandingKind, until: string): StandingMark | undefined => {
+  if (until === '') return undefined
+  const pattern = `\\b${escapeRegExp(kind.key)} \`([^\`]*)\` ${escapeRegExp(until)} (\\d{4})-(\\d{2})-(\\d{2}) (\\d{2}):(\\d{2})(?!\\d)`
+  const marks = [...question.matchAll(new RegExp(pattern, 'g'))]
+  if (marks.length !== 1) return undefined
+  const [, subject, ...parts] = marks[0]
+  const end = localMoment(parts.map(Number))
+  return end !== undefined && kind.isSubject(subject) ? { subject, until: end } : undefined
+}
+
+/** The one subject a question names as ``<Key> `<subject>` ``, with or without an end; none for none or several. */
+const namedSubjectOf = (question: string, kind: StandingKind): string | undefined => {
+  const mention = new RegExp(`\\b${escapeRegExp(kind.key)} \`([^\`]*)\``, 'g')
+  const subjects = new Set([...question.matchAll(mention)].map(([, subject]) => subject))
+  const [only] = subjects
+  return subjects.size === 1 && kind.isSubject(only) ? only : undefined
+}
+
+/**
+ * The subject an answer speaks about, and the end its question names; `NaN` for a question that names the subject
+ * without an end, which never approves but, answered with anything else, ends the approval: in doubt it ends.
+ */
+const markOf = (question: string, kind: StandingKind, until: string): StandingMark | undefined => {
+  const mark = standingMarkOf(question, kind, until)
+  if (mark !== undefined) return mark
+  const subject = namedSubjectOf(question, kind)
+  return subject === undefined ? undefined : { subject, until: Number.NaN }
+}
+
+type MarkedAnswer = DialogAnswer & { mark: StandingMark }
+
+const approves = ({ answer, offered, answeredAt, mark }: MarkedAnswer, label: string): boolean =>
+  label !== '' &&
+  answer === label &&
+  offered.includes(label) &&
+  mark.until > answeredAt &&
+  mark.until - answeredAt <= MAX_STANDING_MINUTES * MS_PER_MINUTE
+
+/** The approval the newest answers about one subject give: all of them approve, and the earliest end is still ahead. */
+const grantOf = (subject: string, answers: readonly MarkedAnswer[], label: string, now: number): StandingMark[] => {
+  const verdict = newestVerdict(answers, now)
+  if (verdict.length === 0 || !verdict.every((answer) => approves(answer, label))) return []
+  const until = Math.min(...verdict.map(({ mark }) => mark.until))
+  return until > now ? [{ subject, until }] : []
+}
+
+/** The subjects of this kind the user approved standing in these dialog answers, and until when; only those holding at `now`. */
+export const standingGrants = (
+  answers: readonly DialogAnswer[],
+  kind: StandingKind,
+  labels: StandingLabels,
+  now: number,
+): StandingMark[] => {
+  const marked = answers.flatMap((answer): MarkedAnswer[] => {
+    const mark = markOf(answer.question, kind, labels.until)
+    return mark === undefined ? [] : [{ ...answer, mark }]
+  })
+  const subjects = [...new Set(marked.map(({ mark }) => mark.subject))]
+  return subjects.flatMap((subject) =>
+    grantOf(
+      subject,
+      marked.filter(({ mark }) => mark.subject === subject),
+      labels.approve,
+      now,
+    ),
+  )
+}

package/kit/hooks/hooks.json

@@ -3,7 +3,7 @@
     "event": "PermissionRequest",
     "handler": {
       "type": "command",
-      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/approval-gate/index.ts '{{kit.approval.allow}}' '{{kit.approval.deny}}' '{{kit.approval.pending}}' '{{kit.approval.denied}}'",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/approval-gate/index.ts '{{kit.approval.allow}}' '{{kit.approval.deny}}' '{{kit.approval.pending}}' '{{kit.approval.denied}}' '{{kit.guard.standingApproval.approve}}' '{{kit.guard.standingApproval.until}}'",
       "timeout": 600
     }
   },
@@ -34,6 +34,15 @@
       "onFailure": "block"
     }
   },
+  "lane-start-guard": {
+    "event": "PreToolUse",
+    "matcher": "Bash",
+    "handler": {
+      "type": "command",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && { input=$(cat); case \"$input\" in *herdr*) printf '%s' \"$input\" | bun .claude/hooks/lane-start-guard/index.ts;; esac; }",
+      "timeout": 10
+    }
+  },
   "merge-guard": {
     "event": "PreToolUse",
     "matcher": "Bash",
@@ -74,7 +83,7 @@
     "matcher": "AskUserQuestion",
     "handler": {
       "type": "command",
-      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/plain-question/index.ts",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/plain-question/index.ts '{{kit.question.recommended}}' '{{kit.approval.allow}}' '{{kit.approval.deny}}' '{{kit.guard.selfMergeLabel}}' '{{kit.guard.standingApproval.approve}}'",
       "timeout": 10
     }
   },

package/kit/review/agents/skill-review.md

@@ -8,11 +8,11 @@ user-invocable: false
 
 Read `.claude/rules/kit/writing-for-agents.md` first, then the project's `.claude/rules/writing-for-agents.md` if it exists, then `.claude/project/skill-review.md` if it exists. They carry the levers this review applies; the project files win where they disagree with the kit.
 
-You receive the `git diff` of agent texts: skills, agents, rules, project supplements, `CLAUDE.md`, `AGENTS.md`. Judge only the lines the diff adds, changes or removes, a moved passage where its trigger or rung changed; the rest of a file is context. A budget, a broken link, a required rule and a trigger in the first lines are measured by `jh check`, so leave them to it.
+You receive the `git diff` of agent texts: skills, agents, rules, project supplements, `CLAUDE.md`, `AGENTS.md`. Judge only the lines the diff adds, changes or removes, a moved passage where its trigger or rung changed; the rest of a file is context. A budget, a broken link, a required rule and a trigger in the first lines are measured by `jh check`, so leave them to it. Length: a finding when the diff takes a file over its target or grows one already over, per the `hint:` lines of the `Skill budgets` result /pre-commit passes; that result missing is a finding. `jh check` measures `Lint pointers`; lens 7 judges what its patterns miss.
 
 ## What is a finding
 
-Check every changed passage against each lens; a passage that passes all six needs no row.
+Check every changed passage against each lens; a passage that passes all seven needs no row.
 
 1. **No-op:** the sentence changes nothing against what the model does by default. Delete the sentence, never trim it.
 2. **Same meaning twice:** the passage restates, in other words, what the skill, its project supplement, a rule, `CLAUDE.md` or a memory file the caller names already carries. Grep for the key terms before you call it new; name the other place. A passage removed in favour of a pointer is lost when the target lacks part of it.
@@ -20,6 +20,7 @@ Check every changed passage against each lens; a passage that passes all six nee
 4. **Late trigger:** a pointer to a reference or another document names its condition after the content, or fires at a moment the agent has already passed.
 5. **Negation:** the passage steers by prohibition where a target could be stated; a hard guardrail stays, paired with its target.
 6. **Open step:** a step ends without a condition the agent can check, so done and not done look alike.
+7. **Lint-shaped prose:** a rule the project's linter can check, without a `lint:` pointer. Propose the lint rule plus the pointer.
 
 ## Output
 

package/kit/review/skills/pre-commit/SKILL.md

@@ -13,42 +13,38 @@ You are the **Pre-Commit Orchestrator**. You measure what a command can measure,
 bunx jackherd check
 ```
 
-One command answers everything a command can answer, and **its output is the evidence for steps 1, 3 and 4** — the changed files (including untracked ones), the affected package roots, which reviewers the changed paths call for, which files a generator owns, staged build artifacts, lint over the changed files, types and tests per package root, and the project's own checks. All of it is configured in the `check` block of `.jackherd/config.json`.
+Its output is **the evidence for steps 1, 3 and 4**: the changed files (untracked included), the affected package roots, the reviewers the changed paths call for, the files a generator owns, staged build artifacts, lint, types and tests per package root, and the project's own checks (the `check` block of `.jackherd/config.json`).
 
-**Quote its results; restate nothing from your own reading of the diff.** A verdict about type errors, passing tests or lint that was not measured is a guess, and the failure mode is a confident false PASS. Where the command says `❌`, the summary says FIX FIRST.
+**Quote its results; restate nothing from your own reading of the diff.** An unmeasured verdict is a guess, and its failure mode is a confident false PASS. Where the command says `❌`, the summary says FIX FIRST.
 
 `--skip-slow` drops types and tests. Use it only when the user asks for a quick pass, and say so in the summary.
 
 ## Step 2: Judgement Review
 
-Run `/review` for what the command cannot decide: dead exports, naming, function size, the design review. The measured points are already settled above.
+Run `/review` for what the command cannot decide: dead exports, naming, function size, the design review.
 
 ## Step 3: Specialized Reviewers
 
-**Step 1 printed the reviewer list** (`Reviewers: …`, from `check.reviewerRoutes`, plus `check.publicContent` and `skill-review` for changed agent texts) — dispatch exactly those, each as a subagent via the `Agent` tool with its `subagent_type`:
+**Step 1 printed the reviewer list** (`Reviewers: …`) — dispatch exactly those, each as a subagent via the `Agent` tool with its `subagent_type`:
 
-- Pass in the `prompt`: the `git diff` of the relevant files and the file paths.
+- Pass the `git diff` of the relevant files and their paths; to `skill-review`, also the `Skill budgets` and `Lint pointers` results of the latest `jh check` run.
 - Start all of them **in parallel**, in a single message, and wait for every result before step 4.
 
-`security-audit` has a judgement half: add it when the diff *does* something security-relevant in a path no route lists — auth middleware, API key handling, a schema at an HTTP endpoint, a raw database query, an access policy.
+Add `security-audit` when the diff *does* something security-relevant in a path no route lists: auth middleware, API key handling, a schema at an HTTP endpoint, a raw database query, an access policy.
 
-**`spec-review` starts in the same message.** It reviews a different axis, not different files, so it applies regardless of which paths changed. Pass it the full `git diff`, the commit list (`git log <base>..HEAD --oneline`, base `{{kit.baseBranch}}`), the base ref and the branch name.
+**`spec-review` starts in the same message.** It applies whichever paths changed. Pass it the full `git diff`, the commit list (`git log <base>..HEAD --oneline`, base `{{kit.baseBranch}}`), the base ref and the branch name.
 
 ## Step 4: Generated Files
 
-Step 1 lists the changed files a generator owns and names the generator. A regenerated file lands in the diff the same way as a hand-edited one, so the judgement is whether this one came from the generator. Ask when it looks hand-edited.
+Step 1 lists the changed files a generator owns. Ask when one looks hand-edited rather than regenerated.
 
 ## Step 5: Spec Alignment
 
-Take the `spec-review` result. Steps 2 and 3 ask whether the code is written well (**Standards**); this one asks whether it does what was asked (**Spec**). Report the two side by side, each under its own heading, so neither masks the other.
+Steps 2 and 3 judge whether the code is written well (**Standards**), `spec-review` whether it does what was asked (**Spec**). Report the two side by side, each under its own heading.
 
-## Step 6: arc42 Check
+## Step 6: arc42 and Architecture
 
-Apply the filter in `.claude/rules/kit/arc42.md` to the changed files. On a hit, **ask the user concretely**. No hit for bug fixes, styling, small UI changes, or refactorings without decision character.
-
-## Step 7: Architecture Check
-
-For changes in a service, a domain package or a data layer, apply the filter in `.claude/rules/kit/architecture-files.md`. On a hit, **ask the user concretely** whether the unit's `ARCHITECTURE.md` needs an update.
+Apply the filter in `.claude/rules/kit/arc42.md` to the changed files; for a service, a domain package or a data layer, also the one in `.claude/rules/kit/architecture-files.md`. On a hit, **ask the user concretely**. No hit for bug fixes, styling or refactorings without decision character.
 
 ## Output Format
 
@@ -75,19 +71,17 @@ Active reviewers: Review + Spec + [routed reviewers]
 ### Verdict: COMMIT / FIX FIRST
 ```
 
-On FIX FIRST, apply what a tool fixes on its own — formatting (`{{kit.command.format}}` or the formatter on the file), lint auto-fixes — then **re-run `bunx jackherd check` and quote the new result.** A fix is verified by the command that found the problem.
-
-A second review round after fixes dispatches only the reviewers whose findings were applied, plus the reviewers of any path the fixes newly touched (the reviewer list of the new `check` run); `jh check` itself always runs in full.
+On FIX FIRST, apply what a tool fixes on its own (`{{kit.command.format}}`, lint auto-fixes), then re-run `bunx jackherd check` and quote the new result. A second review round dispatches only the reviewers whose findings were applied, plus those of any path the fixes newly touched; `jh check` always runs in full.
 
-Architecture problems, missing tests, domain logic errors and **every Spec finding** are reported for the user to decide: whether a requirement was dropped on purpose or the scope grew deliberately is the user's call.
+Architecture problems, missing tests, domain logic errors and **every Spec finding** are reported for the user to decide: a dropped requirement or a grown scope is the user's call.
 
 ## Commit
 
 On COMMIT, propose a Conventional Commit message (`type(scope): description`, imperative, subject at most 72 characters; the body explains cause and consequence in prose).
 
-Ask the commit question with the `AskUserQuestion` tool, as a clickable choice in {{kit.responseLanguage}}: commit with this message / adjust the message / cancel.
+Ask the commit question with the `AskUserQuestion` tool, in {{kit.responseLanguage}}: commit with this message / adjust the message / cancel.
 
-On confirmation, write the message to a file in your scratchpad with the `Write` tool, stage **the files step 1 listed** by name, and commit from the file:
+On confirmation, write the message to a file in your scratchpad with the `Write` tool, stage **the files step 1 listed** by name, and commit from the file, each as one Bash call:
 
 ```bash
 git add -- "<path from step 1>" "<path from step 1>"
@@ -97,4 +91,4 @@ git add -- "<path from step 1>" "<path from step 1>"
 git commit -F "<message file>"
 ```
 
-Each is one Bash call: a chained command cannot be approved as one (Claude Code docs, page "Configure permissions", section "Compound commands"). Staging by name keeps unreviewed files out of the commit. A message file reaches git untouched; passed through the shell (`-m "…"` or a heredoc), the backticks and `$(…)` a commit body quotes could run as commands. Let the repository's own commit hooks run.
+A chained command cannot be approved as one; a message passed through the shell (`-m "…"`, a heredoc) can run the backticks and `$(…)` it quotes. Let the repository's own commit hooks run.

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

@@ -1,32 +1,29 @@
 # Code Style
 
-The kit's core. Project-specific conventions (UI framework, shared component library, class utilities) live in the project's own rules beside `.claude/rules/kit/`; where they are stricter, they win.
+The kit's core. Project-specific conventions (UI framework, shared component library, class utilities) live in the project's own rules beside `.claude/rules/kit/`; where they are stricter, they win. Where the project's own rule names a `lint:<rule id>` for a rule below, the linter's message is the authority.
 
 ## Formatting
 
 The formatter and linter config is the authority; where it is silent, match the surrounding code.
 
 - No unused imports.
-- Blank lines separate logical sections; decorative separator comments (`// ─────────`) stay out.
+- Blank lines separate sections; no decorative separator comments.
 
 ## Language
 
 - **All code in English**: file names, identifiers, type and component names, comments. User-facing strings go through the project's i18n system.
 - **Commit messages in English**, subject and body. The subject is a Conventional Commit (`fix(scope): …`); the body explains cause and consequence in prose.
 - **Plans and ADRs** are written in {{kit.planLanguage}}.
-- **Replies to the user** are in {{kit.responseLanguage}}, addressing the user with {{kit.responseAddress}}. That holds for every answer, every question and every report to the user; it does not change what is written into code, commits or plans.
+- **Replies to the user** are in {{kit.responseLanguage}}, addressing the user with {{kit.responseAddress}}: every answer, question and report. Code, commits and plans keep their own language.
 
 ## Naming
 
-- **No abbreviations in variable names**: `scrollElement`, not `scrollEl`; `domObserver`, not `mo`. Established exceptions: `i`/`j` in tight loops, `el` in single-line callbacks, `err` in catch blocks. When in doubt, spell it out.
-- Keep naming aligned with the existing conventions and folder structure.
+**No abbreviations in variable names**: `scrollElement`, not `scrollEl`. Established exceptions: `i`/`j` in tight loops, `el` in single-line callbacks, `err` in catch blocks.
 
 ## Comments & Documentation
 
 - 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 a doc comment
+- **No section-label comments** (`// Types`, `// Imports`): the code order speaks for itself.
 
 Add a doc comment (JSDoc, PHPDoc …) to an exported item when **any** of these is true:
 
@@ -34,7 +31,7 @@ Add a doc comment (JSDoc, PHPDoc …) to an exported item when **any** of these
 - The function has non-obvious constraints or behaviour (serialization limits, a required context, a side-effect contract)
 - It has edge cases or a subtle contract a caller could easily violate
 
-A well-named function with typed parameters documents itself; one-liners that state the obvious (`/** Returns the sum */`) are noise.
+A one-liner that states the obvious (`/** Returns the sum */`) is noise.
 
 ## Code Organization
 
@@ -44,51 +41,34 @@ A well-named function with typed parameters documents itself; one-liners that st
 2. **Pure functions**: no side effects, no I/O, predictable outputs
 3. **Higher-order functions**: functions that create side effects, orchestrate I/O, or compose other functions
 
-```typescript
-import { foo } from './bar'
-
-export type Config = { ... }
-
-const parse = (input: string): Config => { ... }
-const validate = (config: Config): boolean => { ... }
-
-export const processFile = async (path: string): Promise<void> => {
-  const config = parse(await readFile(path))
-  if (validate(config)) await saveResult(config)
-}
-```
-
 ## Framework as an Adapter, not Domain
 
-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.
+The UI framework is a **replaceable adapter layer**, so the logic stays unit-testable without a component harness.
 
 - **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.
+- **Components consume logic, they don't contain it.** 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 source 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, extract the logic.
 
 ## Code Reuse
 
-**Before implementing new functionality:**
-
-1. **Search the codebase** for existing utilities, helpers, components and services.
+1. **Search the codebase** for existing utilities, helpers, components and services before implementing.
 2. **Reuse > reinvent**: if something does 80% of what you need, use it and extend it.
-3. **One copy of each piece of logic**: extract and reuse.
-4. **Shared placement**: generic helpers (formatters, validators) belong in the nearest shared module, not in a feature file. If more than one module could use it, it is shared.
+3. **One copy of each piece of logic**; a helper more than one module could use belongs in the nearest shared module.
 
-For UI: check the shared component library before building a button, input, modal or similar. Build a custom one only when the shared one is fundamentally incompatible, and write down why.
+For UI: check the shared component library first. Build a custom one only when the shared one is fundamentally incompatible, and write down why.
 
 ## Design Review (Clean Code)
 
 After implementing, review every changed file through these lenses:
 
-1. **Single Responsibility**: each function/module does one thing. If a description needs "and", split it.
+1. **Single Responsibility**: if a description needs "and", split it.
 2. **DRY**: more than 3 identical lines in two places → shared helper.
 3. **Dead code**: remove unused exports, unreachable branches, commented-out code.
-4. **Naming**: names reveal intent. If you need a comment to explain what a variable holds, rename it.
-5. **Small functions**: functions over ~20 lines are a smell; extract named sub-steps. Where the linter measures cognitive complexity, every `&&`, `||`, `??`, ternary and optional chain counts; extracting a named helper gives it its own budget, extracting a variable does not.
-6. **Dependency direction**: pure utilities never import side-effectful modules. Arrows point inward.
+4. **Naming**: if you need a comment to explain what a variable holds, rename it.
+5. **Small functions**: over ~20 lines is a smell; extract named sub-steps. Where the linter measures cognitive complexity, every `&&`, `||`, `??`, ternary and optional chain counts; a named helper gets its own budget, a variable does not.
+6. **Dependency direction**: pure utilities never import side-effectful modules.
 7. **No flag arguments**: a boolean that switches behaviour → two functions.
 8. **Error surface**: handle only errors you can meaningfully recover from; let the rest propagate.
 
@@ -96,26 +76,20 @@ Apply these checks to **your own output** before presenting it, and fix violatio
 
 ## Generators
 
-Before editing a file that might be generated:
-
-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.
+Before editing a file that might be generated, check the project's scripts (`package.json`, `composer.json`, `Makefile`) for `gen`, `generate`, `codegen`. **Run the generator** instead of editing by hand; the next run overwrites a hand edit.
 
 ## Validation & Types
 
 - 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; an unknown value is parsed at the boundary, never typed as "anything".
+- Validation lives once, at the boundary; an unknown value is parsed there, 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** 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.
-
-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.
+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. It earns its place at the **seams where a `string` arrives** (a query parameter, a form option id, a database row), where a literal comparison is unchecked:
 
 ```ts
-// ✅ (TypeScript shown) the constant is the vocabulary; a guard narrows the string, an unknown value is refused
+// ✅ 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 =>
@@ -127,31 +101,29 @@ if (isFeeMode(id)) handleChange(switchMode(form, id))
 mode: id === 'per_km' ? 'per_km' : 'tiers'
 ```
 
-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.
+Derive the schema from the constant, never the other way round. Test fixtures may spell the literal.
 
 ## Database Writes
 
 ### Never `upsert` on a generated natural key
 
-`upsert(row, { onConflict: '<natural key>' })` means "write into whichever row already holds that key" — and when the key was generated rather than supplied by the caller, that row belongs to someone else.
-
-The lesson behind this rule: order numbers drawn from a truncated clock collided for orders created within the same second, and an upsert on that number merged two customers' orders into one row — one name, both carts, the other order gone. The unique index was in place the whole time; the upsert asked it not to complain.
+`upsert(row, { onConflict: '<natural key>' })` writes into whichever row already holds that key; when the key was generated, that row belongs to someone else. Order numbers drawn from a truncated clock collide within one second, and an upsert on them merges two customers' orders into one row.
 
 - **Create and update are separate statements.** `insert` for new rows, `update … where key = ?` for known ones.
 - **Scope an update by tenant as well as by key**, so a key replayed from a URL cannot reach another tenant's row.
-- **An update that matches nothing is an error, not an insert.** Silently creating a row from an unmatched identifier turns a query parameter into a write primitive.
+- **An update that matches nothing is an error, not an insert.**
 - An upsert stays legitimate where the conflict target is a key the **caller owns** and the merge is the intent (a client-generated id, a per-user settings row).
 
 ### A pre-flight existence check is not uniqueness
 
-`SELECT count(*) WHERE key = ?` followed by an insert leaves a gap between two statements, and concurrent writers sit in it. **The unique index is the guarantee: insert against it and retry on the unique-violation error.** When retrying, **name the column** — a table with several unique indexes will otherwise answer a duplicate in another column by burning fresh values until the attempts run out.
+A `SELECT` before an insert leaves a gap concurrent writers sit in. **The unique index is the guarantee: insert against it and retry on the unique-violation error.** When retrying, **name the column**, or a duplicate in another unique column burns fresh values until the attempts run out.
 
 ### 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 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.
+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.
 
 ## External Measurements
 
 ### Normalised to whole units at the adapter, like money to cents
 
-A routing provider answers in fractional metres and seconds, a payment provider in decimal currency. The adapter that receives the value rounds it **once**, to the unit the domain counts in (whole metres, whole seconds, whole cents), and nothing past the adapter rounds again. Two callers rounding for themselves round differently, or one forgets — and a billing boundary sits between them. The domain core may keep a defensive rounding as a guarantee against callers that are not the adapter; the adapter is where the rounding is decided, and its contract says so.
+The adapter that receives a fractional measurement (metres, seconds, currency) rounds it **once**, to the unit the domain counts in, and nothing past the adapter rounds again: two callers rounding for themselves round differently, and a billing boundary sits between them. The domain core may keep a defensive rounding as a guarantee against callers that are not the adapter; the adapter's contract says where the rounding is decided.

package/kit/rules/rules/kit/pull-requests.md

@@ -1,62 +1,39 @@
 # Pull Requests
 
-How an agent opens a pull request so every PR reads consistently and is review- and deploy-ready. Applies whenever you run `gh pr create` or edit a PR body.
+Applies whenever you run `gh pr create` or edit a PR body.
 
 ## Preconditions
 
 - **Open a PR only when the user asks.** Same rule as commit and push.
-- **Base = `{{kit.baseBranch}}`** unless the user names another.
-- **Work on a branch.** If the working branch is `{{kit.baseBranch}}`, branch first.
-- **Push before creating, with the user's go-ahead for the push.** The head branch must be on the remote so `gh pr create` has a target.
+- **Base = `{{kit.baseBranch}}`** unless the user names another; on `{{kit.baseBranch}}` itself, branch first.
+- **Push before creating, with the user's go-ahead for the push.**
 - **Drafts** (`merge.openAsDraft`: **{{kit.merge.openAsDraft}}**). When `on`, open every PR with `gh pr create --draft`; run `gh pr ready <n>` before handing it to the user to merge, or before waiting on its checks for your own `gh pr merge`.
-- **Check for an existing PR first** (`gh pr view <branch>`). If a prior PR for the same branch is already **merged**, the new one is a continuation — mark it in the title.
+- **Check for an existing PR first** (`gh pr view <branch>`). If a prior PR for the same branch is already **merged**, the new one is a continuation.
 
 ## Title
 
-Conventional-commit shape, imperative, lower-case summary, no trailing period:
+`type(scope): short imperative summary`, lower case, no trailing period.
 
-```
-type(scope): short imperative summary
-```
-
-- `type` ∈ `feat | fix | refactor | perf | docs | test | chore | build | ci`. Pick the type of the PR's **dominant** change, not the first commit.
+- `type` ∈ `feat | fix | refactor | perf | docs | test | chore | build | ci`, by the PR's **dominant** change, not the first commit.
 - `scope` = the primary package, app or service.
 - **Continuation of a merged PR on the same branch:** append `(PART N)`.
 
 ## Body structure
 
-Fixed sections, in this order. Omit a section only when it has no content — never leave a placeholder.
-
-1. **Context** — one or two lines: link the plan (`{{kit.planDirectory}}/…`), the predecessor PR, or the issue. State which phase or slice this is.
-2. **Changes** — grouped **by theme**, not commit by commit. Use `###` subheadings or a table when the PR spans several areas. A reviewer must grasp the shape without reading the diff.
-3. **Verification** — the checks you actually ran, with their numbers, and the review gates with their verdicts. Only checks you ran.
-4. **Deploy checklist** — required whenever the PR touches **database migrations, secrets, message or mail templates, or a new or changed service**. Order the steps **causally**: database → secrets → templates → services (consumer before publisher) → apps. Use `- [ ]` so it doubles as a runbook. Flag any migration already applied to an environment and which ones still need it.
-5. **Out of scope / follow-ups** — what was deliberately deferred, so reviewers don't ask.
-
-## Diagrams (Mermaid)
-
-Add a fenced ` ```mermaid ` block **when it removes reader effort**:
-
-- a **new service** or a multi-hop **data flow** (who reads what, who publishes to whom),
-- a **state machine** or transition set,
-- a **security or replication mechanism** where the failure mode is the point.
-
-Keep each diagram to one idea; two small diagrams beat one dense one. Small or single-file PRs need none.
-
-Write edge labels as `-->|"label"|` (`-- text -->` breaks on a `--` in it); `jh mermaid <body file>` must exit 0 before `gh pr create` or `gh pr edit`.
+Fixed sections, in this order; omit one only when it has no content, never leave a placeholder.
 
-## Review order (large PRs)
+1. **Context** — link the plan (`{{kit.planDirectory}}/…`), the predecessor PR, or the issue; name the phase or slice.
+2. **Changes** — grouped **by theme**, not commit by commit, so a reviewer grasps the shape without the diff.
+3. **Verification** — the checks with their numbers, and the review gates with their verdicts. Only checks you ran.
+4. **Deploy checklist** — whenever the PR touches **database migrations, secrets, message or mail templates, or a new or changed service**. Order the steps **causally**: database → secrets → templates → services (consumer before publisher) → apps. Use `- [ ]`, and flag any migration already applied to an environment and which ones still need it.
+5. **Out of scope / follow-ups** — what was deliberately deferred.
 
-When a PR spans many files, add a short **suggested review order** — **pure/domain logic first, adapters next, UI and wiring last**. A `| # | Area | Start here | Why first |` table works well.
+## Diagrams and review order
 
-## Language
+Add a ` ```mermaid ` block **when it removes reader effort**: a new service or a multi-hop data flow, a state machine, a security or replication mechanism whose failure mode is the point. One idea per diagram. Write edge labels as `-->|"label"|`; `jh mermaid <body file>` must exit 0 before `gh pr create` or `gh pr edit`.
 
-PR **title and body are English**, whatever language the conversation runs in, so the history reads the same for every reader.
+A PR across many files adds a **suggested review order**: pure/domain logic first, adapters next, UI and wiring last.
 
-## Anti-patterns
+## Language and content
 
-- Pasting the raw commit log as the body — group by theme instead.
-- A deploy section out of causal order (a deploy before its migration).
-- Claiming tests or reviews that did not run.
-- Secrets, tokens or full connection strings anywhere in the body.
-- A diagram that restates the title without adding structure.
+PR **title and body are English**, whatever language the conversation runs in. Never: Secrets, tokens or full connection strings anywhere in the body.

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

@@ -12,9 +12,7 @@ All new or changed code **must** have tests.
 | 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               |
 
-### Run the tests where the runner can see the project's config
-
-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.
+A runner started from the wrong directory can fail before it runs a test (file descriptors exhausted, a config 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. The project's own testing rule names the failures its runner shows.
 
 ## What to Test (decision tree)
 
@@ -45,23 +43,19 @@ Is it a new user-facing feature?
 
 ### Test-first: money, identifiers, state
 
-The coverage target is the same either way. The **order** is what buys something: a test that has to pass before the code exists cannot be satisfied by logic buried inside a server function with a database call in it. Writing it first forces a seam — the random values or the clock arrive as an argument, so the logic is a pure function a unit test reaches directly. See `code-style.md` → Generated identifiers carry entropy, never a clock.
+The **order** buys the seam: a test that must pass before the code exists forces the random values or the clock to arrive as an argument, so the logic is a pure function a unit test reaches. See `code-style.md` → Generated identifiers carry entropy, never a clock.
 
 ## Test Priority Order
 
-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 the E2E runner (only when requested)
+Unit tests (pure functions, validators, mappers), then integration tests (service interactions, database operations), then E2E tests (only when requested); stop when coverage expectations are met.
 
 ## 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. 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.
+**Mock only the lowest-level dependency** (adapters, repositories): the use-case logic still runs. Where the runner's mock replaces a whole module for the entire file, mocking an intermediate module (a use-case in a handler test) breaks every other test there.
 
 ## Before every commit
 
-`/pre-commit` runs `bunx jackherd check`, which measures types, lint, tests, staged build artifacts and the project's own checks. Beyond that, the judgement points:
+`/pre-commit` runs `bunx jackherd check` (types, lint, tests, staged build artifacts, the project's own checks). Beyond that:
 
 1. Version bumped if the change affects a published package (minor = feature, patch = fix)
-2. `code-style.md` holds in every changed file: its code order, and its design review passed, dead code (unused exports, unreachable branches, commented-out code) included
+2. `code-style.md` holds in every changed file: its code order and its design review, dead code included

package/kit/rules/rules/kit/writing-for-agents.md

@@ -57,6 +57,9 @@ A **context pointer** names material that is out of context and encodes the cond
 - **One trigger per branch.** Synonyms renaming one branch are that branch written twice.
 - **Cut what the body already carries.** A pointer says when to come, not what is inside.
 - **Every trigger names something its loader can honour.** A skill with `disable-model-invocation: true` describes what it is for, since the user picks it; a `paths:` list names globs the repository actually has. Check both against reality — a trigger nothing can fire is a line paid for on every load and never earned back.
+- **A mandatory rule behind a pointer needs a trigger that fires without the reader's judgement.** Code raises it (an event line that names the file, a hook's denial, a command's output) or it is a step every run reaches; "read when needed" is no pointer, since a rule reached only when the reader thinks of it is a weakened rule. Test the link: the rule's sentence stands in the target, the target is linked, and the trigger names it.
+- **A rule a hook enforces is one sentence in the text: how a call gets through.** The full rule lives in the hook's denial, which the reader sees at the moment it matters; written out in both places, it is one meaning in two places that drift apart.
+- **A rule the project's linter can check is a lint rule, and the text keeps one sentence naming it as `lint:<rule id>`**, plus the why where it is not obvious. The full rule lives in the linter's message, for the same reason as above.
 
 ## The two loads